diff --git a/docusaurus.config.js b/docusaurus.config.js index d364e5a26ec..e97de849ff2 100644 --- a/docusaurus.config.js +++ b/docusaurus.config.js @@ -184,6 +184,11 @@ module.exports = { current: { label: "Latest", }, + "2.14": { + label: 'v2.14 (Preview)', + path: 'v2.14', + banner: 'unreleased' + }, "2.13": { label: "v2.13", path: "v2.13", diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/api/api-reference.mdx b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/api/api-reference.mdx new file mode 100644 index 00000000000..c7ebadc12de --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/api/api-reference.mdx @@ -0,0 +1,17 @@ +--- +title: API 参考 +--- + + + + + +:::note + +目前，并非所有的 Rancher 资源都可以通过 Rancher Kubernetes API 操作。 + +::: + +import ApiDocMdx from '@theme/ApiDocMdx'; + + diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/api/api-tokens.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/api/api-tokens.md new file mode 100644 index 00000000000..eb5aedcc002 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/api/api-tokens.md @@ -0,0 +1,93 @@ +--- +title: API 令牌 +--- + +默认情况下，某些集群级别的 API 令牌是使用无限期 TTL（`ttl=0`）生成的。换言之，除非你让令牌失效，否则 `ttl=0` 的 API 令牌永远不会过期。令牌不会因为更改密码而失效。 + +要停用 API 令牌，你可以删除令牌或停用用户账号。 + +## 删除令牌 +要删除令牌： + +1. 转到 `https:///v3/tokens`，在 Rancher API 视图中查看包含所有令牌的列表。 + +1. 通过 ID 访问要删除的令牌。例如，`https:///v3/tokens/kubectl-shell-user-vqkqt`。 + +1. 单击**删除**。 + +以下是使用 `ttl=0` 生成的完整令牌列表： + +| 令牌 | 描述 | +| ----------------- | -------------------------------------------------------------------------------------- | +| `kubeconfig-*` | Kubeconfig 令牌 | +| `kubectl-shell-*` | 在浏览器中访问 `kubectl` shell | +| `agent-*` | Agent deployment 令牌 | +| `compose-token-*` | compose 令牌 | +| `helm-token-*` | Helm Chart deployment 令牌 | +| `telemetry-*` | 遥测令牌 | +| `drain-node-*` | 用于清空的令牌（由于没有原生 Kubernetes API，我们使用 `kubectl` 来清空） | + + +## 在 Kubeconfig 令牌上设置 TTL + +管理员可以在 Kubeconfig 令牌上设置全局存活时间 (time-to-live，TTL)。如需更改默认 kubeconfig TTL，你可以导航到全局设置并将 [`kubeconfig-default-token-ttl-minutes`](#kubeconfig-default-token-ttl-minutes) 设置为所需的持续时间（单位：分钟）。[`kubeconfig-default-token-ttl-minutes`](#kubeconfig-default-token-ttl-minutes) 的默认值为 0，表示令牌永不过期。 + +:::note + +除了由 CLI 创建的用于[生成 kubeconfig 令牌](#在生成的-kubeconfig-中禁用令牌)的令牌之外，所有 kubeconfig 令牌都使用此设置。 + +::: + +## 在生成的 Kubeconfig 中禁用令牌 + +1. 将 `kubeconfig-generate-token` 设置为 `false`。此设置让 Rancher 不再在用户单击下载 kubeconfig 文件时自动生成令牌。如果停用此设置，生成的 kubeconfig 将引用 [Rancher CLI](../reference-guides/cli-with-rancher/kubectl-utility.md#使用-kubectl-和-kubeconfig-令牌进行-ttl-认证) 来检索集群的短期令牌。当这个 kubeconfig 在客户端（例如 `kubectl`）中使用时，你需要安装 Rancher CLI 来完成登录请求。 + +2. 将 `kubeconfig-token-ttl-minutes` 设置为所需的时长（单位：分钟）。`kubeconfig-token-ttl-minutes` 默认设置为 960（即 16 小时）。 + +## 令牌哈希 + +你可以启用令牌哈希，令牌将使用 SHA256 算法进行单向哈希。这是一个不可逆的操作，一旦启用，此功能将无法禁用。在启用功能或在测试环境中评估之前，建议你先进行备份。 + +要启用令牌哈希，请参阅[本节](../how-to-guides/advanced-user-guides/enable-experimental-features/enable-experimental-features.md)。 + +此功能将影响所有令牌，包括但不限于以下内容： + +- Kubeconfig 令牌 +- 持有者令牌 API 密钥/调用 +- 内部操作使用的令牌 + +## 令牌设置 + +以下全局设置会影响 Rancher 令牌的行为： + +| 设置 | 描述 | +| ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| [`auth-user-session-ttl-minutes`](#auth-user-session-ttl-minutes) | 用户认证会话令牌的 TTL（单位：分钟）。 | +| [`auth-user-session-idle-ttl-minutes`](#auth-user-session-idle-ttl-minutes) | TTL in minutes on a user auth session token, without user activity. | +| [`kubeconfig-default-token-TTL-minutes`](#kubeconfig-default-token-ttl-minutes) | 默认 TTL，应用于所有 kubeconfig 令牌（除了[由 Rancher CLI 生成的令牌](#在生成的-kubeconfig-中禁用令牌)）。**此设置从 2.6.6 版本开始引入。** | +| [`kubeconfig-token-ttl-minutes`](#kubeconfig-token-ttl-minutes) | 在 CLI 中生成的令牌 TTL。**自 2.6.6 起已弃用，并将在 2.8.0 中删除**。请知悉，`kubeconfig-default-token-TTL-minutes` 将用于所有 kubeconfig 令牌。 | +| [`auth-token-max-ttl-minutes`](#auth-token-max-ttl-minutes) | 除了由 [`auth-user-session-ttl-minutes`](#auth-user-session-ttl-minutes) 控制的令牌外，所有令牌的最大 TTL。 | +| [`kubeconfig-generate-token`](#kubeconfig-generate-token) | 如果为 true，则在用户下载 kubeconfig 时自动生成令牌。 | + +### auth-user-session-ttl-minutes +存活时间（TTL）（单位：分钟），用于确定用户身份验证会话令牌的到期时间。过期后，用户将需要登录并获取新令牌。此设置不受 [`auth-token-max-ttl-minutes`](#auth-token-max-ttl-minutes) 的影响。会话令牌是在用户登录 Rancher 时创建的。 + +### auth-user-session-idle-ttl-minutes + +Time to live (TTL) without user activity for login sessions tokens, in minutes. +By default, `auth-user-session-idle-ttl-minutes` is set to the same value as [`auth-user-session-ttl-minutes`](#auth-user-session-ttl-minutes) (for backward compatibility). It must never exceed the value of `auth-user-session-ttl-minutes`. + +### kubeconfig-default-token-TTL-minutes +存活时间（TTL）（单位：分钟），用于确定 kubeconfig 令牌的到期时间。令牌过期后，API 将拒绝令牌。此设置的值不能大于 [`auth-token-max-ttl-minutes`](#auth-token-max-ttl-minutes) 的值。此设置适用于在请求的 kubeconfig 文件中生成的令牌，不包括[由 Rancher CLI 生成的](#在生成的-kubeconfig-中禁用令牌)令牌。 +**此设置从 2.6.6 版本开始引入**。 + +### kubeconfig-token-ttl-minutes +存活时间（TTL）（单位：分钟），用于确定由 CLI 生成的 kubeconfig 令牌的到期时间。当 [`kubeconfig-generate-token`](#kubeconfig-generate-token) 设为 false 时，则由 CLI 生成令牌。令牌过期后，API 将拒绝令牌。此设置的值不能大于 [`auth-token-max-ttl-minutes`](#auth-token-max-ttl-minutes) 的值。 +**自版本 2.6.6 起已弃用，并将在 2.8.0 中删除。请知悉，此设置将被 [`kubeconfig-default-token-TTL-minutes`](#kubeconfig-default-token-ttl-minutes) 的值替换**。 + +### auth-token-max-ttl-minutes +身份验证令牌的最大生存时间 (TTL)（单位：分钟）。如果用户尝试创建一个 TTL 大于 `auth-token-max-ttl-minutes` 的令牌，Rancher 会将令牌 TTL 设置为 `auth-token-max-ttl-minutes` 的值。身份验证令牌是为验证 API 请求而创建的。 +**2.6.6 版本更改：适用于所有 kubeconfig 令牌和 API 令牌。** + +### kubeconfig-generate-token +如果设置为 true，则通过 UI 请求的 kubeconfig 将包含一个有效的令牌。如果设置为 false，kubeconfig 将包含一个使用 Rancher CLI 提示用户登录的命令。然后，[CLI 将为用户检索和缓存令牌](../reference-guides/cli-with-rancher/kubectl-utility.md#使用-kubectl-和-kubeconfig-令牌进行-ttl-认证)。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/api/quickstart.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/api/quickstart.md new file mode 100644 index 00000000000..20ca51cc34f --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/api/quickstart.md @@ -0,0 +1,152 @@ +--- +title: API 快速入门指南 +--- + + + + + +你可以通过 Kubernetes API 访问 Rancher 的资源。本指南将帮助你以 Rancher 用户的身份开始使用此 API。 + +1. 在左上角，点击 **☰ > 全局设置**. +2. 找到 `server-url` 字段并复制其地址。 +3. [创建](../reference-guides/user-settings/api-keys.md#创建-api-密钥)一个没有作用域的 Rancher API 密钥。 + + :::danger + + 没有作用域的 Rancher API 密钥授予用户可以访问的所有资源的无限制的访问权限。为防止未经授权的使用，此密钥应安全存储并经常轮换。 + + ::: + +4. 创建一个 `kubeconfig.yaml` 文件，将 `$SERVER_URL` 替换成上面从全局设置中复制的地址，并且将 `$API_KEY` 替换为上面创建的 Rancher API 密钥： + + ```yaml + apiVersion: v1 + kind: Config + clusters: + - name: "rancher" + cluster: + server: "$SERVER_URL" + + users: + - name: "rancher" + user: + token: "$API_KEY" + + contexts: + - name: "rancher" + context: + user: "rancher" + cluster: "rancher" + + current-context: "rancher" + ``` + +你可以使用任何兼容的工具来引用这个文件，例如 kubectl 或 [client-go](https://github.com/kubernetes/client-go)。快速演示内容请参阅 [kubectl 示例](#api-kubectl-示例) + +更多有关处理更复杂证书的设置信息，请参阅[指定 CA 证书](#指定-ca-证书)。 + +更多关于可用的 kubeconfig 选项，请参阅[上游文档](https://kubernetes.io/docs/tasks/access-application-cluster/configure-access-multiple-clusters/)。 + +## API kubectl 示例 + +在此示例中，我们将展示如何使用 kubectl 创建一个项目，然后删除它。关于其他可用的 Rancher 资源列表，请参阅 [API 参考](./api-reference.mdx)。 + +:::note + +目前，并非所有的 Rancher 资源都可以通过 Rancher Kubernetes API 操作。 + +::: + +1. 将 KUBECONFIG 环境变量设置为刚才创建的 kubeconfig 文件： + + ```bash + export KUBECONFIG=$(pwd)/kubeconfig.yaml + ``` + +2. 使用 `kubectl explain` 查看项目的可用字段，或者复杂资源的子字段： + + ```bash + kubectl explain projects + kubectl explain projects.spec + ``` + +不是所有的资源都有详细的输出。 + +3. 在名称为 `project.yaml` 的文件中添加以下内容： + + ```yaml + apiVersion: management.cattle.io/v3 + kind: Project + metadata: + # name 应在每个集群的所有项目中都是唯一的 + name: p-abc123 + # generateName 可以替代 `name` 来随机生成一个名称 + # generateName: p- + # namespace 应与 spec.ClusterName 匹配 + namespace: local + spec: + # clusterName 应与目标集群的 `metadata.Name` 匹配 + clusterName: local + description: Example Project + # displayName 是人类可读的名称并且从 UI 中显示 + displayName: Example + ``` + +4. 创建项目： + + ```bash + kubectl create -f project.yaml + ``` + +5. 删除项目： + + 项目删除的方式取决于项目名称的创建方式。 + + **A. 如果在创建项目时使用 `name`**： + + ```bash + kubectl delete -f project.yaml + ``` + + **B. 如果你使用 `generateName`**： + + 将 `$PROJECT_NAME` 替换为 kubectl 创建项目后随机生成的项目名称。 + + ```bash + kubectl delete project $PROJECT_NAME -n local + ``` + +## 指定 CA 证书 + +为确保你的工具能够识别 Rancher 的 CA 证书，大多数设置都需要对上述模板进行额外修改。 + +1. 在左上角点击 **☰ > 全局设置**. +2. 查找并复制 `ca-certs` 字段中的值。 +3. 将复制的值保存在名称为 `rancher.crt` 的文件中。 + + :::note + 如果你的 Rancher 实例由其他服务代理，你必须提取该服务正在使用的证书，并将其添加到 kubeconfig 文件中，如步骤 5 所示。 + ::: + +4. 以下命令会将 `rancher.crt` 转换为 base64 输出，除去所有换行符，并使用证书内容更新 kubeconfig 中的 cluster 选项，然后删除 `rancher.crt` 文件： + + ```bash + export KUBECONFIG=$PATH_TO_RANCHER_KUBECONFIG + kubectl config set clusters.rancher.certificate-authority-data $(cat rancher.crt | base64 -i - | tr -d '\n') + rm rancher.crt + ``` +5. （可选项）如果你使用不受系统信任的自签名证书，则可以通过 kubectl 在 kubeconfig 中设置不安全选项： + + :::danger + + 此选项不应该在生产环境中使用，因为它存在安全风险。 + + ::: + + ```bash + export KUBECONFIG=$PATH_TO_RANCHER_KUBECONFIG + kubectl config set clusters.rancher.insecure-skip-tls-verify true + ``` + + 如果你的 Rancher 实例由其他服务代理，你必须提取该服务正在使用的证书，并如上面演示的方法，将其添加到 kubeconfig 文件中。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/api/v3-rancher-api-guide.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/api/v3-rancher-api-guide.md new file mode 100644 index 00000000000..a09d21eb6d7 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/api/v3-rancher-api-guide.md @@ -0,0 +1,93 @@ +--- +title: API +--- + + + + + +## 如何使用 API + +API 有自己的用户界面，你可以从 Web 浏览器访问它。这是查看资源、执行操作以及查看等效 cURL 或 HTTP 请求和响应的一种简单的方法。要访问它： + + + + +1. 单击右上角的用户头像。 +1. 单击**账号 & API 密钥**。 +1. 在 **API 密钥**下，找到 **API 端点**字段并单击链接。该链接类似于 `https:///v3`，其中 `` 是 Rancher deployment 的完全限定域名。 + + + + +转到位于 `https:///v3` 的 URL 端点，其中 `` 是你的 Rancher deployment 的完全限定域名。 + + + + +## 认证 + +API 请求必须包含认证信息。认证是通过 [API 密钥](../reference-guides/user-settings/api-keys.md)使用 HTTP 基本认证完成的。API 密钥可以创建新集群并通过 `/v3/clusters/` 访问多个集群。[集群和项目角色](../how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/cluster-and-project-roles.md)会应用于这些键，并限制账号可以查看的集群和项目以及可以执行的操作。 + +默认情况下，某些集群级别的 API 令牌是使用无限期 TTL（`ttl=0`）生成的。换言之，除非你让令牌失效，否则 `ttl=0` 的 API 令牌永远不会过期。有关如何使 API 令牌失效的详细信息，请参阅 [API 令牌](api-tokens.md)。 + +## 发出请求 + +该 API 通常是 RESTful 的，但是还具有多种功能。这些功能可以使客户端发现所有内容，因此可以编写通用客户端，而不必为每种资源编写特定代码。有关通用 API 规范的详细信息，请参阅[此处](https://github.com/rancher/api-spec/blob/master/specification.md)。 + +- 每种类型都有一个 Schema，这个 Schema 描述了以下内容： + - 用于获取此类资源集合的 URL + - 资源可以具有的每个字段及其类型、基本验证规则、是必填还是可选字段等 + - 在此类资源上可以执行的每个操作，以及它们的输入和输出（也作为 schema） + - 允许过滤的每个字段 + - 集合本身或集合中的单个资源可以使用的 HTTP 操作方法 + + +- 因此，你可以只加载 schema 列表并了解 API 的所有信息。实际上，这是 API 的 UI 工作方式，它不包含特定于 Rancher 本身的代码。每个 HTTP 响应中的 `X-Api-Schemas` 标头都会发送获取 Schemas 的 URL。你可以按照每个 schema 上的 `collection` 链接了解要在哪里列出资源，并在返回资源中的其他 `links` 中获取其他信息。 + +- 在实践中，你可能只想构造 URL 字符串。我们强烈建议将此限制为在顶层列出的集合 (`/v3/`)，或获取特定资源 (`/v3//`)。除此之外的任何内容都可能在将来的版本中发生更改。 + +- 资源之间相互之间有联系，称为链接（links）。每个资源都包含一个 `links` 映射，其中包含链接名称和用于检索该信息的 URL。同样，你应该 `GET` 资源并遵循 `links` 映射中的 URL，而不是自己构造这些字符串。 + +- 大多数资源都有操作（action），表示可以执行某个操作或改变资源的状态。要使用操作，请将 HTTP `POST` 请求发送到 `actions` 映射中你想要的操作的 URL。某些操作需要输入或生成输出，请参阅每种类型的独立文档或 schema 以获取具体信息。 + +- 要编辑资源，请将 HTTP `PUT` 请求发送到资源上的 `links.update` 链接，其中包含要更改的字段。如果链接丢失，则你无权更新资源。未知字段和不可编辑的字段将被忽略。 + +- 要删除资源，请将 HTTP `DELETE` 请求发送到资源上的 `links.remove` 链接。如果链接丢失，则你无权更新资源。 + +- 要创建新资源，HTTP `POST` 到 schema（即 `/v3/`）中的集合 URL。 + +## 过滤 + +你可以使用 HTTP 查询参数的公共字段在服务器端过滤大多数集合。`filters` 映射显示了可以过滤的字段，以及过滤后的值在你发起的请求中是什么。API UI 具有设置过滤和显示适当请求的控件。对于简单的 "equals" 匹配，它只是 `field=value`。你可以将修饰符添加到字段名称，例如 `field_gt=42` 表示“字段大于 42”。详情请参阅 [API 规范](https://github.com/rancher/api-spec/blob/master/specification.md#filtering)。 + +## 排序 + +你可以使用 HTTP 查询参数的公共字段在服务器端排序大多数集合。`sortLinks` 映射显示了可用的排序，以及用于获取遵循该排序的集合的 URL。它还包括当前响排序依据的信息（如果指定）。 + +## 分页 + +默认情况下，API 响应以每页 100 个资源的限制进行分页。你可以通过 `limit` 查询参数进行更改，最大为 1000，例如 `/v3/pods?limit=1000`。集合响应中的 `pagination` 映射能让你知道你是否拥有完整的结果集，如果没有，则会指向下一页的链接。 + +## 捕获 Rancher API 调用 + +You can use browser developer tools to capture how the v3 API is called. For example, you could follow these steps to use the Chrome developer tools to get the API call for provisioning a Rancher Kubernetes distribution cluster: + +1. 在 Rancher UI 中，转到**集群管理**并单击**创建**。 +1. 单击某个集群类型。此示例使用 Digital Ocean。 +1. 使用集群名称和节点模板填写表单，但不要单击**创建**。 +1. 在创建集群之前，你需要打开开发人员工具才能看到正在记录的 API 调用。要打开工具，右键单击 Rancher UI，然后单击**检查**。 +1. 在开发者工具中，单击 **Network** 选项卡。 +1. 在 **Network** 选项卡上，确保选择了 **Fetch/XHR**。 +1. 在 Rancher UI 中，单击**创建**。在开发者工具中，你应该会看到一个名为 `cluster?_replace=true` 的新网络请求。 +1. 右键单击 `cluster?_replace=true` 并单击**复制 > 复制为 cURL**。 +1. 将结果粘贴到文本编辑器中。你将能够看到 POST 请求，包括被发送到的 URL、所有标头以及请求的完整正文。此命令可用于从命令行创建集群。请注意，请求包含凭证，因此请将请求存储在安全的地方。 + +### 启用在 API 中查看 + +你还可以查看针对各自集群和资源捕获的 Rancher API 调用。 默认情况下不启用此功能。 要启用它： + +1. 单击 UI 右上角的 **用户图标**，然后从下拉菜单中选择 **偏好设置** +1. 在**高级功能**部分下，单击**启用"在 API 中查看"** + +选中后，**在 API 中查看**链接现在将显示在 UI 资源页面上的 **⋮** 子菜单下。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/api/workflows/projects.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/api/workflows/projects.md new file mode 100644 index 00000000000..187e8042cfd --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/api/workflows/projects.md @@ -0,0 +1,134 @@ +--- +title: 项目 +--- + + + + + +## 创建项目 + +项目资源只能在管理集群上创建，请参考下文了解如何[在管理集群中的项目下创建命名空间](#在项目中创建命名空间) + +### 创建一个基本项目 + +```bash +kubectl create -f - <:` + +## 删除项目 + +在集群命名空间中查找要删除的项目： + +```bash +kubectl --namespace c-m-abcde get projects +``` + +删除集群命名空间下的项目： + +```bash +kubectl --namespace c-m-abcde delete project p-vwxyz +``` + +请注意此命令不会删除以前属于该项目的命名空间和资源。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/contribute-to-rancher.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/contribute-to-rancher.md new file mode 100644 index 00000000000..ea433c1f2be --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/contribute-to-rancher.md @@ -0,0 +1,114 @@ +--- +title: 参与 Rancher 社区贡献 +--- + +本文介绍了 Rancher 仓库和 Rancher 文档、如何构建 Rancher 仓库以及提交 issue 时要包含哪些信息。 + +有关如何为 Rancher 项目开发做出贡献的更多详细信息，请参阅 [Rancher Developer Wiki](https://github.com/rancher/rancher/wiki)。Wiki 包含以下主题的资源： + +- 如何搭建 Rancher 开发环境并运行测试 +- Issue 在开发生命周期中的典型流程 +- 编码指南和开发最佳实践 +- 调试和故障排除 +- 开发 Rancher API + +在 Rancher Users Slack 上，开发者的频道是 **#developer**。 + +## Rancher 文档 + +如果你对此网站上的文档有建议，请在主 [Rancher 文档](https://github.com/rancher/rancher-docs)仓库中[提交 issue](https://github.com/rancher/rancher-docs/issues/new/choose)。此仓库包含 Rancher v2.0 及更高版本的文档。 + +有关贡献和构建 Rancher v2.x 文档仓库的更多详细信息，请参阅 [Rancher 文档 README](https://github.com/rancher/rancher-docs#readme)。 + +有关 Rancher v1.6 及更早版本的文档，请参阅 [Rancher 1.x docs](https://github.com/rancher/rancher.github.io) 仓库，其中包含 https://rancher.com/docs/rancher/v1.6/en/ 的源文件。 + +## Rancher 仓库 + +所有仓库都位于我们的主要 GitHub 组织内。Rancher 使用了很多仓库，以下是部分主要仓库的描述： + +| 仓库 | URL | 描述 | +-----------|-----|------------- +| Rancher | https://github.com/rancher/rancher | Rancher 2.x 的主要源码仓库。 | +| Types | https://github.com/rancher/types | 包含 Rancher 2.x 的所有 API 类型的仓库。 | +| API Framework | https://github.com/rancher/norman | API 框架，用于构建由 Kubernetes 自定义资源支持的 Rancher 风格的 API。 | +| User Interface | https://github.com/rancher/dashboard/ | Dashboard UI 源码仓库。 | +| (Rancher) Docker Machine | https://github.com/rancher/machine | 使用主机驱动时使用的 Docker Machine 二进制文件的源码仓库。这是 `docker/machine` 仓库的一个 fork。 | +| machine-package | https://github.com/rancher/machine-package | 用于构建 Rancher Docker Machine 二进制文件。 | +| kontainer-engine | https://github.com/rancher/kontainer-engine | kontainer-engine 的源码仓库，它是配置托管 Kubernetes 集群的工具。 | +| CLI | https://github.com/rancher/cli | Rancher 2.x 中使用的 Rancher CLI 的源码仓库。 | +| (Rancher) Helm repository | https://github.com/rancher/helm | 打包的 Helm 二进制文件的源码仓库。这是 `helm/helm` 仓库的一个 fork。 | +| Telemetry repository | https://github.com/rancher/telemetry | Telemetry 二进制文件的源码仓库。 | +| loglevel repository | https://github.com/rancher/loglevel | loglevel 二进制文件的源码仓库，用于动态更改日志级别。 | + +要查看 Rancher 使用的所有库/项目，请查看 `rancher/rancher` 仓库中的 [`go.mod` 文件](https://github.com/rancher/rancher/blob/master/go.mod)。 + +![Rancher diagram](/img/ranchercomponentsdiagram-2.6.svg)
+用于配置/管理 Kubernetes 集群的 Rancher 组件。 + +### 构建 Rancher 仓库 + +每个仓库都应该有一个 Makefile，并且可以使用 `make` 命令进行构建。`make` 目标基于仓库中 `/scripts` 目录中的脚本，每个目标都使用 [Dapper](https://github.com/rancher/dapper) 在孤立的环境中运行。`Dockerfile.dapper` 将用于此操作，它包含了所需的所有构建工具。 + +默认目标是 `ci`，它将运行 `./scripts/validate`、`./scripts/build`、`./scripts/test ` 和 `./scripts/package`。生成的二进制文件将在 `./build/bin` 中，通常也打包在 Docker 镜像中。 + +### Rancher Bug、Issue 或疑问 + +如果你发现任何 bug 或问题，由于有人可能遇到过同样的问题，或者我们已经正在寻找解决方案，因此请先在[已报告 issue](https://github.com/rancher/rancher/issues) 中搜索。 + +如果找不到与你的问题相关的内容，请通过[提出 issue](https://github.com/rancher/rancher/issues/new) 与我们联系。与 Rancher 相关的仓库有很多，但请将 issue 提交到 Rancher 仓库中，这样能确保我们能看到这些 issue。如果你想就一个用例提出问题或询问其他用户，你可以在 [Rancher 论坛](https://forums.rancher.com)上发帖。 + +#### 提交 Issue 的检查清单 + +提交问题时请遵循此清单，以便我们调查和解决问题。如果你能提供更多信息，我们就可以使用更多数据来确定导致问题的原因或发现更多相关的内容。 + +:::note + +如果数据量很大，请使用 [GitHub Gist](https://gist.github.com/) 或类似工具，并在 issue 中链接你创建的资源。 + +::: + +:::note 重要提示： + +请删除所有敏感数据。 + +::: + +- **资源**：请尽量详细地提供所使用的资源。导致问题的原因可能很多，因此请尽量提供更多细节来帮助我们确定根本原因。下面是一些参考示例： + - **主机**：主机的规格（例如 CPU/内存/磁盘），运行在什么云厂商上，使用的 Amazon Machine Image，使用的 DigitalOcean droplet，配置的镜像（复现时用于重新构建或使用）。 + - **操作系统**：使用的是什么操作系统。在此处提供详细信息，例如 `cat /etc/os-release` 的输出（确切的操作系统版本）和 `uname -r` 的输出（确切的内核）。 + - **Docker**：使用的 Docker 版本以及安装的方法。Docker 的大部分详情都可以在 `docker version` 和 `docker info` 的输出中找到。 + - **环境**：是否使用了代理，是否使用可信的 CA/自签名证书，是否使用了外部负载均衡器。 + - **Rancher**：使用的 Rancher 版本，可以在 UI 左下角或者从主机运行的 image 标签中获取。 + - **集群**：创建了什么样的集群，如何创建的，在创建时指定了什么参数。 +- **复现 issue 的步骤**：尽量详细地说明你是如何触发所报告的情况的。这有助于复现你的情况。 + - 提供从创建到你报告的情况使用的手动步骤或自动化脚本。 +- **日志**：提供使用资源的数据/日志。 + - Rancher + - Docker 安装 + + ``` + docker logs \ + --timestamps \ + $(docker ps | grep -E "rancher/rancher:|rancher/rancher " | awk '{ print $1 }') + ``` + - 使用 `kubectl` 的 Kubernetes 安装 + + :::note + + 确保你配置了正确的 kubeconfig（例如，如果 Rancher 安装在 Kubernetes 集群上，则 `export KUBECONFIG=$PWD/kube_config_cluster.yml`）或通过 UI 使用了嵌入式 kubectl。 + + ::: + + ``` + kubectl -n cattle-system \ + logs \ + -l app=rancher \ + --timestamps=true + ``` + - 系统日志记录（可能不存在，取决于操作系统） + - `/var/log/messages` + - `/var/log/syslog` + - `/var/log/kern.log` + - Docker Daemon 日志记录（可能并不全部存在，取决于操作系统） + - `/var/log/docker.log` +- **指标**：如果你遇到性能问题，请提供尽可能多的指标数据（文件或屏幕截图）来帮助我们确定问题。如果你遇到主机相关的问题，你可以提供 `top`、`free -m`、`df` 的输出，这些输出会显示进程/内存/磁盘的使用情况。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/faq/container-network-interface-providers.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/faq/container-network-interface-providers.md new file mode 100644 index 00000000000..088e49b7363 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/faq/container-network-interface-providers.md @@ -0,0 +1,169 @@ +--- +title: CNI 网络插件 +description: 了解容器网络接口 (CNI)、Rancher 提供的 CNI 网络插件、提供商的功能，以及如何选择网络提供商 +--- + +## 什么是 CNI？ + +CNI（容器网络接口）是一个[云原生计算基金会项目](https://cncf.io/)，它包含了一些规范和库，用于编写在 Linux 容器中配置网络接口的一系列插件。CNI 只关注容器的网络连接，并在容器被删除时移除所分配的资源。 + +Kubernetes 使用 CNI 作为网络提供商和 Kubernetes Pod 网络之间的接口。 + +![CNI Logo](/img/cni-logo.png) + +有关更多信息，请访问 [CNI GitHub 项目](https://github.com/containernetworking/cni)。 + +## CNI 使用了哪些网络模型？ + +CNI 网络插件使用封装网络模型（例如 Virtual Extensible Lan，缩写是 [VXLAN](https://github.com/flannel-io/flannel/blob/master/Documentation/backends.md#vxlan)）或非封装网络模型（例如 Border Gateway Protocol，缩写是 [BGP](https://en.wikipedia.org/wiki/Border_Gateway_Protocol)）来实现网络结构。 + +### 什么是封装网络？ + +此网络模型提供了一个逻辑二层（L2）网络，该网络封装在跨 Kubernetes 集群节点的现有三层（L3）网络拓扑上。使用此模型，你可以为容器提供一个隔离的 L2 网络，而无需分发路由。封装网络带来了少量的处理开销以及由于覆盖封装生成 IP header 造成的 IP 包大小增加。封装信息由 Kubernetes worker 之间的 UDP 端口分发，交换如何访问 MAC 地址的网络控制平面信息。此类网络模型中常用的封装是 VXLAN、Internet 协议安全性 (IPSec) 和 IP-in-IP。 + +简单来说，这种网络模型在 Kubernetes worker 之间生成了一种扩展网桥，其中连接了 pod。 + +如果你偏向使用扩展 L2 网桥，则可以选择此网络模型。此网络模型对 Kubernetes worker 的 L3 网络延迟很敏感。如果数据中心位于不同的地理位置，请确保它们之间的延迟较低，以避免最终的网络分段。 + +使用这种网络模型的 CNI 网络插件包括 Flannel、Canal、Weave 和 Cilium。默认情况下，Calico 不会使用此模型，但你可以对其进行配置。 + +![封装网络](/img/encapsulated-network.png) + +### 什么是非封装网络？ + +该网络模型提供了一个 L3 网络，用于在容器之间路由数据包。此模型不会生成隔离的 L2 网络，也不会产生开销。这些好处的代价是，Kubernetes worker 必须管理所需的所有路由分发。该网络模型不使用 IP header 进行封装，而是使用 Kubernetes Worker 之间的网络协议来分发路由信息以实现 Pod 连接，例如 [BGP](https://en.wikipedia.org/wiki/Border_Gateway_Protocol)。 + +简而言之，这种网络模型在 Kubernetes worker 之间生成了一种扩展网络路由器，提供了如何连接 Pod 的信息。 + +如果你偏向使用 L3 网络，则可以选择此网络模型。此模型在操作系统级别为 Kubernetes Worker 动态更新路由。对延迟较不敏感。 + +使用这种网络模型的 CNI 网络插件包括 Calico 和 Cilium。Cilium 可以使用此模型进行配置，即使这不是默认模式。 + +![非封装网络](/img/unencapsulated-network.png) + +## Rancher 提供哪些 CNI 插件？ + +### RKE2 Kubernetes 集群 + +Rancher 开箱即用地为 RKE2 Kubernetes 集群提供了几个 CNI 网络插件，分别是 Canal、Calico 和 Cilium。 + +如果你使用 Rancher 创建新的 Kubernetes 集群，你可以选择你的 CNI 网络插件。 + +#### Calico + +![Calico Logo](/img/calico-logo.png) + +Calico 在云上的 Kubernetes 集群中启用网络和网络策略。默认情况下，Calico 使用纯净、未封装的 IP 网络结构和策略引擎为 Kubernetes 工作负载提供网络。工作负载能够使用 BGP 在云上和本地进行通信。 + +Calico 还提供了一种无状态的 IP-in-IP 或 VXLAN 封装模式。如果需要，你可以使用它。Calico 还支持策略隔离，让你使用高级 ingress 和 egress 策略保护和管理 Kubernetes 工作负载。 + +如果使用 BGP，Kubernetes Worker 需要打开 TCP 端口 `179`，如果使用 VXLAN 封装，则需要打开 UDP 端口 `4789`。另外，使用 Typha 时需要 TCP 端口 `5473`。有关详细信息，请参阅[下游集群的端口要求](../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/node-requirements-for-rancher-managed-clusters.md#网络要求)。 + +:::note 重要提示： + +在 Rancher 2.6.3 中，Calico 探测到在安装 RKE2 时 Windows 节点会失败。请注意，此问题已在 v2.6.4 中解决。 + +- 要解决此问题，请先导航到 `https:///v3/settings/windows-rke2-install-script`。 + +- 在那里，将当前设置 `https://raw.githubusercontent.com/rancher/wins/v0.1.3/install.ps1` 更改为新设置 `https://raw.githubusercontent .com/rancher/rke2/master/windows/rke2-install.ps1`。 + +::: + +![Calico Diagram](/img/calico-diagram.svg) + +有关详细信息，请参阅以下页面： + +- [Project Calico 官方网站](https://www.projectcalico.org/) +- [Calico 项目 GitHub 页面](https://github.com/projectcalico/calico) + +#### Canal + +![Canal Logo](/img/canal-logo.png) + +Canal 是一个 CNI 网络插件，它很好地结合了 Flannel 和 Calico 的优点。它让你轻松地将 Calico 和 Flannel 网络部署为统一的网络解决方案，将 Calico 的网络策略执行与 Calico（未封装）和 Flannel（封装）丰富的网络连接选项结合起来。 + +Canal 是 Rancher 默认的 CNI 网络插件，并采用了 Flannel 和 VXLAN 封装。 + +Kubernetes Worker 需要打开 UDP 端口 `8472` (VXLAN) 和 TCP 端口 `9099`（健康检查）。如果使用 Wireguard，则需要打开 UDP 端口 `51820` 和 `51821`。有关详细信息，请参阅[下游集群的端口要求](../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/node-requirements-for-rancher-managed-clusters.md)。 + +![](/img/canal-diagram.png) + +For more information, refer to the [Rancher maintained Canal source](https://github.com/rancher/rke2-charts/tree/main-source/packages/rke2-canal) and the [Canal GitHub Page](https://github.com/projectcalico/canal). + +#### Cilium + +![Cilium Logo](/img/cilium-logo.png) + +Cilium 在 Kubernetes 中启用网络和网络策略（L3、L4 和 L7）。默认情况下，Cilium 使用 eBPF 技术在节点内部路由数据包，并使用 VXLAN 将数据包发送到其他节点。你也可以配置非封装的技术。 + +Cilium 推荐大于 5.2 的内核版本，从而充分利用 eBPF 的能力。Kubernetes worker 需要打开 TCP 端口 `8472`（VXLAN）和 TCP 端口 `4240`（健康检查）。此外，还必须为健康检查启用 ICMP 8/0。有关详细信息，请查看 [Cilium 系统要求](https://docs.cilium.io/en/latest/operations/system_requirements/#firewall-requirements)。 + +##### Cilium 中跨节点的 Ingress 路由 +
+默认情况下，Cilium 不允许 Pod 与其他节点上的 Pod 通信。要解决此问题，请启用 Ingress Controller 以使用 “CiliumNetworkPolicy” 进行跨节点路由请求。 + +选择 Cilium CNI 并为新集群启用项目网络隔离后，配置如下： + +``` +apiVersion: cilium.io/v2 +kind: CiliumNetworkPolicy +metadata: + name: hn-nodes + namespace: default +spec: + endpointSelector: {} + ingress: + - fromEntities: + - remote-node +``` + +## 各个网络插件的 CNI 功能 + +下表总结了 Rancher 中每个 CNI 网络插件支持的不同功能： + +| 提供商 | 网络模型 | 路线分发 | 网络策略 | 网格 | 外部数据存储 | 加密 | Ingress/Egress 策略 | +| ---- | ---- | ---- | ---- | ---- | ---- | ---- | ---- | +| Canal | 封装 (VXLAN) | 否 | 是 | 否 | K8s API | 是 | 是 | +| Flannel | 封装 (VXLAN) | 否 | 否 | 否 | K8s API | 是 | 否 | +| Calico | 封装（VXLAN，IPIP）或未封装 | 是 | 是 | 是 | Etcd 和 K8s API | 是 | 是 | +| Weave | 封装 | 是 | 是 | 是 | 否 | 是 | 是 | +| Cilium | 封装 (VXLAN) | 是 | 是 | 是 | Etcd 和 K8s API | 是 | 是 | + +- 网络模型：封装或未封装。如需更多信息，请参阅 [CNI 中使用的网络模型](#cni-使用了哪些网络模型)。 + +- 路由分发：一种外部网关协议，用于在互联网上交换路由和可达性信息。BGP 可以帮助进行跨集群 pod 之间的网络。此功能对于未封装的 CNI 网络插件是必须的，并且通常由 BGP 完成。如果你想构建跨网段拆分的集群，路由分发是一个很好的功能。 + +- 网络策略：Kubernetes 提供了强制执行规则的功能，这些规则决定了哪些 service 可以使用网络策略进行相互通信。这是从 Kubernetes 1.7 起稳定的功能，可以与某些网络插件一起使用。 + +- 网格：允许在不同的 Kubernetes 集群间进行 service 之间的网络通信。 + +- 外部数据存储：具有此功能的 CNI 网络插件需要一个外部数据存储来存储数据。 + +- 加密：允许加密和安全的网络控制和数据平面。 + +- Ingress/Egress 策略：允许你管理 Kubernetes 和非 Kubernetes 通信的路由控制。 + + +## CNI 社区人气 + +下表总结了不同的 GitHub 指标，让你了解每个项目的受欢迎程度和活动。数据收集于 2022 年 1 月。 + +| 提供商 | 项目 | Stars | Forks | Contributors | +| ---- | ---- | ---- | ---- | ---- | +| Canal | https://github.com/projectcalico/canal | 679 | 100 | 21 | +| Flannel | https://github.com/flannel-io/flannel | 7k | 2.5k | 185 | +| Calico | https://github.com/projectcalico/calico | 3.1k | 741 | 224 | +| Weave | https://github.com/weaveworks/weave/ | 6.2k | 635 | 84 | +| Cilium | https://github.com/cilium/cilium | 10.6k | 1.3k | 352 | + +
+ +## 使用哪个 CNI 插件？ + +这取决于你的项目需求。各个提供商都有不同的功能和选项。没有一个提供商可以满足所有用户的需求。 + +Canal 是默认的 CNI 网络插件。对于大多数用例，我们推荐你使用它。它使用 Flannel 为容器提供封装网络，同时添加 Calico 网络策略，可以在网络方面提供项目/命名空间隔离。 + +## 如何配置 CNI 网络插件？ + +如需了解如何为你的集群配置网络插件，请参阅[集群选项](../reference-guides/cluster-configuration/rancher-server-configuration/rke1-cluster-configuration.md)。有关更高级的配置选项，请参阅有关使用[配置文件](../reference-guides/cluster-configuration/rancher-server-configuration/rke1-cluster-configuration.md#rke-集群配置文件参考)和[网络插件](https://rancher.com/docs/rke/latest/en/config-options/add-ons/network-plugins/)选项来配置集群的说明。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/faq/deprecated-features.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/faq/deprecated-features.md new file mode 100644 index 00000000000..dde3efc7051 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/faq/deprecated-features.md @@ -0,0 +1,22 @@ +--- +title: Rancher 中已弃用的功能 +--- + + + + + +## 在哪里可以了解 Rancher 中已弃用哪些功能？ + +Rancher 将在 GitHub 上发布的 Rancher 的[发版说明](https://github.com/rancher/rancher/releases)中发布已弃用的功能。有关已弃用的功能，请参阅以下的补丁版本： + +| Patch 版本 | 发布时间 | +| ----------------------------------------------------------------- | ------------------ | +| [2.13.3](https://github.com/rancher/rancher/releases/tag/v2.13.3) | 2026 年 02 月 25 日 | +| [2.13.2](https://github.com/rancher/rancher/releases/tag/v2.13.2) | 2026 年 01 月 29 日 | +| [2.13.1](https://github.com/rancher/rancher/releases/tag/v2.13.1) | 2025 年 12 月 18 日 | +| [2.13.0](https://github.com/rancher/rancher/releases/tag/v2.13.0) | 2025 年 11 月 25 日 | + +## 当一个功能被标记为弃用我可以得到什么样的预期？ + +当功能被标记为“已弃用”时，它依然可用并得到支持，允许按照常规的流程进行升级。一旦升级完成，用户/管理员应开始计划在升级到标记为已移除的版本之前放弃使用已弃用的功能。对于新的部署，建议不要使用已弃用的功能。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/faq/general-faq.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/faq/general-faq.md new file mode 100644 index 00000000000..cb1fc3858b9 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/faq/general-faq.md @@ -0,0 +1,51 @@ +--- +title: 一般常见问题解答 +--- + + + + + +本文包含了用户常见的 Rancher 2.x 问题。 + +有关常见技术问题，请参阅[常见技术问题解答](technical-items.md)。 + +## Rancher 2.x 支持 Docker Swarm 和 Mesos 作为环境类型吗？ + +如果你在 Rancher 2.x 中创建环境，Swarm 和 Mesos 将不再是可选的标准选项。但是，Swarm 和 Mesos 还能继续作为可以部署的商店应用程序。这是一个艰难的决定，但这是大势所趋。比如说，15,000 多个集群可能只有大约 200 个在运行 Swarm。 + +## 是否可以使用 Rancher 2.x 管理 Azure Kubernetes 服务？ + +是的。请参阅我们的[集群管理](../how-to-guides/new-user-guides/manage-clusters/manage-clusters.md)指南，了解 AKS 上可用的 Rancher 功能，以及相关的 [AKS 的文档](../getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/rancher-on-aks.md) + +## Rancher 是否支持 Windows？ + +Rancher 支持 Windows Server 1809 容器。有关如何使用 Windows Worker 节点设置集群的详细信息，请参阅[为 Windows 配置自定义集群](../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/use-windows-clusters/use-windows-clusters.md)。 + +## Rancher 是否支持 Istio？ + +Rancher 支持 [Istio](../integrations-in-rancher/istio/istio.md)。 + +## Rancher 2.x 是否支持使用 Hashicorp 的 Vault 来存储密文？ + +密文管理已在我们的 roadmap 上，但我们尚未将该功能分配给特定版本。 + +## Rancher 2.x 是否也支持 RKT 容器？ + +目前，我们只支持 Docker。 + +## Rancher 2.x 是否支持将 Calico、Contiv、Contrail、Flannel、Weave net 等网络插件用于嵌入和已注册的 Kubernetes？ + +Rancher 开箱即用地为 Kubernetes 集群提供了几个 CNI 网络插件，分别是 Canal、Flannel、Calico 和 Weave。有关官方支持的详细信息，请参阅 [Rancher 支持矩阵](https://rancher.com/support-maintenance-terms/)。 + +## Rancher 是否计划支持 Traefik？ + +目前，我们不打算提供嵌入式 Traefik 支持，但我们仍在探索负载均衡方案。 + +## 我可以将 OpenShift Kubernetes 集群导入 2.x 吗？ + +我们的目标是运行任何上游 Kubernetes 集群。因此，Rancher 2.x 应该可以与 OpenShift 一起使用，但我们尚未对此进行测试。 + +## Rancher 会集成 Longhorn 吗？ + +是的。Longhorn 已集成到 Rancher 2.5+ 中。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/faq/install-and-configure-kubectl.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/faq/install-and-configure-kubectl.md new file mode 100644 index 00000000000..656fcba1ce7 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/faq/install-and-configure-kubectl.md @@ -0,0 +1,23 @@ +--- +title: 安装和配置 kubectl +--- + +`kubectl` 是一个 CLI 工具，用于运行 Kubernetes 集群相关的命令。Rancher 2.x 中的许多维护和管理任务都需要它。 + +## 安装 + +请参阅 [kubectl 安装](https://kubernetes.io/docs/tasks/tools/install-kubectl/)将 kubectl 安装到你的操作系统上。 + +## 配置 + +When you create a Kubernetes cluster with RKE2/K3s, the Kubeconfig file is stored at `/etc/rancher/rke2/rke2.yaml` or `/etc/rancher/k3s/k3s.yaml` depending on your chosen distribution. These files are used to configure access to the Kubernetes cluster. + +使用 `kubectl` 测试你的连接性，并查看你是否可以获取节点列表： + +```shell +kubectl get nodes + NAME STATUS ROLES AGE VERSION +165.227.114.63 Ready controlplane,etcd,worker 11m v1.10.1 +165.227.116.167 Ready controlplane,etcd,worker 11m v1.10.1 +165.227.127.226 Ready controlplane,etcd,worker 11m v1.10.1 +``` diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/faq/rancher-is-no-longer-needed.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/faq/rancher-is-no-longer-needed.md new file mode 100644 index 00000000000..48d4c445ffe --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/faq/rancher-is-no-longer-needed.md @@ -0,0 +1,60 @@ +--- +title: 卸载 Rancher +--- + +本文介绍了如果你不再需要 Rancher、不想再由 Rancher 管理集群、或想删除 Rancher Server 需要怎么做。 + +## 如果 Rancher Server 被删除，下游集群中的工作负载会怎样？ + +如果 Rancher 删除了或无法恢复，Rancher 管理的下游 Kubernetes 集群中的所有工作负载将继续正常运行。 + +## 如果删除了 Rancher Server，该如何访问下游集群？ + +如果删除了 Rancher，访问下游集群的方式取决于集群的类型和集群的创建方式。总而言之： + +- **Registered/Imported clusters:** The cluster will be unaffected and you can access the cluster using the same methods that you did before the cluster was registered into Rancher. +- **托管的 Kubernetes 集群**：如果你在 Kubernetes 云提供商（例如 EKS、GKE 或 AKS）中创建集群，你可以继续使用提供商的云凭证来管理集群。 +- **Rancher provisioned clusters:** To access an [RKE2/K3s cluster](../how-to-guides/new-user-guides/launch-kubernetes-with-rancher/launch-kubernetes-with-rancher.md) the cluster must have the [authorized cluster endpoint](../reference-guides/rancher-manager-architecture/communicating-with-downstream-user-clusters.md#4-authorized-cluster-endpoint) enabled, and you must have already downloaded the cluster's kubeconfig file from the Rancher UI. With this endpoint, you can access your cluster with kubectl directly instead of communicating through the Rancher server's [authentication proxy.](../reference-guides/rancher-manager-architecture/communicating-with-downstream-user-clusters.md#1-the-authentication-proxy) For instructions on how to configure kubectl to use the authorized cluster endpoint, refer to the section about directly accessing clusters with [kubectl and the kubeconfig file.](../how-to-guides/new-user-guides/manage-clusters/access-clusters/use-kubectl-and-kubeconfig.md#authenticating-directly-with-a-downstream-cluster) These clusters will use a snapshot of the authentication as it was configured when Rancher was removed. + +## 如果我不想再使用 Rancher 了该怎么做？ + +:::note + +之前推荐的 [System Tools](../reference-guides/system-tools.md) 自 2022 年 6 月起已弃用。 + +::: + +如果你[在 Kubernetes 集群上安装了 Rancher](../getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/install-upgrade-on-a-kubernetes-cluster.md)，你可以使用 [Rancher Cleanup](https://github.com/rancher/rancher-cleanup) 工具删除 Rancher。 + +在高可用 (HA) 模式下卸载 Rancher 还将删除所有 `helm-operation-*` Pod 和以下应用程序： + +- fleet +- fleet-agent +- rancher-operator +- rancher-webhook + +自定义资源 (CRD) 和自定义命名空间仍需要手动删除。 + +如果你在 Docker 中安装 Rancher，则可以通过删除运行 Rancher 的单个 Docker 容器来卸载 Rancher。 + +移除 Rancher 不会影响导入的集群。有关其他集群类型，请参考[移除 Rancher 后访问下游集群](#如果删除了-rancher-server该如何访问下游集群)。 + +## 如果我不想 Rancher 管理我的注册集群该怎么办？ + +如果你在 Rancher UI 中删除了已注册的集群，则该集群将与 Rancher 分离，集群不会发生改变，你可以使用注册集群之前的方法访问该集群。 + +要分离集群： + +1. 在左上角，单击 **☰ > 集群管理**。 +2. 转到要与 Rancher 分离的已注册集群，然后单击 **⋮ > 删除**。 +3. 单击**删除**。 + +**结果**：注册的集群已与 Rancher 分离，并在 Rancher 外正常运行。 + +## What if I don't want my hosted Kubernetes cluster managed by Rancher? + +目前，我们没有将这些集群从 Rancher 中分离出来的功能。在这种情况下，“分离”指的是将 Rancher 组件移除出集群，并独立于 Rancher 管理对集群的访问。 + +[此 issue](https://github.com/rancher/rancher/issues/25234) 跟踪了在没有 Rancher 的情况下管理这些集群的功能。 + +有关如何在删除 Rancher Server 后访问集群的更多信息，请参阅[本节](#如果删除了-rancher-server该如何访问下游集群)。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/faq/security.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/faq/security.md new file mode 100644 index 00000000000..805cfd72c7f --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/faq/security.md @@ -0,0 +1,14 @@ +--- +title: 安全 + +--- + +**是否有强化指南？** + +强化指南现在位于[安全](../reference-guides/rancher-security/rancher-security.md)部分。 + +
+ +**Rancher Kubernetes 集群 CIS Benchmark 测试的结果是什么？** + +我们已经针对强化的 Rancher Kubernetes 集群运行了 CIS Kubernetes Benchmark 测试。你可以在[安全](../reference-guides/rancher-security/rancher-security.md)中找到该评估的结果。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/faq/technical-items.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/faq/technical-items.md new file mode 100644 index 00000000000..d9c83604fc8 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/faq/technical-items.md @@ -0,0 +1,180 @@ +--- +title: 技术 +--- + +## 如何重置管理员密码？ + +Docker 安装： + +``` +$ docker exec -ti reset-password +New password for default administrator (user-xxxxx): + +``` + +Kubernetes 安装（Helm）： + +``` +$ KUBECONFIG=./kube_config_cluster.yml +$ kubectl --kubeconfig $KUBECONFIG -n cattle-system exec $(kubectl --kubeconfig $KUBECONFIG -n cattle-system get pods -l app=rancher --no-headers | head -1 | awk '{ print $1 }') -c rancher -- reset-password +New password for default administrator (user-xxxxx): + +``` + +## 我删除/停用了最后一个 admin，该如何解决？ + +Docker 安装： + +``` +$ docker exec -ti ensure-default-admin +New default administrator (user-xxxxx) +New password for default administrator (user-xxxxx): + +``` + +Kubernetes 安装（Helm）： + +``` +$ KUBECONFIG=./kube_config_cluster.yml +$ kubectl --kubeconfig $KUBECONFIG -n cattle-system exec $(kubectl --kubeconfig $KUBECONFIG -n cattle-system get pods -l app=rancher | grep '1/1' | head -1 | awk '{ print $1 }') -- ensure-default-admin +New password for default administrator (user-xxxxx): + +``` + +## 如何启用调试日志记录？ + +请参阅[故障排除：日志记录](../troubleshooting/other-troubleshooting-tips/logging.md)。 + +## 我的 ClusterIP 不响应 ping，该如何解决？ + +ClusterIP 是一个虚拟 IP，不会响应 ping。要测试 ClusterIP 是否配置正确，最好的方法是使用 `curl` 访问 IP 和端口并检查它是否响应。 + +## 在哪里管理节点模板？ + +打开你的账号菜单（右上角）并选择`节点模板`。 + +## 为什么我的四层负载均衡器处于 `Pending` 状态？ + +四层负载均衡器创建为 `type: LoadBalancer`。Kubernetes 需要一个可以满足这些请求的云提供商或控制器，否则这些请求将永远处于 `Pending` 状态。有关更多信息，请参阅[云提供商](../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-cloud-providers/set-up-cloud-providers.md)或[创建外部负载均衡器](https://kubernetes.io/docs/tasks/access-application-cluster/create-external-load-balancer/)。 + +## Rancher 的状态存储在哪里？ + +- Docker 安装：在 `rancher/rancher` 容器的嵌入式 etcd 中，位于 `/var/lib/rancher`。 +- Kubernetes install: default location is in the `/var/lib/rancher/rke2` or `/var/lib/rancher/k3s` directories of the respective RKE2/K3s cluster created to run Rancher. + +## 支持的 Docker 版本是如何确定的？ + +我们遵循上游 Kubernetes 版本验证过的 Docker 版本。如果需要获取验证过的版本，请查看 Kubernetes 版本 CHANGELOG.md 中的 [External Dependencies](https://github.com/kubernetes/kubernetes/blob/master/CHANGELOG/CHANGELOG-1.10.md#external-dependencies)。 + +## 如何访问 Rancher 创建的节点？ + +你可以转到**节点**视图，然后下载用于访问 Rancher 创建的节点的 SSH 密钥。选择要访问的节点并单击行尾 **⋮** 按钮，然后选择**下载密钥**，如下图所示。 + +![下载密钥](/img/downloadsshkeys.png) + +解压缩下载的 zip 文件，并使用 `id_rsa` 文件连接到你的主机。请务必使用正确的用户名（如果是 RancherOS，则使用 `rancher` 或 `docker`；如果是 Ubuntu，则使用 `ubuntu`；如果是 Amazon Linux，则使用 `ec2-user`）。 + +``` +$ ssh -i id_rsa user@ip_of_node +``` + +## 如何在 Rancher 中自动化任务 X？ + +UI 由静态文件组成，并根据 API 的响应工作。换言之，UI 中可以执行的每个操作/任务都可以通过 API 进行自动化。有两种方法可以实现这一点： + +* 访问 `https://your_rancher_ip/v3` 并浏览 API 选项。 +* 在使用 UI 时捕获 API 调用（通常使用 [Chrome 开发者工具](https://developers.google.com/web/tools/chrome-devtools/#network)，但你也可以使用其他工具）。 + +## 节点的 IP 地址改变了，该如何恢复？ + +节点需要配置静态 IP（或使用 DHCP 保留的 IP）。如果节点的 IP 已更改，你必须在集群中删除并重新添加它。删除后，Rancher 会将集群更新为正确的状态。如果集群不再处于 `Provisioning` 状态，则已从集群删除该节点。 + +节点的 IP 地址发生变化时，Rancher 会失去与节点的连接，因此无法正常清理节点。请参阅[清理集群节点](../how-to-guides/new-user-guides/manage-clusters/clean-cluster-nodes.md)来清理节点。 + +在集群中移除并清理节点时，你可以将节点重新添加到集群中。 + +## 如何将其他参数/绑定/环境变量添加到 Rancher 启动的 Kubernetes 集群的 Kubernetes 组件中？ + +You can add more arguments/binds/environment variables via the respective [RKE2 Config File](../reference-guides/cluster-configuration/rancher-server-configuration/rke2-cluster-configuration.md#cluster-configuration) or [K3s Config File](../reference-guides/cluster-configuration/rancher-server-configuration/k3s-cluster-configuration.md#cluster-configuration). + +## 如何检查证书链是否有效？ + +使用 `openssl verify` 命令来验证你的证书链： + +:::tip + +将 `SSL_CERT_DIR` 和 `SSL_CERT_FILE` 配置到虚拟位置，从而确保在手动验证时不使用操作系统安装的证书。 + +::: + +``` +SSL_CERT_DIR=/dummy SSL_CERT_FILE=/dummy openssl verify -CAfile ca.pem rancher.yourdomain.com.pem +rancher.yourdomain.com.pem: OK +``` + +如果你看到 `unable to get local issuer certificate` 错误，则表示链不完整。通常情况下，这表示你的服务器证书由中间 CA 颁发。如果你已经拥有此证书，你可以在证书的验证中使用它，如下所示： + +``` +SSL_CERT_DIR=/dummy SSL_CERT_FILE=/dummy openssl verify -CAfile ca.pem -untrusted intermediate.pem rancher.yourdomain.com.pem +rancher.yourdomain.com.pem: OK +``` + +如果你已成功验证证书链，你需要在服务器证书中包含所需的中间 CA 证书，从而完成与 Rancher 连接的证书链（例如，使用 Rancher Agent）。服务器证书文件中证书的顺序首先是服务器证书本身（`rancher.yourdomain.com.pem` 的内容），然后是中间 CA 证书（`intermediate.pem` 的内容）： + +``` +-----BEGIN CERTIFICATE----- +%YOUR_CERTIFICATE% +-----END CERTIFICATE----- +-----BEGIN CERTIFICATE----- +%YOUR_INTERMEDIATE_CERTIFICATE% +-----END CERTIFICATE----- +``` + +如果在验证过程中仍然出现错误，你可以运行以下命令，检索服务器证书的主题和颁发者： + +``` +openssl x509 -noout -subject -issuer -in rancher.yourdomain.com.pem +subject= /C=GB/ST=England/O=Alice Ltd/CN=rancher.yourdomain.com +issuer= /C=GB/ST=England/O=Alice Ltd/CN=Alice Intermediate CA +``` + +## 如何在服务器证书中检查 `Common Name` 和 `Subject Alternative Names`？ + +虽然技术上仅需要 `Subject Alternative Names` 中有一个条目，但在 `Common Name` 和 `Subject Alternative Names` 中都包含主机名可以最大程度地提高与旧版浏览器/应用程序的兼容性。 + +检查 `Common Name`： + +``` +openssl x509 -noout -subject -in cert.pem +subject= /CN=rancher.my.org +``` + +检查 `Subject Alternative Names`： + +``` +openssl x509 -noout -in cert.pem -text | grep DNS + DNS:rancher.my.org +``` + +## 为什么节点发生故障时重新调度一个 pod 需要 5 分钟以上的时间？ + +这是以下默认 Kubernetes 设置的组合导致的： + +* kubelet + * `node-status-update-frequency`：指定 kubelet 将节点状态发布到 master 的频率（默认 10s）。 +* kube-controller-manager + * `node-monitor-period`：在 NodeController 中同步 NodeStatus 的周期（默认 5s）。 + * `node-monitor-grace-period`：在将节点标记为不健康之前，允许节点无响应的时间长度（默认 40s）。 + * `pod-eviction-timeout`：在故障节点上删除 pod 的宽限期（默认 5m0s）。 + +有关这些设置的更多信息，请参阅 [Kubernetes：kubelet](https://kubernetes.io/docs/reference/command-line-tools-reference/kubelet/) 和 [Kubernetes：kube-controller-manager](https://kubernetes.io/docs/reference/command-line-tools-reference/kube-controller-manager/)。 + +Kubernetes 1.13 默认启用 `TaintBasedEvictions` 功能。有关详细信息，请参阅 [Kubernetes：基于污点的驱逐](https://kubernetes.io/docs/concepts/configuration/taint-and-toleration/#taint-based-evictions)。 + +* kube-apiserver（Kubernetes 1.13 及更高版本） + * `default-not-ready-toleration-seconds`：表示 `notReady:NoExecute` 的容忍度的 `tolerationSeconds`，该设置默认添加到还没有该容忍度的 pod。 + * `default-unreachable-toleration-seconds`：表示 `unreachable:NoExecute` 的容忍度的 `tolerationSeconds`，该设置默认添加到还没有该容忍度的 pod。 + +## 我可以在 UI 中使用键盘快捷键吗？ + +是的，你可以使用键盘快捷键访问 UI 的大部分内容。要查看快捷方式的概览，请在 UI 任意位置按 `?`。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/faq/telemetry.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/faq/telemetry.md new file mode 100644 index 00000000000..8d6f997c443 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/faq/telemetry.md @@ -0,0 +1,31 @@ +--- +title: 遥测 +--- + +## 什么是遥测？ + +遥测（Telemetry）收集 Rancher 安装大小、使用的组件版本以及使用功能的汇总信息。Rancher Labs 会使用此信息来改进产品，我们不会与第三方共享此信息。 + +## 收集什么信息？ + +我们不会收集任何识别信息（如用户名、密码或用户资源的名称或地址）。 + +收集的主要内容包括： + +- 每个集群的节点总数（最小、平均、最大、总数）及其大小（例如 CPU 核心数和 RAM）。 +- 集群、项目、命名空间和 Pod 等逻辑资源的聚合计数。 +- 用于部署集群和节点的驱动程序计数（例如 GKE、EC2、导入与自定义）。 +- 部署在节点上的 Kubernetes 组件、操作系统和 Docker 的版本。 +- 是否启用了某些可选组件（例如，使用了哪些身份验证提供程序）。 +- 运行的 Rancher 的镜像名称和版本。 +- 此安装的唯一随机标识符。 + +## 我可以看到发送的信息吗？ + +如果启用了遥测，你可以转到 `https:///v1-telemetry` 查看当前数据。 + +如果未启用遥测，则收集数据的进程未运行，因此没有可供查看的内容。 + +## 如何打开或关闭它？ + +完成初始设置后，管理员可以转到 UI `全局`中的`设置`页面，单击**编辑**，然后将 `telemetry-opt` 更改为 `in` 或 `out`。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/air-gapped-upgrades.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/air-gapped-upgrades.md new file mode 100644 index 00000000000..37f8dc7513e --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/air-gapped-upgrades.md @@ -0,0 +1,98 @@ +--- +title: 在离线环境中升级 +--- + +:::note + +以下说明假设你已经按照[本页](upgrades.md)的 Kubernetes 升级说明操作（包括先决条件）到步骤 3：升级 Rancher。 + +::: + +## Rancher Helm 模板选项 + +使用安装 Rancher 时选择的选项来渲染 Rancher 模板。参考下表来替换每个占位符。Rancher 需要配置为使用私有镜像仓库，以便配置所有 Rancher 启动的 Kubernetes 集群或 Rancher 工具。 + +根据你在安装过程中做出的选择，完成以下步骤之一。 + +| 占位符 | 描述 | +------------|------------- +| `` | 输出压缩包的版本号。 | +| `` | 指向负载均衡器的 DNS 名称。 | +| `` | 你的私有镜像仓库的 DNS 名称。 | +| `` | 在 K8s 集群上运行的 cert-manager 版本。 | + +### 选项 A：使用默认的自签名证书 + +``` +helm template rancher ./rancher-.tgz --output-dir . \ + --no-hooks \ # prevent files for Helm hooks from being generated + --namespace cattle-system \ + --set hostname= \ + --set certmanager.version= \ + --set rancherImage=/rancher/rancher \ + --set systemDefaultRegistry= \ # Set a default private registry to be used in Rancher + --set useBundledSystemChart=true # Use the packaged Rancher system charts +``` + +#### 解决 UPGRADE FAILED 错误 + +如果你遇到错误消息 `Error: UPGRADE FAILED: "rancher" has no deployed releases`，Rancher 可能是通过 `helm template` 命令安装的。要成功升级 Rancher，请改用以下命令： + +``` +helm template rancher ./rancher-.tgz --output-dir . \ + --no-hooks \ # prevent files for Helm hooks from being generated + --namespace cattle-system \ + --set hostname= \ + --set certmanager.version= \ + --set rancherImage=/rancher/rancher \ + --set systemDefaultRegistry= \ # Set a default private registry to be used in Rancher + --set useBundledSystemChart=true # Use the packaged Rancher system charts +``` + +执行 Helm 命令后，需要应用渲染后的模板： + +``` +kubectl -n cattle-system apply -R -f ./rancher +``` +### 选项 B：使用 Kubernetes 密文从文件中获取证书 + +```plain +helm template rancher ./rancher-.tgz --output-dir . \ + --no-hooks \ # prevent files for Helm hooks from being generated + --namespace cattle-system \ + --set hostname= \ + --set rancherImage=/rancher/rancher \ + --set ingress.tls.source=secret \ + --set systemDefaultRegistry= \ # Set a default private registry to be used in Rancher + --set useBundledSystemChart=true # Use the packaged Rancher system charts +``` + +如果你使用的是私有 CA 签名的证书，请在 `--set ingress.tls.source=secret` 后加上 `--set privateCA=true`： + +```plain +helm template rancher ./rancher-.tgz --output-dir . \ + --no-hooks \ # prevent files for Helm hooks from being generated + --namespace cattle-system \ + --set hostname= \ + --set rancherImage=/rancher/rancher \ + --set ingress.tls.source=secret \ + --set privateCA=true \ + --set systemDefaultRegistry= \ # Set a default private registry to be used in Rancher + --set useBundledSystemChart=true # Use the packaged Rancher system charts +``` + +## 验证升级 + +登录 Rancher 以确认升级成功。 + +:::tip + +升级后出现网络问题？ + +请参见[恢复集群网络](https://github.com/rancher/rancher-docs/tree/main/archived_docs/en/version-2.0-2.4/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/upgrades/namespace-migration.md)。 + +::: + +## 已知升级问题 + +你可以在 [GitHub](https://github.com/rancher/rancher/releases) 发布说明以及 [Rancher 论坛](https://forums.rancher.com/c/announcements/12)中找到每个 Rancher 版本的已知问题。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/install-upgrade-on-a-kubernetes-cluster.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/install-upgrade-on-a-kubernetes-cluster.md new file mode 100644 index 00000000000..db918c4be8a --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/install-upgrade-on-a-kubernetes-cluster.md @@ -0,0 +1,347 @@ +--- +title: 在 Kubernetes 集群上安装/升级 Rancher +description: 了解如何在开发和生产环境中安装 Rancher。了解单节点和高可用安装 +--- + +在本节中，你将学习如何使用 Helm CLI 在 Kubernetes 集群上部署 Rancher。 + + +## 先决条件 + +- [Kubernetes 集群](#kubernetes-集群) +- [Ingress Controller](#ingress-controller) +- [CLI 工具](#cli-工具) + +### Kubernetes 集群 + +设置 Rancher Server 的本地 Kubernetes 集群。 + +Rancher 可以安装在任何 Kubernetes 集群上。这个集群可以使用上游 Kubernetes，也可以使用 Rancher 的 Kubernetes 发行版之一，也可以是来自 Amazon EKS 等提供商的托管 Kubernetes 集群。 + +你可参考以下教程，以获得设置 Kubernetes 集群的帮助： + +- **K3s**：[安装 K3s Kubernetes 集群的教程](../../../how-to-guides/new-user-guides/kubernetes-cluster-setup/k3s-for-rancher.md)；[设置高可用 K3s 集群的基础设施的教程](../../../how-to-guides/new-user-guides/infrastructure-setup/ha-k3s-kubernetes-cluster.md)。 +- **RKE2:** ：[安装 RKE2 Kubernetes 集群的教程](../../../how-to-guides/new-user-guides/kubernetes-cluster-setup/rke2-for-rancher.md)；[设置高可用 RKE2 集群的基础设施的教程](../../../how-to-guides/new-user-guides/infrastructure-setup/ha-rke2-kubernetes-cluster.md)。 +- **Amazon EKS**：[在 Amazon EKS 上安装 Rancher 以及如何安装 Ingress Controller 以访问 Rancher Server](rancher-on-amazon-eks.md)。 +- **AKS**：[使用 Azure Kubernetes 服务安装 Rancher 以及如何安装 Ingress Controller 以访问 Rancher Server](rancher-on-aks.md)。 +- **GKE**：有关如何使用 GKE 安装 Rancher，包括如何安装 Ingress Controller 以便可以访问 Rancher Server，请参阅[此页面](rancher-on-gke.md)。GKE 创建 Kubernetes 集群时有两种运行模式，分别是 Autopilot 和 Standard 模式。Autopilot 模式的集群配置对编辑 kube-system 命名空间有限制。但是，Rancher 在安装时需要在 kube-system 命名空间中创建资源。因此，你将无法在以 Autopilot 模式创建的 GKE 集群上安装 Rancher。 + + +### Ingress Controller + +Rancher UI 和 API 通过 Ingress 公开。换言之，安装 Rancher 的 Kubernetes 集群必须包含一个 Ingress Controller。 + +对于 RKE2 和 K3s，你不需要手动安装 Ingress Controller，因为它是默认安装的。 + +对于默认不包含 Ingress Controller 的发行版（例如 EKS、GKE 或 AKS 等托管 Kubernetes 集群），你必须先部署 Ingress Controller。请注意，Rancher Helm Chart 默认情况下不会在 Ingress 上设置 `ingressClassName`。因此，你必须将 Ingress Controller 配置为在没有 `ingressClassName` 的情况下也可以监视 Ingress。 + +上面的 **Amazon EKS**、**AKS** 和 **GKE** 教程中包含了示例。 + +### CLI 工具 + +设置 Kubernetes 集群需要以下 CLI 工具。请确保这些工具已安装并在你的 `$PATH` 中可用。 + +- [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/#install-kubectl) - Kubernetes 命令行工具。 +- [Helm](https://docs.helm.sh/using_helm/#installing-helm) - Kubernetes 的包管理器。请参见 [Helm 版本要求](../resources/helm-version-requirements.md)选择 Helm 版本来安装 Rancher。请为你的具体平台参见 [Helm 项目提供的说明](https://helm.sh/docs/intro/install/)。 + +## 安装 Rancher Helm Chart + +Rancher 是使用 Kubernetes 的 [Helm](https://helm.sh/) 包管理器安装的。Helm Chart 为 Kubernetes YAML 清单文件提供了模板语法。通过 Helm，用户可以创建可配置的 deployment，而不仅仅只能使用静态文件。 + +如果系统无法直接访问互联网，请参见[离线环境：Kubernetes 安装](../other-installation-methods/air-gapped-helm-cli-install/install-rancher-ha.md)。 + +如果要指定安装的 Rancher 版本，请参见[选择 Rancher 版本](../resources/choose-a-rancher-version.md)。 + +如果要指定用于安装 Rancher 的 Helm 版本，请参见[Helm 版本要求](../resources/helm-version-requirements.md)。 + +:::note + +本安装指南假定你使用的是 Helm 3。 + +::: + +要设置 Rancher： + +1. [添加 Helm Chart 仓库](#1-添加-helm-chart-仓库) +2. [为 Rancher 创建命名空间](#2-为-rancher-创建命名空间) +3. [选择 SSL 配置](#3-选择-ssl-配置) +4. [安装 cert-manager](#4-安装-cert-manager)（除非你自带证书，否则 TLS 将在负载均衡器上终止） +5. [使用 Helm 和你选择的证书选项安装 Rancher](#5-根据你选择的证书选项通过-helm-安装-rancher) +6. [验证 Rancher Server 是否部署成功](#6-验证-rancher-server-是否部署成功) +7. [保存选项](#7-保存选项) + +### 1. 添加 Helm Chart 仓库 + +执行 `helm repo add` 命令，以添加包含安装 Rancher 的 Chart 的 Helm Chart 仓库。有关如何选择仓库，以及哪个仓库最适合你的用例，请参见[选择 Rancher 版本](../resources/choose-a-rancher-version.md)。 + +- Latest：建议用于试用最新功能 + ``` + helm repo add rancher-latest https://releases.rancher.com/server-charts/latest + ``` +- Stable：建议用于生产环境 + ``` + helm repo add rancher-stable https://releases.rancher.com/server-charts/stable + ``` +- Alpha：即将发布的实验性预览。 + ``` + helm repo add rancher-alpha https://releases.rancher.com/server-charts/alpha + ``` + 注意：不支持升级到 Alpha 版、从 Alpha 版升级或在 Alpha 版之间升级。 + +### 2. 为 Rancher 创建命名空间 + +你需要定义一个 Kubernetes 命名空间，用于安装由 Chart 创建的资源。这个命名空间的名称为 `cattle-system`： + +``` +kubectl create namespace cattle-system +``` + +### 3. 选择 SSL 配置 + +Rancher Management Server 默认需要 SSL/TLS 配置来保证访问的安全性。 + +:::note + +如果你想在外部终止 SSL/TLS，请参见[外部负载均衡器的 TLS 终止](../installation-references/helm-chart-options.md#外部-tls-终止)。 + +::: + +你可以从以下三种证书来源中选择一种，用于在 Rancher Server 中终止 TLS： + +- **Rancher 生成的 TLS 证书**：要求你在集群中安装 `cert-manager`。Rancher 使用 `cert-manager` 签发并维护证书。Rancher 会生成自己的 CA 证书，并使用该 CA 签署证书。然后 `cert-manager`负责管理该证书。 +- **Let's Encrypt**：Let's Encrypt 选项也需要使用 `cert-manager`。但是，在这种情况下，cert-manager 与 Let's Encrypt 的特殊颁发者相结合，该颁发者执行获取 Let's Encrypt 颁发的证书所需的所有操作（包括请求和验证）。此配置使用 HTTP 验证（`HTTP-01`），因此负载均衡器必须具有可以从互联网访问的公共 DNS 记录。 +- **你已有的证书**：使用已有的 CA 颁发的公有或私有证书。Rancher 将使用该证书来保护 WebSocket 和 HTTPS 流量。在这种情况下，你必须上传名称分别为 `tls.crt` 和 `tls.key`的 PEM 格式的证书以及相关的密钥。如果你使用私有 CA，则还必须上传该 CA 证书。这是由于你的节点可能不信任此私有 CA。Rancher 将获取该 CA 证书，并从中生成一个校验和，各种 Rancher 组件将使用该校验和来验证其与 Rancher 的连接。 + + +| 配置 | Helm Chart 选项 | 是否需要 cert-manager | +| ------------------------------ | ----------------------- | ------------------------------------- | +| Rancher 生成的证书（默认） | `ingress.tls.source=rancher` | [是](#4-安装-cert-manager) | +| Let’s Encrypt | `ingress.tls.source=letsEncrypt` | [是](#4-安装-cert-manager) | +| 你已有的证书 | `ingress.tls.source=secret` | 否 | + +### 4. 安装 cert-manager + +> 如果你使用自己的证书文件（`ingress.tls.source=secret`）或使用[外部负载均衡器的 TLS 终止](../installation-references/helm-chart-options.md#外部-tls-终止)，你可以跳过此步骤。 + +仅在使用 Rancher 生成的证书（`ingress.tls.source=rancher`）或 Let's Encrypt 颁发的证书（`ingress.tls.source=letsEncrypt`）时，才需要安装 cert-manager。 + +
+ 单击展开 + +:::note 重要提示： + +由于 cert-manager 的最新改动，你需要升级 cert-manager 版本。如果你需要升级 Rancher 并使用低于 0.11.0 的 cert-manager 版本，请参见[升级文档](../resources/upgrade-cert-manager.md)。 + +::: + +这些说明来自 [cert-manager 官方文档](https://cert-manager.io/docs/installation/kubernetes/#installing-with-helm)。 + +:::note + +要查看自定义 cert-manager 安装的选项（包括集群使用 PodSecurityPolicies 的情况），请参阅 [cert-manager 文档](https://artifacthub.io/packages/helm/cert-manager/cert-manager#configuration)。 + +::: + +``` +# 如果你手动安装了CRD，而不是在 Helm 安装命令中添加了 `--set installCRDs=true` 选项，你应该在升级 Helm Chart 之前升级 CRD 资源。 +kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download//cert-manager.crds.yaml + +# 添加 Jetstack Helm 仓库 +helm repo add jetstack https://charts.jetstack.io + +# 更新本地 Helm Chart 仓库缓存 +helm repo update + +# 安装 cert-manager Helm Chart +helm install cert-manager jetstack/cert-manager \ + --namespace cert-manager \ + --create-namespace +``` + +安装完 cert-manager 后，你可以通过检查 cert-manager 命名空间中正在运行的 Pod 来验证它是否已正确部署： + +``` +kubectl get pods --namespace cert-manager + +NAME READY STATUS RESTARTS AGE +cert-manager-5c6866597-zw7kh 1/1 Running 0 2m +cert-manager-cainjector-577f6d9fd7-tr77l 1/1 Running 0 2m +cert-manager-webhook-787858fcdb-nlzsq 1/1 Running 0 2m +``` + +
+ +### 5. 根据你选择的证书选项，通过 Helm 安装 Rancher + +不同的证书配置需要使用不同的 Rancher 安装命令。 + +但是，无论证书如何配置，Rancher 在 `cattle-system` 命名空间中的安装名称应该总是 `rancher`。 + +:::tip 测试和开发： + +这个安装 Rancher 的最终命令需要一个将流量转发到 Rancher 的域名。如果你使用 Helm CLI 设置概念证明，则可以在传入 `hostname` 选项时使用伪域名。伪域名的一个例子是 `.sslip.io`，这会把 Rancher 暴露在它运行的 IP 上。生产安装中要求填写真实的域名。 + +::: + + + + +默认情况是使用 Rancher 生成 CA，并使用 `cert-manager` 颁发用于访问 Rancher Server 接口的证书。 + +由于 `rancher` 是 `ingress.tls.source` 的默认选项，因此在执行 `helm install` 命令时，我们不需要指定 `ingress.tls.source`。 + +- 将 `hostname` 设置为解析到你的负载均衡器的 DNS 名称。 +- 将 `bootstrapPassword` 设置为 `admin` 用户独有的值。 +- 如果你需要安装指定的 Rancher 版本，使用 `--version` 标志，例如 `--version 2.7.0`。 + +``` +helm install rancher rancher-/rancher \ + --namespace cattle-system \ + --set hostname=rancher.my.org \ + --set bootstrapPassword=admin +``` + +如果你安装的是 alpha 版本，Helm 会要求你在安装命令中添加 `--devel` 选项： + +``` +helm install rancher rancher-alpha/rancher --devel +``` + +等待 Rancher 运行： + +``` +kubectl -n cattle-system rollout status deploy/rancher +Waiting for deployment "rancher" rollout to finish: 0 of 3 updated replicas are available... +deployment "rancher" successfully rolled out +``` + + + + +此选项使用 `cert-manager` 来自动请求和续订 [Let's Encrypt](https://letsencrypt.org/) 证书。Let's Encrypt 是免费的，而且是受信的 CA，因此可以为你提供有效的证书。 + +:::note + +由于 HTTP-01 质询只能在端口 80 上完成，因此你需要打开端口 80。 + +::: + +在以下命令中， + +- 将 `hostname` 设置为公有 DNS 记录。 +- 将 `bootstrapPassword` 设置为 `admin` 用户独有的值。 +- 将 `ingress.tls.source` 设置为 `letsEncrypt`。 +- 将 `letsEncrypt.email` 设置为可通讯的电子邮件地址，用于发送通知（例如证书到期的通知）。 +- 将 `letsEncrypt.ingress.class` 设为你的 Ingress Controller（例如 `traefik`，`nginx`，`haproxy`） + +``` +helm install rancher rancher-/rancher \ + --namespace cattle-system \ + --set hostname=rancher.my.org \ + --set bootstrapPassword=admin \ + --set ingress.tls.source=letsEncrypt \ + --set letsEncrypt.email=me@example.org \ + --set letsEncrypt.ingress.class=nginx +``` + +如果你安装的是 alpha 版本，Helm 会要求你在安装命令中添加 `--devel` 选项： + +``` +helm install rancher rancher-alpha/rancher --devel +``` + +等待 Rancher 运行： + +``` +kubectl -n cattle-system rollout status deploy/rancher +Waiting for deployment "rancher" rollout to finish: 0 of 3 updated replicas are available... +deployment "rancher" successfully rolled out +``` + + + +在此选项中，你使用你自己的证书来创建 Kubernetes 密文，以供 Rancher 使用。 + +运行这个命令时，`hostname` 选项必须与服务器证书中的 `Common Name` 或 `Subject Alternative Names` 条目匹配，否则 Ingress controller 将无法正确配置。 + +虽然技术上仅需要 `Subject Alternative Names` 中有一个条目，但是拥有一个匹配的 `Common Name` 可以最大程度地提高与旧版浏览器/应用的兼容性。 + +:::note + +如果你想检查证书是否正确，请查看[如何在服务器证书中检查 Common Name 和 Subject Alternative Names](../../../faq/technical-items.md#如何在服务器证书中检查-common-name-和-subject-alternative-names)。 + +::: + +- 设置 `hostname`。 +- 将 `bootstrapPassword` 设置为 `admin` 用户独有的值。 +- 将 `ingress.tls.source` 设置为 `secret`。 + +``` +helm install rancher rancher-/rancher \ + --namespace cattle-system \ + --set hostname=rancher.my.org \ + --set bootstrapPassword=admin \ + --set ingress.tls.source=secret +``` +如果你安装的是 alpha 版本，Helm 会要求你在安装命令中添加 `--devel` 选项： + +``` +helm install rancher rancher-alpha/rancher --devel +``` + +如果你使用的是私有 CA 证书，请在命令中增加 `--set privateCA=true`。 + +``` +helm install rancher rancher-/rancher \ + --namespace cattle-system \ + --set hostname=rancher.my.org \ + --set bootstrapPassword=admin \ + --set ingress.tls.source=secret \ + --set privateCA=true +``` + +**添加 TLS 密文（千万不要遗漏此步骤）**：现在 Rancher 已经完成部署，你还需要参考[添加 TLS 密文](../resources/add-tls-secrets.md)发布证书文件，以便 Rancher 和 Ingress Controller 可以使用它们。 + + + + +Rancher Chart 有许多选项，用于为你的具体环境自定义安装。以下是一些常见的高级方案： + +- [HTTP 代理](../installation-references/helm-chart-options.md#http-代理) +- [私有容器镜像仓库](../installation-references/helm-chart-options.md#私有仓库和离线安装) +- [外部负载均衡器上的 TLS 终止](../installation-references/helm-chart-options.md#外部-tls-终止) + +如需获取完整的选项列表，请参见 [Chart 选项](../installation-references/helm-chart-options.md)。 + + +### 6. 验证 Rancher Server 是否部署成功 + +添加密文后，检查 Rancher 是否已成功运行： + +``` +kubectl -n cattle-system rollout status deploy/rancher +Waiting for deployment "rancher" rollout to finish: 0 of 3 updated replicas are available... +deployment "rancher" successfully rolled out +``` + +如果你看到 `error: deployment "rancher" exceeded its progress deadline` 这个错误，可运行以下命令来检查 deployment 的状态： + +``` +kubectl -n cattle-system get deploy rancher +NAME DESIRED CURRENT UP-TO-DATE AVAILABLE AGE +rancher 3 3 3 3 3m +``` + +`DESIRED` 和 `AVAILABLE`的个数应该相同。 + +### 7. 保存选项 + +请保存你使用的 `--set` 选项。使用 Helm 升级 Rancher 到新版本时，你将需要使用相同的选项。 + +### 安装完成 + +安装已完成。现在 Rancher Server 应该已经可以正常运行了。 + +使用浏览器打开把流量转发到你的负载均衡器的 DNS 域名。然后，你就会看到一个漂亮的登录页面了。 + +如果遇到任何问题，请参见[故障排除](troubleshooting.md)。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/rancher-on-aks.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/rancher-on-aks.md new file mode 100644 index 00000000000..4db511d97a0 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/rancher-on-aks.md @@ -0,0 +1,147 @@ +--- +title: 在 Azure Kubernetes Service 上安装 Rancher +--- + +本文介绍了如何在微软的 Azure Kubernetes Service (AKS) 上安装 Rancher。 + +本指南使用命令行工具来配置一个带有 Ingress 的 AKS 集群。如果你更喜欢使用 Azure 门户来配置集群，请参见[官方文档](https://docs.microsoft.com/en-us/azure/aks/kubernetes-walkthrough-portal)。 + +如果你已有一个 AKS Kubernetes 集群，请直接跳到[安装 Ingress](#5-安装-ingress) 的步骤，然后按照[此页](install-upgrade-on-a-kubernetes-cluster.md#安装-rancher-helm-chart)的说明安装 Rancher Helm Chart。 + +## 先决条件 + +:::caution + +部署到 Microsoft Azure 会产生费用。 + +::: + +- [Microsoft Azure 账号](https://azure.microsoft.com/en-us/free/)：用于创建部署 Rancher 和 Kubernetes 的资源。 +- [Microsoft Azure 订阅](https://docs.microsoft.com/en-us/azure/cost-management-billing/manage/create-subscription#create-a-subscription-in-the-azure-portal)：如果你没有的话，请访问此链接查看如何创建 Microsoft Azure 订阅。 +- [Micsoroft Azure 租户](https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-create-new-tenant)：访问此链接并参考教程以创建 Microsoft Azure 租户。 +- 你的订阅有足够的配额，至少有 2 个 vCPU。有关 Rancher Server 资源要求的详情，请参见[此节](../installation-requirements/installation-requirements.md)。 +- 在 Azure 中用 Helm 安装 Rancher 时，请使用 L7 负载均衡器来避免网络问题。详情请参见 [Azure 负载均衡器限制](https://docs.microsoft.com/en-us/azure/load-balancer/components#limitations)。 + +## 1. 准备你的工作站 + +在工作站上安装以下命令行工具： + +- **az**，Azure CLI：如需获得帮助，请参见[安装步骤](https://docs.microsoft.com/en-us/cli/azure/)。 +- **kubectl**：如需获得帮助，请参见[安装步骤](https://kubernetes.io/docs/tasks/tools/#kubectl)。 +- **helm**：如需获取帮助，请参见[安装步骤](https://helm.sh/docs/intro/install/)。 + +## 2. 创建资源组 + +安装 CLI 后，你需要用你的 Azure 账户登录： + +``` +az login +``` + +创建一个 [资源组](https://docs.microsoft.com/en-us/azure/azure-resource-manager/management/manage-resource-groups-portal) 来保存集群的所有相关资源。使用一个适用于你实际情况的位置： + +``` +az group create --name rancher-rg --location eastus +``` + +## 3. 创建 AKS 集群 + +运行以下命令创建一个 AKS 集群。选择适用于你实际情况的虚拟机大小。如需获得可用的大小和选项，请参见[此处](https://docs.microsoft.com/en-us/azure/virtual-machines/sizes)。在选择 Kubernetes 版本时，请务必先查阅[支持矩阵](https://rancher.com/support-matrix/)，以找出已针对你的 Rancher 版本验证的最新 Kubernetes 版本。 + +:::note + +如果你要从旧的 Kubernetes 版本更新到 Kubernetes v1.22 或更高版本，你还需要[更新](https://kubernetes.github.io/ingress-nginx/user-guide/k8s-122-migration/) ingress-nginx。 + +::: + +``` +az aks create \ + --resource-group rancher-rg \ + --name rancher-server \ + --kubernetes-version \ + --node-count 3 \ + --node-vm-size Standard_D2_v3 +``` + +集群部署需要一些时间才能完成。 + +## 4. 获取访问凭证 + +集群部署完成后，获取访问凭证。 + +``` +az aks get-credentials --resource-group rancher-rg --name rancher-server +``` + +此命令把集群的凭证合并到现有的 kubeconfig 中，并允许 `kubectl` 与集群交互。 + +## 5. 安装 Ingress + +集群需要一个 Ingress，以从集群外部访问 Rancher。要 Ingress，你需要分配一个公共 IP 地址。请确保你有足够的配额，否则它将无法分配 IP 地址。公共 IP 地址的限制在每个订阅的区域级别生效。 + +为确保你选择了正确的 Ingress-NGINX Helm Chart，首先在 [Kubernetes/ingress-nginx 支持表](https://github.com/kubernetes/ingress-nginx#supported-versions-table)中找到与你的 Kubernetes 版本兼容的 `Ingress-NGINX 版本`。 + +然后，运行以下命令列出可用的 Helm Chart： + +``` +helm repo add ingress-nginx https://kubernetes.github.io/ingress-nginx +helm repo update +helm search repo ingress-nginx -l +``` + +`helm search` 命令的输出包含一个 `APP VERSION` 列。此列下的版本等同于你之前选择的 `Ingress-NGINX 版本`。使用应用程序版本，选择一个 Chart 版本，该版本打包了与你的 Kubernetes 兼容的应用程序。例如，如果使用的是 Kubernetes v1.24，则可以选择 v4.6.0 Helm Chart，因为 Ingress-NGINX v1.7.0 与该 Chart 打包在一起，而 v1.7.0 与 Kubernetes v1.24 兼容。如有疑问，请选择最新的兼容版本。 + +了解你需要的 Helm chart `版本`后，运行以下命令。它安装一个带有 Kubernetes 负载均衡器服务的 `nginx-ingress-controller`： + +``` +helm search repo ingress-nginx -l +helm upgrade --install \ + ingress-nginx ingress-nginx/ingress-nginx \ + --namespace ingress-nginx \ + --set controller.service.type=LoadBalancer \ + --set controller.service.annotations."service\.beta\.kubernetes\.io/azure-load-balancer-health-probe-request-path"=/healthz \ + --set controller.service.externalTrafficPolicy=Local \ + --version 4.6.0 \ + --create-namespace +``` + +## 6. 获取负载均衡器的 IP + +运行以下命令获取负载均衡器的 IP 地址： + +``` +kubectl get service ingress-nginx-controller --namespace=ingress-nginx +``` + +返回的结果应与以下内容类似： + +``` +NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) + AGE +ingress-nginx-controller LoadBalancer 10.0.116.18 40.31.180.83 80:31229/TCP,443:31050/TCP + 67s +``` + +保存 `EXTERNAL-IP`。 + +## 7. 设置 DNS + +到 Rancher Server 的外部流量需要重定向到你创建的负载均衡器。 + +创建指向你保存的 `EXTERNAL-IP` 的 DNS。这个 DNS 会用作 Rancher Server 的 URL。 + +设置 DNS 的有效方法有很多。如需获取帮助，请参见 [Azure DNS 文档中心](https://docs.microsoft.com/en-us/azure/dns/)。 + +## 8. 安装 Rancher Helm Chart + +按照[本页](install-upgrade-on-a-kubernetes-cluster.md#安装-rancher-helm-chart)的说明安装 Rancher Helm Chart。任何 Kubernetes 发行版上安装的 Rancher 的 Helm 说明都是一样的。 + +安装 Rancher 时，使用上一步获取的 DNS 名称作为 Rancher Server 的 URL。它可以作为 Helm 选项传递进来。例如，如果 DNS 名称是 `rancher.my.org`，你需要使用 `--set hostname=rancher.my.org` 选项来运行 Helm 安装命令。 + +在此设置之上安装 Rancher 时，你还需要将以下值传递到 Rancher Helm 安装命令，以设置与 Rancher 的 Ingress 资源一起使用的 Ingress Controller 的名称： + +``` +--set ingress.ingressClassName=nginx +``` + +请参阅[Helm 安装命令](install-upgrade-on-a-kubernetes-cluster.md#5-根据你选择的证书选项通过-helm-安装-rancher)了解你的证书选项。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/rancher-on-amazon-eks.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/rancher-on-amazon-eks.md new file mode 100644 index 00000000000..efc95fe7e13 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/rancher-on-amazon-eks.md @@ -0,0 +1,151 @@ +--- +title: 在 Amazon EKS 上安装 Rancher +--- + +本文介绍了如何在 Amazon EKS 集群上安装 Rancher。你也可以[通过 AWS Marketplace 安装 Rancher](../../quick-start-guides/deploy-rancher-manager/aws-marketplace.md)。 + +如果你已经有一个 EKS Kubernetes 集群，请直接跳转到[安装 Ingress](#5-安装-ingress)这个步骤。然后按照[此处](install-upgrade-on-a-kubernetes-cluster.md#安装-rancher-helm-chart)的步骤安装 Rancher Helm Chart。 + +## 为 Rancher Server 创建 EKS 集群 + +在本节中，你将使用命令行工具安装一个带有 Ingress 的 EKS 集群。如果你想在 EKS 上使用 Rancher 时使用较少的资源，请使用此方法。 + +:::note 先决条件： + +- 已有一个 AWS 账户。 +- 建议使用 IAM 用户而不是 AWS 根账户。你将需要 IAM 用户的访问密钥 (access key) 和密文秘钥 (secret key) 来配置 AWS 命令行界面。 +- IAM 用户需要具备[eksctl 文档](https://eksctl.io/usage/minimum-iam-policies/)中描述的最低 IAM 策略。 + +::: + +### 1. 准备你的工作站 + +在工作站上安装以下命令行工具： + +- **AWS CLI v2**：如需获取帮助，请参见[安装步骤](https://docs.aws.amazon.com/cli/latest/userguide/install-cliv2.html)。 +- **eksctl**：如需获取帮助，请参见[安装步骤](https://docs.aws.amazon.com/eks/latest/userguide/eksctl.html)。 +- **kubectl**：如需获得帮助，请参见[安装步骤](https://docs.aws.amazon.com/eks/latest/userguide/install-kubectl.html)。 +- **helm**：如需获取帮助，请参见[安装步骤](https://helm.sh/docs/intro/install/)。 + +### 2. 配置 AWS CLI + +运行以下命令，配置 AWS CLI： + +``` +aws configure +``` + +输入以下参数： + +| 值 | 描述 | +|-------|-------------| +| AWS Access Key ID | 具有 EKS 权限的 IAM 用户的访问密钥凭证。 | +| AWS Secret Access Key | 具有 EKS 权限的 IAM 用户的密文密钥凭证。 | +| Default region name | 集群节点所在的 [AWS 区域](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/Concepts.RegionsAndAvailabilityZones.html#Concepts.RegionsAndAvailabilityZones.Regions)。 | +| Default output format | 输入 `json`。 | + +### 3. 创建 EKS 集群 + +运行以下命令创建一个 EKS 集群。使用适用于你的用例的 AWS 区域。在选择 Kubernetes 版本时，请务必先查阅[支持矩阵](https://rancher.com/support-matrix/)，以找出已针对你的 Rancher 版本验证的最新 Kubernetes 版本。 + +**注意**：如果你要从旧的 Kubernetes 版本更新到 Kubernetes v1.22 或更高版本，你还需要[更新](https://kubernetes.github.io/ingress-nginx/user-guide/k8s-122-migration/) ingress-nginx。 + +``` +eksctl create cluster \ + --name rancher-server \ + --version \ + --region us-west-2 \ + --nodegroup-name ranchernodes \ + --nodes 3 \ + --nodes-min 1 \ + --nodes-max 4 \ + --managed +``` + +使用 CloudFormation 进行的集群部署可能需要一些时间才能完成。 + +### 4. 测试集群 + +运行以下命令测试集群： + +``` +eksctl get cluster +``` + +返回的结果应与以下内容类似： + +``` +eksctl get cluster +2021-03-18 15:09:35 [ℹ] eksctl version 0.40.0 +2021-03-18 15:09:35 [ℹ] using region us-west-2 +NAME REGION EKSCTL CREATED +rancher-server-cluster us-west-2 True +``` + +### 5. 安装 Ingress + +集群需要一个 Ingress，以从集群外部访问 Rancher。 + +为确保你选择了正确的 Ingress-NGINX Helm Chart，首先在 [Kubernetes/ingress-nginx 支持表](https://github.com/kubernetes/ingress-nginx#supported-versions-table)中找到与你的 Kubernetes 版本兼容的 `Ingress-NGINX 版本`。 + +然后，运行以下命令列出可用的 Helm Chart： + +``` +helm repo add ingress-nginx https://kubernetes.github.io/ingress-nginx +helm repo update +helm search repo ingress-nginx -l +``` + +`helm search` 命令的输出包含一个 `APP VERSION` 列。此列下的版本等同于你之前选择的 `Ingress-NGINX 版本`。使用应用程序版本，选择一个 Chart 版本，该版本打包了与你的 Kubernetes 兼容的应用程序。例如，如果使用的是 Kubernetes v1.23，则可以选择 v4.6.0 Helm Chart，因为 Ingress-NGINX v1.7.0 与该 Chart 打包在一起，而 v1.7.0 与 Kubernetes v1.23 兼容。如有疑问，请选择最新的兼容版本。 + +了解你需要的 Helm chart `版本`后，运行以下命令。它安装一个带有 Kubernetes 负载均衡器服务的 `nginx-ingress-controller`： + +``` +helm upgrade --install \ + ingress-nginx ingress-nginx/ingress-nginx \ + --namespace ingress-nginx \ + --set controller.service.type=LoadBalancer \ + --version 4.6.0 \ + --create-namespace +``` + +### 6. 获取负载均衡器的 IP + +运行以下命令获取负载均衡器的 IP 地址： + +``` +kubectl get service ingress-nginx-controller --namespace=ingress-nginx +``` + +返回的结果应与以下内容类似： + +``` +NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) + AGE +ingress-nginx-controller LoadBalancer 10.100.90.18 a904a952c73bf4f668a17c46ac7c56ab-962521486.us-west-2.elb.amazonaws.com 80:31229/TCP,443:31050/TCP + 27m +``` + +保存 `EXTERNAL-IP`。 + +### 7. 设置 DNS + +到 Rancher Server 的外部流量需要重定向到你创建的负载均衡器。 + +创建指向你保存的外部 IP 地址的 DNS。这个 DNS 会用作 Rancher Server 的 URL。 + +设置 DNS 的有效方法有很多。如需获得帮助，请参见 AWS 文档中心的[转发流量到 ELB 负载均衡器](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/routing-to-elb-load-balancer.html)。 + +### 8. 安装 Rancher Helm Chart + +按照[本页](install-upgrade-on-a-kubernetes-cluster.md#安装-rancher-helm-chart)的说明安装 Rancher Helm Chart。任何 Kubernetes 发行版上安装的 Rancher 的 Helm 说明都是一样的。 + +安装 Rancher 时，使用上一步获取的 DNS 名称作为 Rancher Server 的 URL。它可以作为 Helm 选项传递进来。例如，如果 DNS 名称是 `rancher.my.org`，你需要使用 `--set hostname=rancher.my.org` 选项来运行 Helm 安装命令。 + +在此设置之上安装 Rancher 时，你还需要将以下值传递到 Rancher Helm 安装命令，以设置与 Rancher 的 Ingress 资源一起使用的 Ingress Controller 的名称： + +``` +--set ingress.ingressClassName=nginx +``` + +请参阅[Helm 安装命令](install-upgrade-on-a-kubernetes-cluster.md#5-根据你选择的证书选项通过-helm-安装-rancher)了解你的证书选项。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/rancher-on-gke.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/rancher-on-gke.md new file mode 100644 index 00000000000..a16c142b6bc --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/rancher-on-gke.md @@ -0,0 +1,201 @@ +--- +title: 在 GKE 集群上安装 Rancher +--- + +在本节中，你将学习如何使用 GKE 安装 Rancher。 + +如果你已经有一个 GKE Kubernetes 集群，请直接跳转到[安装 Ingress](#7-安装-ingress)这个步骤。然后按照[此处](install-upgrade-on-a-kubernetes-cluster.md#安装-rancher-helm-chart)的步骤安装 Rancher Helm Chart。 + +## 先决条件 + +- 你需要有一个 Google 账号。 +- 你需要有一个 Google Cloud Billing 账号。你可使用 Google Cloud Console 来管理你的 Cloud Billing 账号。有关 Cloud Console 的详情，请参见 [ Console 通用指南](https://support.google.com/cloud/answer/3465889?hl=en&ref_topic=3340599)。 +- 你需要至少一个在用的 IP 地址和至少 2 个 CPU 的云配额。有关 Rancher Server 的硬件要求，请参见[本节](../installation-requirements/installation-requirements.md)。 + +## 1. 启用 Kubernetes Engine API + +按照以下步骤启用 Kubernetes Engine API： + +1. 访问 Google Cloud Console 中的 [Kubernetes Engine 页面](https://console.cloud.google.com/projectselector/kubernetes?_ga=2.169595943.767329331.1617810440-856599067.1617343886)。 +1. 创建或选择一个项目。 +1. 打开项目，并为项目启用 Kubernetes Engine API。等待 API 和相关服务的启用。这可能需要几分钟时间。 +1. 确保为你的云项目启用了计费。有关如何为你的项目启用计费，请参见 [Google Cloud 文档中心](https://cloud.google.com/billing/docs/how-to/modify-project#enable_billing_for_a_project)。 + +## 2. 打开 Cloud Shell + +Cloud Shell 是一个 shell 环境，用于管理托管在 Google Cloud 上的资源。Cloud Shell 预装了 `gcloud` 命令行工具和 kubectl 命令行工具中。`gcloud` 工具为 Google Cloud 提供主要的命令行界面，而`kubectl` 则提供针对 Kubernetes 集群的主要命令行界面。 + +下文描述了如何从 Google Cloud Console 或从本地工作站启动 Cloud Shell。 + +### Cloud Shell + +如需从 [Google Cloud Console](https://console.cloud.google.com) 启动 shell，请在控制台的右上角点击终端按钮。鼠标悬停在按钮上时，它会标记为 **Activate Cloud Shell**。 + +### 本地 Shell + +执行以下步骤以安装 `gcloud` 和 `kubectl`： + +1. 按照[这些步骤](https://cloud.google.com/sdk/docs/install)安装 Cloud SDK。The Cloud SDK 包括 `gcloud` 命令行工具。不同操作系统对应的步骤有所不同。 +1. 安装 Cloud SDK 后，运行以下命令以安装 `kubectl` 命令行工具： + + ``` + gcloud components install kubectl + ``` + 后面的步骤会配置 `kubectl`，使其用于使用新的 GKE 集群。 +1. 如果 Helm 3 未安装的话，[安装 Helm 3](https://helm.sh/docs/intro/install/)。 +1. 使用 `HELM_EXPERIMENTAL_OCI` 变量来启用 Helm 的实验功能 [OCI 镜像支持](https://github.com/helm/community/blob/master/hips/hip-0006.md)。把以下行添加到 `~/.bashrc` （或 macOS 中的 `~/.bash_profile`，或者你的 shell 存储环境变量的地方）： + + ``` + export HELM_EXPERIMENTAL_OCI=1 + ``` +1. 运行以下命令来加载你更新的 `.bashrc` 文件： + + ``` + source ~/.bashrc + ``` + 如果你运行的是 macOS，使用这个命令: + ``` + source ~/.bash_profile + ``` + + + +## 3. 配置 gcloud CLI + +选择以下方法之一配置默认的 gcloud 设置： + +- 如果你想了解默认值，请使用 gcloud init。 +- 如需单独设置你的项目 ID、地区和区域，使用 gcloud config。 + + + + +1. 运行 gcloud init 并按照指示操作： + + ``` + gcloud init + ``` + 如果你在远程服务器上使用 SSH，使用 --console-only 标志，以防止该命令启动浏览器。 + + ``` + gcloud init --console-only + ``` +2. 按照指示，以授权 gcloud 使用你的 Google Cloud 账户，并选择你创建的新项目。 + + + + + + + +## 4. 确认 gcloud 的配置是否正确 + +运行： + +``` +gcloud config list +``` + +返回的结果应与以下内容类似： + +``` +[compute] +region = us-west1 # Your chosen region +zone = us-west1-b # Your chosen zone +[core] +account = +disable_usage_reporting = True +project = + +Your active configuration is: [default] +``` + +## 5. 创建一个 GKE 集群 + +下面的命令创建了一个三节点的集群。 + +把 `cluster-name` 替换为你新集群的名称。 + +在选择 Kubernetes 版本时，请务必先查阅[支持矩阵](https://rancher.com/support-matrix/)，以找出已针对你的 Rancher 版本验证的最新 Kubernetes 版本。 + +要使用 Rancher 成功创建 GKE 集群，GKE 必须处于 Standard 模式。GKE 在创建 Kubernetes 集群时有两种运行模式，分别是 Autopilot 和 Standard 模式。Autopilot 模式的集群配置对编辑 kube-system 命名空间有限制。但是，Rancher 在安装时需要在 kube-system 命名空间中创建资源。因此，你将无法在以 Autopilot 模式创建的 GKE 集群上安装 Rancher。如需详细了解 GKE Autopilot 模式和 Standard 模式之间的差异，请访问[比较 GKE Autopilot 和 Standard ](https://cloud.google.com/kubernetes-engine/docs/resources/autopilot-standard-feature-comparison)。 + +**注意**：如果你要从旧的 Kubernetes 版本更新到 Kubernetes v1.22 或更高版本，你还需要[更新](https://kubernetes.github.io/ingress-nginx/user-guide/k8s-122-migration/) ingress-nginx。 + +``` +gcloud container clusters create cluster-name --num-nodes=3 --cluster-version= +``` + +## 6. 获取验证凭证 + +创建集群后，你需要获得认证凭证才能与集群交互： + +``` +gcloud container clusters get-credentials cluster-name +``` + +此命令将 `kubectl` 配置成使用你创建的集群。 + +## 7. 安装 Ingress + +集群需要一个 Ingress，以从集群外部访问 Rancher。 + +以下命令安装带有 LoadBalancer 服务的 `nginx-ingress-controller`： + +``` +helm repo add ingress-nginx https://kubernetes.github.io/ingress-nginx +helm repo update +helm upgrade --install \ + ingress-nginx ingress-nginx/ingress-nginx \ + --namespace ingress-nginx \ + --set controller.service.type=LoadBalancer \ + --version 4.0.18 \ + --create-namespace +``` + +## 8. 获取负载均衡器的 IP + +运行以下命令获取负载均衡器的 IP 地址： + +``` +kubectl get service ingress-nginx-controller --namespace=ingress-nginx +``` + +返回的结果应与以下内容类似： + +``` +NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE +ingress-nginx-controller LoadBalancer 10.3.244.156 35.233.206.34 80:31876/TCP,443:32497/TCP 81s +``` + +保存 `EXTERNAL-IP`。 + +## 9. 设置 DNS + +到 Rancher Server 的外部流量需要重定向到你创建的负载均衡器。 + +创建指向你保存的外部 IP 地址的 DNS。这个 DNS 会用作 Rancher Server 的 URL。 + +设置 DNS 的有效方法有很多。如需获取帮助，请参见 Google Cloud 文档中的[管理 DNS 记录](https://cloud.google.com/dns/docs/records)部分。 + +## 10. 安装 Rancher Helm Chart + +按照[本页](./install-upgrade-on-a-kubernetes-cluster.md#安装-rancher-helm-chart)的说明安装 Rancher Helm Chart。任何 Kubernetes 发行版上安装的 Rancher 的 Helm 说明都是一样的。 + +安装 Rancher 时，使用上一步获取的 DNS 名称作为 Rancher Server 的 URL。它可以作为 Helm 选项传递进来。例如，如果 DNS 名称是 `rancher.my.org`，你需要使用 `--set hostname=rancher.my.org` 选项来运行 Helm 安装命令。 + +在此设置之上安装 Rancher 时，你还需要设置与 Rancher 的 Ingress 资源一起使用的 Ingress Controller 的名称： + +``` +--set ingress.ingressClassName=nginx +``` + +请参阅[Helm 安装命令](./install-upgrade-on-a-kubernetes-cluster.md#5-根据你选择的证书选项通过-helm-安装-rancher)了解你的证书选项。 + +在 Rancher v2.7.5 中，如果你打算在集群上使用默认的 GKE Ingress 而不启用 VPC 原生的集群模式，则需要设置以下标志： + +``` +--set service.type=NodePort +``` + +此设置是必要的，这考虑了与 ClusterIP（`cattle-system/rancher` 的默认类型）之间的兼容性问题。 \ No newline at end of file diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/rancher-psact.yaml b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/rancher-psact.yaml new file mode 100644 index 00000000000..ae248cc9b7c --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/rancher-psact.yaml @@ -0,0 +1,37 @@ +apiVersion: apiserver.config.k8s.io/v1 +kind: AdmissionConfiguration +plugins: +- configuration: + apiVersion: pod-security.admission.config.k8s.io/v1 + defaults: + audit: restricted + audit-version: latest + enforce: restricted + enforce-version: latest + warn: restricted + warn-version: latest + exemptions: + namespaces: + - ingress-nginx + - kube-system + - cattle-system + - cattle-epinio-system + - cattle-fleet-system + - longhorn-system + - cattle-neuvector-system + - cattle-monitoring-system + - rancher-alerting-drivers + - cis-operator-system + - cattle-csp-adapter-system + - cattle-externalip-system + - cattle-gatekeeper-system + - istio-system + - cattle-istio-system + - cattle-logging-system + - cattle-windows-gmsa-system + - cattle-sriov-system + - cattle-ui-plugin-system + - tigera-operator + kind: PodSecurityConfiguration + name: PodSecurity + path: "" \ No newline at end of file diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/rollbacks.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/rollbacks.md new file mode 100644 index 00000000000..98fc3420220 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/rollbacks.md @@ -0,0 +1,154 @@ +--- +title: 回滚 +--- + +本页概述了如何在升级 Rancher 后将 Rancher 回滚到之前的版本。 + +请在以下情况时按照本页的说明进行操作： +- 正在运行的 Rancher 实例在备份完成后升级到了更新的版本。 +- 上游（本地）集群与进行备份的集群相同。 + +:::tip + +* [请参阅这些步骤来迁移 Rancher](../../../how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/migrate-rancher-to-new-cluster.md). +* 如果你需要还原 Rancher 到同一版本的之前的状态, 请参阅[还原 Rancher](../../../how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/restore-rancher.md). + +::: + +## 特殊场景下的操作 + +在以下场景中需要执行替代步骤来进行回滚： +- 从 v2.6.4 及更高版本回滚到 v2.6.x 的早期版本。 +- 从 v2.7.7 及更高版本回滚到 v2.7.x 的早期版本。 + +Rancher v2.6.4 将 cluster-api 模块从 v0.4.4 升级到 v1.0.2。反过来，cluster-api 的 v1.0.2 版本将集群 API 的自定义资源定义 (CRD) 从 `cluster.x-k8s.io/v1alpha4` 升级到 `cluster.x-k8s.io/v1beta1`。当你尝试将 Rancher v2.6.4 回滚到以前版本的 Rancher v2.6.x 时，CRD 升级到 v1beta1 会导致回滚失败。这是因为使用旧 apiVersion (v1alpha4) 的 CRD 与 v1beta1 不兼容。 + +在 Rancher v2.7.7 版本中，应用 `rancher-provisioning-capi` 会自动安装在上游（本地）集群上，来替代嵌入的 cluster-api 控制器。 如果上游集群同时包含该应用和 Rancher v2.7.6 及更早版本，则会发生冲突和意外错误。 因此，如果你尝试从 Rancher v2.7.7 回滚到 Rancher v2.7.x 的任何早期版本，需要执行替代的步骤。 + +### 步骤 1： 清理上游（本地）集群 + +要避免回滚失败，你需要在尝试恢复操作或回滚**之前**根据该[说明](https://github.com/rancher/rancher-cleanup/blob/main/README.md)运行以下 Rancher 脚本： + + +* `cleanup.sh`：清理集群。 +* `verify.sh`：检查集群中是否有任何与 Rancher 相关的资源。 + + +:::caution + +`cleanup.sh` 运行的时候会有停机时间，这是因为脚本会删除 Rancher 创建的资源。 + +::: + +**结果：** 上游（本地）集群中所有 Rancher 关联的资源将被清理。 + +请参阅 [rancher/rancher-cleanup 仓库](https://github.com/rancher/rancher-cleanup) 以获取更多细节和源码。 + +### 步骤 2： 还原备份并启动 Rancher + +此时上游集群上应该已经没有 Rancher 相关的资源了。 因此，下一步与将 Rancher 迁移到不包含 Rancher 资源的新集群相同。 + +按照[说明](../../../how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/migrate-rancher-to-new-cluster.md)安装 Rancher-Backup Helm Chart 并恢复 Rancher 到之前的状态。请记住： +1. 步骤 3 可以跳过，因为之前安装的 Cert-Manager 应用应该还在上游（本地）集群中。 +2. 执行到步骤 4 时，在要回滚到的 local 集群上安装你需要的 Rancher 版本。 + +## 回滚到 Rancher 2.5.0+ + +要回滚到 Rancher 2.5.0+，使用 **Rancher 备份**应用并通过备份来恢复 Rancher。 + +回滚后，Rancher 必须以较低/较早的版本启动。 + +还原是通过创建 Restore 自定义资源实现的。 + +:::note 重要提示： + +* 请按照此页面上的说明在已备份的同一集群上还原 Rancher。要把 Rancher 迁移到新集群，请参照步骤[迁移 Rancher](../../../how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/migrate-rancher-to-new-cluster.md)。 + +* 在使用相同设置恢复 Rancher 时，Rancher deployment 在恢复开始前被手动缩减，然后 Operator 将在恢复完成后将其缩回。因此，在恢复完成之前，Rancher 和 UI 都将不可用。如果 UI 不可用时，你可使用 `kubectl create -f restore.yaml`YAML 恢复文件来使用初始的集群 kubeconfig。 + +::: + +### 步骤 1 ：创建 Restore 自定义资源 + +1. 点击 **☰ > 集群管理**。 +1. 找到你的本地集群，并点击 **Explore**。 +1. 在左侧导航栏中，点击 **Rancher 备份 > 还原**。 + :::note + + 如果 Rancher Backups 应用不可见，你需要到 **Apps** 的 Charts 页面中安装应用。详情请参见[此处](../../../how-to-guides/new-user-guides/helm-charts-in-rancher/helm-charts-in-rancher.md#访问-charts)。 + + ::: + +1. 单击**创建**。 +1. 使用表单或 YAML 创建 Restore。如需获取使用表单创建 Restore 资源的更多信息，请参见[配置参考](../../../reference-guides/backup-restore-configuration/restore-configuration.md)和[示例](../../../reference-guides/backup-restore-configuration/examples.md)。 +1. 如需使用 YAML 编辑器，点击**创建 > 使用 YAML 文件创建**。然后输入 Restore YAML。以下是 Restore 自定义资源示例： + + ```yaml + apiVersion: resources.cattle.io/v1 + kind: Restore + metadata: + name: restore-migration + spec: + backupFilename: backup-b0450532-cee1-4aa1-a881-f5f48a007b1c-2020-09-15T07-27-09Z.tar.gz + encryptionConfigSecretName: encryptionconfig + storageLocation: + s3: + credentialSecretName: s3-creds + credentialSecretNamespace: default + bucketName: rancher-backups + folder: rancher + region: us-west-2 + endpoint: s3.us-west-2.amazonaws.com + ``` + 如需获得配置 Restore 的帮助，请参见[配置参考](../../../reference-guides/backup-restore-configuration/restore-configuration.md)和[示例](../../../reference-guides/backup-restore-configuration/examples.md)。 + +1. 单击**创建**。 + +**结果**：已创建备份文件并更新到目标存储位置。资源还原顺序如下： + +1. 自定义资源定义（CRD） +2. 集群范围资源 +3. 命名空间资源 + +如需查看还原的处理方式，请检查 Operator 的日志。按照如下步骤获取日志： + +```yaml +kubectl get pods -n cattle-resources-system +kubectl logs -n cattle-resources-system -f +``` + +### 步骤 2：回滚到上一个 Rancher 版本 + +你可以使用 Helm CLI 回滚 Rancher。要回滚到上一个版本： + +```yaml +helm rollback rancher -n cattle-system +``` + +如果你不是想回滚到上一个版本，你也可以指定回滚的版本。查看部署历史记录： + +```yaml +helm history rancher -n cattle-system +``` + +确定目标版本后，执行回滚。此示例回滚到版本 `3`： + +```yaml +helm rollback rancher 3 -n cattle-system +``` + +## 回滚到 Rancher 2.2-2.4 + +要回滚到 2.5 之前的 Rancher 版本，参考此处的步骤[恢复备份 — Kubernetes 安装](https://github.com/rancher/rancher-docs/tree/main/archived_docs/en/version-2.0-2.4/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/restore-rancher-launched-kubernetes-clusters-from-backup.md)。如果恢复 Rancher Server 的集群的某个快照，Rancher 的版本以及状态均会恢复回到快照时的版本和状态。 + +有关回滚 Docker 安装的 Rancher，请参见[本页](../other-installation-methods/rancher-on-a-single-node-with-docker/roll-back-docker-installed-rancher.md)。 + +:::note + +托管集群对其状态具有权威性。因此，恢复 Rancher Server 不会恢复快照后对托管集群进行的工作负载部署或更改。 + +::: + +## 回滚到 Rancher 2.0-2.1 + +我们不再支持回滚到 Rancher 2.0-2.1。回滚到这些版本的说明保留在[此处](https://github.com/rancher/rancher-docs/tree/main/archived_docs/en/version-2.0-2.4/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/restore-rancher-launched-kubernetes-clusters-from-backup/roll-back-to-v2.0-v2.1.md)，仅用于无法升级到 v2.2 的情况。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/troubleshooting.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/troubleshooting.md new file mode 100644 index 00000000000..9a391416f4b --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/troubleshooting.md @@ -0,0 +1,180 @@ +--- +title: Rancher Server Kubernetes 集群的问题排查 +--- + +本文介绍如何对安装在 Kubernetes 集群上的 Rancher 进行故障排除。 + +## 相关命名空间 + +故障排除主要针对以下 3 个命名空间中的对象： + +- `cattle-system`：`rancher` deployment 和 Pod。 +- `ingress-nginx`：Ingress Controller Pod 和 services。 +- `cert-manager`：`cert-manager` Pod。 + +## "default backend - 404" + +很多操作都有可能导致 Ingress Controller 无法将流量转发到你的 Rancher 实例。但是大多数情况下都是由错误的 SSL 配置导致的。 + +检查事项： + +- [Rancher 是否正在运行](#检查-rancher-是否正在运行) +- [证书的 Common Name（CN）是 "Kubernetes Ingress Controller Fake Certificate"](#证书的-cn-是-kubernetes-ingress-controller-fake-certificate) + +## 检查 Rancher 是否正在运行 + +使用 `kubectl` 检查 `cattle-system` 系统命名空间，并查看 Rancher Pod 的状态是否是 **Running**： + +``` +kubectl -n cattle-system get pods + +NAME READY STATUS RESTARTS AGE +pod/rancher-784d94f59b-vgqzh 1/1 Running 0 10m +``` + +如果状态不是 `Running`，在 Pod 上运行 `describe`，并检查 **Events**： + +``` +kubectl -n cattle-system describe pod + +... +Events: + Type Reason Age From Message + ---- ------ ---- ---- ------- + Normal Scheduled 11m default-scheduler Successfully assigned rancher-784d94f59b-vgqzh to localhost + Normal SuccessfulMountVolume 11m kubelet, localhost MountVolume.SetUp succeeded for volume "rancher-token-dj4mt" + Normal Pulling 11m kubelet, localhost pulling image "rancher/rancher:v2.0.4" + Normal Pulled 11m kubelet, localhost Successfully pulled image "rancher/rancher:v2.0.4" + Normal Created 11m kubelet, localhost Created container + Normal Started 11m kubelet, localhost Started container +``` + +## 检查 Rancher 日志 + +使用 `kubectl` 列出 Pod： + +``` +kubectl -n cattle-system get pods + +NAME READY STATUS RESTARTS AGE +pod/rancher-784d94f59b-vgqzh 1/1 Running 0 10m +``` + +使用 `kubectl` 和 Pod 名称列出该 Pod 的日志： + +``` +kubectl -n cattle-system logs -f rancher-784d94f59b-vgqzh +``` + +## 证书的 CN 是 "Kubernetes Ingress Controller Fake Certificate" + +使用浏览器检查证书的详细信息。如果显示 CN 是 "Kubernetes Ingress Controller Fake Certificate"，则说明读取或颁发 SSL 证书时出现了问题。 + +:::note + +如果你使用的是 Let's Encrypt 证书，证书颁发的过程可能需要几分钟。 + +::: + +## 排查 Cert-Manager 颁发的证书（Rancher 或 Let's Encrypt 生成的）问题 + +`cert-manager` 有 3 部分： + +- `cert-manager` 命名空间中的 `cert-manager` Pod。 +- `cattle-system` 命名空间中的 `Issuer` 对象。 +- `cattle-system` 命名空间中的 `Certificate` 对象。 + +往后操作，对每个对象运行 `kubectl describe` 并检查事件。这样，你可以追踪可能丢失的内容。 + +以下是 Issuer 有问题的示例： + +``` +kubectl -n cattle-system describe certificate +... +Events: + Type Reason Age From Message + ---- ------ ---- ---- ------- + Warning IssuerNotReady 18s (x23 over 19m) cert-manager Issuer rancher not ready +``` + +``` +kubectl -n cattle-system describe issuer +... +Events: + Type Reason Age From Message + ---- ------ ---- ---- ------- + Warning ErrInitIssuer 19m (x12 over 19m) cert-manager Error initializing issuer: secret "tls-rancher" not found + Warning ErrGetKeyPair 9m (x16 over 19m) cert-manager Error getting keypair for CA issuer: secret "tls-rancher" not found +``` + +## 排查你自己提供的 SSL 证书问题 + +你的证书直接应用于 `cattle-system` 命名空间中的 Ingress 对象。 + +检查 Ingress 对象的状态，并查看它是否准备就绪： + +``` +kubectl -n cattle-system describe ingress +``` + +如果 Ingress 对象已就绪，但是 SSL 仍然无法正常工作，你的证书或密文的格式可能不正确。 + +这种情况下，请检查 nginx-ingress-controller 的日志。nginx-ingress-controller 的 Pod 中有多个容器，因此你需要指定容器的名称： + +``` +kubectl -n ingress-nginx logs -f nginx-ingress-controller-rfjrq nginx-ingress-controller +... +W0705 23:04:58.240571 7 backend_ssl.go:49] error obtaining PEM from secret cattle-system/tls-rancher-ingress: error retrieving secret cattle-system/tls-rancher-ingress: secret cattle-system/tls-rancher-ingress was not found +``` + +## 没有匹配的 "Issuer" + +你所选的 SSL 配置要求在安装 Rancher 之前先安装 Cert-Manager，否则会出现以下错误: + +``` +Error: validation failed: unable to recognize "": no matches for kind "Issuer" in version "certmanager.k8s.io/v1alpha1" +``` + +在这种情况下，先安装 Cert-Manager，然后再重新安装 Rancher。 + + +## Canal Pod 显示 READY 2/3 + +此问题的最常见原因是端口 8472/UDP 在节点之间未打开。因此，你可以检查你的本地防火墙、网络路由或安全组。 + +解决网络问题后，`canal` Pod 会超时并重启以建立连接。 + +## nginx-ingress-controller Pod 显示 RESTARTS + +此问题的最常见原因是 `canal` pod 未能建立覆盖网络。参见 [canal Pod 显示 READY `2/3`](#canal-pod-显示-ready-23) 进行排查。 + + +## Failed to dial to /var/run/docker.sock: ssh: rejected: administratively prohibited (open failed) + +此错误的原因可能是： + +* 指定连接的用户无权访问 Docker Socket。如果是这个原因，你通过登录主机并运行 `docker ps` 命令来检查： + +``` +$ ssh user@server +user@server$ docker ps +CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES +``` + +如果需要了解如何进行正确设置，请参见[以非 root 用户身份管理 Docker](https://docs.docker.com/install/linux/linux-postinstall/#manage-docker-as-a-non-root-user)。 + +* 你使用的操作系统是 RedHat 或 CentOS：由于 [Bugzilla #1527565](https://bugzilla.redhat.com/show_bug.cgi?id=1527565)，你不能使用 `root` 用户连接到节点。因此，你需要添加一个单独的用户并配置其访问 Docker Socket。如果需要了解如何进行正确设置，请参见[以非 root 用户身份管理 Docker](https://docs.docker.com/install/linux/linux-postinstall/#manage-docker-as-a-non-root-user)。 + +* SSH 服务器版本不是 6.7 或更高版本：高版本是 Socket 转发所必须的，用于通过 SSH 连接到 Docker Socket。你可以在你要连接的主机上使用 `sshd -V` 或使用 netcat 进行检查： +``` +$ nc xxx.xxx.xxx.xxx 22 +SSH-2.0-OpenSSH_6.6.1p1 Ubuntu-2ubuntu2.10 +``` + +## Failed to dial ssh using address [xxx.xxx.xxx.xxx:xx]: ssh: handshake failed: ssh: unable to authenticate, attempted methods [none publickey], no supported methods remain + +`ssh_key_path` 密钥文件不是访问节点的正确文件：请仔细检查，确保你已为节点指定了正确的 `ssh_key_path` 和连接用户。 + +## Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running? + +节点无法通过配置的 `address` 和 `port` 访问。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/upgrades.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/upgrades.md new file mode 100644 index 00000000000..bbe3c786ac9 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/upgrades.md @@ -0,0 +1,202 @@ +--- +title: 升级 +--- + +本文介绍如何升级使用 Helm 安装在 Kubernetes 集群上的 Rancher Server。这些步骤也适用于使用 Helm 进行的离线安装。 + +有关使用 Docker 安装的 Rancher 的升级说明，请参见[本页。](../other-installation-methods/rancher-on-a-single-node-with-docker/upgrade-docker-installed-rancher.md) + +## 先决条件 + +### 访问 Kubeconfig + +Helm 的运行位置，应该与你的 Kubeconfig 文件，或你运行 kubectl 命令的位置相同。 + +If you installed Kubernetes with RKE2/K3s, the Kubeconfig is stored in the `/etc/rancher/rke2/rke2.yaml` or `/etc/rancher/k3s/k3s.yaml` directory depending on your chosen distribution. + +Kubeconfig 也可以通过 `--kubeconfig` 标签（详情请参见 https://helm.sh/docs/helm/helm/ ）来手动指定所需的集群。 + +### 查看已知问题 + +如需查看每个 Rancher 版本的已知问题，请参见 [GitHub](https://github.com/rancher/rancher/releases) 中的发行说明，或查看 [Rancher 论坛](https://forums.rancher.com/c/announcements/12)。 + +不支持 _升级_ 或 _升级到_ [rancher-alpha 仓库](../resources/choose-a-rancher-version.md#helm-chart-仓库)中的任何 Chart。 +### Helm 版本 + +本安装指南假定你使用的是 Helm 3。 + + + +如果你使用 Helm 2，请参见 [Helm 2 迁移到 Helm 3 文档](https://helm.sh/blog/migrate-from-helm-v2-to-helm-v3/)。如果你不能升级到 Helm 3，[Helm 2 升级页面](https://github.com/rancher/rancher-docs/tree/main/archived_docs/en/version-2.0-2.4/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/upgrades/helm2.md) 提供了使用 Helm 2 升级的旧升级指南。 + +### 离线安装：推送镜像到私有镜像仓库 + +[仅适用于离线安装](../other-installation-methods/air-gapped-helm-cli-install/air-gapped-helm-cli-install.md)：为新的 Rancher Server 版本收集和推送镜像。使用你需要针对 Rancher 版本升级的镜像，按照步骤[推送镜像到私有镜像仓库](../other-installation-methods/air-gapped-helm-cli-install/publish-images.md)。 + +### 使用 cert-manager 0.8.0 之前的版本升级 + +[从 2019 年 11 月 1 日开始，Let's Encrypt 已屏蔽早于 0.8.0 的 cert-manager 实例](https://community.letsencrypt.org/t/blocking-old-cert-manager-versions/98753)。因此，请参见[说明](../resources/upgrade-cert-manager.md)把 cert-manager 升级到最新版本。 + +## 升级概要 + +按照以下步骤升级 Rancher Server： + + +### 1. 备份运行 Rancher Server 的 Kubernetes 集群 + +使用[备份应用](../../../how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/back-up-rancher.md)来备份 Rancher。 + +如果升级过程中出现问题，你将使用备份作为还原点。 + +### 2. 更新 Helm Chart 仓库 + +1. 更新本地 Helm 仓库缓存。 + + ``` + helm repo update + ``` + +1. 获取你用来安装 Rancher 的仓库名称。 + + 关于仓库及其区别，请参见 [Helm Chart 仓库](../resources/choose-a-rancher-version.md#helm-chart-仓库)。 + + - Latest：建议用于试用最新功能 + ``` + helm repo add rancher-latest https://releases.rancher.com/server-charts/latest + ``` + - Stable：建议用于生产环境 + ``` + helm repo add rancher-stable https://releases.rancher.com/server-charts/stable + ``` + - Alpha：即将发布的实验性预览。 + ``` + helm repo add rancher-alpha https://releases.rancher.com/server-charts/alpha + ``` + 注意：不支持升级到 Alpha 版、从 Alpha 版升级或在 Alpha 版之间升级。 + + ``` + helm repo list + + NAME URL + stable https://charts.helm.sh/stable + rancher- https://releases.rancher.com/server-charts/ + ``` + + :::note + + 如果你想切换到不同的 Helm Chart 仓库，请按照[切换仓库步骤](../resources/choose-a-rancher-version.md#切换到不同-helm-chart-仓库)进行操作。如果你要切换仓库，请先再次列出仓库，再继续执行步骤 3，以确保添加了正确的仓库。 + + ::: + +1. 从 Helm Chart 仓库获取最新的 Chart 来安装 Rancher。 + + 该命令将提取最新的 Chart，并将其作为 `.tgz`文件保存在当前目录中。 + + ```plain + helm fetch rancher-/rancher + ``` + 你可以通过 `--version=` 标记，来指定要升级的目标 Chart 版本。例如： + + ```plain + helm fetch rancher-/rancher --version=2.6.8 + ``` + +### 3. 升级 Rancher + +本节介绍了如何使用 Helm 升级 Rancher 的一般（互联网连接）或离线安装。 + +:::note 离线说明： + +如果你在离线环境中安装 Rancher，请跳过本页的其余部分，按照[本页](air-gapped-upgrades.md)上的说明渲染 Helm 模板。 + +::: + + +从当前安装的 Rancher Helm Chart 中获取用 `--set`传递的值。 + +``` +helm get values rancher -n cattle-system + +hostname: rancher.my.org +``` + +:::note + +这个命令会列出更多的值。此处展示的只是其中一个值的例子。 + +::: + +:::tip + +Deployment 的名称可能会有所不同。例如，如果你通过 AWS Marketplace 部署 Rancher，则 Deployment 的名称为“rancher-stable”。 +因此： +``` +helm get values rancher-stable -n cattle-system + +hostname: rancher.my.org +``` + +::: + +如果要将 cert-manager 从 v1.5 或更早的版本升级到最新版本，请参阅 [cert-manager upgrade docs](../resources/upgrade-cert-manager.md#选项-c升级-15-及以下版本的-cert-manager) 了解如何在不卸载或重新安装 Rancher 的情况下升级 cert-manager。否则，请按照以下[ Rancher 升级步骤](#rancher-升级步骤)进行操作。 + +#### Rancher 升级步骤 + +保留你的所有设置把 Rancher 升级到最新版本。 + +将上一步中的所有值用 `--set key=value` 追加到命令中。 + +``` +helm upgrade rancher rancher-/rancher \ + --namespace cattle-system \ + --set hostname=rancher.my.org +``` + +:::note + +以上是一个例子，可能有更多上一步的值需要追加。 + +::: + +:::tip + +如果你通过 AWS Marketplace 部署 Rancher，则 Deployment 的名称为“rancher-stable”。 +因此： +``` +helm upgrade rancher-stable rancher-/rancher \ + --namespace cattle-system \ + --set hostname=rancher.my.org +``` + +::: + +另外，你也可以将当前的值导出到一个文件中，并在升级时引用该文件。例如，如果你只需要改变 Rancher 的版本： + +1. 将当前值导出到文件： + ``` + helm get values rancher -n cattle-system -o yaml > values.yaml + ``` +1. 只更新 Rancher 版本： + + ``` + helm upgrade rancher rancher-/rancher \ + --namespace cattle-system \ + -f values.yaml \ + --version=2.6.8 + ``` + +### 4. 验证升级 + +登录 Rancher 以确认升级成功。 + +:::tip + +升级后出现网络问题？ + +请参见[恢复集群网络](https://github.com/rancher/rancher-docs/tree/main/archived_docs/en/version-2.0-2.4/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/upgrades/namespace-migration.md)。 + +::: + +## 已知升级问题 + +你可以在 [GitHub](https://github.com/rancher/rancher/releases) 发布说明以及 [Rancher 论坛](https://forums.rancher.com/c/announcements/12)中找到每个 Rancher 版本的已知问题。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/installation-and-upgrade/installation-and-upgrade.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/installation-and-upgrade/installation-and-upgrade.md new file mode 100644 index 00000000000..aeef9f9c6e7 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/installation-and-upgrade/installation-and-upgrade.md @@ -0,0 +1,94 @@ +--- +title: 安装/升级 Rancher +description: 了解如何在开发和生产环境中安装 Rancher。了解单节点和高可用安装 +--- + +本节介绍了 Rancher 各种安装方式以及每个安装方式的优点。 + +## 名词解释 + +本章节涉及以下名词： + +- **Rancher Server**：用于管理和配置 Kubernetes 集群。你可以通过 Rancher Server 的 UI 与下游 Kubernetes 集群进行交互。Rancher Management Server 可以安装到任意 Kubernetes 集群上，包括托管的集群，如 Amazon EKS 集群。 +- **RKE（Rancher Kubernetes Engine）**：是经过认证的 Kubernetes 发行版，也是用于创建和管理 Kubernetes 集群的 CLI 工具和库。 +- **K3s（轻量级 Kubernetes）**：也是经过认证的 Kubernetes 发行版。它比 RKE 更新，更易用且更轻量，其所有组件都在一个小于 100 MB 的二进制文件中。 +- **RKE2**：一个完全合规的 Kubernetes 发行版，专注于安全和合规性。 + +`restrictedAdmin` Helm Chart 选项在 **Rancher Server** 可用。如果该选项设置为 true，初始的 Rancher 用户访问本地 Kubernetes 集群会受到限制，以避免权限升级。详情请参见 [restricted-admin 角色](../../how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/global-permissions.md#受限管理员)。 + +## 安装方式概述 + +Rancher 可以安装在以下主要架构上： + +### 使用 Helm CLI 安装的高可用 Kubernetes + +我们建议使用 Kubernetes 包管理器 Helm 在专用的 Kubernetes 集群上安装 Rancher。在 RKE 集群中，需要使用三个节点才能实现高可用集群。在 K3s 集群中，只需要两个节点即可。 + +### 通过 AWS Marketplace 在 EKS 上安装 Rancher + +你可以[通过 AWS Marketplace](../quick-start-guides/deploy-rancher-manager/aws-marketplace.md) 将 Rancher 安装到 Amazon Elastic Kubernetes Service (EKS) 上。部署的 EKS 集群已生产就绪，并遵循 AWS 最佳实践。 + +### 单节点 Kubernetes 安装 + +Rancher 可以安装在单节点 Kubernetes 集群上。但是，在单节点安装的情况下，Rancher Server 没有高可用性。而高可用性对在生产环境中运行 Rancher 非常重要。 + +但是，如果你想要短期内使用单节点节省资源，同时又保留高可用性迁移路径，那么单节点 Kubernetes 安装也是合适的。你也可以之后向集群中添加节点，获得高可用的 Rancher Server。 + +### Docker 安装 + +如果你的目的是测试或演示，你可以使用 Docker 把 Rancher 安装到单个节点中。本地 Kubernetes 集群是安装到单个 Docker 容器中的，而 Rancher 是安装到本地集群中的。 + +Rancher backup operator 可将 Rancher 从单个 Docker 容器迁移到高可用 Kubernetes 集群上。详情请参见[把 Rancher 迁移到新集群](../../how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/migrate-rancher-to-new-cluster.md)。 + +### 其他方式 + +如果你需要在离线环境中或使用 HTTP 代理安装 Rancher，请参见以下独立的说明文档： + +| 网络访问方式 | 基于 Kubernetes 安装（推荐） | 基于 Docker 安装 | +| ---------------------------------- | ------------------------------ | ---------- | +| 可直接访问互联网 | [文档](install-upgrade-on-a-kubernetes-cluster/install-upgrade-on-a-kubernetes-cluster.md) | [文档](other-installation-methods/rancher-on-a-single-node-with-docker/rancher-on-a-single-node-with-docker.md) | +| 使用 HTTP 代理 | [文档](other-installation-methods/rancher-behind-an-http-proxy/rancher-behind-an-http-proxy.md) | [文档](other-installation-methods/rancher-on-a-single-node-with-docker/rancher-on-a-single-node-with-docker.md)及[配置](../../reference-guides/single-node-rancher-in-docker/http-proxy-configuration.md) | +| 离线环境 | [文档](other-installation-methods/air-gapped-helm-cli-install/air-gapped-helm-cli-install.md) | [文档](other-installation-methods/air-gapped-helm-cli-install/air-gapped-helm-cli-install.md) | + +我们建议在 Kubernetes 集群上安装 Rancher，因为在多节点集群中，Rancher Server 可以实现高可用。高可用配置可以提升 Rancher 访问其管理的下游 Kubernetes 集群的稳定性。 + +因此，我们建议在生产级别的架构中，设置一个高可用的 Kubernetes 集群，然后在这个集群上安装 Rancher。安装 Rancher 后，你可以使用 Rancher 部署和管理 Kubernetes 集群。 + +如果你的目的是测试或演示，你可以将 Rancher 安装到单个 Docker 容器中。Docker 安装可以让你实现开箱即用，以使用 Rancher 设置 Kubernetes 集群。Docker 安装主要是用于探索 Rancher Server 的功能，只适用于开发和测试。 + +[在 Kubernetes 上安装 Rancher 的说明](install-upgrade-on-a-kubernetes-cluster/install-upgrade-on-a-kubernetes-cluster.md)介绍了如何首先使用 K3s 或 RKE 创建和管理 Kubernetes 集群，然后再将 Rancher 安装到该集群上。 + +如果 Kubernetes 集群中的节点正在运行且满足[节点要求](installation-requirements/installation-requirements.md)，你可以使用 Helm 将 Rancher 部署到 Kubernetes 上。Helm 使用 Rancher 的 Helm Chart 在 Kubernetes 集群的每个节点上安装 Rancher 的副本。我们建议使用负载均衡器将流量定向到集群中的每个 Rancher 副本上。 + +如需进一步了解 Rancher 架构，请参见[架构概述](../../reference-guides/rancher-manager-architecture/rancher-manager-architecture.md)，[生产级别架构推荐](../../reference-guides/rancher-manager-architecture/architecture-recommendations.md)或[最佳实践指南](../../reference-guides/best-practices/rancher-server/tips-for-running-rancher.md)。 + +## 先决条件 + +安装 Rancher 之前，请确保你的节点满足所有[安装要求](installation-requirements/installation-requirements.md)。 + +## 架构建议 + +为了达到最佳性能和安全性，我们建议你为 Rancher Management Server 使用单独的专用 Kubernetes 集群。不建议在此集群上运行用户工作负载。部署 Rancher 后，你可以[创建或导入集群](../../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/kubernetes-clusters-in-rancher-setup.md)来运行你的工作负载。 + +详情请参见[架构推荐](../../reference-guides/rancher-manager-architecture/architecture-recommendations.md)。 + +### 在 Kubernetes 上安装 Rancher 的更多选项 + +参见 [Helm Chart 选项](installation-references/helm-chart-options.md)以了解在 Kubernetes 集群上安装 Rancher 的其他配置，包括： + +- [开启 API 审计日志来记录所有事务](installation-references/helm-chart-options.md#api-审计日志) +- [负载均衡器上的 TLS 终止](installation-references/helm-chart-options.md#外部-tls-终止) +- [自定义 Ingress](installation-references/helm-chart-options.md#自定义-ingress) + +在 Rancher 的安装指南中，我们推荐使用 K3s 或 RKE 来配置 Kubernetes 集群，然后再在这个集群中安装 Rancher。K3s 和 RKE 均提供许多配置选项，用于为你的具体环境自定义 Kubernetes 集群。有关选项和功能的完整列表，请参见： + +- [RKE 配置选项](https://rancher.com/docs/rke/latest/en/config-options/) +- [K3s 配置选项](https://rancher.com/docs/k3s/latest/en/installation/install-options/) + +### 在 Docker 上安装 Rancher 的更多选项 + +参见 [Docker 安装选项](other-installation-methods/rancher-on-a-single-node-with-docker/rancher-on-a-single-node-with-docker.md)了解其他配置，包括： + +- [开启 API 审计日志来记录所有事务](../../reference-guides/single-node-rancher-in-docker/advanced-options.md#api-审计日志) +- [外部负载均衡器](../../how-to-guides/advanced-user-guides/configure-layer-7-nginx-load-balancer.md) +- [持久化数据存储](../../reference-guides/single-node-rancher-in-docker/advanced-options.md#持久化数据) diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/installation-and-upgrade/installation-references/feature-flags.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/installation-and-upgrade/installation-references/feature-flags.md new file mode 100644 index 00000000000..e37a3d976da --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/installation-and-upgrade/installation-references/feature-flags.md @@ -0,0 +1,43 @@ +--- +title: 功能开关 +--- + +使用功能开关（Feature Flag），你可以试用可选或实验性的功能并启用正在逐步淘汰的旧版功能。 + +要了解功能的值以及如何启用它们，请参阅[启用实验性功能](../../../how-to-guides/advanced-user-guides/enable-experimental-features/enable-experimental-features.md)。 + +:::note + +某些功能要求重新启动 Rancher 容器。Rancher UI 中标记了要求重启的功能。 + +::: + +以下是 Rancher 中可用的功能开关列表。如果你是从旧 Rancher 版本升级的，你可能会在 Rancher UI 中看到其他功能，例如 `proxy` 或 `dashboard`（均[已中断](https://github.com/rancher/rancher-docs/tree/main/archived_docs/en/version-2.5/reference-guides/installation-references/feature-flags.md)）： + +- `clean-stale-secrets`: Removes stale secrets from the `cattle-impersonation-system` namespace. This slowly cleans up old secrets which are no longer being used by the impersonation system. +- `continuous-delivery`：允许从 Fleet 中单独禁用 Fleet GitOps。有关详细信息，请参阅[持续交付](../../../how-to-guides/advanced-user-guides/enable-experimental-features/continuous-delivery.md)。 +- `fleet`：v2.6 及更高版本的 Rancher 配置框架需要 Fleet。即使你在旧 Rancher 版本中禁用了该标志，该标志也将在升级时自动启用。有关详细信息，请参阅 [Fleet - GitOps at Scale](../../../integrations-in-rancher/fleet/fleet.md)。 +- `harvester`：管理 Virtualization Management 页面的访问。用户可以在该页面直接导航到 Harvester 集群并访问 Harvester UI。有关详细信息，请参阅 [Harvester 集成](../../../integrations-in-rancher/harvester/overview.md)。 +- `istio-virtual-service-ui`：启用[可视界面](../../../how-to-guides/advanced-user-guides/enable-experimental-features/istio-traffic-management-features.md)来创建、读取、更新和删除 Istio 虚拟服务和目标规则，这些都是 Istio 流量管理功能。 +- `legacy`：启用 2.5.x 及更早版本的一组功能，这些功能正逐渐被新的实现淘汰。它们是已弃用以及后续可用于新版本的功能组合。新的 Rancher 安装会默认禁用此标志。如果你从以前版本的 Rancher 升级，此标志会启用。 +- `multi-cluster-management`：允许配置和管理多个 Kubernetes 集群。此标志只能在安装时设置。后续无法启用或禁用它。 +- `rke2`：启用配置 RKE2 集群。此标志默认启用。 +- `token-hashing`：启用令牌哈希。启用后，会使用 SHA256 算法对现有 Token 和所有新 Token 进行哈希处理。一旦对 Token 进行哈希处理，就无法撤消操作。此标志在启用后无法禁用。有关详细信息，请参阅 [API 令牌](../../../api/api-tokens.md#令牌哈希)。 +- `uiextension`: Enables UI extensions. This flag is enabled by default. Enabling or disabling the flag forces the Rancher pod to restart. The first time this flag is set to `true`, it creates a CRD and enables the controllers and endpoints necessary for the feature to work. If set to `false`, it disables the previously mentioned controllers and endpoints. Setting `uiextension` to `false` has no effect on the CRD -- it does not create a CRD if it does not yet exist, nor does it delete the CRD if it already exists. +- `unsupported-storage-drivers`：允许启用非默认启用的存储提供程序和卷插件。有关详细信息，请参阅[允许使用不受支持的存储驱动程序](../../../how-to-guides/advanced-user-guides/enable-experimental-features/unsupported-storage-drivers.md)。 +- `ui-sql-cache`: Enables a SQLite-based cache for UI tables. See [UI Server-Side Pagination](../../../how-to-guides/advanced-user-guides/enable-experimental-features/ui-server-side-pagination.md) for more information. + +下表介绍了 Rancher 中功能开关的可用性和默认值。标记为“GA”的功能已普遍可用： + +| 功能开关名称 | 默认值 | 状态 | 可用于 | +| ----------------------------- | ------------- | ------------ | --------------- | +| `clean-stale-secrets` | `true` | GA | v2.10.2 | | +| `continuous-delivery` | `true` | GA | v2.6.0 | +| `fleet` | `true` | 不能禁用 | v2.6.0 | +| `fleet` | `true` | GA | v2.5.0 | +| `harvester` | `true` | 实验功能 | v2.6.1 | +| `legacy` | 新安装：`false`；升级：`true` | GA | v2.6.0 | +| `rke2` | `true` | 实验功能 | v2.6.0 | +| `token-hashing` | 新安装：`false`；升级：`true` | GA | v2.6.0 | +| `uiextension` | `true` | GA | v2.9.0 | | +| `ui-sql-cache` | `false` | Highly experimental | v2.9.0 | | diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/installation-and-upgrade/installation-references/helm-chart-options.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/installation-and-upgrade/installation-references/helm-chart-options.md new file mode 100644 index 00000000000..b6349b27b75 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/installation-and-upgrade/installation-references/helm-chart-options.md @@ -0,0 +1,308 @@ +--- +title: Rancher Helm Chart 选项 +keywords: [rancher helm chart, rancher helm 选项, rancher helm chart 选项, helm chart rancher, helm 选项 rancher, helm chart 选项 rancher] +--- + +本文提供了 Rancher Helm Chart 的配置参考。 + +如需选择 Helm Chart 版本，请参见[本页](../../../getting-started/installation-and-upgrade/resources/choose-a-rancher-version.md)。 + +了解开启实验性功能的详情，请参见[本页](../../../how-to-guides/advanced-user-guides/enable-experimental-features/enable-experimental-features.md)。 + +## 常用选项 + +| 选项 | 默认值 | 描述 | +| ------------------------- | ------------- | ---------------------------------------------------------------------------------- | +| `bootstrapPassword` | " " | `string` - 为第一个管理员用户设置[引导密码](#引导密码)。登录后，管理员需要重置密码。如不设置，会使用随机生成的引导密码。 | +| `hostname` | " " | `string` - 你的 Rancher Server 的完全限定的域名（FQDN) | +| `ingress.tls.source` | "rancher" | `string` - 从哪里获取 Ingress 的证书- "rancher, letsEncrypt, secret" | +| `letsEncrypt.email` | " " | `string` - 你的邮箱地址 | +| `letsEncrypt.environment` | "production" | `string` - 可选项："staging, production" | +| `privateCA` | false | `bool` - 如果你的证书是由私有 CA 签发的，把这个值设置为 true | + +
+ +## 高级选项 + +| 选项 | 默认值 | 描述 | +| ------------------------------ | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | +| `additionalTrustedCAs` | false | `bool` - 请参见[额外的授信 CA](#额外的授信-ca) | +| `addLocal` | "true" | `string` - 让 Rancher 检测并导入 “local” Rancher Server 集群。_注意：此选项在 2.5.0 中已不可用。你可考虑使用 `restrictedAdmin` 选项，来避免用户修改本地集群。_ | +| `antiAffinity` | "preferred" | `string` - Rancher Pod 的反亲和性规则 - "preferred, required" | +| `auditLog.destination` | "sidecar" | `string` - 发送审计日志到 Sidecar 容器的控制台或 hostPath 卷 - "sidecar, hostPath" | +| `auditLog.hostPath` | "/var/log/rancher/audit" | `string` - 主机上的日志文件目标地址（仅当`auditLog.destination` 的值是 `hostPath` 时生效） | +| `auditLog.level` | 0 | `int` - 设置 [API 审计日志](../../../how-to-guides/advanced-user-guides/enable-api-audit-log.md)等级。0 代表关闭。[0-3] | +| `auditLog.maxAge` | 1 | `int` - 旧审计日志文件最多可保留的天数（仅当`auditLog.destination` 的值是 `hostPath` 时生效） | +| `auditLog.maxBackup` | 1 | `int` - 审计文件最大可保留的个数（仅当 `auditLog.destination` 的值是 `hostPath` 时生效） | +| `auditLog.maxSize` | 100 | `int` - 在审计日志被轮换前的最大容量，单位是 MB（仅当 `auditLog.destination` 的值是 `hostPath` 时生效） | +| `auditLog.image.repository` | "registry.suse.com/bci/bci-micro" | `string` - 用于收集审计日志的镜像的位置。 | +| `auditLog.image.tag` | "15.4.14.3" | `string` - 用于收集审计日志的镜像的标签。 | +| `auditLog.image.pullPolicy` | "IfNotPresent" | `string` - 覆盖 auditLog 镜像的 imagePullPolicy - “Always”、“Never”、“IfNotPresent”。 | +| `busyboxImage` | "" | `string` - 用于收集审计日志的 busybox 镜像位置。_注意：此选项已弃用，请使用 `auditLog.image.repository` 来控制审计 sidecar 镜像_。 | +| `certmanager.version` | "" | `string` - 设置 cert-manager compatibility | +| `debug` | false | `bool` - 在 Rancher Server 设置 debug 参数 | +| `extraEnv` | [] | `list` - 为 Rancher 额外设置环境变量 | +| `imagePullSecrets` | [] | `list` - 私有镜像仓库凭证的密文名称列表 | +| `ingress.configurationSnippet` | "" | `string` - 添加额外的 Nginx 配置。可用于代理配置。 | +| `ingress.extraAnnotations` | {} | `map` - 用于自定义 Ingress 的额外注释 | +| `ingress.enabled` | true | 如果值为 false，Helm 不会安装 Rancher Ingress。你可把值设为 false 以部署你自己的 Ingress。 | +| `letsEncrypt.ingress.class` | "" | `string` - cert-manager acmesolver ingress 的可选 ingress 类，用于响应 Let's Encrypt ACME 质询。选项：traefik，nginx。 | | +| `noProxy` | "127.0.0.0/8,10.0.0.0/8,172.16.0.0/12,192.168.0.0/16,.svc,.cluster.local,cattle-system.svc" | `string` - 不使用代理的主机名或 IP 地址的逗号分隔列表 | | +| `proxy` | "" | `string` - 给 Rancher 配置的 HTTP[S] 代理 | +| `rancherImage` | "rancher/rancher" | `string` - Rancher 镜像源 | +| `rancherImagePullPolicy` | "IfNotPresent" | `string` - 覆盖 Rancher Server 镜像的 imagePullPolicy - "Always", "Never", "IfNotPresent" | +| `rancherImageTag` | 和 Chart 版本一致 | `string` - rancher/rancher 镜像标签 | +| `replicas` | 3 | `int` - Rancher Server 副本数。如果设为 -1，会根据集群中的可用节点数自动选择 1，2或3。 | +| `resources` | {} | `map` - Rancher Pod 资源请求和限制 | +| `restrictedAdmin` | `false` | `bool` - 如果值为 true，初始的 Rancher 用户访问本地 Kubernetes 集群会受到限制，以避免权限升级。详情请参见 [restricted-admin 角色](../../../how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/global-permissions.md#受限管理员)。 | +| `systemDefaultRegistry` | "" | `string` - 用于所有系统容器镜像的私有仓库，例如 http://registry.example.com/ | +| `tls` | "ingress" | `string` - 详情请参见[外部 TLS 终止](#外部-tls-终止)。- "ingress, external" | +| `useBundledSystemChart` | `false` | `bool` - 选择 Rancher Server 打包的 system-charts。此参数用于离线环境安装。 | + +### 引导密码 + +Rancher 首次启动时，会为第一个管理员用户随机生成一个密码。当管理员首次登录 Rancher 时，用于获取引导密码（Bootstrap）的命令会在 UI 上显示。管理员需要运行命令并使用引导密码登录。然后 Rancher 会让管理员重置密码。 + +如果你想指定引导密码而不使用随机生成的密码，请参考以下命令设置密码。 + +```plain +--set bootstrapPassword="rancher" +``` + +无论你是使用提供的密码还是生成的密码，密码均存储在 Kubernetes 密文中。安装 Rancher 后，如何使用 kubectl 获取密码的说明将会在 UI 中显示： + +``` +kubectl get secret --namespace cattle-system bootstrap-secret -o go-template='{{ .data.bootstrapPassword|base64decode}}{{ "\n" }}' +``` + +### API 审计日志 + +启用 [API 审计日志](../../../how-to-guides/advanced-user-guides/enable-api-audit-log.md)。 + +你可以像收集其他容器日志一样收集此日志。在 Rancher Server 集群上为 `System` 项目启用 [Logging](../../../integrations-in-rancher/logging/logging.md)。 + +```plain +--set auditLog.level=1 +``` + +默认情况下，启用审计日志会在 Rancher pod 中创建一个 Sidecar 容器。这个容器（`rancher-audit-log`）会把日志流传输到 `stdout`。你可以像收集其他容器日志一样收集此日志。如果你使用 Sidecar 作为审计日志的目标时， `hostPath`，`maxAge`，`maxBackups` 和 `maxSize` 选项不会生效。建议使用你的操作系统或 Docker Daemon 的日志轮换功能来控制磁盘空间的使用。请为 Rancher Server 集群或 System 项目启用 [Logging](../../../integrations-in-rancher/logging/logging.md)。 + +将 `auditLog.destination` 的值设为 `hostPath`，可以将日志转发到与主机系统共享的卷，而不是传输到 Sidecar 容器。如果目标设置为 `hostPath`，你可能需要调整其他 auditLog 参数以进行日志轮换。 + +### 额外设置环境变量 + +你可以使用 `extraEnv` 为 Rancher Server 额外设置环境变量。该列表以 YAML 格式传递给 Rancher 部署，它嵌入在 Rancher 容器的 `env` 下。你可以参考 Kubernetes 文档设置容器环境变量。`extraEnv` 可以使用 [Define Environment Variables for a Container](https://kubernetes.io/docs/tasks/inject-data-application/define-environment-variable-container/#define-an-environment-variable-for-a-container) 中引用的任何键。 + +使用 `name` 和 `value` 键的示例： + +```plain +--set 'extraEnv[0].name=CATTLE_TLS_MIN_VERSION' +--set 'extraEnv[0].value=1.0' +``` + +如果将敏感数据（例如代理认证凭证）作为环境变量的值传递，则强烈建议使用 Secret 引用。这将防止敏感数据在 Helm 或 Rancher 部署中暴露。 + +你可以参考使用 `name`、`valueFrom.secretKeyRef.name` 和 `valueFrom.secretKeyRef.key` 键的示例。详见 [HTTP 代理](#http-代理)中的示例。 + +### TLS 设置 + +当你在 Kubernetes 集群内安装 Rancher 时，TLS 会在集群的 Ingress Controller 上卸载。支持的 TLS 设置取决于使用的 Ingress Controller。 + +参见 [TLS 设置](tls-settings.md)了解更多信息和选项。 + +### 导入 `local` 集群 + +默认情况下，Rancher Server 会检测并导入其所在的 `local` 集群。有权访问 `local` 集群的用户对 Rancher Server 管理的所有集群具有“root”访问权限。 + +:::caution + +如果你关闭 addLocal，大多数 Rancher 2.5 功能都不能使用，包括 EKS Provisioner。 + +::: + +如果这在你的环境中是一个问题，你可以在初始安装时将此选项设置为“false”。 + +此选项仅在首次安装 Rancher 时有效。详情请参见 [Issue 16522](https://github.com/rancher/rancher/issues/16522)。 + +```plain +--set addLocal="false" +``` + +### 自定义 Ingress + +要自定义或使用 Rancher Server 的其他 Ingress，你可以设置自己的 Ingress 注释。 + +设置自定义证书颁发者的示例： + +```plain +--set ingress.extraAnnotations.'cert-manager\.io/cluster-issuer'=issuer-name +``` + +以下是使用 `ingress.configurationSnippet`设置静态代理标头的示例。该值像模板一样进行解析，因此可以使用变量。 + +```plain +--set ingress.configurationSnippet='more_set_input_headers X-Forwarded-Host {{ .Values.hostname }};' +``` + +### HTTP 代理 + +Rancher 的一些功能（Helm Chart）需要使用互联网才能使用。你可以使用 `proxy` 设置代理服务器，或使用 `extraEnv` 设置 `HTTPS_PROXY` 环境变量来指向代理服务器。 + +将要排除的 IP 使用逗号分隔列表添加到 `noProxy` Chart value 中。确保添加了以下值： +- Pod 集群 IP 范围（默认值：`10.42.0.0/16`）。 +- Service Cluster IP 范围（默认值：`10.43.0.0/16`）。 +- 内部集群域（默认值：`.svc,.cluster.local`）。 +- 任何 Worker 集群 `controlplane` 节点。 + Rancher 支持在此列表中使用 CIDR 表示法来表示范围。 + +不包括敏感数据时，可以使用 `proxy` 或 `extraEnv` Chart 选项。使用 `extraEnv` 时将忽略 `noProxy` Helm 选项。因此，`NO_PROXY` 环境变量也必须设置为 `extraEnv`。 + +以下是使用 `proxy` Chart 选项设置代理的示例： + +```plain +--set proxy="http:///" +``` + +使用 `extraEnv` Chart 选项设置代理的示例： +```plain +--set extraEnv[1].name=HTTPS_PROXY +--set extraEnv[1].value="http://:/" +--set extraEnv[2].name=NO_PROXY +--set extraEnv[2].value="127.0.0.0/8\,10.0.0.0/8\,172.16.0.0/12\,192.168.0.0/16\,.svc\,.cluster.local" +``` + +包含敏感数据（例如代理认证凭证）时，请使用 `extraEnv` 选项和 `valueFrom.secretRef` 来防止敏感数据在 Helm 或 Rancher 部署中暴露。 + +下面是使用 `extraEnv` 配置代理的示例。此示例 Secret 在 Secret 的 `"https-proxy-url"` 键中包含 `"http://:@:/"` 值： +```plain +--set extraEnv[1].name=HTTPS_PROXY +--set extraEnv[1].valueFrom.secretKeyRef.name=secret-name +--set extraEnv[1].valueFrom.secretKeyRef.key=https-proxy-url +--set extraEnv[2].name=NO_PROXY +--set extraEnv[2].value="127.0.0.0/8\,10.0.0.0/8\,172.16.0.0/12\,192.168.0.0/16\,.svc\,.cluster.local" +``` + +有关如何配置环境变量的更多信息，请参阅[为容器定义环境变量](https://kubernetes.io/docs/tasks/inject-data-application/define-environment-variable-container/#define-an-environment-variable-for-a-container)。 + +### 额外的授信 CA + +如果你有私有镜像仓库（registries）、应用商店（catalogs）或拦截证书的代理，则可能需要向 Rancher 添加额外的授信 CA。 + +```plain +--set additionalTrustedCAs=true +``` + +创建完 Rancher deployment 后，将 pem 格式的 CA 证书复制到一个名为 `ca-additional.pem` 的文件中，并使用 `kubectl` 在 `cattle-system` 命名空间中创建 `tls-ca-additional` 密文。 + +```plain +kubectl -n cattle-system create secret generic tls-ca-additional --from-file=ca-additional.pem=./ca-additional.pem +``` + +### 私有仓库和离线安装 + +有关使用私有仓库安装 Rancher 的详情，请参见[离线安装](../other-installation-methods/air-gapped-helm-cli-install/air-gapped-helm-cli-install.md)。 + +## 外部 TLS 终止 + +我们建议将负载均衡器配置为 4 层均衡，将普通 80/tcp 和 443/tcp 转发到 Rancher Management 集群节点。集群上的 Ingress Controller 会将端口 80 上的 HTTP 流量重定向到端口 443 上的 HTTPS。 + +你可以在 Rancher 集群（Ingress）外部的 L7 负载均衡器上终止 SSL/TLS。使用 `--set tls=external` 选项，将负载均衡器指向所有 Rancher 集群节点上的端口 HTTP 80。这将在 HTTP 端口 80 上暴露 Rancher 接口。请注意，允许直接连接到 Rancher 集群的客户端不会被加密。如果你选择这样做，我们建议你将网络级别的直接访问限制为仅你的负载均衡器。 + +:::note + +如果你使用的是私有 CA 签名的证书，请添加 `--set privateCA=true` 并参见[添加 TLS 密文 - 使用私有 CA 签名证书](../../../getting-started/installation-and-upgrade/resources/add-tls-secrets.md)，为 Rancher 添加 CA 证书。 + +::: + +你的负载均衡器必须支持长期存在的 Websocket 连接，并且需要插入代理头，以便 Rancher 可以正确传送链接。 + +### 使用 NGINX v0.25 为外部 TLS 配置 Ingress + +在 NGINX 0.25 中，NGINX 关于转发头和外部 TLS 终止的行为[已更改](https://github.com/kubernetes/ingress-nginx/blob/master/Changelog.md#0220)。因此，如果你同时使用 NGINX 0.25 和外部 TLS 终止配置，你必须编辑 `cluster.yml` 来为 Ingress 启用 `use-forwarded-headers` 选项。 + +```yaml +ingress: + provider: nginx + options: + use-forwarded-headers: 'true' +``` + +### 必须的 Header + +- `Host` +- `X-Forwarded-Proto` +- `X-Forwarded-Port` +- `X-Forwarded-For` + +### 建议的超时时间 + +- 读超时：`1800 seconds` +- 写超时：`1800 seconds` +- 连接超时：`30 seconds` + +### 健康检查 + +Rancher 将对 `/healthz` 端点的健康检查响应`200`。 + +### 示例 NGINX 配置 + +此 NGINX 配置已在 NGINX 1.14 上进行了测试。 + +:::caution + +此 NGINX 配置只是一个示例，可能不适合你的环境。如需查阅完整文档，请参见 [NGINX 负载均衡 - HTTP 负载均衡](https://docs.nginx.com/nginx/admin-guide/load-balancer/http-load-balancer/)。 + +::: + +- 将 `IP_NODE1`，`IP_NODE2` 和 `IP_NODE3` 替换为你集群中节点的 IP 地址。 +- 将两处的 `FQDN` 均替换为 Rancher 的 DNS 名称。 +- 把 `/certs/fullchain.pem` 和 `/certs/privkey.pem` 分别替换为服务器证书和服务器证书密钥的位置。 + +``` +worker_processes 4; +worker_rlimit_nofile 40000; + +events { + worker_connections 8192; +} + +http { + upstream rancher { + server IP_NODE_1:80; + server IP_NODE_2:80; + server IP_NODE_3:80; + } + + map $http_upgrade $connection_upgrade { + default Upgrade; + '' close; + } + + server { + listen 443 ssl http2; + server_name FQDN; + ssl_certificate /certs/fullchain.pem; + ssl_certificate_key /certs/privkey.pem; + + location / { + proxy_set_header Host $host; + proxy_set_header X-Forwarded-Proto $scheme; + proxy_set_header X-Forwarded-Port $server_port; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + proxy_pass http://rancher; + proxy_http_version 1.1; + proxy_set_header Upgrade $http_upgrade; + proxy_set_header Connection $connection_upgrade; + # 此项允许执行的 shell 窗口保持开启，最长可达15分钟。不使用此参数的话，默认1分钟后自动关闭。 + proxy_read_timeout 900s; + proxy_buffering off; + } + } + + server { + listen 80; + server_name FQDN; + return 301 https://$server_name$request_uri; + } +} +``` diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/installation-and-upgrade/installation-references/installation-references.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/installation-and-upgrade/installation-references/installation-references.md new file mode 100644 index 00000000000..c2d9035c3cd --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/installation-and-upgrade/installation-references/installation-references.md @@ -0,0 +1,5 @@ +--- +title: 安装参考 +--- + +有关其他安装资源，请参阅以下参考指南：[Rancher Helm Chart 选项](helm-chart-options.md)、[TLS 设置](tls-settings.md)和[功能开关](feature-flags.md)。 \ No newline at end of file diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/installation-and-upgrade/installation-references/tls-settings.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/installation-and-upgrade/installation-references/tls-settings.md new file mode 100644 index 00000000000..d8ad91b7d67 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/installation-and-upgrade/installation-references/tls-settings.md @@ -0,0 +1,21 @@ +--- +title: TLS 设置 +--- + +更改默认 TLS 设置的方法取决于它的安装方式。 + +## 在高可用 Kubernetes 集群中运行 Rancher + +当你在 Kubernetes 集群内安装 Rancher 时，TLS 会在集群的 Ingress Controller 上卸载。可用的 TLS 设置取决于使用的 Ingress Controller： + +* nginx-ingress-controller（default RKE2 默认）：[默认的 TLS 版本和密码](https://kubernetes.github.io/ingress-nginx/user-guide/tls/#default-tls-version-and-ciphers)。 +* traefik（K3s 默认）：[TLS 选项](https://doc.traefik.io/traefik/https/tls/#tls-options)。 + +## 在单个 Docker 容器中运行 Rancher + +默认 TLS 配置仅支持 TLS 1.2 和安全的 TLS 密码套件。你可以通过设置以下环境变量来更改此配置： + +| 参数 | 描述 | 默认 | 可用选项 | +|-----|-----|-----|-----| +| `CATTLE_TLS_MIN_VERSION` | 最小 TLS 版本 | `1.2` | `1.0`, `1.1`, `1.2`, `1.3` | +| `CATTLE_TLS_CIPHERS` | 支持的 TLS 密码套件 | `TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256`,
`TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384`,
`TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305`,
`TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256`,
`TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384`,
`TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305` | 详情请参见 [Golang TLS 常量](https://golang.org/pkg/crypto/tls/#pkg-constants)。 | diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/installation-and-upgrade/installation-requirements/installation-requirements.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/installation-and-upgrade/installation-requirements/installation-requirements.md new file mode 100644 index 00000000000..4658305a80d --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/installation-and-upgrade/installation-requirements/installation-requirements.md @@ -0,0 +1,187 @@ +--- +title: 安装要求 +description: Learn the node requirements for each node running Rancher server when you’re configuring Rancher to run either in a Kubernetes setup +--- + +本文描述了对需要安装 Rancher Server 的节点的软件、硬件和网络要求。Rancher Server 可以安装在单个节点或高可用的 Kubernetes 集群上。 + +:::note 重要提示： + +如果你需要在 Kubernetes 集群上安装 Rancher，该节点的要求与用于运行应用和服务的[下游集群的节点要求](../../../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/node-requirements-for-rancher-managed-clusters.md)不同。 + +::: + +Rancher UI 在基于 Firefox 或 Chromium 的浏览器（Chrome、Edge、Opera、Brave）中效果最佳。 + +查看我们的[最佳实践](../../../reference-guides/best-practices/rancher-server/tips-for-running-rancher.md)页面，获取在生产环境中运行 Rancher Server 的建议。 + +## Kubernetes 与 Rancher 的兼容性 + +Rancher 需要安装在支持的 Kubernetes 版本上。请查阅 [Rancher 支持矩阵](https://www.suse.com/suse-rancher/support-matrix/all-supported-versions)，确保你的 Kubernetes 版本受支持。 + +## 在安全加固的 Kubernetes 集群上安装 Rancher + +如果你在安全加固的 Kubernetes 集群上安装 Rancher，请查看[豁免必须的 Rancher 命名空间](../../../how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/psa-config-templates.md#豁免必须的-rancher-命名空间)以了解详细的要求。 + +## 操作系统和容器运行时要求 + +所有支持的操作系统都使用 64-bit x86 架构。Rancher 兼容当前所有的主流 Linux 发行版。 + +The [Rancher support matrix](https://www.suse.com/suse-rancher/support-matrix/all-supported-versions) lists which OS versions were tested for each Rancher version. + +运行 RKE 集群的节点需要安装 Docker。RKE2 或 K3s 集群不需要它。 + +请安装 `ntp`（Network Time Protocol），以防止在客户端和服务器之间由于时间不同步造成的证书验证错误。 + +某些 Linux 发行版的默认防火墙规则可能会阻止 Kubernetes 集群内的通信。从 Kubernetes v1.19 开始，你必须关闭 firewalld，因为它与 Kubernetes 网络插件冲突。 + +如果你不太想这样做的话，你可以查看[相关问题](https://github.com/rancher/rancher/issues/28840)中的建议。某些用户已能成功[使用 ACCEPT 策略 为 Pod CIDR 创建一个独立的 firewalld 区域](https://github.com/rancher/rancher/issues/28840#issuecomment-787404822)。 + +如果你需要在 ARM64 上使用 Rancher，请参见[在 ARM64（实验功能）上运行 Rancher](../../../how-to-guides/advanced-user-guides/enable-experimental-features/rancher-on-arm64.md)。 + +### RKE2 要求 + +对于容器运行时，RKE2 附带了自己的 containerd. + +如需了解 RKE2 通过了哪些操作系统版本的测试，请参见 [Rancher 支持矩阵](https://www.suse.com/suse-rancher/support-matrix/all-supported-versions)。 + + +### K3s 要求 + +对于容器运行时，K3s 默认附带了自己的 containerd。你也可以将 K3s 配置为使用已安装的 Docker 运行时。有关在 Docker 中使用 K3s 的更多信息，请参阅 [K3s 文档](https://docs.k3s.io/advanced#using-docker-as-the-container-runtime)。 + +Rancher 需要安装在支持的 Kubernetes 版本上。如需了解你使用的 Rancher 版本支持哪些 Kubernetes 版本，请参见 [Rancher 支持矩阵](https://www.suse.com/suse-rancher/support-matrix/all-supported-versions)。如需指定 K3s 版本，在运行 K3s 安装脚本时，使用 `INSTALL_K3S_VERSION` 环境变量。 + +如果你使用 **Raspbian Buster** 在 K3s 集群上安装 Rancher，请按照[这些步骤](https://rancher.com/docs/k3s/latest/en/advanced/#enabling-legacy-iptables-on-raspbian-buster)切换到旧版 iptables。 + +如果你使用 Alpine Linux 的 K3s 集群上安装 Rancher，请按照[这些步骤](https://rancher.com/docs/k3s/latest/en/advanced/#additional-preparation-for-alpine-linux-setup)进行其他设置。 + +### RKE 要求 + +RKE 需要 Docker 容器运行时。支持的 Docker 版本请参见 [Rancher 支持矩阵](https://www.suse.com/suse-rancher/support-matrix/all-supported-versions) + +有关详细信息，请参阅[安装 Docker](install-docker.md)。 + +## 硬件要求 + +本节描述安装 Rancher Server 的节点的 CPU、内存和磁盘要求。硬件要求根据你的 Rancher 部署规模而定。 + +### 实际考虑 + +Rancher 的硬件占用空间取决于许多因素，包括： + + - 托管的基础设施规模 (例如： 节点数量，集群数量)。 + - 所需访问控制规则的复杂性（例如：RoleBinding 对象计数）。 + - 工作负载数量 (例如： Kubernetes 部署，Fleet 部署)。 + - 使用模式 (例如：主动使用的功能集合，使用频率，并发用户数量). + +由于存在许多可能随时间变化的影响因素，因此此处列出的要求为适合大多数用例的起点。 然而，你的用例可能有不同的要求。 若你需要对于特定场景的咨询，请[联系 Rancher](https://rancher.com/contact/) 以获得进一步指导。 + + +特别指出，本页面中的要求基于以下假设的环境提出，包括： + - 每种类型的 Kubernetes 资源数量小于 60,000 个。 + - 每个节点最多 120 个 Pod。 + - 上游（本地）集群中最多 200 个 CRD。 + - 下游集群中最多 100 个 CRD。 + - 最多 50 个 Fleet 部署。 + +更多的数量也是能够达到的，但需要更高的硬件要求。 如果你有超过 20,000 个相同类型的资源，通过 Rancher UI 加载整个列表的时间可能需要几秒钟。 + +:::note Evolution: + +Rancher 的代码库不断发展，用例不断变化，Rancher 积累的经验也在不断增长。 + +随着指导方针的准确性不断的提高并且变得更加具体，硬件要求也会发生变化。 + +如果你发现你的 Rancher 部署不再符合列出的建议，请[联系 Rancher](https://rancher.com/contact/) 进行重新评估。 + +::: + +### RKE2 Kubernetes + +下面的表格列出了[上游集群](../install-upgrade-on-a-kubernetes-cluster/install-upgrade-on-a-kubernetes-cluster.md)中每个节点最小的 CPU 和内存要求。 + +请注意，生产环境下的高可用安装最少需要 3 个节点。 + +| 部署规模 | 最大集群数量 | 最大节点数量 | vCPUs | 内存 | +| --------------- | -------- | --------- | ----- | ---- | +| 小 | 150 | 1500 | 4 | 16 GB | +| 中 | 300 | 3000 | 8 | 32 GB | +| 大 (*) | 500 | 5000 | 16 | 64 GB | +| 更大 (†) | (†) | (†) | (†) | (†) | + +(*)： 大规模的部署需要你[遵循最佳实践](../../../reference-guides/best-practices/rancher-server/tuning-and-best-practices-for-rancher-at-scale.md)以获得足够的性能。 + +(†)： 通过特别的硬件建议和调整能够实现更大的部署规模。 你可以[联系 Rancher](https://rancher.com/contact/) 进行定制评估。 + +有关 RKE2 一般要求的更多详细信息，请参见 [RKE2 文档](https://docs.rke2.io/install/requirements)。 + +### K3s Kubernetes + +下面的表格列出了[上游集群](../install-upgrade-on-a-kubernetes-cluster/install-upgrade-on-a-kubernetes-cluster.md)中每个节点最小的 CPU 和内存要求。 + +请注意，生产环境下的高可用安装最少需要 3 个节点。 + +| 部署规模 | 最大集群数量 | 最大节点数量 | vCPUs | 内存 | 外部数据库(*) | +| --------------- | ---------- | ------------ | -------| ---------| ------------------------- | +| Small | 150 | 1500 | 4 | 16 GB | 2 vCPUs, 8 GB + 1000 IOPS | +| Medium | 300 | 3000 | 8 | 32 GB | 4 vCPUs, 16 GB + 2000 IOPS | +| Large (†) | 500 | 5000 | 16 | 64 GB | 8 vCPUs, 32 GB + 4000 IOPS | + +(*)：外部数据库是指将 K3s 集群数据存储在[专用的外部主机](https://docs.k3s.io/datastore)上。 这是可选的。 具体要求取决于使用的外部数据库。 + +(†)：大规模的部署需要你[遵循最佳实践](../../../reference-guides/best-practices/rancher-server/tuning-and-best-practices-for-rancher-at-scale.md)以获得足够的性能。 + +有关 K3s 一般要求的更多详细信息，请参见 [K3s 文档](https://docs.k3s.io/installation/requirements)。 + +### 托管 Kubernetes + +下面的表格列出了[上游集群](../install-upgrade-on-a-kubernetes-cluster/install-upgrade-on-a-kubernetes-cluster.md)中每个节点最小的 CPU 和内存要求。 + +请注意，生产环境下的高可用安装最少需要 3 个节点。 + +这些要求适用于托管 Kubernetes 集群，例如 Amazon Elastic Kubernetes Service (EKS)、Azure Kubernetes Service (AKS) 或 Google Kubernetes Engine (GKE)。 它们不适用于 Rancher SaaS 解决方案，例如 [Rancher Prime Hosted](https://www.rancher.com/products/rancher)。 + +| 部署规模 | 最大集群数量 | 最大节点数量 | vCPUs | 内存 | +|-----------------------------|----------------------------|-------------------------|-------|-------| +| 小 | 150 | 1500 | 4 | 16 GB | +| 中 | 300 | 3000 | 8 | 32 GB | +| 大 (*) | 500 | 5000 | 16 | 64 GB | + +(*)：大规模的部署需要你[遵循最佳实践](../../../reference-guides/best-practices/rancher-server/tuning-and-best-practices-for-rancher-at-scale.md)以获得足够的性能。 + +## Ingress + +安装 Rancher 的 Kubernetes 集群中的每个节点都应该运行一个 Ingress。 + +Ingress 需要部署为 DaemonSet 以确保负载均衡器能成功把流量转发到各个节点。 + +如果是 RKE2 和 K3s 安装，你不需要手动安装 Ingress，因为它是默认安装的。 + +对于托管的 Kubernetes 集群（EKS、GKE、AKS），你需要设置 Ingress。 + +- **Amazon EKS**：[在 Amazon EKS 上安装 Rancher 以及如何安装 Ingress 以访问 Rancher Server](../install-upgrade-on-a-kubernetes-cluster/rancher-on-amazon-eks.md)。 +- **AKS**：[使用 Azure Kubernetes 服务安装 Rancher 以及如何安装 Ingress 以访问 Rancher Server](../install-upgrade-on-a-kubernetes-cluster/rancher-on-aks.md)。 +- **GKE**：[使用 GKE 安装 Rancher 以及如何安装 Ingress 以访问 Rancher Server](../install-upgrade-on-a-kubernetes-cluster/rancher-on-gke.md)。 + +## 磁盘 + +etcd 在集群中的性能决定了 Rancher 的性能。因此，为了获得最佳速度，我们建议使用 SSD 磁盘来支持 Rancher 管理的 Kubernetes 集群。在云提供商上，你还需使用能获得最大 IOPS 的最小大小。在较大的集群中，请考虑使用专用存储设备存储 etcd 数据和 wal 目录。 + +## 网络要求 + +本节描述了安装 Rancher Server 的节点的网络要求。 + +:::caution + +如果包含 Rancher 的服务器带有 `X-Frame-Options=DENY` 标头，在升级旧版 UI 之后，Rancher UI 中的某些页面可能无法渲染。这是因为某些旧版页面在新 UI 中是以 iFrames 模式嵌入的。 + +::: + +### 节点 IP 地址 + +无论你是在单个节点还是高可用集群上安装 Rancher，每个节点都应配置一个静态 IP。如果使用 DHCP，则每个节点都应该有一个 DHCP 预留，以确保节点分配到相同的 IP 地址。 + +### 端口要求 + +为了确保能正常运行，Rancher 需要在 Rancher 节点和下游 Kubernetes 集群节点上开放一些端口。不同集群类型的 Rancher 和下游集群的所有必要端口，请参见[端口要求](port-requirements.md)。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/installation-and-upgrade/installation-requirements/port-requirements.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/installation-and-upgrade/installation-requirements/port-requirements.md new file mode 100644 index 00000000000..eb127681b42 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/installation-and-upgrade/installation-requirements/port-requirements.md @@ -0,0 +1,295 @@ +--- +title: 端口要求 +description: 了解 Rancher 正常运行所需的端口要求，包括 Rancher 节点和下游 Kubernetes 集群节点 +--- + +import PortsIaasNodes from '@site/src/components/PortsIaasNodes' +import PortsCustomNodes from '@site/src/components/PortsCustomNodes' +import PortsImportedHosted from '@site/src/components/PortsImportedHosted' + +为了确保能正常运行，Rancher 需要在 Rancher 节点和下游 Kubernetes 集群节点上开放一些端口。 + +## Rancher 节点 + +下表列出了运行 Rancher Server 的节点之间需要开放的端口。 + +不同的 Rancher Server 架构有不同的端口要求。 + +Rancher 可以安装在任何 Kubernetes 集群上。如果你的 Rancher 安装在 K3s 或 RKE2 Kubernetes 集群上，请参考下面的标签页。对于其他 Kubernetes 发行版，请参见该发行版的文档，了解集群节点的端口要求。 + +:::note 注意事项： + +- Rancher 节点可能要求额外出站访问已配置的外部验证提供程序（如 LDAP）。 +- Kubernetes 建议节点端口服务使用 TCP 30000-32767。 +- 对于防火墙，可能需要在集群和 Pod CIDR 内启用流量。 +- Rancher 节点可能还需要出站访问用于存储集群备份（如 Minio）的外部 S3 上的位置。 + +::: + +### K3s 上 Rancher Server 节点的端口 + +
+ 单击展开 + +K3s server 需要开放端口 6443 才能供节点访问。 + +使用 Flannel VXLAN 时，节点需要能够通过 UDP 端口 8472 访问其他节点。节点不应监听任何其他端口。K3s 使用反向隧道，建立节点与 Server 的出站连接，所有 kubelet 流量都通过该隧道进行。但是，如果你不使用 Flannel，而是使用自定义的 CNI，K3s 则不需要打开 8472 端口。 + +如果要使用 Metrics Server，则需要在每个节点上打开端口 10250。 + +:::note 重要提示： + +节点上的 VXLAN 端口会开放集群网络，让任何人均能访问集群。因此，不要将 VXLAN 端口暴露给外界。请使用禁用 8472 端口的防火墙/安全组来运行节点。 + +::: + +下表描述了入站和出站流量的端口要求： + +
Rancher Server 节点的入站规则
+ +| 协议 | 端口 | 源 | 描述 | +|-----|-----|----------------|---| +| TCP | 80 | 执行外部 SSL 终止的负载均衡器/代理 | 使用外部 SSL 终止时的 Rancher UI/API | +| TCP | 443 |
  • Server 节点
  • Agent 节点
  • 托管/注册的 Kubernetes
  • 任何需要使用 Rancher UI 或 API 的源
| Rancher Agent，Rancher UI/API，kubectl | +| TCP | 6443 | K3s Server 节点 | Kubernetes API | +| UDP | 8472 | K3s Server 和 Agent 节点 | 仅 Flannel VXLAN 需要 | +| TCP | 10250 | K3s Server 和 Agent 节点 | kubelet | + +
Rancher 节点的出站规则
+ +| 协议 | 端口 | 目标 | 描述 | +| -------- | ---- | -------------------------------------------------------- | --------------------------------------------- | +| TCP | 22 | 使用 Node Driver 创建的节点的任何节点 IP | 使用 Node Driver SSH 配置节点 | +| TCP | 443 | git.rancher.io | Rancher catalog | +| TCP | 2376 | 使用 Node Driver 创建的节点的任何节点 IP | Docker Machine 使用的 Docker daemon TLS 端口 | +| TCP | 6443 | 托管/导入的 Kubernetes API | Kubernetes API Server | + +
+ +### RKE2 上 Rancher Server 节点的端口 + +
+ 单击展开 + +RKE2 server 需要开放端口 6443 和 9345 才能供集群中的其他节点访问。 + +使用 Flannel VXLAN 时，所有节点都需要能够通过 UDP 端口 8472 访问其他节点。 + +如果要使用 Metrics Server，则需要在每个节点上打开端口 10250。 + +:::note 重要提示： + +节点上的 VXLAN 端口会开放集群网络，让任何人均能访问集群。因此，不要将 VXLAN 端口暴露给外界。请使用禁用 8472 端口的防火墙/安全组来运行节点。 + +::: + +
RKE2 Server 节点的入站规则
+ +| 协议 | 端口 | 源 | 描述 | +|-----|-----|----------------|---| +| TCP | 9345 | RKE2 Server 和 Agent 节点 | 节点注册。需要在所有 Server 节点上将端口开放给集群中的所有其他节点。 | +| TCP | 6443 | RKE2 Agent 节点 | Kubernetes API | +| UDP | 8472 | RKE2 Server 和 Agent 节点 | 仅 Flannel VXLAN 需要 | +| TCP | 10250 | RKE2 Server 和 Agent 节点 | kubelet | +| TCP | 2379 | RKE2 Server 节点 | etcd 客户端端口 | +| TCP | 2380 | RKE2 Server 节点 | etcd 对等端口 | +| TCP | 30000-32767 | RKE2 Server 和 Agent 节点 | NodePort 端口范围。可以使用 TCP 或 UDP。 | +| TCP | 5473 | Calico-node pod 连接到 typha pod | 使用 Calico 部署时需要 | +| HTTP | 80 | 执行外部 SSL 终止的负载均衡器/代理 | 使用外部 SSL 终止时的 Rancher UI/API | +| HTTPS | 443 |
  • 托管/注册的 Kubernetes
  • 任何需要使用 Rancher UI 或 API 的源
| Rancher Agent，Rancher UI/API，kubectl。如果负载均衡器执行 TLS 终止，则不需要。 | + +所有出站流量通常都是允许的。 +
+ +### Docker 安装的 Rancher Server 的端口 + +
+ 单击展开 + +下表描述了 Rancher 节点入站和出站流量的端口要求： + +
Rancher 节点的入站规则
+ +| 协议 | 端口 | 源 | 描述 | +|-----|-----|----------------|---| +| TCP | 80 | 执行外部 SSL 终止的负载均衡器/代理 | 使用外部 SSL 终止时的 Rancher UI/API | +| TCP | 443 |
  • 托管/注册的 Kubernetes
  • 任何需要使用 Rancher UI 或 API 的源
| Rancher Agent，Rancher UI/API，kubectl | + +
Rancher 节点的出站规则
+ +| 协议 | 端口 | 源 | 描述 | +|-----|-----|----------------|---| +| TCP | 22 | 使用 Node Driver 创建的节点的任何节点 IP | 使用 Node Driver SSH 配置节点 | +| TCP | 443 | git.rancher.io | Rancher catalog | +| TCP | 2376 | 使用 Node Driver 创建的节点的任何节点 IP | Docker Machine 使用的 Docker daemon TLS 端口 | +| TCP | 6443 | 托管/导入的 Kubernetes API | Kubernetes API Server | + +
+ +## 下游 Kubernetes 集群节点 + +下游 Kubernetes 集群用于运行你的应用和服务。本节介绍了哪些端口需要在下游集群的节点上打开，以便 Rancher 能够与它们进行通信。 + +不同的下游集群的启动方式有不同的端口要求。下面的每个标签都列出了不同[集群类型](../../../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/kubernetes-clusters-in-rancher-setup.md)所需打开的端口。 + +下图描述了为每个[集群类型](../../../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/kubernetes-clusters-in-rancher-setup.md)打开的端口。 + +
Rancher 管理面板的端口要求
+ +![基本端口要求](/img/port-communications.svg) + +:::tip + +如果你对安全性的关注不是太高，而且也愿意多打开几个端口，你可以参考[常用端口](#常用端口)中列出的端口，而不是参考下方的表格。 + +::: + +### Harvester 集群的端口 + +有关 Harvester 端口要求的更多信息，请参阅[此处](../../../integrations-in-rancher/harvester.md#端口要求)。 + + +### Rancher 使用节点池启动 Kubernetes 集群的端口 + +
+ 单击展开 + +下表描述了节点在[云提供商](../../../how-to-guides/new-user-guides/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/use-new-nodes-in-an-infra-provider.md)中创建的情况下，[Rancher 启动 Kubernetes](../../../how-to-guides/new-user-guides/launch-kubernetes-with-rancher/launch-kubernetes-with-rancher.md) 的端口要求。 + +:::note + +在 AWS EC2 或 DigitalOcean 等云提供商中创建集群期间，Rancher 会自动打开所需的端口。 + +::: + + + +
+ +### Rancher 使用自定义节点启动 Kubernetes 集群的端口 + +
+ 单击展开 + +下表描述了使用[自定义节点](../../../reference-guides/cluster-configuration/rancher-server-configuration/use-existing-nodes/use-existing-nodes.md)的情况下，[Rancher 启动 Kubernetes](../../../how-to-guides/new-user-guides/launch-kubernetes-with-rancher/launch-kubernetes-with-rancher.md) 的端口要求。 + + + +
+ +### 托管 Kubernetes 集群的端口 + +
+ 单击展开 + +下表描述了[托管集群](../../../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-clusters-from-hosted-kubernetes-providers/set-up-clusters-from-hosted-kubernetes-providers.md)的端口要求。 + + + +
+ +### 已注册集群的端口 + +:::note + +在 Rancher 2.5 之前，注册集群被称为导入集群。 + +::: + +
+ 单击展开 + +下表描述了[注册集群](../../../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/register-existing-clusters.md)的端口要求。 + + + +
+ + +## 其他端口注意事项 + +### 常用端口 + +无论集群是什么类型，常用端口通常在你的 Kubernetes 节点上打开。 + +import CommonPortsTable from '../../../shared-files/_common-ports-table.md'; + + + +---- + +### 本地节点流量 + +上述要求中标记为`本地流量`（例如 `9099 TCP`）的端口会用于 Kubernetes 健康检查 （`livenessProbe` 和 `readinessProbe`）。 +这些健康检查是在节点本身执行的。在大多数云环境中，这种本地流量是默认允许的。 + +但是，在以下情况下可能会阻止此流量： + +- 你已在节点上应用了严格的主机防火墙策略。 +- 你正在使用有多个接口（多宿主）的节点。 + +在这些情况下，你必须在你的主机防火墙中主动允许这种流量，如果是公共/私有云托管的主机（例如 AWS 或 OpenStack），你需要在你的安全组配置中主动允许此流量。请记住，如果你在安全组中使用安全组作为源或目标，主动开放端口只适用于节点/实例的私有接口。 + +### Rancher AWS EC2 安全组 + +当你使用 [AWS EC2 Node Driver](../../../how-to-guides/new-user-guides/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/create-an-amazon-ec2-cluster.md) 在 Rancher 中配置集群节点时，你可以让 Rancher 创建一个名为 `rancher-nodes` 的安全组。以下规则会自动添加到该安全组中。 + +| 类型 | 协议 | 端口范围 | 源/目标 | 规则类型 | +|-----------------|:--------:|:-----------:|------------------------|:---------:| +| SSH | TCP | 22 | 0.0.0.0/0 | 入站 | +| HTTP | TCP | 80 | 0.0.0.0/0 | 入站 | +| 自定义 TCP 规则 | TCP | 443 | 0.0.0.0/0 | 入站 | +| 自定义 TCP 规则 | TCP | 2376 | 0.0.0.0/0 | 入站 | +| 自定义 TCP 规则 | TCP | 2379-2380 | sg-xxx (rancher-nodes) | 入站 | +| 自定义 UDP 规则 | UDP | 4789 | sg-xxx (rancher-nodes) | 入站 | +| 自定义 TCP 规则 | TCP | 6443 | 0.0.0.0/0 | 入站 | +| 自定义 UDP 规则 | UDP | 8472 | sg-xxx (rancher-nodes) | 入站 | +| 自定义 TCP 规则 | TCP | 10250-10252 | sg-xxx (rancher-nodes) | 入站 | +| 自定义 TCP 规则 | TCP | 10256 | sg-xxx (rancher-nodes) | 入站 | +| 自定义 TCP 规则 | TCP | 30000-32767 | 0.0.0.0/0 | 入站 | +| 自定义 UDP 规则 | UDP | 30000-32767 | 0.0.0.0/0 | 入站 | +| 所有流量 | 全部 | 全部 | 0.0.0.0/0 | 出站 | + +### 打开 SUSE Linux 端口 + +SUSE Linux 可能有一个防火墙，默认情况下会阻止所有端口。要打开将主机添加到自定义集群所需的端口： + + + + +1. SSH 进入实例。 +1. 以文本模式启动 YaST： + ``` + sudo yast2 + ``` + +1. 导航到**安全和用户** > **防火墙** > **区域：公共** > **端口**。要在界面内导航，请参照[说明](https://doc.opensuse.org/documentation/leap/reference/html/book-reference/cha-yast-text.html#sec-yast-cli-navigate)。 +1. 要打开所需的端口，把它们输入到 **TCP 端口** 和 **UDP 端口** 字段。在这个例子中，端口 9796 和 10250 也被打开，用于监控。由此产生的字段应类似于以下内容： + ```yaml + TCP Ports + 22, 80, 443, 2376, 2379, 2380, 6443, 9099, 9796, 10250, 10254, 30000-32767 + UDP Ports + 8472, 30000-32767 + ``` + +1. 所有必须端口都输入后，选择**接受**。 + + + + +1. SSH 进入实例。 +1. 编辑 `/etc/sysconfig/SuSEfirewall2` 并打开所需的端口。在这个例子中，端口 9796 和 10250 也被打开，用于监控。 + ``` + FW_SERVICES_EXT_TCP="22 80 443 2376 2379 2380 6443 9099 9796 10250 10254 30000:32767" + FW_SERVICES_EXT_UDP="8472 30000:32767" + FW_ROUTE=yes + ``` +1. 用新的端口重启防火墙： + ``` + SuSEfirewall2 + ``` + + + + +**结果** ：该节点已打开添加到自定义集群所需的端口。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/installation-and-upgrade/other-installation-methods/air-gapped-helm-cli-install/air-gapped-helm-cli-install.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/installation-and-upgrade/other-installation-methods/air-gapped-helm-cli-install/air-gapped-helm-cli-install.md new file mode 100644 index 00000000000..2f2b9ba1b28 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/installation-and-upgrade/other-installation-methods/air-gapped-helm-cli-install/air-gapped-helm-cli-install.md @@ -0,0 +1,31 @@ +--- +title: 离线 Helm CLI 安装 +--- + +本文介绍如何使用 Helm CLI 在离线环境中安装 Rancher Server。离线环境可以是 Rancher Server 离线安装、防火墙后面或代理后面。 + +Rancher 安装在 K3s Kubernetes 集群，或单个 Docker 容器上对应的安装步骤会有所不同。 + +如需了解各个安装方式的更多信息，请参见[本页](../../installation-and-upgrade.md)。 + +在安装指导中，我们为不同的安装选项提供对应的 _选项卡_ 。 + +:::note 重要提示： + +如果你按照 Docker 安装指南安装 Rancher，你将没有把 Docker 安装转换为 Kubernetes 安装的升级途径。 + +::: + +## 安装概要 + +1. [设置基础设施和私有镜像仓库](infrastructure-private-registry.md) +2. [收集镜像到私有镜像仓库](publish-images.md) +3. [设置 Kubernetes 集群（如果你使用 Docker 安装，请跳过此步骤）](install-kubernetes.md) +4. [安装 Rancher](install-rancher-ha.md) + +## 升级 + +如需在离线环境中使用 Helm CLI 升级 Rancher，请按照[升级步骤](../../install-upgrade-on-a-kubernetes-cluster/upgrades.md)进行操作。 + +### 后续操作 +[准备节点](infrastructure-private-registry.md) diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/installation-and-upgrade/other-installation-methods/air-gapped-helm-cli-install/docker-install-commands.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/installation-and-upgrade/other-installation-methods/air-gapped-helm-cli-install/docker-install-commands.md new file mode 100644 index 00000000000..23612291fc0 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/installation-and-upgrade/other-installation-methods/air-gapped-helm-cli-install/docker-install-commands.md @@ -0,0 +1,149 @@ +--- +title: Docker 安装命令 +--- + +Docker 安装适用于想要测试 Rancher 的用户。 + +你可以使用 `docker run`命令，把 Rancher Server 组件安装到单个节点上，而不需要运行 Kubernetes 集群。由于只有一个节点和一个 Docker 容器，因此，如果该节点发生故障，由于其他节点上没有可用的 etcd 数据副本，你将丢失 Rancher Server 的所有数据。 + +你可以使用备份应用，按照[这些步骤](../../../../how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/migrate-rancher-to-new-cluster.md)，将 Rancher Server 从 Docker 安装迁移到 Kubernetes 安装。 + +出于安全考虑，使用 Rancher 时请使用 SSL（Secure Sockets Layer）。SSL 保护所有 Rancher 网络通信（如登录和与集群交互）的安全。 + +| 环境变量键 | 环境变量值 | 描述 | +| -------------------------------- | -------------------------------- | ---- | +| `CATTLE_SYSTEM_DEFAULT_REGISTRY` | `` | 将 Rancher Server 配置成在配置集群时，始终从私有镜像仓库中拉取镜像。 | +| `CATTLE_SYSTEM_CATALOG` | `bundled` | 配置 Rancher Server 使用打包的 Helm System Chart 副本。[system charts](https://github.com/rancher/system-charts) 仓库包含所有 Monitoring，Logging，告警和全局 DNS 等功能所需的应用商店项目。这些 [Helm Chart](https://github.com/rancher/system-charts) 位于 GitHub 中。但是由于你处在离线环境，因此使用 Rancher 内置的 Chart 会比设置 Git mirror 容易得多。 | + +:::note 你是否需要： + +- 配置自定义 CA 根证书以访问服务。参见[自定义 CA 根证书](../../resources/custom-ca-root-certificates.md)。 +- 记录所有 Rancher API 的事务。参见 [API 审计](../../../../reference-guides/single-node-rancher-in-docker/advanced-options.md#api-审计日志)。 + +::: + +选择以下的选项之一： + +## 选项 A：使用 Rancher 默认的自签名证书 + +
+ 单击展开 + +如果你在不考虑身份验证的开发或测试环境中安装 Rancher，可以使用 Rancher 生成的自签名证书安装 Rancher。这种安装方式避免了自己生成证书的麻烦。 + +登录到你的 Linux 主机，然后运行下面的安装命令。输入命令时，参考下表来替换每个占位符。 + +| 占位符 | 描述 | +| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | +| `` | 私有镜像仓库的 URL 和端口。 | +| `` | 你想要安装的 [Rancher 版本](../../installation-references/helm-chart-options.md)的版本标签。 | + +特权访问是[必须](./install-rancher-ha.md#rancher-特权访问)的。 + +``` +docker run -d --restart=unless-stopped \ + -p 80:80 -p 443:443 \ + -e CATTLE_SYSTEM_DEFAULT_REGISTRY= \ # 设置在 Rancher 中使用的默认私有镜像仓库 + -e CATTLE_SYSTEM_CATALOG=bundled \ # 使用打包的 Rancher System Chart + --privileged \ + /rancher/rancher: +``` + +
+ +## 选项 B：使用你自己的证书 - 自签名 + +
+ 单击展开 + +在你团队访问 Rancher Server 的开发或测试环境中，创建一个用于你的安装的自签名证书，以便团队验证他们对实例的连接。 + +:::note 先决条件： + +从能连接到互联网的计算机上，使用 [OpenSSL](https://www.openssl.org/) 或其他方法创建自签名证书。 + +- 证书文件的格式必须是 PEM。 +- 在你的证书文件中，包括链中的所有中间证书。你需要对你的证书进行排序，把你的证书放在最前面，后面跟着中间证书。如需查看示例，请参见[证书故障排除](../rancher-on-a-single-node-with-docker/certificate-troubleshooting.md)。 + +::: + +创建证书后，登录 Linux 主机，然后运行以下安装命令。输入命令时，参考下表来替换每个占位符。使用 `-v` 标志并提供证书的路径，以将证书挂载到容器中。 + +| 占位符 | 描述 | +| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | +| `` | 包含证书文件的目录的路径。 | +| `` | 完整证书链的路径。 | +| `` | 证书私钥的路径。 | +| `` | CA 证书的路径。 | +| `` | 私有镜像仓库的 URL 和端口。 | +| `` | 你想要安装的 [Rancher 版本](../../installation-references/helm-chart-options.md)的版本标签。 | + +特权访问是[必须](./install-rancher-ha.md#rancher-特权访问)的。 + +``` +docker run -d --restart=unless-stopped \ + -p 80:80 -p 443:443 \ + -v //:/etc/rancher/ssl/cert.pem \ + -v //:/etc/rancher/ssl/key.pem \ + -v //:/etc/rancher/ssl/cacerts.pem \ + -e CATTLE_SYSTEM_DEFAULT_REGISTRY= \ # 设置在 Rancher 中使用的默认私有镜像仓库 + -e CATTLE_SYSTEM_CATALOG=bundled \ # 使用打包的 Rancher System Chart + --privileged \ + /rancher/rancher: +``` + +
+ +## 选项 C：使用你自己的证书 - 可信 CA 签名的证书 + +
+ 单击展开 + +在公开暴露应用的开发或测试环境中，请使用由可信 CA 签名的证书，以避免用户收到证书安全警告。 + +:::note 先决条件： + +证书文件的格式必须是 PEM。 + +::: + +获取证书后，登录 Linux 主机，然后运行以下安装命令。输入命令时，参考下表来替换每个占位符。因为你的证书是由可信的 CA 签名的，因此你不需要安装额外的 CA 证书文件。 + +| 占位符 | 描述 | +| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | +| `` | 包含证书文件的目录的路径。 | +| `` | 完整证书链的路径。 | +| `` | 证书私钥的路径。 | +| `` | 私有镜像仓库的 URL 和端口。 | +| `` | 你想要安装的 [Rancher 版本](../../installation-references/helm-chart-options.md)的版本标签。 | + +:::note + +使用 `--no-cacerts` 作为容器的参数，以禁用 Rancher 生成的默认 CA 证书。 + +::: + +特权访问是[必须](./install-rancher-ha.md#rancher-特权访问)的。 + +``` +docker run -d --restart=unless-stopped \ + -p 80:80 -p 443:443 \ + --no-cacerts \ + -v //:/etc/rancher/ssl/cert.pem \ + -v //:/etc/rancher/ssl/key.pem \ + -e CATTLE_SYSTEM_DEFAULT_REGISTRY= \ # 设置在 Rancher 中使用的默认私有镜像仓库 + -e CATTLE_SYSTEM_CATALOG=bundled \ # 使用打包的 Rancher System Chart + --privileged + /rancher/rancher: +``` + +
+ + + +:::note + +如果你不想发送遥测数据，在首次登录时退出[遥测](../../../../faq/telemetry.md)。 + +::: + diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/installation-and-upgrade/other-installation-methods/air-gapped-helm-cli-install/infrastructure-private-registry.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/installation-and-upgrade/other-installation-methods/air-gapped-helm-cli-install/infrastructure-private-registry.md new file mode 100644 index 00000000000..e70759c3f3a --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/installation-and-upgrade/other-installation-methods/air-gapped-helm-cli-install/infrastructure-private-registry.md @@ -0,0 +1,193 @@ +--- +title: '1. 设置基础设施和私有镜像仓库' +--- + +本文介绍如何在离线环境中，为 Rancher Management server 配置底层基础设施。你还将设置 Rancher 节点中必须可用的私有容器镜像仓库。 + +离线环境是 Rancher Server 离线安装或安装在防火墙后面的环境。 + +Rancher 安装在 K3s Kubernetes 集群、RKE Kubernetes 集群还是单个 Docker 容器上对应的基础设施设置会有所不同。如需了解各个安装方式的更多信息，请参见[本页](../../installation-and-upgrade.md)。 + +Rancher 可以安装在任何 Kubernetes 集群上。为了阅读方便，我们在下文中仍提供了 RKE 和 K3s Kubernetes 基础设施教程。 + + + + +为了实现高可用安装，我们建议设置以下的基础设施： + +- **2 个 Linux 节点**：可以是你的云提供商中的虚拟机。 +- **1 个外部数据库**：用于存储集群数据。支持 PostgreSQL, MySQL 和 etcd。 +- **1 个负载均衡器**：用于将流量转发到这两个节点中。 +- **1 个 DNS 记录**：用于将 URL 映射到负载均衡器。此 DNS 记录将成为 Rancher Server 的 URL，下游集群需要可以访问到这个地址。 +- **私有镜像仓库**，用于将容器镜像分发到你的主机。 + +## 1. 配置 Linux 节点 + +这些主机会断开互联网链接，但需要能与你的私有镜像仓库连接。 + +请确保你的节点满足[操作系统，容器运行时，硬件和网络](../../installation-requirements/installation-requirements.md)的常规要求。 + +如需获取配置 Linux 节点的示例，请参见[在 Amazon EC2 中配置节点](../../../../how-to-guides/new-user-guides/infrastructure-setup/nodes-in-amazon-ec2.md)的教程。 + +## 2. 配置外部数据库 + +K3s 与其他 Kubernetes 发行版不同，在于其支持使用 etcd 以外的数据库来运行 Kubernetes。该功能让 Kubernetes 运维更加灵活。你可以根据实际情况选择合适的数据库。 + +对于 K3s 高可用安装，你需要配置以下的其中一个数据库： + +* [PostgreSQL](https://www.postgresql.org/)（10.7 和 11.5 已验证） +* [MySQL](https://www.mysql.com/)（5.7 已验证） +* [etcd](https://etcd.io/)（3.3.15 已验证） + +在安装 Kubernetes 时，你需要传入 K3s 连接数据库的详细信息。 + +如需获取配置数据库示例，请参见[在 Amazon RDS 服务中配置 MySQL 数据库](../../../../how-to-guides/new-user-guides/infrastructure-setup/mysql-database-in-amazon-rds.md)的教程。 + +如需获取配置 K3s 集群数据库的所有可用选项，请参见 [K3s 官方文档](https://rancher.com/docs/k3s/latest/en/installation/datastore/)。 + +## 3. 配置负载均衡器 + +你还需要设置一个负载均衡器，来将流量重定向到两个节点上的 Rancher 副本。配置后，当单个节点不可用时，继续保障与 Rancher Management Server 的通信。 + +在后续步骤中配置 Kubernetes 时，K3s 工具会部署一个 Traefik Ingress Controller。该 Controller 将侦听 worker 节点的 80 端口和 443 端口，以响应发送给特定主机名的流量。 + +在安装 Rancher 后（也是在后续步骤中），Rancher 系统将创建一个 Ingress 资源。该 Ingress 通知 Traefik Ingress Controller 监听发往 Rancher 主机名的流量。Traefik Ingress Controller 在收到发往 Rancher 主机名的流量时，会将其转发到集群中正在运行的 Rancher Server Pod。 + +在你的实现中，你可以考虑是否需要使用 4 层或 7 层的负载均衡器： + +- **4 层负载均衡器**：两种选择中较为简单的一种，它将 TCP 流量转发到你的节点中。我们建议使用 4 层负载均衡器，将流量从 TCP/80 端口和 TCP/443 端口转发到 Rancher Management 集群节点上。集群上的 Ingress Controller 会将 HTTP 流量重定向到 HTTPS，并在 TCP/443 端口上终止 SSL/TLS。Ingress Controller 会将流量转发到 Rancher deployment 中 Ingress Pod 的 TCP/80 端口。 +- **7 层负载均衡器**：相对比较复杂，但功能更全面。例如，与 Rancher 本身进行 TLS 终止相反，7 层负载均衡器能够在负载均衡器处处理 TLS 终止。如果你需要集中在基础设施中进行 TLS 终止，7 层负载均衡可能会很适合你。7 层负载均衡还能让你的负载均衡器基于 HTTP 属性（例如 cookie 等）做出决策，而 4 层负载均衡器则不能。如果你选择在 7 层负载均衡器上终止 SSL/TLS 流量，则在安装 Rancher 时（后续步骤）需要使用 `--set tls=external` 选项。详情请参见 [Rancher Helm Chart 选项](../../installation-references/helm-chart-options.md#外部-tls-终止)。 + +如需获取配置 NGINX 负载均衡器的示例，请参见[本页](../../../../how-to-guides/new-user-guides/infrastructure-setup/nginx-load-balancer.md)。 + +如需获取如何配置 Amazon ELB 网络负载均衡器的指南，请参见[本页](../../../../how-to-guides/new-user-guides/infrastructure-setup/amazon-elb-load-balancer.md)。 + +:::note 重要提示： + +安装后，请勿将此负载均衡（例如 `local` 集群 Ingress）用于 Rancher 以外的应用。如果此 Ingress 与其他应用共享，在其他应用的 Ingress 配置重新加载后，可能导致 Rancher 出现 websocket 错误。我们建议把 `local` 集群专用给 Rancher，不要在集群内部署其他应用。 + +::: + +## 4. 配置 DNS 记录 + +配置完负载均衡器后，你将需要创建 DNS 记录，以将流量发送到该负载均衡器。 + +根据你的环境，DNS 记录可以是指向负载均衡器 IP 的 A 记录，也可以是指向负载均衡器主机名的 CNAME。无论是哪种情况，请确保该记录是你要 Rancher 进行响应的主机名。 + +在安装 Rancher 时（后续步骤），你需要指定此主机名。请知悉，此主机名无法修改。请确保你设置的主机名是你想要的。 + +有关设置 DNS 记录以将域流量转发到 Amazon ELB 负载均衡器的指南，请参见 [AWS 官方文档](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/routing-to-elb-load-balancer)。 + +## 5. 配置私有镜像仓库 + +Rancher 支持使用私有镜像仓库进行离线安装。你必须有自己的私有镜像仓库或使用其他方式将容器镜像分发到主机。 + +在后续设置 K3s Kubernetes 集群时，你需要创建一个[私有镜像仓库配置文件](https://rancher.com/docs/k3s/latest/en/installation/private-registry/)，其中包含此镜像仓库的信息。 + +如果你需要创建私有镜像仓库，请参阅相应运行时的文档： + +* [Containerd](https://github.com/containerd/containerd/blob/main/docs/cri/config.md#registry-configuration). + * [Nerdctl 命令和镜像仓库托管服务](https://github.com/containerd/nerdctl/blob/main/docs/registry.md) +* [Docker](https://docs.docker.com/registry/deploying/). + + + + +如需在高可用 RKE 集群中安装 Rancher Management Server，我们建议配置以下基础设施： + +- **3 个 Linux 节点**：可以是你的云提供商（例如 Amazon EC2，GCE 或 vSphere）中的虚拟机。 +- **1 个负载均衡器**：用于将前端流量转发到这三个节点中。 +- **1 个 DNS 记录**：用于将 URL 映射到负载均衡器。此 DNS 记录将成为 Rancher Server 的 URL，下游集群需要可以访问到这个地址。 +- **私有镜像仓库**，用于将容器镜像分发到你的主机。 + +这些节点必须位于同一个区域或数据中心。但是你可以把这些服务器放在不同的可用区。 + +## 为什么使用三个节点？ + +在 RKE 集群中，Rancher Server 的数据存储在 etcd 中。而这个 etcd 数据库在这三个节点上运行。 + +为了选举出大多数 etcd 节点认可的 etcd 集群 leader，etcd 数据库需要奇数个节点。如果 etcd 数据库无法选出 leader，etcd 可能会出现[脑裂（split brain）](https://www.quora.com/What-is-split-brain-in-distributed-systems)的问题，此时你需要使用备份恢复集群。如果三个 etcd 节点之一发生故障，其余两个节点可以选择一个 leader，因为它们是 etcd 节点总数的大多数部分。 + +## 1. 配置 Linux 节点 + +这些主机会断开互联网链接，但需要能与你的私有镜像仓库连接。 + +请确保你的节点满足[操作系统，容器运行时，硬件和网络](../../installation-requirements/installation-requirements.md)的常规要求。 + +如需获取配置 Linux 节点的示例，请参见[在 Amazon EC2 中配置节点](../../../../how-to-guides/new-user-guides/infrastructure-setup/nodes-in-amazon-ec2.md)的教程。 + +## 2. 配置负载均衡器 + +你还需要设置一个负载均衡器，来将流量重定向到两个节点上的 Rancher 副本。配置后，当单个节点不可用时，继续保障与 Rancher Management Server 的通信。 + +在后续步骤中配置 Kubernetes 时，RKE 工具会部署一个 NGINX Ingress Controller。该 Controller 将侦听 worker 节点的 80 端口和 443 端口，以响应发送给特定主机名的流量。 + +在安装 Rancher 后（也是在后续步骤中），Rancher 系统将创建一个 Ingress 资源。该 Ingress 通知 NGINX Ingress Controller 监听发往 Rancher 主机名的流量。NGINX Ingress Controller 在收到发往 Rancher 主机名的流量时，会将其转发到集群中正在运行的 Rancher Server Pod。 + +在你的实现中，你可以考虑是否需要使用 4 层或 7 层的负载均衡器： + +- **4 层负载均衡器**：两种选择中较为简单的一种，它将 TCP 流量转发到你的节点中。我们建议使用 4 层负载均衡器，将流量从 TCP/80 端口和 TCP/443 端口转发到 Rancher Management 集群节点上。集群上的 Ingress Controller 会将 HTTP 流量重定向到 HTTPS，并在 TCP/443 端口上终止 SSL/TLS。Ingress Controller 会将流量转发到 Rancher deployment 中 Ingress Pod 的 TCP/80 端口。 +- **7 层负载均衡器**：相对比较复杂，但功能更全面。例如，与 Rancher 本身进行 TLS 终止相反，7 层负载均衡器能够在负载均衡器处处理 TLS 终止。如果你需要集中在基础设施中进行 TLS 终止，7 层负载均衡可能会很适合你。7 层负载均衡还能让你的负载均衡器基于 HTTP 属性（例如 cookie 等）做出决策，而 4 层负载均衡器则不能。如果你选择在 7 层负载均衡器上终止 SSL/TLS 流量，则在安装 Rancher 时（后续步骤）需要使用 `--set tls=external` 选项。详情请参见 [Rancher Helm Chart 选项](../../installation-references/helm-chart-options.md#外部-tls-终止)。 + +如需获取配置 NGINX 负载均衡器的示例，请参见[本页](../../../../how-to-guides/new-user-guides/infrastructure-setup/nginx-load-balancer.md)。 + +如需获取如何配置 Amazon ELB 网络负载均衡器的指南，请参见[本页](../../../../how-to-guides/new-user-guides/infrastructure-setup/amazon-elb-load-balancer.md)。 + +:::caution + +安装后，请勿将此负载均衡（例如 `local` 集群 Ingress）用于 Rancher 以外的应用。如果此 Ingress 与其他应用共享，在其他应用的 Ingress 配置重新加载后，可能导致 Rancher 出现 websocket 错误。我们建议把 `local` 集群专用给 Rancher，不要在集群内部署其他应用。 + +::: + +## 3. 配置 DNS 记录 + +配置完负载均衡器后，你将需要创建 DNS 记录，以将流量发送到该负载均衡器。 + +根据你的环境，DNS 记录可以是指向负载均衡器 IP 的 A 记录，也可以是指向负载均衡器主机名的 CNAME。无论是哪种情况，请确保该记录是你要 Rancher 进行响应的主机名。 + +在安装 Rancher 时（后续步骤），你需要指定此主机名。请知悉，此主机名无法修改。请确保你设置的主机名是你想要的。 + +有关设置 DNS 记录以将域流量转发到 Amazon ELB 负载均衡器的指南，请参见 [AWS 官方文档](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/routing-to-elb-load-balancer)。 + +## 4. 配置私有镜像仓库 + +Rancher 支持使用安全的私有镜像仓库进行离线安装。你必须有自己的私有镜像仓库或使用其他方式将容器镜像分发到主机。 + +在后续设置 RKE Kubernetes 集群时，你需要创建一个[私有镜像仓库配置文件](https://rancher.com/docs/rke/latest/en/config-options/private-registries/)，其中包含此镜像仓库的信息。 + +如果你需要创建私有镜像仓库，请参阅相应运行时的文档： + +* [Containerd](https://github.com/containerd/containerd/blob/main/docs/cri/config.md#registry-configuration). + * [Nerdctl 命令和镜像仓库托管服务](https://github.com/containerd/nerdctl/blob/main/docs/registry.md) +* [Docker](https://docs.docker.com/registry/deploying/). + + + + +:::note 注意事项： + +- Docker 安装适用于想要测试 Rancher 的用户。由于只有一个节点和一个 Docker 容器，因此如果该节点发生故障，你将丢失 Rancher Server 的所有数据。 + +- Rancher backup operator 可将 Rancher 从单个 Docker 容器迁移到高可用 Kubernetes 集群上。详情请参见[把 Rancher 迁移到新集群](../../../../how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/migrate-rancher-to-new-cluster.md)。 + +::: + +## 1. 配置 Linux 节点 + +此主机会断开互联网链接，但需要能与你的私有镜像仓库连接。 + +请确保你的节点满足[操作系统，容器，硬件和网络](../../installation-requirements/installation-requirements.md)的常规安装要求。 + +如需获取配置 Linux 节点的示例，请参见[在 Amazon EC2 中配置节点](../../../../how-to-guides/new-user-guides/infrastructure-setup/nodes-in-amazon-ec2.md)的教程。 + +## 2. 配置私有 Docker 镜像仓库 + +Rancher 支持使用私有镜像仓库在堡垒服务器中进行离线安装。你必须有自己的私有镜像仓库或使用其他方式将容器镜像分发到主机。 + +如需获得创建私有镜像仓库的帮助，请参见 [Docker 官方文档](https://docs.docker.com/registry/)。 + + + + +## 后续操作 +[收集镜像并发布到你的私有镜像仓库](publish-images.md) diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/installation-and-upgrade/other-installation-methods/air-gapped-helm-cli-install/install-kubernetes.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/installation-and-upgrade/other-installation-methods/air-gapped-helm-cli-install/install-kubernetes.md new file mode 100644 index 00000000000..e187c8625dc --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/installation-and-upgrade/other-installation-methods/air-gapped-helm-cli-install/install-kubernetes.md @@ -0,0 +1,294 @@ +--- +title: '3. 安装 Kubernetes（Docker 安装请跳过）' +--- + +:::note + +如果你使用 Docker 在单个节点上安装 Rancher，请跳过本节。 + +::: + +本文描述了如何根据 [Rancher Server 环境的最佳实践](../../../../reference-guides/rancher-manager-architecture/architecture-recommendations.md#kubernetes-安装环境)来安装 Kubernetes 集群。该集群需要专用于运行 Rancher Server。 + +Rancher 可以安装在任何 Kubernetes 集群上，包括托管的 Kubernetes。 + +在 RKE2 或 K3s 上离线安装 Kubernetes 集群的步骤如下所示： + + + + +在本指南中，我们假设你已经在离线环境中创建了节点，并且在堡垒服务器上有一个安全的 Docker 私有镜像仓库。 + +### 安装概要 + +1. [准备镜像目录](#1-准备镜像目录) +2. [创建镜像仓库 YAML](#2-创建镜像仓库-yaml) +3. [安装 K3s](#3-安装-k3s) +4. [保存并开始使用 kubeconfig 文件](#4-保存并开始使用-kubeconfig-文件) + +### 1. 准备镜像目录 +从 [Releases](https://github.com/k3s-io/k3s/releases) 页面获取要运行的 K3s 版本的镜像 tar 文件。 + +在每个节点上启动 K3s 之前，将这个 tar 文件放在 `images` 目录中，例如： + +```sh +sudo mkdir -p /var/lib/rancher/k3s/agent/images/ +sudo cp ./k3s-airgap-images-$ARCH.tar /var/lib/rancher/k3s/agent/images/ +``` + +### 2. 创建镜像仓库 YAML +把 `registries.yaml` 文件创建到 `/etc/rancher/k3s/registries.yaml` 中。此文件为 K3s 提供连接到你的私有镜像仓库的详细信息。 + +在加入必要信息之前，`registries.yaml` 文件是这样的： + +```yaml +--- +mirrors: + customreg: + endpoint: + - "https://ip-to-server:5000" +configs: + customreg: + auth: + username: xxxxxx # 镜像仓库的用户名 + password: xxxxxx # 镜像仓库的密码 + tls: + cert_file: <镜像仓库所用的证书文件路径> + key_file: <镜像仓库所用的密钥文件路径> + ca_file: <镜像仓库所用的 CA 文件路径> +``` + +请注意，目前，K3s 仅支持安全的镜像仓库（带有自定义 CA 的 SSL）。 + +有关 K3s 的私有镜像仓库配置文件的详情，请参见 [K3s 官方文档](https://rancher.com/docs/k3s/latest/en/installation/private-registry/)。 + +### 3. 安装 K3s + +Rancher 需要安装在支持的 Kubernetes 版本上。如需了解你使用的 Rancher 版本支持哪些 Kubernetes 版本，请参见 [Rancher 支持矩阵](https://www.suse.com/suse-rancher/support-matrix/all-supported-versions/)。 + +如需指定 K3s（Kubernetes）版本，在运行 K3s 安装脚本时使用 `INSTALL_K3S_VERSION` 环境变量（例如 `INSTALL_K3S_VERSION="v1.24.10+k3s1"`）。 + +从 [Releases](https://github.com/k3s-io/k3s/releases) 页面获取 K3s 的二进制文件，该文件要匹配用于获取离线镜像的 tar 版本。 +访问 [K3s 安装脚本](https://get.k3s.io)以获取 K3s 的安装脚本。 + +将二进制文件放到每个节点的 `/usr/local/bin` 中。 +将安装脚本放在每个节点的任意位置，并将脚本命名为 `install.sh`。 + +在每个 Server 上安装 K3s： + +``` +INSTALL_K3S_SKIP_DOWNLOAD=true INSTALL_K3S_VERSION= ./install.sh +``` + +在每个 Agent 上安装 K3s： + +``` +INSTALL_K3S_SKIP_DOWNLOAD=true INSTALL_K3S_VERSION= K3S_URL=https://:6443 K3S_TOKEN= ./install.sh +``` + +其中 `` 是 Server 的 IP 或有效 DNS，`` 是可以在 `/var/lib/rancher/k3s/server/node-token` 中找到的 Server node-token。 + +:::note + +K3s 自动为 kubelets 提供 `--resolv-conf` 标志，该标志可能对在离线环境中配置 DNS 有帮助。 + +::: + +### 4. 保存并开始使用 kubeconfig 文件 + +在每个 Rancher Server 节点安装 K3s 时，会在每个节点的 `/etc/rancher/k3s/k3s.yaml` 中生成一个 `kubeconfig` 文件。该文件包含访问集群的凭证。请将该文件保存在安全的位置。 + +如要使用该 `kubeconfig` 文件： + +1. 安装 Kubernetes 命令行工具 [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/#install-kubectl)。 +2. 复制 `/etc/rancher/k3s/k3s.yaml` 文件并保存到本地主机的 `~/.kube/config` 目录上。 +3. 在 kubeconfig 文件中，`server` 的参数为 localhost。你需要将 `server` 配置为负载均衡器的 DNS，并指定端口 6443（通过端口 6443 访问 Kubernetes API Server，通过端口 80 和 443 访问 Rancher Server）。以下是一个 `k3s.yaml` 示例： + +```yaml +apiVersion: v1 +clusters: +- cluster: + certificate-authority-data: [CERTIFICATE-DATA] + server: [LOAD-BALANCER-DNS]:6443 # 编辑此行 + name: default +contexts: +- context: + cluster: default + user: default + name: default +current-context: default +kind: Config +preferences: {} +users: +- name: default + user: + password: [PASSWORD] + username: admin +``` + +**结果**：你可以开始使用 `kubectl` 来管理你的 K3s 集群。如果你有多个 `kubeconfig` 文件，在使用 `kubectl` 时，你可以传入文件路径来指定要使用的 `kubeconfig` 文件： + +``` +kubectl --kubeconfig ~/.kube/config/k3s.yaml get pods --all-namespaces +``` + +有关 `kubeconfig` 文件的详情，请参见 [K3s 官方文档](https://rancher.com/docs/k3s/latest/en/cluster-access/) 或 [ Kubernetes 官方文档](https://kubernetes.io/docs/concepts/configuration/organize-cluster-access-kubeconfig/)中关于使用 `kubeconfig` 文件管理集群访问的部分。 + +### 升级注意事项 + +你可以通过以下方式完成离线环境的升级： + +1. 从 [Releases](https://github.com/k3s-io/k3s/releases) 页面下载要升级的 K3s 版本的新离线镜像 tar 包。将 tar 文件放在每个节点上的 `/var/lib/rancher/k3s/agent/images/` 目录中。删除旧的 tar 文件。 +2. 复制并替换每个节点上 `/usr/local/bin` 中的旧 K3s 二进制文件。复制 [K3s 安装脚本](https://get.k3s.io)（因为脚本可能自上次版本发布以来已更改）。使用相同的环境变量再次运行脚本。 +3. 重启 K3s 服务（如果安装程序没有自动重启 K3s 的话）。 + + + + +在本指南中，我们假设你已经在离线环境中创建了节点，并且在堡垒服务器上有一个安全的 Docker 私有镜像仓库。 + +### 安装概要 + +1. [创建 RKE2 配置](#1-创建-rke2-配置) +2. [创建镜像仓库 YAML](#2-创建镜像仓库-yaml) +3. [安装 RKE2](#3-安装-rke2) +4. [保存并开始使用 kubeconfig 文件](#4-保存并开始使用-kubeconfig-文件) + +### 1. 创建 RKE2 配置 +把 config.yaml 文件创建到 `/etc/rancher/rke2/config.yaml` 中。这将包含创建高可用 RKE2 集群所需的所有配置选项。 + +第一台服务器的最低配置是： + +``` +token: my-shared-secret +tls-san: + - loadbalancer-dns-domain.com +``` + +其他服务器的配置文件应该包含相同的令牌，并让 RKE2 知道要连接到现有的第一台服务器： + +``` +server: https://ip-of-first-server:9345 +token: my-shared-secret +tls-san: + - loadbalancer-dns-domain.com +``` + +有关详细信息，请参阅 [RKE2 文档](https://docs.rke2.io/install/ha)。 + +:::note + +RKE2 自动为 kubelets 提供 `resolv-conf` 选项，该标志可能对在离线环境中配置 DNS 有帮助。 + +::: + +### 2. 创建镜像仓库 YAML +把 `registries.yaml` 文件创建到 `/etc/rancher/rke2/registries.yaml` 中。此文件为 RKE2 提供连接到你的私有镜像仓库的详细信息。 + +在加入必要信息之前，`registries.yaml` 文件是这样的： + +``` +--- +mirrors: + customreg: + endpoint: + - "https://ip-to-server:5000" +configs: + customreg: + auth: + username: xxxxxx # 镜像仓库的用户名 + password: xxxxxx # 镜像仓库的密码 + tls: + cert_file: <镜像仓库所用的证书文件路径> + key_file: <镜像仓库所用的密钥文件路径> + ca_file: <镜像仓库所用的 CA 文件路径> +``` + +有关 RKE2 的私有镜像仓库配置文件的详情，请参见 [RKE2 官方文档](https://docs.rke2.io/install/private_registry)。 + +### 3. 安装 RKE2 + +Rancher 需要安装在支持的 Kubernetes 版本上。如需了解你使用的 Rancher 版本支持哪些 Kubernetes 版本，请参见[支持维护条款](https://rancher.com/support-maintenance-terms/)。 + +从 Release 页面下载安装脚本、rke2、rke2-images 和 sha256sum 存档，并将它们上传到每个服务器上的目录中： + +``` +mkdir /tmp/rke2-artifacts && cd /tmp/rke2-artifacts/ +wget https://github.com/rancher/rke2/releases/download/v1.21.5%2Brke2r2/rke2-images.linux-amd64.tar.zst +wget https://github.com/rancher/rke2/releases/download/v1.21.5%2Brke2r2/rke2.linux-amd64.tar.gz +wget https://github.com/rancher/rke2/releases/download/v1.21.5%2Brke2r2/sha256sum-amd64.txt +curl -sfL https://get.rke2.io --output install.sh +``` + +接下来，使用每个服务器上的目录运行 install.sh，如下例所示： + +``` +INSTALL_RKE2_ARTIFACT_PATH=/tmp/rke2-artifacts sh install.sh +``` + +然后在所有服务器上启用并启动该服务： + +`` +systemctl enable rke2-server.service +systemctl start rke2-server.service +`` + +有关详细信息，请参阅 [RKE2 文档](https://docs.rke2.io/install/airgap)。 + +### 4. 保存并开始使用 kubeconfig 文件 + +在每个 Rancher Server 节点安装 RKE2 时，会在每个节点的 `/etc/rancher/rke2/rke2.yaml` 中生成一个 `kubeconfig` 文件。该文件包含访问集群的凭证。请将该文件保存在安全的位置。 + +如要使用该 `kubeconfig` 文件： + +1. 安装 [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/#install-kubectl)（Kubernetes 命令行工具）。 +2. 复制 `/etc/rancher/rke2/rke2.yaml` 文件并保存到本地主机的 `~/.kube/config` 目录上。 +3. 在 kubeconfig 文件中，`server` 的参数为 localhost。你需要将 `server` 配置为负载均衡器的 DNS，并指定端口 6443（通过端口 6443 访问 Kubernetes API Server，通过端口 80 和 443 访问 Rancher Server）。以下是一个 `rke2.yaml` 示例： + +``` +apiVersion: v1 +clusters: +- cluster: + certificate-authority-data: [CERTIFICATE-DATA] + server: [LOAD-BALANCER-DNS]:6443 # 编辑此行 + name: default +contexts: +- context: + cluster: default + user: default + name: default +current-context: default +kind: Config +preferences: {} +users: +- name: default + user: + password: [PASSWORD] + username: admin +``` + +**结果**：你可以开始使用 `kubectl` 来管理你的 RKE2 集群。如果你有多个 `kubeconfig` 文件，在使用 `kubectl` 时，你可以传入文件路径来指定要使用的 `kubeconfig` 文件： + +``` +kubectl --kubeconfig ~/.kube/config/rke2.yaml get pods --all-namespaces +``` + +有关 `kubeconfig` 文件的详情，请参见 [RKE2 官方文档](https://docs.rke2.io/cluster_access)或 [ Kubernetes 官方文档](https://kubernetes.io/docs/concepts/configuration/organize-cluster-access-kubeconfig/)中关于使用 `kubeconfig` 文件管理集群访问的部分。 + +### 升级注意事项 + +你可以通过以下方式完成离线环境的升级： + +1. 从 [Releases](https://github.com/rancher/rke2/releases) 页面下载新的离线工件，并安装升级 RKE2 版本的脚本。 +2. 使用相同的环境变量再次运行脚本。 +3. 重启 RKE2 服务。 + + + + +### 故障排除 + +参见[故障排除](../../install-upgrade-on-a-kubernetes-cluster/troubleshooting.md)页面。 + +### 后续操作 +[安装 Rancher](install-rancher-ha.md) diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/installation-and-upgrade/other-installation-methods/air-gapped-helm-cli-install/install-rancher-ha.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/installation-and-upgrade/other-installation-methods/air-gapped-helm-cli-install/install-rancher-ha.md new file mode 100644 index 00000000000..7311f4f4b02 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/installation-and-upgrade/other-installation-methods/air-gapped-helm-cli-install/install-rancher-ha.md @@ -0,0 +1,243 @@ +--- +title: 4. 安装 Rancher +--- + +本文介绍如何在高可用 Kubernetes 安装的离线环境部署 Rancher。离线环境可以是 Rancher Server 离线安装、防火墙后面或代理后面。 + +## Rancher 特权访问 + +当 Rancher Server 部署在 Docker 容器中时，容器内会安装一个本地 Kubernetes 集群供 Rancher 使用。为 Rancher 的很多功能都是以 deployment 的方式运行的，而在容器内运行容器是需要特权模式的，因此你需要在安装 Rancher 时添加 `--privileged` 选项。 + +## Docker 说明 + +如果你想使用 Docker 命令进行离线安装，请跳过本页的剩余部分，并按照[此页](docker-install-commands.md)进行操作。 + +## Kubernetes 说明 + +我们建议在 Kubernetes 集群上安装 Rancher。高可用的 Kubernetes 安装的情况下，一个 Kubernetes 集群包含三个运行 Rancher Server 组件的节点。持久层（etcd）也在这三个节点上进行复制，以便在其中一个节点发生故障时提供冗余和数据复制。 + +### 1. 添加 Helm Chart 仓库 + +从可以访问互联网的系统中，获取最新的 Helm Chart，然后将 manifest 复制到可访问 Rancher Server 集群的系统中。 + +1. 如果你还没有安装 `helm`，请在可访问互联网的工作站上进行本地安装。注意：参考 [Helm 版本要求](../../resources/helm-version-requirements.md)选择 Helm 版本来安装 Rancher。 + +2. 执行 `helm repo add` 命令，以添加包含安装 Rancher 的 Chart 的 Helm Chart 仓库。有关如何选择仓库，以及哪个仓库最适合你的用例，请参见[选择 Rancher 版本](../../resources/choose-a-rancher-version.md)。 + - Latest：建议用于试用最新功能 + ``` + helm repo add rancher-latest https://releases.rancher.com/server-charts/latest + ``` + - Stable：建议用于生产环境 + ``` + helm repo add rancher-stable https://releases.rancher.com/server-charts/stable + ``` + - Alpha：即将发布的实验性预览。 + ``` + helm repo add rancher-alpha https://releases.rancher.com/server-charts/alpha + ``` + 注意：不支持升级到 Alpha 版、从 Alpha 版升级或在 Alpha 版之间升级。 + +3. 获取最新的 Rancher Chart。此操作将获取 Chart 并将其作为 `.tgz` 文件保存在当前目录中。 + ```plain + helm fetch rancher-/rancher + ``` + + 如需下载特定的 Rancher 版本，你可以用 Helm `--version` 参数指定版本，如下： + ```plain + helm fetch rancher-stable/rancher --version=v2.4.8 + ``` + +### 2. 选择 SSL 配置 + +Rancher Server 默认设计为安全的，并且需要 SSL/TLS 配置。 + +如果你在离线的 Kubernetes 集群中安装 Rancher，我们建议使用以下两种证书生成方式。 + +:::note + +如果你想在外部终止 SSL/TLS，请参见[外部负载均衡器的 TLS 终止](../../installation-references/helm-chart-options.md#外部-tls-终止)。 + +::: + +| 配置 | Chart 选项 | 描述 | 是否需要 cert-manager | +| ------------------------------------------ | ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------- | +| Rancher 生成的自签名证书 | `ingress.tls.source=rancher` | 使用 Rancher 生成的 CA 签发的自签名证书。此项是**默认选项**。在渲染 Helm 模板的时候不需要传递此项。 | 是 | +| 你已有的证书 | `ingress.tls.source=secret` | 通过创建 Kubernetes 密文使用你自己的证书文件。
在渲染 Rancher Helm 模板时必须传递此选项。 | 否 | + +### 离线安装的 Helm Chart 选项 + +在配置 Rancher Helm 模板时，Helm Chart 中有几个专为离线安装设计的选项，如下表： + +| Chart 选项 | Chart 值 | 描述 | +| ----------------------- | -------------------------------- | ---- | +| `certmanager.version` | `` | 根据运行的 cert-manager 版本配置适当的 Rancher TLS 颁发者。 | +| `systemDefaultRegistry` | `` | 将 Rancher Server 配置成在配置集群时，始终从私有镜像仓库中拉取镜像。 | +| `useBundledSystemChart` | `true` | 配置 Rancher Server 使用打包的 Helm System Chart 副本。[system charts](https://github.com/rancher/system-charts) 仓库包含所有 Monitoring，Logging，告警和全局 DNS 等功能所需的应用商店项目。这些 [Helm Chart](https://github.com/rancher/system-charts) 位于 GitHub 中。但是由于你处在离线环境，因此使用 Rancher 内置的 Chart 会比设置 Git mirror 容易得多。 | + +### 3. 获取 Cert-Manager Chart + +根据你在[2：选择 SSL 配置](#2-选择-ssl-配置)中的选择，完成以下步骤之一： + +#### 选项 A：使用 Rancher 默认的自签名证书 + +默认情况下，Rancher 会生成一个 CA 并使用 cert-manager 颁发证书以访问 Rancher Server 界面。 + +:::note + +由于 cert-manager 的最新改动，你需要升级 cert-manager 版本。如果你需要升级 Rancher 并使用低于 0.11.0 的 cert-manager 版本，请参见 [cert-manager 升级文档](../../resources/upgrade-cert-manager.md)。 + +::: + +##### 1. 添加 cert-manager 仓库 + +在可以连接互联网的系统中，将 cert-manager 仓库添加到 Helm： + +```plain +helm repo add jetstack https://charts.jetstack.io +helm repo update +``` + +##### 2. 获取 cert-manager Chart + +从 [Helm Chart 仓库](https://artifacthub.io/packages/helm/cert-manager/cert-manager)中获取最新可用的 cert-manager Chart： + +```plain +helm fetch jetstack/cert-manager +``` + +##### 3. 检索 Cert-Manager CRD + +为 cert-manager 下载所需的 CRD 文件： +```plain +curl -L -o cert-manager-crd.yaml https://github.com/cert-manager/cert-manager/releases/download//cert-manager.crds.yaml +``` + +### 4. 安装 Rancher + +将获取的 Chart 复制到有权访问 Rancher Server 集群的系统以完成安装。 + +#### 1. 安装 Cert-Manager + +使用要用于安装 Chart 的选项来安装 cert-manager。记住要设置 `image.repository` 选项，以从你的私有镜像仓库拉取镜像。此操作会创建一个包含 Kubernetes manifest 文件的 `cert-manager` 目录。 + +:::note + +要查看自定义 cert-manager 安装的选项（包括集群使用 PodSecurityPolicies 的情况），请参阅 [cert-manager 文档](https://artifacthub.io/packages/helm/cert-manager/cert-manager#configuration)。 + +::: + +
+ 单击展开 + +如果你使用自签名证书，安装 cert-manager： + +1. 为 cert-manager 创建命名空间： + + ```plain + kubectl create namespace cert-manager + ``` + +2. 创建 cert-manager CustomResourceDefinition (CRD)。 + + ```plain + kubectl apply -f cert-manager/cert-manager-crd.yaml + ``` + +3. 安装 cert-manager。 + + ```plain + helm install cert-manager ./cert-manager-.tgz \ + --namespace cert-manager \ + --set image.repository=/quay.io/jetstack/cert-manager-controller \ + --set webhook.image.repository=/quay.io/jetstack/cert-manager-webhook \ + --set cainjector.image.repository=/quay.io/jetstack/cert-manager-cainjector \ + --set startupapicheck.image.repository=/quay.io/jetstack/cert-manager-ctl + ``` + +
+ +#### 2. 安装 Rancher + +首先，参见[添加 TLS 密文](../../resources/add-tls-secrets.md)发布证书文件，以便 Rancher 和 Ingress Controller 可以使用它们。 + +然后，使用 kubectl 为 Rancher 创建命名空间： + +```plain +kubectl create namespace cattle-system +``` + +然后安装 Rancher，并声明你选择的选项。参考下表来替换每个占位符。Rancher 需要配置为使用私有镜像仓库，以便配置所有 Rancher 启动的 Kubernetes 集群或 Rancher 工具。 + +| 占位符 | 描述 | +------------|------------- +| `` | 输出压缩包的版本号。 | +| `` | 指向负载均衡器的 DNS 名称。 | +| `` | 你的私有镜像仓库的 DNS 名称。 | +| `` | 在 K8s 集群上运行的 cert-manager 版本。 | + +```plain + helm install rancher ./rancher-.tgz \ + --namespace cattle-system \ + --set hostname= \ + --set certmanager.version= \ + --set rancherImage=/rancher/rancher \ + --set systemDefaultRegistry= \ # 设置在 Rancher 中使用的默认私有镜像仓库 + --set useBundledSystemChart=true # 使用打包的 Rancher System Chart +``` + +**可选**：如需安装特定的 Rancher 版本，设置`rancherImageTag` 的值，例如：`--set rancherImageTag=v2.5.8` + +#### 选项 B：使用 Kubernetes 密文从文件中获取证书 + +##### 1. 创建密文 + +使用你自己的证书来创建 Kubernetes 密文，以供 Rancher 使用。证书的 common name 需要与以下命令中的 `hostname` 选项匹配，否则 Ingress Controller 将无法为 Rancher 配置站点。 + +##### 2. 安装 Rancher + +安装 Rancher，并声明你选择的选项。参考下表来替换每个占位符。Rancher 需要配置为使用私有镜像仓库，以便配置所有 Rancher 启动的 Kubernetes 集群或 Rancher 工具。 + +| 占位符 | 描述 | +| -------------------------------- | ----------------------------------------------- | +| `` | 输出压缩包的版本号。 | +| `` | 指向负载均衡器的 DNS 名称。 | +| `` | 你的私有镜像仓库的 DNS 名称。 | + +```plain + helm install rancher ./rancher-.tgz \ + --namespace cattle-system \ + --set hostname= \ + --set rancherImage=/rancher/rancher \ + --set ingress.tls.source=secret \ + --set systemDefaultRegistry= \ # 设置在 Rancher 中使用的默认私有镜像仓库 + --set useBundledSystemChart=true # 使用打包的 Rancher System Chart +``` + +如果你使用的是私有 CA 签名的证书，请在 `--set ingress.tls.source=secret` 后加上 `--set privateCA=true`： + +```plain + helm install rancher ./rancher-.tgz \ + --namespace cattle-system \ + --set hostname= \ + --set rancherImage=/rancher/rancher \ + --set ingress.tls.source=secret \ + --set privateCA=true \ + --set systemDefaultRegistry= \ # 设置在 Rancher 中使用的默认私有镜像仓库 + --set useBundledSystemChart=true # 使用打包的 Rancher System Chart +``` + + +安装已完成。 +:::caution + +如果你不想发送遥测数据，在首次登录时退出[遥测](../../../../faq/telemetry.md)。如果在离线安装的环境中让这个功能处于 active 状态，socket 可能无法打开。 + +::: + +## 其他资源 + +以下资源可能对安装 Rancher 有帮助： + +- [Rancher Helm Chart 选项](../../installation-references/helm-chart-options.md) +- [添加 TLS 密文](../../resources/add-tls-secrets.md) +- [Rancher Kubernetes 安装的故障排除](../../install-upgrade-on-a-kubernetes-cluster/troubleshooting.md) diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/installation-and-upgrade/other-installation-methods/air-gapped-helm-cli-install/publish-images.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/installation-and-upgrade/other-installation-methods/air-gapped-helm-cli-install/publish-images.md new file mode 100644 index 00000000000..783555ba158 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/installation-and-upgrade/other-installation-methods/air-gapped-helm-cli-install/publish-images.md @@ -0,0 +1,305 @@ +--- +title: '2. 收集镜像并发布到私有仓库' +--- + +本文介绍如何配置私有镜像仓库，以便在安装 Rancher 时，Rancher 可以从此私有镜像仓库中拉取所需的镜像。 + +默认情况下，所有用于[配置 Kubernetes 集群](../../../../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/kubernetes-clusters-in-rancher-setup.md)或启动 Rancher 中的工具（如监控，流水线，告警等）的镜像都是从 Docker Hub 中拉取的。在 Rancher 的离线安装中，你需要一个私有仓库，该仓库位于你的 Rancher Server 中某个可访问的位置。然后，你可加载该存有所有镜像的镜像仓库。 + +使用 Docker 安装 Rancher，和把 Rancher 安装到 Kubernetes 集群，其对应的推送镜像到私有镜像仓库步骤是一样的。 + +你使用 Rancher 配置的下游集群是否有运行 Windows 的节点，决定了本文涉及的步骤。我们提供的推送镜像到私有镜像仓库步骤，是基于假设 Rancher 仅配置运行 Linux 节点的下游 Kubernetes 集群的。但是，如果你计划[在下游 Kubernetes 集群中使用 Windows 节点](../../../../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/use-windows-clusters/use-windows-clusters.md)，我们有单独的文档来介绍如何为需要的镜像提供支持。 + +:::note 先决条件： + +你必须有一个可用的[私有镜像仓库](https://docs.docker.com/registry/deploying/#run-an-externally-accessible-registry)。 + +如果镜像仓库有证书，请参见 [K3s 文档中心](https://rancher.com/docs/k3s/latest/en/installation/private-registry/)了解添加私有镜像仓库的详情。证书和镜像仓库配置文件均需要挂载到 Rancher 容器中。 + +::: + + + + +如果 Rancher Server 用于配置仅有 Linux 节点的集群，请按以下步骤将你的镜像推送到私有镜像仓库。 + +1. [找到你的 Rancher 版本所需的资源](#1-找到你的-rancher-版本所需的资源) +2. [收集 cert-manager 镜像](#2-收集-cert-manager-镜像)（除非你使用自己的证书，或在负载均衡器上终止 TLS） +3. [把镜像保存到你的工作站](#3-将镜像保存到你的工作站中) +4. [推送镜像到私有镜像仓库](#4-推送镜像到私有镜像仓库) + +### 先决条件 + +这些步骤要求你使用一个 Linux 工作站，该工作站需要可访问互联网和你的私有镜像仓库，且至少有 20GB 的可用磁盘空间。 + +如果你的主机架构是 ARM64，镜像仓库必须支持 Manifest。这是因为从 2020 年 4 月开始, Amazon Elastic Container Registry 已经不再支持 Manifest。 + +### 1. 找到你的 Rancher 版本所需的资源 + +1. 访问 Rancher 的[发布说明](https://github.com/rancher/rancher/releases)页面，找到你需要安装的 Rancher v2.x.x 版本，然后点击 **Assets**。注意不要使用带有 `rc` 或 `Pre-release` 标记的版本，因为这些版本在生产环境中不够稳定。 + +2. 从你所需版本的 **Assets** 处下载以下文件，这些文件是在离线环境中安装 Rancher 所必须的： + +| Release 文件 | 描述 | +| ---------------- | -------------- | +| `rancher-images.txt` | 此文件包含安装 Rancher、配置集群和用户 Rancher 工具所需的镜像。 | +| `rancher-save-images.sh` | 该脚本从 Docker Hub 中拉取在文件 `rancher-images.txt` 中记录的所有镜像，并把这些镜像保存为 `rancher-images.tar.gz`。 | +| `rancher-load-images.sh` | 该脚本从 `rancher-images.tar.gz` 文件中加载镜像，并把镜像推送到你的私有镜像仓库。 | + +### 2. 收集 cert-manager 镜像 + +:::note + +如果你使用自己的证书，或要在外部负载均衡器上终止 TLS，请跳过此步骤。 + +::: + +在 Kubernetes 安装中，如果你使用的是 Rancher 默认的自签名 TLS 证书，则必须将 [`cert-manager`](https://artifacthub.io/packages/helm/cert-manager/cert-manager) 镜像添加到 `rancher-images.txt` 文件中。 + +1. 获取最新的 `cert-manager` Helm Chart，并解析模板以获取镜像的详情信息： + + :::note + + 由于 cert-manager 的最新改动，你需要升级 cert-manager 版本。如果你需要升级 Rancher 并使用低于 0.12.0 的 cert-manager 版本，请参见[升级文档](../../resources/upgrade-cert-manager.md)。 + + ::: + + ```plain + helm repo add jetstack https://charts.jetstack.io + helm repo update + helm fetch jetstack/cert-manager + helm template ./cert-manager-.tgz | awk '$1 ~ /image:/ {print $2}' | sed s/\"//g >> ./rancher-images.txt + ``` + +2. 对镜像列表进行排序和唯一化，以去除重复的镜像源： + + ```plain + sort -u rancher-images.txt -o rancher-images.txt + ``` + +### 3. 将镜像保存到你的工作站中 + +1. 为 `rancher-save-images.sh` 文件添加可执行权限： + ``` + chmod +x rancher-save-images.sh + ``` + +1. 使用 `rancher-images.txt` 镜像列表执行 `rancher-save-images.sh` 脚本，以创建包含所有所需镜像的压缩包： + ```plain + ./rancher-save-images.sh --image-list ./rancher-images.txt + ``` + **结果**：Docker 开始拉取用于离线安装的镜像。请耐心等待。这个过程需要几分钟。完成时，你的当前目录会输出名为 `rancher-images.tar.gz` 的压缩包。请确认输出文件是否存在。 + +### 4. 推送镜像到私有镜像仓库 + +下一步，你将使用脚本将 `rancher-images.tar.gz` 中的镜像移动到你的私有镜像仓库，以方便加载镜像。 + +使用脚本将 `rancher-images.tar.gz` 中的镜像移动到你的私有镜像仓库，以方便加载镜像。 + +`rancher-images.txt` 需要位于工作站中运行 `rancher-load-images.sh` 脚本的同一目录中。`rancher-images.tar.gz` 也需要位于同一目录中。 + +1. 登录到你的私有镜像仓库： +```plain +docker login +``` +1. 为 `rancher-load-images.sh` 添加可执行权限： +``` +chmod +x rancher-load-images.sh +``` + +1. 使用 `rancher-load-images.sh` 脚本来提取，标记和推送 `rancher-images.txt` 及 `rancher-images.tar.gz` 到你的私有镜像仓库： +```plain +./rancher-load-images.sh --image-list ./rancher-images.txt --registry +``` + + + + +如果你的 Rancher Server 将用于配置 Linux 和 Windows 集群，你需要执行不同的步骤，来将 Windows 镜像和 Linux 镜像推送到你的私有镜像仓库。由于 Windows 集群同时包含 Linux 和 Windows 节点，因此推送到私有镜像仓库的 Linux 镜像是 Manifest。 + +## Windows 步骤 + +从 Windows Server 工作站中收集和推送 Windows 镜像。 + +1. 找到你的 Rancher 版本所需的资源 +2. 将镜像保存到你的 Windows Server 工作站 +3. 准备 Docker daemon +4. 推送镜像到私有镜像仓库 + +### 先决条件 + +以下步骤假设你使用 Windows Server 1809 工作站，该工作站能访问网络及你的私有镜像仓库，且至少拥有 50GB 的磁盘空间。 + +工作站必须安装 Docker 18.02+ 版本以提供 manifest 支持。Manifest 支持是配置 Windows 集群所必须的。 + +你的镜像仓库必须支持 Manifest。这是因为从 2020 年 4 月开始, Amazon Elastic Container Registry 已经不再支持 Manifest。 + + + +### 1. 找到你的 Rancher 版本所需的资源 + +1. 访问 Rancher 的[发布说明](https://github.com/rancher/rancher/releases)页面，找到你需要安装的 Rancher v2.x.x 版本。不要下载带有 `rc` 或 `Pre-release` 标记的版本，因为这些版本在生产环境中不够稳定。 + +2. 从你所需版本的 **Assets** 处下载以下文件： + +| Release 文件 | 描述 | +|----------------------------|------------------| +| `rancher-windows-images.txt` | 此文件包含配置 Windows 集群所需的 Windows 镜像。 | +| `rancher-save-images.ps1` | 该脚本从 Docker Hub 中拉取在文件 `rancher-windows-images.txt` 中记录的所有镜像，并把这些镜像保存为 `rancher-windows-images.tar.gz`。 | +| `rancher-load-images.ps1` | 该脚本从 `rancher-windows-images.tar.gz` 文件中加载镜像，并把镜像推送到你的私有镜像仓库。 | + + + +### 2. 将镜像保存到你的 Windows Server 工作站 + +1. 在 `powershell` 中，进入上一步下载的文件所在的目录。 + +1. 运行 `rancher-save-images.ps1` 以创建包含所有所需镜像的压缩包： + ```plain + ./rancher-save-images.ps1 + ``` + + **结果**：Docker 开始拉取用于离线安装的镜像。请耐心等待。这个过程需要几分钟。完成时，你的当前目录会输出名为 `rancher-windows-images.tar.gz` 的压缩包。请确认输出文件是否存在。 + + + +### 3. 准备 Docker daemon + +将你的私有镜像仓库地址尾附到 Docker daemon (`C:\\ProgramData\\Docker\\config\\daemon.json`) 的 `allow-nondistributable-artifacts` 配置字段中。Windows 镜像的基础镜像是由 `mcr.microsoft.com` 镜像仓库维护的，而 Docker Hub 中缺少 Microsoft 镜像仓库层，且需要将其拉入私有镜像仓库，因此这一步骤是必须的。 + +```json +{ + ... + "allow-nondistributable-artifacts": [ + ... + "" + ] + ... +} +``` + + + +### 4. 推送镜像到私有镜像仓库 + +使用脚本将 `rancher-windows-images.tar.gz` 中的镜像移动到你的私有镜像仓库，以方便加载镜像。 + +`rancher-windows-images.txt` 需要位于工作站中运行 `rancher-load-images.ps1` 脚本的同一目录中。`rancher-windows-images.tar.gz` 也需要位于同一目录中。 + +1. 使用 `powershell` 登录到你的私有镜像仓库： + ```plain + docker login + ``` + +1. 在 `powershell` 中，使用 `rancher-load-images.ps1` 脚本来提取，标记和推送 `rancher-images.tar.gz` 中的镜像到你的私有镜像仓库： + ```plain + ./rancher-load-images.ps1 --registry + ``` + +## Linux 步骤 + +Linux 镜像需要在 Linux 主机上收集和推送，但是你必须先将 Windows 镜像推送到私有镜像仓库，然后再推送 Linux 镜像。由于被推送的 Linux 镜像实际上是支持 Windows 和 Linux 镜像的 manifest，因此涉及的步骤不同于只包含 Linux 节点的集群。 + +1. 找到你的 Rancher 版本所需的资源 +2. 收集所有需要的镜像 +3. 将镜像保存到你的 Linux 工作站中 +4. 推送镜像到私有镜像仓库 + +### 先决条件 + +在将 Linux 镜像推送到私有镜像仓库之前，你必须先把 Windows 镜像推送到私有镜像仓库。如果你已经把 Linux 镜像推送到私有镜像仓库，则需要再次按照说明重新推送，因为它们需要发布支持 Windows 和 Linux 镜像的 manifest。 + +这些步骤要求你使用一个 Linux 工作站，该工作站需要可访问互联网和你的私有镜像仓库，且至少有 20GB 的可用磁盘空间。 + +工作站必须安装 Docker 18.02+ 版本以提供 manifest 支持。Manifest 支持是配置 Windows 集群所必须的。 + + + +### 1. 找到你的 Rancher 版本所需的资源 + +1. 访问 Rancher 的[发布说明](https://github.com/rancher/rancher/releases)页面，找到你需要安装的 Rancher v2.x.x 版本。不要下载带有 `rc` 或 `Pre-release` 标记的版本，因为这些版本在生产环境中不够稳定。点击 **Assets**。 + +2. 从你所需版本的 **Assets** 处下载以下文件： + +| Release 文件 | 描述 | +|----------------------------| -------------------------- | +| `rancher-images.txt` | 此文件包含安装 Rancher、配置集群和用户 Rancher 工具所需的镜像。 | +| `rancher-windows-images.txt` | 此文件包含配置 Windows 集群所需的镜像。 | +| `rancher-save-images.sh` | 该脚本从 Docker Hub 中拉取在文件 `rancher-images.txt` 中记录的所有镜像，并把这些镜像保存为 `rancher-images.tar.gz`。 | +| `rancher-load-images.sh` | 该脚本从 `rancher-images.tar.gz` 文件中加载镜像，并把镜像推送到你的私有镜像仓库。 | + + + +### 2. 收集所有需要的镜像 + +**在 Kubernetes 安装中，如果你使用的是 Rancher 默认的自签名 TLS 证书**，则必须将 [`cert-manager`](https://artifacthub.io/packages/helm/cert-manager/cert-manager) 镜像添加到 `rancher-images.txt` 文件中。如果你使用自己的证书，则可跳过此步骤。 + + +1. 获取最新的 `cert-manager` Helm Chart，并解析模板以获取镜像的详情信息： + + :::note + + 由于 cert-manager 的最新改动，你需要升级 cert-manager 版本。如果你需要升级 Rancher 并使用低于 0.12.0 的 cert-manager 版本，请参见[升级文档](../../resources/upgrade-cert-manager.md)。 + + ::: + + ```plain + helm repo add jetstack https://charts.jetstack.io + helm repo update + helm fetch jetstack/cert-manager + helm template ./cert-manager-.tgz | awk '$1 ~ /image:/ {print $2}' | sed s/\"//g >> ./rancher-images.txt + ``` + +2. 对镜像列表进行排序和唯一化，以去除重复的镜像源： + ```plain + sort -u rancher-images.txt -o rancher-images.txt + ``` + + + +### 3. 将镜像保存到你的工作站中 + +1. 为 `rancher-save-images.sh` 文件添加可执行权限： + ``` + chmod +x rancher-save-images.sh + ``` + +1. 使用 `rancher-images.txt` 镜像列表执行 `rancher-save-images.sh` 脚本，以创建包含所有所需镜像的压缩包： + ```plain + ./rancher-save-images.sh --image-list ./rancher-images.txt + ``` + +**结果**：Docker 开始拉取用于离线安装的镜像。请耐心等待。这个过程需要几分钟。完成时，你的当前目录会输出名为 `rancher-images.tar.gz` 的压缩包。请确认输出文件是否存在。 + + + +### 4. 推送镜像到私有镜像仓库 + +使用 `rancher-load-images.sh script` 脚本将 `rancher-images.tar.gz` 中的镜像移动到你的私有镜像仓库，以方便加载镜像。 + +镜像列表，即 `rancher-images.txt` 或 `rancher-windows-images.txt` 需要位于工作站中运行 `rancher-load-images.sh` 脚本的同一目录中。`rancher-images.tar.gz` 也需要位于同一目录中。 + +1. 登录到你的私有镜像仓库： + ```plain + docker login + ``` + +1. 为 `rancher-load-images.sh` 添加可执行权限： + ``` + chmod +x rancher-load-images.sh + ``` + +1. 使用 `rancher-load-images.sh` 脚本来提取，标记和推送 `rancher-images.tar.gz` 中的镜像到你的私有镜像仓库： + +```plain +./rancher-load-images.sh --image-list ./rancher-images.txt \ + --windows-image-list ./rancher-windows-images.txt \ + --registry +``` + + + + +### [Kubernetes 安装的后续步骤 - 启动 Kubernetes 集群](install-kubernetes.md) + +### [Docker 安装的后续步骤 - 安装 Rancher](install-rancher-ha.md) diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/installation-and-upgrade/other-installation-methods/other-installation-methods.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/installation-and-upgrade/other-installation-methods/other-installation-methods.md new file mode 100644 index 00000000000..f16dfc23d57 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/installation-and-upgrade/other-installation-methods/other-installation-methods.md @@ -0,0 +1,19 @@ +--- +title: 其他安装方式 +--- + +## 离线安装 + +按照[以下步骤](air-gapped-helm-cli-install/air-gapped-helm-cli-install.md)在离线环境中安装 Rancher Server。 + +离线环境可以是 Rancher Server 离线安装、防火墙后面或代理后面。 + +## Docker 安装 + +[单节点 Docker 安装](rancher-on-a-single-node-with-docker/rancher-on-a-single-node-with-docker.md)适用于想要测试 Rancher 的用户。你无需使用 Helm 在 Kubernetes 集群上运行 Rancher，你可以使用 `docker run` 命令，把 Rancher Server 组件安装到单个节点上。 + +Docker 安装仅用于开发和测试环境。 + +由于只有一个节点和一个 Docker 容器，因此，如果该节点发生故障，由于其他节点上没有可用的 etcd 数据副本，你将丢失 Rancher Server 的所有数据。 + +Rancher backup operator 可将 Rancher 从单个 Docker 容器迁移到高可用 Kubernetes 集群上。详情请参见[把 Rancher 迁移到新集群](../../../how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/migrate-rancher-to-new-cluster.md)。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/installation-and-upgrade/other-installation-methods/rancher-behind-an-http-proxy/install-kubernetes.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/installation-and-upgrade/other-installation-methods/rancher-behind-an-http-proxy/install-kubernetes.md new file mode 100644 index 00000000000..9cd840268f8 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/installation-and-upgrade/other-installation-methods/rancher-behind-an-http-proxy/install-kubernetes.md @@ -0,0 +1,103 @@ +--- +title: '2. 安装 Kubernetes' +--- + +基础设施配置好后，你可以设置一个 Kubernetes 集群来安装 Rancher。 + +设置 RKE2 或 K3s 的步骤如下所示。 + +为方便起见，将代理的 IP 地址和端口导出到一个环境变量中，并在每个节点上为你当前的 shell 设置 HTTP_PROXY 变量： + +``` +export proxy_host="10.0.0.5:8888" +export HTTP_PROXY=http://${proxy_host} +export HTTPS_PROXY=http://${proxy_host} +export NO_PROXY=127.0.0.0/8,10.0.0.0/8,cattle-system.svc,172.16.0.0/12,192.168.0.0/16 +``` + + + + +首先在 K3s systemd 服务上配置 HTTP 代理设置，让 K3s 的 containerd 可以通过代理拉取镜像： + +``` +cat <<'EOF' | sudo tee /etc/default/k3s > /dev/null +HTTP_PROXY=http://${proxy_host} +HTTPS_PROXY=http://${proxy_host}" +NO_PROXY=127.0.0.0/8,10.0.0.0/8,cattle-system.svc,172.16.0.0/12,192.168.0.0/16,.svc,.cluster.local +EOF +``` + +Rancher 需要安装在支持的 Kubernetes 版本上。如需了解你使用的 Rancher 版本支持哪些 Kubernetes 版本，请参见 [Rancher 支持矩阵](https://www.suse.com/suse-rancher/support-matrix/all-supported-versions/)。 + +如需指定 K3s（Kubernetes）版本，在运行 K3s 安装脚本时使用 `INSTALL_K3S_VERSION` 环境变量（例如 `INSTALL_K3S_VERSION="v1.24.10+k3s1"`）。 + +在第一个节点上，创建一个新集群： +``` +curl -sfL https://get.k3s.io | INSTALL_K3S_VERSION= K3S_TOKEN= sh -s - server --cluster-init +``` + +然后加入其他节点： +``` +curl -sfL https://get.k3s.io | INSTALL_K3S_VERSION= K3S_TOKEN= sh -s - server --server https://:6443 +``` + +其中 `` 是 Server 的 IP 或有效 DNS，`` 是可以在 `/var/lib/rancher/k3s/server/node-token` 中找到的 Server node-token。 + +有关安装 K3s 的更多信息，请参阅 [K3s 安装文档](https://docs.k3s.io/installation)。 + +如需查看集群，请运行以下命令： + +``` +kubectl cluster-info +kubectl get pods --all-namespaces +``` + + + + +在每个节点上，运行 RKE2 安装脚本。确保你安装的 RKE2 版本受 [Rancher 支持](https://www.suse.com/suse-rancher/support-matrix/all-supported-versions/)。 + +``` +curl -sfL https://get.rke2.io | INSTALL_RKE2_CHANNEL=v1.xx sh - +``` + +然后，你必须在 RKE2 systemd 服务上配置 HTTP 代理设置，让 RKE2 的 containerd 可以通过代理拉取镜像： + +``` +cat <<'EOF' | sudo tee /etc/default/rke2-server > /dev/null +HTTP_PROXY=http://${proxy_host} +HTTPS_PROXY=http://${proxy_host}" +NO_PROXY=127.0.0.0/8,10.0.0.0/8,cattle-system.svc,172.16.0.0/12,192.168.0.0/16,.svc,.cluster.local +EOF +``` + +接下来，按照 [RKE2 高可用性文档](https://docs.rke2.io/install/ha)在每个节点上创建 RKE2 配置文件。 + +之后启动并启用 `rke2-server` 服务： + +``` +systemctl enable rke2-server.service +systemctl start rke2-server.service +``` + +有关安装 RKE2 的更多信息，请参阅 [RKE2 文档](https://docs.rke2.io)。 + +如需查看集群，请运行以下命令： + +``` +export KUBECONFIG=/etc/rancher/rke2/rke2.yaml +alias kubectl=/var/lib/rancher/rke2/bin/kubectl +kubectl cluster-info +kubectl get pods --all-namespaces +``` + + + + +### 故障排除 + +参见[故障排除](../../install-upgrade-on-a-kubernetes-cluster/troubleshooting.md)页面。 + +### 后续操作 +[安装 Rancher](install-rancher.md) diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/installation-and-upgrade/other-installation-methods/rancher-behind-an-http-proxy/install-rancher.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/installation-and-upgrade/other-installation-methods/rancher-behind-an-http-proxy/install-rancher.md new file mode 100644 index 00000000000..af41595c6a1 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/installation-and-upgrade/other-installation-methods/rancher-behind-an-http-proxy/install-rancher.md @@ -0,0 +1,106 @@ +--- +title: 3. 安装 Rancher +--- + +在前文的操作后，你已经有了一个运行的 RKE2/K3s 集群，现在可以在其中安装 Rancher 了。出于安全考虑，所有到 Rancher 的流量都必须使用 TLS 加密。在本教程中，你将使用 [cert-manager](https://cert-manager.io/)自动颁发自签名证书。在实际使用情况下，你可使用 Let's Encrypt 或自己的证书。 + +## 安装 Helm CLI + + + +在具有 kubeconfig 的主机上安装 [Helm](https://helm.sh/docs/intro/install/) CLI 以访问 Kubernetes 集群： + +``` +curl -fsSL -o get_helm.sh https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 +chmod +x get_helm.sh +sudo ./get_helm.sh +``` + +## 安装 cert-manager + +添加 cert-manager Helm 仓库： + +``` +helm repo add jetstack https://charts.jetstack.io +``` + +为 cert-manager 创建命名空间： + +``` +kubectl create namespace cert-manager +``` + +安装 cert-manager 的 CustomResourceDefinitions： + +``` +kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download//cert-manager.crds.yaml +``` + +使用 Helm 安装 cert-manager。请注意，cert-manager 还需要你配置代理，以防它需要与 Let's Encrypt 或其他外部证书颁发商进行通信： + +:::note + +要查看自定义 cert-manager 安装的选项（包括集群使用 PodSecurityPolicies 的情况），请参阅 [cert-manager 文档](https://artifacthub.io/packages/helm/cert-manager/cert-manager#configuration)。 + +::: + +``` +helm upgrade --install cert-manager jetstack/cert-manager \ + --namespace cert-manager \ + --set http_proxy=http://${proxy_host} \ + --set https_proxy=http://${proxy_host} \ + --set no_proxy=127.0.0.0/8\\,10.0.0.0/8\\,cattle-system.svc\\,172.16.0.0/12\\,192.168.0.0/16\\,.svc\\,.cluster.local +``` + +等待 cert-manager 完成启动： + +``` +kubectl rollout status deployment -n cert-manager cert-manager +kubectl rollout status deployment -n cert-manager cert-manager-webhook +``` + +## 安装 Rancher + +接下来，你可以安装 Rancher 了。首先，添加 Helm 仓库： + +``` +helm repo add rancher-latest https://releases.rancher.com/server-charts/latest +``` + +创建命名空间： + +``` +kubectl create namespace cattle-system +``` + +然后使用 Helm 安装 Rancher：Rancher 也需要你配置代理，以便它可以与外部应用商店通信，或检索 Kubernetes 版本更新元数据： + +``` +helm upgrade --install rancher rancher-latest/rancher \ + --namespace cattle-system \ + --set hostname=rancher.example.com \ + --set proxy=http://${proxy_host} \ + --set noProxy=127.0.0.0/8\\,10.0.0.0/8\\,cattle-system.svc\\,172.16.0.0/12\\,192.168.0.0/16\\,.svc\\,.cluster.local +``` + +等待部署完成： + +``` +kubectl rollout status deployment -n cattle-system rancher +``` + +现在，你可以导航到 `https://rancher.example.com` 并开始使用 Rancher。 + +:::caution + +如果你不想发送遥测数据，在首次登录时退出[遥测](../../../../faq/telemetry.md)。如果在离线安装的环境中让这个功能处于 active 状态，socket 可能无法打开。 + +::: + +## 其他资源 + +以下资源可能对安装 Rancher 有帮助： + +- [Rancher Helm Chart 选项](../../installation-references/helm-chart-options.md) +- [添加 TLS 密文](../../resources/add-tls-secrets.md) +- [Rancher Kubernetes 安装的故障排除](../../install-upgrade-on-a-kubernetes-cluster/troubleshooting.md) diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/installation-and-upgrade/other-installation-methods/rancher-behind-an-http-proxy/rancher-behind-an-http-proxy.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/installation-and-upgrade/other-installation-methods/rancher-behind-an-http-proxy/rancher-behind-an-http-proxy.md new file mode 100644 index 00000000000..1701dba329e --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/installation-and-upgrade/other-installation-methods/rancher-behind-an-http-proxy/rancher-behind-an-http-proxy.md @@ -0,0 +1,13 @@ +--- +title: 使用 HTTP 代理安装 Rancher +--- + +很多企业本地运行的服务器或虚拟机不能直接访问互联网，但是出于安全考虑，他们必须通过 HTTP(S) 代理连接到外部服务。本教程将分步介绍如何在这样的环境中进行高可用的 Rancher 安装。 + +另外，用户也可以在没有任何互联网访问的情况下离线设置 Rancher。详情请参见 [Rancher 官方文档](../air-gapped-helm-cli-install/air-gapped-helm-cli-install.md)。 + +## 安装概要 + +1. [配置基础设施](set-up-infrastructure.md) +2. [配置 Kubernetes 集群](install-kubernetes.md) +3. [安装 Rancher](install-rancher.md) diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/installation-and-upgrade/other-installation-methods/rancher-behind-an-http-proxy/set-up-infrastructure.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/installation-and-upgrade/other-installation-methods/rancher-behind-an-http-proxy/set-up-infrastructure.md new file mode 100644 index 00000000000..9b226f6ead1 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/installation-and-upgrade/other-installation-methods/rancher-behind-an-http-proxy/set-up-infrastructure.md @@ -0,0 +1,64 @@ +--- +title: '1. 配置基础设施' +--- + +在本节中，你将为 Rancher Management Server 配置底层基础设施，并使其通过 HTTP 代理访问互联网。 + +如需在高可用 RKE2/K3s 集群中安装 Rancher Management Server，我们建议配置以下基础设施： + +- **3 个 Linux 节点**：可以是你的云提供商（例如 Amazon EC2，GCE 或 vSphere）中的虚拟机。 +- **1 个负载均衡器**：用于将前端流量转发到这三个节点中。 +- **1 个 DNS 记录**：用于将 URL 映射到负载均衡器。此 DNS 记录将成为 Rancher Server 的 URL，下游集群需要可以访问到这个地址。 + +这些节点必须位于同一个区域或数据中心。但是你可以把这些服务器放在不同的可用区。 + +## 为什么使用三个节点？ + +在 RKE2/K3s 集群中，Rancher Server 的数据存储在 etcd 中。而这个 etcd 数据库在这三个节点上运行。 + +为了选举出大多数 etcd 节点认可的 etcd 集群 leader，etcd 数据库需要奇数个节点。如果 etcd 数据库无法选出 leader，etcd 可能会出现[脑裂（split brain）](https://www.quora.com/What-is-split-brain-in-distributed-systems)的问题，此时你需要使用备份恢复集群。如果三个 etcd 节点之一发生故障，其余两个节点可以选择一个 leader，因为它们是 etcd 节点总数的大多数部分。 + +## 1. 配置 Linux 节点 + +这些主机将通过 HTTP 代理连接到互联网。 + +请确保你的节点满足[操作系统，容器运行时，硬件和网络](../../installation-requirements/installation-requirements.md)的常规要求。 + +如需获取配置 Linux 节点的示例，请参见[在 Amazon EC2 中配置节点](../../../../how-to-guides/new-user-guides/infrastructure-setup/nodes-in-amazon-ec2.md)的教程。 + +## 2. 配置负载均衡器 + +你还需要设置一个负载均衡器，来将流量重定向到两个节点上的 Rancher 副本。配置后，当单个节点不可用时，继续保障与 Rancher Management Server 的通信。 + +在后续步骤中配置 Kubernetes 时，RKE2/K3s 工具会部署一个 NGINX Ingress Controller。该 Controller 将侦听 worker 节点的 80 端口和 443 端口，以响应发送给特定主机名的流量。 + +在安装 Rancher 后（也是在后续步骤中），Rancher 系统将创建一个 Ingress 资源。该 Ingress 通知 NGINX Ingress Controller 监听发往 Rancher 主机名的流量。NGINX Ingress Controller 在收到发往 Rancher 主机名的流量时，会将其转发到集群中正在运行的 Rancher Server Pod。 + +在你的实现中，你可以考虑是否需要使用 4 层或 7 层的负载均衡器： + +- **4 层负载均衡器**：两种选择中较为简单的一种，它将 TCP 流量转发到你的节点中。我们建议使用 4 层负载均衡器，将流量从 TCP/80 端口和 TCP/443 端口转发到 Rancher Management 集群节点上。集群上的 Ingress Controller 会将 HTTP 流量重定向到 HTTPS，并在 TCP/443 端口上终止 SSL/TLS。Ingress Controller 会将流量转发到 Rancher deployment 中 Ingress Pod 的 TCP/80 端口。 +- **7 层负载均衡器**：相对比较复杂，但功能更全面。例如，与 Rancher 本身进行 TLS 终止相反，7 层负载均衡器能够在负载均衡器处处理 TLS 终止。如果你需要集中在基础设施中进行 TLS 终止，7 层负载均衡可能会很适合你。7 层负载均衡还能让你的负载均衡器基于 HTTP 属性（例如 cookie 等）做出决策，而 4 层负载均衡器则不能。如果你选择在 7 层负载均衡器上终止 SSL/TLS 流量，则在安装 Rancher 时（后续步骤）需要使用 `--set tls=external` 选项。详情请参见 [Rancher Helm Chart 选项](../../installation-references/helm-chart-options.md#外部-tls-终止)。 + +如需获取配置 NGINX 负载均衡器的示例，请参见[本页](../../../../how-to-guides/new-user-guides/infrastructure-setup/nginx-load-balancer.md)。 + +如需获取如何配置 Amazon ELB 网络负载均衡器的指南，请参见[本页](../../../../how-to-guides/new-user-guides/infrastructure-setup/amazon-elb-load-balancer.md)。 + +:::note 重要提示： + +安装后，请勿将此负载均衡（例如 `local` 集群 Ingress）用于 Rancher 以外的应用。如果此 Ingress 与其他应用共享，在其他应用的 Ingress 配置重新加载后，可能导致 Rancher 出现 websocket 错误。我们建议把 `local` 集群专用给 Rancher，不要在集群内部署其他应用。 + +::: + +## 3. 配置 DNS 记录 + +配置完负载均衡器后，你将需要创建 DNS 记录，以将流量发送到该负载均衡器。 + +根据你的环境，DNS 记录可以是指向负载均衡器 IP 的 A 记录，也可以是指向负载均衡器主机名的 CNAME。无论是哪种情况，请确保该记录是你要 Rancher 进行响应的主机名。 + +在安装 Rancher 时（后续步骤），你需要指定此主机名。请知悉，此主机名无法修改。请确保你设置的主机名是你想要的。 + +有关设置 DNS 记录以将域流量转发到 Amazon ELB 负载均衡器的指南，请参见 [AWS 官方文档](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/routing-to-elb-load-balancer)。 + + +## 后续操作 +[配置 Kubernetes 集群](install-kubernetes.md) diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/certificate-troubleshooting.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/certificate-troubleshooting.md new file mode 100644 index 00000000000..992fd0b55e2 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/certificate-troubleshooting.md @@ -0,0 +1,92 @@ +--- +title: 证书故障排除 +--- + + + +## 如何确定我的证书格式是否为 PEM？ + +你可以通过以下特征识别 PEM 格式： + +- 文件开始的标头： + ``` + -----BEGIN CERTIFICATE----- + ``` +- 表头后跟一长串字符。 +- 文件结束的页脚： + ``` + -----END CERTIFICATE----- + ``` + +PEM 证书示例： + +``` +----BEGIN CERTIFICATE----- +MIIGVDCCBDygAwIBAgIJAMiIrEm29kRLMA0GCSqGSIb3DQEBCwUAMHkxCzAJBgNV +... more lines +VWQqljhfacYPgp8KJUJENQ9h5hZ2nSCrI+W00Jcw4QcEdCI8HL5wmg== +-----END CERTIFICATE----- +``` + +PEM 证书密钥示例： + +``` +-----BEGIN RSA PRIVATE KEY----- +MIIGVDCCBDygAwIBAgIJAMiIrEm29kRLMA0GCSqGSIb3DQEBCwUAMHkxCzAJBgNV +... more lines +VWQqljhfacYPgp8KJUJENQ9h5hZ2nSCrI+W00Jcw4QcEdCI8HL5wmg== +-----END RSA PRIVATE KEY----- +``` + +如果你的密钥与以下示例类似，请参见[将 PKCS8 证书密钥转换为 PKCS1](#将-pkcs8-证书密钥转换为-pkcs1)。 + +``` +-----BEGIN PRIVATE KEY----- +MIIGVDCCBDygAwIBAgIJAMiIrEm29kRLMA0GCSqGSIb3DQEBCwUAMHkxCzAJBgNV +... more lines +VWQqljhfacYPgp8KJUJENQ9h5hZ2nSCrI+W00Jcw4QcEdCI8HL5wmg== +-----END PRIVATE KEY----- +``` + +## 将 PKCS8 证书密钥转换为 PKCS1 + +如果你使用的是 PKCS8 证书密钥文件，Rancher 将打印以下日志： + +``` +ListenConfigController cli-config [listener] failed with : failed to read private key: asn1: structure error: tags don't match (2 vs {class:0 tag:16 length:13 isCompound:true}) +``` + +为了能正常工作，你需要运行以下命令，将密钥从 PKCS8 转换为 PKCS1： + +``` +openssl rsa -in key.pem -out convertedkey.pem +``` + +你可使用 `convertedkey.pem` 作为 Rancher 证书密钥文件。 + +## 添加中间证书的顺序是什么？ + +添加证书的顺序如下： + +``` +-----BEGIN CERTIFICATE----- +%YOUR_CERTIFICATE% +-----END CERTIFICATE----- +-----BEGIN CERTIFICATE----- +%YOUR_INTERMEDIATE_CERTIFICATE% +-----END CERTIFICATE----- +``` + +## 如何验证我的证书链？ + +你可使用 `openssl` 二进制文件来验证证书链。如果命令的输出以 `Verify return code: 0 (ok)` 结尾（参见以下示例），你的证书链是有效的。`ca.pem` 文件必须与你添加到 `rancher/rancher` 容器中的文件一致。 + +如果你使用由可信的 CA 签发的证书，可省略 `-CAfile` 参数。 + +命令： + +``` +openssl s_client -CAfile ca.pem -connect rancher.yourdomain.com:443 +... + Verify return code: 0 (ok) +``` diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/rancher-on-a-single-node-with-docker.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/rancher-on-a-single-node-with-docker.md new file mode 100644 index 00000000000..ae91e251294 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/rancher-on-a-single-node-with-docker.md @@ -0,0 +1,209 @@ +--- +title: 使用 Docker 将 Rancher 安装到单个节点中 +description: 在开发和测试环境中，你可以使用 Docker 安装。在单个 Linux 主机上安装 Docker，然后使用一个 Docker 容器部署 Rancher。 +--- + + + +Rancher 可以通过运行单个 Docker 容器进行安装。 + +在这种安装方案中，你需要将 Docker 安装到单个 Linux 主机，然后使用单个 Docker 容器将 Rancher 部署到主机中。 + +:::note 想要使用外部负载均衡器？ + +请参阅[使用外部负载均衡器的 Docker 安装](../../../../how-to-guides/advanced-user-guides/configure-layer-7-nginx-load-balancer.md)。 + +::: + +Rancher 的 Docker 安装仅推荐用于开发和测试环境中。Rancher 版本决定了能否将 Rancher 迁移到高可用集群。 + +Rancher backup operator 可将 Rancher 从单个 Docker 容器迁移到高可用 Kubernetes 集群上。详情请参见[把 Rancher 迁移到新集群](../../../../how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/migrate-rancher-to-new-cluster.md)。 + +## Rancher 特权访问 + +当 Rancher Server 部署在 Docker 容器中时，容器内会安装一个本地 Kubernetes 集群供 Rancher 使用。为 Rancher 的很多功能都是以 deployment 的方式运行的，而在容器内运行容器是需要特权模式的，因此你需要在安装 Rancher 时添加 `--privileged` 选项。 + +## 操作系统，Docker，硬件和网络要求 + +请确保你的节点满足常规的[安装要求](../../installation-requirements/installation-requirements.md)。 + +## 1. 配置 Linux 主机 + +按照[要求](../../installation-requirements/installation-requirements.md)配置一个 Linux 主机，用于运行 Rancher Server。 + +## 2. 选择一个 SSL 选项并安装 Rancher + +出于安全考虑，使用 Rancher 时请使用 SSL（Secure Sockets Layer）。SSL 保护所有 Rancher 网络通信（如登录和与集群交互）的安全。 + +:::tip 你是否需要： + +- 使用代理。参见 [HTTP 代理配置](../../../../reference-guides/single-node-rancher-in-docker/http-proxy-configuration.md)。 +- 配置自定义 CA 根证书以访问服务。参见[自定义 CA 根证书](../../../../reference-guides/single-node-rancher-in-docker/advanced-options.md#自定义-ca-证书)。 +- 完成离线安装。参见 [离线：Docker 安装](../air-gapped-helm-cli-install/air-gapped-helm-cli-install.md)。 +- 记录所有 Rancher API 的事务。参加 [API 审计](../../../../reference-guides/single-node-rancher-in-docker/advanced-options.md#api-审计日志)。 + +::: + +选择以下的选项之一： + +- [选项 A：使用 Rancher 生成的默认自签名证书](#选项-a使用-rancher-生成的默认自签名证书) +- [选项 B：使用你自己的证书 - 自签名](#选项-b使用你自己的证书---自签名) +- [选项 C：使用你自己的证书 - 可信 CA 签名的证书](#选项-c使用你自己的证书---可信-ca-签名的证书) +- [选项 D：Let's Encrypt 证书](#选项-dlets-encrypt-证书) +- [选项 E：Localhost 隧道，不使用证书](#选项-elocalhost-隧道不使用证书) + +### 选项 A：使用 Rancher 生成的默认自签名证书 + +如果你在不考虑身份验证的开发或测试环境中安装 Rancher，可以使用 Rancher 生成的自签名证书安装 Rancher。这种安装方式避免了自己生成证书的麻烦。 + +登录到你的主机，然后运行以下命令： + +``` +docker run -d --restart=unless-stopped \ + -p 80:80 -p 443:443 \ + --privileged \ + rancher/rancher:latest +``` + +### 选项 B：使用你自己的证书 - 自签名 +在你团队访问 Rancher Server 的开发或测试环境中，创建一个用于你的安装的自签名证书，以便团队验证他们对实例的连接。 + +:::note 先决条件： + +使用 [OpenSSL](https://www.openssl.org/) 或其他方法创建自签名证书。 + +- 证书文件的格式必须是 PEM。 +- 在你的证书文件中，包括链中的所有中间证书。你需要对你的证书进行排序，把你的证书放在最前面，后面跟着中间证书。如需查看示例，请参见[证书故障排除](./certificate-troubleshooting.md)。 + +::: + +创建证书后，运行以下 Docker 命令以安装 Rancher。使用 `-v` 标志并提供证书的路径，以将证书挂载到容器中。 + +| 占位符 | 描述 | +| ------------------- | --------------------- | +| `` | 包含证书文件的目录的路径。 | +| `` | 完整证书链的路径。 | +| `` | 证书私钥的路径。 | +| `` | CA 证书的路径。 | + +登录到你的主机，然后运行以下命令： + +``` +docker run -d --restart=unless-stopped \ + -p 80:80 -p 443:443 \ + -v //:/etc/rancher/ssl/cert.pem \ + -v //:/etc/rancher/ssl/key.pem \ + -v //:/etc/rancher/ssl/cacerts.pem \ + --privileged \ + rancher/rancher:latest +``` + +### 选项 C：使用你自己的证书 - 可信 CA 签名的证书 + +在公开暴露应用的生产环境中，请使用由可信 CA 签名的证书，以避免用户收到证书安全警告。 + +不建议将 Docker 安装用于生产环境。这些说明仅适用于测试和开发。 + +:::note 先决条件： + +- 证书文件的格式必须是 PEM。 +- 在你的证书文件中，包括可信 CA 提供的所有中间证书。你需要对你的证书进行排序，把你的证书放在最前面，后面跟着中间证书。如需查看示例，请参见[证书故障排除](./certificate-troubleshooting.md)。 + +::: + +获取证书后，运行以下 Docker 命令。 + +- 使用 `-v` 标志并提供证书的路径，以将证书挂载到容器中。因为你的证书是由可信的 CA 签名的，因此你不需要安装额外的 CA 证书文件。 +- 使用 `--no-cacerts` 作为容器的参数，以禁用 Rancher 生成的默认 CA 证书。 + +| 占位符 | 描述 | +| ------------------- | ----------------------------- | +| `` | 包含证书文件的目录的路径。 | +| `` | 完整证书链的路径。 | +| `` | 证书私钥的路径。 | + +登录到你的主机，然后运行以下命令： + +``` +docker run -d --restart=unless-stopped \ + -p 80:80 -p 443:443 \ + -v //:/etc/rancher/ssl/cert.pem \ + -v //:/etc/rancher/ssl/key.pem \ + --privileged \ + rancher/rancher:latest \ + --no-cacerts +``` + +### 选项 D：Let's Encrypt 证书 + +:::caution + +Let's Encrypt 对新证书请求有频率限制。因此，请限制创建或销毁容器的频率。详情请参见 [Let's Encrypt 官方文档 - 频率限制](https://letsencrypt.org/docs/rate-limits/)。 + +::: + +你也可以在生产环境中使用 [Let's Encrypt](https://letsencrypt.org/) 证书。Let's Encrypt 使用 HTTP-01 质询来验证你对域名的控制权。如果要确认你对该域名有控制权，你可将用于访问 Rancher 的主机名（例如 `rancher.mydomain.com`）指向运行的主机的 IP。你可通过在 DNS 中创建 A 记录，以将主机名绑定到 IP 地址。 + +不建议将 Docker 安装用于生产环境。这些说明仅适用于测试和开发。 + +:::note 先决条件： + +- Let's Encrypt 是联网服务。因此，在内网和离线环境中不能使用。 +- 在 DNS 中创建一条记录，将 Linux 主机 IP 地址绑定到要用于访问 Rancher 的主机名（例如，`rancher.mydomain.com`）。 +- 在 Linux 主机上打开 `TCP/80` 端口。Let's Encrypt 的 HTTP-01 质询可以来自任何源 IP 地址，因此端口 `TCP/80` 必须开放开所有 IP 地址。 + +::: + +满足先决条件后，你可以运行以下命令使用 Let's Encrypt 证书安装 Rancher。 + +| 占位符 | 描述 | +| ----------------- | ------------------- | +| `` | 你的域名地址 | + +登录到你的主机，然后运行以下命令： + +``` +docker run -d --restart=unless-stopped \ + -p 80:80 -p 443:443 \ + --privileged \ + rancher/rancher:latest \ + --acme-domain +``` + +### 选项 E：Localhost 隧道，不使用证书 + +如果你在开发或测试环境中安装 Rancher，且环境中有运行的 localhost 隧道解决方案（如 [ngrok](https://ngrok.com/)），不要生成证书。此安装选项不需要证书。 + +- 使用 `--no-cacerts` 作为参数，以禁用 Rancher 生成的默认 CA 证书。 + +登录到你的主机，然后运行以下命令： + +``` +docker run -d --restart=unless-stopped \ + -p 80:80 -p 443:443 \ + --privileged \ + rancher/rancher:latest \ + --no-cacerts +``` + +## 高级选项 + +使用 Docker 将 Rancher 安装到单个节点时，有如下几个可开启的高级选项： + +- 自定义 CA 证书 +- API 审计日志 +- TLS 设置 +- 离线环境 +- 持久化数据 +- 在同一个节点中运行 `rancher/rancher` 和 `rancher/rancher-agent` + +详情请参见[本页](../../../../reference-guides/single-node-rancher-in-docker/advanced-options.md)。 + +## 故障排除 + +如需了解常见问题及故障排除提示，请参见[本页](certificate-troubleshooting.md)。 + +## 后续操作 + +- **推荐**：检查单节点[备份](../../../../how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/back-up-docker-installed-rancher.md)和[恢复](../../../../how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/restore-docker-installed-rancher.md)。你可能暂时没有需要备份的数据，但是我们建议你在常规使用 Rancher 后创建备份。 +- 创建 Kubernetes 集群：[配置 Kubernetes 集群](../../../../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/kubernetes-clusters-in-rancher-setup.md)。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/roll-back-docker-installed-rancher.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/roll-back-docker-installed-rancher.md new file mode 100644 index 00000000000..762ec2bd1a5 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/roll-back-docker-installed-rancher.md @@ -0,0 +1,93 @@ +--- +title: 回滚 Docker 安装的 Rancher +--- + + + +如果 Rancher 升级没有成功完成，你需要回滚到你在 [Docker 升级](upgrade-docker-installed-rancher.md)之前使用的 Rancher 设置。回滚可以恢复： + +- 先前版本的 Rancher。 +- 升级前创建的数据备份。 + +## 在你开始前 + +在回滚到先前 Rancher 版本的过程中，你将输入一系列命令。请按照你环境的实际情况替换占位符。占位符用尖括号和大写字母（如 ``）表示。以下是带有占位符的命令示例： + +``` +docker pull rancher/rancher: +``` + +在此命令中，`` 是升级失败之前运行的 Rancher 版本，如 `v2.0.5`。 + +请交叉参考下方的图片和表格，了解获取此占位符数据的方法。在开始以下步骤之前，请先记下或复制此信息。 + +终端 docker ps 命令，显示如何找到 <PRIOR_RANCHER_VERSION> 和 <RANCHER_CONTAINER_NAME>![占位符参考](/img/placeholder-ref-2.png) + +| 占位符 | 示例 | 描述 | +| -------------------------- | -------------------------- | ------------------------------------------------------- | +| `` | `v2.0.5` | 升级前使用的 rancher/rancher 镜像。 | +| `` | `festive_mestorf` | 你的 Rancher 容器的名称。 | +| `` | `v2.0.5` | 备份对应的 Rancher 版本。 | +| `` | `9-27-18` | 数据容器或备份的创建日期。 | +
+ +可以通过远程连接登录到 Rancher Server 所在的主机并输入命令 `docker ps` 以查看正在运行的容器，从而获得 `` 和 `` 。你还可以运行 `docker ps -a` 命令查看停止了的容器。在创建备份期间，你随时可以运行这些命令来获得帮助。 + +## 回滚 Rancher + +如果你在升级 Rancher 时遇到问题，你可拉取先前使用的镜像并恢复在升级前所做的备份，从而将 Rancher 回滚到之前的正常工作状态。 + +:::danger + +回滚到先前的 Rancher 版本会破坏你在升级后对 Rancher 做出的所有更改。丢失的数据可能无法恢复。 + +::: + +1. 使用远程终端连接，登录到运行 Rancher Server 的节点。 + +1. 拉取升级前运行的 Rancher 版本。把 `` 替换为该版本。 + + 例如，如果升级之前运行的是 Rancher v2.0.5，请拉取 v2.0.5。 + + ``` + docker pull rancher/rancher: + ``` + +1. 停止当前运行 Rancher Server 的容器。将 `` 替换为你的 Rancher 容器的名称： + + ``` + docker stop + ``` + 你可输入 `docker ps`获取 Rancher 容器的名称。 + +1. 将你在 [Docker 升级](upgrade-docker-installed-rancher.md)时创建的备份压缩包移动到 Rancher Server。切换到你将其移动到的目录。输入 `dir` 以确认它在该位置。 + + 如果你遵循了我们在 [Docker 升级](upgrade-docker-installed-rancher.md)中推荐的命名方式，它的名称会与 `rancher-data-backup--.tar.gz` 类似。 + +1. 替换占位符来运行以下命令，将 `rancher-data` 容器中的数据替换为备份压缩包中的数据。不要忘记关闭引号。 + + ``` + docker run --volumes-from rancher-data \ + -v $PWD:/backup busybox sh -c "rm /var/lib/rancher/* -rf \ + && tar zxvf /backup/rancher-data-backup--.tar.gz" + ``` + +1. 将 `` 占位符指向数据容器，启动一个新的 Rancher Server 容器。 + ``` + docker run -d --volumes-from rancher-data \ + --restart=unless-stopped \ + -p 80:80 -p 443:443 \ + --privileged \ + rancher/rancher: + ``` + 特权访问是[必须](rancher-on-a-single-node-with-docker.md#rancher-特权访问)的。 + + :::danger + + 启动回滚后，即使回滚耗时比预期长，也 **_不要_** 停止回滚。如果你停止回滚，可能会导致之后的升级中出现数据库错误。 + + ::: + +1. 等待片刻，然后在浏览器中打开 Rancher。确认回滚成功并且你的数据已恢复。 + +**结果**：Rancher 回滚到升级前的版本和数据状态。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/upgrade-docker-installed-rancher.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/upgrade-docker-installed-rancher.md new file mode 100644 index 00000000000..9232b9a6d02 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/upgrade-docker-installed-rancher.md @@ -0,0 +1,393 @@ +--- +title: 升级 Docker 安装的 Rancher +--- + +本文介绍如何升级通过 Docker 安装的 Rancher Server。 + +:::caution + +**生产环境不支持 Docker 安装**。这些说明仅适用于测试和开发。如果你已经在生产环境中部署了 Docker 安装并且需要升级到新的 Rancher 版本，我们建议你在升级前先[迁移到 Helm Chart 安装](../../../../how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/migrate-rancher-to-new-cluster.md)。 + +::: + +## 先决条件 + +- 在 Rancher 文档中**检查[已知升级问题](../../install-upgrade-on-a-kubernetes-cluster/upgrades.md#已知升级问题)**，了解升级 Rancher 时最需要注意的问题。你可以在 [GitHub](https://github.com/rancher/rancher/releases) 发布说明以及 [Rancher 论坛](https://forums.rancher.com/c/announcements/12)中找到每个 Rancher 版本的已知问题。不支持升级或升级到 [rancher-alpha 仓库](../../resources/choose-a-rancher-version.md#helm-chart-仓库)中的任何 Chart。 +- **[仅适用于离线安装](../air-gapped-helm-cli-install/air-gapped-helm-cli-install.md)：为新的 Rancher Server 版本收集和推送镜像**。按照指南为你想要升级的目标 Rancher 版本[推送镜像到私有镜像仓库](../air-gapped-helm-cli-install/publish-images.md)。 + +## 占位符 + +在升级过程中，你将输入一系列命令。请按照你环境的实际情况替换占位符。占位符用尖括号和大写字母（如 ``）表示。 + +以下是带有占位符的命令**示例**： + +``` +docker stop +``` + +在此命令中，`` 是你的 Rancher 容器的名称。 + +## 获取升级命令的数据 + +要获取替换占位符的数据，请运行： + +``` +docker ps +``` + +在开始升级之前记下或复制此信息。 + +终端 docker ps 命令，显示如何找到 <RANCHER_CONTAINER_TAG> 和 <RANCHER_CONTAINER_NAME> + +![占位符参考](/img/placeholder-ref.png) + +| 占位符 | 示例 | 描述 | +| -------------------------- | -------------------------- | --------------------------------------------------------- | +| `` | `v2.1.3` | 首次安装拉取的 rancher/rancher 镜像。 | +| `` | `festive_mestorf` | 你的 Rancher 容器的名称。 | +| `` | `v2.1.3` | 你为其创建备份的 Rancher 版本。 | +| `` | `2018-12-19` | 数据容器或备份的创建日期。 | +
+ +可以通过远程连接登录到 Rancher Server 所在的主机并输入命令 `docker ps` 以查看正在运行的容器，从而获得 `` 和 ``。你还可以运行 `docker ps -a` 命令查看停止了的容器。在创建备份期间，你随时可以运行这些命令来获得帮助。 + +## 升级 + +在升级期间，你可以为当前 Rancher 容器创建数据的副本及备份，以确保可以在升级出现问题时可以进行回滚。然后，你可使用现有数据将新版本的 Rancher 部署到新容器中。 +### 1. 创建 Rancher Server 容器的数据副本 + +1. 使用远程终端连接，登录到运行 Rancher Server 的节点。 + +1. 停止正在运行 Rancher Server 的容器。将 `` 替换为你的 Rancher 容器的名称： + + ``` + docker stop + ``` + +1. 运行以下命令，从刚才停止的 Rancher 容器创建一个数据容器。请替换命令中的占位符： + + ``` + docker create --volumes-from --name rancher-data rancher/rancher: + ``` + +### 2. 创建备份压缩包 + +1. 从你刚刚创建的数据容器（rancher-data）中，创建一个备份 tar 包（rancher-data-backup-<RANCHER_VERSION>-<DATE>.tar.gz）。 + + 如果升级期间出现问题，此压缩包可以用作回滚点。替换占位符来运行以下命令。 + ``` + docker run --volumes-from rancher-data -v "$PWD:/backup" --rm busybox tar zcvf /backup/rancher-data-backup--.tar.gz /var/lib/rancher + ``` + + **步骤结果**：你输入此命令时，会运行一系列命令。 + +1. 输入 `ls` 命令，确认备份压缩包已创建成功。压缩包的名称格式类似 `rancher-data-backup--.tar.gz`。 + + ``` + [rancher@ip-10-0-0-50 ~]$ ls + rancher-data-backup-v2.1.3-20181219.tar.gz + ``` + +1. 将备份压缩包移动到 Rancher Server 外的安全位置。 + +### 3. 拉取新的 Docker 镜像 + +拉取你需要升级到的 Rancher 版本镜像。 + +| 占位符 | 描述 | +------------|------------- +| `` | 你想要升级到的 [Rancher 版本](../../installation-references/helm-chart-options.md)的版本标签。 | + +``` +docker pull rancher/rancher: +``` + +### 4. 启动新的 Rancher Server 容器 + +使用 `rancher-data` 容器中的数据启动一个新的 Rancher Server 容器。记住要传入启动原始容器时使用的所有环境变量。 + +:::danger + +启动升级后，即使升级耗时比预期长，也 **_不要_** 停止升级。如果你停止升级，可能会导致之后的升级中出现数据库迁移错误。 + +::: + +如果你使用代理，请参见 [HTTP 代理配置](../../../../reference-guides/single-node-rancher-in-docker/http-proxy-configuration.md)。 + +如果你配置了自定义 CA 根证书来访问服务，请参见[自定义 CA 根证书](../../../../reference-guides/single-node-rancher-in-docker/advanced-options.md#自定义-ca-证书)。 + +如果你要记录所有 Rancher API 的事务，请参见 [API 审计](../../../../reference-guides/single-node-rancher-in-docker/advanced-options.md#api-审计日志)。 + +如需查看启动新 Rancher Server 容器时使用的命令，从以下的选项中进行选择： + +- Docker 升级 +- 离线安装的 Docker 升级 + + + + +选择你安装 Rancher Server 时用的选项 + +#### 选项 A：使用 Rancher 默认的自签名证书 + +
+ 单击展开 + +如果你使用 Rancher 生成的自签名证书，则将 `--volumes-from rancher-data` 添加到你启动原始 Rancher Server 容器的命令中。 + +| 占位符 | 描述 | +------------|------------- +| `` | 你想要升级到的 [Rancher 版本](../../installation-references/helm-chart-options.md)的版本标签。 | + +``` +docker run -d --volumes-from rancher-data \ + --restart=unless-stopped \ + -p 80:80 -p 443:443 \ + --privileged \ + rancher/rancher: +``` + +特权访问是[必须](./rancher-on-a-single-node-with-docker.md#rancher-特权访问)的。 + +
+ +#### 选项 B：使用你自己的证书 - 自签名 + +
+单击展开 + +如果你选择使用自己的自签名证书，则在启动原始 Rancher Server 容器的命令中添加 `--volumes-from rancher-data`。此外，你需要能够访问你原始安装时使用的证书。 + +:::note 证书要求提示： + +证书文件的格式必须是 PEM。在你的证书文件中，包括链中的所有中间证书。你需要对你的证书进行排序，把你的证书放在最前面，后面跟着中间证书。 + +::: + +| 占位符 | 描述 | +------------|------------- +| `` | 包含证书文件的目录的路径。 | +| `` | 完整证书链的路径。 | +| `` | 证书私钥的路径。 | +| `` | CA 证书的路径。 | +| `` | 你想要升级到的 [Rancher 版本](../../installation-references/helm-chart-options.md)的版本标签。 | + +``` +docker run -d --volumes-from rancher-data \ + --restart=unless-stopped \ + -p 80:80 -p 443:443 \ + -v //:/etc/rancher/ssl/cert.pem \ + -v //:/etc/rancher/ssl/key.pem \ + -v //:/etc/rancher/ssl/cacerts.pem \ + --privileged \ + rancher/rancher: +``` + +特权访问是[必须](./rancher-on-a-single-node-with-docker.md#rancher-特权访问)的。 + +
+ +#### 选项 C：使用你自己的证书 - 可信 CA 签名的证书 + +
+ 单击展开 + +如果你选择使用可信 CA 签名的证书，则在启动原始 Rancher Server 容器的命令中添加 `--volumes-from rancher-data`。此外，你需要能够访问你原始安装时使用的证书。注意要使用 `--no-cacerts` 作为容器的参数，以禁用 Rancher 生成的默认 CA 证书。 + +:::note 证书要求提示： + +证书文件的格式必须是 PEM。在你的证书文件中，包括可信 CA 提供的所有中间证书。你需要对你的证书进行排序，把你的证书放在最前面，后面跟着中间证书。如需查看示例，请参见[证书故障排除](certificate-troubleshooting.md)。 + +::: + +| 占位符 | 描述 | +------------|------------- +| `` | 包含证书文件的目录的路径。 | +| `` | 完整证书链的路径。 | +| `` | 证书私钥的路径。 | +| `` | 你想要升级到的 [Rancher 版本](../../installation-references/helm-chart-options.md)的版本标签。 | + +``` +docker run -d --volumes-from rancher-data \ + --restart=unless-stopped \ + -p 80:80 -p 443:443 \ + -v //:/etc/rancher/ssl/cert.pem \ + -v //:/etc/rancher/ssl/key.pem \ + --privileged \ + rancher/rancher: \ + --no-cacerts +``` + +特权访问是[必须](./rancher-on-a-single-node-with-docker.md#rancher-特权访问)的。 +
+ +#### 选项 D：Let's Encrypt 证书 + +
+ 单击展开 + +:::caution + +Let's Encrypt 对新证书请求有频率限制。因此，请限制创建或销毁容器的频率。详情请参见 [Let's Encrypt 官方文档 - 频率限制](https://letsencrypt.org/docs/rate-limits/)。 + +::: + +如果你选择使用 [Let's Encrypt](https://letsencrypt.org/) 证书，则在启动原始 Rancher Server 容器的命令中添加 `--volumes-from rancher-data`，并且提供最初安装 Rancher 时使用的域名。 + +:::note 证书要求提示： + +- 在 DNS 中创建一条记录，将 Linux 主机 IP 地址绑定到要用于访问 Rancher 的主机名（例如，`rancher.mydomain.com`）。 +- 在 Linux 主机上打开 `TCP/80` 端口。Let's Encrypt 的 HTTP-01 质询可以来自任何源 IP 地址，因此端口 `TCP/80` 必须开放开所有 IP 地址。 + +::: + +| 占位符 | 描述 | +------------|------------- +| `` | 你想要升级到的 [Rancher 版本](../../installation-references/helm-chart-options.md)的版本标签。 | +| `` | 你最初使用的域名 | + +``` +docker run -d --volumes-from rancher-data \ + --restart=unless-stopped \ + -p 80:80 -p 443:443 \ + --privileged \ + rancher/rancher: \ + --acme-domain +``` + +特权访问是[必须](./rancher-on-a-single-node-with-docker.md#rancher-特权访问)的。 + +
+ + + + +出于安全考虑，使用 Rancher 时请使用 SSL（Secure Sockets Layer）。SSL 保护所有 Rancher 网络通信（如登录和与集群交互）的安全。 + +启动新的 Rancher Server 容器时，从以下的选项中进行选择： + +#### 选项 A：使用 Rancher 默认的自签名证书 + +
+ 单击展开 + +如果你使用 Rancher 生成的自签名证书，则将 `--volumes-from rancher-data` 添加到你启动原始 Rancher Server 容器的命令中。 + +| 占位符 | 描述 | +------------|------------- +| `` | 私有镜像仓库的 URL 和端口。 | +| `` | 你想要升级到的 [Rancher 版本](../../installation-references/helm-chart-options.md)的版本标签。 | + +``` + docker run -d --volumes-from rancher-data \ + --restart=unless-stopped \ + -p 80:80 -p 443:443 \ + -e CATTLE_SYSTEM_DEFAULT_REGISTRY= \ # 设置在 Rancher 中使用的默认私有镜像仓库 + -e CATTLE_SYSTEM_CATALOG=bundled \ # 使用打包的 Rancher System Chart + --privileged \ + /rancher/rancher: +``` + +特权访问是[必须](./rancher-on-a-single-node-with-docker.md#rancher-特权访问)的。 +
+ +#### 选项 B：使用你自己的证书 - 自签名 + +
+ 单击展开 + +如果你选择使用自己的自签名证书，则在启动原始 Rancher Server 容器的命令中添加 `--volumes-from rancher-data`。此外，你需要能够访问你原始安装时使用的证书。 + +:::note 证书要求提示： + +证书文件的格式必须是 PEM。在你的证书文件中，包括链中的所有中间证书。你需要对你的证书进行排序，把你的证书放在最前面，后面跟着中间证书。如需查看示例，请参见[证书故障排除](certificate-troubleshooting.md)。 + +::: + +| 占位符 | 描述 | +------------|------------- +| `` | 包含证书文件的目录的路径。 | +| `` | 完整证书链的路径。 | +| `` | 证书私钥的路径。 | +| `` | CA 证书的路径。 | +| `` | 私有镜像仓库的 URL 和端口。 | +| `` | 你想要升级到的 [Rancher 版本](../../installation-references/helm-chart-options.md)的版本标签。 | + +``` +docker run -d --restart=unless-stopped \ + -p 80:80 -p 443:443 \ + -v //:/etc/rancher/ssl/cert.pem \ + -v //:/etc/rancher/ssl/key.pem \ + -v //:/etc/rancher/ssl/cacerts.pem \ + -e CATTLE_SYSTEM_DEFAULT_REGISTRY= \ # 设置在 Rancher 中使用的默认私有镜像仓库 + -e CATTLE_SYSTEM_CATALOG=bundled \ # 使用打包的 Rancher System Chart + --privileged \ + /rancher/rancher: +``` +特权访问是[必须](./rancher-on-a-single-node-with-docker.md#rancher-特权访问)的。 +
+ +#### 选项 C：使用你自己的证书 - 可信 CA 签名的证书 + +
+ 单击展开 + +如果你选择使用可信 CA 签名的证书，则在启动原始 Rancher Server 容器的命令中添加 `--volumes-from rancher-data`。此外，你需要能够访问你原始安装时使用的证书。 + +:::note 证书要求提示： + +证书文件的格式必须是 PEM。在你的证书文件中，包括可信 CA 提供的所有中间证书。你需要对你的证书进行排序，把你的证书放在最前面，后面跟着中间证书。如需查看示例，请参见[证书故障排除](certificate-troubleshooting.md)。 + +::: + +| 占位符 | 描述 | +------------|------------- +| `` | 包含证书文件的目录的路径。 | +| `` | 完整证书链的路径。 | +| `` | 证书私钥的路径。 | +| `` | 私有镜像仓库的 URL 和端口。 | +| `` | 你想要升级到的 [Rancher 版本](../../installation-references/helm-chart-options.md)的版本标签。 | + +:::note + +使用 `--no-cacerts` 作为容器的参数，以禁用 Rancher 生成的默认 CA 证书。 + +::: + +``` +docker run -d --volumes-from rancher-data \ + --restart=unless-stopped \ + -p 80:80 -p 443:443 \ + --no-cacerts \ + -v //:/etc/rancher/ssl/cert.pem \ + -v //:/etc/rancher/ssl/key.pem \ + -e CATTLE_SYSTEM_DEFAULT_REGISTRY= \ # 设置在 Rancher 中使用的默认私有镜像仓库 + -e CATTLE_SYSTEM_CATALOG=bundled \ # 使用打包的 Rancher System Chart + --privileged + /rancher/rancher: +``` +特权访问是[必须](./rancher-on-a-single-node-with-docker.md#rancher-特权访问)的。 +
+ + + + +**结果**：你已升级 Rancher。已升级 Server 中的数据将保存在 `rancher-data` 容器中，用于将来的升级。 + +### 5. 验证升级 + +登录到 Rancher。通过检查浏览器左下角的版本号，确认升级是否成功。 + +:::note 升级后下游集群出现网络问题？ + +请参见[恢复集群网络](https://github.com/rancher/rancher-docs/tree/main/archived_docs/en/version-2.0-2.4/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/upgrades/namespace-migration.md)。 + +::: + +### 6. 清理旧的 Rancher Server 容器 + +移除旧的 Rancher Server 容器。如果你仅停止了旧的 Rancher Server 容器，但没有移除它，该容器还可能在服务器下次重启后重新启动。 + +## 回滚 + +如果升级没有成功完成，你可以将 Rancher Server 及其数据回滚到上次的健康状态。详情请参见 [Docker 回滚](roll-back-docker-installed-rancher.md)。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/installation-and-upgrade/resources/add-tls-secrets.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/installation-and-upgrade/resources/add-tls-secrets.md new file mode 100644 index 00000000000..34260d846dd --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/installation-and-upgrade/resources/add-tls-secrets.md @@ -0,0 +1,45 @@ +--- +title: 添加 TLS 密文 +--- + +我们使用证书和密钥将 `cattle-system` 命名空间中的 `tls-rancher-ingress` 密文配置好后，Kubernetes 会为 Rancher 创建对象和服务。 + +将服务器证书和所需的所有中间证书合并到名为 `tls.crt`的文件中。将证书密钥复制到名为 `tls.key` 的文件中。 + +例如，[acme.sh](https://acme.sh) 在 `fullchain.cer` 文件中提供服务器证书和 CA 链。 +请将 `fullchain.cer` 命名为 `tls.crt`，将证书密钥文件命名为 `tls.key`。 + +使用 `kubectl` 创建 `tls` 类型的密文。 + +``` +kubectl -n cattle-system create secret tls tls-rancher-ingress \ + --cert=tls.crt \ + --key=tls.key +``` + +:::note + +如需替换证书，你可以运行 `kubectl -n cattle-system delete secret tls-rancher-ingress` 来删除 `tls-rancher-ingress` 密文，然后运行上方命令来添加新的密文。如果你使用的是私有 CA 签名证书，仅当新证书与当前证书是由同一个 CA 签发的，才可以替换。 + +::: + +## 使用私有 CA 签名证书 + +如果你使用的是私有 CA，Rancher 需要私有 CA 的根证书或证书链的副本，Rancher Agent 使用它来校验与 Server 的连接。 + +创建一个名为 `cacerts.pem` 的文件，该文件仅包含私有 CA 的根 CA 证书或证书链，并使用 `kubectl` 在 `cattle-system` 命名空间中创建 `tls-ca` Secret。 + +``` +kubectl -n cattle-system create secret generic tls-ca \ + --from-file=cacerts.pem +``` + +:::note + +Rancher 启动时会检索配置的 `tls-ca` 密文。如果 Rancher 在运行中，更新的 CA 会在新的 Rancher Pod 启动后生效。 + +::: + +## 更新私有 CA 证书 + +按照[步骤](update-rancher-certificate.md)更新 [Rancher 高可用 Kubernetes 安装](../install-upgrade-on-a-kubernetes-cluster/install-upgrade-on-a-kubernetes-cluster.md)中的 Ingress，或从默认自签名证书切换到自定义证书。 \ No newline at end of file diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/installation-and-upgrade/resources/bootstrap-password.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/installation-and-upgrade/resources/bootstrap-password.md new file mode 100644 index 00000000000..6819429dbe5 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/installation-and-upgrade/resources/bootstrap-password.md @@ -0,0 +1,27 @@ +--- +title: 引导密码 +--- + +Rancher 首次启动时，会为第一个管理员用户随机生成一个密码。当管理员首次登录 Rancher 时，用于获取引导密码（Bootstrap）的命令会在 UI 上显示。管理员需要运行命令并使用引导密码登录。然后 Rancher 会让管理员重置密码。 + +如果你在安装过程中没有使用变量来设置引导密码，则会随机生成引导密码。如需了解使用变量设置引导密码的详情，请参见下文。 + +## 在 Helm 安装中指定引导密码 + +Helm 安装的情况下，你可以使用 `.Values.bootstrapPassword` 在 Helm Chart 值中指定引导密码变量。 + +密码将存储在 Kubernetes 密文中。安装 Rancher 后，如何使用 kubectl 获取密码的说明将会在 UI 中显示： + +``` +kubectl get secret --namespace cattle-system bootstrap-secret -o go-template='{{ .data.bootstrapPassword|base64decode}}{{ "\n" }}' +``` + +## 在 Docker 安装中指定引导密码 + +如果 Rancher 是使用 Docker 安装的，你可以通过在 Docker 安装命令中传递 `-e CATTLE_BOOTSTRAP_PASSWORD=password` 来指定引导密码。 + +密码将存储在 Docker 容器日志中。安装 Rancher 后，如何使用 Docker 容器 ID 获取密码的说明将会在 UI 中显示： + +``` +docker logs container-id 2>&1 | grep "Bootstrap Password:" +``` diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/installation-and-upgrade/resources/choose-a-rancher-version.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/installation-and-upgrade/resources/choose-a-rancher-version.md new file mode 100644 index 00000000000..734ef56e8a5 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/installation-and-upgrade/resources/choose-a-rancher-version.md @@ -0,0 +1,118 @@ +--- +title: 选择 Rancher 版本 +--- + +本节介绍如何选择 Rancher 版本。 + +在我们推荐用于生产环境的 Rancher 高可用安装中，Rancher Server 是通过 Kubernetes 集群上的 **Helm Chart** 安装的。请参见 [Helm 版本要求](helm-version-requirements.md)选择 Helm 版本来安装 Rancher。 + +如果你在开发和测试中使用 Docker 来安装 Rancher，你需要把 Rancher 作为一个 **Docker 镜像**来安装。 + + + + +如果 Rancher Server 是[安装在 Kubernetes 集群上](../install-upgrade-on-a-kubernetes-cluster/install-upgrade-on-a-kubernetes-cluster.md)的，Rancher Server 的安装，升级和回滚中，都是使用 Kubernetes 集群上的 Helm Chart 来安装 Rancher 的。因此，在准备安装或升级 Rancher 高可用时，必须添加包含用于安装 Rancher 的 Chart 的 Helm Chart 仓库。 + +请参见 [Helm 版本要求](helm-version-requirements.md)选择 Helm 版本来安装 Rancher。 + +### Helm Chart 仓库 + +Rancher 提供几个可选的 Helm Chart 仓库供你选择。最新版或稳定版的 Helm Chart 仓库与用于 Docker 安装中的 Docker 标签对应。因此，`rancher-latest` 仓库包含所有标记为 `rancher/rancher:latest` 的 Rancher 版本 Chart。当 Rancher 版本升级到 `rancher/rancher:stable`，它会被添加到 `rancher-stable` 仓库中。 + +| 类型 | 添加仓库的命令 | 仓库描述 | +| -------------- | ------------ | ----------------- | +| rancher-latest | `helm repo add rancher-latest https://releases.rancher.com/server-charts/latest` | 添加最新版本的 Rancher 的 Helm Chart 仓库。建议使用此仓库来测试新版本的 Rancher。 | +| rancher-stable | `helm repo add rancher-stable https://releases.rancher.com/server-charts/stable` | 添加较旧的，稳定的版本的 Rancher 的 Helm Chart 仓库。建议在生产环境中使用此仓库。 | +| rancher-alpha | `helm repo add rancher-alpha https://releases.rancher.com/server-charts/alpha` | 添加 alpha 版本的 Rancher 的 Helm Chart 仓库，以预览即将发布的版本。不建议在生产环境中使用这些版本。无论是什么仓库，均不支持 _升级_ 或 _升级到_ rancher-alpha 仓库中的任何 Chart。 | + +了解何时选择这些仓库，请参见[切换到不同 Helm Chart 仓库](#切换到不同-helm-chart-仓库)。 + +:::note + +`rancher-stable` 仓库中的所有 Chart 都与 `stable` 标记的 Rancher 版本对应。 + +::: + +### Helm Chart 版本 + +Rancher Helm Chart 版本与 Rancher 版本（即 `appVersion`）对应。添加仓库后，你可以运行以下命令搜索可用版本：
+    `helm search repo --versions` + +如果你有多个仓库，你可指定仓库名称，即：`helm search repo rancher-stable/rancher --versions`
+详情请访问 https://helm.sh/docs/helm/helm_search_repo/ + +要获取所选仓库的指定版本，参见如下示例指定 `--version` 参数：
+    `helm fetch rancher-stable/rancher --version=2.4.8` + +### 切换到不同 Helm Chart 仓库 + +安装 Rancher 后，如果想修改安装 Rancher 的 Helm Chart 仓库，按照以下步骤操作。 + +:::note + +由于 rancher-alpha 仓库只包含 alpha 版本 Chart，因此不支持从 rancher alpha 仓库切换到 rancher-stable 或 rancher-latest 仓库以进行升级。 + +::: + +- Latest：建议用于试用最新功能 + ``` + helm repo add rancher-latest https://releases.rancher.com/server-charts/latest + ``` +- Stable：建议用于生产环境 + ``` + helm repo add rancher-stable https://releases.rancher.com/server-charts/stable + ``` +- Alpha：即将发布的实验性预览。 + ``` + helm repo add rancher-alpha https://releases.rancher.com/server-charts/alpha + ``` + 注意：不支持升级到 Alpha 版、从 Alpha 版升级或在 Alpha 版之间升级。 + +1. 列出当前 Helm Chart 仓库。 + + ```plain + helm repo list + + NAME URL + stable https://charts.helm.sh/stable + rancher- https://releases.rancher.com/server-charts/ + ``` + +2. 删除包含安装 Rancher 时用的 Chart 的 Helm Chart 仓库。是 `rancher-stable` 或 `rancher-latest` 取决于你初始安装时的选择。 + + ```plain + helm repo remove rancher- + ``` + +3. 添加你要用于安装 Rancher 的 Helm Chart 仓库。 + + ```plain + helm repo add rancher- https://releases.rancher.com/server-charts/ + ``` + +4. 按照以下步骤，从新的 Helm Chart 仓库[升级 Rancher](../install-upgrade-on-a-kubernetes-cluster/upgrades.md)。 + + + + +在执行 [Docker 安装](../other-installation-methods/rancher-on-a-single-node-with-docker/rancher-on-a-single-node-with-docker.md)、升级或回滚时，你可以使用 _tags_ 来安装特定版本的 Rancher。 + +### Server 标签 + +Rancher Server 以 Docker 镜像的形式分发并附有标签。你可以在输入命令部署 Rancher 时指定标签。请记住，如果你指定了标签，但是没有指定版本（如 `latest` 或 `stable`），你必须显式拉取该镜像标签的新版本。否则，将使用缓存在主机上的镜像。 + +| 标签 | 描述 | +| -------------------------- | ------ | +| `rancher/rancher:latest` | 最新的开发版本。这些版本通过了我们的 CI 自动化验证。不推荐在生产环境使用这些版本。 | +| `rancher/rancher:stable` | 最新的稳定版本。推荐将此标签用于生产环境。 | +| `rancher/rancher:` | 你可以使用以前版本中的标签来指定要安装的 Rancher 版本。访问 DockerHub 查看可用的版本。 | + +:::note + +- `master` 和带有 `-rc` 或其他后缀的标签是供 Rancher 测试团队验证用的。这些标签不受官方支持，因此请不要使用这些标签。 +- 安装 alpha 版本进行预览：使用我们的[公告页面](https://forums.rancher.com/c/announcements)中列出的 alpha 标签（例如，`v2.2.0-alpha1`）进行安装。不支持升级或升级到 Alpha 版本。 + +::: + + + diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/installation-and-upgrade/resources/custom-ca-root-certificates.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/installation-and-upgrade/resources/custom-ca-root-certificates.md new file mode 100644 index 00000000000..d454197c8a5 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/installation-and-upgrade/resources/custom-ca-root-certificates.md @@ -0,0 +1,24 @@ +--- +title: 自定义 CA 根证书 +--- + +如果你在内部生产环境使用 Rancher，且不打算公开暴露应用，你可以使用使用私有 CA 颁发的证书。 + +Rancher 可能会访问配置了自定义/内部 CA 根证书（也称为自签名证书）的服务。如果 Rancher 无法验证服务的证书，则会显示错误信息 `x509: certificate signed by unknown authority`。 + +如需验证证书，你需要把 CA 根证书添加到 Rancher。由于 Rancher 是用 Go 编写的，我们可以使用环境变量 `SSL_CERT_DIR` 指向容器中 CA 根证书所在的目录。启动 Rancher 容器时，可以使用 Docker 卷选项（`-v host-source-directory:container-destination-directory`）来挂载 CA 根证书目录。 + +Rancher 可以访问的服务示例： + +- 应用商店 +- 验证提供程序 +- 使用 Node Driver 访问托管/云 API + +## 使用自定义 CA 证书安装 + +有关启动挂载了私有 CA 证书的 Rancher 容器的详情，请参见安装文档： + +- [Docker 安装的自定义 CA 证书选项](../../../reference-guides/single-node-rancher-in-docker/advanced-options.md#自定义-ca-证书) + +- [Kubernetes 安装的其他受信 CA 选项](../installation-references/helm-chart-options.md#额外的授信-ca) + diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/installation-and-upgrade/resources/helm-version-requirements.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/installation-and-upgrade/resources/helm-version-requirements.md new file mode 100644 index 00000000000..239f7cc8350 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/installation-and-upgrade/resources/helm-version-requirements.md @@ -0,0 +1,14 @@ +--- +title: Helm 版本要求 +--- + +本文介绍 Helm 的要求。Helm 是用于把 Rancher 安装在高可用 Kubernetes 集群上的工具。 + +> 我们已针对 Helm 3 更新了安装指南。如果你使用 Helm 2 进行安装，请参见 [Helm 2 迁移到 Helm 3 文档](https://helm.sh/blog/migrate-from-helm-v2-to-helm-v3/)。[本文](https://github.com/rancher/rancher-docs/tree/main/archived_docs/en/version-2.0-2.4/getting-started/installation-and-upgrade/advanced-options/advanced-use-cases/helm2/helm2.md)提供了较早的使用 Helm 2 的 Rancher 高可用安装指南的副本。如果你如果无法升级到 Helm 3，可以使用这个说明安装。 + + + +- 如需安装或升级 Rancher 2.5，请使用 Helm 3.2.x 或更高版本。 +- Kubernetes 1.16 要求 Helm 2.16.0 或更高版本。如果使用的是默认 Kubernetes 版本，请参见[发行说明](https://github.com/rancher/rke/releases)获取所使用的 RKE 版本。 +- 请不要使用 Helm 2.15.0，因为这个版本有转换/比较数字的问题。 +- 请不要使用 Helm 2.12.0，因为该版本有 `cert-manager` 的兼容问题。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/installation-and-upgrade/resources/local-system-charts.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/installation-and-upgrade/resources/local-system-charts.md new file mode 100644 index 00000000000..17c965ad095 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/installation-and-upgrade/resources/local-system-charts.md @@ -0,0 +1,13 @@ +--- +title: 离线安装中设置本地 System Charts +--- + +[Charts](https://github.com/rancher/charts) 仓库包含 Monitoring、Logging、告警和 Istio 等功能所需的所有 Helm 目录项。 + +在 Rancher 的离线安装中，你需要配置 Rancher 以使用 System Charts 的本地副本。本节介绍如何通过 CLI 标志使用本地 System Charts。 + +## 使用本地 System Charts + +`system-charts` 的一个本地副本已经打包到 `rancher/rancher` 容器中。为了在离线安装中使用这些功能，你需要使用额外的环境变量 `CATTLE_SYSTEM_CATALOG=bundled` 来运行 Rancher 安装命令，该环境变量告诉 Rancher 使用 Chart 的本地副本，而不是尝试从 GitHub 获取 Chart。 + +带有 `system-charts` 的 Rancher 安装命令示例包含在 Docker 和 Helm 的[离线安装说明](../other-installation-methods/air-gapped-helm-cli-install/air-gapped-helm-cli-install.md)中。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/installation-and-upgrade/resources/resources.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/installation-and-upgrade/resources/resources.md new file mode 100644 index 00000000000..ce4989d9d0e --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/installation-and-upgrade/resources/resources.md @@ -0,0 +1,25 @@ +--- +title: 资源 +--- + +## Docker 安装 + +[单节点 Docker 安装](../other-installation-methods/rancher-on-a-single-node-with-docker/rancher-on-a-single-node-with-docker.md)适用于想要测试 Rancher 的用户。你无需使用 Helm 在 Kubernetes 集群上运行 Rancher，你可以使用 `docker run` 命令，把 Rancher Server 组件安装到单个节点上。 + +由于只有一个节点和一个 Docker 容器，因此，如果该节点发生故障，由于其他节点上没有可用的 etcd 数据副本，你将丢失 Rancher Server 的所有数据。 + +## 离线安装 + +按照[以下步骤](../other-installation-methods/air-gapped-helm-cli-install/air-gapped-helm-cli-install.md)在离线环境中安装 Rancher Server。 + +离线环境可以是 Rancher Server 离线安装、防火墙后面或代理后面。 + +## 高级选项 + +安装 Rancher 时，有如下几个可开启的高级选项：每个安装指南中都提供了对应的选项。了解选项详情： + +- [自定义 CA 证书](custom-ca-root-certificates.md) +- [API 审计日志](../../../how-to-guides/advanced-user-guides/enable-api-audit-log.md) +- [TLS 设置](../installation-references/tls-settings.md) +- [etcd 配置](../../../how-to-guides/advanced-user-guides/tune-etcd-for-large-installs.md) +- [离线安装 Local System Chart](local-system-charts.md) diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/installation-and-upgrade/resources/update-rancher-certificate.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/installation-and-upgrade/resources/update-rancher-certificate.md new file mode 100644 index 00000000000..c5eb98f8aaf --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/installation-and-upgrade/resources/update-rancher-certificate.md @@ -0,0 +1,263 @@ +--- +title: 更新 Rancher 证书 +--- + +## 更新私有 CA 证书 + +按照以下步骤轮换[安装在 Kubernetes 集群上](../install-upgrade-on-a-kubernetes-cluster/install-upgrade-on-a-kubernetes-cluster.md)、由 Rancher 使用的 SSL 证书和私有 CA，或转用由私有 CA 签发的 SSL 证书。 + +步骤概述： + +1. 使用新证书和私钥创建或更新 `tls-rancher-ingress` Kubernetes Secret 对象。 +1. 使用根 CA 证书创建或更新 `tls-ca` Kubernetes Secret 对象（仅在使用私有 CA 时需要）。 +1. 使用 Helm CLI 更新 Rancher 安装。 +1. 重新配置 Rancher Agent 以信任新的 CA 证书。 +1. 选择 Fleet 集群的强制更新，来将 fleet-agent 连接到 Rancher。 + +各个步骤的详细说明如下。 + +### 1. 创建/更新证书 Secret 对象 + +首先，将服务器证书和所有中间证书合并到名为 `tls.crt` 的文件，并在名为 `tls.key` 的文件中提供相应的证书密钥。 + +使用以下命令在 Rancher（本地）管理集群中创建 `tls-rancher-ingress` Secret 对象： + +```bash +kubectl -n cattle-system create secret tls tls-rancher-ingress \ + --cert=tls.crt \ + --key=tls.key +``` + +或者，更新现有的 `tls-rancher-ingress` Secret： + +```bash +kubectl -n cattle-system create secret tls tls-rancher-ingress \ + --cert=tls.crt \ + --key=tls.key \ + --dry-run --save-config -o yaml | kubectl apply -f - +``` + +### 2. 创建/更新证书 CA Secret 对象 + +如果新证书由私有 CA 签发的，你需要将相应的根 CA 证书复制到名为 `cacerts.pem` 的文件中，并创建或更新 `cattle-system` 命名空间中的 `tls-ca` Secret。如果证书由中间 CA 签名，则 `cacerts.pem` 必须按顺序同时包含中间 CA 证书和根 CA 证书。 + +创建初始 `tls-ca` Secret： + +```bash +kubectl -n cattle-system create secret generic tls-ca \ + --from-file=cacerts.pem +``` + +要更新现有的 `tls-ca` Secret： + +```bash +kubectl -n cattle-system create secret generic tls-ca \ + --from-file=cacerts.pem \ + --dry-run --save-config -o yaml | kubectl apply -f - +``` + +### 3. 重新配置 Rancher 部署 + +如果证书源保持不变（例如，`secret`），请按照步骤 3a 中的步骤操作。 + +但是，如果证书源发生变化（例如，`letsEncrypt` 更改为 `secret`），请按照 3b 中的步骤操作。 + +#### 3a. 重新部署 Rancher pod + +当证书源保持不变，但需要更新 CA 证书时，需要执行此步骤。 + +在这种情况下，由于 `tls-ca` secret 在启动时由 Rancher pod 读取，因此你需要重新部署 Rancher pod。 + +你可以运行以下命令重新部署 Rancher pod： +```bash +kubectl rollout restart deploy/rancher -n cattle-system +``` + +修改完成后，访问 `https:///v3/settings/cacerts`，验证该值是否与先前写入 `tls-ca` Secret 中的 CA 证书匹配。在所有重新部署的 Rancher pod 启动之前，CA `cacerts` 值可能不会更新。 + +#### 3b. 更新 Rancher 的 Helm 值 + +如果证书源有更改，则需要执行此步骤。如果你的 Rancher 之前使用默认的自签名证书 (`ingress.tls.source=rancher`) 或 Let's Encrypt (`ingress.tls.source=letsEncrypt`) 证书，并且现在正在使用由私有 CA (`ingress.tls.source=secret`) 签名的证书。 + +以下步骤更新了 Rancher Chart 的 Helm 值，因此 Rancher pod 和 ingress 会使用在步骤 1 和 2 中创建的新私有 CA 证书。 + +1. 调整初始安装期间使用的值，将当前值存储为： +```bash +helm get values rancher -n cattle-system -o yaml > values.yaml +``` +1. 检索当前部署的 Rancher Chart 的版本字符串： +```bash +helm ls -n cattle-system +``` +1. 更新 `values.yaml` 文件中的当前 Helm 值以包含下方内容： +```yaml +ingress: + tls: + source: secret +privateCA: true +``` +:::note 重要： +由于证书由私有 CA 签发，因此确保在 `values.yaml` 文件中设置了 [`privateCA: true`](../installation-references/helm-chart-options.md#常用选项) 是非常重要的。 +::: +1. 使用 `values.yaml` 文件和当前 Chart 版本升级 Helm 应用程序实例。版本必须匹配以防止 Rancher 升级。 +```bash + helm upgrade rancher rancher-stable/rancher \ + --namespace cattle-system \ + -f values.yaml \ + --version +``` + +修改完成后，访问 `https:///v3/settings/cacerts`，验证该值是否与先前写入 `tls-ca` Secret 中的 CA 证书匹配。在所有 Rancher pod 启动之前，CA `cacerts` 值可能不会更新。 + +### 4. 重新配置 Rancher Agent 以信任私有 CA + +本节介绍了重新配置 Rancher Agent 以信任私有 CA 的三种方法。如果你的实际情况符合以下任意一个条件，请执行此步骤： + +- Rancher 在先前的配置中使用了 Rancher 自签名证书 (`ingress.tls.source=rancher`) 或 Let's Encrypt 证书 (`ingress.tls.source=letsEncrypt`)。 +- 该证书由不同的私有 CA 签发 + +#### 为什么要执行这一步骤？ + +如果 Rancher 配置了私有 CA 签名的证书时，CA 证书链将受到 Rancher agent 容器的信任。Agent 会对下载证书的校验和及 `CATTLE_CA_CHECKSUM` 环境变量进行比较。换言之，如果 Rancher 使用的私有 CA 证书发生变化，环境变量 `CATTLE_CA_CHECKSUM` 必须相应更新。 + +#### 可使用的方法 + +- 方法 1（最简单的方法）：在轮换证书后将所有集群连接到 Rancher。适用于更新或重新部署 Rancher 部署（步骤 3）后立即执行的情况。 + +- 方法 2：适用于集群与 Rancher 失去连接，但所有集群都启用了 [Authorized Cluster Endpoint](../../../how-to-guides/new-user-guides/manage-clusters/access-clusters/authorized-cluster-endpoint.md) (ACE) 的情况。 + +- 方法 3：如果方法 1 和 2 不可行，则可使用方法 3 进行回退。 + +#### 方法 1：强制重新部署 Rancher Agent + +对于每个下游集群，使用 Rancher（本地）管理集群的 Kubeconfig 文件运行以下命令。 + +```bash +kubectl annotate clusters.management.cattle.io io.cattle.agent.force.deploy=true +``` + +:::note +找到下游集群的集群 ID (c-xxxxx)。你可以在 Rancher UI 的**集群管理**中查看集群时在浏览器 URL 中找到 ID。 +::: + +此命令将使 Agent 清单重新应用新证书的校验和。 + +#### 方法二：手动更新校验和环境变量 + +将 `CATTLE_CA_CHECKSUM` 环境变量更新为匹配新 CA 证书校验和的值，从而手动为 Agent Kubernetes 对象打上补丁。通过以下操作生成新的校验和： + +```bash +curl -k -s -fL /v3/settings/cacerts | jq -r .value | sha256sum | awk '{print $1}' +``` + +为每个下游集群使用 Kubeconfig 更新两个 Agent 部署的环境变量。如果集群启用了 [ACE](../../../how-to-guides/new-user-guides/manage-clusters/access-clusters/authorized-cluster-endpoint.md)，你可以[调整 kubectl 上下文](../../../how-to-guides/new-user-guides/manage-clusters/access-clusters/use-kubectl-and-kubeconfig.md#直接使用下游集群进行身份验证)，从而直接连接到下游集群。 + +```bash +kubectl edit -n cattle-system ds/cattle-node-agent +kubectl edit -n cattle-system deployment/cattle-cluster-agent +``` + +#### 方法三：手动重新部署 Rancher agent + +该方法通过在每个下游集群的 control plane 节点上运行一组命令，从而重新应用 Rancher agent。 + +对每个下游集群重复以下步骤： + +1. 检索 agent 注册 kubectl 命令： + 1. 找到下游集群的集群 ID (c-xxxxx)。你可以在 Rancher UI 的**集群管理**中查看集群时在浏览器 URL 中找到 ID。 + 1. 将 Rancher Server URL 和集群 ID 添加到以下 URL：`https:///v3/clusterregistrationtokens?clusterId=`。 + 1. 复制 `insecureCommand` 字段中的命令，使用此命令是因为未使用私有 CA。 + +2. 使用以下其中一种方法，使用 kubeconfig 为下游集群运行上一步中的 kubectl 命令： + 1. 如果集群启用了 [ACE](../../../how-to-guides/new-user-guides/manage-clusters/access-clusters/authorized-cluster-endpoint.md)，你可以[调整上下文](../../../how-to-guides/new-user-guides/manage-clusters/access-clusters/use-kubectl-and-kubeconfig.md#直接使用下游集群进行身份验证)，从而直接连接到下游集群。 + 1. 或者，SSH 到 control plane 节点： + - RKE：使用[此处文档中的步骤](https://github.com/rancherlabs/support-tools/tree/master/how-to-retrieve-kubeconfig-from-custom-cluster)生成 kubeconfig + - RKE2/K3s：使用安装时填充的 kubeconfig + +### 5. 强制更新 Fleet 集群，从而将 fleet-agent 重新连接到 Rancher + +在 Rancher UI 的[持续交付](../../../integrations-in-rancher/fleet/overview.md#在-rancher-ui-中访问-fleet)中，为集群选择“强制更新”，来允许下游集群中的 fleet-agent 成功连接到 Rancher。 + +#### 为什么要执行这一步骤？ + +Rancher 管理的集群中的 Fleet agent 存储了用于连接到 Rancher 的 kubeconfig。kubeconfig 包含一个 `certificate-authority-data` 字段，该字段包含 Rancher 使用的证书的 CA。更改 CA 时，你需要更新此块来允许 fleet-agent 信任 Rancher 使用的证书。 + +## 将私有 CA 证书更改为公共证书 + +按照以下步骤执行与上面相反的操作，将私有 CA 颁发的证书更改为公共或自签名 CA。 + +### 1. 创建/更新证书 Secret 对象 + +首先，将服务器证书和所有中间证书合并到名为 `tls.crt` 的文件，并在名为 `tls.key` 的文件中提供相应的证书密钥。 + +使用以下命令在 Rancher（本地）管理集群中创建 `tls-rancher-ingress` Secret 对象： + +```bash +kubectl -n cattle-system create secret tls tls-rancher-ingress \ + --cert=tls.crt \ + --key=tls.key +``` + +或者，更新现有的 `tls-rancher-ingress` Secret： + +```bash +kubectl -n cattle-system create secret tls tls-rancher-ingress \ + --cert=tls.crt \ + --key=tls.key \ + --dry-run --save-config -o yaml | kubectl apply -f - +``` + +### 2. 删除 CA 证书 Secret 对象 + +你需要删除 `cattle-system` 命名空间中的 `tls-ca secret`（不再需要它）。如果需要，你还可以选择保存 `tls-ca` secret 的副本。 + +要保存现有的 `tls-ca` Secret： + +```bash +kubectl -n cattle-system get secret tls-ca -o yaml > tls-ca.yaml +``` + +要删除现有的 `tls-ca` 密文： + +```bash +kubectl -n cattle-system delete secret tls-ca +``` + +### 3. 重新配置 Rancher 部署 + +如果证书源有更改，则需要执行此步骤。在这种情况下，它变化的原因很可能是因为 Rancher 之前配置为使用默认的自签名证书 (`ingress.tls.source=rancher`)。 + +以下步骤更新了 Rancher Chart 的 Helm 值，因此 Rancher pod 和 Ingress 会使用在步骤 1 中创建的新证书。 + +1. 调整初始安装期间使用的值，将当前值存储为： +```bash +helm get values rancher -n cattle-system -o yaml > values.yaml +``` +1. 获取当前部署的 Rancher Chart 的版本字符串： +```bash +helm ls -n cattle-system +``` +1. 更新 `values.yaml` 文件中的当前 Helm 值： + 1. 由于不再使用私有 CA，删除 `privateCA: true` 字段，或将其设置为 `false`。 + 1. 根据需要调整 `ingress.tls.source` 字段。有关更多信息，请参阅 [Chart 选项](../installation-references/helm-chart-options.md#常用选项)。以下是一些示例： + 1. 如果使用公共 CA，继续使用 `secret` + 1. 如果使用 Let's Encrypt，将值更新为 `letsEncrypt` +1. 使用 `values.yaml` 文件更新 Rancher Chart 的 Helm 值，并使用当前 Chart 版本防止升级： +```bash + helm upgrade rancher rancher-stable/rancher \ + --namespace cattle-system \ + -f values.yaml \ + --version +``` + +### 4. 为非私有/通用证书重新配置 Rancher Agent + +由于不再使用私有 CA，因此你需要删除下游集群 agent 上的 `CATTLE_CA_CHECKSUM` 环境变量，或将其设置为 ""（空字符串）。 + +### 5. 强制更新 Fleet 集群，从而将 fleet-agent 重新连接到 Rancher + +在 Rancher UI 的[持续交付](../../../integrations-in-rancher/fleet/overview.md#在-rancher-ui-中访问-fleet)中，为集群选择“强制更新”，来允许下游集群中的 fleet-agent 成功连接到 Rancher。 + +#### 为什么要执行这一步骤？ + +Rancher 管理的集群中的 Fleet agent 存储了用于连接到 Rancher 的 kubeconfig。kubeconfig 包含一个 `certificate-authority-data` 字段，该字段包含 Rancher 使用的证书的 CA。更改 CA 时，你需要更新此块来允许 fleet-agent 信任 Rancher 使用的证书。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/installation-and-upgrade/resources/upgrade-cert-manager.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/installation-and-upgrade/resources/upgrade-cert-manager.md new file mode 100644 index 00000000000..f8a6cb3d1a0 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/installation-and-upgrade/resources/upgrade-cert-manager.md @@ -0,0 +1,284 @@ +--- +title: 升级 Cert-Manager +--- + +Rancher 适配 API 版本 `cert-manager.io/v1` 并且在 cert-manager v1.13.1 版本上进行了测试。 + +Rancher 使用 cert-manager 为 Rancher 高可用部署自动生成和续期 TLS 证书。从 2019 秋季开始，cert-manager 发生了以下的三个重要变更。如果你在此时间段前创建了 Rancher 高可用部署，请进行相关操作。 + +1. [从 2019 年 11 月 1 日开始，Let's Encrypt 已阻止低于 0.8.0 的 cert-manager 实例。](https://community.letsencrypt.org/t/blocking-old-cert-manager-versions/98753) +1. [Cert-manager 正在弃用和替换 certificate.spec.acme.solvers 字段](https://cert-manager.io/docs/installation/upgrading/upgrading-0.7-0.8/)。此更改暂时没有确切的截止日期。 +1. [Cert-manager 正在弃用 `v1alpha1` API 和替换它的 API 组](https://cert-manager.io/docs/installation/upgrading/upgrading-0.10-0.11/)。 + +为了帮助你应对这些变化，本文将： + +1. 提供升级 cert-manager 步骤的文档。 +1. 阐述 cert-manager API 的变更，并提供 cert-manager 官方文档的链接，助你实现数据迁移。 + +:::note 重要提示： + +如果你要将 cert-manager 从早于 1.5 的版本升级到最新版本，请按照以下[选项 C](#选项-c升级-15-及以下版本的-cert-manager) 中的步骤进行操作。请注意，你无需重新安装 Rancher 即可执行此升级。 + +::: + +## 升级 Cert-Manager + +以下说明中使用的命名空间是由当前安装了 cert-manager 的命名空间决定的。如果它在 kube-system 中，在以下说明步骤中使用。你可以运行 `kubectl get pods --all-namespaces` 来验证，并检查 cert-manager-\* pods 列在哪个命名空间中。不要更改运行 cert-manager 的命名空间，否则可能会出现错误。 + +要升级 cert-manager，请遵循步骤操作。 + +### 选项 A：联网升级 cert-manager + +
+ 单击展开 + +1. [备份现有资源](https://cert-manager.io/docs/tutorials/backup/)： + + ```plain + kubectl get -o yaml --all-namespaces \ + issuer,clusterissuer,certificates,certificaterequests > cert-manager-backup.yaml + ``` + + :::note 重要提示： + + 如果你从低于 0.11.0 的版本升级，请将所有备份资源上的 apiVersion 从 `certmanager.k8s.io/v1alpha1` 升级到 `cert-manager.io/v1alpha2`。如果你需要在其他资源上使用 cert-manager 注释，请对其进行更新以反映新的 API 组。详情请参见[附加注释变更](https://cert-manager.io/docs/installation/upgrading/upgrading-0.10-0.11/#additional-annotation-changes)。 + + ::: + +1. [卸载现有部署](https://cert-manager.io/docs/installation/uninstall/kubernetes/#uninstalling-with-helm)： + + ```plain + helm uninstall cert-manager + ``` + + 使用你安装的 vX.Y.Z 版本的链接删除 CustomResourceDefinition： + + ```plain + kubectl delete -f https://github.com/cert-manager/cert-manager/releases/download/vX.Y.Z/cert-manager.crds.yaml + + ``` + +1. 单独安装 CustomResourceDefinition 资源： + + ```plain + kubectl apply --validate=false -f https://github.com/cert-manager/cert-manager/releases/download/vX.Y.Z/cert-manager.crds.yaml + + ``` + + :::note + + 如果你运行的 Kubernetes 版本是 1.15 或更低版本，你需要在以上的 `kubectl apply` 命令中添加 `--validate=false`。否则你将看到 cert-manager CRD 资源中的 `x-kubernetes-preserve-unknown-fields` 字段校验错误提示。这是 kubectl 执行资源校验方式产生的良性错误。 + + ::: + +1. 根据需要为 cert-manager 创建命名空间： + + ```plain + kubectl create namespace cert-manager + ``` + +1. 添加 Jetstack Helm 仓库： + + ```plain + helm repo add jetstack https://charts.jetstack.io + ``` + +1. 更新 Helm Chart 仓库本地缓存： + + ```plain + helm repo update + ``` + +1. 安装新版本的 cert-manager： + + ```plain + helm install \ + cert-manager jetstack/cert-manager \ + --namespace cert-manager + ``` + +1. [恢复备份资源](https://cert-manager.io/docs/tutorials/backup/#restoring-resources)： + + ```plain + kubectl apply -f cert-manager-backup.yaml + ``` + +
+ +### 选项 B：在离线环境中升级 Cert-Manager + +
+ 单击展开 + +### 先决条件 + +在执行升级之前，先将所需的容器镜像添加到私有镜像仓库中，并下载/渲染所需的 Kubernetes manifest 文件来准备离线环境。 + +1. 参见[准备私有镜像仓库](../other-installation-methods/air-gapped-helm-cli-install/publish-images.md)指南，将升级所需的镜像推送到镜像仓库。 + +1. 在可以连接互联网的系统中，将 cert-manager 仓库添加到 Helm： + + ```plain + helm repo add jetstack https://charts.jetstack.io + helm repo update + ``` + +1. 从 [Helm Chart 仓库](https://artifacthub.io/packages/helm/cert-manager/cert-manager)中获取最新可用的 cert-manager Chart： + + ```plain + helm fetch jetstack/cert-manager + ``` + +1. 使用安装 Chart 的选项来渲染 cert-manager 模板。记住要设置 `image.repository` 选项，以从你的私有镜像仓库拉取镜像。此操作会创建一个包含 Kubernetes manifest 文件的 `cert-manager` 目录。 + + Helm 3 命令如下： + + ```plain + helm template cert-manager ./cert-manager-v0.12.0.tgz --output-dir . \ + --namespace cert-manager \ + --set image.repository=/quay.io/jetstack/cert-manager-controller + --set webhook.image.repository=/quay.io/jetstack/cert-manager-webhook + --set cainjector.image.repository=/quay.io/jetstack/cert-manager-cainjector + ``` + + + + Helm 2 命令如下： + + ```plain + helm template ./cert-manager-v0.12.0.tgz --output-dir . \ + --name cert-manager --namespace cert-manager \ + --set image.repository=/quay.io/jetstack/cert-manager-controller + --set webhook.image.repository=/quay.io/jetstack/cert-manager-webhook + --set cainjector.image.repository=/quay.io/jetstack/cert-manager-cainjector + ``` + +1. 下载新旧版 cert-manager 所需的 CRD 文件： + + ```plain + curl -L -o cert-manager-crd.yaml https://raw.githubusercontent.com/cert-manager/cert-manager/release-0.12/deploy/manifests/00-crds.yaml + curl -L -o cert-manager/cert-manager-crd-old.yaml https://raw.githubusercontent.com/cert-manager/cert-manager/release-X.Y/deploy/manifests/00-crds.yaml + ``` + +### 安装 cert-manager + +1. 备份现有资源： + + ```plain + kubectl get -o yaml --all-namespaces \ + issuer,clusterissuer,certificates,certificaterequests > cert-manager-backup.yaml + ``` + + :::note 重要提示： + + 如果你从低于 0.11.0 的版本升级，请将所有备份资源上的 apiVersion 从 `certmanager.k8s.io/v1alpha1` 升级到 `cert-manager.io/v1alpha2`。如果你需要在其他资源上使用 cert-manager 注释，请对其进行更新以反映新的 API 组。详情请参见[附加注释变更](https://cert-manager.io/docs/installation/upgrading/upgrading-0.10-0.11/#additional-annotation-changes)。 + + ::: + +1. 删除现有的 cert-manager 安装包： + + ```plain + kubectl -n cert-manager \ + delete deployment,sa,clusterrole,clusterrolebinding \ + -l 'app=cert-manager' -l 'chart=cert-manager-v0.5.2' + ``` + + 使用你安装的 vX.Y 版本的链接删除 CustomResourceDefinition： + + ```plain + kubectl delete -f cert-manager/cert-manager-crd-old.yaml + ``` + +1. 单独安装 CustomResourceDefinition 资源： + + ```plain + kubectl apply -f cert-manager/cert-manager-crd.yaml + ``` + + :::note 重要提示： + + 如果你运行的 Kubernetes 版本是 1.15 或更低版本，你需要在以上的 `kubectl apply` 命令中添加 `--validate=false`。否则你将看到 cert-manager CRD 资源中的 `x-kubernetes-preserve-unknown-fields` 字段校验错误提示。这是 kubectl 执行资源校验方式产生的良性错误。 + + ::: + +1. 为 cert-manager 创建命名空间： + + ```plain + kubectl create namespace cert-manager + ``` + +1. 安装 cert-manager + + ```plain + kubectl -n cert-manager apply -R -f ./cert-manager + ``` + +1. [恢复备份资源](https://cert-manager.io/docs/tutorials/backup/#restoring-resources)： + + ```plain + kubectl apply -f cert-manager-backup.yaml + ``` + +
+ +### 选项 C：升级 1.5 及以下版本的 cert-manager + +
+ 单击展开 + +以前，要升级旧版本的 cert-manager，我们建议卸载并重新安装 Rancher。使用以下方法，你可以升级 cert-manager 而无需执行此额外步骤，从而更好地保护你的生产环境： + +1. 按照[安装指南](https://cert-manager.io/docs/usage/cmctl/#installation)安装 `cmctl`（cert-manager CLI 工具）。 + +1. 确保所有以已弃用的 API 版本存储在 etcd 中的 cert-manager 自定义资源都迁移到 v1： + + ``` + cmctl upgrade migrate-api-version + ``` + 有关详细信息，请参阅 [API 版本迁移文档](https://cert-manager.io/docs/usage/cmctl/#migrate-api-version)。另请参阅[将 1.5 升级到 1.6](https://cert-manager.io/docs/installation/upgrading/upgrading-1.5-1.6/) 和[将 1.6 升级到到 1.7](https://cert-manager.io/docs/installation/upgrading/upgrading-1.6-1.7/)。 + +1. 正常使用 `helm upgrade` 将 cert-manager 升级到 1.7.1。如果需要，你可以直接从版本 1.5 转到 1.7。 + +1. 按照 Helm 教程[更新发布清单的 API 版本](https://helm.sh/docs/topics/kubernetes_apis/#updating-api-versions-of-a-release-manifest)。Chart 发布名称为 `release_name=rancher`，发布命名空​​间为 `release_namespace=cattle-system`。 + +1. 在解码后的文件中，搜索 `cert-manager.io/v1beta1` 并将其**替换**为 `cert-manager.io/v1`。 + +1. 使用 `helm upgrade` 正常升级 Rancher。 + +
+ +### 验证部署 + +安装完 cert-manager 后，你可以通过检查 kube-system 命名空间中正在运行的 Pod 来验证它是否已正确部署： + +``` +kubectl get pods --namespace cert-manager + +NAME READY STATUS RESTARTS AGE +cert-manager-5c6866597-zw7kh 1/1 Running 0 2m +cert-manager-cainjector-577f6d9fd7-tr77l 1/1 Running 0 2m +cert-manager-webhook-787858fcdb-nlzsq 1/1 Running 0 2m +``` + +## Cert-Manager API 变更和数据迁移 + +--- + +Rancher 现在支持 cert-manager 1.6.2 和 1.7.1。推荐使用 v1.7.x，因为 v 1.6.x 将在 2022 年 3 月 30 日结束生命周期。详情请参见 [cert-manager 文档](../install-upgrade-on-a-kubernetes-cluster/install-upgrade-on-a-kubernetes-cluster.md#4-安装-cert-manager)。有关将 cert-manager 从 1.5 升级到 1.6 的说明，请参见上游的 [cert-manager 文档](https://cert-manager.io/docs/installation/upgrading/upgrading-1.5-1.6/)。有关将 cert-manager 从 1.6 升级到 1.7 的说明，请参见上游的 [cert-manager 文档](https://cert-manager.io/docs/installation/upgrading/upgrading-1.6-1.7/)。 + +--- + +Cert-manager 已经弃用 `certificate.spec.acme.solvers` 字段，而且会在未来的版本中放弃对该字段的支持。 + +根据 cert-manager 文档，v0.8 引入了配置 ACME 证书资源的新格式。具体来说，就是移动了 challenge solver 字段。v0.9 新旧格式均支持。请知悉，之后发布的新 cert-manager 版本会放弃对旧格式的支持。Cert-Manager 文档建议你在更新后，将 ACME 颁发者和证书资源更新到新格式。 + +如需了解变更细节以及迁移说明，请参见[将 Cert-Manager 从 v0.7 升级到 v0.8](https://cert-manager.io/docs/installation/upgrading/upgrading-0.7-0.8/)。 + +v0.11 版本标志着删除先前 Cert-Manager 版本中使用的 v1alpha1 API，以及将 API 组从 certmanager.k8s.io 更改到 cert-manager.io。 + +此外，我们已不再支持 v0.8 版本中已弃用的旧配置格式。换言之，在升级到 v0.11 之前，你必须先为 ACME 发行者使用新的 solver 样式配置格式作为过渡。详情请参见[升级到 v0.8](https://cert-manager.io/docs/installation/upgrading/upgrading-0.7-0.8/)。 + +如需了解变更细节以及迁移说明，请参见[将 Cert-Manager 从 v0.10 升级到 v0.11](https://cert-manager.io/docs/installation/upgrading/upgrading-0.10-0.11/)。 + +如需获得更多信息，请参见 [Cert-Manager 升级](https://cert-manager.io/docs/installation/upgrade/)。 + diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/installation-and-upgrade/upgrade-and-roll-back-kubernetes.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/installation-and-upgrade/upgrade-and-roll-back-kubernetes.md new file mode 100644 index 00000000000..b23f7651dd3 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/installation-and-upgrade/upgrade-and-roll-back-kubernetes.md @@ -0,0 +1,126 @@ +--- +title: 升级和回滚 Kubernetes +--- + +升级到最新版本的 Rancher 之后，下游 Kubernetes 集群可以升级为 Rancher 支持的最新的 Kubernetes 版本。 + +Rancher 使用 RKE（Rancher Kubernetes Engine）来预置和编辑 RKE 集群。有关为 RKE 集群配置升级策略的更多信息，请参阅 [RKE 文档](https://rancher.com/docs/rke/latest/en/)。 + + +## 经过测试的 Kubernetes 版本 + +Rancher 在发布新版本之前，会对其与 Kubernetes 的最新次要版本进行测试，以确保兼容性。有关各个 Rancher 版本测试了哪些 Kubernetes 版本的详细信息，请参阅[支持维护条款](https://rancher.com/support-maintenance-terms/all-supported-versions/rancher-v2.6.0/)。 + +## 升级的工作原理 + +RKE v1.1.0 改变了集群升级的方式。 + +在 [RKE 文档](https://rancher.com/docs/rke/latest/en/upgrades/how-upgrades-work)中，你将了解编辑或升级 RKE Kubernetes 集群时会发生的情况。 + + +## 升级的最佳实践 + +在升级集群的 Kubernetes 版本时，我们建议你： + +1. 拍一张快照。 +1. 启动 Kubernetes 升级。 +1. 如果升级失败，请将集群恢复到升级前的 Kubernetes 版本。这可以通过选择**恢复 etcd 和 Kubernetes 版本**选项来实现。在恢复 etcd 快照 之前，这会将你的集群恢复到升级前的 kubernetes 版本。 + +恢复操作将在不处于健康或 active 状态的集群上运行。 + +## 升级 Kubernetes 版本 + +:::note 先决条件： + +- 以下选项适用于 [Rancher 启动的 Kubernetes 集群](../../how-to-guides/new-user-guides/launch-kubernetes-with-rancher/launch-kubernetes-with-rancher.md)和[注册的 K3s Kubernetes 集群](../../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/register-existing-clusters.md#已注册-rke2-和-k3s-集群的附加功能)。 +- 以下选项也适用于导入且已注册的 RKE2 集群。如果你从外部云平台导入集群但不注册，你将无法在 Rancher 中升级 Kubernetes 版本。 +- 在升级 Kubernetes 之前，先[备份你的集群](../../how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/backup-restore-and-disaster-recovery.md)。 + +::: + +1. 在左上角，单击 **☰ > 集群管理**。 +1. 在**集群**页面中，进入要升级的集群，然后点击 **⋮ > 编辑配置**。 +1. 从 **Kubernetes 版本** 下拉列表中，选择要用于集群的 Kubernetes 版本。 +1. 单击**保存**。 + +**结果**：已开始为集群升级 Kubernetes。 + +## 回滚 + +你可以将集群恢复到使用先前 Kubernetes 版本的备份。有关详细信息，请参阅： + +- [备份集群](../../how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/back-up-rancher-launched-kubernetes-clusters.md#快照工作原理) +- [使用备份恢复集群](../../how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/restore-rancher-launched-kubernetes-clusters-from-backup.md#使用快照恢复集群) + +## 配置升级策略 + +从 RKE v1.1.0 开始，我们提供了额外的升级选项，让你更精细地控制升级过程。如果满足[条件和要求](https://rancher.com/docs/rke/latest/en/upgrades/maintaining-availability)，你可以使用这些选项，从而在集群升级期间维持应用的可用性。 + +你可以在 Rancher UI 中配置升级策略，也可以通过编辑 `cluster.yml` 来配置策略。编辑 `cluster.yml` 可以配置更多高级选项。 + +### 在 Rancher UI 中配置最大不可用的 Worker 节点 + +你可以在 Rancher UI 中配置不可用 worker 节点的最大数量。在集群升级期间，worker 节点将按此大小批量升级。 + +默认情况下，不可用 worker 节点的最大数量为所有 worker 节点的 10%。此数字可以配置为百分比或整数。当定义为百分比时，批大小会被四舍五入到最近的节点，最小为一个节点。 + +要更改 worker 节点的默认数量或百分比： + +1. 在左上角，单击 **☰ > 集群管理**。 +1. 在**集群**页面中，进入要升级的集群，然后点击 **⋮ > 编辑配置**。 +1. 在**升级策略**选项卡中，输入 **Worker 并发**作为固定的数字或百分比。你可以通过将集群中的节点数减去最大不可用节点数来获取该数字。 +1. 单击**保存**。 + +**结果**：集群更新为使用新的升级策略。 + +### 使用 Rancher UI 在升级期间启用节点清空 + +默认情况下，RKE 会在升级之前[封锁](https://kubernetes.io/docs/concepts/architecture/nodes/#manual-node-administration)每个节点。默认情况下，[清空](https://kubernetes.io/docs/tasks/administer-cluster/safely-drain-node/)会在升级期间被禁用。如果在集群配置中启用了清空​​，RKE 将在升级之前对节点进行封锁和清空。 + +要在集群升级期间清空每个节点： + +1. 在左上角，单击 **☰ > 集群管理**。 +1. 在**集群**页面中，进入要启用节点清空的集群，然后点击 **⋮ > 编辑配置**。 +1. 单击 **⋮ > 编辑**。 +1. 在**升级策略**选项卡中，转到**清空节点**字段并单击**是**。controlplane 和 worker 节点的清空是单独配置的。 +1. 配置如何删除 pod 的选项。有关每个选项的详细信息，请参阅[本节](../../how-to-guides/new-user-guides/manage-clusters/nodes-and-node-pools.md#激进和安全的清空选项)。 +1. （可选）配置宽限期。宽限期是给每个 pod 进行清理的超时时间，能让 pod 有机会优雅地退出。Pod 可能需要完成任何未完成的请求、回滚事务或将状态保存到某些外部存储。如果该值为负数，将使用 pod 中指定的默认值。 +1. （可选）配置超时，这是在清空放弃之前应该继续等待的时间。 +1. 单击**保存**。 + +**结果**：集群更新为使用新的升级策略。 + +:::note + +目前存在一个[已知问题](https://github.com/rancher/rancher/issues/25478)，即使 etcd 和 controlplane 正在被清空， Rancher UI 也不会将它们的状态显示为 drained。 + +::: + +### 在升级期间维护应用的可用性 + +_从 RKE v1.1.0 起可用_ + +在 [RKE 文档](https://rancher.com/docs/rke/latest/en/upgrades/maintaining-availability/)中，你将了解在升级集群时防止应用停机的要求。 + +### 在 cluster.yml 中配置升级策略 + +你通过编辑 `cluster.yml` 来获得更高级的升级策略配置选项。 + +有关详细信息，请参阅 RKE 文档中的[配置升级策略](https://rancher.com/docs/rke/latest/en/upgrades/configuring-strategy)。这部分还包括一个用于配置升级策略的示例 `cluster.yml`。 + +## 故障排除 + +如果升级后节点没有出现，`rke up` 命令会出错。 + +如果不可用节点的数量超过配置的最大值，则不会进行升级。 + +如果升级停止，你可能需要修复不可用节点或将其从集群中删除，然后才能继续升级。 + +失败的节点可能处于许多不同的状态： + +- 关机 +- 不可用 +- 用户在升级过程中清空了节点，因此节点上没有 kubelet +- 升级本身失败 + +如果在升级过程中达到最大不可用节点数，Rancher 的下游集群将停留在更新中的状态，并且不会继续升级其他 controlplane 节点。它将继续评估不可用的节点集，以防其中一个节点变得可用。如果无法修复节点，则必须移除节点才能继续升级。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/installation-and-upgrade/upgrade-kubernetes-without-upgrading-rancher.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/installation-and-upgrade/upgrade-kubernetes-without-upgrading-rancher.md new file mode 100644 index 00000000000..5d98f3c6d53 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/installation-and-upgrade/upgrade-kubernetes-without-upgrading-rancher.md @@ -0,0 +1,93 @@ +--- +title: 在不升级 Rancher 的情况下升级 Kubernetes +--- + + + +RKE 元数据功能允许你在新版本 Kubernetes 发布后立即为集群配置新版本，而无需升级 Rancher。此功能对于使用 Kubernetes 的补丁版本非常有用，例如，在原本支持 Kubernetes v1.14.6 的 Rancher Server 版本中，将 Kubernetes 升级到 v1.14.7。 + +:::note + +Kubernetes API 可以在次要版本之间更改。因此，我们不支持引入 Kubernetes 次要版本，例如在 Rancher 支持 v1.14 的情况下引入 v1.15。在这种情况下，你需要升级 Rancher 以添加对 Kubernetes 次要版本的支持。 + +::: + +Rancher 的 Kubernetes 元数据包含 Rancher 用于配置 [RKE 集群](../../how-to-guides/new-user-guides/launch-kubernetes-with-rancher/launch-kubernetes-with-rancher.md)的 Kubernetes 版本信息。Rancher 会定期同步数据并为 **系统镜像**、**服务选项**和**插件模板**创建自定义资源定义 (CRD)。因此，当新的 Kubernetes 版本与 Rancher Server 版本兼容时，Kubernetes 元数据可以使 Rancher 使用新版本来配置集群。元数据概述了 [Rancher Kubernetes Engine](https://rancher.com/docs/rke/latest/en/) (RKE) 用于部署各种 Kubernetes 版本的信息。 + +下表描述了受周期性数据同步影响的 CRD。 + +:::note + +只有管理员可以编辑元数据 CRD。除非明确需要，否则建议不要更新现有对象。 + +::: + +| 资源 | 描述 | Rancher API URL | +|----------|-------------|-----------------| +| 系统镜像 | 用于通过 RKE 部署 Kubernetes 集群的系统镜像列表。 | `/v3/rkek8ssystemimages` | +| 服务选项 | 传递给 Kubernetes 组件的默认选项，例如 `kube-api`、`scheduler`、`kubelet`、`kube-proxy` 和 `kube-controller-manager` | `/v3/rkek8sserviceoptions` | +| 插件模板 | 用于部署插件组件的 YAML 定义，例如 Canal、Calico、Flannel、Weave、Kube-dns、CoreDNS、`metrics-server`、`nginx-ingress` | `/v3/rkeaddons` | + +管理员可以通过配置 RKE 元数据设置来执行以下操作： + +- 刷新 Kubernetes 元数据。适用于有新的 Kubernetes 补丁版本发布，而用户希望在不升级 Rancher 的情况下为集群配置最新版本的 Kubernetes 的情景。 +- 更改 Rancher 用于同步元数据的 URL。适用于要让 Rancher 从本地同步而不是与 GitHub 同步的情况。这在离线环境下非常有用。 +- 防止 Rancher 自动同步元数据。这可以防止在 Rancher 中使用新的/不受支持的 Kubernetes 版本。 + +## 刷新 Kubernetes 元数据 + +默认情况下，管理员或具有**管理集群驱动**[全局角色](../../how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/global-permissions.md)的用户，可以刷新 Kubernetes 元数据。 + +要强制 Rancher 刷新 Kubernetes 元数据，可以执行手动刷新操作： + +1. 在左上角，单击 **☰ > 集群管理**。 +1. 在左侧导航菜单中，单击**驱动**。 +1. 单击**刷新 Kubernetes 元数据**。 + +你可以将 `refresh-interval-minutes` 设置为 `0`（见下文），将 Rancher 配置为仅在需要时刷新元数据，并在需要时使用此按钮手动执行元数据刷新。 + +## 配置元数据同步 + +:::caution + +只有管​​理员可以更改这些设置。 + +::: + +RKE 元数据的配置控制 Rancher 同步元数据的频率以及从何处下载数据。你可以通过 Rancher UI 或通过 Rancher API 端点 `v3/settings/rke-metadata-config` 配置元数据。 + +元数据的配置方式取决于 Rancher 版本。 + +要在 Rancher 中编辑元数据配置： + +1. 在左上角，单击 **☰ > 全局设置**。 +1. 转到 **rke-metadata-config**。单击 **⋮ > 编辑设置**。 +1. 你可以选择填写以下参数： + +- `refresh-interval-minutes`：Rancher 等待同步元数据的时间。如果要禁用定期刷新，请将 `refresh-interval-minutes` 设置为 0。 +- `url`：Rancher 从中获取数据的 HTTP 路径。该路径必须是 JSON 文件的直接路径。例如，Rancher v2.4 的默认 URL 是 `https://releases.rancher.com/kontainer-driver-metadata/release-v2.4/data.json`。 +1. 单击**保存**。 + +如果你没有离线设置，则无需指定 Rancher 获取元数据的 URL，因为默认是从 [Rancher 的元数据 Git 仓库获取](https://github.com/rancher/kontainer-driver-metadata/blob/dev-v2.5/data/data.json)的。 + +但是，如果你有[离线设置](#离线设置)需求，你需要将 Kubernetes 元数据仓库镜像到 Rancher 可用的位置。然后，你需要更改 URL 来指向 JSON 文件的新位置。 + +## 离线设置 + +Rancher Server 会定期刷新 `rke-metadata-config` 来下载新的 Kubernetes 版本元数据。有关 Kubernetes 和 Rancher 版本的兼容性表，请参阅[服务条款](https://rancher.com/support-maintenance-terms/all-supported-versions/rancher-v2.2.8/)。 + +如果你使用离线设置，则可能无法从 Rancher 的 Git 仓库自动定期刷新 Kubernetes 元数据。在这种情况下，应该禁用定期刷新以防止在日志中显示相关错误。或者，你可以配置元数据，以便 Rancher 与本地的 RKE 元数据副本进行同步。 + +要将 Rancher 与 RKE 元数据的本地镜像同步，管理员需要配置 `rke-metadata-config` 来指向镜像。详情请参考[配置元数据同步](#配置元数据同步) + +在将新的 Kubernetes 版本加载到 Rancher Server 中之后，需要执行其他步骤才能使用它们启动集群。Rancher 需要访问更新的系统镜像。虽然只有管理员可以更改元数据设置，但任何用户都可以下载 Rancher 系统镜像并为镜像准备私有容器镜像仓库。 + +要下载私有镜像仓库的系统镜像： + +1. 点击左上角的 **☰**。 +1. 点击左侧导航底部的Rancher版本号。 +1. 下载适用于 Linux 或 Windows 操作系统的镜像。 +1. 下载 `rancher-images.txt`。 +1. 使用[离线环境安装](other-installation-methods/air-gapped-helm-cli-install/publish-images.md)时使用的步骤准备私有镜像仓库，但不要使用发布页面中的 `rancher-images.txt`，而是使用上一个步骤中获取的文件。 + +**结果**：Rancher 的离线安装现在可以同步 Kubernetes 元数据。如果你在发布新版本的 Kubernetes 时更新了私有镜像仓库，你可以使用新版本配置集群，而无需升级 Rancher。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/overview.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/overview.md new file mode 100644 index 00000000000..e2826075461 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/overview.md @@ -0,0 +1,65 @@ +--- +title: 概述 +--- + +Rancher 是一个为使用容器的公司打造的容器管理平台。Rancher 使得开发者可以随处运行 Kubernetes（Run Kubernetes Everywhere），满足 IT 需求规范，赋能 DevOps 团队。 + +## Run Kubernetes Everywhere + +Kubernetes 已经成为容器编排标准。现在，大多数云和虚拟化提供商都提供容器编排服务。Rancher 用户可以选择使用 Rancher Kubernetes distributions（RKE2/K3s）或云 Kubernetes 服务（例如 GKE、AKS 和 EKS）创建 Kubernetes 集群，还可以导入和管理使用任何 Kubernetes 发行版或安装程序创建的现有 Kubernetes 集群。 + +## 满足 IT 需求规范 + +Rancher 支持对其控制的所有 Kubernetes 集群进行集中认证、访问控制和监控。例如，你可以： + +- 使用你的 Active Directory 凭证访问由云提供商（例如 GKE）托管的 Kubernetes 集群。 +- 设置所有用户、组、项目、集群和云服务的权限控制策略和安全策略。 +- 一站式查看 Kubernetes 集群的运行状况和容量。 + +## 赋能 DevOps 团队 + +Rancher 为 DevOps 工程师提供简单直接的用户界面，以管理其应用负载。用户不需要对 Kubernetes 有非常深入的了解，即可使用 Rancher。Rancher 应用商店包含一套实用的 DevOps 开发工具。Rancher 获得了多种云原生生态系统产品的认证，包括安全工具、监控系统、容器镜像仓库、存储和网络驱动等。 + +下图讲述了 Rancher 在 IT 管理团队和 DevOps 开发团队之间扮演的角色。DevOps 团队把他们的应用部署在他们选择的公有云或私有云上。IT 管理员负责查看并管理用户、集群、云服务的权限。 + +![平台](/img/platform.png) + +## Rancher API Server 的功能 + +Rancher API Server 是基于嵌入式 Kubernetes API Server 和 etcd 数据库建立的，它提供了以下功能： + +### 授权和基于角色的权限控制（RBAC） + +- **用户管理**：Rancher API Server 除了管理本地用户，还[管理用户用来访问外部服务所需的认证信息](../how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/authentication-config/authentication-config.md)，如登录 Active Directory 和 GitHub 所需的账号密码。 +- **授权**：Rancher API Server 可以管理[访问控制策略](../how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/manage-role-based-access-control-rbac.md)和[安全标准](../how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/pod-security-standards.md)。 + +### 使用 Kubernetes 的功能 + +- **配置 Kubernetes 集群**：Rancher API Server 可以在已有节点上[配置 Kubernetes](../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/kubernetes-clusters-in-rancher-setup.md)，或进行 [Kubernetes 版本升级](installation-and-upgrade/upgrade-and-roll-back-kubernetes.md)。 +- **管理应用商店**：Rancher 支持使用 [Helm Chart 应用商店](../how-to-guides/new-user-guides/helm-charts-in-rancher/helm-charts-in-rancher.md)实现轻松重复部署应用。 +- **管理项目**：项目由集群中多个命名空间和访问控制策略组成，是 Rancher 中的一个概念，Kubernetes 中并没有这个概念。你可以使用项目实现以组为单位，管理多个命名空间，并进行 Kubernetes 相关操作。Rancher UI 提供用于[项目管理](../how-to-guides/advanced-user-guides/manage-projects/manage-projects.md)和[项目内应用管理](../how-to-guides/new-user-guides/kubernetes-resources-setup/kubernetes-resources-setup.md)的功能。 +- **Fleet 持续交付**：在 Rancher 中，你可以使用 [Fleet 持续交付](../integrations-in-rancher/fleet/fleet.md)将应用程序从 Git 仓库部署到目标下游 Kubernetes 集群，无需任何手动操作。 +- **Istio**：[Rancher 与 Istio 集成](../integrations-in-rancher/istio/istio.md)，使得管理员或集群所有者可以将 Istio 交给开发者，然后开发者使用 Istio 执行安全策略，排查问题，或为蓝绿部署，金丝雀部署，和 A/B 测试进行流量管理。 + +### 配置云基础设施 + +- **同步节点信息**：Rancher API Server 可以同步所有集群中全部[节点](../how-to-guides/new-user-guides/manage-clusters/nodes-and-node-pools.md)的信息。 +- **配置云基础设施**：如果你为 Rancher 配置了云提供商，Rancher 可以在云端动态配置[新节点](../how-to-guides/new-user-guides/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/use-new-nodes-in-an-infra-provider.md)和[持久化存储](../how-to-guides/new-user-guides/manage-clusters/create-kubernetes-persistent-storage/create-kubernetes-persistent-storage.md)。 + +### 查看集群信息 + +- **日志管理**：Rancher 可以与多种 Kubernetes 集群之外的主流日志管理工具集成。 +- **监控**：你可以使用 Rancher，通过业界领先并开源的 Prometheus 来监控集群节点、Kubernetes 组件和软件部署的状态和进程。 +- **告警**：为了保证集群和应用的正常运行，提高公司的生产效率，你需要随时了解集群和项目的计划内和非计划事件。 + +## 使用 Rancher 编辑下游集群 + +对于已有集群而言，可提供的选项和设置取决于你配置集群的方法。 + +使用 Rancher 创建集群后，集群管理员可以管理集群成员，管理节点池，或进行[其他操作](../reference-guides/cluster-configuration/cluster-configuration.md)。 + +下表总结了每一种类型的集群和对应的可编辑的选项和设置： + +import ClusterCapabilitiesTable from '../shared-files/_cluster-capabilities-table.md'; + + diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/quick-start-guides/deploy-rancher-manager/aws-marketplace.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/quick-start-guides/deploy-rancher-manager/aws-marketplace.md new file mode 100644 index 00000000000..1d06135d7f4 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/quick-start-guides/deploy-rancher-manager/aws-marketplace.md @@ -0,0 +1,6 @@ +--- +title: Rancher Prime AWS Marketplace 快速入门 +description: 使用 Amazon Marketplace 列表部署 Rancher Server。 +--- + +你可以快速将 Rancher Prime 部署到 Amazon Elastic Kubernetes Service (EKS)。详情请参见[说明](https://suse-enceladus.github.io/marketplace-docs/rancher-prime/aws/?repository=rancher-payg-billing-adapter-llc-prd)以及我们的 [Amazon Marketplace 列表](https://aws.amazon.com/marketplace/pp/prodview-go7ent7goo5ae)。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/quick-start-guides/deploy-rancher-manager/aws.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/quick-start-guides/deploy-rancher-manager/aws.md new file mode 100644 index 00000000000..e9d2326317e --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/quick-start-guides/deploy-rancher-manager/aws.md @@ -0,0 +1,95 @@ +--- +title: Rancher AWS 快速入门指南 +description: 阅读此分步 Rancher AWS 指南，以快速部署带有单节点下游 Kubernetes 集群的 Rancher Server。 +--- + +你可以参考以下步骤，在 AWS 的单节点 K3s Kubernetes 集群中快速部署 Rancher Server，并附加一个单节点下游 Kubernetes 集群。 + +:::caution + +本章节中提供的指南，旨在帮助你快速启动一个用于 Rancher 的沙盒，以评估 Rancher 是否能满足你的使用需求。快速入门指南不适用于生产环境。如果你需要获取生产环境的操作指导，请参见[安装](../../installation-and-upgrade/installation-and-upgrade.md)。 + +::: + +## 先决条件 + +:::caution + +部署到 Amazon AWS 会产生费用。 + +::: + +- [Amazon AWS 账号](https://aws.amazon.com/account/): 用于创建部署 Rancher Server 和 Kubernetes 的资源。 +- [Amazon AWS 访问密钥](https://docs.aws.amazon.com/general/latest/gr/managing-aws-access-keys.html)：如果你没有的话，请访问此链接查看相关指南。 +- [已创建 IAM 策略](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_create.html#access_policies_create-start)：定义附加此策略的账号所具有的权限。 +- [Terraform](https://developer.hashicorp.com/terraform/install): 用于在 Amazon AWS 中配置服务器和集群。 + +### IAM 策略示例 + +AWS 模块只创建一个 EC2 密钥对、一个 EC2 安全组和一个 EC2 实例。以下是一个简单的策略： + +```json +{ + "Version": "2012-10-17", + "Statement": [ + { + "Effect": "Allow", + "Action": "ec2:*", + "Resource": "*" + } + ] +} +``` + +## 开始使用 + +1. 使用命令行工具，执行 `git clone https://github.com/rancher/quickstart` 把 [Rancher Quickstart](https://github.com/rancher/quickstart) 克隆到本地。 + +2. 执行 `cd quickstart/rancher/aws` 命令，进入包含 Terraform 文件的 AWS 文件夹。 + +3. 把 `terraform.tfvars.example` 文件重命名为 `terraform.tfvars`。 + +4. 编辑 `terraform.tfvars` 文件，并替换以下变量： + + - `aws_access_key` - 替换为 Amazon AWS 访问密钥 + - `aws_secret_key` - 替换为 Amazon AWS Secret 密钥 + - `rancher_server_admin_password` - 替换为创建 Rancher Server 的 admin 账号的密码（最少 12 字符） + +5. **可选**：修改 `terraform.tfvars` 中的可选参数。参见 [Quickstart Readme](https://github.com/rancher/quickstart) 以及 [AWS Quickstart Readme](https://github.com/rancher/quickstart/tree/master/rancher/aws) 了解更多信息。 + 建议包括： + + - `aws_region` - Amazon AWS 区域。AWS 的默认区域 (`us-east-1`) 不一定是距离你最近的区域。建议修改为距离你最近的区域。 + - `prefix` - 所有创建资源的前缀 + - `instance_type` - EC2 使用的实例规格，最小规格为 `t3a.medium` 。如果在预算范围内，可以使用 `t3a.large` 或 `t3a.xlarge`。 + - `add_windows_node` - 如果设为 true，一个额外的 Windows worker 节点会添加到工作负载集群中。 + +6. 执行 `terraform init`。 + +7. 执行 `terraform apply --auto-approve` 以初始化环境。然后，等待命令行工具返回以下信息： + + ``` + Apply complete! Resources: 16 added, 0 changed, 0 destroyed. + + Outputs: + + rancher_node_ip = xx.xx.xx.xx + rancher_server_url = https://rancher.xx.xx.xx.xx.sslip.io + workload_node_ip = yy.yy.yy.yy + ``` + +8. 将以上输出中的 `rancher_server_url` 粘贴到浏览器中。在登录页面中登录（默认用户名为 `admin`，密码为在 `rancher_server_admin_password` 中设置的密码）。 +9. 使用 `quickstart/rancher/aws` 中生成的 `id_rsa` 密钥 SSH 到 Rancher Server。 + +##### 结果 + +两个 Kubernetes 集群已部署到你的 AWS 账户中，一个运行 Rancher Server，另一个为实验部署做好准备。请注意，虽然这种设置是探索 Rancher 功能的好方法，但在生产环境中，应遵循我们的高可用设置指南。用于虚拟机的 SSH 密钥是自动生成的，存储在模块目录中。 + +## 后续操作 + +使用 Rancher 创建 deployment。详情请参见[创建 Deployment](../deploy-workloads/deploy-workloads.md)。 + +## 销毁环境 + +1. 进入 `quickstart/rancher/aws` 文件夹，然后执行 `terraform destroy --auto-approve`。 + +2. 等待命令行界面显示资源已删除的消息。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/quick-start-guides/deploy-rancher-manager/azure.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/quick-start-guides/deploy-rancher-manager/azure.md new file mode 100644 index 00000000000..8bbed80a2a3 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/quick-start-guides/deploy-rancher-manager/azure.md @@ -0,0 +1,81 @@ +--- +title: Rancher Azure 快速入门指南 +description: 阅读此分步 Rancher Azure 指南，以快速部署带有单节点下游 Kubernetes 集群的 Rancher Server。 +--- + +你可以参考以下步骤，在 Azure 的单节点 K3s Kubernetes 集群中快速部署 Rancher Server，并附加一个单节点下游 Kubernetes 集群。 + +:::caution + +本章节中提供的指南，旨在帮助你快速启动一个用于 Rancher 的沙盒，以评估 Rancher 是否能满足你的使用需求。快速入门指南不适用于生产环境。如果你需要获取生产环境的操作指导，请参见[安装](../../installation-and-upgrade/installation-and-upgrade.md)。 + +::: + +## 先决条件 + +:::caution + +部署到 Microsoft Azure 会产生费用。 + +::: + +- [Microsoft Azure 账号](https://azure.microsoft.com/en-us/free/)：用于创建部署 Rancher 和 Kubernetes 的资源。 +- [Microsoft Azure 订阅](https://docs.microsoft.com/en-us/azure/cost-management-billing/manage/create-subscription#create-a-subscription-in-the-azure-portal)：如果你没有的话，请访问此链接查看如何创建 Microsoft Azure 订阅。 +- [Micsoroft Azure 租户](https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-create-new-tenant)：访问此链接并参考教程以创建 Microsoft Azure 租户。 +- [Microsoft Azure 客户端 ID/密文](https://docs.microsoft.com/en-us/azure/active-directory/develop/howto-create-service-principal-portal)：访问此链接并参考教程以创建 Microsoft Azure 客户端和密文。 +- [Terraform](https://developer.hashicorp.com/terraform/install)：用于在 Microsoft Azure 中配置服务器和集群。 + + +## 开始使用 + +1. 使用命令行工具，执行 `git clone https://github.com/rancher/quickstart` 把 [Rancher Quickstart](https://github.com/rancher/quickstart) 克隆到本地。 + +2. 执行 `cd quickstart/rancher/azure` 命令，进入包含 Terraform 文件的 Azure 文件夹。 + +3. 把 `terraform.tfvars.example` 文件重命名为 `terraform.tfvars`。 + +4. 编辑 `terraform.tfvars` 文件，并替换以下变量： + - `azure_subscription_id` - 替换为 Microsoft Azure 订阅 ID。 + - `azure_client_id` - 替换为 Microsoft Azure 客户端 ID。 + - `azure_client_secret` - 替换为 Microsoft Azure 客户端密文。 + - `azure_tenant_id` - 替换为 Microsoft Azure 租户 ID。 + - `rancher_server_admin_password` - 替换为创建 Rancher Server 的 admin 账号的密码（最少 12 字符） + +5. **可选**：修改 `terraform.tfvars` 中的可选参数。 + 参见 [Quickstart Readme](https://github.com/rancher/quickstart) 以及 [Azure Quickstart Readme](https://github.com/rancher/quickstart/tree/master/rancher/azure) 了解更多信息。建议包括： + - `azure_location` - Microsoft Azure 区域。Azure 的默认区域 (`East US`) 不一定是距离你最近的区域。建议修改为距离你最近的区域。 + - `prefix` - 所有创建资源的前缀 + - `instance_type` - 使用的计算实例大小，最小规格为 `Standard_DS2_v2`。如果在预算范围内，可以使用 `Standard_DS2_v3` 或 `Standard_DS3_v2`。 + - `add_windows_node` - 如果设为 true，一个额外的 Windows worker 节点会添加到工作负载集群中。 + - `windows_admin_password` - Windows worker 节点管理员的密码 + +6. 执行 `terraform init`。 + +7. 执行 `terraform apply --auto-approve` 以初始化环境。然后，等待命令行工具返回以下信息： + + ``` + Apply complete! Resources: 16 added, 0 changed, 0 destroyed. + + Outputs: + + rancher_node_ip = xx.xx.xx.xx + rancher_server_url = https://rancher.xx.xx.xx.xx.sslip.io + workload_node_ip = yy.yy.yy.yy + ``` + +8. 将以上输出中的 `rancher_server_url` 粘贴到浏览器中。在登录页面中登录（默认用户名为 `admin`，密码为在 `rancher_server_admin_password` 中设置的密码）。 +9. 使用 `quickstart/rancher/azure` 中生成的 `id_rsa` 密钥 SSH 到 Rancher Server。 + +#### 结果 + +两个 Kubernetes 集群已部署到你的 Azure 账户中，一个运行 Rancher Server，另一个为实验部署做好准备。请注意，虽然这种设置是探索 Rancher 功能的好方法，但在生产环境中，应遵循我们的高可用设置指南。用于虚拟机的 SSH 密钥是自动生成的，存储在模块目录中。 + +### 后续操作 + +使用 Rancher 创建 deployment。详情请参见[创建 Deployment](../deploy-workloads/deploy-workloads.md)。 + +## 销毁环境 + +1. 进入 `quickstart/rancher/azure` 文件夹，然后执行 `terraform destroy --auto-approve`。 + +2. 等待命令行界面显示资源已删除的消息。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/quick-start-guides/deploy-rancher-manager/deploy-rancher-manager.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/quick-start-guides/deploy-rancher-manager/deploy-rancher-manager.md new file mode 100644 index 00000000000..5eebb87e4e8 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/quick-start-guides/deploy-rancher-manager/deploy-rancher-manager.md @@ -0,0 +1,20 @@ +--- +title: 部署 Rancher Server +--- + +你可使用以下指南之一，在你选择的提供商中部署和配置 Rancher 和 Kubernetes 集群。 + +- [AWS](aws.md)（使用 Terraform） +- [AWS Marketplace](aws-marketplace.md)（使用 Amazon EKS） +- [Azure](azure.md)（使用 Terraform） +- [DigitalOcean](digitalocean.md)（使用 Terraform） +- [GCP](gcp.md)（使用 Terraform） +- [Hetzner Cloud](hetzner-cloud.md)（使用 Terraform） +- [Linode](linode.md) (使用 Terraform) +- [Vagrant](vagrant.md) +- [Equinix Metal](equinix-metal.md) +- [Outscale](outscale-qs.md)（使用 Terraform） + +如有需要，你可以查看以下指南以了解分步步骤。如果你需要在其他提供商中或本地运行 Rancher，或者你只是想看看它是多么容易上手，你可阅读以下指南： + +- [手动安装](helm-cli.md) diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/quick-start-guides/deploy-rancher-manager/digitalocean.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/quick-start-guides/deploy-rancher-manager/digitalocean.md new file mode 100644 index 00000000000..b57cada0150 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/quick-start-guides/deploy-rancher-manager/digitalocean.md @@ -0,0 +1,74 @@ +--- +title: Rancher DigitalOcean 快速入门指南 +description: 阅读此分步 Rancher DigitalOcean 指南，以快速部署带有单节点下游 Kubernetes 集群的 Rancher Server。 +--- + +你可以参考以下步骤，在 DigitalOcean 的单节点 K3s Kubernetes 集群中快速部署 Rancher Server，并附加一个单节点下游 Kubernetes 集群。 + +:::caution + +本章节中提供的指南，旨在帮助你快速启动一个用于 Rancher 的沙盒，以评估 Rancher 是否能满足你的使用需求。快速入门指南不适用于生产环境。如果你需要获取生产环境的操作指导，请参见[安装](../../installation-and-upgrade/installation-and-upgrade.md)。 + +::: + +## 先决条件 + +:::caution + +部署到 DigitalOcean 会产生费用。 + +::: + +- [DigitalOcean 账号](https://www.digitalocean.com)：用于运行服务器和集群。 +- [DigitalOcean 访问密钥](https://www.digitalocean.com/community/tutorials/how-to-create-a-digitalocean-space-and-api-key)：如果你没有的话，请访问此链接创建一个。 +- [Terraform](https://developer.hashicorp.com/terraform/install)：用于在 DigitalOcean 中配置服务器和集群。 + + +## 开始使用 + +1. 使用命令行工具，执行 `git clone https://github.com/rancher/quickstart` 把 [Rancher Quickstart](https://github.com/rancher/quickstart) 克隆到本地。 + +2. 执行 `cd quickstart/rancher/do` 命令，进入包含 Terraform 文件的 DigitalOcean 文件夹。 + +3. 把 `terraform.tfvars.example` 文件重命名为 `terraform.tfvars`。 + +4. 编辑 `terraform.tfvars` 文件，并替换以下变量： + - `do_token` - 替换为 DigitalOcean 访问密钥 + - `rancher_server_admin_password` - 替换为创建 Rancher Server 的 admin 账号的密码（最少 12 字符） + +5. **可选**：修改 `terraform.tfvars` 中的可选参数。 + 参见 [Quickstart Readme](https://github.com/rancher/quickstart) 以及 [DO Quickstart Readme](https://github.com/rancher/quickstart/tree/master/rancher/do) 了解更多信息。建议包括： + - `do_region` - DigitalOcean 区域。DigitalOcean 的默认区域不一定是距离你最近的区域。建议修改为距离你最近的区域。 + - `prefix` - 所有创建资源的前缀 + - `droplet_size` - 使用的计算实例规格，最小规格为`s-2vcpu-4gb`。如果在预算范围内，可以使用 `s-4vcpu-8gb`。 + +6. 执行 `terraform init`。 + +7. 执行 `terraform apply --auto-approve` 以初始化环境。然后，等待命令行工具返回以下信息： + + ``` + Apply complete! Resources: 15 added, 0 changed, 0 destroyed. + + Outputs: + + rancher_node_ip = xx.xx.xx.xx + rancher_server_url = https://rancher.xx.xx.xx.xx.sslip.io + workload_node_ip = yy.yy.yy.yy + ``` + +8. 将以上输出中的 `rancher_server_url` 粘贴到浏览器中。在登录页面中登录（默认用户名为 `admin`，密码为在 `rancher_server_admin_password` 中设置的密码）。 +9. 使用 `quickstart/rancher/do` 中生成的 `id_rsa` 密钥 SSH 到 Rancher Server。 + +#### 结果 + +两个 Kubernetes 集群已部署到你的 DigitalOcean 账户中，一个运行 Rancher Server，另一个为实验部署做好准备。请注意，虽然这种设置是探索 Rancher 功能的好方法，但在生产环境中，应遵循我们的高可用设置指南。用于虚拟机的 SSH 密钥是自动生成的，存储在模块目录中。 + +### 后续操作 + +使用 Rancher 创建 deployment。详情请参见[创建 Deployment](../deploy-workloads/deploy-workloads.md)。 + +## 销毁环境 + +1. 进入 `quickstart/rancher/do` 文件夹，然后执行 `terraform destroy --auto-approve`。 + +2. 等待命令行界面显示资源已删除的消息。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/quick-start-guides/deploy-rancher-manager/equinix-metal.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/quick-start-guides/deploy-rancher-manager/equinix-metal.md new file mode 100644 index 00000000000..43370362d12 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/quick-start-guides/deploy-rancher-manager/equinix-metal.md @@ -0,0 +1,104 @@ +--- +title: Rancher Equinix Metal 快速入门 +--- + +## 本章节引导你： + +- 配置 Equinix Metal server +- 安装 Rancher 2.x +- 创建你的第一个集群 +- 部署一个 Nginx 应用 + +:::caution + +本章节中提供的指南，旨在帮助你快速启动一个用于 Rancher 的沙盒，以评估 Rancher 是否能满足你的使用需求。不建议将 Docker 安装用于生产环境。如果你需要获取生产环境的操作指导，请参见[安装](../../installation-and-upgrade/installation-and-upgrade.md)。 + +::: + +## 快速入门概述 + +本指南划分为不同任务，以便于使用。 + +
+ +## 先决条件 + +- [Equinix Metal 账号](https://deploy.equinix.com/developers/docs/metal/identity-access-management/users/) +- [Equinix Metal 项目](https://deploy.equinix.com/developers/docs/metal/projects/creating-a-project/) + + +### 1. 配置 Equinix Metal 主机 + +开始部署 Equinix Metal 主机。你可以使用 Equinix Metal 控制台、CLI 或 API 来配置 Equinix Metal Server。如果你需要了解每种 Deployment 类型的说明，请参见 [Equinix Metal 部署](https://metal.equinix.com/developers/docs/deploy/on-demand/)。You can find additional information on Equinix Metal server types in the [Equinix Metal Documentation](https://deploy.equinix.com/developers/docs/metal/hardware/standard-servers/). + +:::note 注意事项： + +- 如果使用 CLI 或 API 配置新的 Equinix Metal Server，你需要提供项目 ID、计划、metro 和操作系统。 +- 当使用云主机的虚拟机时，你需要允许 80 和 443 端口的入站 TCP 通信。有关端口配置的信息，请参见你的云主机的文档。 +- 如需了解所有端口要求，请参见 [Docker 安装](../../../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/node-requirements-for-rancher-managed-clusters.md)。 +- 根据我们的[要求](../../installation-and-upgrade/installation-requirements/installation-requirements.md)配置主机。 + +::: +### 2. 安装 Rancher + +要在 Equinix Metal 主机上安装 Rancher，先与它连接，然后使用 shell 进行安装。 + +1. 使用你惯用的 shell（例如 PuTTy 或远程终端）登录到你的 Equinix Metal 主机。 + +2. 在 shell 中执行以下命令： + + ``` + sudo docker run -d --restart=unless-stopped -p 80:80 -p 443:443 --privileged rancher/rancher + ``` + +**结果**：Rancher 已安装。 + +### 3. 登录 + +登录到 Rancher 后，你还需要进行一些一次性配置。 + +1. 打开 Web 浏览器并输入主机的 IP 地址`https://`。 + + 将 `` 替换为你的主机 IP 地址。 + +2. 出现提示时，为默认 `admin` 账号创建密码。 + +3. 设置 **Rancher Server URL**。URL 可以是 IP 地址或主机名。需要注意，添加到集群中的每个节点都必须能够连接到此 URL。

如果你在 URL 中使用主机名，则此主机名必须在 DNS 中解析到你需要添加到集群的节点上。 + +
+ +### 4. 创建集群 + +欢迎使用 Rancher！现在，你可以创建你的第一个 Kubernetes 集群了。 + +在此任务中，你可以使用**自定义**选项。此选项允许你把 _任意_ Linux 主机（云虚拟机、本地虚拟机或裸机）添加到集群中。 + +1. 点击 **☰ > 集群管理**。 +1. 在**集群**页面，点击**创建**。 +1. 选择**自定义**。 +1. 输入**集群名称**。 +1. 点击**下一步**。 +1. 在**节点角色**中，选择 _全部_ 角色，即 **etcd**，**Control** 和 **Worker**。 + - **可选**：Rancher 会自动检测用于 Rancher 通信和集群通信的 IP 地址。你可以使用**节点地址**处的`公有地址`和`内网地址`进行覆盖。 +1. 将注册命令复制到剪贴板。 +1. 使用你惯用的 shell（例如 PuTTy 或远程终端）登录到你的 Linux 主机。粘贴剪贴板的命令并运行。 +1. 在 Linux 主机上运行完命令后，单击**完成**。 + +**结果**： + +你已创建集群，集群的状态是**配置中**。Rancher 已在你的集群中。 + +当集群状态变为 **Active** 后，你可访问集群。 + +**Active** 状态的集群会分配到两个项目： + +- `Default`：包含 `default` 命名空间 +- `System`：包含 `cattle-system`，`ingress-nginx`，`kube-public` 和 `kube-system` 命名空间。 + +#### 已完成！ + +恭喜！你已创建第一个集群。 + +#### 后续操作 + +使用 Rancher 创建 deployment。详情请参见[创建 Deployment](../deploy-workloads/deploy-workloads.md)。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/quick-start-guides/deploy-rancher-manager/gcp.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/quick-start-guides/deploy-rancher-manager/gcp.md new file mode 100644 index 00000000000..053bc2d0eaa --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/quick-start-guides/deploy-rancher-manager/gcp.md @@ -0,0 +1,77 @@ +--- +title: Rancher GCP 快速入门指南 +description: 阅读此分步 Rancher GCP 指南，以快速部署带有单节点下游 Kubernetes 集群的 Rancher Server。 +--- + +你可以参考以下步骤，在 GCP 的单节点 K3s Kubernetes 集群中快速部署 Rancher Server，并附加一个单节点下游 Kubernetes 集群。 + +:::caution + +本章节中提供的指南，旨在帮助你快速启动一个用于 Rancher 的沙盒，以评估 Rancher 是否能满足你的使用需求。快速入门指南不适用于生产环境。如果你需要获取生产环境的操作指导，请参见[安装](../../installation-and-upgrade/installation-and-upgrade.md)。 + +::: + +## 先决条件 + +:::caution + +部署到 Google GCP 会产生费用。 + +::: + +- [Google GCP Account](https://console.cloud.google.com/)：用于创建部署 Rancher 和 Kubernetes 的资源。 +- [Google GCP 项目](https://cloud.google.com/appengine/docs/standard/nodejs/building-app/creating-project)：如果你没有的话，请访问此链接查看如何创建 GCP 项目。 +- [Google GCP ServiceAccount](https://cloud.google.com/iam/docs/creating-managing-service-account-keys)：请访问此链接查看如何创建 GCP ServiceAccount 和 Token 文件。 +- [Terraform](https://developer.hashicorp.com/terraform/install)：用于在 Google GCP 中配置服务器和集群。 + + +## 开始使用 + +1. 使用命令行工具，执行 `git clone https://github.com/rancher/quickstart` 把 [Rancher Quickstart](https://github.com/rancher/quickstart) 克隆到本地。 + +2. 执行 `cd quickstart/rancher/gcp` 命令，进入包含 Terraform 文件的 GCP 文件夹。 + +3. 把 `terraform.tfvars.example` 文件重命名为 `terraform.tfvars`。 + +4. 编辑 `terraform.tfvars` 文件，并替换以下变量： + - `gcp_account_json` - 替换为 GCP ServiceAccount 文件路径和文件名。 + - `rancher_server_admin_password` - 替换为创建 Rancher Server 的 admin 账号的密码（最少 12 字符） + +5. **可选**：修改 `terraform.tfvars` 中的可选参数。 + 参见 [Quickstart Readme](https://github.com/rancher/quickstart) 以及 [GCP Quickstart Readme](https://github.com/rancher/quickstart/tree/master/rancher/gcp) 了解更多信息。 + 建议包括： + - `gcp_region` - Google GCP 区域。GCP 的默认区域 (`us-east4`) 不一定是距离你最近的区域。建议修改为距离你最近的区域。 + - `gcp_zone` - Google GCP 区域。GCP 的默认区域 (`us-east4-a`) 不一定是距离你最近的区域。建议修改为距离你最近的区域。 + - `prefix` - 所有创建资源的前缀 + - `machine_type` - 使用的计算实例大小，最小规格为 `n1-standard-1`。如果在预算范围内，可以使用 `n1-standard-2` 或 `n1-standard-4`。 + +6. 执行 `terraform init`。 + +7. 执行 `terraform apply --auto-approve` 以初始化环境。然后，等待命令行工具返回以下信息： + + ``` + Apply complete! Resources: 16 added, 0 changed, 0 destroyed. + + Outputs: + + rancher_node_ip = xx.xx.xx.xx + rancher_server_url = https://rancher.xx.xx.xx.xx.sslip.io + workload_node_ip = yy.yy.yy.yy + ``` + +8. 将以上输出中的 `rancher_server_url` 粘贴到浏览器中。在登录页面中登录（默认用户名为 `admin`，密码为在 `rancher_server_admin_password` 中设置的密码）。 +9. 使用 `quickstart/rancher/gcp` 中生成的 `id_rsa` 密钥 SSH 到 Rancher Server。 + +#### 结果 + +两个 Kubernetes 集群已部署到你的 GCP 账户中，一个运行 Rancher Server，另一个为实验部署做好准备。请注意，虽然这种设置是探索 Rancher 功能的好方法，但在生产环境中，应遵循我们的高可用设置指南。用于虚拟机的 SSH 密钥是自动生成的，存储在模块目录中。 + +### 后续操作 + +使用 Rancher 创建 deployment。详情请参见[创建 Deployment](../deploy-workloads/deploy-workloads.md)。 + +## 销毁环境 + +1. 进入 `quickstart/rancher/gcp` 文件夹，然后执行 `terraform destroy --auto-approve`。 + +2. 等待命令行界面显示资源已删除的消息。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/quick-start-guides/deploy-rancher-manager/helm-cli.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/quick-start-guides/deploy-rancher-manager/helm-cli.md new file mode 100644 index 00000000000..ab70519ffc4 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/quick-start-guides/deploy-rancher-manager/helm-cli.md @@ -0,0 +1,150 @@ +--- +title: Helm CLI 快速入门 +--- + +本文提供了快速安装 Rancher 的方法。 + +这些说明假设你有一个 Linux 虚拟机，并能从本地工作站与之通信。Rancher 将安装在 Linux 主机上。你将需要检索该主机的 IP 地址，以便从本地工作站访问 Rancher。Rancher 旨在远程管理 Kubernetes 集群，因此 Rancher 管理的任何 Kubernetes 集群也都需要能够访问该 IP 地址。 + +我们不建议在本地安装 Rancher，因为它会产生网络问题。如果你在 localhost 上安装 Rancher，Rancher 无法与下游 Kubernetes 集群通信，因此在 localhost 上你无法测试 Rancher 的集群配置和集群管理功能。 + +你的 Linux 主机可以位于任何地方。例如，它可以是 Amazon EC2 实例、Digital Ocean Droplet 或 Azure 虚拟机。其他 Rancher 文档也经常称它们为“节点”。部署 Linux 主机的一种方法是设置一个 Amazon EC2 实例，如[本教程](../../../how-to-guides/new-user-guides/infrastructure-setup/nodes-in-amazon-ec2.md)中所示。 + +完整的安装要求在[这里](../../installation-and-upgrade/installation-requirements/installation-requirements.md)。 + +## 在 Linux 上安装 K3s + +Rancher 需要安装在支持的 Kubernetes 版本上。如需了解你使用的 Rancher 版本支持哪些 Kubernetes 版本，请参见 [Rancher 支持矩阵](https://www.suse.com/suse-rancher/support-matrix/all-supported-versions/)。 + +如需指定 K3s（Kubernetes）版本，在运行 K3s 安装脚本时使用 `INSTALL_K3S_VERSION` 环境变量（例如 `INSTALL_K3S_VERSION="v1.24.10+k3s1"`）。 + +在 Linux 主机上运行以下命令来安装 K3s 集群： + +``` +curl -sfL https://get.k3s.io | INSTALL_K3S_VERSION= sh -s - server --cluster-init +``` + +`--cluster-init` 允许 K3s 使用嵌入式 etcd 作为数据存储，并能够转换为 HA 设置。请参阅[嵌入式数据库的高可用性](https://rancher.com/docs/k3s/latest/en/installation/ha-embedded/)。 + +保存 Linux 主机的 IP。 + +## 将 kubeconfig 保存到你的工作站 + +kubeconfig 文件对于访问 Kubernetes 集群非常重要。从 Linux 主机复制 `/etc/rancher/k3s/k3s.yaml` 中的文件，并将其保存到本地工作站的 `~/.kube/config` 目录中。一种方法是使用 `scp` 工具并在本地计算机上运行此命令： + + + + +``` +scp root@:/etc/rancher/k3s/k3s.yaml ~/.kube/config +``` + +在某些情况下，它可能需要确保你的 shell 定义了环境变量 `KUBECONFIG=~/.kube/config`，例如，它可以在你的配置文件或 rc 文件中导出。 + + + + +默认情况下不能识别“scp”命令，所以我们需要先安装一个模块。 + +在 Windows Powershell 中： + +``` +Find-Module Posh-SSH +Install-Module Posh-SSH + +## 获取远程 kubeconfig 文件 +scp root@:/etc/rancher/k3s/k3s.yaml $env:USERPROFILE\.kube\config +``` + + + + +## 在 kubeconfig 中编辑 Rancher Server URL + +在 kubeconfig 文件中，你需要将 `server` 字段的值更改为 `:6443`。你可以通过端口 6443 访问 Kubernetes API Server，通过端口 80 和 443 访问 Rancher Server。你需要进行此编辑，以便你从本地工作站运行 Helm 或 kubectl 命令时，能够与安装了 Rancher 的 Kubernetes 集群进行通信。 + + + + +打开 kubeconfig 文件进行编辑的一种方法是使用 Vim： + +``` +vi ~/.kube/config +``` + +输入 `i` 以打开 Vim 的插入模式。要保存你的工作，请按 `Esc`。然后输入 `:wq` 并按 `Enter`。 + + + + + +在 Windows Powershell 中，你可以使用 `notepad.exe` 来编辑 kubeconfig 文件： + +``` +notepad.exe $env:USERPROFILE\.kube\config +``` + +编辑完成后，按 `ctrl+s` 或转到 `File > Save` 来保存你的工作。 + + + + +## 使用 Helm 来安装 Rancher + +从本地工作站运行以下命令。你需要先安装 [kubectl](https://kubernetes.io/docs/tasks/tools/#kubectl) 和 [helm](https://helm.sh/docs/intro/install/)： + +:::note + +要查看自定义 cert-manager 安装的选项（包括集群使用 PodSecurityPolicies 的情况），请参阅 [cert-manager 文档](https://artifacthub.io/packages/helm/cert-manager/cert-manager#configuration)。 + +::: + +``` +helm repo add rancher-latest https://releases.rancher.com/server-charts/latest + +kubectl create namespace cattle-system + +kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download//cert-manager.crds.yaml + +helm repo add jetstack https://charts.jetstack.io + +helm repo update + +helm install cert-manager jetstack/cert-manager \ + --namespace cert-manager \ + --create-namespace + +# Windows Powershell +helm install cert-manager jetstack/cert-manager ` + --namespace cert-manager ` + --create-namespace +``` + +安装 Rancher 的最终命令如下。该命令需要一个将流量转发到 Linux 主机的域名。为了简化本教程，你可以使用假域名。`.sslip.io` 是一个假域名的例子。 + +要安装特定的 Rancher 版本，请使用 `--version` 标志（例如，`--version 2.6.6`）。否则，默认安装最新的 Rancher。请参阅[选择 Rancher 版本](../../installation-and-upgrade/resources/choose-a-rancher-version.md)。 + +请注意，密码至少需要 12 个字符。 + +``` +helm install rancher rancher-latest/rancher \ + --namespace cattle-system \ + --set hostname=.sslip.io \ + --set replicas=1 \ + --set bootstrapPassword= + +# Windows Powershell +helm install rancher rancher-latest/rancher ` + --namespace cattle-system ` + --set hostname=.sslip.io ` + --set replicas=1 ` + --set bootstrapPassword= +``` + +现在，如果你在 Web 浏览器中导航到 `.sslip.io`，你应该会看到 Rancher UI。 + +为了简化说明，我们使用了一个假域名和自签名证书来进行安装。因此，你可能需要在 Web 浏览器中添加一个安全例外来查看 Rancher UI。请注意，对于生产安装，你需要具有负载均衡器、真实域名和真实证书的高可用性设置。 + +这些说明还省略了完整的安装要求和其他安装选项。如果你对这些步骤有任何疑问，请参阅完整的 [Helm CLI 安装文档](../../installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/install-upgrade-on-a-kubernetes-cluster.md)。 + +要使用新的 Rancher Server 来启动新的 Kubernetes 集群，你可能需要在 Rancher 中设置云凭证。有关更多信息，请参阅[使用 Rancher 启动 Kubernetes 集群](../../../how-to-guides/new-user-guides/launch-kubernetes-with-rancher/launch-kubernetes-with-rancher.md)。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/quick-start-guides/deploy-rancher-manager/hetzner-cloud.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/quick-start-guides/deploy-rancher-manager/hetzner-cloud.md new file mode 100644 index 00000000000..95404b7cbe4 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/quick-start-guides/deploy-rancher-manager/hetzner-cloud.md @@ -0,0 +1,76 @@ +--- +title: Rancher Hetzner Cloud 快速入门指南 +description: 阅读此分步 Rancher Hetzner Cloud 指南，以快速部署带有单节点下游 Kubernetes 集群的 Rancher Server。 +--- + +你可以参考以下步骤，在 Hetzner Cloud 的单节点 K3s Kubernetes 集群中快速部署 Rancher Server，并附加一个单节点下游 Kubernetes 集群。 + +:::caution + +本章节中提供的指南，旨在帮助你快速启动一个用于 Rancher 的沙盒，以评估 Rancher 是否能满足你的使用需求。快速入门指南不适用于生产环境。如果你需要获取生产环境的操作指导，请参见[安装](../../installation-and-upgrade/installation-and-upgrade.md)。 + +::: + +## 先决条件 + +:::caution + +部署到 Hetzner Cloud 会产生费用。 + +::: + +- [Hetzner Cloud 账号](https://www.hetzner.com)：用于运行服务器和集群。 +- [Hetzner API 访问密钥](https://docs.hetzner.cloud/#getting-started)：如果你没有的话，请参考说明创建一个。 +- [Terraform](https://developer.hashicorp.com/terraform/install)：用于在 Hetzner 中配置服务器和集群。 + + +## 开始使用 + +1. 使用命令行工具，执行 `git clone https://github.com/rancher/quickstart` 把 [Rancher Quickstart](https://github.com/rancher/quickstart) 克隆到本地。 + +2. 执行 `cd quickstart/rancher/hcloud` 命令，进入包含 Terraform 文件的 Hetzner 文件夹。 + +3. 把 `terraform.tfvars.example` 文件重命名为 `terraform.tfvars`。 + +4. 编辑 `terraform.tfvars` 文件，并替换以下变量： + - `hcloud_token` - 替换为 Hetzner API 访问密钥。 + - `rancher_server_admin_password` - 替换为创建 Rancher Server 的 admin 账号的密码（最少 12 字符） + +5. **可选**：修改 `terraform.tfvars` 中的可选参数。 + 参见 [Quickstart Readme](https://github.com/rancher/quickstart) 以及 [Hetzner Quickstart Readme](https://github.com/rancher/quickstart/tree/master/rancher/hcloud) 了解更多信息。 + 建议包括： + + - `prefix` - 所有创建资源的前缀 + - `instance_type` - 实例类型，至少需要是 `cx21`。 + - `hcloud_location`- Hetzner Cloud 位置。选择最近的位置，而不是使用默认位置（`fsn1`）。 + +6. 执行 `terraform init`。 + +7. 执行 `terraform apply --auto-approve` 以初始化环境。然后，等待命令行工具返回以下信息： + + ``` + Apply complete! Resources: 15 added, 0 changed, 0 destroyed. + + Outputs: + + rancher_node_ip = xx.xx.xx.xx + rancher_server_url = https://rancher.xx.xx.xx.xx.sslip.io + workload_node_ip = yy.yy.yy.yy + ``` + +8. 将以上输出中的 `rancher_server_url` 粘贴到浏览器中。在登录页面中登录（默认用户名为 `admin`，密码为在 `rancher_server_admin_password` 中设置的密码）。 +9. 使用 `quickstart/rancher/hcloud` 中生成的 `id_rsa` 密钥 SSH 到 Rancher Server。 + +#### 结果 + +两个 Kubernetes 集群已部署到你的 Hetzner 账户中，一个运行 Rancher Server，另一个为实验部署做好准备。请注意，虽然这种设置是探索 Rancher 功能的好方法，但在生产环境中，应遵循我们的高可用设置指南。用于虚拟机的 SSH 密钥是自动生成的，存储在模块目录中。 + +### 后续操作 + +使用 Rancher 创建 deployment。详情请参见[创建 Deployment](../deploy-workloads/deploy-workloads.md)。 + +## 销毁环境 + +1. 进入 `quickstart/rancher/hcloud` 文件夹，然后执行 `terraform destroy --auto-approve`。 + +2. 等待命令行界面显示资源已删除的消息。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/quick-start-guides/deploy-rancher-manager/linode.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/quick-start-guides/deploy-rancher-manager/linode.md new file mode 100644 index 00000000000..cf245c9a235 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/quick-start-guides/deploy-rancher-manager/linode.md @@ -0,0 +1,79 @@ +--- +title: Rancher Linode 快速入门指南 +description: 阅读此分步 Rancher Linode 指南，以快速部署带有单节点下游 Kubernetes 集群的 Rancher Server。 +--- + +你可以参考以下步骤，在 Linode 的单节点 K3s Kubernetes 集群中快速部署 Rancher Server，并附加一个单节点下游 Kubernetes 集群。 + +:::caution + +本章节中提供的指南，旨在帮助你快速启动一个用于 Rancher 的沙盒，以评估 Rancher 是否能满足你的使用需求。快速入门指南不适用于生产环境。如果你需要获取生产环境的操作指导，请参见[安装](../../installation-and-upgrade/installation-and-upgrade.md)。 + +::: + +## 先决条件 + +:::caution + +部署到 Linode 会产生费用。 + +::: + +- [Linode 账号](https://www.linode.com/): 用于运行服务器和集群。 +- [Linode 访问密钥](https://techdocs.akamai.com/cloud-computing/docs/manage-personal-access-tokens): 用于权限认证的 Linode 访问密钥。 +- [Terraform](https://developer.hashicorp.com/terraform/install): 用于在 Linode 中配置服务器和集群。 + + +## 开始使用 + +1. 使用命令行工具，执行 `git clone https://github.com/rancher/quickstart` 把 [Rancher Quickstart](https://github.com/rancher/quickstart) 克隆到本地。 + +2. 执行 `cd quickstart/rancher/linode` 命令，进入包含 Terraform 文件的 Linode 文件夹。 + +3. 把 `terraform.tfvars.example` 文件重命名为 `terraform.tfvars`。 + +4. 编辑 `terraform.tfvars` 文件，并替换以下变量： + - `linode_token` - 上面提到的 Linode 访问密钥。 + - `rancher_server_admin_password` - 替换为创建 Rancher Server 的 admin 账号的密码（最少 12 字符） + +5. **可选**：修改 `terraform.tfvars` 中的可选参数。 + 参见 [Quickstart Readme](https://github.com/rancher/quickstart) 以及 [Linode Quickstart Readme](https://github.com/rancher/quickstart/tree/master/rancher/linode) 了解更多信息。 + 建议包括： + - `linode_region` - 创建服务器以及集群的目标 Linode 区域。 + - 默认: `eu-central` + - 完整的区域列表, 请参照[官方的可用区域页面](https://www.linode.com/global-infrastructure/availability/). + - `prefix` - 所有创建资源的前缀 + - `linode_type` - 所有的 Linode 资源使用的类型/计划 + - 默认: `g6-standard-2` + - 完整的计划列表, 请参照[官方的计划类型页面](https://techdocs.akamai.com/cloud-computing/docs/compute-instance-plan-types). + +6. 执行 `terraform init`。 + +7. 执行 `terraform apply --auto-approve` 以初始化环境。然后，等待命令行工具返回以下信息： + + ``` + Apply complete! Resources: 15 added, 0 changed, 0 destroyed. + + Outputs: + + rancher_node_ip = xx.xx.xx.xx + rancher_server_url = https://rancher.xx.xx.xx.xx.sslip.io + workload_node_ip = yy.yy.yy.yy + ``` + +8. 将以上输出中的 `rancher_server_url` 粘贴到浏览器中。在登录页面中登录（默认用户名为 `admin`，密码为在 `rancher_server_admin_password` 中设置的密码）。 +9. 使用 `quickstart/rancher/linode` 中生成的 `id_rsa` 密钥 SSH 到 Rancher Server。 + +#### 结果 + +两个 Kubernetes 集群已部署到你的 Linode 账户中，一个运行 Rancher Server，另一个为实验部署做好准备。请注意，虽然这种设置是探索 Rancher 功能的好方法，但在生产环境中，应遵循我们的高可用设置指南。用于虚拟机的 SSH 密钥是自动生成的，存储在模块目录中。 + +### 后续操作 + +使用 Rancher 创建 deployment。详情请参见[创建 Deployment](../deploy-workloads/deploy-workloads.md)。 + +## 销毁环境 + +1. 进入 `quickstart/rancher/linode` 文件夹，然后执行 `terraform destroy --auto-approve`。 + +2. 等待命令行界面显示资源已删除的消息。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/quick-start-guides/deploy-rancher-manager/outscale-qs.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/quick-start-guides/deploy-rancher-manager/outscale-qs.md new file mode 100644 index 00000000000..a1748c8287f --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/quick-start-guides/deploy-rancher-manager/outscale-qs.md @@ -0,0 +1,76 @@ +--- +title: Rancher Outscale 快速入门指南 +description: 阅读此分步 Rancher Outscale 指南，以快速部署带有单节点下游 Kubernetes 集群的 Rancher Server。 +--- + +你可以参考以下步骤，在 Outscale 的单节点 K3s Kubernetes 集群中快速部署 Rancher Server，并附加一个单节点下游 Kubernetes 集群。 + +:::note + +本章节中提供的指南，旨在帮助你快速启动一个用于 Rancher 的沙盒，以评估 Rancher 是否能满足你的使用需求。快速入门指南不适用于生产环境。如果你需要获取生产环境的操作指导，请参见[安装](../../installation-and-upgrade/installation-and-upgrade.md)。 + +::: + +## 先决条件 + +:::caution + +部署到 Outscale 会产生费用。 + +::: + +- [Outscale 账号](https://en.outscale.com/)：用于运行服务器和集群。 +- [Outscale 访问密钥](https://docs.outscale.com/en/userguide/About-Access-Keys.html)：如果你没有的话，请按照说明创建一个 Outscale 访问密钥。 +- [Terraform](https://developer.hashicorp.com/terraform/install)：用于在 Outscale 中配置服务器和集群。 + + +## 开始使用 + +1. 使用命令行工具，执行 `git clone https://github.com/rancher/quickstart` 把 [Rancher Quickstart](https://github.com/rancher/quickstart) 克隆到本地。 + +2. 执行 `cd quickstart/rancher/outscale` 命令，进入包含 Terraform 文件的 Outscale 文件夹。 + +3. 把 `terraform.tfvars.example` 文件重命名为 `terraform.tfvars`。 + +4. 编辑 `terraform.tfvars` 文件，并替换以下变量： + - `access_key_id` - 替换为 Outscale 访问密钥 + - `secret_key_id` - 替换为 Outscale 密文密钥 + - `rancher_server_admin_password` - 替换为创建 Rancher Server 的 admin 账号的密码（最少 12 字符） + +5. **可选**：修改 `terraform.tfvars` 中的可选参数。 + 参见 [Quickstart Readme](https://github.com/rancher/quickstart) 以及 [Outscale Quickstart Readme](https://github.com/rancher/quickstart/tree/master/rancher/outscale) 了解更多信息。 + 建议包括： + - `region` - Outscale 区域。Outscale 的默认区域不一定是距离你最近的区域。建议修改为距离你最近的区域（`eu-west-2`）。 + - `prefix` - 所有创建资源的前缀 + - `instance_type` - 实例类型，至少需要是 `tinav3.c2r4p3`。 + +6. 执行 `terraform init`。 + +7. 执行 `terraform apply --auto-approve` 以初始化环境。然后，等待命令行工具返回以下信息： + + ``` + Apply complete! Resources: 21 added, 0 changed, 0 destroyed. + + Outputs: + + rancher_node_ip = xx.xx.xx.xx + rancher_server_url = https://rancher.xx.xx.xx.xx.sslip.io + workload_node_ip = yy.yy.yy.yy + ``` + +8. 将以上输出中的 `rancher_server_url` 粘贴到浏览器中。在登录页面中登录（默认用户名为 `admin`，密码为在 `rancher_server_admin_password` 中设置的密码）。 +9. 使用 `quickstart/rancher/outscale` 中生成的 `id_rsa` 密钥 SSH 到 Rancher Server。 + +#### 结果 + +两个 Kubernetes 集群已部署到你的 Outscale 账户中，一个运行 Rancher Server，另一个为实验部署做好准备。请注意，虽然这种设置是探索 Rancher 功能的好方法，但在生产环境中，应遵循我们的高可用设置指南。用于虚拟机的 SSH 密钥是自动生成的，存储在模块目录中。 + +### 后续操作 + +使用 Rancher 创建 deployment。详情请参见[创建 Deployment](../deploy-workloads/deploy-workloads.md)。 + +## 销毁环境 + +1. 进入 `quickstart/rancher/outscale` 文件夹，然后执行 `terraform destroy --auto-approve`。 + +2. 等待命令行界面显示资源已删除的消息。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/quick-start-guides/deploy-rancher-manager/prime.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/quick-start-guides/deploy-rancher-manager/prime.md new file mode 100644 index 00000000000..8ffbc4fab65 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/quick-start-guides/deploy-rancher-manager/prime.md @@ -0,0 +1,9 @@ +--- +title: Rancher Prime +--- + +Rancher 在 v2.7 中引入了 Rancher Prime，这是 Rancher 企业级产品的进化。Rancher Prime 是基于相同源代码构建的商业化、企业级的新版本。因此，Rancher 的产品将继续保持 100% 开源，并通过安全、延长生命周期、访问重点架构和 Kubernetes 公告体现额外价值。Rancher Prime 还将提供选项，让用户获得创新 Rancher 项目的生产支持。使用 Rancher Prime，安装 asset 会托管在由 Rancher 持有和管理的可信镜像仓库中。 + +要开始使用 Rancher Prime，请[转到此页面](https://www.rancher.com/quick-start)并填写表格。 + +At a minimum, users are expected to have a working knowledge of Kubernetes and peripheral functions such as Permissions, Roles and RBAC. diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/quick-start-guides/deploy-rancher-manager/vagrant.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/quick-start-guides/deploy-rancher-manager/vagrant.md new file mode 100644 index 00000000000..bf5641cb345 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/quick-start-guides/deploy-rancher-manager/vagrant.md @@ -0,0 +1,52 @@ +--- +title: Vagrant 快速入门 +--- + +你可以参考以下步骤快速部署 Rancher Server，并附加一个单节点集群。 + +:::caution + +本章节中提供的指南，旨在帮助你快速启动一个用于 Rancher 的沙盒，以评估 Rancher 是否能满足你的使用需求。快速入门指南不适用于生产环境。如果你需要获取生产环境的操作指导，请参见[安装](../../installation-and-upgrade/installation-and-upgrade.md)。 + +::: + +## 先决条件 + +- [Vagrant](https://developer.hashicorp.com/vagrant)：Vagrant 是必需的，用于根据 Vagrantfile 配置主机。 +- [Virtualbox](https://www.virtualbox.org)：需要把 Vagrant 配置的虚拟机配置到 VirtualBox。 +- 至少 4GB 的可用内存。 + +::: 注意 + +Vagrant 需要使用插件来创建 VirtualBox 虚拟机。请执行以下命令进行安装： +- `vagrant plugin install vagrant-vboxmanage` +- `vagrant plugin install vagrant-vbguest` + +::: + +## 开始使用 + +1. 使用命令行工具，执行 `git clone https://github.com/rancher/quickstart` 把 [Rancher Quickstart](https://github.com/rancher/quickstart) 克隆到本地。 + +2. 执行 `cd quickstart/rancher/vagrant` 命令，进入包含 Vagrantfile 文件的文件夹。 + +3. **可选**：编辑 `config.yaml` 文件： + + - 根据需要更改节点数和内存分配（`node.count`, `node.cpus`, `node.memory`） + - 更改 `admin` 的密码以登录 Rancher。(`admin_password`) + +4. 执行 `vagrant up --provider=virtualbox` 以初始化环境。 + +5. 配置完成后，在浏览器中打开 `https://192.168.56.101`。默认的用户名和密码是 `admin/adminPassword`。 + +**结果**：Rancher Server 和你的 Kubernetes 集群已安装在 VirtualBox 上。 + +### 后续操作 + +使用 Rancher 创建 deployment。详情请参见[创建 Deployment](../deploy-workloads/deploy-workloads.md)。 + +## 销毁环境 + +1. 进入 `quickstart/rancher/vagrant` 文件夹，然后执行 `vagrant destroy -f`。 + +2. 等待所有资源已删除的确认消息。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/quick-start-guides/deploy-workloads/deploy-workloads.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/quick-start-guides/deploy-workloads/deploy-workloads.md new file mode 100644 index 00000000000..b0aa55e4fb4 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/quick-start-guides/deploy-workloads/deploy-workloads.md @@ -0,0 +1,12 @@ +--- +title: 部署工作负载 +--- + + + + + +这些指南指导你完成一个应用的部署，包括如何将应用暴露在集群之外使用。 + +- [部署带有 Ingress 的工作负载](workload-ingress.md) +- [部署带有 NodePort 的工作负载](nodeports.md) diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/quick-start-guides/deploy-workloads/nodeports.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/quick-start-guides/deploy-workloads/nodeports.md new file mode 100644 index 00000000000..1023f0da487 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/quick-start-guides/deploy-workloads/nodeports.md @@ -0,0 +1,138 @@ +--- +title: 部署带有 NodePort 的工作负载 +--- + +## 先决条件 + +你已有一个正在运行的集群，且该集群中有至少一个节点。 + +## 1. 部署工作负载 + +你可以开始创建你的第一个 Kubernetes [工作负载](https://kubernetes.io/docs/concepts/workloads/)。工作负载是一个对象，其中包含 pod 以及部署应用所需的其他文件和信息。 + +在本文的工作负载中，你将部署一个 Rancher Hello-World 应用。 + +1. 点击 **☰ > 集群管理**。 +1. 在**集群**页面中，进入需要部署工作负载的集群，然后单击 **Explore**。 +1. 点击**工作负载**。 +1. 单击**创建**。 +1. 为工作负载设置**名称**。 +1. 在**容器镜像**字段中，输入 `rancher/hello-world`。注意区分大小写。 +1. 点击**添加端口**。 +1. 在**服务类型**下拉菜单中，确保选择了 **NodePort**。 + + ![NodePort 下拉菜单（在每个所选节点处）](/img/nodeport-dropdown.png) + +1. 在**发布容器端口**字段中，输入端口`80`。 + + ![发布容器端口，端口 80 已输入](/img/container-port-field.png) + +1. 单击**创建**。 + +**结果**： + +* 工作负载已部署。此过程可能需要几分钟。 +* 当工作负载完成部署后，它的状态会变为 **Active**。你可以从项目的**工作负载**页面查看其状态。 + +
+ +## 2. 查看应用 + +在**工作负载**页面中，点击工作负载下方的链接。如果 deployment 已完成，你的应用会打开。 + +## 注意事项 + +如果使用云虚拟机，你可能无法访问运行容器的端口。这种情况下，你可以使用 `Execute Shell` 在本地主机的 SSH 会话中测试 Nginx。如果可用的话，使用工作负载下方的链接中 `:` 后面的端口号。在本例中，端口号为 `31568`。 + +```html +gettingstarted@rancher:~$ curl http://localhost:31568 + + + + Rancher + + + + + +

Hello world!

+

My hostname is hello-world-66b4b9d88b-78bhx

+
+

k8s services found 2

+ + INGRESS_D1E1A394F61C108633C4BD37AEDDE757 tcp://10.43.203.31:80
+ + KUBERNETES tcp://10.43.0.1:443
+ +
+
+ + +
+ + +
+ + + +gettingstarted@rancher:~$ + +``` + +## 已完成！ + +恭喜！你已成功通过 NodePort 部署工作负载。 + +### 后续操作 + +使用完沙盒后，你需要清理 Rancher Server 和集群。详情请参见： + +- [Amazon AWS：销毁环境](../deploy-rancher-manager/aws.md#销毁环境) +- [DigitalOcean：销毁环境](../deploy-rancher-manager/digitalocean.md#销毁环境) +- [Vagrant：销毁环境](../deploy-rancher-manager/vagrant.md#销毁环境) diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/quick-start-guides/deploy-workloads/workload-ingress.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/quick-start-guides/deploy-workloads/workload-ingress.md new file mode 100644 index 00000000000..3beeb02b815 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/quick-start-guides/deploy-workloads/workload-ingress.md @@ -0,0 +1,72 @@ +--- +title: 部署带有 Ingress 的工作负载 +--- + +## 先决条件 + +你已有一个正在运行的集群，且该集群中有至少一个节点。 + +## 1. 部署工作负载 + +你可以开始创建你的第一个 Kubernetes [工作负载](https://kubernetes.io/docs/concepts/workloads/)。工作负载是一个对象，其中包含 pod 以及部署应用所需的其他文件和信息。 + +在本文的工作负载中，你将部署一个 Rancher Hello-World 应用。 + +1. 点击 **☰ > 集群管理**。 +1. 选择你创建的集群，并点击 **Explore**。 +1. 点击**工作负载**。 +1. 单击**创建**。 +1. 点击 **Deployment**。 +1. 为工作负载设置**名称**。 +1. 在**容器镜像**字段中，输入 `rancher/hello-world`。注意区分大小写。 +1. 在 `Service Type` 点击 **Add Port** 和 `Cluster IP`，并在 **Private Container Port** 字段中输入`80`。你可以将 `Name` 留空或指定名称。通过添加端口，你可以访问集群内外的应用。有关详细信息，请参阅 [Service](../../../how-to-guides/new-user-guides/kubernetes-resources-setup/workloads-and-pods/workloads-and-pods.md#services)。 +1. 单击**创建**。 + +**结果**： + +* 工作负载已部署。此过程可能需要几分钟。 +* 当工作负载完成部署后，它的状态会变为 **Active**。你可以从项目的**工作负载**页面查看其状态。 + +## 2. 通过 Ingress 暴露应用 + +现在应用已启动并运行，你需要暴露应用以让其他服务连接到它。 + +1. 点击 **☰ > 集群管理**。 +1. 选择你创建的集群，并点击 **Explore**。 + +1. 点击**服务发现 > Ingresses**。 + +1. 点击**创建**。 + +1. 在选择**命名空间**时，你需要选择在创建 deployment 时使用的命名空间。否则，在步骤8中选择**目标服务**时，你的 deployment 会不可用。 + +1. 输入**名称**，例如 **hello**。 + +1. 指定**路径**，例如 `/hello`。 + +1. 在**目标服务**字段的下拉菜单中，选择你为服务设置的名称。 + +1. 在**端口**字段中的下拉菜单中，选择 `80`。 + +1. 点击右下角的**创建**。 + +**结果**：应用分配到了一个 `sslip.io` 地址并暴露。这可能需要一两分钟。 + + +## 查看应用 + +在 **Deployments** 页面中，找到你 deployment 的 **endpoint** 列，然后单击一个 endpoint。可用的 endpoint 取决于你添加到 deployment 中的端口配置。如果你看不到随机分配端口的 endpoint，请将你在创建 Ingress 时指定的路径尾附到 IP 地址上。例如，如果你的 endpoint 是 `xxx.xxx.xxx.xxx` 或 `https://xxx.xxx.xxx.xxx`，把它修改为 `xxx.xxx.xxx.xxx/hello` 或 `https://xxx.xxx.xxx.xxx/hello`。 + +应用将在另一个窗口中打开。 + +### 已完成！ + +恭喜！你已成功通过 Ingress 部署工作负载。 + +### 后续操作 + +使用完沙盒后，你需要清理 Rancher Server 和集群。详情请参见： + +- [Amazon AWS：销毁环境](../deploy-rancher-manager/aws.md#销毁环境) +- [DigitalOcean：销毁环境](../deploy-rancher-manager/digitalocean.md#销毁环境) +- [Vagrant：销毁环境](../deploy-rancher-manager/vagrant.md#销毁环境) diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/quick-start-guides/quick-start-guides.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/quick-start-guides/quick-start-guides.md new file mode 100644 index 00000000000..e3e750dc9b4 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/getting-started/quick-start-guides/quick-start-guides.md @@ -0,0 +1,17 @@ +--- +title: Rancher 部署快速入门指南 +--- + +:::caution + +本章节中提供的指南，旨在帮助你快速启动一个用于 Rancher 的沙盒，以评估 Rancher 是否能满足你的使用需求。快速入门指南不适用于生产环境。如果你需要获取生产环境的操作指导，请参见[安装](../installation-and-upgrade/installation-and-upgrade.md)。 + +::: + +你可以阅读本章节，以快速开始部署和测试 Rancher 2.x。本章节包含 Rancher 的简单设置和一些常见用例的说明。未来，我们会在本章节中添加更多内容。 + +我们提供以下快速入门指南： + +- [部署 Rancher Server](deploy-rancher-manager/deploy-rancher-manager.md)：使用最方便的方式运行 Rancher。 + +- [部署工作负载](deploy-workloads/deploy-workloads.md)：部署一个简单的[工作负载](https://kubernetes.io/docs/concepts/workloads/)并公暴露工作负载，以从集群外部访问工作负载。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/advanced-user-guides/advanced-user-guides.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/advanced-user-guides/advanced-user-guides.md new file mode 100644 index 00000000000..ef7e395ad3c --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/advanced-user-guides/advanced-user-guides.md @@ -0,0 +1,11 @@ +--- +title: 高级用户指南 +--- + + + + + +高级用户指南是“问题导向”的文档，用户可以从中学习如何解决问题。高级用户指南与新用户指南的主要区别在于，高级用户指南面向更有经验或更高级的用户，这些用户对文档有更多的技术需求，而且已经了解 Rancher 及其功能。他们知道自己需要做什么，只是需要额外的指导来完成更复杂的任务。 + +应该注意的是，新用户指南和高级用户指南都没有提供详细的解释或讨论（这些文档不包括在本部分）。操作指南侧重于引导用户通过可重复、有效的步骤来学习新技能、掌握某些操作或解决某些问题。 \ No newline at end of file diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/advanced-user-guides/cis-scan-guides/cis-scan-guides.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/advanced-user-guides/cis-scan-guides/cis-scan-guides.md new file mode 100644 index 00000000000..ff6b6200e19 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/advanced-user-guides/cis-scan-guides/cis-scan-guides.md @@ -0,0 +1,17 @@ +--- +title: CIS 扫描指南 +--- + + + + + +- [安装 Rancher CIS Benchmark](install-rancher-cis-benchmark.md) +- [卸载 Rancher CIS Benchmark](uninstall-rancher-cis-benchmark.md) +- [运行扫描](run-a-scan.md) +- [定时运行扫描](run-a-scan-periodically-on-a-schedule.md) +- [跳过测试](skip-tests.md) +- [查看报告](view-reports.md) +- [为 Rancher CIS Benchmark 启用告警](enable-alerting-for-rancher-cis-benchmark.md) +- [为定时扫描配置告警](configure-alerts-for-periodic-scan-on-a-schedule.md) +- [为集群扫描创建自定义 Benchmark 版本](create-a-custom-benchmark-version-to-run.md) \ No newline at end of file diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/advanced-user-guides/cis-scan-guides/configure-alerts-for-periodic-scan-on-a-schedule.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/advanced-user-guides/cis-scan-guides/configure-alerts-for-periodic-scan-on-a-schedule.md new file mode 100644 index 00000000000..643a7122e37 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/advanced-user-guides/cis-scan-guides/configure-alerts-for-periodic-scan-on-a-schedule.md @@ -0,0 +1,40 @@ +--- +title: 为定时扫描配置告警 +--- + +你可以定时运行 ClusterScan。 + +你还可以为定时扫描指定是否在扫描完成时发出告警。 + +只有定时运行的扫描才支持告警。 + +CIS Benchmark 应用支持两种类型的告警： + +- 扫描完成告警：此告警在扫描运行完成时发出。告警包括详细信息，包括 ClusterScan 的名称和 ClusterScanProfile 的名称。 +- 扫描失败告警：如果扫描中有一些测试失败或扫描处于 `Fail` 状态，则会发出此告警。 + +:::note 先决条件： + +为 `rancher-cis-benchmark` 启用告警之前，确保安装了 `rancher-monitoring` 应用并配置了接收器（Receiver）和路由（Route）。详情请参见[本章节](../../../reference-guides/monitoring-v2-configuration/receivers.md)。 + +在为 `rancher-cis-benchmark` 告警配置路由时，你可以使用键值对 `job:rancher-cis-scan` 来指定匹配。详情请查看[路由配置示例](../../../reference-guides/monitoring-v2-configuration/receivers.md#cis-扫描告警的示例路由配置)。 + +::: + +要为定时运行的扫描配置告警： + +1. 请在 `rancher-cis-benchmark` 应用程序上启用告警。详情请参见[本页](../../../how-to-guides/advanced-user-guides/cis-scan-guides/enable-alerting-for-rancher-cis-benchmark.md)。 +1. 在左上角，单击 **☰ > 集群管理**。 +1. 在**集群**页面上，转到要运行 CIS 扫描的集群，然后单击 **Explore**。 +1. 点击 **CIS Benchmark > 扫描**。 +1. 单击**创建**。 +1. 选择集群扫描配置文件。该配置文件确定要使用哪个 CIS Benchmark 版本以及要执行哪些测试。如果你选择 Default 配置文件，则 CIS Operator 将选择适用于它所在的 Kubernetes 集群类型的配置文件。 +1. 选择**定时运行扫描**的选项。 +1. 在**调度**字段中输入有效的 [Cron 表达式](https://en.wikipedia.org/wiki/Cron#CRON_expression)。 +1. 选中**告警**下告警类型旁边的框。 +1. （可选）选择一个**保留计数**，表示为这个定时扫描维护的报告数量。默认情况下，此计数为 3。超过此保留限制时，旧报告将被删除。 +1. 单击**创建**。 + +**结果**：扫描运行，并根据设置的 cron 表达式重新调度。如果在 `rancher-monitoring` 应用下配置了路由和接收器，则会在扫描完成时发出告警。 + +每次运行扫描都会生成一份带有扫描结果的报告。如需查看最新的结果，请单击显示的扫描名称。 \ No newline at end of file diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/advanced-user-guides/cis-scan-guides/create-a-custom-benchmark-version-to-run.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/advanced-user-guides/cis-scan-guides/create-a-custom-benchmark-version-to-run.md new file mode 100644 index 00000000000..fe8477f7b55 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/advanced-user-guides/cis-scan-guides/create-a-custom-benchmark-version-to-run.md @@ -0,0 +1,9 @@ +--- +title: 为集群扫描创建自定义 Benchmark 版本 +--- + +某些 Kubernetes 集群可能需要自定义配置 Benchmark 测试。例如，Kubernetes 配置文件或证书的路径可能与上游 CIS Benchmark 的标准位置不同。 + +现在，你可以使用 `rancher-cis-benchmark` 应用来创建自定义 Benchmark 版本，从而运行集群扫描。 + +有关详细信息，请参阅[此页面](../../../integrations-in-rancher/cis-scans/custom-benchmark.md)。 \ No newline at end of file diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/advanced-user-guides/cis-scan-guides/enable-alerting-for-rancher-cis-benchmark.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/advanced-user-guides/cis-scan-guides/enable-alerting-for-rancher-cis-benchmark.md new file mode 100644 index 00000000000..55c34dcdf5c --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/advanced-user-guides/cis-scan-guides/enable-alerting-for-rancher-cis-benchmark.md @@ -0,0 +1,20 @@ +--- +title: 为 Rancher CIS Benchmark 启用告警 +--- + +你可以配置告警，从而将告警发送给定时运行的扫描。 + +:::note 先决条件： + +为 `rancher-cis-benchmark` 启用告警之前，确保安装了 `rancher-monitoring` 应用并配置了接收器（Receiver）和路由（Route）。详情请参见[本章节](../../../reference-guides/monitoring-v2-configuration/receivers.md)。 + +在为 `rancher-cis-benchmark` 告警配置路由时，你可以使用键值对 `job:rancher-cis-scan` 来指定匹配。详情请查看[路由配置示例](../../../reference-guides/monitoring-v2-configuration/receivers.md#cis-扫描告警的示例路由配置)。 + +::: + +在安装或升级 `rancher-cis-benchmark` Helm Chart 时，在 `values.yaml` 中将以下标志设置为 `true`： + +```yaml +alerts: + enabled: true +``` diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/advanced-user-guides/cis-scan-guides/install-rancher-cis-benchmark.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/advanced-user-guides/cis-scan-guides/install-rancher-cis-benchmark.md new file mode 100644 index 00000000000..fee5bb8b64c --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/advanced-user-guides/cis-scan-guides/install-rancher-cis-benchmark.md @@ -0,0 +1,11 @@ +--- +title: 安装 Rancher CIS Benchmark +--- + +1. 在左上角，单击 **☰ > 集群管理**。 +1. 在**集群**页面上，转到要安装 CIS Benchmark 的集群，然后单击 **Explore**。 +1. 在左侧导航栏中，单击 **Apps > Charts**。 +1. 单击 **CIS Benchmark**。 +1. 单击**安装**。 + +**结果**：CIS 扫描应用已经部署在 Kubernetes 集群上。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/advanced-user-guides/cis-scan-guides/run-a-scan-periodically-on-a-schedule.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/advanced-user-guides/cis-scan-guides/run-a-scan-periodically-on-a-schedule.md new file mode 100644 index 00000000000..d43567fbb25 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/advanced-user-guides/cis-scan-guides/run-a-scan-periodically-on-a-schedule.md @@ -0,0 +1,20 @@ +--- +title: 定时运行扫描 +--- + +要定时运行 ClusterScan： + +1. 在左上角，单击 **☰ > 集群管理**。 +1. 在**集群**页面上，转到要运行 CIS 扫描的集群，然后单击 **Explore**。 +1. 点击 **CIS Benchmark > 扫描**。 +1. 选择集群扫描配置文件。该配置文件确定要使用哪个 CIS Benchmark 版本以及要执行哪些测试。如果你选择 Default 配置文件，则 CIS Operator 将选择适用于它所在的 Kubernetes 集群类型的配置文件。 +1. 选择**定时运行扫描**的选项。 +1. 将一个有效的 Cron 表达式填写到**调度**字段。 +1. 选择一个**保留计数**，表示为这个定时扫描维护的报告数量。默认情况下，此计数为 3。超过此保留限制时，旧报告将被删除。 +1. 单击**创建**。 + +**结果**：扫描运行，并根据设置的 cron 表达式重新调度。**下一次扫描**的值表示下次运行此扫描的时间。 + +每次运行扫描都会生成一份带有扫描结果的报告。如需查看最新的结果，请单击显示的扫描名称。 + +你还可以在扫描详情页面上的**报告**下拉菜单中查看之前的报告。 \ No newline at end of file diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/advanced-user-guides/cis-scan-guides/run-a-scan.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/advanced-user-guides/cis-scan-guides/run-a-scan.md new file mode 100644 index 00000000000..e658029233e --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/advanced-user-guides/cis-scan-guides/run-a-scan.md @@ -0,0 +1,22 @@ +--- +title: 运行扫描 +--- + +创建 ClusterScan 自定义资源后，它会在集群上为所选 ClusterScanProfile 启动新的 CIS 扫描。 + +:::note + +请注意，目前一个集群每次只能运行一次 CIS 扫描。如果你创建了多个 ClusterScan 自定义资源，operator 只能一个接一个地运行这些资源。一个扫描完成之前，其余 ClusterScan 自定义资源将处于 “Pending” 状态。 + +::: + +要运行扫描： + +1. 在左上角，单击 **☰ > 集群管理**。 +1. 在**集群**页面上，转到要运行 CIS 扫描的集群，然后单击 **Explore**。 +1. 点击 **CIS Benchmark > 扫描**。 +1. 单击**创建**。 +1. 选择集群扫描配置文件。该配置文件确定要使用哪个 CIS Benchmark 版本以及要执行哪些测试。如果你选择 Default 配置文件，则 CIS Operator 将选择适用于它所在的 Kubernetes 集群类型的配置文件。 +1. 单击**创建**。 + +**结果**：已生成带有扫描结果的报告。如需查看结果，请单击显示的扫描名称。 \ No newline at end of file diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/advanced-user-guides/cis-scan-guides/skip-tests.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/advanced-user-guides/cis-scan-guides/skip-tests.md new file mode 100644 index 00000000000..230bb1c7696 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/advanced-user-guides/cis-scan-guides/skip-tests.md @@ -0,0 +1,34 @@ +--- +title: 跳过测试 +--- + +用户可以在测试配置文件中自定义要跳过的测试，然后 CIS 扫描可以使用该配置文件运行。 + +要跳过测试，你需要创建自定义一个 CIS 扫描配置文件。配置文件包含 CIS 扫描的配置，包括要使用的 Benchmark 测试版本以及要在该 Benchmark 测试中跳过的测试。 + +1. 在左上角，单击 **☰ > 集群管理**。 +1. 在**集群**页面上，转到要运行 CIS 扫描的集群，然后单击 **Explore**。 +1. 单击 **CIS Benchmark > 配置文件**。 +1. 在这里，你可以使用多种方式来创建配置文件。要创建新配置文件，单击**创建**并在 UI 中填写表单。要基于现有配置文件来创建新配置文件，请转到现有配置文件并单击**⋮ 克隆**。如果你在填写表单，请使用测试 ID 添加要跳过的测试，并参考相关的 CIS Benchmark。如果你将新的测试配置文件创建为 YAML，你需要在 `skipTests` 参数中添加要跳过的测试的 ID。你还需要为配置文件命名： + + ```yaml + apiVersion: cis.cattle.io/v1 + kind: ClusterScanProfile + metadata: + annotations: + meta.helm.sh/release-name: clusterscan-operator + meta.helm.sh/release-namespace: cis-operator-system + labels: + app.kubernetes.io/managed-by: Helm + name: "" + spec: + benchmarkVersion: cis-1.5 + skipTests: + - "1.1.20" + - "1.1.21" + ``` +1. 单击**创建**。 + +**结果**：已创建一个新的 CIS 扫描配置文件。 + +使用此配置文件[运行扫描](./run-a-scan.md)时，会跳过定义的跳过测试。跳过的测试将在生成的报告中标记为 `Skip`。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/advanced-user-guides/cis-scan-guides/uninstall-rancher-cis-benchmark.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/advanced-user-guides/cis-scan-guides/uninstall-rancher-cis-benchmark.md new file mode 100644 index 00000000000..83d36169627 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/advanced-user-guides/cis-scan-guides/uninstall-rancher-cis-benchmark.md @@ -0,0 +1,9 @@ +--- +title: 卸载 Rancher CIS Benchmark +--- + +1. 在**集群**仪表板中，单击左侧导航的 **Apps > Installed Apps**。 +1. 前往 `cis-operator-system` 命名空间，并选中 `rancher-cis-benchmark-crd` 和 `rancher-cis-benchmark` 旁边的框。 +1. 单击**删除**并确认**删除**。 + +**结果**：已卸载 `rancher-cis-benchmark` 应用。 \ No newline at end of file diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/advanced-user-guides/cis-scan-guides/view-reports.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/advanced-user-guides/cis-scan-guides/view-reports.md new file mode 100644 index 00000000000..adfcce53799 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/advanced-user-guides/cis-scan-guides/view-reports.md @@ -0,0 +1,12 @@ +--- +title: 查看报告 +--- + +要查看生成的 CIS 扫描报告： + +1. 在左上角，单击 **☰ > 集群管理**。 +1. 在**集群**页面上，转到要运行 CIS 扫描的集群，然后单击 **Explore**。 +1. 点击 **CIS Benchmark > 扫描**。 +1. **扫描**页面将显示生成的报告。要查看详细报告，请转到扫描报告并单击报告名称。 + +你可以从扫描列表或扫描详情页面下载报告。 \ No newline at end of file diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/advanced-user-guides/configure-layer-7-nginx-load-balancer.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/advanced-user-guides/configure-layer-7-nginx-load-balancer.md new file mode 100644 index 00000000000..2e9ab992ebf --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/advanced-user-guides/configure-layer-7-nginx-load-balancer.md @@ -0,0 +1,258 @@ +--- +title: 7 层 NGINX 负载均衡器上的 TLS 终止（Docker 安装） +--- + +如果你的开发或测试环境要求在负载均衡器上终止 TLS/SSL，而不是在 Rancher Server 上，请部署 Rancher 并配置负载均衡器。 + +如果要在基础设施中对 TLS 集中进行终止，请使用 7 层负载均衡器。7 层负载均衡还能让你的负载均衡器基于 HTTP 属性（例如 cookie 等）做出决策，而 4 层负载均衡器则不能。 + +本文中的安装步骤将引导你使用单个容器部署 Rancher，并提供 7 层 NGINX 负载均衡器的示例配置。 + +## 操作系统，Docker，硬件和网络要求 + +请确保你的节点满足常规的[安装要求](../../getting-started/installation-and-upgrade/installation-requirements/installation-requirements.md)。 + +## 安装概要 + + +## 1. 配置 Linux 主机 + +根据我们的[要求](../../getting-started/installation-and-upgrade/installation-requirements/installation-requirements.md)配置一个 Linux 主机来启动 Rancher Server。 + +## 2. 选择一个 SSL 选项并安装 Rancher + +出于安全考虑，使用 Rancher 时请使用 SSL（Secure Sockets Layer）。SSL 保护所有 Rancher 网络通信（如登录和与集群交互）的安全。 + +:::note 你是否需要： + +- 完成离线安装。 +- 记录所有 Rancher API 的事务。 + +继续之前，请参见[高级选项](#高级选项)。 + +::: + +选择以下的选项之一： + +
+ 选项 A：使用你自己的证书 - 自签名 + +如果要使用自签名证书来加密通信，你必须在负载均衡器（后续步骤）和 Rancher 容器上安装证书。运行 Docker 命令部署 Rancher，将 Docker 指向你的证书。 + +:::note 先决条件： + +创建自签名证书。 + +- 证书文件的格式必须是 PEM。 + +::: + +**使用自签名证书安装 Rancher**： + +1. 在运行 Docker 命令部署 Rancher 时，将 Docker 指向你的 CA 证书文件。 + + ``` + docker run -d --restart=unless-stopped \ + -p 80:80 -p 443:443 \ + -v /etc/your_certificate_directory/cacerts.pem:/etc/rancher/ssl/cacerts.pem \ + rancher/rancher:latest + ``` + +
+
+ 选项 B：使用你自己的证书 - 可信 CA 签名的证书 + +如果你的集群面向公众，则最好使用由公认 CA 签署的证书。 + +:::note 先决条件： + +- 证书文件的格式必须是 PEM。 + +::: + +**使用授信 CA 签发的证书安装 Rancher**： + +如果你使用授信 CA 签发的证书，你无需在 Rancher 容器中安装证书。但是，请确保不要生成和存储默认的 CA 证书（你可以通过将 `--no-cacerts` 参数传递给容器来实现）。 + +1. 输入以下命令： + + ``` + docker run -d --restart=unless-stopped \ + -p 80:80 -p 443:443 \ + rancher/rancher:latest --no-cacerts + ``` + +
+ +## 3. 配置负载均衡器 + +在 Rancher 容器前使用负载均衡器时，容器无需从端口 80 或端口 443 重定向端口通信。你可以通过传递 `X-Forwarded-Proto: https` 标头禁用此重定向。 + +负载均衡器或代理必须支持以下内容： + +- **WebSocket** 连接 +- **SPDY** / **HTTP/2** 协议 +- 传递/设置以下标头： + + | 标头 | 值 | 描述 | + |--------|-------|-------------| + | `Host` | 用于访问 Rancher 的主机名。 | 识别客户端所请求的服务器。 | + | `X-Forwarded-Proto` | `https` | 识别客户端连接负载均衡器或代理时所用的协议。

**注意**：如果此标头存在，`rancher/rancher` 不会将 HTTP 重定向到 HTTPS。 | + | `X-Forwarded-Port` | 用于访问 Rancher 的端口。 | 识别客户端连接到负载均衡器或代理时所用的端口。 | + | `X-Forwarded-For` | 客户端 IP 地址 | 识别客户端的原始 IP 地址。 | +### 示例 NGINX 配置 + +此 NGINX 配置已在 NGINX 1.14 上进行了测试。 + +:::note + +此 NGINX 配置只是一个示例，可能不适合你的环境。如需查阅完整文档，请参见 [NGINX 负载均衡 - HTTP 负载均衡](https://docs.nginx.com/nginx/admin-guide/load-balancer/http-load-balancer/)。 + +::: + +- 将 `rancher-server` 替换为运行 Rancher 容器的节点的 IP 或主机名。 +- 将两处的 `FQDN` 均替换为 Rancher 的 DNS 名称。 +- 把 `/certs/fullchain.pem` 和 `/certs/privkey.pem` 分别替换为服务器证书和服务器证书密钥的位置。 + +``` +worker_processes 4; +worker_rlimit_nofile 40000; + +events { + worker_connections 8192; +} + +http { + upstream rancher { + server rancher-server:80; + } + + map $http_upgrade $connection_upgrade { + default Upgrade; + '' close; + } + + server { + listen 443 ssl http2; + server_name FQDN; + ssl_certificate /certs/fullchain.pem; + ssl_certificate_key /certs/privkey.pem; + + location / { + proxy_set_header Host $host; + proxy_set_header X-Forwarded-Proto $scheme; + proxy_set_header X-Forwarded-Port $server_port; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + proxy_pass http://rancher; + proxy_http_version 1.1; + proxy_set_header Upgrade $http_upgrade; + proxy_set_header Connection $connection_upgrade; + # 此项允许执行的 shell 窗口保持开启，最长可达15分钟。不使用此参数的话，默认1分钟后自动关闭。 + proxy_read_timeout 900s; + proxy_buffering off; + } + } + + server { + listen 80; + server_name FQDN; + return 301 https://$server_name$request_uri; + } +} +``` + +
+ +## 后续操作 + +- **推荐**：检查单节点[备份](../../how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/back-up-docker-installed-rancher.md)和[恢复](../../how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/restore-docker-installed-rancher.md)。你可能暂时没有需要备份的数据，但是我们建议你在常规使用 Rancher 后创建备份。 +- 创建 Kubernetes 集群：[配置 Kubernetes 集群](../../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/kubernetes-clusters-in-rancher-setup.md)。 + +## 常见问题和故障排除 + +如果你需要对证书进行故障排除，请参见[此章节](../../getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/certificate-troubleshooting.md)。 + +## 高级选项 + +### API 审计 + +如果你需要记录所有 Rancher API 事务，请将以下标志添加到安装命令中，从而启用 [API 审计](enable-api-audit-log.md)功能。 + + -e AUDIT_LEVEL=1 \ + -e AUDIT_LOG_PATH=/var/log/auditlog/rancher-api-audit.log \ + -e AUDIT_LOG_MAXAGE=20 \ + -e AUDIT_LOG_MAXBACKUP=20 \ + -e AUDIT_LOG_MAXSIZE=100 \ + +### 离线环境 + +如果你访问此页面是为了完成[离线安装](../../getting-started/installation-and-upgrade/other-installation-methods/air-gapped-helm-cli-install/air-gapped-helm-cli-install.md)，则在运行安装命令时，先将你的私有镜像仓库 URL 附加到 Server 标志中。也就是说，在 `rancher/rancher:latest` 前面添加 `` 和私有镜像仓库 URL。 + +**示例**： + + /rancher/rancher:latest + +### 持久化数据 + +Rancher 使用 etcd 作为数据存储。如果 Rancher 是使用 Docker 安装的，Rancher 会使用嵌入式 etcd。持久化数据位于容器的 `/var/lib/rancher` 路径中。 + +你可以将主机卷挂载到该位置，来将数据保留在运行它的主机上： + +``` +docker run -d --restart=unless-stopped \ + -p 80:80 -p 443:443 \ + -v /opt/rancher:/var/lib/rancher \ + --privileged \ + rancher/rancher:latest +``` + +此操作需要 [privileged 访问](../../getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/rancher-on-a-single-node-with-docker.md#rancher-特权访问)。 + +这个 7 层 NGINX 配置已经在 NGINX 1.13（Mainline）和 1.14（Stable）版本上进行了测试。 + +:::note + +此 NGINX 配置只是一个示例，可能不适合你的环境。如果需要查阅完整文档，请参见 [NGINX 负载均衡 - TCP 和 UDP 负载均衡器](https://docs.nginx.com/nginx/admin-guide/load-balancer/tcp-udp-load-balancer/)。 + +::: + +``` +upstream rancher { + server rancher-server:80; +} + +map $http_upgrade $connection_upgrade { + default Upgrade; + '' close; +} + +server { + listen 443 ssl http2; + server_name rancher.yourdomain.com; + ssl_certificate /etc/your_certificate_directory/fullchain.pem; + ssl_certificate_key /etc/your_certificate_directory/privkey.pem; + + location / { + proxy_set_header Host $host; + proxy_set_header X-Forwarded-Proto $scheme; + proxy_set_header X-Forwarded-Port $server_port; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + proxy_pass http://rancher; + proxy_http_version 1.1; + proxy_set_header Upgrade $http_upgrade; + proxy_set_header Connection $connection_upgrade; + # 此项允许执行的 shell 窗口保持开启，最长可达15分钟。不使用此参数的话，默认1分钟后自动关闭。 + proxy_read_timeout 900s; + proxy_buffering off; + } +} + +server { + listen 80; + server_name rancher.yourdomain.com; + return 301 https://$server_name$request_uri; +} +``` + +
+ diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/advanced-user-guides/enable-api-audit-log-in-downstream-clusters.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/advanced-user-guides/enable-api-audit-log-in-downstream-clusters.md new file mode 100644 index 00000000000..483d881b28e --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/advanced-user-guides/enable-api-audit-log-in-downstream-clusters.md @@ -0,0 +1,189 @@ +--- +title: 下游集群开启 API 审计日志 +--- + + + + + +Kubernetes 审计提供了由 Kube-apiserver 执行的与安全相关的、按时间顺序排列的集群审计记录。Kube API 会在请求执行的每个阶段都生成一个事件，然后根据策略进行预处理并保存，审计策略配置了要记录的内容。 + +你可能希望将审计日志配置为遵守互联网安全中心 (CIS) Kubernetes 基准控制的一部分。 + +有关配置的详细信息，请参阅 [Kubernetes 官方文档](https://kubernetes.io/docs/tasks/debug/debug-cluster/audit/)。 + + + + +### 方法1（建议）：设置 `machineGlobalConfig` 字段的 `audit-policy-file` + +你可以在配置文件中设置 `audit-policy-file`，Rancher 会将该文件保存在 Control Plane 节点的 `/var/lib/rancher/rke2/etc/config-files/audit-policy-file` 目录中，并在 RKE2 服务器中配置相应的选项。 + +例子： +```yaml +apiVersion: provisioning.cattle.io/v1 +kind: Cluster +spec: + rkeConfig: + machineGlobalConfig: + audit-policy-file: | + apiVersion: audit.k8s.io/v1 + kind: Policy + rules: + - level: RequestResponse + resources: + - group: "" + resources: + - pods +``` + +### 方法2：直接使用 `machineSelectorFiles` 和 `machineGlobalConfig` 配置 + +:::note + +Rancher v2.7.2 及以上版本提供此功能。 + +::: + +你可以使用 `machineSelectorFiles` 将审计策略文件传递到 Control Plane 节点，并使用 `machineGlobalConfig` 设置 kube-apiserver 的选项。 + +在此之前，你需要创建 [Secret](../new-user-guides/kubernetes-resources-setup/secrets.md) 或 [ConfigMap](../new-user-guides/kubernetes-resources-setup/configmaps.md) 作为审计策略的来源。 + +Secret 或 ConfigMap 必须满足以下要求： + +1. 必须位于 Cluster 对象所在的 `fleet-default` 命名空间中。 +2. 它必须含有 Annotation `rke.cattle.io/object-authorized-for-clusters: ,`，以允许目标集群使用它。 + +:::tip + +Rancher Dashboard 提供了易用的表单页面用于创建 Secret 或 ConfigMap。 + +::: + +例子： + +```yaml +apiVersion: v1 +data: + audit-policy: >- + IyBMb2cgYWxsIHJlcXVlc3RzIGF0IHRoZSBNZXRhZGF0YSBsZXZlbC4KYXBpVmVyc2lvbjogYXVkaXQuazhzLmlvL3YxCmtpbmQ6IFBvbGljeQpydWxlczoKLSBsZXZlbDogTWV0YWRhdGE= +kind: Secret +metadata: + annotations: + rke.cattle.io/object-authorized-for-clusters: cluster1 + name: + namespace: fleet-default +``` + +可以通过编辑集群 YAML 的 `machineSelectorFiles` 和 `machineGlobalConfig` 字段来启用和配置审计日志。 + +例子： + +```yaml +apiVersion: provisioning.cattle.io/v1 +kind: Cluster +spec: + rkeConfig: + machineGlobalConfig: + kube-apiserver-arg: + - audit-policy-file=/dev-audit-policy.yaml + - audit-log-path=/dev-audit.logs + machineSelectorFiles: + - fileSources: + - configMap: + name: '' + secret: + items: + - key: audit-policy + path: /dev-audit-policy.yaml + name: dev-audit-policy + machineLabelSelector: + matchLabels: + rke.cattle.io/control-plane-role: 'true' +``` + +:::tip + +你还可以使用指令 `machineSelectorConfig` 和适当的 `machineLabelSelectors` 来达到相同的效果。 + +::: + +有关集群配置的更多信息，请参阅 [RKE2 集群配置参考](../../reference-guides/cluster-configuration/rancher-server-configuration/rke2-cluster-configuration.md)页面。 + + + + + +:::note + +Rancher v2.7.2 及以上版本提供此功能。 + +::: + +你可以使用 `machineSelectorFiles` 将审计策略文件传递到 Control Plane 节点，并使用 `machineGlobalConfig` 设置 kube-apiserver 的选项。 + +在此之前，你需要创建 [Secret](../new-user-guides/kubernetes-resources-setup/secrets.md) 或 [ConfigMap](../new-user-guides/kubernetes-resources-setup/configmaps.md) 作为审计策略的来源。 + +Secret 或 ConfigMap 必须满足以下要求： + +1. 必须位于 Cluster 对象所在的 `fleet-default` 命名空间中。 +2. 它必须含有 Annotation `rke.cattle.io/object-authorized-for-clusters: ,`，以允许目标集群使用它。 + +:::tip + +Rancher Dashboard 提供了易于使用的表单页面用于创建 [Secret](../new-user-guides/kubernetes-resources-setup/secrets.md) 或 [ConfigMap](../new-user-guides/kubernetes-resources-setup/configmaps.md)。 + +::: + +例子： + +```yaml +apiVersion: v1 +data: + audit-policy: >- + IyBMb2cgYWxsIHJlcXVlc3RzIGF0IHRoZSBNZXRhZGF0YSBsZXZlbC4KYXBpVmVyc2lvbjogYXVkaXQuazhzLmlvL3YxCmtpbmQ6IFBvbGljeQpydWxlczoKLSBsZXZlbDogTWV0YWRhdGE= +kind: Secret +metadata: + annotations: + rke.cattle.io/object-authorized-for-clusters: cluster1 + name: + namespace: fleet-default +``` + +可以通过编辑集群 YAML 的 `machineSelectorFiles` 和 `machineGlobalConfig` 字段来启用和配置审计日志。 + +例子： + +```yaml +apiVersion: provisioning.cattle.io/v1 +kind: Cluster +spec: + rkeConfig: + machineGlobalConfig: + kube-apiserver-arg: + - audit-policy-file=/dev-audit-policy.yaml + - audit-log-path=/dev-audit.logs + machineSelectorFiles: + - fileSources: + - configMap: + name: '' + secret: + items: + - key: audit-policy + path: /dev-audit-policy.yaml + name: dev-audit-policy + machineLabelSelector: + matchLabels: + rke.cattle.io/control-plane-role: 'true' +``` + +:::tip + +你还可以使用指令 `machineSelectorConfig` 和适当的 `machineLabelSelectors` 来达到相同的效果。 + +::: + +有关集群配置的更多信息，请参阅 [K3s 集群配置参考](../../reference-guides/cluster-configuration/rancher-server-configuration/k3s-cluster-configuration.md) 页面。 + + + diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/advanced-user-guides/enable-api-audit-log.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/advanced-user-guides/enable-api-audit-log.md new file mode 100644 index 00000000000..285c70d5617 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/advanced-user-guides/enable-api-audit-log.md @@ -0,0 +1,558 @@ +--- +title: 启用 API 审计日志以记录系统事件 +--- + +你可以启用 API 审计日志来记录各个用户发起的系统事件的顺序。通过查看日志，你可以了解发生了什么事件、事件发生的时间，事件发起人，以及事件影响的集群。启用此功能后，所有 Rancher API 的请求和响应都会写入日志中。 + +API 审计可以在 Rancher 安装或升级期间启用。 + +## 启用 API 审计日志 + +你可以将环境变量传递给 Rancher Server 容器，从而启用和配置审计日志。请参见以下文档，在安装时启用该功能： + +- [Docker 安装](../../reference-guides/single-node-rancher-in-docker/advanced-options.md#api-审计日志) + +- [Kubernetes 安装](../../getting-started/installation-and-upgrade/installation-references/helm-chart-options.md#api-审计日志) + +## API 审计日志选项 + +以下参数定义了审计日志的记录规则，其中包括应该记录什么内容以及包括什么数据： + +| 参数 | 描述 | +| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `AUDIT_LEVEL` | `0` - 禁用审计日志（默认）
`1` - 日志事件元数据
`2` - 日志事件元数据和请求体
`3` - 日志事件元数据，请求体和响应体。请求/响应对的每个日志事务都使用同一个的 `auditID`。
如需了解每个设置记录的日志内容，请参见[审计日志级别](#审核日志级别)。 | +| `AUDIT_LOG_PATH` | Rancher Server API 的日志路径。默认路径：`/var/log/auditlog/rancher-api-audit.log`。你可以将日志目录挂载到主机。

示例：`AUDIT_LOG_PATH=/my/custom/path/`
| +| `AUDIT_LOG_MAXAGE` | 旧审计日志文件可保留的最大天数。默认为 10 天。 | +| `AUDIT_LOG_MAXBACKUP` | 保留的审计日志最大文件个数。默认值为 10。 | +| `AUDIT_LOG_MAXSIZE` | 在审计日志文件被轮换前的最大容量，单位是 MB。默认大小为 100MB。 | + +
+ +### 审核日志级别 + +下表介绍了每个 [`AUDIT_LEVEL`](#api-审计日志选项) 记录的 API 事务： + +| `AUDIT_LEVEL` 设置 | 请求元数据 | 请求体 | 响应元数据 | 响应体 | +| --------------------- | ---------------- | ------------ | ----------------- | ------------- | +| `0` | | | | | +| `1` | ✓ | | | | +| `2` | ✓ | ✓ | | | +| `3` | ✓ | ✓ | ✓ | ✓ | + +## 查看 API 审计日志 + +### Docker 安装 + +与主机系统共享 `AUDIT_LOG_PATH` 目录（默认目录：`/var/log/auditlog`）。日志可以通过标准 CLI 工具进行解析，也可以转发到 Fluentd、Filebeat、Logstash 等日志收集工具。 + +### Kubernetes 安装 + +使用 Helm Chart 安装 Rancher 时启动 API 审计日志，会在 Rancher Pod 中创建一个 `rancher-audit-log` Sidecar 容器。该容器会将日志发送到标准输出 (stdout)。你可以像查看其他容器的日志一样查看 API 审计日志。 + +`rancher-audit-log` 容器位于 `cattle-system` 命名空间中的 `rancher` Pod 中。 + +#### CLI + +```bash +kubectl -n cattle-system logs -f rancher-84d886bdbb-s4s69 rancher-audit-log +``` + +#### 发送审计日志 + +你可以为集群启用 Rancher 的内置日志收集和传送功能，将审计日志和其他服务日志发送到支持的 endpoint。详情请参见 [Rancher 工具 - Logging](../../integrations-in-rancher/logging/logging.md)。 + +## 审计日志示例 + +启用审计日志后，Rancher 会以 JSON 格式记录每个 API 的请求和响应。下文的代码示例展示了如何查看 API 事务。 + +### 元数据日志级别 + +如果你将 `AUDIT_LEVEL` 设置为 `1`，Rancher 只会记录每个 API 请求的元数据标头，而不会记录请求体。标头记录了 API 事务的基本信息，包括 ID、发起人、发起时间等。代码示例如下： + +```json +{ + "auditID": "30022177-9e2e-43d1-b0d0-06ef9d3db183", + "requestURI": "/v3/schemas", + "sourceIPs": ["::1"], + "user": { + "name": "user-f4tt2", + "group": ["system:authenticated"] + }, + "verb": "GET", + "stage": "RequestReceived", + "stageTimestamp": "2018-07-20 10:22:43 +0800" +} +``` + +### 元数据和请求体日志级别 + +如果你将 `AUDIT_LEVEL` 设置为 `2`，Rancher 会记录每个 API 请求的元数据标头和请求体。 + +下面的代码示例描述了一个 API 请求，包括它的元数据标头和正文： + +```json +{ + "auditID": "ef1d249e-bfac-4fd0-a61f-cbdcad53b9bb", + "requestURI": "/v3/project/c-bcz5t:p-fdr4s/workloads/deployment:default:nginx", + "sourceIPs": ["::1"], + "user": { + "name": "user-f4tt2", + "group": ["system:authenticated"] + }, + "verb": "PUT", + "stage": "RequestReceived", + "stageTimestamp": "2018-07-20 10:28:08 +0800", + "requestBody": { + "hostIPC": false, + "hostNetwork": false, + "hostPID": false, + "paused": false, + "annotations": {}, + "baseType": "workload", + "containers": [ + { + "allowPrivilegeEscalation": false, + "image": "nginx", + "imagePullPolicy": "Always", + "initContainer": false, + "name": "nginx", + "ports": [ + { + "containerPort": 80, + "dnsName": "nginx-nodeport", + "kind": "NodePort", + "name": "80tcp01", + "protocol": "TCP", + "sourcePort": 0, + "type": "/v3/project/schemas/containerPort" + } + ], + "privileged": false, + "readOnly": false, + "resources": { + "type": "/v3/project/schemas/resourceRequirements", + "requests": {}, + "limits": {} + }, + "restartCount": 0, + "runAsNonRoot": false, + "stdin": true, + "stdinOnce": false, + "terminationMessagePath": "/dev/termination-log", + "terminationMessagePolicy": "File", + "tty": true, + "type": "/v3/project/schemas/container", + "environmentFrom": [], + "capAdd": [], + "capDrop": [], + "livenessProbe": null, + "volumeMounts": [] + } + ], + "created": "2018-07-18T07:34:16Z", + "createdTS": 1531899256000, + "creatorId": null, + "deploymentConfig": { + "maxSurge": 1, + "maxUnavailable": 0, + "minReadySeconds": 0, + "progressDeadlineSeconds": 600, + "revisionHistoryLimit": 10, + "strategy": "RollingUpdate" + }, + "deploymentStatus": { + "availableReplicas": 1, + "conditions": [ + { + "lastTransitionTime": "2018-07-18T07:34:38Z", + "lastTransitionTimeTS": 1531899278000, + "lastUpdateTime": "2018-07-18T07:34:38Z", + "lastUpdateTimeTS": 1531899278000, + "message": "Deployment has minimum availability.", + "reason": "MinimumReplicasAvailable", + "status": "True", + "type": "Available" + }, + { + "lastTransitionTime": "2018-07-18T07:34:16Z", + "lastTransitionTimeTS": 1531899256000, + "lastUpdateTime": "2018-07-18T07:34:38Z", + "lastUpdateTimeTS": 1531899278000, + "message": "ReplicaSet \"nginx-64d85666f9\" has successfully progressed.", + "reason": "NewReplicaSetAvailable", + "status": "True", + "type": "Progressing" + } + ], + "observedGeneration": 2, + "readyReplicas": 1, + "replicas": 1, + "type": "/v3/project/schemas/deploymentStatus", + "unavailableReplicas": 0, + "updatedReplicas": 1 + }, + "dnsPolicy": "ClusterFirst", + "id": "deployment:default:nginx", + "labels": { + "workload.user.cattle.io/workloadselector": "deployment-default-nginx" + }, + "name": "nginx", + "namespaceId": "default", + "projectId": "c-bcz5t:p-fdr4s", + "publicEndpoints": [ + { + "addresses": ["10.64.3.58"], + "allNodes": true, + "ingressId": null, + "nodeId": null, + "podId": null, + "port": 30917, + "protocol": "TCP", + "serviceId": "default:nginx-nodeport", + "type": "publicEndpoint" + } + ], + "restartPolicy": "Always", + "scale": 1, + "schedulerName": "default-scheduler", + "selector": { + "matchLabels": { + "workload.user.cattle.io/workloadselector": "deployment-default-nginx" + }, + "type": "/v3/project/schemas/labelSelector" + }, + "state": "active", + "terminationGracePeriodSeconds": 30, + "transitioning": "no", + "transitioningMessage": "", + "type": "deployment", + "uuid": "f998037d-8a5c-11e8-a4cf-0245a7ebb0fd", + "workloadAnnotations": { + "deployment.kubernetes.io/revision": "1", + "field.cattle.io/creatorId": "user-f4tt2" + }, + "workloadLabels": { + "workload.user.cattle.io/workloadselector": "deployment-default-nginx" + }, + "scheduling": { + "node": {} + }, + "description": "my description", + "volumes": [] + } +} +``` + +### 元数据、请求体和响应体日志级别 + +如果你将 `AUDIT_LEVEL` 设置为 `3`，Rancher 会记录： + +- 每个 API 请求的元数据标头和请求体。 +- 每个 API 响应的元数据标头和响应体。 + +#### 请求 + +下面的代码示例描述了一个 API 请求，包括它的元数据标头和正文： + +```json +{ + "auditID": "a886fd9f-5d6b-4ae3-9a10-5bff8f3d68af", + "requestURI": "/v3/project/c-bcz5t:p-fdr4s/workloads/deployment:default:nginx", + "sourceIPs": ["::1"], + "user": { + "name": "user-f4tt2", + "group": ["system:authenticated"] + }, + "verb": "PUT", + "stage": "RequestReceived", + "stageTimestamp": "2018-07-20 10:33:06 +0800", + "requestBody": { + "hostIPC": false, + "hostNetwork": false, + "hostPID": false, + "paused": false, + "annotations": {}, + "baseType": "workload", + "containers": [ + { + "allowPrivilegeEscalation": false, + "image": "nginx", + "imagePullPolicy": "Always", + "initContainer": false, + "name": "nginx", + "ports": [ + { + "containerPort": 80, + "dnsName": "nginx-nodeport", + "kind": "NodePort", + "name": "80tcp01", + "protocol": "TCP", + "sourcePort": 0, + "type": "/v3/project/schemas/containerPort" + } + ], + "privileged": false, + "readOnly": false, + "resources": { + "type": "/v3/project/schemas/resourceRequirements", + "requests": {}, + "limits": {} + }, + "restartCount": 0, + "runAsNonRoot": false, + "stdin": true, + "stdinOnce": false, + "terminationMessagePath": "/dev/termination-log", + "terminationMessagePolicy": "File", + "tty": true, + "type": "/v3/project/schemas/container", + "environmentFrom": [], + "capAdd": [], + "capDrop": [], + "livenessProbe": null, + "volumeMounts": [] + } + ], + "created": "2018-07-18T07:34:16Z", + "createdTS": 1531899256000, + "creatorId": null, + "deploymentConfig": { + "maxSurge": 1, + "maxUnavailable": 0, + "minReadySeconds": 0, + "progressDeadlineSeconds": 600, + "revisionHistoryLimit": 10, + "strategy": "RollingUpdate" + }, + "deploymentStatus": { + "availableReplicas": 1, + "conditions": [ + { + "lastTransitionTime": "2018-07-18T07:34:38Z", + "lastTransitionTimeTS": 1531899278000, + "lastUpdateTime": "2018-07-18T07:34:38Z", + "lastUpdateTimeTS": 1531899278000, + "message": "Deployment has minimum availability.", + "reason": "MinimumReplicasAvailable", + "status": "True", + "type": "Available" + }, + { + "lastTransitionTime": "2018-07-18T07:34:16Z", + "lastTransitionTimeTS": 1531899256000, + "lastUpdateTime": "2018-07-18T07:34:38Z", + "lastUpdateTimeTS": 1531899278000, + "message": "ReplicaSet \"nginx-64d85666f9\" has successfully progressed.", + "reason": "NewReplicaSetAvailable", + "status": "True", + "type": "Progressing" + } + ], + "observedGeneration": 2, + "readyReplicas": 1, + "replicas": 1, + "type": "/v3/project/schemas/deploymentStatus", + "unavailableReplicas": 0, + "updatedReplicas": 1 + }, + "dnsPolicy": "ClusterFirst", + "id": "deployment:default:nginx", + "labels": { + "workload.user.cattle.io/workloadselector": "deployment-default-nginx" + }, + "name": "nginx", + "namespaceId": "default", + "projectId": "c-bcz5t:p-fdr4s", + "publicEndpoints": [ + { + "addresses": ["10.64.3.58"], + "allNodes": true, + "ingressId": null, + "nodeId": null, + "podId": null, + "port": 30917, + "protocol": "TCP", + "serviceId": "default:nginx-nodeport", + "type": "publicEndpoint" + } + ], + "restartPolicy": "Always", + "scale": 1, + "schedulerName": "default-scheduler", + "selector": { + "matchLabels": { + "workload.user.cattle.io/workloadselector": "deployment-default-nginx" + }, + "type": "/v3/project/schemas/labelSelector" + }, + "state": "active", + "terminationGracePeriodSeconds": 30, + "transitioning": "no", + "transitioningMessage": "", + "type": "deployment", + "uuid": "f998037d-8a5c-11e8-a4cf-0245a7ebb0fd", + "workloadAnnotations": { + "deployment.kubernetes.io/revision": "1", + "field.cattle.io/creatorId": "user-f4tt2" + }, + "workloadLabels": { + "workload.user.cattle.io/workloadselector": "deployment-default-nginx" + }, + "scheduling": { + "node": {} + }, + "description": "my decript", + "volumes": [] + } +} +``` + +#### 响应 + +下面的代码示例描述了一个 API 响应，包括它的元数据标头和正文： + +```json +{ + "auditID": "a886fd9f-5d6b-4ae3-9a10-5bff8f3d68af", + "responseStatus": "200", + "stage": "ResponseComplete", + "stageTimestamp": "2018-07-20 10:33:06 +0800", + "responseBody": { + "actionLinks": { + "pause": "https://localhost:8443/v3/project/c-bcz5t:p-fdr4s/workloads/deployment:default:nginx?action=pause", + "resume": "https://localhost:8443/v3/project/c-bcz5t:p-fdr4s/workloads/deployment:default:nginx?action=resume", + "rollback": "https://localhost:8443/v3/project/c-bcz5t:p-fdr4s/workloads/deployment:default:nginx?action=rollback" + }, + "annotations": {}, + "baseType": "workload", + "containers": [ + { + "allowPrivilegeEscalation": false, + "image": "nginx", + "imagePullPolicy": "Always", + "initContainer": false, + "name": "nginx", + "ports": [ + { + "containerPort": 80, + "dnsName": "nginx-nodeport", + "kind": "NodePort", + "name": "80tcp01", + "protocol": "TCP", + "sourcePort": 0, + "type": "/v3/project/schemas/containerPort" + } + ], + "privileged": false, + "readOnly": false, + "resources": { + "type": "/v3/project/schemas/resourceRequirements" + }, + "restartCount": 0, + "runAsNonRoot": false, + "stdin": true, + "stdinOnce": false, + "terminationMessagePath": "/dev/termination-log", + "terminationMessagePolicy": "File", + "tty": true, + "type": "/v3/project/schemas/container" + } + ], + "created": "2018-07-18T07:34:16Z", + "createdTS": 1531899256000, + "creatorId": null, + "deploymentConfig": { + "maxSurge": 1, + "maxUnavailable": 0, + "minReadySeconds": 0, + "progressDeadlineSeconds": 600, + "revisionHistoryLimit": 10, + "strategy": "RollingUpdate" + }, + "deploymentStatus": { + "availableReplicas": 1, + "conditions": [ + { + "lastTransitionTime": "2018-07-18T07:34:38Z", + "lastTransitionTimeTS": 1531899278000, + "lastUpdateTime": "2018-07-18T07:34:38Z", + "lastUpdateTimeTS": 1531899278000, + "message": "Deployment has minimum availability.", + "reason": "MinimumReplicasAvailable", + "status": "True", + "type": "Available" + }, + { + "lastTransitionTime": "2018-07-18T07:34:16Z", + "lastTransitionTimeTS": 1531899256000, + "lastUpdateTime": "2018-07-18T07:34:38Z", + "lastUpdateTimeTS": 1531899278000, + "message": "ReplicaSet \"nginx-64d85666f9\" has successfully progressed.", + "reason": "NewReplicaSetAvailable", + "status": "True", + "type": "Progressing" + } + ], + "observedGeneration": 2, + "readyReplicas": 1, + "replicas": 1, + "type": "/v3/project/schemas/deploymentStatus", + "unavailableReplicas": 0, + "updatedReplicas": 1 + }, + "dnsPolicy": "ClusterFirst", + "hostIPC": false, + "hostNetwork": false, + "hostPID": false, + "id": "deployment:default:nginx", + "labels": { + "workload.user.cattle.io/workloadselector": "deployment-default-nginx" + }, + "links": { + "remove": "https://localhost:8443/v3/project/c-bcz5t:p-fdr4s/workloads/deployment:default:nginx", + "revisions": "https://localhost:8443/v3/project/c-bcz5t:p-fdr4s/workloads/deployment:default:nginx/revisions", + "self": "https://localhost:8443/v3/project/c-bcz5t:p-fdr4s/workloads/deployment:default:nginx", + "update": "https://localhost:8443/v3/project/c-bcz5t:p-fdr4s/workloads/deployment:default:nginx", + "yaml": "https://localhost:8443/v3/project/c-bcz5t:p-fdr4s/workloads/deployment:default:nginx/yaml" + }, + "name": "nginx", + "namespaceId": "default", + "paused": false, + "projectId": "c-bcz5t:p-fdr4s", + "publicEndpoints": [ + { + "addresses": ["10.64.3.58"], + "allNodes": true, + "ingressId": null, + "nodeId": null, + "podId": null, + "port": 30917, + "protocol": "TCP", + "serviceId": "default:nginx-nodeport" + } + ], + "restartPolicy": "Always", + "scale": 1, + "schedulerName": "default-scheduler", + "selector": { + "matchLabels": { + "workload.user.cattle.io/workloadselector": "deployment-default-nginx" + }, + "type": "/v3/project/schemas/labelSelector" + }, + "state": "active", + "terminationGracePeriodSeconds": 30, + "transitioning": "no", + "transitioningMessage": "", + "type": "deployment", + "uuid": "f998037d-8a5c-11e8-a4cf-0245a7ebb0fd", + "workloadAnnotations": { + "deployment.kubernetes.io/revision": "1", + "field.cattle.io/creatorId": "user-f4tt2" + }, + "workloadLabels": { + "workload.user.cattle.io/workloadselector": "deployment-default-nginx" + } + } +} +``` diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/advanced-user-guides/enable-experimental-features/continuous-delivery.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/advanced-user-guides/enable-experimental-features/continuous-delivery.md new file mode 100644 index 00000000000..fdc7139d5ef --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/advanced-user-guides/enable-experimental-features/continuous-delivery.md @@ -0,0 +1,13 @@ +--- +title: 持续交付 +--- + +Rancher 中预装的 [Fleet](../../../integrations-in-rancher/fleet/fleet.md) 无法完全禁用。但是，你可以使用 `continuous-delivery` 功能开关来禁用 GitOps 持续交付的 Fleet 功能。 + +如需启用或禁用此功能，请参见[启用实验功能主页](./enable-experimental-features.md)中的说明。 + +| 环境变量键 | 默认值 | 描述 | +---|---|--- +| `continuous-delivery` | `true` | 此开关禁用 Fleet 的 GitOps 持续交付功能。 | + +如果你在 Rancher 2.5.x 中禁用了 Fleet，然后将 Rancher 升级到 v2.6.x，Fleet 将启用。只有 Fleet 的持续交付功能可以被禁用。当 `continuous-delivery` 被禁用时，`gitjob` deployment 不再部署到 Rancher Server 的本地集群中，且 `continuous-delivery` 不会在 Rancher UI 中显示。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/advanced-user-guides/enable-experimental-features/enable-experimental-features.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/advanced-user-guides/enable-experimental-features/enable-experimental-features.md new file mode 100644 index 00000000000..97218077f07 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/advanced-user-guides/enable-experimental-features/enable-experimental-features.md @@ -0,0 +1,125 @@ +--- +title: 启用实验功能 +--- + + + + + +Rancher 包含一些默认关闭的实验功能。在某些情况下，例如当你认为使用[不支持的存储类型](unsupported-storage-drivers.md)的好处大于使用未经测试的功能的风险时，你可能想要启用实验功能。为了让你能够试用这些默认关闭的功能，我们引入了功能开关（feature flag）。 + +实验功能可以通过以下三种方式启用： + +- [使用 CLI](#启动-rancher-时启用功能)：在使用 CLI 安装 Rancher 时，使用功能开关默认启用某个功能。 +- [使用 Rancher UI](#使用-rancher-ui-启用功能)：在**设置**页面启用功能。 +- [使用 Rancher API](#使用-rancher-api-启用功能)：安装 Rancher 后启用功能。 + +每个功能均有以下两个值： + +- 默认值：可以通过在命令行使用标志或环境变量进行配置。 +- 设置值：可以通过 Rancher API 或 UI 进行配置。 + +如果没有设置值，Rancher 会使用默认值。 + +设置值是通过 API 设置的，而默认值是通过命令行设置。因此，如果你使用 API 或 UI 启用或禁用某个功能，命令行中设置的值将被覆盖。 + +如果你安装 Rancher 后使用 Rancher API 将功能开关设置为 true，然后在使用命令升级 Rancher 时将功能开关设置为 false，在这种情况下，虽然默认值会是 false，但是该功能依然会被启用，因为它是通过 API 设置的。如果你随后使用 Rancher API 删除设置值（true）并将它设置为 NULL，则默认值（false）将生效。有关详细信息，请参阅[功能开关页面](../../../getting-started/installation-and-upgrade/installation-references/feature-flags.md)。 + +## 启动 Rancher 时启用功能 + +安装 Rancher 时，使用功能开关启用你所需的功能。通过单节点容器安装 Rancher，和在 Kubernetes 集群上安装 Rancher 对应的命令有所不同。 + +### Kubernetes 安装的情况下启用功能 + +:::note + +通过 Rancher API 设置的值会覆盖命令行传入的值。 + +::: + +使用 Helm Chart 安装 Rancher 时，使用 `--set` 选项。下面的示例通过传递功能开关名称（用逗号分隔）来启用两个功能： + +``` +helm install rancher rancher-latest/rancher \ + --namespace cattle-system \ + --set hostname=rancher.my.org \ + --set 'extraEnv[0].name=CATTLE_FEATURES' + --set 'extraEnv[0].value==true,=true' +``` + +:::note + +如果你安装的是 alpha 版本，Helm 要求你在命令中添加 `--devel` 选项。 + +::: + +### 离线安装的情况下渲染 Helm Chart + +如果你是在离线环境安装 Rancher 的，在使用 Helm 安装 Rancher 之前，你需要添加一个 Helm Chart 仓库并渲染一个 Helm 模板。详情请参见[离线安装文档](../../../getting-started/installation-and-upgrade/other-installation-methods/air-gapped-helm-cli-install/install-rancher-ha.md)。 + +以下是在渲染 Helm 模板时传入功能开关名称的命令示例。下面的示例通过传递功能开关名称（用逗号分隔）来启用两个功能。 + +Helm 命令如下： + +``` +helm install rancher ./rancher-.tgz \ + --namespace cattle-system \ + --set hostname= \ + --set rancherImage=/rancher/rancher \ + --set ingress.tls.source=secret \ + --set systemDefaultRegistry= \ # 设置在 Rancher 中使用的私有镜像仓库 + --set useBundledSystemChart=true # 使用打包的 Rancher System Chart + --set 'extraEnv[0].name=CATTLE_FEATURES' + --set 'extraEnv[0].value==true,=true' +``` + +### Docker 安装的情况下启用功能 + +如果 Rancher 是使用 Docker 安装的，请使用 `--features` 选项。下面的示例通过传递功能开关名称（用逗号分隔）来启用两个功能： + +``` +docker run -d -p 80:80 -p 443:443 \ + --restart=unless-stopped \ + rancher/rancher:rancher-latest \ + --features==true,=true +``` + +## 使用 Rancher UI 启用功能 + +1. 在左上角，单击 **☰ > 全局设置**。 +1. 单击**功能开关**。 +1. 如需启用某个功能，找到该已禁用的功能，并点击**⋮ > 激活**。 + +**结果**：该功能已启用。 + +### 使用 Rancher UI 禁用功能 + +1. 在左上角，单击 **☰ > 全局设置**。 +1. 单击**功能开关**。你将看到实验功能列表。 +1. 如需禁用某个功能，找到该已启用的功能，并点击**⋮ > 停用**。 + +**结果**：该功能已禁用。 + +## 使用 Rancher API 启用功能 + +1. 前往 `/v3/features`。 +1. 在 `data` 中，你会看到一个数组，该数组包含所有能通过功能开关启用的功能。功能的名称在 `id` 字段中。单击要启用的功能的名称。 +1. 在左上角的 **Operations** 下，点击 **Edit**。 +1. 在 **Value** 下拉菜单中，单击 **True**。 +1. 单击 **Show Request**。 +1. 单击 **Send Request**。 +1. 点击 **Close**。 + +**结果**：该功能已启用。 + +### 使用 Rancher API 禁用功能 + +1. 前往 `/v3/features`。 +1. 在 `data` 中，你会看到一个数组，该数组包含所有能通过功能开关启用的功能。功能的名称在 `id` 字段中。单击要启用的功能的名称。 +1. 在左上角的 **Operations** 下，点击 **Edit**。 +1. 在 **Value** 下拉菜单中，单击 **False**。 +1. 单击 **Show Request**。 +1. 单击 **Send Request**。 +1. 点击 **Close**。 + +**结果**：该功能已禁用。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/advanced-user-guides/enable-experimental-features/istio-traffic-management-features.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/advanced-user-guides/enable-experimental-features/istio-traffic-management-features.md new file mode 100644 index 00000000000..8e730c24cb3 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/advanced-user-guides/enable-experimental-features/istio-traffic-management-features.md @@ -0,0 +1,32 @@ +--- +title: UI 管理 Istio 虚拟服务和目标规则 +--- + +此功能可启动一个 UI，用于管理 Istio 的流量，其中包括创建、读取、更新和删除虚拟服务（Virtual Service）和目标规则（Destination Rule）。 + +> **注意**：启用此功能并不会启用 Istio。集群管理员需要[为集群启用 Istio](../istio-setup-guide/istio-setup-guide.md) 才能使用该功能。 + +如需启用或禁用此功能，请参见[启用实验功能主页](./enable-experimental-features.md)中的说明。 + +| 环境变量键 | 默认值 | 状态 | 可用于 | +---|---|---|--- +| `istio-virtual-service-ui` | `false` | 实验功能 | v2.3.0 | +| `istio-virtual-service-ui` | `true` | GA | v2.3.2 | + +## 功能介绍 + +Istio 流量管理功能的主要优势时允许动态请求路由，这对于金丝雀发布，蓝/绿发布或 A/B 测试都非常有用。 + +启用此功能后，一个页面会打开，让你通过 Rancher UI 配置 Istio 的某些流量管理功能。如果不使用此功能，你可以通过 `kubectl` 来使用 Istio 管理流量。 + +此功能会启用两个选项卡，一个用于**虚拟服务**，另一个用于**目标规则**。 + +- **虚拟服务**：拦截并将流量重定向到你的 Kubernetes Service 上。这样，你可以将部分请求流量定向到不同的服务上。你可以使用这些服务来定义一组路由规则，用于主机寻址。详情请参见 [Istio 官方文档](https://istio.io/docs/reference/config/networking/v1alpha3/virtual-service/)。 +- **目标规则**：作为唯一可信来源，表明哪些服务版本可用于接收虚拟服务的流量。你可以使用这些资源来定义策略，这些策略适用于路由发生后用于服务的流量。详情请参见 [Istio 官方文档](https://istio.io/docs/reference/config/networking/v1alpha3/destination-rule)。 + +如需查看选项卡： + +1. 点击 **☰ > 集群管理**。 +1. 转到安装了 Istio 的集群，然后单击 **Explore**。 +1. 在左侧导航栏中，单击 **Istio**。 +1. 你将看到 **Kiali** 和 **Jaeger** 的选项卡。在左侧导航栏中，你可查看和配置**虚拟服务**和**目标规则**。 \ No newline at end of file diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/advanced-user-guides/enable-experimental-features/rancher-on-arm64.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/advanced-user-guides/enable-experimental-features/rancher-on-arm64.md new file mode 100644 index 00000000000..3fc9998f1a6 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/advanced-user-guides/enable-experimental-features/rancher-on-arm64.md @@ -0,0 +1,44 @@ +--- +title: "在 ARM64 上运行 Rancher（实验性）" +--- + +:::caution + +在使用 ARM64 架构的节点上运行 Rancher 目前还处在实验阶段，Rancher 尚未正式支持该功能。因此，我们不建议你在生产环境中使用 ARM64 架构的节点。 + +::: + +如果你的节点使用 ARM64 架构，你可以使用以下选项： + +- 在 ARM64 架构的节点上运行 Rancher + - 此选项仅适用于 Docker 安装。请知悉，以下安装命令取代了 [Docker 安装链接](../../../getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/rancher-on-a-single-node-with-docker.md)中的示例： + + ``` + # 在最后一行 `rancher/rancher:vX.Y.Z` 中，请务必将 "X.Y.Z" 替换为包含 ARM64 版本的发布版本。例如，如果你的匹配版本是 v2.5.8，请在此行填写 `rancher/rancher:v2.5.8`。 + docker run -d --restart=unless-stopped \ + -p 80:80 -p 443:443 \ + --privileged \ + rancher/rancher:vX.Y.Z + ``` + +:::note + +要检查你的发行版本是否与 ARM64 架构兼容，你可以使用以下两种方式找到对应版本的发行说明： + +- 访问 [Rancher 发行版本](https://github.com/rancher/rancher/releases)自行查询。 +- 根据标签和版本号直接找到你的版本。例如，你使用的版本为 2.5.8，你可以访问 [Rancher 发行版本 - 2.5.8](https://github.com/rancher/rancher/releases/tag/v2.5.8)。 + +::: + +- 创建自定义集群并添加使用 ARM64 架构的节点 + - Kubernetes 集群必须为 1.12 或更高版本 + - CNI 网络插件必须是 [Flannel](../../../faq/container-network-interface-providers.md#flannel) +- 导入包含使用 ARM64 架构的节点的集群 + - Kubernetes 集群必须为 1.12 或更高版本 + +Depending on your cluster provisioning refer to [RKE2 cluster configuration options](../../../reference-guides/cluster-configuration/rancher-server-configuration/rke2-cluster-configuration.md) or [K3s cluster configuration options](../../../reference-guides/cluster-configuration/rancher-server-configuration/k3s-cluster-configuration.md) for more information. + +以下是未经测试的功能： + +- Monitoring、告警、Notifiers、流水线和 Logging +- 通过应用商店发布应用 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/advanced-user-guides/enable-experimental-features/unsupported-storage-drivers.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/advanced-user-guides/enable-experimental-features/unsupported-storage-drivers.md new file mode 100644 index 00000000000..7bd9c0cabfb --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/advanced-user-guides/enable-experimental-features/unsupported-storage-drivers.md @@ -0,0 +1,41 @@ +--- +title: 使用非默认支持的存储驱动 +--- + +此功能允许你使用不是默认启用的存储提供商和卷插件。 + +如需启用或禁用此功能，请参见[启用实验功能主页](./enable-experimental-features.md)中的说明。 + +| 环境变量键 | 默认值 | 描述 | +---|---|--- +| `unsupported-storage-drivers` | `false` | 启用非默认启用的存储提供商和卷插件。 | + +## 默认启用的持久卷插件 + +下表描述了默认启用的存储类型对应的持久卷插件。启用此功能开关时，不在此列表中的任何持久卷插件均被视为实验功能，且不受支持： + +| 名称 | 插件 | +--------|---------- +| Amazon EBS Disk | `aws-ebs` | +| AzureFile | `azure-file` | +| AzureDisk | `azure-disk` | +| Google Persistent Disk | `gce-pd` | +| Longhorn | `flex-volume-longhorn` | +| VMware vSphere Volume | `vsphere-volume` | +| 本地 | `local` | +| 网络文件系统 | `nfs` | +| hostPath | `host-path` | + +## 默认启用的 StorageClass + +下表描述了默认启用的 StorageClass 对应的持久卷插件。启用此功能开关时，不在此列表中的任何持久卷插件均被视为实验功能，且不受支持： + +| 名称 | 插件 | +--------|-------- +| Amazon EBS Disk | `aws-ebs` | +| AzureFile | `azure-file` | +| AzureDisk | `azure-disk` | +| Google Persistent Disk | `gce-pd` | +| Longhorn | `flex-volume-longhorn` | +| VMware vSphere Volume | `vsphere-volume` | +| 本地 | `local` | \ No newline at end of file diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/advanced-user-guides/istio-setup-guide/enable-istio-in-cluster.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/advanced-user-guides/istio-setup-guide/enable-istio-in-cluster.md new file mode 100644 index 00000000000..f6428ce27cd --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/advanced-user-guides/istio-setup-guide/enable-istio-in-cluster.md @@ -0,0 +1,28 @@ +--- +title: 1. 在集群中启用 Istio +--- + +:::note 先决条件： + +- 只有分配了 `cluster-admin` [Kubernetes 默认角色](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#user-facing-roles)的用户可以在 Kubernetes 集群中配置和安装 Istio。 +- 要在 RKE2 集群上安装 Istio，则需要执行额外的步骤。有关详细信息，请参阅[本节](../../../integrations-in-rancher/istio/configuration-options/install-istio-on-rke2-cluster.md)。 +- 要在启用了项目网络隔离的集群中安装 Istio，则需要执行额外的步骤。有关详细信息，请参阅[本节](../../../integrations-in-rancher/istio/configuration-options/project-network-isolation.md)。 + +::: + +1. 点击 **☰ > 集群管理**。 +1. 转到要启用 Istio 的位置，然后单击 **Explore**。 +1. 单击 **Apps**。 +1. 单击 **Chart**。 +1. 单击 **Istio**。 +1. 如果你还没有安装 Monitoring 应用，系统会提示你安装 rancher-monitoring。你也可以选择在 Rancher-monitoring 安装上设置选择器或抓取配置选项。 +1. 可选：为 Istio 组件配置成员访问和[资源限制](../../../integrations-in-rancher/istio/cpu-and-memory-allocations.md)。确保你的 Worker 节点上有足够的资源来启用 Istio。 +1. 可选：如果需要，对 values.yaml 进行额外的配置更改。 +1. 可选：通过[覆盖文件](../../../integrations-in-rancher/istio/configuration-options/configuration-options.md#覆盖文件)来添加其他资源或配置。 +1. 单击**安装**。 + +**结果**：已在集群级别安装 Istio。 + +## 其他配置选项 + +有关配置 Istio 的更多信息，请参阅[配置参考](../../../integrations-in-rancher/istio/configuration-options/configuration-options.md)。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/advanced-user-guides/istio-setup-guide/enable-istio-in-namespace.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/advanced-user-guides/istio-setup-guide/enable-istio-in-namespace.md new file mode 100644 index 00000000000..95313cf2328 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/advanced-user-guides/istio-setup-guide/enable-istio-in-namespace.md @@ -0,0 +1,53 @@ +--- +title: 2. 在命名空间中启用 Istio +--- + +你需要在需要由 Istio 跟踪或控制的每个命名空间中手动启用 Istio。在命名空间中启用 Istio 时，Envoy sidecar 代理将自动注入到部署在命名空间中的所有新工作负载中。 + +此命名空间设置只会影响命名空间中的新工作负载。之前的工作负载需要重新部署才能使用 sidecar 自动注入。 + +:::note 先决条件： + +要在命名空间中启用 Istio，集群必须安装 Istio。 + +::: + +1. 点击 **☰ > 集群管理**。 +1. 选择你创建的集群，并点击 **Explore**。 +1. 单击**集群 > 项目/命名空间**。 +1. 转到要启用 Istio 的命名空间，然后单击**⋮ > 启用 Istio 自动注入**。或者，你也可以单击命名空间，然后在命名空间详情页面上，单击**⋮ > 启用 Istio 自动注入**。 + +**结果**：命名空间带有了 `istio-injection=enabled` 标签。默认情况下，部署在此命名空间中的所有新工作负载都将注入 Istio sidecar。 + +## 验证是否启用了自动 Istio Sidecar 注入 + +要验证 Istio 是否已启用，请在命名空间中部署一个 hello-world 工作负载。转到工作负载并单击 pod 名称。在**容器**中，你应该能看到 `istio-proxy` 容器。 + +## 排除工作负载的 Istio Sidecar 注入 + +要排除 Istio sidecar 被注入某工作负载，请在工作负载上使用以下注释： + +``` +sidecar.istio.io/inject: “false” +``` + +要将注释添加到工作负载： + +1. 点击 **☰ > 集群管理**。 +1. 选择你创建的集群，并点击 **Explore**。 +1. 点击**工作负载**。 +1. 转到不需要 sidecar 的工作负载并以 yaml 编辑。 +1. 将键值 `sidecar.istio.io/inject: false` 添加为工作负载的注释。 +1. 单击**保存**。 + +**结果**：Istio sidecar 不会被注入到工作负载中。 + +:::note + +如果你遇到部署的 job 未完成的问题，则需要使用提供的步骤将此注释添加到 pod 中。由于 Istio Sidecars 会一直运行，因此即使任务完成了，也不能认为 Job 已完成。 + +::: + +## 后续步骤 + +[使用 Istio Sidecar 添加部署](use-istio-sidecar.md) diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/advanced-user-guides/istio-setup-guide/generate-and-view-traffic.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/advanced-user-guides/istio-setup-guide/generate-and-view-traffic.md new file mode 100644 index 00000000000..a6d77763919 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/advanced-user-guides/istio-setup-guide/generate-and-view-traffic.md @@ -0,0 +1,26 @@ +--- +title: 6. 生成和查看流量 +--- + +本文介绍如何查看 Istio 管理的流量。 + +## Kiali 流量图 + +Istio 概览页面提供了 Kiali 仪表板的链接。在 Kiali 仪表板中，你可以查看每个命名空间的图。Kiali 图提供了一种强大的方式来可视化 Istio 服务网格的拓扑。它显示了服务之间相互通信的情况。 + +:::note 先决条件： + +要显示流量图，请确保你在集群中安装了 Prometheus。Rancher-istio 安装了默认配置的 Kiali 来与 rancher-monitoring Chart 一起工作。你可以使用 rancher-monitoring 或安装自己的监控解决方案。你也可以通过设置[选择器 & 抓取配置](../../../integrations-in-rancher/istio/configuration-options/selectors-and-scrape-configurations.md)选项来更改数据抓取的配置（可选）。 + +::: + +要查看流量图： + +1. 在安装了 Istio 的集群中，点击左侧导航栏中的 **Istio**。 +1. 单击 **Kiali** 链接。 +1. 单击侧导航中的**图**。 +1. 在**命名空间**下拉列表中，更改命名空间以查看每个命名空间的流量。 + +如果你多次刷新 BookInfo 应用的 URL，你将能够在 Kiali 图上看到绿色箭头，显示 `reviews` 服务 `v1` 和 `v3` 的流量。图右侧的控制面板可用于配置详细信息，包括应在图上显示多少分钟的最新流量。 + +对于其他工具和可视化，你可以从**监控** > **概览**页面转到 Grafana 和 Prometheus 仪表板。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/advanced-user-guides/istio-setup-guide/istio-setup-guide.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/advanced-user-guides/istio-setup-guide/istio-setup-guide.md new file mode 100644 index 00000000000..e6b3e08e753 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/advanced-user-guides/istio-setup-guide/istio-setup-guide.md @@ -0,0 +1,34 @@ +--- +title: 设置指南 +--- + + + + + +本文介绍如何启用 Istio 并在你的项目中使用它。 + +如果你使用 Istio 进行流量管理，则需要允许外部流量进入集群。在这种情况下，你将需要执行以下所有步骤。 + +## 先决条件 + +本指南假设你已经[安装 Rancher](../../../getting-started/installation-and-upgrade/installation-and-upgrade.md)，且已经[配置了一个单独的 Kubernetes 集群](../../new-user-guides/kubernetes-clusters-in-rancher-setup/kubernetes-clusters-in-rancher-setup.md)并要在该集群上安装 Istio。 + +集群中的节点必须满足 [CPU 和内存要求](../../../integrations-in-rancher/istio/cpu-and-memory-allocations.md)。 + +Istio 控制的工作负载和服务必须满足 [Istio 要求](https://istio.io/docs/setup/additional-setup/requirements/)。 + +## 安装 + +:::tip 快速设置提示: + +如果你不需要外部流量到达 Istio，而只想设置 Istio 以监控和跟踪集群内的流量，请跳过[设置 Istio Gateway](set-up-istio-gateway.md)和[设置 Istio 的流量管理组件](set-up-traffic-management.md)步骤。 + +::: + +1. [在集群中启用 Istio。](enable-istio-in-cluster.md) +2. [在命名空间中启用 Istio。](enable-istio-in-namespace.md) +3. [使用 Istio Sidecar 添加部署和服务。](use-istio-sidecar.md) +4. [设置 Istio Gateway。](set-up-istio-gateway.md) +5. [设置 Istio 的流量管理组件。](set-up-traffic-management.md) +6. [生成和查看流量。](generate-and-view-traffic.md) diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/advanced-user-guides/istio-setup-guide/set-up-istio-gateway.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/advanced-user-guides/istio-setup-guide/set-up-istio-gateway.md new file mode 100644 index 00000000000..42f89baa8ef --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/advanced-user-guides/istio-setup-guide/set-up-istio-gateway.md @@ -0,0 +1,147 @@ +--- +title: 4. 设置 Istio Gateway +--- + +每个集群的网关可以有自己的端口或负载均衡器，这与服务网格无关。默认情况下，每个 Rancher 配置的集群都有一个 NGINX Ingress Controller 来允许流量进入集群。 + +无论是否安装了 Istio，你都可以使用 NGINX Ingress Controller。如果这是你集群的唯一网关，Istio 将能够将流量从集群内部的服务路由到集群内部的另一个服务，但 Istio 将无法接收来自集群外部的流量。 + +要让 Istio 接收外部流量，你需要启用 Istio 的网关，作为外部流量的南北代理。启用 Istio Gateway 后，你的集群将有两个 Ingress。 + +你还需要为你的服务设置 Kubernetes 网关。此 Kubernetes 资源指向 Istio 对集群 Ingress Gateway 的实现。 + +你可以使用负载均衡器将流量路由到服务网格中，或使用 Istio 的 NodePort 网关。本文介绍如何设置 NodePort 网关。 + +有关 Istio Gateway 的更多信息，请参阅 [Istio 文档](https://istio.io/docs/reference/config/networking/v1alpha3/gateway/)。 + +![启用 Istio 的集群可以有两个 ingress，分别是默认的 Nginx ingress 和默认的 Istio controller](/img/istio-ingress.svg) + +## 启用 Istio Gateway + +Ingress Gateway 是一个 Kubernetes 服务，将部署在你的集群中。Istio Gateway 支持更多自定义设置，更加灵活。 + +1. 点击 **☰ > 集群管理**。 +1. 选择你创建的集群，并点击 **Explore**。 +1. 在左侧导航栏中，单击 **Istio > 网关**。 +1. 单击**使用 YAML 文件创建**。 +1. 粘贴你的 Istio Gateway yaml，或选择**从文件读取**。 +1. 单击**创建**。 + +**结果**：已部署网关，将使用应用的规则来路由流量。 + +## Istio Gateway 示例 + +在演示工作负载示例时，我们在服务中添加 BookInfo 应用部署。接下来，我们添加一个 Istio Gateway，以便从集群外部访问该应用。 + +1. 点击 **☰ > 集群管理**。 +1. 选择你创建的集群，并点击 **Explore**。 +1. 在左侧导航栏中，单击 **Istio > 网关**。 +1. 单击**使用 YAML 文件创建**。 +1. 复制并粘贴下面的 Gateway YAML。 +1. 单击**创建**。 + +```yaml +apiVersion: networking.istio.io/v1alpha3 +kind: Gateway +metadata: + name: bookinfo-gateway +spec: + selector: + istio: ingressgateway # use istio default controller + servers: + - port: + number: 80 + name: http + protocol: HTTP + hosts: + - "*" +--- +``` + +然后，部署为 Gateway 提供流量路由的 VirtualService： + +1. 点击 **☰ > 集群管理**。 +1. 选择你创建的集群，并点击 **Explore**。 +1. 在左侧导航栏中，单击 **Istio > VirtualServices**。 +1. 复制并粘贴下面的 VirtualService YAML。 +1. 单击**创建**。 + +```yaml +apiVersion: networking.istio.io/v1alpha3 +kind: VirtualService +metadata: + name: bookinfo +spec: + hosts: + - "*" + gateways: + - bookinfo-gateway + http: + - match: + - uri: + exact: /productpage + - uri: + prefix: /static + - uri: + exact: /login + - uri: + exact: /logout + - uri: + prefix: /api/v1/products + route: + - destination: + host: productpage + port: + number: 9080 +``` + +**结果**：你已配置网关资源，Istio 现在可以接收集群外部的流量。 + +运行以下命令来确认资源存在： +``` +kubectl get gateway -A +``` + +结果应与以下内容类似： +``` +NAME AGE +bookinfo-gateway 64m +``` + +### 在 Web 浏览器访问 ProductPage 服务 + +要测试 BookInfo 应用是否已正确部署，你可以使用 Istio 控制器 IP 和端口以及在 Kubernetes 网关资源中指定的请求名称，在 Web 浏览器中查看该应用： + +`http://:/productpage` + +要获取 Ingress Gateway URL 和端口： + +1. 点击 **☰ > 集群管理**。 +1. 选择你创建的集群，并点击 **Explore**。 +1. 在左侧导航栏中，单击**工作负载**。 +1. 向下滚动到 `istio-system` 命名空间。 +1. 在 `istio-system`中，有一个名为 `istio-ingressgateway` 的工作负载。在此工作负载的名称下，你应该会看到如 `80/tcp` 的链接。 +1. 单击其中一个链接。然后，你的 Web 浏览器中会显示 Ingress Gateway 的 URL。将 `/productpage` 尾附到 URL。 + +**结果**：你能会在 Web 浏览器中看到 BookInfo 应用。 + +如需检查 Istio 控制器 URL 和端口的帮助，请尝试运行 [Istio 文档](https://istio.io/docs/tasks/traffic-management/ingress/ingress-control/#determining-the-ingress-ip-and-ports)中的命令。 + +## 故障排除 + +[官方 Istio 文档](https://istio.io/docs/tasks/traffic-management/ingress/ingress-control/#troubleshooting)建议使用 `kubectl` 命令来检查外部请求的正确 ingress 主机和 ingress 端口。 + +### 确认 Kubernetes 网关与 Istio 的 Ingress Controller 匹配 + +你可以尝试执行本节中的步骤以确保 Kubernetes 网关配置正确。 + +在网关资源中，选择器通过标签来引用 Istio 的默认 Ingress Controller，其中标签的键是 `Istio`，值是 `ingressgateway`。要确保标签适用于网关，请执行以下操作： + +1. 点击 **☰ > 集群管理**。 +1. 选择你创建的集群，并点击 **Explore**。 +1. 在左侧导航栏中，单击**工作负载**。 +1. 向下滚动到 `istio-system` 命名空间。 +1. 在 `istio-system`中，有一个名为 `istio-ingressgateway` 的工作负载。单击此工作负载的名称并转到**标签和注释**部分。你应该看到它具有 `istio` 键和 `ingressgateway` 值。这确认了 Gateway 资源中的选择器与 Istio 的默认 ingress controller 匹配。 + +### 后续步骤 +[设置 Istio 的流量管理组件](set-up-traffic-management.md) diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/advanced-user-guides/istio-setup-guide/set-up-traffic-management.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/advanced-user-guides/istio-setup-guide/set-up-traffic-management.md new file mode 100644 index 00000000000..f143dc2cdc6 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/advanced-user-guides/istio-setup-guide/set-up-traffic-management.md @@ -0,0 +1,77 @@ +--- +title: 5. 设置 Istio 的流量管理组件 +--- + +Istio 中流量管理的一个核心优势是允许动态请求路由。动态请求路由通常应用于金丝雀部署和蓝/绿部署等。Istio 流量管理中的两个关键资源是*虚拟服务*和*目标规则*。 + +- [虚拟服务](https://istio.io/docs/reference/config/networking/v1alpha3/virtual-service/)：拦截并将流量重定向到你的 Kubernetes Service 上。这样，你可以将部分请求流量分配到不同的服务上。你可以使用这些服务来定义一组路由规则，用于主机寻址。 +- [目标规则](https://istio.io/docs/reference/config/networking/v1alpha3/destination-rule/)：作为唯一可信来源，表明哪些服务版本可用于接收虚拟服务的流量。你可以使用这些资源来定义策略，这些策略适用于路由发生后用于服务的流量。 + +本文介绍如何在示例 BookInfo 应用中添加与 `reviews` 微服务对应的虚拟服务示例。此服务的目的是在 `reviews` 服务的两个版本之间划分流量。 + +在这个示例中，我们将流量带到 `reviews` 服务中并拦截流量，这样，50% 的流量会流向服务的 `v1`，另外 50% 的流量会流向 `v2 `。 + +部署这个虚拟服务后，我们将生成流量，并通过 Kiali 可视化看到流量平均路由到服务的两个版本中。 + +要为 `reviews` 服务部署虚拟服务和目标规则： +1. 点击 **☰ > 集群管理**。 +1. 转到安装了 Istio 的集群，然后单击 **Explore**。 +1. 在安装了 Istio 的集群中，点击左侧导航栏中的 **Istio > DestinationRules**。 +1. 单击**创建**。 +1. 复制并粘贴下面的 DestinationRule YAML。 +1. 单击**创建**。 +1. 单击**以 YAML 文件编辑**并使用此配置： + + ```yaml + apiVersion: networking.istio.io/v1alpha3 + kind: DestinationRule + metadata: + name: reviews + spec: + host: reviews + subsets: + - name: v1 + labels: + version: v1 + - name: v2 + labels: + version: v2 + - name: v3 + labels: + version: v3 + ``` +1. 单击**创建**。 + +然后，部署提供利用 DestinationRule 的流量路由的 VirtualService： + +1. 单击侧导航栏中的 **VirtualService**。 +1. 单击**使用 YAML 文件创建**。 +1. 复制并粘贴下面的 VirtualService YAML。 +1. 单击**创建**。 + +```yaml +apiVersion: networking.istio.io/v1alpha3 +kind: VirtualService +metadata: + name: reviews +spec: + hosts: + - reviews + http: + - route: + - destination: + host: reviews + subset: v1 + weight: 50 + - destination: + host: reviews + subset: v3 + weight: 50 +--- +``` + +**结果**：生成流到该服务的流量时（例如，刷新 Ingress Gateway URL），你可以在 Kiali 流量图中看到流到 `reviews` 服务的流量被平均分配到了 `v1` 和 `v3`。 + +## 后续步骤 + +[生成和查看流量](generate-and-view-traffic.md) diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/advanced-user-guides/istio-setup-guide/use-istio-sidecar.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/advanced-user-guides/istio-setup-guide/use-istio-sidecar.md new file mode 100644 index 00000000000..cae09528074 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/advanced-user-guides/istio-setup-guide/use-istio-sidecar.md @@ -0,0 +1,361 @@ +--- +title: 3. 使用 Istio Sidecar 添加部署和服务 +--- + +:::note 先决条件： + +要为工作负载启用 Istio，你必须先在集群和命名空间中安装 Istio 应用。 + +::: + +在命名空间中启用 Istio 只会为新工作负载启用自动 sidecar 注入。要为现有工作负载启用 Envoy sidecar，你需要手动为每个工作负载启用它。 + +要在命名空间中的现有工作负载上注入 Istio sidecar： + +1. 在左上角，单击 **☰ > 集群管理**。 +1. 在**集群**页面上，转到要可视化的集群，然后单击 **Explore**。 +1. 点击**工作负载**。 +1. 转到要注入 Istio sidecar 的工作负载，然后单击 **⋮ > 重新部署**。重新部署工作负载后，该工作负载会自动注入 Envoy sidecar。 + +等待几分钟，然后工作负载将升级并具有 Istio sidecar。单击它并转到**容器**。你应该能看到该工作负载旁边的 `istio-proxy`。这意味着为工作负载启用了 Istio sidecar。Istio 正在为 Sidecar Envoy 做所有的接线工作。如果你现在在 yaml 中启用它们，Istio 可以自动执行所有功能。 + +## 添加部署和服务 + +以下是在命名空间中添加新 **Deployment** 的几种方法： + +1. 点击 **☰ > 集群管理**。 +1. 选择你创建的集群，并点击 **Explore**。 +1. 点击**工作负载**。 +1. 单击**创建**。 +1. 点击 **Deployment**。 +1. 填写表单，或**以 YAML 文件编辑**。 +1. 单击**创建**。 + +要将 **Service** 添加到你的命名空间： + +1. 点击 **☰ > 集群管理**。 +1. 选择你创建的集群，并点击 **Explore**。 +1. 点击**服务发现 > 服务**。 +1. 单击**创建**。 +1. 选择所需的服务类型。 +1. 填写表单，或**以 YAML 文件编辑**。 +1. 点击**创建**。 + +你还可以使用 kubectl **shell** 来创建 deployment 和 service： + +1. 如果你的文件存储在本地集群中，运行 `kubectl create -f .yaml`。 +1. 或运行 `cat<< EOF | kubectl apply -f -`，将文件内容粘贴到终端，然后运行 `EOF` 来完成命令。 + +## 部署和服务示例 + +接下来，我们为 Istio 文档中的 BookInfo 应用的示例部署和服务添加 Kubernetes 资源： + +1. 点击 **☰ > 集群管理**。 +1. 选择你创建的集群，并点击 **Explore**。 +1. 在顶部导航栏中，打开 kubectl shell。 +1. 运行 `cat<< EOF | kubectl apply -f -`。 +1. 将以下资源复制到 shell 中。 +1. 运行 `EOF`。 + +这将在 Istio 的示例 BookInfo 应用中设置以下示例资源： + +Details 服务和部署： + +- 一个 `details` Service。 +- 一个 `bookinfo-details` 的 ServiceAccount。 +- 一个 `details-v1` Deployment。 + +Ratings 服务和部署： + +- 一个 `ratings` Service。 +- 一个 `bookinfo-ratings` 的 ServiceAccount。 +- 一个 `ratings-v1` Deployment。 + +Reviews 服务和部署（三个版本）： + +- 一个 `reviews` Service。 +- 一个 `bookinfo-reviews` 的 ServiceAccount。 +- 一个 `reviews-v1` Deployment。 +- 一个 `reviews-v2` Deployment。 +- 一个 `reviews-v3` Deployment。 + +Productpage 服务和部署： + +这是应用的主页，可以通过网络浏览器中查看。将从该页面调用其他服务。 + +- 一个 `productpage` service。 +- 一个 `bookinfo-productpage` 的 ServiceAccount。 +- 一个 `productpage-v1` Deployment。 + +## 资源 YAML + +```yaml +# Copyright 2017 Istio Authors +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +################################################################################################## +# Details service +################################################################################################## +apiVersion: v1 +kind: Service +metadata: + name: details + labels: + app: details + service: details +spec: + ports: + - port: 9080 + name: http + selector: + app: details +--- +apiVersion: v1 +kind: ServiceAccount +metadata: + name: bookinfo-details +--- +apiVersion: apps/v1 +kind: Deployment +metadata: + name: details-v1 + labels: + app: details + version: v1 +spec: + replicas: 1 + selector: + matchLabels: + app: details + version: v1 + template: + metadata: + labels: + app: details + version: v1 + spec: + serviceAccountName: bookinfo-details + containers: + - name: details + image: docker.io/istio/examples-bookinfo-details-v1:1.15.0 + imagePullPolicy: IfNotPresent + ports: + - containerPort: 9080 +--- +################################################################################################## +# Ratings service +################################################################################################## +apiVersion: v1 +kind: Service +metadata: + name: ratings + labels: + app: ratings + service: ratings +spec: + ports: + - port: 9080 + name: http + selector: + app: ratings +--- +apiVersion: v1 +kind: ServiceAccount +metadata: + name: bookinfo-ratings +--- +apiVersion: apps/v1 +kind: Deployment +metadata: + name: ratings-v1 + labels: + app: ratings + version: v1 +spec: + replicas: 1 + selector: + matchLabels: + app: ratings + version: v1 + template: + metadata: + labels: + app: ratings + version: v1 + spec: + serviceAccountName: bookinfo-ratings + containers: + - name: ratings + image: docker.io/istio/examples-bookinfo-ratings-v1:1.15.0 + imagePullPolicy: IfNotPresent + ports: + - containerPort: 9080 +--- +################################################################################################## +# Reviews service +################################################################################################## +apiVersion: v1 +kind: Service +metadata: + name: reviews + labels: + app: reviews + service: reviews +spec: + ports: + - port: 9080 + name: http + selector: + app: reviews +--- +apiVersion: v1 +kind: ServiceAccount +metadata: + name: bookinfo-reviews +--- +apiVersion: apps/v1 +kind: Deployment +metadata: + name: reviews-v1 + labels: + app: reviews + version: v1 +spec: + replicas: 1 + selector: + matchLabels: + app: reviews + version: v1 + template: + metadata: + labels: + app: reviews + version: v1 + spec: + serviceAccountName: bookinfo-reviews + containers: + - name: reviews + image: docker.io/istio/examples-bookinfo-reviews-v1:1.15.0 + imagePullPolicy: IfNotPresent + ports: + - containerPort: 9080 +--- +apiVersion: apps/v1 +kind: Deployment +metadata: + name: reviews-v2 + labels: + app: reviews + version: v2 +spec: + replicas: 1 + selector: + matchLabels: + app: reviews + version: v2 + template: + metadata: + labels: + app: reviews + version: v2 + spec: + serviceAccountName: bookinfo-reviews + containers: + - name: reviews + image: docker.io/istio/examples-bookinfo-reviews-v2:1.15.0 + imagePullPolicy: IfNotPresent + ports: + - containerPort: 9080 +--- +apiVersion: apps/v1 +kind: Deployment +metadata: + name: reviews-v3 + labels: + app: reviews + version: v3 +spec: + replicas: 1 + selector: + matchLabels: + app: reviews + version: v3 + template: + metadata: + labels: + app: reviews + version: v3 + spec: + serviceAccountName: bookinfo-reviews + containers: + - name: reviews + image: docker.io/istio/examples-bookinfo-reviews-v3:1.15.0 + imagePullPolicy: IfNotPresent + ports: + - containerPort: 9080 +--- +################################################################################################## +# Productpage services +################################################################################################## +apiVersion: v1 +kind: Service +metadata: + name: productpage + labels: + app: productpage + service: productpage +spec: + ports: + - port: 9080 + name: http + selector: + app: productpage +--- +apiVersion: v1 +kind: ServiceAccount +metadata: + name: bookinfo-productpage +--- +apiVersion: apps/v1 +kind: Deployment +metadata: + name: productpage-v1 + labels: + app: productpage + version: v1 +spec: + replicas: 1 + selector: + matchLabels: + app: productpage + version: v1 + template: + metadata: + labels: + app: productpage + version: v1 + spec: + serviceAccountName: bookinfo-productpage + containers: + - name: productpage + image: docker.io/istio/examples-bookinfo-productpage-v1:1.15.0 + imagePullPolicy: IfNotPresent + ports: + - containerPort: 9080 +--- +``` + +## 后续步骤 + +[设置 Istio Gateway](set-up-istio-gateway.md) diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/advanced-user-guides/manage-projects/manage-project-resource-quotas/about-project-resource-quotas.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/advanced-user-guides/manage-projects/manage-project-resource-quotas/about-project-resource-quotas.md new file mode 100644 index 00000000000..26e87e8f31a --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/advanced-user-guides/manage-projects/manage-project-resource-quotas/about-project-resource-quotas.md @@ -0,0 +1,67 @@ +--- +title: Rancher 项目中资源配额的工作原理 +--- + +Rancher 中的资源配额包含与 [Kubernetes 原生版本](https://kubernetes.io/docs/concepts/policy/resource-quotas/)相同的功能。Rancher 还扩展了资源配额的功能，让你将资源配额应用于项目。 + +在标准 Kubernetes deployment 中，资源配额会应用于各个命名空间。但是，你不能通过单次操作将配额应用到多个命名空间，而必须多次应用资源配额。 + +在下图中，Kubernetes 管理员试图在没有 Rancher 的情况下强制执行资源配额。管理员想要使用一个资源配额来为集群中的每个命名空间配置统一的 CPU 和内存限制 (`Namespace 1-4`)。但是，在 Kubernetes 的基础版本中，每个命名空间都需要单独设置资源配额。因此，管理员必须创建四个配置相同规格的不同资源配额（`Resource Quota 1-4`）并单独应用这些配额。 + +Kubernetes 基础版本：每个命名空间都需要独立设置资源配额 + +![原生 Kubernetes 资源配额实现](/img/kubernetes-resource-quota.svg) + +和原生 Kubernetes 相比，Rancher 的资源配额有不同。在 Rancher 中，你可以把资源配额应用到项目层级，进而让项目的资源配额沿用到项目内的每一个命名空间，然后 Kubernetes 会使用原生的资源配额来强制执行你设置的限制。如果要更改特定命名空间的配额，你也可以覆盖设置。 + +项目配额包括你在创建或编辑集群时设置的两个限制： + + +- **项目限制**： + + 配置了项目中所有命名空间共享的每个指定资源的总限制。 + +- **命名空间默认限制**： + + 配置了每个命名空间对每个指定资源的默认配额。 + 如果项目中的命名空间配置没有被覆盖，那么此限制会自动绑定到命名空间并强制执行。 + + +在下图中，Rancher 管理员想使用资源配额来为项目中的每个命名空间（`命名空间 1-4`）设置相同的 CPU 和内存限制。在 Rancher 中，管理员可以为项目设置资源配额（`项目资源配额`），而不需要为命名空间单独进行设置。此配额包括整个项目（`项目限制`）和单个命名空间（`命名空间默认限制`）的资源限制。然后，Rancher 会将`命名空间默认限制`的配额沿用到每个命名空间（`命名空间资源配额`）。 + +Rancher：资源配额沿用到每个命名空间 + +![Rancher 资源配额实现](/img/rancher-resource-quota.png) + +以下介绍在 Rancher UI **_中_** 创建的命名空间的更细微的功能。如果你删除了项目级别的资源配额，无论命名空间层级是否有自定义的资源配额，项目内的所有命名空间也会移除这个资源配额。在项目层级修改已有的命名空间默认资源配额，不会影响命名空间内的资源配额，修改后的项目层级资源配额只会对以后新建的命名空间生效。要修改多个现有命名空间的默认限制，你可以在项目层级删除该限制，然后再使用新的默认值重新创建配额。这种方式会将新的默认值应用于项目中的所有现有命名空间。 + +在项目中创建命名空间之前，Rancher 会使用默认限制和覆盖限制来对比项目内的可用资源和请求资源。 +如果请求的资源超过了项目中这些资源的剩余容量，Rancher 将为命名空间分配该资源的剩余容量。 + +但是，在 Rancher 的 UI **_外_** 创建的命名空间的处理方法则不一样。对于通过 `kubectl` 创建的命名空间，如果请求的资源量多余项目内的余量，Rancher 会分配一个数值为 **0** 的资源配额。 + +要使用 `kubectl` 在现有项目中创建命名空间，请使用 `field.cattle.io/projectId` 注释。要覆盖默认的请求配额限制，请使用 `field.cattle.io/resourceQuota` 注释。 + +请注意，Rancher 只会覆盖项目配额上定义的资源限制。 + +``` +apiVersion: v1 +kind: Namespace +metadata: + annotations: + field.cattle.io/projectId: [your-cluster-ID]:[your-project-ID] + field.cattle.io/resourceQuota: '{"limit":{"limitsCpu":"100m", "configMaps": "50"}}' + name: my-ns +``` +在此示例中，如果项目配额在其资源列表中不包含 configMaps，那么 Rancher 将忽略此覆盖中的 `configMaps`。 + +对于项目中未定义的资源，建议你在命名空间中创建专用的 `ResourceQuota` 对象来配置其它自定义限制。 +资源配额是原生 Kubernetes 对象，如果命名空间属于具有配额的项目，Rancher 将忽略用户定义的配额，从而给予用户更多的控制权。 + +下表对比了 Rancher 和 Kubernetes 资源配额的主要区别： + +| Rancher 资源配额 | Kubernetes 资源配额 | +| ---------------------------------------------------------- | -------------------------------------------------------- | +| 应用于项目和命名空间。 | 仅应用于命名空间。 | +| 为项目中的所有命名空间创建资源池。 | 将静态资源限制应用到单独的命名空间。 | +| 通过沿用的模式，将资源配额应用于各个命名空间。 | 仅应用于指定的命名空间。 | diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/advanced-user-guides/manage-projects/manage-project-resource-quotas/manage-project-resource-quotas.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/advanced-user-guides/manage-projects/manage-project-resource-quotas/manage-project-resource-quotas.md new file mode 100644 index 00000000000..f4af6d0c85b --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/advanced-user-guides/manage-projects/manage-project-resource-quotas/manage-project-resource-quotas.md @@ -0,0 +1,50 @@ +--- +title: 项目资源配额 +--- + + + + + +如果多个团队共享一个集群，某个团队可能会使用过多的可用资源，例如 CPU、内存、存储、服务、Kubernetes 对象（如 Pod 或 Secret）等。你可以应用 _资源配额_ 来防止过度消耗资源。资源配额是 Rancher 用来限制项目或命名空间可用资源的功能。 + +本文介绍如何在现有项目中创建资源配额。 + +你也可以在创建新项目时设置资源配额。有关详细信息，请参阅[创建新项目](../../../new-user-guides/manage-clusters/projects-and-namespaces.md#创建项目)。 + +Rancher 中的资源配额包含与 [Kubernetes 原生版本](https://kubernetes.io/docs/concepts/policy/resource-quotas/)相同的功能。Rancher 还扩展了资源配额的功能，从而让你将资源配额应用于项目。有关资源配额如何与 Rancher 中的项目一起使用的详细信息，请参阅[此页面](about-project-resource-quotas.md)。 + +## 将资源配额应用于现有项目 + +修改资源配额的使用场景如下： + +- 限制某个项目和项目下的命名空间能使用的资源 +- 在资源配额已生效的情况下，对项目可用的资源进行扩容或缩容 + +1. 在左上角，单击 **☰ > 集群管理**。 +1. 在**集群**页面，进入要应用资源配额的集群，然后单击 **Explore**。 +1. 单击**集群 > 项目/命名空间**。 +1. 确保 **Projects/Namespaces** 页面处于 **Group by Project** 视图模式。 + ![Screenshot highlighting the "Group by Project" icon, above the list of projects. It resembles a folder.](/img/edit-project-config-for-resource-quotas-group-by-project.png) + +1. 找到要添加资源配额的项目，选择与项目名称同行的 **⋮**。 + ![Screenshot highlighting triple dots icon at the end of the same row as the project name.](/img/edit-project-config-for-resource-quotas-dots.png) + +1. 选择**编辑配置**。 + +1. 展开**资源限额**并单击**添加资源**。你也可以编辑现有配额。 + +1. 选择资源类型。有关类型的更多信息，请参阅[配额类型参考](resource-quota-types.md)。 + +1. 输入**项目限制**和**命名空间默认限制**的值。 + + | 字段 | 描述 | + | ----------------------- | -------------------------------------------------------------------------------------------------------- | + | 项目限制 | 项目的总资源限制。 | + | 命名空间默认限制 | 每个命名空间的默认资源限制。此限制会沿用到项目中的每个命名空间。项目中所有命名空间的限制之和不应超过项目限制。 | + +1. **可选**：添加更多配额。 + +1. 单击**创建**。 + +**结果**：资源配额已应用到你的项目和命名空间。如果你后续需要添加更多命名空间，Rancher 会验证项目是否可以容纳该命名空间。如果项目无法分配资源，你仍然可以创建命名空间，但命名空间将获得的资源配额为 0。然后 Rancher 将不允许你创建任何受此配额限制的资源。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/advanced-user-guides/manage-projects/manage-project-resource-quotas/override-default-limit-in-namespaces.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/advanced-user-guides/manage-projects/manage-project-resource-quotas/override-default-limit-in-namespaces.md new file mode 100644 index 00000000000..359dcd7695a --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/advanced-user-guides/manage-projects/manage-project-resource-quotas/override-default-limit-in-namespaces.md @@ -0,0 +1,34 @@ +--- +title: 覆盖命名空间的默认限制 +--- + +**命名空间默认限制**会在创建时从项目沿用到每个命名空间。但在某些情况下，你可能需要增加或减少特定命名空间的配额。在这种情况下，你可以通过编辑命名空间来覆盖默认限制。 + +在下图中，Rancher 管理员的项目有一个已生效的资源配额。但是，管理员想要覆盖 `Namespace 3` 的命名空间限制，以便让该命名空间使用更多资源。因此，管理员[提高了 `Namespace 3` 的命名空间限制](../../../new-user-guides/manage-clusters/projects-and-namespaces.md)，以便命名空间可以访问更多资源。 + +命名空间默认限制覆盖 + +![命名空间默认限制覆盖](/img/rancher-resource-quota-override.svg) + +有关详细信息，请参阅[如何编辑命名空间资源配额](../../../new-user-guides/manage-clusters/projects-and-namespaces.md)。 + +## 编辑命名空间资源配额 + +如果你已为项目配置了资源配额，你可以覆盖命名空间默认限制，从而为特定命名空间提供对更多（或更少）项目资源的访问权限： + +1. 在左上角，单击 **☰ > 集群管理**。 +1. 在**集群**页面上，转到要编辑命名空间资源配额的集群，然后单击 **Explore**。 +1. 单击**集群 > 项目/命名空间**。 +1. 找到要为其编辑资源配额的命名空间。单击 **⋮ > 编辑配置**。 +1. 编辑资源限制。这些限制决定了命名空间可用的资源。必须在项目限制范围内配置这些配额限制。 + + 有关每个**资源类型**的详细信息，请参阅[类型参考](resource-quota-types.md)。 + + :::note + + - 如果没有为项目配置资源配额，这些选项将不可用。 + - 如果你输入的限制超过了配置的项目限制，你将无法保存修改。 + + ::: + +**结果**：覆盖设置已经应用到命名空间的资源配额。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/advanced-user-guides/manage-projects/manage-project-resource-quotas/resource-quota-types.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/advanced-user-guides/manage-projects/manage-project-resource-quotas/resource-quota-types.md new file mode 100644 index 00000000000..b0873befd7a --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/advanced-user-guides/manage-projects/manage-project-resource-quotas/resource-quota-types.md @@ -0,0 +1,27 @@ +--- +title: 资源配额类型参考 +--- + +创建资源配额相当于配置项目可用的资源池。你可以为以下资源类型设置资源配额： + +| 资源类型 | 描述 | +| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| CPU 限制\* | 分配给项目/命名空间的最大 CPU 量（以[毫核](https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container/#meaning-of-cpu)为单位）1 | +| CPU 预留\* | 预留给项目/命名空间的最小 CPU 量（以毫核为单位）1 | +| 内存限制\* | 分配给项目/命名空间的最大内存量（以字节为单位）1 | +| 内存预留\* | 预留给项目/命名空间的最小内存量（以字节为单位）1 | +| 存储预留 | 预留给项目/命名空间的最小存储量（以千兆字节为单位） | +| 服务负载均衡器 | 项目/命名空间中可以存在的负载均衡器服务的最大数量 | +| 服务节点端口 | 项目/命名空间中可以存在的节点端口服务的最大数量 | +| Pod | 可以在项目/命名空间中以非终端状态存在的 pod 的最大数量（即 `.status.phase in (Failed, Succeeded)` 等于 true 的 pod） | +| Services | 项目/命名空间中可以存在的最大 service 数量 | +| ConfigMap | 项目/命名空间中可以存在的 ConfigMap 的最大数量 | +| 持久卷声明 | 项目/命名空间中可以存在的持久卷声明的最大数量 | +| ReplicationController | 项目/命名空间中可以存在的最大 ReplicationController 数量 | +| 密文 | 项目/命名空间中可以存在的最大密文数量 | + +:::note ***** + +在设置资源配额时，如果你在项目或命名空间上设置了任何与 CPU 或内存相关的内容（即限制或预留），所有容器都需要在创建期间设置各自的 CPU 或内存字段。你可以同时设置容器的默认资源限制，以避免为每个工作负载显式设置这些限制。详情请参阅 [Kubernetes 文档](https://kubernetes.io/docs/concepts/policy/resource-quotas/#requests-vs-limits)。 + +::: \ No newline at end of file diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/advanced-user-guides/manage-projects/manage-project-resource-quotas/set-container-default-resource-limits.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/advanced-user-guides/manage-projects/manage-project-resource-quotas/set-container-default-resource-limits.md new file mode 100644 index 00000000000..1735266bd74 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/advanced-user-guides/manage-projects/manage-project-resource-quotas/set-container-default-resource-limits.md @@ -0,0 +1,40 @@ +--- +title: 设置容器默认资源限制 +--- + +在设置资源配额时，如果你在项目或命名空间上设置了任何与 CPU 或内存相关的内容（即限制或预留），所有容器都需要在创建期间设置各自的 CPU 或内存字段。详情请参阅 [Kubernetes 文档](https://kubernetes.io/docs/concepts/policy/resource-quotas/#requests-vs-limits)。 + +为了避免在创建工作负载期间对每个容器设置这些限制，可以在命名空间上指定一个默认的容器资源限制。 + +## 编辑容器默认资源限制 + +你可以在以下情况下编辑容器的默认资源限制： + +- 你在项目上设置了 CPU 或内存资源配额，现在需要为容器设置相应的默认值。 +- 你需要编辑容器的默认资源限制。 + +1. 在左上角，单击 **☰ > 集群管理**。 +1. 在**集群**页面上，转到要编辑默认资源限制的集群，然后单击 **Explore**。 +1. 单击**集群 > 项目/命名空间**。 +1. 找到要编辑容器默认资源限制的项目。在该项目中选择 **⋮ > 编辑配置**。 +1. 展开**容器默认资源限制**并编辑对应的值。 + +## 沿用资源限制 + +在项目级别设置默认容器资源限制后，项目中所有新建的命名空间都会沿用这个资源限制参数。新设置的限制不会影响项目中现有的命名空间。你需要为项目中的现有命名空间手动设置默认容器资源限制，以便创建容器时能应用该限制。 + +你可以为项目设置容器的默认资源限制并启动任何商店应用。 + +在命名空间上配置容器默认资源限制后，在该命名空间中创建的任何容器都会沿用该默认值。你可以在工作负载创建期间覆盖这些限制/预留。 + +## 容器资源配额类型 + +可以配置以下资源限制： + +| 资源类型 | 描述 | +| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| CPU 限制 | 分配给容器的最大 CPU 量（以[毫核](https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container/#meaning-of-cpu)为单位）。 | +| CPU 预留 | 保留给容器的最小 CPU 量（以毫核为单位）。 | +| 内存限制 | 分配给容器的最大内存量（以字节为单位）。 | +| 内存预留 | 保留给容器的最小内存量（以字节为单位）。 | +| NVIDIA GPU 限制/预留 | 分配给容器的 GPU 数量。GPU 的限制和预留始终相同。 | diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/advanced-user-guides/manage-projects/manage-projects.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/advanced-user-guides/manage-projects/manage-projects.md new file mode 100644 index 00000000000..94fe25d38b8 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/advanced-user-guides/manage-projects/manage-projects.md @@ -0,0 +1,40 @@ +--- +title: 项目管理 +--- + + + + + +_项目_ 是 Rancher 中引入的对象，可帮助你更有组织地管理 Kubernetes 集群中的命名空间。你可以使用项目创建多租户集群，这种集群允许一组用户共享相同的底层资源来创建应用，而应用之间不会相互影响。 + +在层次结构方面： + +- 集群包含项目 +- 项目包含命名空间 + +在 Rancher 中，你可以使用项目将多个命名空间作为一个实体进行管理。在原生 Kubernetes（没有项目这个概念）中，RBAC 或集群资源等功能被分配给了各个命名空间。如果集群中的多个命名空间需要分配同样的访问权限，分配权限会变得非常繁琐。即使所有命名空间都需要相同的权限，但也无法使用一个操作中将这些权限应用于所有命名空间。你必须重复地将这些权限分配给每个命名空间。 + +而 Rancher 通过引入项目的概念，通过允许你在项目级别应用资源和访问权限。然后，项目中的每个命名空间都会继承这些资源和策略。因此你只需将资源和策略分配给项目即可，不需要将它们分配给每个单独的命名空间。 + +你可以使用项目执行以下操作： + +- [为用户分配一组命名空间的访问权限](../../new-user-guides/add-users-to-projects.md) +- 为用户分配[项目中的特定角色](../../new-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/cluster-and-project-roles.md#项目角色)。角色可以是所有者、成员、只读或[自定义](../../new-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/custom-roles.md) +- [设置资源配额](manage-project-resource-quotas/manage-project-resource-quotas.md) +- [管理命名空间](../../new-user-guides/manage-namespaces.md) +- [配置工具](../../../reference-guides/rancher-project-tools.md) + +## 授权 + +非管理者用户只有在[管理员](../../new-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/global-permissions.md)、[集群所有者或成员](../../new-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/cluster-and-project-roles.md#集群角色)或[项目所有者](../../new-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/cluster-and-project-roles.md#项目角色)将非管理员用户添加到项目的**成员**选项卡后，才能获取项目的访问权限。 + +创建项目的人自动成为[项目所有者](../../new-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/cluster-and-project-roles.md#项目角色)。 + +## 在项目之间切换 + +要在项目之间切换，请使用导航栏中的下拉菜单。你也可以直接在导航栏中切换项目： + +1. 在左上角，单击 **☰ > 集群管理**。 +1. 在**集群**页面，进入要切换项目的集群然后点击 **Explore**。 +1. 在顶部导航栏中，选择要打开的项目。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/advanced-user-guides/monitoring-alerting-guides/create-persistent-grafana-dashboard.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/advanced-user-guides/monitoring-alerting-guides/create-persistent-grafana-dashboard.md new file mode 100644 index 00000000000..e5a2deccf45 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/advanced-user-guides/monitoring-alerting-guides/create-persistent-grafana-dashboard.md @@ -0,0 +1,148 @@ +--- +title: 持久化 Grafana 仪表板 +--- + +要在重启 Grafana 实例后保存 Grafana 仪表板，请将仪表板的配置 JSON 添加到 ConfigMap 中。ConfigMap 还支持使用基于 GitOps 或 CD 的方法来部署仪表板，从而让你对仪表板进行版本控制。 + +- [创建持久化 Grafana 仪表板](#创建持久化-grafana-仪表板) +- [已知问题](#已知问题) + +## 创建持久化 Grafana 仪表板 + + + + +:::note 先决条件： + +- 已安装 Monitoring 应用。 +- 要创建持久化仪表板，你必须在包含 Grafana 仪表板的项目或命名空间中至少具有**管理 ConfigMap** 的 Rancher RBAC 权限。这与 Monitoring Chart 公开的 `monitoring-dashboard-edit` 或 `monitoring-dashboard-admin` Kubernetes 原生 RBAC 角色对应。 +- 要查看指向外部监控 UI（包括 Grafana 仪表板）的链接，你至少需要一个 [project-member 角色](../../../integrations-in-rancher/monitoring-and-alerting/rbac-for-monitoring.md#具有-rancher-权限的用户)。 + +::: + +### 1. 获取要持久化的仪表板的 JSON 模型 + +要创建持久化仪表板，你需要获取要持久化的仪表板的 JSON 模型。你可以使用预制仪表板或自行构建仪表板。 + +要使用预制仪表板，请转到 [https://grafana.com/grafana/dashboards](https://grafana.com/grafana/dashboards)，打开详细信息页面，然后单击 **Download JSON** 按钮来获取下一步所需的 JSON 模型。 + +要使用你自己的仪表板： + +1. 点击链接打开 Grafana。在集群详细信息页面上，单击 **Monitoring**。 +1. 登录到 Grafana。请注意，Grafana 实例的默认 Admin 用户名和密码是 `admin/prom-operator`。你还可以在部署或升级 Chart 时替换凭证。 + + :::note + + 无论谁拥有密码，你都需要在部署了 Rancher Monitoring 的项目中至少具有管理服务或查看监控的权限才能访问 Grafana 实例。你还可以在部署或升级 Chart 时替换凭证。 + + ::: + +1. 使用 Grafana UI 创建仪表板。完成后，单击顶部导航菜单中的齿轮图标转到仪表板设置页面。在左侧导航菜单中，单击 **JSON Model**。 +1. 复制出现的 JSON 数据结构。 + +### 2. 使用 Grafana JSON 模型创建 ConfigMap + +在包含 Grafana 仪表板的命名空间中创建一个 ConfigMap（默认为 cattle-dashboards ）。 + +ConfigMap 与以下内容类似： + +```yaml +apiVersion: v1 +kind: ConfigMap +metadata: + labels: + grafana_dashboard: "1" + name: + namespace: cattle-dashboards # 如果不使用默认命名空间，则修改此值 +data: + .json: |- + +``` + +默认情况下，Grafana 配置为监控 `cattle-dashboards` 命名空间中带有 `grafana_dashboard` 标签的所有 ConfigMap。 + +要让 Grafana 监控所有命名空间中的 ConfigMap，请参阅[本节](#为-grafana-仪表板-configmap-配置命名空间)。 + +要在 Rancher UI 中创建 ConfigMap： + +1. 在左上角，单击 **☰ > 集群管理**。 +1. 在**集群**页面上，转到要可视化的集群，然后单击 **Explore**。 +1. 单击**更多资源 > 核心 > 配置映射**。 +1. 单击**创建**。 +1. 设置与上例类似的键值对。输入 `.json` 的值时，点击**从文件读取**并上传 JSON 数据模型。 +1. 单击**创建**。 + +**结果**：创建 ConfigMap 后，即使 Grafana pod 重启了，ConfigMap 也能显示在 Grafana UI 上并持久化。 + +无法在 Grafana UI 中删除或编辑使用 ConfigMap 持久化了的仪表板。 + +如果你在 Grafana UI 中删除仪表板，你将看到 "Dashboard cannot be deleted because it was provisioned" 的错误消息。如需删除仪表板，你需要删除 ConfigMap。 + +### 为 Grafana 仪表板 ConfigMap 配置命名空间 + +要让 Grafana 监控所有命名空间中的 ConfigMap，请在 `rancher-monitoring` Helm chart 中指定以下值： + +``` +grafana.sidecar.dashboards.searchNamespace=ALL +``` + +请注意，Monitoring Chart 用于添加 Grafana 仪表板的 RBAC 角色仅能让用户将仪表板添加到定义在 `grafana.dashboards.namespace` 中的命名空间，默认为 `cattle-dashboards`。 + + + + +:::note 先决条件： + +- 已安装 Monitoring 应用。 +- 你必须具有 cluster-admin ClusterRole 权限。 + +::: + +1. 在左上角，单击 **☰ > 集群管理**。 +1. 在**集群**页面上，转到要在其中配置 Grafana 命名空间的集群，然后单击 **Explore**。 +1. 在左侧导航栏中，单击**监控**。 +1. 点击 **Grafana**。 +1. 登录到 Grafana。请注意，Grafana 实例的默认 Admin 用户名和密码是 `admin/prom-operator`。你还可以在部署或升级 Chart 时替换凭证。 + + :::note + + 无论谁拥有密码，都需要 Rancher 的集群管理员权限才能访问 Grafana 实例。 + + ::: + +1. 转到要进行持久化的仪表板。在顶部导航菜单中，通过单击齿轮图标转到仪表板设置。 +1. 在左侧导航菜单中，单击 **JSON Model**。 +1. 复制出现的 JSON 数据结构。 +1. 在 `cattle-dashboards` 命名空间中创建一个 ConfigMap。ConfigMap 需要有 `grafana_dashboard: "1"` 标签。将 JSON 粘贴到 ConfigMap 中，格式如下例所示： + + ```yaml + apiVersion: v1 + kind: ConfigMap + metadata: + labels: + grafana_dashboard: "1" + name: + namespace: cattle-dashboards + data: + .json: |- + + ``` + +**结果**：创建 ConfigMap 后，即使 Grafana pod 重启了，ConfigMap 也能显示在 Grafana UI 上并持久化。 + +无法在 Grafana UI 中删除使用 ConfigMap 持久化了的仪表板。如果你在 Grafana UI 中删除仪表板，你将看到 "Dashboard cannot be deleted because it was provisioned" 的错误消息。如需删除仪表板，你需要删除 ConfigMap。 + +为防止在卸载 Monitoring v2 时删除持久化的仪表板，请将以下注释添加到 `cattle-dashboards` 命名空间： + +``` +helm.sh/resource-policy: "keep" +``` + + + + +## 已知问题 + +如果你的 Monitoring V2 版本是 v9.4.203 或更低版本，卸载 Monitoring chart 将同时删除 `cattle-dashboards` 命名空间，所有持久化的仪表板将被删除（除非命名空间带有注释 `helm.sh/resource-policy: "keep"`）。 + +Rancher 2.5.8 发布的新 Monitoring Chart 中默认添加了该注解，但使用早期 Rancher 版本的用户仍需手动应用该注释。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/advanced-user-guides/monitoring-alerting-guides/customize-grafana-dashboard.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/advanced-user-guides/monitoring-alerting-guides/customize-grafana-dashboard.md new file mode 100644 index 00000000000..6dd3a86e7eb --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/advanced-user-guides/monitoring-alerting-guides/customize-grafana-dashboard.md @@ -0,0 +1,38 @@ +--- +title: 自定义 Grafana 仪表板 +--- + +在本文中，你将学习通过自定义 Grafana 仪表板来显示特定容器的指标。 + +## 先决条件 + +在自定义 Grafana 仪表板之前，你必须先安装 `rancher-monitoring` 应用。 + +要查看指向外部监控 UI（包括 Grafana 仪表板）的链接，你至少需要一个 [project-member 角色](../../../integrations-in-rancher/monitoring-and-alerting/rbac-for-monitoring.md#具有-rancher-权限的用户)。 + +## 登录 Grafana + +1. 在 Rancher UI 中，转到要自定义的仪表板的集群。 +1. 在左侧导航栏中，单击**监控**。 +1. 单击 **Grafana**。Grafana 仪表板将在新选项卡中打开。 +1. 转到左下角的登录图标，然后单击 **Sign In**。 +1. 登录到 Grafana。Grafana 实例的默认 Admin 用户名和密码是 `admin/prom-operator`（无论谁拥有密码，都需要 Rancher 的集群管理员权限才能访问 Grafana 实例）。你还可以在部署或升级 Chart 时替换凭证。 + +## 获取支持 Grafana 面板的 PromQL 查询 + +对于任何面板，你可以单击标题并单击 **Explore** 以获取支持图形的 PromQL 查询。 + +例如，如果要获取 Alertmanager 容器的 CPU 使用率，点击 **CPU Utilization > Inspect**。 + +**Data** 选项卡将基础数据显示为时间序列，第一列是时间，第二列是 PromQL 查询结果。复制 PromQL 查询。 + +``` +(1 - (avg(irate({__name__=~"node_cpu_seconds_total|windows_cpu_time_total",mode="idle"}[5m])))) * 100 +``` + +然后，你可以在 Grafana 面板中修改查询，或使用该查询创建新的 Grafana 面板。 + +参考： + +- [编辑面板的 Grafana 文档](https://grafana.com/docs/grafana/latest/panels-visualizations/configure-panel-options/#edit-a-panel) +- [向仪表板添加面板的 Grafana 文档](https://grafana.com/docs/grafana/latest/panels-visualizations/panel-editor-overview) diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/advanced-user-guides/monitoring-alerting-guides/debug-high-memory-usage.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/advanced-user-guides/monitoring-alerting-guides/debug-high-memory-usage.md new file mode 100644 index 00000000000..40a32dbadab --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/advanced-user-guides/monitoring-alerting-guides/debug-high-memory-usage.md @@ -0,0 +1,19 @@ +--- +title: 调试高内存用量 +--- + +Prometheus 中的每个时间序列都由其[指标名称](https://prometheus.io/docs/practices/naming/#metric-names)和称为[标签](https://prometheus.io/docs/practices/naming/#labels)的可选键值对唯一标识。 + +标签允许过滤和聚合时间序列数据，但它们也使 Prometheus 收集的数据量成倍增加。 + +每个时间序列都有一组定义的标签，Prometheus 为所有唯一的标签组合生成一个新的时间序列。如果一个指标附加了两个标签，则会为该指标生成两个时间序列。更改任何标签值，包括添加或删除标签，都会创建一个新的时间序列。 + +Prometheus 经过了优化，可以存储基于索引的序列数据。它是为相对一致的时间序列数量和相对大量的样本而设计的，这些样本需要随时间从 exporter 处收集。 + +但是，Prometheus 没有就快速变化的时间序列数量进行对应的优化。因此，如果你在创建和销毁了大量资源的集群（尤其是多租户集群）上安装 Monitoring，可能会出现内存使用量激增的情况。 + +## 减少内存激增 + +为了减少内存消耗，Prometheus 可以通过抓取更少的指标或在时间序列上添加更少的标签，从而存储更少的时间序列。要查看使用内存最多的序列，你可以查看 Prometheus UI 中的 TSDB（时序数据库）状态页面。 + +分布式 Prometheus 解决方案（例如 [Thanos](https://thanos.io/) 和 [Cortex](https://cortexmetrics.io/)）使用了一个替代架构，该架构部署多个小型 Prometheus 实例。如果使用 Thanos，每个 Prometheus 的指标都聚合到通用的 Thanos 部署中，然后再将这些指标导出到 S3 之类的持久存储。这种架构更加健康，能避免给单个 Prometheus 实例带来过多时间序列，同时还能在全局级别查询指标。 \ No newline at end of file diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/advanced-user-guides/monitoring-alerting-guides/enable-monitoring.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/advanced-user-guides/monitoring-alerting-guides/enable-monitoring.md new file mode 100644 index 00000000000..d6d6e2797ee --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/advanced-user-guides/monitoring-alerting-guides/enable-monitoring.md @@ -0,0 +1,67 @@ +--- +title: 启用 Monitoring +--- + +[管理员](../../new-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/global-permissions.md)或[集群所有者](../../new-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/cluster-and-project-roles.md#集群角色)可以通过配置 Rancher 来部署 Prometheus，从而监控 Kubernetes 集群。 + +本文介绍如何使用新的 monitoring 应用在集群内启用监控和告警。 + +不论是否使用 SSL，你都可以启用 monitoring。 + +## 要求 + +- 在每个节点上允许端口 9796 上的流量。Prometheus 将从这些端口抓取指标。 + - 如果 [PushProx](../../../integrations-in-rancher/monitoring-and-alerting/how-monitoring-works.md#pushprox) 被禁用（`ingressNginx.enabled` 设置为 `false`），或者你已经升级了安装了 Monitoring V1 的 Rancher 版本，你可能还需要为每个节点允许端口 10254 上的流量。 +- 确保你的集群满足资源要求。集群应至少有 1950Mi 可用内存、2700m CPU 和 50Gi 存储。有关资源限制和请求的详细信息，请参阅[配置资源限制和请求](../../../reference-guides/monitoring-v2-configuration/helm-chart-options.md#配置资源限制和请求)。 + +:::note + +如果要设置 Alertmanager、Grafana 或 Ingress，必须通过 Helm chart 部署上的设置来完成。在部署之外创建 Ingress 可能会产生问题。 + +::: + +## 设置资源限制和请求 + +安装 `rancher-monitoring` 时可以配置资源请求和限制。要从 Rancher UI 配置 Prometheus 资源，请单击左上角的 **Apps > Monitoring**。 + +有关默认限制的更多信息，请参阅[此页面](../../../reference-guides/monitoring-v2-configuration/helm-chart-options.md#配置资源限制和请求)。 + +## 安装 Monitoring 应用 + +### 在不使用 SSL 的情况下启用 Monitoring + +1. 点击 **☰ > 集群管理**。 +1. 选择你创建的集群，并点击 **Explore**。 +1. 点击**集群工具**（左下角）。 +1. 单击 Monitoring 的**安装**。 +1. 可选：在 Values 步骤中为 Alerting、Prometheus 和 Grafana 自定义请求、限制等。如需帮助，请参阅[配置参考](../../../reference-guides/monitoring-v2-configuration/helm-chart-options.md)。 + +**结果**：Monitoring 应用已部署到 `cattle-monitoring-system` 命名空间中。 + +### 在使用 SSL 的情况下启用 Monitoring + +1. 按照[此页面](../../new-user-guides/kubernetes-resources-setup/secrets.md)上的步骤创建密文，以便将 SSL 用于告警。 +- 密文应该创建到 `cattle-monitoring-system` 命名空间中。如果它不存在，请先创建它。 +- 将 `ca`、`cert` 和 `key` 文件添加到密文中。 +1. 在左上角，单击 **☰ > 集群管理**。 +1. 在**集群**页面上，转到要启用 Monitoring 以与 SSL 一起使用的集群，然后单击 **Explore**。 +1. 单击 **Apps > Charts**。 +1. 单击 **Monitoring**。 +1. 根据你是否已安装 Monitoring，单击**安装**或**更新**。 +1. 选中**在安装前自定义 Helm 选项**，然后单击**下一步**。 +1. 单击 **Alerting**。 +1. 在**补充密文**字段中，添加之前创建的密文。 + +**结果**：Monitoring 应用已部署到 `cattle-monitoring-system` 命名空间中。 + +[创建接收器](../../../reference-guides/monitoring-v2-configuration/receivers.md#在-rancher-ui-中创建接收器)时，启用 SSL 的接收器（例如电子邮件或 webhook）将具有 **SSL**，其中包含 **CA 文件路径**、**证书文件路径**和**密钥文件路径**字段。使用 `ca`、`cert` 和 `key` 的路径填写这些字段。路径的格式为 `/etc/alertmanager/secrets/name-of-file-in-secret`。 + +例如，如果你使用以下键值对创建了一个密文： + +```yaml +ca.crt=`base64-content` +cert.pem=`base64-content` +key.pfx=`base64-content` +``` + +则**证书文件路径**需要设为 `/etc/alertmanager/secrets/cert.pem`。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/advanced-user-guides/monitoring-alerting-guides/monitoring-alerting-guides.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/advanced-user-guides/monitoring-alerting-guides/monitoring-alerting-guides.md new file mode 100644 index 00000000000..16a504ae226 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/advanced-user-guides/monitoring-alerting-guides/monitoring-alerting-guides.md @@ -0,0 +1,15 @@ +--- +title: Monitoring/Alerting 指南 +--- + + + + + +- [启用 Monitoring](enable-monitoring.md) +- [卸载 Monitoring](uninstall-monitoring.md) +- [为工作负载设置 Monitoring](set-up-monitoring-for-workloads.md) +- [自定义 Grafana 仪表板](customize-grafana-dashboard.md) +- [持久化 Grafana 仪表板](create-persistent-grafana-dashboard.md) +- [调试高内存用量](debug-high-memory-usage.md) + diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/advanced-user-guides/monitoring-alerting-guides/prometheus-federator-guides/customize-grafana-dashboards.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/advanced-user-guides/monitoring-alerting-guides/prometheus-federator-guides/customize-grafana-dashboards.md new file mode 100644 index 00000000000..44d69d05f9e --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/advanced-user-guides/monitoring-alerting-guides/prometheus-federator-guides/customize-grafana-dashboards.md @@ -0,0 +1,7 @@ +--- +title: 自定义 Grafana 仪表板 +--- + +无论是用于 rancher-monitoring 还是 Prometheus Federator，Grafana 仪表板的定制方式都是相同的。 + +有关说明，请参阅[此页面](../customize-grafana-dashboard.md)。 \ No newline at end of file diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/advanced-user-guides/monitoring-alerting-guides/prometheus-federator-guides/enable-prometheus-federator.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/advanced-user-guides/monitoring-alerting-guides/prometheus-federator-guides/enable-prometheus-federator.md new file mode 100644 index 00000000000..ed318fe4724 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/advanced-user-guides/monitoring-alerting-guides/prometheus-federator-guides/enable-prometheus-federator.md @@ -0,0 +1,86 @@ +--- +title: 启用 Prometheus Federator +--- + +## 要求 + +默认情况下，Prometheus Federator 已配置并旨在与 [rancher-monitoring](../../../../integrations-in-rancher/monitoring-and-alerting/monitoring-and-alerting.md) 一起部署。rancher-monitoring 同时部署了 Prometheus Operator 和 Cluster Prometheus，每个项目监控堆栈（Project Monitoring Stack）默认会联合命名空间范围的指标。 + +有关安装 rancher-monitoring 的说明，请参阅[此页面](../enable-monitoring.md)。 + +默认配置与你的 rancher-monitoring 堆栈是兼容的。但是，为了提高集群中 Prometheus Federator 的安全性和可用性，我们建议对 rancher-monitoring 进行以下额外的配置： + +- [确保 cattle-monitoring-system 命名空间位于 System 项目中](#确保-cattle-monitoring-system-命名空间位于-system-项目中或者位于一个锁定并能访问集群中其他项目的项目中) +- [将 rancher-monitoring 配置为仅监视 Helm Chart 创建的资源](#将-rancher-monitoring-配置为仅监视-helm-chart-创建的资源) +- [提高 Cluster Prometheus 的 CPU/内存限制](#提高-cluster-prometheus-的-cpu内存限制) + +### 确保 cattle-monitoring-system 命名空间位于 System 项目中（或者位于一个锁定并能访问集群中其他项目的项目中） + +![选择项目/命名空间](/img/install-in-system-project.png) + +Prometheus Operator 的安全模型有一定的要求，即希望部署它的命名空间（例如，`cattle-monitoring-system`）对除集群管理员之外的任何用户都只有有限的访问权限，从而避免通过 Pod 内执行（例如正在执行的 Helm 操作的 Job）来提升权限。此外，如果将 Prometheus Federator 和所有 Project Prometheus 堆栈都部署到 System 项目中，即使网络策略是通过项目网络隔离定义的，每个 Project Prometheus 都依然能够在所有项目中抓取工作负载。它还为项目所有者、项目成员和其他用户提供有限的访问权限，从而确保这些用户无法访问他们不应访问的数据（例如，在 pod 中执行，在项目外部抓取命名空间数据等）。 + +1. 打开 `System` 项目以检查你的命名空间： + + 在 Rancher UI 中单击 **Cluster > Projects/Namespaces**。这将显示 `System` 项目中的所有命名空间： + + ![选择项目/命名空间](/img/cattle-monitoring-system.png) + +1. 如果你在 `cattle-monitoring-system` 命名空间中已经安装了一个 Monitoring V2，但该命名空间不在 `System` 项目中，你可以将 `cattle- monitoring-system` 命名空间移动到 `System` 项目或另一个访问受限的项目中。为此，你有以下两种方法： + + - 将命名空间拖放到 `System` 项目。 + - 选择命名空间右侧的 **⋮**，点击 **Move**，然后从 **Target Project** 下拉列表中选择 `System`： + + ![移至新项目](/img/move-to-new-project.png) + +### 将 rancher-monitoring 配置为仅监视 Helm Chart 创建的资源 + +每个项目监控堆栈都会监视其他命名空间并收集其他自定义工作负载指标或仪表板。因此，我们建议在所有选择器上配置以下设置，以确保 Cluster Prometheus 堆栈仅监控由 Helm Chart 创建的资源： + +``` +matchLabels: + release: "rancher-monitoring" +``` + +建议为以下选择器字段赋予此值： +- `.Values.alertmanager.alertmanagerSpec.alertmanagerConfigSelector` +- `.Values.prometheus.prometheusSpec.serviceMonitorSelector` +- `.Values.prometheus.prometheusSpec.podMonitorSelector` +- `.Values.prometheus.prometheusSpec.ruleSelector` +- `.Values.prometheus.prometheusSpec.probeSelector` + +启用此设置后，你始终可以通过向它们添加 `release: "rancher-monitoring"` 标签来创建由 Cluster Prometheus 抓取的 ServiceMonitor 或 PodMonitor。在这种情况下，即使这些 ServiceMonitor 或 PodMonitor 所在的命名空间不是 System 命名空间，项目监控堆栈也会默认自动忽略它们。 + +:::note + +如果你不希望用户能够在 Project 命名空间中创建聚合到 Cluster Prometheus 中的 ServiceMonitor 和 PodMonitor，你可以另外将 Chart 上的 namespaceSelectors 设置为仅目标 System 命名空间（必须包含 `cattle-monitoring-system` 和 `cattle-dashboards`，默认情况下资源通过 rancher-monitoring 部署到该命名空间中。你还需要监控 `default` 命名空间以获取 apiserver 指标，或创建自定义 ServiceMonitor 以抓取位于 `default` 命名空间中的 Service 的 apiserver 指标），从而限制你的 Cluster Prometheus 获取其他 Prometheus Operator CR。在这种情况下，建议设置 `.Values.prometheus.prometheusSpec.ignoreNamespaceSelectors=true`。这样，你可以定义能从 System 命名空间中监视非 System 命名空间的 ServiceMonitor。 + +::: + +### 提高 Cluster Prometheus 的 CPU/内存限制 + +根据集群的设置，我们一般建议为 Cluster Prometheus 配置大量的专用内存，以避免因内存不足的错误（OOMKilled）而重启。通常情况下，集群中创建的改动项（churn）会导致大量高基数指标在一个时间块内生成并被 Prometheus 引入，然后导致这些错误。这也是为什么默认的 Rancher Monitoring 堆栈希望能分配到大约 4GB 的 RAM 以在正常大小的集群中运行的原因之一。但是，如果你引入向同一个 Cluster Prometheus 发送 `/federate` 请求的项目监控堆栈，并且项目监控堆栈依赖于 Cluster Prometheus 的启动状态来在其命名空间上联合系统数据，那么你更加需要为 Cluster Prometheus 分配足够的 CPU/内存，以防止集群中的所有 Prometheus 项目出现数据间隙的中断。 + +:::note + +我们没有 Cluster Prometheus 内存配置的具体建议，因为这完全取决于用户的设置（即遇到高改动率的可能性以及可能同时生成的指标的规模）。不同的设置通常有不同的推荐参数。 + +::: + +## 安装 Prometheus Federator 应用程序 + +1. 点击 **☰ > 集群管理**。 +1. 转到要安装 Prometheus Federator 的集群，然后单击 **Explore**。 +1. 点击**应用 > Charts**。 +1. 单击 **Prometheus Federator** Chart。 +1. 单击**安装**。 +1. 在**元数据**页面，点击**下一步**。 +1. 在**命名空间** > **项目 Release 命名空间项目 ID** 字段中，`System 项目`是默认值，但你可以使用具有类似[有限访问权限](#确保-cattle-monitoring-system-命名空间位于-system-项目中或者位于一个锁定并能访问集群中其他项目的项目中)的另一个项目覆盖它。你可以在 local 上游集群中运行以下命令来找到项目 ID： + +```plain +kubectl get projects -A -o custom-columns="NAMESPACE":.metadata.namespace,"ID":.metadata.name,"NAME":.spec.displayName +``` + +1. 单击**安装**。 + +**结果**：Prometheus Federator 应用程序已部署在 `cattle-monitoring-system` 命名空间中。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/advanced-user-guides/monitoring-alerting-guides/prometheus-federator-guides/project-monitors.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/advanced-user-guides/monitoring-alerting-guides/prometheus-federator-guides/project-monitors.md new file mode 100644 index 00000000000..9dba3d6d401 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/advanced-user-guides/monitoring-alerting-guides/prometheus-federator-guides/project-monitors.md @@ -0,0 +1,17 @@ +--- +title: 安装 Project Monitor +--- + +在要启用项目监控的各个项目中安装 **Project Monitor**。 + +1. 点击 **☰ > 集群管理**。 + +1. 在**集群**页面中，转到要启用监控的集群，然后单击 **Explore**。 + +1. 单击左侧导航栏上的**监控 > Project Monitor**。然后，点击右上角的**创建**。 + + ![Project Monitor](/img/project-monitors.png) + +1. 从下拉菜单中选择你的项目，然后再次单击**创建**。 + + ![创建 Project Monitor](/img/create-project-monitors.png) diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/advanced-user-guides/monitoring-alerting-guides/prometheus-federator-guides/prometheus-federator-guides.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/advanced-user-guides/monitoring-alerting-guides/prometheus-federator-guides/prometheus-federator-guides.md new file mode 100644 index 00000000000..7bc98a902e4 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/advanced-user-guides/monitoring-alerting-guides/prometheus-federator-guides/prometheus-federator-guides.md @@ -0,0 +1,12 @@ +--- +title: Prometheus Federator 指南 +--- + + + + + +- [启用 Prometheus Federator](enable-prometheus-federator.md) +- [卸载 Prometheus Federator](uninstall-prometheus-federator.md) +- [自定义 Grafana 仪表板](customize-grafana-dashboards.md) +- [为工作负载设置 Prometheus Federator](set-up-workloads.md) \ No newline at end of file diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/advanced-user-guides/monitoring-alerting-guides/prometheus-federator-guides/set-up-workloads.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/advanced-user-guides/monitoring-alerting-guides/prometheus-federator-guides/set-up-workloads.md new file mode 100644 index 00000000000..ce1ad698b1b --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/advanced-user-guides/monitoring-alerting-guides/prometheus-federator-guides/set-up-workloads.md @@ -0,0 +1,13 @@ +--- +title: 为工作负载设置 Prometheus Federator +--- + +## 显示工作负载的 CPU 和内存指标 + +使用 Prometheus Federator 显示 CPU 和内存指标的方式与使用 rancher-monitoring 相同。有关说明，请参阅[此处](../set-up-monitoring-for-workloads.md#显示工作负载的-cpu-和内存指标)。 + +## 设置 CPU 和内存之外的指标 + +使用 Prometheus Federator 设置 CPU 和内存之外的指标与使用 rancher-monitoring 的方式相同。有关说明，请参阅[此处](../set-up-monitoring-for-workloads.md#设置-cpu-和内存之外的指标)。 + + diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/advanced-user-guides/monitoring-alerting-guides/prometheus-federator-guides/uninstall-prometheus-federator.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/advanced-user-guides/monitoring-alerting-guides/prometheus-federator-guides/uninstall-prometheus-federator.md new file mode 100644 index 00000000000..c6b04a736bb --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/advanced-user-guides/monitoring-alerting-guides/prometheus-federator-guides/uninstall-prometheus-federator.md @@ -0,0 +1,13 @@ +--- +title: 卸载 Prometheus Federator +--- + +1. 点击 **☰ > 集群管理**。 +1. 选择你创建的集群，并点击 **Explore**。 +1. 在左侧导航栏中，点击 **Apps**。 +1. 点击**已安装的应用**。 +1. 转到 `cattle-monitoring-system` 命名空间并选中 `rancher-monitoring-crd` 和 `rancher-monitoring`。 +1. 单击**删除**。 +1. 确认**删除**。 + +**结果**：已卸载 `prometheus-federator`。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/advanced-user-guides/monitoring-alerting-guides/set-up-monitoring-for-workloads.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/advanced-user-guides/monitoring-alerting-guides/set-up-monitoring-for-workloads.md new file mode 100644 index 00000000000..f81aa879d86 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/advanced-user-guides/monitoring-alerting-guides/set-up-monitoring-for-workloads.md @@ -0,0 +1,27 @@ +--- +title: 为工作负载设置 Monitoring +--- + +如果你只需要工作负载的 CPU 和内存时间序列，则不需要部署 ServiceMonitor 或 PodMonitor，因为 Monitoring 应用默认会收集资源使用情况的指标数据。 + +设置工作负载监控的步骤取决于你是否需要基本指标（例如工作负载的 CPU 和内存），或者是否需要从工作负载中抓取自定义指标。 + +如果你只需要工作负载的 CPU 和内存时间序列，则不需要部署 ServiceMonitor 或 PodMonitor，因为 Monitoring 应用默认会收集资源使用情况的指标数据。资源使用的时间序列数据在 Prometheus 的本地时间序列数据库中。 + +Grafana 显示聚合数据，你也可以使用 PromQL 查询来查看单个工作负载的数据。进行 PromQL 查询后，你可以在 Prometheus UI 中单独执行查询并查看可视化的时间序列，你也可以使用查询来自定义显示工作负载指标的 Grafana 仪表板。有关工作负载指标的 PromQL 查询示例，请参阅[本节](../../../integrations-in-rancher/monitoring-and-alerting/promql-expressions.md#工作负载指标)。 + +要为你的工作负载设置自定义指标，你需要设置一个 Exporter 并创建一个新的 ServiceMonitor 自定义资源，从而将 Prometheus 配置为从 Exporter 中抓取指标。 + +## 显示工作负载的 CPU 和内存指标 + +默认情况下，Monitoring 应用会抓取 CPU 和内存指标。 + +要获取特定工作负载的细粒度信息，你可以自定义 Grafana 仪表板来显示该工作负载的指标。 + +## 设置 CPU 和内存之外的指标 + +对于自定义指标，你需要使用 Prometheus 支持的格式来公开应用上的指标。 + +我们建议你创建一个新的 ServiceMonitor 自定义资源。创建此资源时，Prometheus 自定义资源将自动更新，以便将新的自定义指标端点包含在抓取配置中。然后 Prometheus 会开始从端点抓取指标。 + +你还可以创建 PodMonitor 来公开自定义指标端点，但 ServiceMonitor 更适合大多数用例。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/advanced-user-guides/monitoring-alerting-guides/uninstall-monitoring.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/advanced-user-guides/monitoring-alerting-guides/uninstall-monitoring.md new file mode 100644 index 00000000000..06845311909 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/advanced-user-guides/monitoring-alerting-guides/uninstall-monitoring.md @@ -0,0 +1,19 @@ +--- +title: 卸载 Monitoring +--- + +1. 点击 **☰ > 集群管理**。 +1. 选择你创建的集群，并点击 **Explore**。 +1. 在左侧导航栏中，点击 **Apps**。 +1. 点击**已安装的应用**。 +1. 转到 `cattle-monitoring-system` 命名空间并选中 `rancher-monitoring-crd` 和 `rancher-monitoring`。 +1. 单击**删除**。 +1. 确认**删除**。 + +**结果**：已卸载 `rancher-monitoring`。 + +:::note 持久化 Grafana 仪表板： + +如果你的 Monitoring V2 版本是 v9.4.203 或更低版本，卸载 Monitoring chart 将同时删除 cattle-dashboards 命名空间，所有持久化的仪表板将被删除（除非命名空间带有注释 `helm.sh/resource-policy: "keep"`）。Monitoring V2 v14.5.100+ 会默认添加此注释。但如果你的集群上安装了旧版本的 Monitoring Chart，你可以在卸载它之前手动将注释应用到 cattle-dashboards 命名空间。 + +::: \ No newline at end of file diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/advanced-user-guides/monitoring-v2-configuration-guides/advanced-configuration/advanced-configuration.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/advanced-user-guides/monitoring-v2-configuration-guides/advanced-configuration/advanced-configuration.md new file mode 100644 index 00000000000..388da060f7a --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/advanced-user-guides/monitoring-v2-configuration-guides/advanced-configuration/advanced-configuration.md @@ -0,0 +1,19 @@ +--- +title: 高级配置 +--- + + + + + +## Alertmanager + +有关配置 Alertmanager 自定义资源的信息，请参阅[此页面。](alertmanager.md) + +## Prometheus + +有关配置 Prometheus 自定义资源的信息，请参阅[此页面。](prometheus.md) + +## PrometheusRules + +有关配置 PrometheusRules 自定义资源的信息，请参阅[此页面。](prometheusrules.md) diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/advanced-user-guides/monitoring-v2-configuration-guides/advanced-configuration/alertmanager.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/advanced-user-guides/monitoring-v2-configuration-guides/advanced-configuration/alertmanager.md new file mode 100644 index 00000000000..77851a3accb --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/advanced-user-guides/monitoring-v2-configuration-guides/advanced-configuration/alertmanager.md @@ -0,0 +1,43 @@ +--- +title: Alertmanager 配置 +--- + +通常情况下，你不需要直接编辑 Alertmanager 自定义资源。对于大多数用例，只需要编辑接收器和路由即可配置通知。 + +当路由和接收器更新时，Monitoring 应用将自动更新 Alertmanager 自定义资源来与这些更改保持一致。 + +:::note + +本节参考假设你已经熟悉 Monitoring 组件的协同工作方式。有关 Alertmanager 的详细信息，请参阅[本节](../../../../integrations-in-rancher/monitoring-and-alerting/how-monitoring-works.md#3-alertmanager-的工作原理)。 + +::: + +## 关于 Alertmanager 自定义资源 + +默认情况下，Rancher Monitoring 将单个 Alertmanager 部署到使用默认 Alertmanager Config Secret 的集群上。 + +如果你想使用 Rancher UI 表单中未公开的高级选项（例如创建超过两层深的路由树结构），你可能需要编辑 Alertmanager 自定义资源。 + +你也可以在集群中创建多个 Alertmanager 来实现命名空间范围的监控。在这种情况下，你应该使用相同的底层 Alertmanager Config Secret 来管理 Alertmanager 自定义资源。 + +### 深度嵌套的路由 + +虽然 Rancher UI 仅支持两层深度的路由树，但你可以通过编辑 Alertmanager YAML 来配置更深的嵌套路由结构。 + +### 多个 Alertmanager 副本 + +作为 Chart 部署选项的一部分，你可以选择增加部署到集群上的 Alertmanager 副本的数量。这些副本使用相同的底层 Alertmanager Config Secret 进行管理。 + +此 Secret 可以按照你的需求随时更新或修改： + +- 添加新的通知程序或接收器 +- 更改应该发送给指定通知程序或接收器的告警 +- 更改发出的告警组 + +默认情况下，你可以选择提供现有的 Alertmanager Config Secret（即 `cattle-monitoring-system` 命名空间中的任何 Secret），或允许 Rancher Monitoring 将默认的 Alertmanager Config Secret 部署到你的集群上。 + +默认情况下，在升级或卸载 `rancher-monitoring` Chart 时，Rancher 创建的 Alertmanager Config Secret 不会被修改或删除。这个限制可以防止用户在 Chart 上执行操作时丢失或覆盖他们的告警配置。 + +有关可以在 Alertmanager Config Secret 中指定的字段的更多信息，请查看 [Prometheus Alertmanager 文档](https://prometheus.io/docs/alerting/latest/alertmanager/)。 + +你可以在[此处](https://prometheus.io/docs/alerting/latest/configuration/#configuration-file)找到 Alertmanager 配置文件的完整规范及其内容。 \ No newline at end of file diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/advanced-user-guides/monitoring-v2-configuration-guides/advanced-configuration/prometheus.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/advanced-user-guides/monitoring-v2-configuration-guides/advanced-configuration/prometheus.md new file mode 100644 index 00000000000..b83ad90b748 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/advanced-user-guides/monitoring-v2-configuration-guides/advanced-configuration/prometheus.md @@ -0,0 +1,19 @@ +--- +title: Prometheus 配置 +--- + +通常情况下，你不需要直接编辑 Prometheus 自定义资源，因为 Monitoring 应用会根据 ServiceMonitor 和 PodMonitor 的更改自动更新资源。 + +:::note + +本节参考假设你已经熟悉 Monitoring 组件的协同工作方式。有关详细信息，请参阅[本节](../../../../integrations-in-rancher/monitoring-and-alerting/how-monitoring-works.md)。 + +::: + +## 关于 Prometheus 自定义资源 + +Prometheus CR 定义了所需的 Prometheus deployment。Prometheus Operator 会观察 Prometheus CR。当 CR 发生变化时，Prometheus Operator 会创建 `prometheus-rancher-monitoring-prometheus`，即根据 CR 配置的 Prometheus deployment。 + +Prometheus CR 指定了详细信息，例如规则以及连接到 Prometheus 的 Alertmanager。Rancher 会为你构建这个 CR。 + +Monitoring V2 仅支持每个集群一个 Prometheus。如果你想将监控限制到指定命名空间，你需要编辑 Prometheus CR。 \ No newline at end of file diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/advanced-user-guides/monitoring-v2-configuration-guides/advanced-configuration/prometheusrules.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/advanced-user-guides/monitoring-v2-configuration-guides/advanced-configuration/prometheusrules.md new file mode 100644 index 00000000000..5519e6c56cb --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/advanced-user-guides/monitoring-v2-configuration-guides/advanced-configuration/prometheusrules.md @@ -0,0 +1,80 @@ +--- +title: PrometheusRule 配置 +--- + +PrometheusRule 定义了一组 Prometheus 告警和/或记录规则。 + +:::note + +本节参考假设你已经熟悉 Monitoring 组件的协同工作方式。有关详细信息，请参阅[本节](../../../../integrations-in-rancher/monitoring-and-alerting/how-monitoring-works.md)。 + +::: + +## 在 Rancher UI 中创建 PrometheusRule + +:::note 先决条件： + +已安装 Monitoring 应用。 + +::: + +要在 Rancher UI 中创建规则组： + +1. 转到要创建规则组的集群。单击**监控 > 高级选项**，然后单击 **PrometheusRules**。 +1. 单击**创建**。 +1. 输入**组名称**。 +1. 配置规则。在 Rancher 的 UI 中，规则组需要包含告警规则或记录规则，但不能同时包含两者。如需获取填写表单的帮助，请参阅下方的配置选项。 +1. 单击**创建**。 + +**结果**：告警可以向接收器发送通知。 + +## 关于 PrometheusRule 自定义资源 + +当你定义规则时（在 PrometheusRule 资源的 RuleGroup 中声明），[规则本身的规范](https://github.com/prometheus-operator/prometheus-operator/blob/main/Documentation/api-reference/api.md#rule)会包含标签，然后 Alertmanager 会使用这些标签来确定接收此告警的路由。例如，标签为 `team: front-end` 的告警将​​发送到与该标签匹配的所有路由。 + +Prometheus 规则文件保存在 PrometheusRule 自定义资源中。PrometheusRule 支持定义一个或多个 RuleGroup。每个 RuleGroup 由一组 Rule 对象组成，每个 Rule 对象均能表示告警或记录规则，并具有以下字段： + +- 新告警或记录的名称 +- 新告警或记录的 PromQL 表达式 +- 用于标记告警或记录的标签（例如集群名称或严重性） +- 对需要在告警通知上显示的其他重要信息进行编码的注释（例如摘要、描述、消息、Runbook URL 等）。记录规则不需要此字段。 + +有关可以指定的字段的更多信息，请查看 [Prometheus Operator 规范。](https://github.com/prometheus-operator/prometheus-operator/blob/main/Documentation/api-reference/api.md#prometheusrulespec) + +你可以使用 Prometheus 对象中的标签选择器字段 `ruleSelector` 来定义要挂载到 Prometheus 的规则文件。 + +如需查看示例，请参阅 Prometheus 文档中的[记录规则](https://prometheus.io/docs/prometheus/latest/configuration/recording_rules/)和[告警规则](https://prometheus.io/docs/prometheus/latest/configuration/alerting_rules/)。 + +## 配置 + +### 规则组 + +| 字段 | 描述 | +|-------|----------------| +| 组名称 | 组的名称。在规则文件中必须是唯一的。 | +| 覆盖组间隔 | 组中规则的评估时间间隔（单位：秒）。 | + + +### 告警规则 + +[告警规则](https://prometheus.io/docs/prometheus/latest/configuration/alerting_rules/)可以让你根据 PromQL（Prometheus 查询语言）表达式来定义告警条件，并将触发告警的通知发送到外部服务。 + +| 字段 | 描述 | +|-------|----------------| +| 告警名称 | 告警的名称。必须是有效的标签值。 | +| 告警触发等待时间 | 时长，以秒为单位。当告警触发时间到达该指定时长时，则视为触发。当告警未触发足够长的时间，则视为待处理。 | +| PromQL 表达式 | 要评估的 PromQL 表达式。Prometheus 将在每个评估周期评估此 PromQL 表达式的当前值，并且所有生成的时间序列都将成为待处理/触发告警。有关详细信息，请参阅 [Prometheus 文档](https://prometheus.io/docs/prometheus/latest/querying/basics/)或我们的 [PromQL 表达式示例](../../../../integrations-in-rancher/monitoring-and-alerting/promql-expressions.md)。 | +| Labels | 为每个告警添加或覆盖的标签。 | +| 严重程度 | 启用后，标签​​会附加到告警或记录中，这些标签通过严重程度来标识告警/记录。 | +| 严重程度 Label 值 | Critical，warning 或 none | +| 注释 | 注释是一组信息标签，可用于存储更长的附加信息，例如告警描述或 Runbook 链接。[Runbook](https://en.wikipedia.org/wiki/Runbook) 是一组有关如何处理告警的文档。注释值可以是[模板化](https://prometheus.io/docs/prometheus/latest/configuration/alerting_rules/#templating)的。 | + +### 记录规则 + +[记录规则](https://prometheus.io/docs/prometheus/latest/configuration/recording_rules/#recording-rules)允许你预先计算常用或计算量大的 PromQL（Prometheus 查询语言）表达式，并将其结果保存为一组新的时间序列。 + +| 字段 | 描述 | +|-------|----------------| +| 时间序列名称 | 要输出的时间序列的名称。必须是有效的指标名称。 | +| PromQL 表达式 | 要评估的 PromQL 表达式。Prometheus 将在每个评估周期评估此 PromQL 表达式的当前值，并且将结果记录为一组新的时间序列，其指标名称由“记录”指定。有关表达式的更多信息，请参阅 [Prometheus 文档](https://prometheus.io/docs/prometheus/latest/querying/basics/)或我们的 [PromQL 表达式示例](../../../../integrations-in-rancher/monitoring-and-alerting/promql-expressions.md)。 | +| Labels | 在存储结果之前要添加或覆盖的标签。 | diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/advanced-user-guides/monitoring-v2-configuration-guides/monitoring-v2-configuration-guides.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/advanced-user-guides/monitoring-v2-configuration-guides/monitoring-v2-configuration-guides.md new file mode 100644 index 00000000000..9521acfc95b --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/advanced-user-guides/monitoring-v2-configuration-guides/monitoring-v2-configuration-guides.md @@ -0,0 +1,55 @@ +--- +title: 配置 +--- + + + + + +本文介绍在 Rancher UI 中配置 Monitoring V2 的一些最重要选项。 + +有关为 Prometheus 配置自定义抓取目标和规则的信息，请参阅 [Prometheus Operator](https://github.com/prometheus-operator/prometheus-operator) 的上游文档。Prometheus Operator [设计文档](https://github.com/prometheus-operator/prometheus-operator/blob/main/Documentation/getting-started/design.md)中解释了一些最重要的自定义资源。Prometheus Operator 文档还可以帮助你设置 RBAC、Thanos 或进行自定义配置。 + +## 设置资源限制和请求 + +安装 `rancher-monitoring` 时可以配置 Monitoring 应用的资源请求和限制。有关默认限制的更多信息，请参阅[此页面](../../../reference-guides/monitoring-v2-configuration/helm-chart-options.md#配置资源限制和请求)。 + +:::tip + +在空闲集群上，Monitoring 可能会占用很多 CPU 资源。要提高性能，请关闭 Prometheus Adapter。 + +::: + +## Prometheus 配置 + +通常不需要直接编辑 Prometheus 自定义资源。 + +相反，要让 Prometheus 抓取自定义指标，你只需创建一个新的 ServiceMonitor 或 PodMonitor 来将 Prometheus 配置为抓取其他指标。 + +### ServiceMonitor 和 PodMonitor 配置 + +有关详细信息，请参阅[此页面](../../../reference-guides/monitoring-v2-configuration/servicemonitors-and-podmonitors.md)。 + +### 高级 Prometheus 配置 + +有关直接编辑 Prometheus 自定义资源（对高级用例可能有帮助）的更多信息，请参阅[此页面](advanced-configuration/prometheus.md)。 + +## Alertmanager 配置 + +Alertmanager 自定义资源通常不需要直接编辑。在常见用例中，你可以通过更新路由和接收器来管理告警。 + +路由和接收器是 Alertmanager 自定义资源配置的一部分。在 Rancher UI 中，路由（Route）和接收器（Receiver）并不是真正的自定义资源，而是 Prometheus Operator 用来将你的配置与 Alertmanager 自定义资源同步的伪自定义资源。当路由和接收器更新时，Monitoring 应用将自动更新 Alertmanager 来反映这些更改。 + +对于一些高级用例，你可能需要直接配置 Alertmanager。有关详细信息，请参阅[此页面](advanced-configuration/alertmanager.md)。 + +### 接收器 + +接收器（Receiver）用于设置通知。有关如何配置接收器的详细信息，请参阅[此页面](../../../reference-guides/monitoring-v2-configuration/receivers.md)。 + +### 路由 + +路由（Route）在通知到达接收器之前过滤它们。每条路由都需要引用一个已经配置好的接收器。有关如何配置路由的详细信息，请参阅[此页面](../../../reference-guides/monitoring-v2-configuration/routes.md)。 + +### 高级配置 + +有关直接编辑 Alertmanager 自定义资源（对高级用例可能有帮助）的更多信息，请参阅[此页面](advanced-configuration/alertmanager.md)。 \ No newline at end of file diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/advanced-user-guides/open-ports-with-firewalld.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/advanced-user-guides/open-ports-with-firewalld.md new file mode 100644 index 00000000000..bc9c0e68048 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/advanced-user-guides/open-ports-with-firewalld.md @@ -0,0 +1,107 @@ +--- +title: 使用 firewalld 打开端口 +--- + +> 我们建议禁用 firewalld。如果你使用的是 Kubernetes 1.19 或更高版本，则必须关闭 firewalld。 + +某些 [源自 RHEL](https://en.wikipedia.org/wiki/Red_Hat_Enterprise_Linux#Rebuilds) 的 Linux 发行版（包括 Oracle Linux）的默认防火墙规则可能会阻止与 Helm 的通信。 + +例如，AWS 中的一个 Oracle Linux 镜像具有 REJECT 规则，这些规则会阻止 Helm 与 Tiller 通信： + +``` +Chain INPUT (policy ACCEPT) +target prot opt source destination +ACCEPT all -- anywhere anywhere state RELATED,ESTABLISHED +ACCEPT icmp -- anywhere anywhere +ACCEPT all -- anywhere anywhere +ACCEPT tcp -- anywhere anywhere state NEW tcp dpt:ssh +REJECT all -- anywhere anywhere reject-with icmp-host-prohibited + +Chain FORWARD (policy ACCEPT) +target prot opt source destination +REJECT all -- anywhere anywhere reject-with icmp-host-prohibited + +Chain OUTPUT (policy ACCEPT) +target prot opt source destination +``` + +你可运行以下命令检查默认防火墙规则： + +``` +sudo iptables --list +``` + +下文介绍如何使用 `firewalld`，将[防火墙端口规则](../../getting-started/installation-and-upgrade/installation-requirements/installation-requirements.md#端口要求)应用到高可用 Rancher Server 集群中的节点。 + +## 先决条件 + +安装 v7.x 或更高版本的 `firewalld`： + +``` +yum install firewalld +systemctl start firewalld +systemctl enable firewalld +``` + +## 应用防火墙端口规则 + +在 Rancher 高可用安装中，Rancher Server 设置在三个节点上，三个节点均具有 Kubernetes 的所有三个角色（etcd、controlplane 和 worker）。如果你的 Rancher Server 节点同时具有这三个角色，请在每个节点上运行以下命令： + +``` +firewall-cmd --permanent --add-port=22/tcp +firewall-cmd --permanent --add-port=80/tcp +firewall-cmd --permanent --add-port=443/tcp +firewall-cmd --permanent --add-port=2376/tcp +firewall-cmd --permanent --add-port=2379/tcp +firewall-cmd --permanent --add-port=2380/tcp +firewall-cmd --permanent --add-port=6443/tcp +firewall-cmd --permanent --add-port=8472/udp +firewall-cmd --permanent --add-port=9099/tcp +firewall-cmd --permanent --add-port=10250/tcp +firewall-cmd --permanent --add-port=10254/tcp +firewall-cmd --permanent --add-port=30000-32767/tcp +firewall-cmd --permanent --add-port=30000-32767/udp +``` +如果你的 Rancher Server 节点配置了单独的角色，请根据节点角色运行以下命令： + +``` +# 在 etcd 节点上运行以下命令： +firewall-cmd --permanent --add-port=2376/tcp +firewall-cmd --permanent --add-port=2379/tcp +firewall-cmd --permanent --add-port=2380/tcp +firewall-cmd --permanent --add-port=8472/udp +firewall-cmd --permanent --add-port=9099/tcp +firewall-cmd --permanent --add-port=10250/tcp + +# 在 controlplane 节点上运行以下命令： +firewall-cmd --permanent --add-port=80/tcp +firewall-cmd --permanent --add-port=443/tcp +firewall-cmd --permanent --add-port=2376/tcp +firewall-cmd --permanent --add-port=6443/tcp +firewall-cmd --permanent --add-port=8472/udp +firewall-cmd --permanent --add-port=9099/tcp +firewall-cmd --permanent --add-port=10250/tcp +firewall-cmd --permanent --add-port=10254/tcp +firewall-cmd --permanent --add-port=30000-32767/tcp +firewall-cmd --permanent --add-port=30000-32767/udp + +# 在 worker 节点上运行以下命令： +firewall-cmd --permanent --add-port=22/tcp +firewall-cmd --permanent --add-port=80/tcp +firewall-cmd --permanent --add-port=443/tcp +firewall-cmd --permanent --add-port=2376/tcp +firewall-cmd --permanent --add-port=8472/udp +firewall-cmd --permanent --add-port=9099/tcp +firewall-cmd --permanent --add-port=10250/tcp +firewall-cmd --permanent --add-port=10254/tcp +firewall-cmd --permanent --add-port=30000-32767/tcp +firewall-cmd --permanent --add-port=30000-32767/udp +``` + +在节点上运行 `firewall-cmd` 命令后，使用以下命令启用防火墙规则： + +``` +firewall-cmd --reload +``` + +**结果**：防火墙已更新，因此 Helm 可以与 Rancher Server 节点通信了。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/advanced-user-guides/tune-etcd-for-large-installs.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/advanced-user-guides/tune-etcd-for-large-installs.md new file mode 100644 index 00000000000..3866f39db8e --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/advanced-user-guides/tune-etcd-for-large-installs.md @@ -0,0 +1,32 @@ +--- +title: 为大型安装进行 etcd 调优 +--- + +当你运行具有 15 个或更多集群的大型 Rancher 安装时，我们建议你扩大 etcd 的默认 keyspace（默认为 2GB）。你最大可以将它设置为 8GB。此外，请确保主机有足够的 RAM 来保存整个数据集。如果需要增加这个值，你还需要同步增加主机的大小。如果你预计在垃圾回收间隔期间 Pod 的变化率很高，你也可以在较小的安装中调整 Keyspace 大小。 + +Kubernetes 每隔五分钟会自动清理 etcd 数据集。在某些情况下（例如发生部署抖动），在垃圾回收发生并进行清理之前会有大量事件写入 etcd 并删除，从而导致 Keyspace 填满。如果你在 etcd 日志或 Kubernetes API Server 日志中看到 `mvcc: database space exceeded` 错误，你可以在 etcd 服务器上设置 [quota-backend-bytes](https://etcd.io/docs/v3.5/op-guide/maintenance/#space-quota) 来增加 Keyspace 的大小。 + +## 示例：此 RKE2/K3s config.yaml 文件的代码片段将 Keyspace 的大小增加到 5GB + +```yaml +# RKE2/K3s config.yaml +--- +etcd-arg: + - "quota-backend-bytes=5368709120" +``` + +## 扩展 etcd 磁盘性能 + +你可以参见 [etcd 文档](https://etcd.io/docs/v3.5/tuning/#disk)中的建议，了解如何调整主机上的磁盘优先级。 + +此外，为了减少 etcd 磁盘上的 IO 争用，你可以为 data 和 wal 目录使用专用设备。etcd 最佳实践不建议配置 Mirror RAID（因为 etcd 在集群中的节点之间复制数据）。你可以使用 striping RAID 配置来增加可用的 IOPS。 + +要在 RKE2/K3s 集群中实现此解决方案，你需要在底层主机上为 `/var/lib/etcd/data` 和 `/var/lib/etcd/wal` 目录挂载并格式化磁盘。`etcd` 服务的 `extra_args` 指令中必须包含 `wal_dir` 目录。如果不指定 `wal_dir`，etcd 进程会尝试在权限不足的情况下操作底层的 `wal` 挂载。 + +```yaml +# RKE2/K3s config.yaml +--- +etcd-arg: + - "data-dir=/var/lib/etcd/data" + - "wal-dir=/var/lib/etcd/wal" +``` diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/add-users-to-projects.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/add-users-to-projects.md new file mode 100644 index 00000000000..5f064ec685f --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/add-users-to-projects.md @@ -0,0 +1,70 @@ +--- +title: 添加项目成员 +--- + +如果你想为用户提供集群内 _特定_ 项目和资源的访问权限，请为用户分配项目成员资格。 + +你可以在创建项目时将成员添加到项目中，或将用户添加到现有项目中。 + +:::tip + +如果你需要为用户提供对集群内 _所有_ 项目的访问权限，请参见[添加集群成员](../../how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/cluster-and-project-roles.md)。 + +::: + +## 将成员添加到新项目 + +你可以在创建项目时将成员添加到项目中（建议）。有关创建新项目的详细信息，请参阅[集群管理](../../how-to-guides/new-user-guides/manage-clusters/projects-and-namespaces.md)。 + +## 将成员添加到现有项目 + +创建项目后，你可以将用户添加为项目成员，以便用户可以访问项目的资源： + +1. 在左上角，单击 **☰ > 集群管理**。 +1. 在**集群**页面上，转到要添加项目成员的集群，然后单击 **Explore**。 +1. 单击**集群 > 项目/命名空间**。 +1. 转到要添加成员的项目。在项目名称上方的**创建命名空间**按钮旁边，单击 **☰**。选择 **编辑配置**。 +1. 在**成员**选项卡中，单击**添加**。 +1. 搜索要添加到项目的用户或组。 + + :::note Notes: + + - At least 2 characters must be typed in the search box for results to appear. + - Users can be searched based on their username or display name. + - Search is prefix-based (e.g., a user named `Stan Dard` will appear when searching for `Sta`, but not when searching for `Dar`) and case-sensitive. + + ::: + + 如果配置了外部身份验证： + + - 在你键入时，Rancher 会从你的外部身份验证源返回用户。 + + - 你可以在下拉菜单中添加组，而不是单个用户。下拉列表仅会列出你（登录用户）所在的组。 + + :::note + + 如果你以本地用户身份登录，外部用户不会显示在你的搜索结果中。 + + ::: + +1. 分配用户或组的**项目**角色。 + + [什么是项目角色？](../../how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/cluster-and-project-roles.md) + + :::note 注意事项： + + - 如果用户分配到了项目的`所有者`或`成员`角色，用户会自动继承`命名空间创建`角色。然而，这个角色是 [Kubernetes ClusterRole](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#role-and-clusterrole)，这表示角色的范围会延展到集群中的所有项目。因此，对于显式分配到了项目`所有者`或`成员`角色的用户来说，即使只有`只读`角色，这些用户也可以在分配给他们的其他项目中创建或删除命名空间。 + + - 默认情况下，Rancher 的`项目成员`角色继承自 `Kubernetes-edit` 角色，而`项目所有者`角色继承自 `Kubernetes-admin` 角色。因此，`项目成员`和`项目所有者`角色都能管理命名空间，包括创建和删除命名空间。 + + - 对于`自定义`角色，你可以修改可分配的角色列表。 + + - 要将角色添加到列表中，请[添加自定义角色](../../how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/custom-roles.md)。 + - 要从列表中删除角色，请[锁定/解锁角色](../../how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/locked-roles.md)。 + + ::: + +**结果**：已将选中的用户添加到项目中。 + +- 要撤销项目成员资格，请选择用户并单击**删除**。此操作会删除成员资格，而不会删除用户。 +- 要修改项目中的用户角色，请将其从项目中删除，然后使用修改后的角色重新添加用户。 \ No newline at end of file diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/about-provisioning-drivers/about-provisioning-drivers.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/about-provisioning-drivers/about-provisioning-drivers.md new file mode 100644 index 00000000000..efcd02f34ba --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/about-provisioning-drivers/about-provisioning-drivers.md @@ -0,0 +1,45 @@ +--- +title: 配置驱动 +--- + + + + + +使用 Rancher 中的驱动，你可以管理可以使用哪些供应商来部署[托管的 Kubernetes 集群](../../kubernetes-clusters-in-rancher-setup/set-up-clusters-from-hosted-kubernetes-providers/set-up-clusters-from-hosted-kubernetes-providers.md)或[云服务器节点](../../launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/use-new-nodes-in-an-infra-provider.md)，以允许 Rancher 部署和管理 Kubernetes。 + +## Rancher 驱动 + +你可以启用或禁用 Rancher 中内置的驱动。如果相关驱动 Rancher 尚未实现，你可以添加自己的驱动。 + +Rancher 中有两种类型的驱动： + +* [集群驱动](#集群驱动) +* [主机驱动](#主机驱动) + +## 集群驱动 + +集群驱动用于配置[托管的 Kubernetes 集群](../../kubernetes-clusters-in-rancher-setup/set-up-clusters-from-hosted-kubernetes-providers/set-up-clusters-from-hosted-kubernetes-providers.md)，例如 GKE、EKS、AKS 等。创建集群时可以显示的集群驱动，是由集群驱动的状态定义的。只有 `active` 集群驱动将显示为为托管 Kubernetes 集群创建集群的选项。默认情况下，Rancher 与几个现有的集群驱动打包在一起，但你也可以创建自定义集群驱动并添加到 Rancher。 + +默认情况下，Rancher 已激活多个托管 Kubernetes 云提供商，包括： + +* [Amazon EKS](../../kubernetes-clusters-in-rancher-setup/set-up-clusters-from-hosted-kubernetes-providers/eks.md) +* [Google GKE](../../kubernetes-clusters-in-rancher-setup/set-up-clusters-from-hosted-kubernetes-providers/gke.md) +* [Azure AKS](../../kubernetes-clusters-in-rancher-setup/set-up-clusters-from-hosted-kubernetes-providers/aks.md) + +## 主机驱动 + +主机驱动用于配置主机，Rancher 使用这些主机启动和管理 Kubernetes 集群。主机驱动与 [Docker Machine 驱动](https://github.com/docker/docs/blob/vnext-engine/machine/drivers/index.md)相同。创建主机模板时可以显示的主机驱动，是由主机驱动的状态定义的。只有 `active` 主机驱动将显示为创建节点模板的选项。默认情况下，Rancher 与许多现有的 Docker Machine 驱动打包在一起，但你也可以创建自定义主机驱动并添加到 Rancher。 + +如果你不想向用户显示特定的主机驱动，则需要停用这些主机驱动。 + +Rancher 支持几家主要的云提供商，但默认情况下，这些主机驱动处于 active 状态并可供部署： + +* [Amazon EC2](../../launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/create-an-amazon-ec2-cluster.md) +* [Azure](../../launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/create-an-azure-cluster.md) +* [Digital Ocean](../../launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/create-a-digitalocean-cluster.md) +* [vSphere](../../launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/vsphere/vsphere.md) + +还有其他几个默认禁用的主机驱动，但打包在 Rancher 中： + +* [Harvester](../../../../integrations-in-rancher/harvester/overview.md#harvester-主机驱动) - 在 Rancher 2.6.1 中可用 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/about-provisioning-drivers/manage-cluster-drivers.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/about-provisioning-drivers/manage-cluster-drivers.md new file mode 100644 index 00000000000..8be4aa59fbb --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/about-provisioning-drivers/manage-cluster-drivers.md @@ -0,0 +1,41 @@ +--- +title: 集群驱动 +--- +集群驱动用于在[托管 Kubernetes 提供商](../../kubernetes-clusters-in-rancher-setup/set-up-clusters-from-hosted-kubernetes-providers/set-up-clusters-from-hosted-kubernetes-providers.md)（例如 Google GKE）中创建集群。创建集群时可以显示的集群驱动，是由集群驱动的状态定义的。只有 `active` 集群驱动将作为创建集群的选项显示。默认情况下，Rancher 与多个现有的云提供商集群驱动打包在一起，但你也可以将自定义集群驱动添加到 Rancher。 + +如果你不想向用户显示特定的集群驱动，你可以在 Rancher 中停用这些集群驱动，它们将不会作为创建集群的选项出现。 + +## 管理集群驱动 + +:::note 先决条件： + +要创建、编辑或删除集群驱动，你需要以下权限中的_一个_： + +- [管理员全局权限](../manage-role-based-access-control-rbac/global-permissions.md) +- 分配了[管理集群驱动角色](../manage-role-based-access-control-rbac/global-permissions.md)的[自定义全局权限](../manage-role-based-access-control-rbac/global-permissions.md#自定义全局权限)。 + +::: + +## 激活/停用集群驱动 + +默认情况下，Rancher 仅激活主流的云提供商 Google GKE、Amazon EKS 和 Azure AKS 的驱动。如果要显示或隐藏驱动，你可以更改驱动的状态： + +1. 在左上角，单击 **☰ > 集群管理**。 + +2. 在左侧导航菜单中，单击**驱动**。 + +3. 在**集群驱动**选项卡上，选择要激活或停用的驱动，然后单击 **⋮ > 激活** 或 **⋮ > 停用**。 + +## 添加自定义集群驱动 + +如果你想使用 Rancher 不支持开箱即用的集群驱动，你可以添加提供商的驱动，从而使用该驱动来创建 _托管_ Kubernetes 集群： + +1. 在左上角，单击 **☰ > 集群管理**。 +1. 在左侧导航菜单中，单击**驱动**。 +1. 在**集群驱动**选项卡上，单击**添加集群驱动**。 +1. 填写**添加集群驱动**表单。然后单击**创建**。 + + +## 开发自己的集群驱动 + +如果要开发集群驱动并添加到 Rancher，请参考我们的[示例](https://github.com/rancher-plugins/kontainer-engine-driver-example)。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/about-provisioning-drivers/manage-node-drivers.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/about-provisioning-drivers/manage-node-drivers.md new file mode 100644 index 00000000000..ee87c8732c3 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/about-provisioning-drivers/manage-node-drivers.md @@ -0,0 +1,41 @@ +--- +title: 主机驱动 +--- + +主机驱动用于配置主机，Rancher 使用这些主机启动和管理 Kubernetes 集群。主机驱动与 [Docker Machine 驱动](https://github.com/docker/docs/blob/vnext-engine/machine/drivers/index.md)相同。创建主机模板时可以显示的主机驱动，是由主机驱动的状态定义的。只有 `active` 主机驱动将显示为创建节点模板的选项。默认情况下，Rancher 与许多现有的 Docker Machine 驱动打包在一起，但你也可以创建自定义主机驱动并添加到 Rancher。 + +如果你不想向用户显示特定的主机驱动，则需要停用这些主机驱动。 + +## 管理主机驱动 + +:::note 先决条件： + +要创建、编辑或删除驱动，你需要以下权限中的_一个_： + +- [管理员全局权限](../manage-role-based-access-control-rbac/global-permissions.md) +- 分配了[管理主机驱动角色](../manage-role-based-access-control-rbac/global-permissions.md)的[自定义全局权限](../manage-role-based-access-control-rbac/global-permissions.md#自定义全局权限)。 + +::: + +## 激活/停用主机驱动 + +默认情况下，Rancher 仅激活主流云提供商 Amazon EC2、Azure、DigitalOcean 和 vSphere 的驱动。如果要显示或隐藏驱动，你可以更改驱动的状态： + +1. 在左上角，单击 **☰ > 集群管理**。 + +2. 在左侧导航菜单中，单击**驱动**。 + +2. 在**主机驱动**选项卡上，选择要激活或停用的驱动，然后单击 **⋮ > 激活** 或 **⋮ > 停用**。 + +## 添加自定义主机驱动 + +如果你想使用 Rancher 不支持开箱即用的主机驱动，你可以添加提供商的驱动，从而使用该驱动为你的 Kubernetes 集群创建节点模板并最终创建节点池： + +1. 在左上角，单击 **☰ > 集群管理**。 +1. 在左侧导航菜单中，单击**驱动**。 +1. 在**主机驱动**选项卡上，单击**添加主机驱动**。 +1. 填写**添加主机驱动**表单。然后单击**创建**。 + +## 开发自己的主机驱动 + +主机驱动使用 [Docker Machine](https://github.com/docker/docs/blob/vnext-engine/machine/overview.md) 来实现。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/about-rke1-templates.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/about-rke1-templates.md new file mode 100644 index 00000000000..aeef11c9c35 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/about-rke1-templates.md @@ -0,0 +1,133 @@ +--- +title: RKE 模板 +--- + + + + + + + + +RKE 模板旨在让 DevOps 和安全团队标准化和简化 Kubernetes 集群创建的流程。 + +RKE 的全称是 [Rancher Kubernetes Engine](https://rancher.com/docs/rke/latest/en/)，它是 Rancher 用来配置 Kubernetes 集群的工具。 + +随着 Kubernetes 越来越受欢迎，管理更多小型集群逐渐成为趋势。如果你想要创建大量集群，对集群进行一致管理尤为重要。多集群管理面临着安全和附件配置执行的挑战，在将集群移交给最终用户之前，这些配置需要标准化。 + +RKE 模板有助于标准化这些配置。无论是使用 Rancher UI、Rancher API 还是自动化流程创建的集群，Rancher 都将保证从 RKE 集群模板创建的每个集群在生成方式上是一致的。 + +管理员可以控制最终用户能更改的集群选项。RKE 模板还可以与特定的用户和组共享，以便管理员可以为不同的用户集创建不同的 RKE 模板。 + +如果集群是使用 RKE 模板创建的，则不能让集群使用另一个 RKE 模板。你只能将集群更新为同一模板的新版本。 + +你可以[将现有集群的配置保存为 RKE 模板](apply-templates.md#将现有集群转换为使用-rke-模板)。这样，只有模板更新后才能更改集群的设置。新模板还可用于启动新集群。 + +RKE 模板的核心功能允许 DevOps 和安全团队： + +- 标准化集群配置并确保按照最佳实践创建 Rancher 配置的集群 +- 配置集群时，防止用户做出不明智的选择 +- 与不同的用户和组共享不同的模板 +- 将模板的所有权委托给受信任的用户进行更改 +- 控制哪些用户可以创建模板 +- 要求用户使用模板来创建集群 + +## 可配置的设置 + +RKE 模板可以在 Rancher UI 中创建或以 YAML 格式定义。当你使用 Rancher 从基础设施提供商配置自定义节点或一般节点时，它们可以指定为相同的参数： + +- 云提供商选项 +- Pod 安全选项 +- 网络提供商 +- Ingress Controller +- 网络安全配置 +- 网络插件 +- 私有镜像仓库 URL 和凭证 +- 附加组件 +- Kubernetes 选项，包括 kube-api、kube-controller、kubelet 和服务等 Kubernetes 组件的配置 + +RKE 模板的[附加组件](#附加组件)的功能特别强大，因为它允许多种自定义选项。 + +## RKE 模板的范围 + +Rancher 配置的集群支持 RKE 模板。模板可用于配置自定义集群或由基础设施提供商启动的集群。 + +RKE 模板用于定义 Kubernetes 和 Rancher 设置。节点模板负责配置节点。有关如何将 RKE 模板与硬件结合使用的参考，请参阅 [RKE 模板和硬件](infrastructure.md)。 + +可以从头开始创建 RKE 模板来预先定义集群配置。它们可以用于启动新集群，也可以从现有的 RKE 集群导出模板。 + +现有集群的设置可以[保存为 RKE 模板](apply-templates.md#将现有集群转换为使用-rke-模板)。这会创建一个新模板并将集群设置绑定到该模板。这样，集群只有在[模板更新](manage-rke1-templates.md#更新模板)的情况下才能[使用新版本的模板](manage-rke1-templates.md#升级集群以使用新的模板修订版)进行升级。新模板也可以用来创建新集群。 + + +## 示例场景 +如果一个组织同时拥有普通和高级 Rancher 用户，管理员可能希望为高级用户提供更多用于集群创建的选项，并限制普通用户的选项。 + +这些[示例场景](example-use-cases.md)描述组织如何使用模板来标准化集群创建。 + +示例场景包括： + +- **强制执行模板**：如果希望所有 Rancher 配置的新集群都具有某些设置，管理员可能想要[为每个用户强制执行一项或多项模板设置](example-use-cases.md#强制执行模板设置)。 +- **与不同的用户共享不同的模板**：管理员可以为[普通用户和高级用户提供不同的模板](example-use-cases.md#普通用户和高级用户模板)。这样，普通用户会有更多限制选项，而高级用户在创建集群时可以使用更多选项。 +- **更新模板设置**：如果组织的安全和 DevOps 团队决定将最佳实践嵌入到新集群所需的设置中，这些最佳实践可能会随着时间而改变。如果最佳实践发生变化，[可以将模板更新为新版本](example-use-cases.md#更新模板和集群)，这样，使用模板创建的集群可以[升级到模板的新版本](manage-rke1-templates.md#升级集群以使用新的模板修订版)。 +- **共享模板的所有权**：当模板所有者不再想要维护模板或想要共享模板的所有权时，此方案描述了如何[共享模板所有权](example-use-cases.md#允许其他用户控制和共享模板)。 + +## 模板管理 + +创建 RKE 模板时，可以在 Rancher UI 中的**集群管理**下的 **RKE 模板**中使用模板。创建模板后，你将成为模板所有者，这将授予你修改和共享模板的权限。你可以与特定用户或组共享 RKE 模板，也可以公开模板。 + +管理员可以开启模板强制执行，要求用户在创建集群时始终使用 RKE 模板。这使管理员可以保证 Rancher 总是创建指定配置的集群。 + +RKE 模板更新通过修订系统处理。如果要更改或更新模板，请创建模板的新版本。然后，可以将使用旧版本模板创建的集群升级到新模板修订版。 + +在 RKE 模板中，模板所有者可以限制设置的内容，也可以打开设置以供最终用户选择值。它们的差别体现在，创建模板时，Rancher UI 中的每个设置上的**允许用户覆盖**标示。 + +对于无法覆盖的设置，最终用户将无法直接编辑它们。为了让用户使用这些设置的不同选项，RKE 模板所有者需要创建 RKE 模板的新版本，这将允许用户升级和更改该选项。 + +本节中的文件解释了 RKE 模板管理的细节： + +- [获取创建模板的权限](creator-permissions.md) +- [创建和修改模板](manage-rke1-templates.md) +- [强制执行模板设置](enforce-templates.md#强制新集群使用-rke-模板) +- [覆盖模板设置](override-template-settings.md) +- [与集群创建者共享模板](access-or-share-templates.md#与特定用户或组共享模板) +- [共享模板的所有权](access-or-share-templates.md#共享模板所有权) + +你可以参见此[模板的示例 YAML 文件](../../../../reference-guides/rke1-template-example-yaml.md)作为参考。 + +## 应用模板 + +你可以使用你自己创建的模板来[创建集群](apply-templates.md#使用-rke-模板创建集群)，也可以使用[与你共享的模板](access-or-share-templates.md)来创建集群。 + +如果 RKE 模板所有者创建了模板的新版本，你可以[将你的集群升级到该版本](apply-templates.md#更新使用-rke-模板创建的集群)。 + +可以从头开始创建 RKE 模板来预先定义集群配置。它们可以用于启动新集群，也可以从现有的 RKE 集群导出模板。 + +你可以[将现有集群的配置保存为 RKE 模板](apply-templates.md#将现有集群转换为使用-rke-模板)。这样，只有模板更新后才能更改集群的设置。 + +## 标准化硬件 + +RKE 模板的目的是标准化 Kubernetes 和 Rancher 设置。如果你还想标准化你的基础设施，一个选择是将 RKE 模板与[其他工具](infrastructure.md)一起使用。 + +另一种选择是使用包含节点池配置选项，但不强制执行配置的[集群模板](../../manage-clusters/manage-cluster-templates.md)。 + +## YAML 定制 + +如果将 RKE 模板定义为 YAML 文件，则可以修改此[示例 RKE 模板 YAML](../../../../reference-guides/rke1-template-example-yaml.md)。RKE 模板中的 YAML 使用了 Rancher 在创建 RKE 集群时使用的相同自定义设置。但由于 YAML 要在 Rancher 配置的集群中使用，因此需要将 RKE 模板自定义项嵌套在 YAML 中的 `rancher_kubernetes_engine_config` 参数下。 + +RKE 文档也提供[注释的](https://rancher.com/docs/rke/latest/en/example-yamls/) `cluster.yml` 文件供你参考。 + +有关可用选项的更多信息，请参阅[集群配置](https://rancher.com/docs/rke/latest/en/config-options/)上的 RKE 文档。 + +### 附加组件 + +RKE 模板配置文件的附加组件部分的工作方式与[集群配置文件的附加组件部分](https://rancher.com/docs/rke/latest/en/config-options/add-ons/)相同。 + +用户定义的附加组件指令允许你调用和下拉 Kubernetes 清单或将它们直接内联。如果这些 YAML 清单包括在 RKE 模板中，Rancher 将在集群中部署这些 YAML 文件。 + +你可以使用附加组件执行以下操作： + +- 启动 Kubernetes 集群后，在集群上安装应用 +- 在使用 Kubernetes Daemonset 部署的节点上安装插件 +- 自动设置命名空间、ServiceAccount 或角色绑定 + +RKE 模板配置必须嵌套在 `rancher_kubernetes_engine_config` 参数中。要设置附加组件，在创建模板时单击**以 YAML 文件编辑**。然后使用 `addons` 指令添加清单，或使用 `addons_include` 指令设置哪些 YAML 文件可用于附加组件。有关自定义附加组件的更多信息，请参见[用户自定义附加组件文档](https://rancher.com/docs/rke/latest/en/config-options/add-ons/user-defined-add-ons/)。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/access-or-share-templates.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/access-or-share-templates.md new file mode 100644 index 00000000000..8d7be6171d8 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/access-or-share-templates.md @@ -0,0 +1,64 @@ +--- +title: 访问和共享 +--- + +如果你是 RKE 模板所有者，你可以将该模板共享给用户或用户组，然后他们可以使用该模板创建集群。 + +由于 RKE 模板是专门与用户和组共享的，因此所有者可以与不同的用户共享不同的 RKE 模板。 + +共享模板时，每个用户都可以拥有以下两个访问权限中的其中一个： + +- **所有者**：可以更新、删除和共享他们拥有的模板。所有者还可以与其他用户共享模板。 +- **用户**：可以使用模板创建集群。他们还可以将这些集群升级到同一模板的新版本。如果你将模板共享为**公开（只读）**，你的 Rancher 设置中的所有用户都拥有该模板的用户访问权限。 + +如果你创建了一个模板，你将自动成为该模板的所有者。 + +如果你想让其他用户更新该模板，你可以共享模板的所有权。有关所有者如何修改模板的详细信息，请参阅[修改模板文档](manage-rke1-templates.md)。 + +共享模板的方式有如下几种： + +- 在模板创建期间将用户添加到新的 RKE 模板 +- 将用户添加到现有 RKE 模板 +- 公开 RKE 模板，并与 Rancher 设置中的所有用户共享 +- 与受信任修改模板的用户共享模板所有权 + +## 与特定用户或组共享模板 + +要允许用户或组使用你的模板创建集群，你可以为他们提供模板的基本**用户**访问权限。 + +1. 在左上角，单击 **☰ > 集群管理**。 +1. 在 **RKE1 配置**下，单击 **RKE 模板**。 +1. 转到要共享的模板，然后单击 **⋮ > 编辑**。 +1. 在**共享模板**中，单击**添加成员**。 +1. 在**名称**字段中搜索你要与之共享模板的用户或组。 +1. 选择**用户**访问类型。 +1. 单击**保存**。 + +**结果**：用户或组可以使用模板创建集群。 + +## 与所有用户共享模板 + +1. 在左上角，单击 **☰ > 集群管理**。 +1. 在左侧导航栏，单击 **RKE1 配置 > RKE 模板**。 +1. 转到要共享的模板，然后单击 **⋮ > 编辑**。 +1. 在**共享模板**下，选中 **公开（只读）** 复选框。 +1. 单击**保存**。 + +**结果**：Rancher 设置中的所有用户都可以使用该模板创建集群。 + +## 共享模板所有权 + +如果你是模板的创建者，你可能希望将维护和更新模板的责任委派给其他用户或组。 + +在这种情况下，你可以为用户提供**所有者**访问权限，该权限允许其他用户更新、删除模板或与其他用户共享对模板的访问权限。 + +要授予用户或组**所有者**权限： + +1. 在左上角，单击 **☰ > 集群管理**。 +1. 在 **RKE1 配置**下，单击 **RKE 模板**。 +1. 转到要共享的 RKE 模板，然后单击 **⋮ > 编辑**。 +1. 在**共享模板**下，单击**添加成员**并在**名称**字段中搜索要与之共享模板的用户或组。 +1. 在**访问类型**字段中，单击**所有者**。 +1. 单击**保存**。 + +**结果**：用户或组具有**所有者**访问类型，可以修改、共享或删除模板。 \ No newline at end of file diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/apply-templates.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/apply-templates.md new file mode 100644 index 00000000000..1e20c57d100 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/apply-templates.md @@ -0,0 +1,58 @@ +--- +title: 应用模板 +--- + +你可以使用你自己创建的 RKE 模板来创建集群，也可以使用[与你共享的模板](access-or-share-templates.md)来创建集群。 + +RKE 模板可以应用于新集群。 + +你可以[将现有集群的配置保存为 RKE 模板](#将现有集群转换为使用-rke-模板)。这样，只有模板更新后才能更改集群的设置。 + +你无法将集群更改为使用不同的 RKE 模板。你只能将集群更新为同一模板的新版本。 + +## 使用 RKE 模板创建集群 + +要使用 RKE 模板添加[由基础设施提供商托管](../../launch-kubernetes-with-rancher/launch-kubernetes-with-rancher.md)的集群，请按照以下步骤操作： + +1. 在左上角，单击 **☰ > 集群管理**。 +1. 在**集群**页面上，单击**创建**并选择基础设施提供商。 +1. 设置集群名称和节点模板详情。 +1. 要使用 RKE 模板，请在**集群选项**下，选中**使用现有 RKE 模板和修订版**复选框。 +1. 从下拉菜单中选择 RKE 模板和修订版。 +1. 可选：你可以编辑 RKE 模板所有者在创建模板时标记为**允许用户覆盖**的任何设置。如果你无法更改某些设置，则需要联系模板所有者以获取模板的新修订版。然后，你需要编辑集群来将其升级到新版本。 +1. 单击**创建**以启动集群。 + +## 更新使用 RKE 模板创建的集群 + +模板所有者创建 RKE 模板时，每个设置在 Rancher UI 中都有一个开关，指示用户是否可以覆盖该设置。 + +- 如果某个设置允许用户覆盖，你可以通过[编辑集群](../../../../reference-guides/cluster-configuration/cluster-configuration.md)来更新集群中的设置。 +- 如果该开关处于关闭状态，则除非集群所有者创建了允许你覆盖这些设置的模板修订版，否则你无法更改这些设置。如果你无法更改某些设置，则需要联系模板所有者以获取模板的新修订版。 + +如果集群是使用 RKE 模板创建的，你可以编辑集群，来将集群更新为模板的新版本。 + +现有集群的设置可以[保存为 RKE 模板](#将现有集群转换为使用-rke-模板)。在这种情况下，你还可以编辑集群以将集群更新为模板的新版本。 + +:::note + +你无法将集群更改为使用不同的 RKE 模板。你只能将集群更新为同一模板的新版本。 + +::: + +## 将现有集群转换为使用 RKE 模板 + +本节介绍如何使用现有集群创建 RKE 模板。 + +除非你将现有集群的设置保存为 RKE 模板，否则 RKE 模板不能应用于现有集群。这将把集群的设置导出为新的 RKE 模板，并且将集群绑定到该模板。然后，只有[更新了模板](manage-rke1-templates.md#更新模板)并且集群升级到**使用更新版本的模板**时，集群才能改变。 + +要将现有集群转换为使用 RKE 模板： + +1. 在左上角，单击 **☰ > 集群管理**。 +1. 在**集群**页面上，转到要转换为使用 RKE 模板的集群。单击 **⋮ > 保存为 RKE 模板**。 +1. 在出现的表单中输入模板的名称，然后单击**创建**。 + +**结果**： + +- 创建了一个新的 RKE 模板。 +- 将集群转换为使用该新模板。 +- 可以[使用新模板创建新集群](#使用-rke-模板创建集群)。 \ No newline at end of file diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/creator-permissions.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/creator-permissions.md new file mode 100644 index 00000000000..7db812c38ef --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/creator-permissions.md @@ -0,0 +1,57 @@ +--- +title: 模板创建者权限 +--- + +管理员有创建 RKE 模板的权限，只有管理员可以将该权限授予其他用户。 + +有关管理员权限的更多信息，请参阅[全局权限文档](../manage-role-based-access-control-rbac/global-permissions.md)。 + +## 授予用户创建模板的权限 + +只有具有**创建 RKE 模板**全局权限的用户才能创建模板。 + +管理员拥有创建模板的全局权限，只有管理员才能将该权限授予其他用户。 + +有关允许用户修改现有模板的信息，请参阅[共享模板](access-or-share-templates.md)。 + +管理员可以通过两种方式授予用户创建 RKE 模板的权限： + +- 通过编辑[单个用户](#允许用户创建模板)的权限 +- 通过更改[新用户的默认权限](#默认允许新用户创建模板) + +### 允许用户创建模板 + +管理员可以按照以下步骤将**创建 RKE 模板**角色单独授予给任何现有用户： + +1. 在左上角，单击 **☰ > 用户 & 认证**。 +1. 在左侧导航栏中，单击**用户**。 +1. 选择要编辑的用户，然后单击 **⋮ > 编辑配置**。 +1. 在**内置角色**中，选中**创建 RKE 集群模板**角色以及用户应具有的其他角色。你可能还需要选中**创建 RKE 模板修订版**复选框。 +1. 单击**保存**。 + +**结果**：用户拥有创建 RKE 模板的权限。 + +### 默认允许新用户创建模板 + +管理员也可以按照以下步骤为所有新用户授予创建 RKE 模板的默认权限。这不会影响现有用户的权限。 + +1. 在左上角，单击 **☰ > 用户 & 认证**。 +1. 在左侧导航栏中，单击**角色**。 +1. 转到**创建 RKE 集群模板**角色，然后单击 **⋮ > 编辑配置**。 +1. 选择**是：新用户的默认角色**选项。 +1. 单击**保存**。 +1. 如果你希望新用户能够创建 RKE 模板修订，请将该角色设置为默认值。 + +**结果**：在此 Rancher 安装中创建的任何新用户都可以创建 RKE 模板。现有用户将不会获得此权限。 + +### 取消创建模板的权限 + +管理员可以通过以下步骤删除用户创建模板的权限。请注意，无论是否选择了细粒度权限，管理员都可以完全控制所有资源。 + +1. 在左上角，单击 **☰ > 用户 & 认证**。 +1. 在左侧导航栏中，单击**用户**。 +1. 选择要编辑权限的用户，然后单击 **⋮ > 编辑配置**。 +1. 在**内置角色**中，取消选中**创建 RKE 模板**和**创建 RKE 模板修订版**复选框（如果适用）。在此处，你可以将用户改回普通用户，或授予用户一组不同的权限。 +1. 单击**保存**。 + +**结果**：用户无法创建 RKE 模板。 \ No newline at end of file diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/enforce-templates.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/enforce-templates.md new file mode 100644 index 00000000000..38ab0f41ee8 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/enforce-templates.md @@ -0,0 +1,43 @@ +--- +title: 强制使用模板 +--- + +本节介绍模板管理员如何在 Rancher 中强制执行模板，从而限制用户在没有模板的情况下创建集群。 + +默认情况下，Rancher 中的任何普通用户都可以创建集群。但当开启强制使用 RKE 模板时，有以下约束： + +- 只有管理员才能在没有模板的情况下创建集群。 +- 所有普通用户必须使用 RKE 模板来创建新集群。 +- 普通用户在不使用模板的情况下无法创建集群。 + +只有管​​理员[授予权限](creator-permissions.md#允许用户创建模板)后，用户才能创建新模板。 + +使用 RKE 模板创建集群后，集群创建者无法编辑模板中定义的设置。创建集群后更改这些设置的唯一方法是[将集群升级到相同模板的新修订版](apply-templates.md#更新使用-rke-模板创建的集群)。如果集群创建者想要更改模板定义的设置，他们需要联系模板所有者以获取模板的新版本。有关模板修订如何工作的详细信息，请参阅[修订模板](manage-rke1-templates.md#更新模板)。 + +## 强制新集群使用 RKE 模板 + +要求用户创建新集群时使用模板，可以确保[普通用户](../manage-role-based-access-control-rbac/global-permissions.md)启动的任何集群都使用经过管理员审核的 Kubernetes 和 Rancher 设置。 + +管理员可以通过以下步骤启用 RKE 模板强制，从而要求用户必须使用模板创建集群： + +1. 单击 **☰ > 全局设置**。 +1. 转到 `cluster-template-enforcement` 设置。单击 **⋮ > 编辑设置**。 +1. 将值设置为 **True** 并单击**保存**。 + + :::note 重要提示： + + 如果管理员将 `cluster-template-enforcement` 设置为 True，还需要与用户共享 `clusterTemplates`，以便用户可以选择其中一个模板来创建集群。 + + ::: + +**结果**：除非创建者是管理员，否则 Rancher 配置的所有集群都必须使用模板。 + +## 禁用 RKE 模板强制 + +管理员可以通过以下步骤关闭 RKE 模板强制，从而允许用户在没有 RKE 模板的情况下创建新集群： + +1. 单击 **☰ > 全局设置**。 +1. 转到 `cluster-template-enforcement` 设置。单击 **⋮ > 编辑设置**。 +1. 将值设置为 **False** 并单击**保存**。 + +**结果**：在 Rancher 中创建集群时，用户不需要使用模板。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/example-use-cases.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/example-use-cases.md new file mode 100644 index 00000000000..7457df20253 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/example-use-cases.md @@ -0,0 +1,70 @@ +--- +title: 示例场景 +--- + +以下示例场景描述了组织如何使用模板来标准化集群创建。 + +- **强制执行模板**：如果希望所有 Rancher 配置的新集群都具有某些设置，管理员可能想要[为每个用户强制执行一项或多项模板设置](#强制执行模板设置)。 +- **与不同的用户共享不同的模板**：管理员可以为[普通用户和高级用户提供不同的模板](#普通用户和高级用户模板)。这样，普通用户会有更多限制选项，而高级用户在创建集群时可以使用更多选项。 +- **更新模板设置**：如果组织的安全和 DevOps 团队决定将最佳实践嵌入到新集群所需的设置中，这些最佳实践可能会随着时间而改变。如果最佳实践发生变化，[可以将模板更新为新版本](#更新模板和集群)。这样，使用模板创建的集群可以升级到模板的新版本。 +- **共享模板的所有权**：当模板所有者不再想要维护模板或想要共享模板的所有权时，此方案描述了如何[授权模板所有权](#允许其他用户控制和共享模板)。 + + +## 强制执行模板设置 + +假设一个组织的管理员决定用 Kubernetes 版本 1.14 创建所有新集群： + +1. 首先，管理员创建一个模板，将 Kubernetes 版本指定为 1.14，并将所有其他设置标记为**允许用户覆盖**。 +1. 管理员将模板公开。 +1. 管理员打开模板强制功能。 + +**结果**： + +- 组织中的所有 Rancher 用户都可以访问该模板。 +- [普通用户](../manage-role-based-access-control-rbac/global-permissions.md)使用此模板创建的所有新集群都将使用 Kubernetes 1.14，它们无法使用其它 Kubernetes 版本。默认情况下，普通用户没有创建模板的权限。因此，除非与他们共享更多模板，否则此模板将是普通用户唯一可以使用的模板。 +- 所有普通用户都必须使用集群模板来创建新集群。他们无法在不使用模板的情况下创建集群。 + +通过这种方式，管理员在整个组织中强制执行 Kubernetes 版本，同时仍然允许最终用户配置其他所有内容。 + +## 普通用户和高级用户模板 + +假设一个组织有普通用户和高级用户。管理员希望普通用户必须使用模板，而高级用户和管理员可以根据自己的需要创建集群。 + +1. 首先，管理员开启 [RKE 模板强制执行](enforce-templates.md#强制新集群使用-rke-模板)。这意味着 Rancher 中的每个[普通用户](../manage-role-based-access-control-rbac/global-permissions.md)在创建集群时都需要使用 RKE 模板。 +1. 然后管理员创建两个模板： + +- 一个普通用户模板，该模板除了访问密钥外，几乎指定了所有选项 +- 一个高级用户模板，该模板具有大部分或所有已启用**允许用户覆盖**的选项 + +1. 管理员仅与高级用户共享高级模板。 +1. 管理员将普通用户的模板公开，因此在 Rancher 中创建的 RKE 集群的每个人都能选择限制性更强的模板。 + +**结果**：除管理员外，所有 Rancher 用户在创建集群时都需要使用模板。每个人都可以访问限制模板，但只有高级用户有权使用更宽松的模板。普通用户会受到更多限制，而高级用户在配置 Kubernetes 集群时有更多选择。 + +## 更新模板和集群 + +假设一个组织有一个模板，该模板要求集群使用 Kubernetes v1.14。然而，随着时间的推移，管理员改变了主意。管理员现在希望用户能够升级集群，以使用更新版本的 Kubernetes。 + +在这个组织中，许多集群是用一个需要 Kubernetes v1.14 的模板创建的。由于模板不允许重写该设置，因此创建集群的用户无法直接编辑该设置。 + +模板所有者可以有以下几个选项，来允许集群创建者在集群上升级 Kubernetes： + +- **在模板上指定 Kubernetes v1.15**：模板所有者可以创建指定 Kubernetes v1.15 的新模板修订版。然后使用该模板的每个集群的所有者可以将集群升级到模板的新版本。此模板升级允许集群创建者在集群上将 Kubernetes 升级到 v1.15。 +- **允许在模板上使用任何 Kubernetes 版本**：创建模板修订时，模板所有者还可以使用 Rancher UI 上该设置附近的开关，将 Kubernetes 版本标记为**允许用户覆盖**。该设置允许升级到此模板版本的集群使用任意 Kubernetes 的版本。 +- **允许在模板上使用最新的 Kubernetes 次要版本**：模板所有者还可以创建一个模板修订版，其中 Kubernetes 版本被定义为 **Latest v1.14（允许补丁版本升级）**。这意味着使用该版本的集群将能够进行补丁版本升级，但不支持主要版本升级。 + +## 允许其他用户控制和共享模板 + +假设 Alice 是 Rancher 管理员。她拥有一个 RKE 模板，该模板反映了她的组织为创建集群而商定的最佳实践。 + +Bob 是一位高级用户，可以就集群配置做出明智的决策。随着最佳实践随着时间的推移不断更新，Alice 相信 Bob 会为她的模板创建新的修订。因此，她决定让 Bob 成为模板的所有者。 + +为了与 Bob 共享模板的所有权，Alice [将 Bob 添加为模板的所有者](access-or-share-templates.md#共享模板所有权)。 + +结果是，作为模板所有者，Bob 负责该模板的版本控制。Bob 现在可以执行以下所有操作： + +- 当最佳实践发生变化时[修改模板](manage-rke1-templates.md#更新模板) +- [禁用模板的过时修订](manage-rke1-templates.md#禁用模板修订版)，以禁止使用该模板来创建集群 +- 如果组织想要改变方向，则[删除整个模板](manage-rke1-templates.md#删除模板) +- [将某个版本设置为默认值](manage-rke1-templates.md#将模板修订版设置为默认)，用于用户创建集群。模板的最终用户仍然可以选择他们想要使用哪个版本来创建集群。 +- [与特定用户共享模板](access-or-share-templates.md)，让所有 Rancher 用户都可以使用该模板，或与其他用户共享该模板的所有权。 \ No newline at end of file diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/infrastructure.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/infrastructure.md new file mode 100644 index 00000000000..e430820063d --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/infrastructure.md @@ -0,0 +1,68 @@ +--- +title: RKE 模板和基础设施 +--- + +在 Rancher 中，RKE 模板用于配置 Kubernetes 和定义 Rancher 设置，而节点模板则用于配置节点。 + +因此，即使开启了 RKE 模板强制，最终用户在创建 Rancher 集群时仍然可以灵活选择底层硬件。RKE 模板的最终用户仍然可以选择基础设施提供商和他们想要使用的节点。 + +如果要标准化集群中的硬件，请将 RKE 模板与节点模板或服务器配置工具 (如 Terraform) 结合使用。 + +## 节点模板 + +[节点模板](../../../../reference-guides/user-settings/manage-node-templates.md)负责 Rancher 中的节点配置和节点预配。你可以在用户配置文件中设置节点模板，从而定义在每个节点池中使用的模板。启用节点池后，可以确保每个节点池中都有所需数量的节点，并确保池中的所有节点都相同。 + +## Terraform + +Terraform 是一个服务器配置工具。它使用基础架构即代码，支持使用 Terraform 配置文件创建几乎所有的基础设施。它可以自动执行服务器配置，这种方式是自文档化的，并且在版本控制中易于跟踪。 + +本节重点介绍如何将 Terraform 与 [Rancher 2 Terraform Provider](https://www.terraform.io/docs/providers/rancher2/) 一起使用，这是标准化 Kubernetes 集群硬件的推荐选项。如果你使用 Rancher Terraform Provider 来配置硬件，然后使用 RKE 模板在该硬件上配置 Kubernetes 集群，你可以快速创建一个全面的、可用于生产的集群。 + +Terraform 支持： + +- 定义几乎任何类型的基础架构即代码，包括服务器、数据库、负载均衡器、监控、防火墙设置和 SSL 证书 +- 跨多个平台（包括 Rancher 和主要云提供商）对基础设施进行编码 +- 将基础架构即代码提交到版本控制 +- 轻松重复使用基础设施的配置和设置 +- 将基础架构更改纳入标准开发实践 +- 防止由于配置偏移，导致一些服务器的配置与其他服务器不同 + +### Terraform 工作原理 + +Terraform 是用扩展名为 `.tf` 的文件编写的。它是用 HashiCorp 配置语言编写的。HashiCorp 配置语言是一种声明性语言，支持定义集群中所需的基础设施、正在使用的云提供商以及提供商的凭证。然后 Terraform 向提供商发出 API 调用，以便有效地创建基础设施。 + +要使用 Terraform 创建 Rancher 配置的集群，请转到你的 Terraform 配置文件并将提供商定义为 Rancher 2。你可以使用 Rancher API 密钥设置你的 Rancher 2 提供商。请注意，API 密钥与其关联的用户具有相同的权限和访问级别。 + +然后 Terraform 会调用 Rancher API 来配置你的基础设施，而 Rancher 调用基础设施提供商。例如，如果你想使用 Rancher 在 AWS 上预配基础设施，你需要在 Terraform 配置文件或环境变量中提供 Rancher API 密钥和 AWS 凭证，以便它们用于预配基础设施。 + +如果你需要对基础设施进行更改，你可以在 Terraform 配置文件中进行更改，而不是手动更新服务器。然后，可以将这些文件提交给版本控制、验证，并根据需要进行检查。然后，当你运行 `terraform apply` 时，更改将会被部署。 + +### 使用 Terraform 的技巧 + +- [Rancher 2 提供商文档](https://www.terraform.io/docs/providers/rancher2/)提供了如何配置集群大部分的示例。 + +- 在 Terraform 设置中，你可以使用 Docker Machine 主机驱动来安装 Docker Machine。 + +- 可以在 Terraform Provider 中修改身份验证。 + +- 可以通过更改 Rancher 中的设置，来反向工程如何在 Terraform 中定义设置，然后返回并检查 Terraform 状态文件，以查看该文件如何映射到基础设施的当前状态。 + +- 如果你想在一个地方管理 Kubernetes 集群设置、Rancher 设置和硬件设置，请使用 [Terraform 模块](https://github.com/rancher/terraform-modules)。你可以将集群配置 YAML 文件或 RKE 模板配置文件传递给 Terraform 模块，以便 Terraform 模块创建它。在这种情况下，你可以使用基础架构即代码来管理 Kubernetes 集群及其底层硬件的版本控制和修订历史。 + +## 创建符合 CIS 基准的集群的技巧 + +本节描述了一种方法，可以使安全合规相关的配置文件成为集群的标准配置文件。 + +在你创建[符合 CIS 基准的集群](../../../../reference-guides/rancher-security/rancher-security.md)时，你有一个加密配置文件和一个审计日志配置文件。 + +你的基础设施预配系统可以将这些文件写入磁盘。然后在你的 RKE 模板中，你需要指定这些文件的位置，然后将你的加密配置文件和审计日志配置文件作为额外的挂载添加到 `kube-api-server`。 + +然后，你需要确保 RKE 模板中的 `kube-api-server` 标志使用符合 CIS 的配置文件。 + +通过这种方式，你可以创建符合 CIS 基准的标志。 + +## 资源 + +- [Terraform 文档](https://www.terraform.io/docs/) +- [Rancher2 Terraform Provider 文档](https://www.terraform.io/docs/providers/rancher2/) +- [The RanchCast - 第 1 集：Rancher 2 Terraform Provider](https://youtu.be/YNCq-prI8-8)：在此演示中，社区主管 Jason van Brackel 使用 Rancher 2 Terraform Provider 创建了节点并创建自定义集群。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/manage-rke1-templates.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/manage-rke1-templates.md new file mode 100644 index 00000000000..0ae0c786814 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/manage-rke1-templates.md @@ -0,0 +1,162 @@ +--- +title: 创建和修改 RKE 模板 +--- + + + +本节介绍如何管理 RKE 模板和修订版。你可以从 **RKE1 配置 > RKE 模板**下的**集群管理**视图创建、共享、更新和删除模板。 + +模板更新通过修订系统处理。当模板所有者想要更改或更新模板时，他们会创建模板的新版本。单个修订无法编辑。但是，如果你想防止使用修订来创建新集群，你可以禁用它。 + +你可以使用两种方式来使用模板修订：创建新集群，或升级使用较早版本的模板创建的集群。模板创建者可以设置默认修订版，但是在最终用户创建集群时，他们可以选择任何模板以及可供使用的任何模板修订版。使用指定的修订版创建集群后，就无法将其更改为另一个模板，但是可以将集群升级为同一模板的较新的可用修订版。 + +模板所有者对模板修订版具有完全控制权，并且可以创建新的修订版来更新模板，删除或禁用不应被用于创建集群的修订版，和设置默认的模板修订版。 + +## 先决条件 + +如果你具有**创建 RKE 模板**权限，则可以创建 RKE 模板，该权限可由[管理员授予](creator-permissions.md)。 + +如果你是模板的所有者，你可以修改、共享和删除模板。有关如何成为模板所有者的详细信息，请参阅[共享模板所有权文档](access-or-share-templates.md#共享模板所有权)。 + +## 创建模板 + +1. 在左上角，单击 **☰ > 集群管理**。 +1. 单击 **RKE1 配置 > 节点模板**。 +1. 单击**添加模板**。 +1. 输入模板的名称。Rancher 已经为模板的第一个版本自动生成了名称，该版本与该模板一起创建。 +1. 可选：通过将用户添加为成员，来[与其他用户或组共享模板](access-or-share-templates.md#与特定用户或组共享模板)。你还可以将模板公开，从而与 Rancher 中的所有人共享。 +1. 然后按照屏幕上的表格将集群配置参数保存为模板修订的一部分。可以将修订标记为此模板的默认值。 + +**结果**：配置了具有一个修订版的 RKE 模板。你可以稍后在[配置 Rancher 启动的集群](../../launch-kubernetes-with-rancher/launch-kubernetes-with-rancher.md)时使用此 RKE 模板修订版。通过 RKE 模板管理集群后，集群无法解除与模板的绑定，并且无法取消选中**使用现有 RKE 模板和修订版**。 + +## 更新模板 + +更新 RKE 模板相当于创建现有模板的修订版。使用旧版本模板创建的集群可以进行更新，从而匹配新版本。 + +你不能编辑单个修订。由于你无法编辑模板的单个修订，为了防止使用某个修订，你可以[禁用该修订版](#禁用模板修订版)。 + +创建新模板修订时，使用旧模板修订的集群不受影响。 + +1. 在左上角，单击 **☰ > 集群管理**。 +1. 在左侧导航栏，单击 **RKE1 配置 > RKE 模板**。 +1. 转到要编辑的模板，然后单击 **⋮ > 编辑**。 +1. 编辑所需信息并单击**保存**。 +1. 可选：你可以更改此模板的默认修订版，也可以更改共享对象。 + +**结果**：模板已更新。要将其应用到使用旧版本模板的集群，请参阅[升级集群以使用新的模板修订版](#升级集群以使用新的模板修订版)。 + +## 删除模板 + +当不再需要为任何集群使用某个 RKE 模板时，可以将其删除。 + +1. 在左上角，单击 **☰ > 集群管理**。 +1. 单击 **RKE1 配置 > RKE 模板**。 +1. 转到要删除的 RKE 模板，然后单击 **⋮ > 删除**。 +1. 确认删除。 + +**结果**：模板被删除。 + +## 基于默认版创建新修订版 + +你可以复制默认模板修订版并快速更新其设置，而无需从头开始创建新修订版。克隆模板为你省去了重新输入集群创建所需的访问密钥和其他参数的麻烦。 + +1. 在左上角，单击 **☰ > 集群管理**。 +1. 在左侧导航栏，单击 **RKE1 配置 > RKE 模板**。 +1. 转到要克隆的 RKE 模板，然后单击 **⋮ > 基于默认版创建新修订版**。 +1. 填写表单的其余部分来创建新修订。 + +**结果**：克隆并配置了 RKE 模板修订版。 + +## 基于克隆版创建新修订版 + +通过用户设置创建新的 RKE 模板修订版时，可以克隆现有修订版并快速更新其设置，而无需从头开始创建新的修订版。克隆模板修订省去了重新输入集群参数的麻烦。 + +1. 在左上角，单击 **☰ > 集群管理**。 +1. 在 **RKE1 配置**下，单击 **RKE 模板**。 +1. 转到要克隆的模板修订。然后选择 **⋮ > 克隆修订版**。 +1. 填写表单的其余部分。 + +**结果**：克隆并配置了 RKE 模板修订版。你可以在配置集群时使用 RKE 模板修订。任何使用此 RKE 模板的现有集群都可以升级到此新版本。 + +## 禁用模板修订版 + +当你不需要将 RKE 模板修订版本用于创建新集群时，可以禁用模板修订版。你也可以重新启用禁用了的修订版。 + +如果没有任何集群使用该修订，你可以禁用该修订。 + +1. 在左上角，单击 **☰ > 集群管理**。 +1. 在左侧导航栏，单击 **RKE1 配置 > RKE 模板**。 +1. 转到要禁用的模板修订版。然后选择 **⋮ > 禁用**。 + +**结果**：RKE 模板修订版不能用于创建新集群。 + +## 重新启用禁用的模板修订版 + +如果要使用已禁用的 RKE 模板修订版来创建新集群，你可以重新启用该修订版。 + +1. 在左上角，单击 **☰ > 集群管理**。 +1. 在 **RKE1 配置**下，单击 **RKE 模板**。 +1. 转到要重新启用的模板修订。然后选择 **⋮ > 启用**。 + +**结果**：RKE 模板修订版可用于创建新集群。 + +## 将模板修订版设置为默认 + +当最终用户使用 RKE 模板创建集群时，他们可以选择使用哪个版本来创建集群。你可以配置默认使用的版本。 + +要将 RKE 模板修订版设置为默认： + +1. 在左上角，单击 **☰ > 集群管理**。 +1. 在左侧导航栏，单击 **RKE1 配置 > RKE 模板**。 +1. 转到要设为默认的 RKE 模板修订版，然后单击 **⋮ > 设为默认配置**。 + +**结果**：使用模板创建集群时，RKE 模板修订版将用作默认选项。 + +## 删除模板修订版 + +你可以删除模板的所有修订（默认修订除外）。 + +要永久删除修订版： + +1. 在左上角，单击 **☰ > 集群管理**。 +1. 在左侧导航栏，单击 **RKE1 配置 > RKE 模板**。 +1. 转到要删除的 RKE 模板修订版，然后单击 **⋮ > 删除**。 + +**结果**：RKE 模板修订版被删除。 + +## 升级集群以使用新的模板修订版 + +:::note + +本部分假设你已经有一个集群，该集群[应用了 RKE 模板](apply-templates.md)。 + +本部分还假设你已[更新了集群使用的模板](#更新模板)，以便可以使用新的模板修订版。 + +::: + +要将集群升级到使用新的模板修订版： + +1. 在左上角，单击 **☰ > 集群管理**。 +1. 转到要升级的集群，然后单击 **⋮ > 编辑配置**。 +1. 在**集群选项**中，单击模板修订版的下拉菜单，然后选择新的模板修订版。 +1. 单击**保存**。 + +**结果**：集群已升级为使用新模板修订版中定义的设置。 + +## 将正在运行的集群导出到新的 RKE 模板和修订版 + +你可以将现有集群的设置保存为 RKE 模板。 + +这将把集群的设置导出为新的 RKE 模板，并且将集群绑定到该模板。然后，只有[更新了模板](#更新模板)并且集群升级到[使用更新版本的模板](#升级集群以使用新的模板修订版)时，集群才能改变。 + +要将现有集群转换为使用 RKE 模板： + +1. 在左上角，单击 **☰ > 集群管理**。 +1. 转到将被转换为使用 RKE 模板的集群，然后 **⋮ > 保存为 RKE 模板**。 +1. 在出现的表单中输入 RKE 模板的名称，然后单击**创建**。 + +**结果**： + +- 创建了一个新的 RKE 模板。 +- 将集群转换为使用该新模板。 +- 可以[使用新模板和修订版创建新集群。](apply-templates.md#使用-rke-模板创建集群) \ No newline at end of file diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/override-template-settings.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/override-template-settings.md new file mode 100644 index 00000000000..11ecac6fabd --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/override-template-settings.md @@ -0,0 +1,14 @@ +--- +title: 覆盖模板设置 +--- + +用户创建 RKE 模板时，模板中的每个设置在 Rancher UI 中都有一个开关，指示用户是否可以覆盖该设置。此开关将这些设置标记为**允许用户覆盖**。打开开关表示用户可以修改对应的参数，关闭开关表示用户无权修改对应的参数。 + +使用模板创建集群后，除非模板所有者将设置标记为**允许用户覆盖**，否则最终用户无法更新模板中定义的任何设置。但是，如果模板[更新到新修订版](manage-rke1-templates.md)，且该修订版更改了设置或允许最终用户更改设置，则集群可以升级到模板的新修订版，并且新修订版中的更改将应用于集群。 + +如果 RKE 模板上的任何参数设置为**允许用户覆盖**，最终用户必须在集群创建期间设置这些字段，然后他们可以随时编辑这些设置。 + +RKE 模板的**允许用户覆盖**选项的适用场景如下： + +- 管理员认为某些参数需要保持灵活性，以便随时更新。 +- 最终用户将需要输入他们自己的访问密钥或密文密钥，例如，云凭证或备份快照的凭证。 \ No newline at end of file diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/authentication-config/authentication-config.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/authentication-config/authentication-config.md new file mode 100644 index 00000000000..b18e6701900 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/authentication-config/authentication-config.md @@ -0,0 +1,146 @@ +--- +title: 配置认证 +weight: 10 +--- + + + + + +Rancher 为 Kubernetes 添加的一个关键功能是集中式用户认证，这个特性允许用户使用一组凭证对任何 Kubernetes 集群进行身份认证。 + +这种集中式用户认证是通过 Rancher 的认证代理完成的，该代理与 Rancher 的其余部分一并安装，此代理对用户进行认证并通过一个 Service Acount 将请求转发到 Kubernetes 集群中。 + +:::warning + +用来启用外部认证的账户将被授予管理员权限。如果你使用一个测试账号或非管理员账号，该账号仍然会被授予管理员级别权限。请查看[外部认证配置和主体用户](#外部认证配置和用户主体)了解原因。 + +::: + +## 外部认证与本地认证 + +Rancher 认证代理可以与以下外部认证服务集成。 + +| 认证服务 | +| ---------------------------------------------------------------------------------------------------------------------- | +| [Microsoft Active Directory](configure-active-directory.md) | +| [GitHub](configure-github.md) | +| [Microsoft Azure AD](configure-azure-ad.md) | +| [FreeIPA](configure-freeipa.md) | +| [OpenLDAP](../configure-openldap/configure-openldap.md) | +| [Microsoft AD FS](../configure-microsoft-ad-federation-service-saml/configure-microsoft-ad-federation-service-saml.md) | +| [PingIdentity](configure-pingidentity.md) | +| [Keycloak (OIDC)](configure-keycloak-oidc.md) | +| [Keycloak (SAML)](configure-keycloak-saml.md) | +| [Okta](configure-okta-saml.md) | +| [Google OAuth](configure-google-oauth.md) | +| [Shibboleth](../configure-shibboleth-saml/configure-shibboleth-saml.md) | + +当然，Rancher 也提供[本地认证](create-local-users.md). + +在多数情况下，你应该使用外部认证服务而不是使用本地认证，因为外部认证服务可以集中式的对用户进行管理。但是在极少数情况下，例如外部认证服务不可用或正在维护时，你可能需要使用本地认证用户来管理 Rancher。 + +## 用户和组 + +:::note + +- Local authentication does not support creating or managing groups. +- After an external authentication provider is configured, note that local Rancher scoped administrative users only display resources such as users and groups that they are a member of in the respective authentication provider. + +::: + +Rancher 依赖用户和组来决定允许谁登录 Rancher 以及他们可以访问哪些资源。当使用外部认证时，外部认证系统会根据用户提供组的信息。这些用户和组被赋予了集群、项目及全局 DNS 提供商和条目等资源的特定角色。当你对组进行授权时，在认证服务中所有属于这个组中的用户都有访问指定的资源的权限。有关角色和权限的更多信息，请查看 [RBAC](../manage-role-based-access-control-rbac/manage-role-based-access-control-rbac.md)。 + +更多信息，请查看[用户和组](manage-users-and-groups.md) + +## Rancher 授权范围 + +当你配置完 Rancher 使用外部认证服务后，你可以配置允许谁登录和使用 Rancher，包含如下的选项： + +| 访问级别 | 描述 | +| ---------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | +| 允许任何有效用户 | 在认证服务中的*任何*用户都可以访问 Rancher。通常情况下不建议使用该设置！ | +| 允许集群和项目成员，以及授权的用户和组织 | 认证服务中属于**集群成员**或**项目成员**的用户或组成员都可以登录 Rancher。此外添加在**授权的用户和组织**列表中的用户和组成员也可以登录到 Rancher。 | +| 仅限于授权的用户可以访问 | 仅有在授权用户和组织列表中的用户和组成员可以登录到 Rancher。 | + +要在授权服务中为用户设置 Rancher 访问级别，请执行以下步骤： + +1. 在左上角，点击 **☰ > 用户 & 认证**。 +1. 在左侧导航栏，点击 **认证**. +1. 设置完外部认证详细信息后，使用 **站点访问** 选项配置用户权限范围，上面的表格说明了每个选项的访问级别。 +1. 可选：如果你选择 **允许任何有效用户** 以外的选项，你可以通过在出现的文本框中搜索用户，将用户添加到授权用户和组织的列表中。 +1. 点击 **保存**。 + +**结果:** Rancher 的访问配置被应用。 + +:::note SAML 认证警告 + +- Users and groups aren't validated when you assign permissions to them in Rancher. +- 添加用户时，必须正确输入确切的用户 ID（即 UID 字段）。键入用户 ID 时，将不会搜索可能匹配的其他用户 ID。 +- 添加组时，必须从文本框旁边的下拉列表中选择组。Rancher 假定来自文本框的任何输入都是用户。 +- The group drop-down shows only the groups that you are a member of. However, if you have Administrator permissions or Restricted Administrator permissions, you can join a group that you are not a member of. + +::: + +## 外部认证配置和用户主体 + +配置外部认证需要： + +- 分配了管理员角色的本地用户，以下称为 _本地主体_。 +- 可以使用外部认证服务进行认证的外部用户，以下简称为 _外部主体_。 + +外部认证的配置也会影响 Rancher 中主体用户的管理方式，具体地说，当用户账户启用了外部认证时，将授予其管理员级别的权限。这是因为本地主体和外部主体共享相同的用户 ID 和访问权限。 + +以下说明演示了这些效果： + +1. 作为本地主体登录到 Rancher 并完成外部身份验证的配置。 + + ![Sign In](/img/sign-in.png) + +2. Rancher 将外部主体与本地主体相关联。这两个用户共享本地主体的用户 ID。 + + ![Principal ID Sharing](/img/principal-ID.png) + +3. 完成配置后，Rancher 将自动退出本地主体。 + + ![Sign Out Local Principal](/img/sign-out-local.png) + +4. 然后，Rancher 会自动将您登录外部主体。 + + ![Sign In External Principal](/img/sign-in-external.png) + +5. 因为外部主体和本地主体共享一个 ID，所以用户列中不会再单独显示一个另外的外部主体的对象。 + + ![Sign In External Principal](/img/users-page.png) + +6. 外部主体和本地主体共享相同的访问权限。 + +:::note 重新配置先前设置的认证 + +如果需要重新配置或禁用后重新启用先前设置过的认证，请确保尝试这样做的用户以外部用户身份登录到 Rancher，而不是使用本地管理员登录。 + +::: + +## 禁用认证 + +当你禁用认证时，Rancher 会删除所有与之关联的资源，例如： + +- 密文 +- 绑定的全局角色。 +- 绑定的集群角色。 +- 绑定的项目角色。 +- 与外部认证关联但从未以本地用户身份登录 Rancher 的外部用户。 + +由于此操作可能会导致许多资源丢失，因此你可能需要添加一些保护措施。若要确保禁用外部认证时不执行清理流程，需要为外部认证的配置添加特殊的注释。 + +例如，若要对 Azure AD 认证增加保护措施，你需要在 authconfig 对象上增加 `azuread` 注释： + +`kubectl annotate --overwrite authconfig azuread management.cattle.io/auth-provider-cleanup='user-locked'` + +禁用 Azure AD 认证后，Rancher 不会执行清理流程，直到你将该注解设置为 `unlocked`。 + +### 手动运行资源清理 + +Rancher 可能会在本地集群中保留之前禁用的外部认证配置的资源，即使你配置对接了另一种认证也是如此。例如，如果你对接了 A 认证，然后禁用它，并重新对接使用 B 认证，当你升级到新版本的 Rancher 时，你可以手动触发对认证 A 配置的资源清理。 + +要手动触发已禁用的认证配置的清理，请将 `unlocked` 值添加到对应认证配置的 `management.cattle.io/auth-provider-cleanup` 注解中。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/authentication-config/configure-active-directory.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/authentication-config/configure-active-directory.md new file mode 100644 index 00000000000..449befbcc5e --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/authentication-config/configure-active-directory.md @@ -0,0 +1,219 @@ +--- +title: 配置 Active Directory (AD) +--- + +如果你的组织使用 Microsoft Active Directory 作为中心用户仓库，你可以将 Rancher 配置为与 Active Directory 服务器通信，从而对用户进行身份验证。这使 Rancher 管理员可以对外部用户系统中的用户和组进行集群和项目的访问控制，同时允许最终用户在登录 Rancher UI 时使用 Active Directory 凭证进行身份验证。 + +Rancher 使用 LDAP 与 Active Directory 服务器通信。因此，Active Directory 与 [OpenLDAP 身份验证](../configure-openldap/configure-openldap.md)的流程相同。 + +:::note + +在开始之前，请熟悉[外部身份验证配置和主体用户](./authentication-config.md#外部认证配置和用户主体)的概念。 + +::: + +## 先决条件 + +你需要创建或从你的 AD 管理员处获取一个新的 AD 用户，用作 Rancher 的 ServiceAccount。此用户必须具有足够的权限，才能执行 LDAP 搜索并读取你的 AD 域下的用户和组的属性。 + +通常可以使用（非管理员）**域用户**账号，因为默认情况下，该用户对域分区中的大多数对象具有只读特权。 + +但是，请注意，在某些锁定的 Active Directory 配置中，此默认操作可能不适用。在这种情况下，你需要确保 ServiceAccount 用户在 Base OU（包含用户和组）上或全局范围内至少拥有域的 **Read** 和 **List Content** 权限。 + +:::note 使用 TLS？ + +- 如果 AD 服务器使用的证书是自签名的或不是来自认可的证书颁发机构，请确保手头有 PEM 格式的 CA 证书（包含所有中间证书）。你必须在配置期间粘贴此证书，以便 Rancher 能够验证证书链。 + +- 升级到 v2.6.0 后，如果 AD 服务器上的证书不支持 SAN 属性，则使用 TLS 通过 Rancher 对 Active Directory 进行身份验证可能会失败。这是 Go v1.15 中默认启用的检查。 + + - 收到"Error creating SSL connection: LDAP Result Code 200 "Network Error": x509 错误：证书依赖于旧的通用名称（Common Name）字段，使用 SAN 或临时启用与 GODEBUG=x509ignoreCN=0 匹配的通用名称。 + + - 要解决此错误，请使用支持 SAN 属性的新证书更新或替换 AD 服务器上的证书。或者，将 `GODEBUG=x509ignoreCN=0` 设置为 Rancher Server 容器的环境变量来忽略此错误。 + +::: + +## 配置步骤 +### 打开 Active Directory 配置 + +1. 使用初始的本地 `admin` 账号登录到 Rancher UI。 +1. 在左上角，单击 **☰ > 用户 & 认证**。 +1. 在左侧导航栏，单击**认证**。 +1. 单击 **ActiveDirectory**。然后会显示**验证提供程序：ActiveDirectory** 的表单。 +1. 填写表单。如果需要获取帮助，请参见下方的配置选项详情。 +1. 点击**启用**。 + +### 配置 Active Directory 服务器 + +在 `1. 配置 Active Directory 服务器` 的步骤中，使用你 Active Directory 的实际信息完成字段配置。有关每个参数所需值的详细信息，请参阅下表。 + +:::note + +如果你不确定要在用户/组`搜索库`字段中输入什么值，请参见[使用 ldapsearch 确定搜索库和 Schema](#附录使用-ldapsearch-确定搜索库和-schema)。 + +::: + +**表 1：AD 服务器参数** + +| 参数 | 描述 | +|:--|:--| +| 主机名 | 指定 AD 服务器的主机名或 IP 地址。 | +| 端口 | 指定 AD 服务器监听连接的端口。未加密的 LDAP 通常使用 389 的标准端口，而 LDAPS 使用 636 端口。 | +| TLS | 选中此框可启用 SSL/TLS 上的 LDAP（通常称为 LDAPS）。 | +| 服务器连接超时 | Rancher 在认为无法访问 AD 服务器之前等待的时间（秒）。 | +| ServiceAccount 用户名 | 输入对域分区具有只读访问权限的 AD 账号的用户名（参见[先决条件](#先决条件)）。用户名可以用 NetBIOS（例如 "DOMAIN\serviceaccount"）或 UPN 格式（例如 "serviceaccount@domain.com"）。 | +| ServiceAccount 密码 | ServiceAccount 的密码。 | +| 默认登录域 | 如果你使用 AD 域的 NetBIOS 名称配置此字段，在绑定到 AD 服务器时，没有包含域的用户名（例如“jdoe”）将自动转换为带斜杠的 NetBIOS 登录（例如，“LOGIN_DOMAIN\jdoe”）。如果你的用户以 UPN（例如，"jdoe@acme.com"）作为用户名进行身份验证，则此字段必须**必须**留空。 | +| 用户搜索库 | 输入目录树中开始搜索用户对象的节点的标识名称（DN）。所有用户都必须是此基础标识名称的后代。例如，"ou=people,dc=acme,dc=com"。 | +| 组搜索库 | 如果组位于`用户搜索库`下配置的节点之外的其他节点下，则需要在此处提供标识名称。否则请留空。例如："ou=groups,dc=acme,dc=com"。 | + +--- + +### 配置用户/组 Schema + +在 `2. 自定义 Schema` 中，你必须为 Rancher 提供与目录中使用的 Schema 对应的用户和组属性的正确映射。 + +Rancher 使用 LDAP 查询来搜索和检索关于 Active Directory 中的用户和组的信息。本节中配置的属性映射用于构造搜索筛选器和解析组成员身份。因此，所提供的设置需要反映你 AD 域的真实情况。 + +:::note + +如果你不熟悉 Active Directory 域中使用的 Schema，请参见[使用 ldapsearch 确定搜索库和 Schema](#附录使用-ldapsearch-确定搜索库和-schema) 来确定正确的配置值。 + +::: + +#### 用户 Schema + +下表详细说明了用户 Schema 配置的参数。 + +**表 2：用户 Schema 配置参数** + +| 参数 | 描述 | +|:--|:--| +| Object Class | 域中用于用户对象的对象类别名称。如果定义了此参数，则仅指定对象类别的名称 - *请勿*将其放在 LDAP 包装器中，例如 `&(objectClass=xxxx)`。 | +| Username Attribute | 用户属性的值适合作为显示名称。 | +| Login Attribute | 登录属性的值与用户登录 Rancher 时输入的凭证的用户名部分匹配。如果你的用户以他的 UPN（例如 "jdoe@acme.com"）作为用户名进行身份验证，则此字段通常必须设置为 `userPrincipalName`。否则，对于旧的 NetBIOS 风格的登录名（例如 "jdoe"），则通常设为 `sAMAccountName`。 | +| User Member Attribute | 包含用户所属组的属性。 | +| Search Attribute | 当用户输入文本以在用户界面中添加用户或组时，Rancher 会查询 AD 服务器，并尝试根据此设置中提供的属性匹配用户。可以通过使用管道（“\|”）符号分隔属性来指定多个属性。要匹配 UPN 用户名（例如 jdoe@acme.com），通常应将此字段的值设置为 `userPrincipalName`。 | +| Search Filter | 当 Rancher 尝试将用户添加到网站访问列表，或尝试将成员添加到集群或项目时，此筛选器将应用于搜索的用户列表。例如，用户搜索筛选器可能是 (|(memberOf=CN=group1,CN=Users,DC=testad,DC=rancher,DC=io)(memberOf=CN=group2,CN=Users,DC=testad,DC=rancher,DC=io))。注意：如果搜索筛选器未使用[有效的 AD 搜索语法](https://docs.microsoft.com/en-us/windows/win32/adsi/search-filter-syntax)，则用户列表将为空。 | +| User Enabled Attribute | 该属性是一个整数值，代表用户账号标志的枚举。Rancher 使用此选项来确定用户账号是否已禁用。通常应该将此参数设置为 AD 标准的 `userAccountControl`。 | +| Disabled Status Bitmask | 指定的禁用用户账号的 `User Enabled Attribute` 的值。通常，你应该将此参数设置为 Microsoft Active Directory Schema 中指定的默认值 2（请参见[此处](https://docs.microsoft.com/en-us/windows/desktop/adschema/a-useraccountcontrol#remarks)）。 | + +--- + +#### 组 Schema + +下表详细说明了组 Schema 配置的参数。 + +**表 3：组 Schema 配置参数** + +| 参数 | 描述 | +|:--|:--| +| Object Class | 域中用于组对象的对象类别名称。如果定义了此参数，则仅指定对象类别的名称 - *请勿*将其放在 LDAP 包装器中，例如 `&(objectClass=xxxx)`。 | +| Name Attribute | 名称属性的值适合作为显示名称。 | +| Group Member User Attribute | **用户属性**的名称。它的格式与 `Group Member Mapping Attribute` 中的组成员匹配。 | +| Group Member Mapping Attribute | 包含组成员的组属性的名称。 | +| Search Attribute | 在将组添加到集群或项目时，用于构造搜索筛选器的属性。请参见用户 Schema 的 `Search Attribute`。 | +| Search Filter | 当 Rancher 尝试将组添加到网站访问列表，或将组添加到集群或项目时，此筛选器将应用于搜索的组列表。例如，组搜索筛选器可以是 (|(cn=group1)(cn=group2))。注意：如果搜索筛选器未使用[有效的 AD 搜索语法](https://docs.microsoft.com/en-us/windows/win32/adsi/search-filter-syntax)，则组列表将为空。 | +| Group DN Attribute | 组属性的名称，其格式与描述用户成员身份的用户属性中的值匹配。参见 `User Member Attribute`。 | +| Nested Group Membership | 此设置定义 Rancher 是否应解析嵌套组成员身份。仅当你的组织使用这些嵌套成员身份时才使用（即你有包含其他组作为成员的组。我们建议尽量避免使用嵌套组，从而避免在存在大量嵌套成员时出现潜在的性能问题）。 | + +--- + +### 测试身份验证 + +完成配置后，请**使用你的 AD 管理员账户**测试与 AD 服务器的连接。如果测试成功，将启用配置的 Active Directory 身份验证，测试时使用的账号会成为管理员。 + +:::note + +与此步骤中输入的凭证相关的 AD 用户将映射到本地主体账号，并在 Rancher 中分配系统管理员权限。因此，你应该决定使用哪个 AD 账号来执行此步骤。 + +::: + +1. 输入应映射到本地主体账号的 AD 账号的**用户名**和**密码** 。 +2. 点击**启用 Active Directory 认证**来完成设置。 + +**结果**： + +- 已启用 Active Directory 身份验证。 +- 你已使用 AD 凭证以系统管理员身份登录到 Rancher。 + +:::note + +如果 LDAP 服务中断，你仍然可以使用本地配置的 `admin` 账号和密码登录。 + +::: + +## 附录：使用 ldapsearch 确定搜索库和 Schema + +为了成功配置 AD 身份验证，你必须提供 AD 服务器的层次结构和 Schema 的正确配置。 + +[`ldapsearch`](https://manpages.ubuntu.com/manpages/noble/en/man1/ldapsearch.1.html) 工具允许你查询你的 AD 服务器，从而了解用于用户和组对象的 Schema。 + +在下面的示例命令中，我们假设： + +- Active Directory 服务器的主机名是 `ad.acme.com`。 +- 服务器正在监听端口 `389` 上的未加密连接。 +- Active Directory 的域是 `acme`。 +- 你有一个用户名为 `jdoe`，密码为 `secret` 的有效 AD 账号。 + +### 确认搜索库 + +首先，我们将使用 `ldapsearch` 来找到用户和组的父节点的标识名称： + +``` +$ ldapsearch -x -D "acme\jdoe" -w "secret" -p 389 \ +-h ad.acme.com -b "dc=acme,dc=com" -s sub "sAMAccountName=jdoe" +``` + +此命令执行 LDAP 搜索，搜索起点设置为域根目录（`-b "dc=acme,dc=com"`），并执行针对用户账号（`sAMAccountNam=jdoe`）的筛选器，返回所述用户的属性： + +![](/img/ldapsearch-user.png) + +因为在这种情况下，用户的 DN 是 `CN=John Doe,CN=Users,DC=acme,DC=com` [5]，所以我们应该使用父节点 DN `CN=Users,DC=acme,DC=com` 来配置**用户搜索库**。 + +同样，基于 **memberOf** 属性 [4] 中引用的组的 DN，**组搜索库**的值将是该值的父节点，即 `OU=Groups,DC=acme,DC=com`。 + +### 确定用户 Schema + +上述 `ldapsearch` 查询的输出还能用于确定在用户 Schema 配置中使用的值： + +- `Object Class`：**person** [1] +- `Username Attribute`:：**name** [2] +- `Login Attribute`：**sAMAccountName** [3] +- `User Member Attribute`：**memberOf** [4] + +:::note + +如果我们组织中的 AD 用户使用其 UPN（例如 `jdoe@acme.com`）而不是短登录名进行身份验证，则必须将 `Login Attribute` 设置为 **userPrincipalName**。 + +::: + +我们还将 `Search Attribute` 数设置为 **sAMAccountName|name**。这样，用户可以通过输入用户名或全名添加到 Rancher UI 中的集群/项目中。 + +### 确定组 Schema + +接下来，我们将查询与此用户关联的一个组，在本例中为 `CN=examplegroup,OU=Groups,DC=acme,DC=com`： + +``` +$ ldapsearch -x -D "acme\jdoe" -w "secret" -p 389 \ +-h ad.acme.com -b "ou=groups,dc=acme,dc=com" \ +-s sub "CN=examplegroup" +``` + +此命令将告知我们用于组对象的属性： + +![](/img/ldapsearch-group.png) + +同样，这能让我们确定要在组 Schema 配置中输入的值： + +- `Object Class`：**group** [1] +- `Name Attribute`：**name** [2] +- `Group Member Mapping Attribute`：**member** [3] +- `Search Attribute`：**sAMAccountName** [4] + +查看 **member** 属性的值，我们可以看到它包含被引用用户的 DN。这对应我们的用户对象中的 **distinguishedName** 属性。因此，必须将 `Group Member User Attribute` 参数的值设置为此属性。 + +同样，我们可以看到用户对象中 **memberOf** 属性中的值对应组的 **distinguishedName** [5]。因此，我们需要将 `Group DN Attribute` 参数的值设置为此属性。 + +## 附录：故障排除 + +如果在测试与 Active Directory 服务器的连接时遇到问题，请首先仔细检查为 ServiceAccount 输入的凭证以及搜索库配置。你还可以检查 Rancher 日志来查明问题的原因。调试日志可能包含有关错误的更详细信息。详情请参见[如何启用调试日志](../../../../faq/technical-items.md#如何启用调试日志记录)。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/authentication-config/configure-azure-ad.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/authentication-config/configure-azure-ad.md new file mode 100644 index 00000000000..45c5a5d12cb --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/authentication-config/configure-azure-ad.md @@ -0,0 +1,325 @@ +--- +title: 配置 Azure AD +--- + +## Microsoft Graph API + +Microsoft Graph API 现在是设置 Azure AD 的流程。下文将帮助[新用户](#新用户设置)使用新实例来配置 Azure AD，并帮助现有 Azure 应用所有者[迁移到新流程](#从-azure-ad-graph-api-迁移到-microsoft-graph-api)。 + +Rancher 中的 Microsoft Graph API 流程正在不断发展。建议你使用最新的 2.7 补丁版本，该版本仍在积极开发中，并将持续获得新功能和改进。 + +### 新用户设置 + +如果你在 Azure 中托管了一个 Active Directory（AD）实例，你可以将 Rancher 配置为允许你的用户使用 AD 账号登录。你需要在 Azure 和 Rancher 中进行 Azure AD 外部身份验证。 + +:::note 注意事项 + +- Azure AD 集成仅支持服务提供商发起的登录。 +- 大部分操作是从 [Microsoft Azure 门户](https://portal.azure.com/)执行的。 + +::: + +#### Azure Active Directory 配置概述 + +要将 Rancher 配置为允许用户使用其 Azure AD 账号进行身份验证，你需要执行多个步骤。在你开始之前，请查看下文操作步骤大纲。 + +:::tip + +在开始之前，打开两个浏览器选项卡：一个用于 Rancher，另一个用于 Azure 门户。这样，你可以将门户的配置值复制并粘贴到 Rancher 中。 + +::: + + +#### 1. 在 Azure 注册 Rancher + +在 Rancher 中启用 Azure AD 之前，你必须先向 Azure 注册 Rancher。 + +1. 以管理用户身份登录 [Microsoft Azure](https://portal.azure.com/)。后续配置步骤中需要管理访问权限。 + +1. 使用搜索功能打开 **App registrations** 服务。 + +1. 点击 **New registration** 并填写表单。 + + ![New App Registration](/img/new-app-registration.png) + + 1. 输入 **Name**（例如 `Rancher`）。 + + 1. 在 **Supported account types** 中，选择 **Accounts in this organizational directory only (AzureADTest only - Single tenant)**。这对应于旧版应用注册选项。 + + :::note + + 在更新后的 Azure 门户中，Redirect URI 与 Reply URL 的意思相同。为了将 Azure AD 与 Rancher 一起使用，你必须将 Rancher 列入 Azure 白名单（之前通过 Reply URL 完成）。因此，请确保使用你的 Rancher Server URL 填写 Redirect URI，以包含下面列出的验证路径。 + + ::: + + 1. 在 [**Redirect URI**](https://docs.microsoft.com/en-us/azure/active-directory/develop/reply-url) 中，确保从下拉列表中选择 **Web**，并在旁边的文本框中输入 Rancher Server 的 URL。Rancher Server URL 后需要追加验证路径，例如 `/verify-auth-azure`。 + + :::tip + + 你可以在 Azure AD 身份验证页面（全局视图 > Authentication > Web）中找到你 Rancher 中的个性化 Azure Redirect URI（Reply URL）。 + + ::: + + 1. 单击 **Register**。 + +:::note + +此更改可能需要五分钟才能生效。因此，如果在配置 Azure AD 之后无法立即进行身份验证，请不要惊慌。 + +::: + +#### 2. 创建客户端密文 + +在 Azure 门户中，创建一个客户端密文。Rancher 将使用此密钥向 Azure AD 进行身份验证。 + +1. 使用搜索功能打开 **App registrations** 服务。然后打开你在上一个步骤中创建的 Rancher 项。 + + ![Open Rancher Registration](/img/open-rancher-app-reg.png) + +1. 在导航窗格中，单击 **Certificates & secrets**。 + +1. 单击 **New client secret**。 + ![创建新的客户端密文](/img/new-client-secret.png) +1. 输入 **Description**（例如 `Rancher`）。 +1. 从 **Expires** 下的选项中选择持续时间。此下拉菜单设置的是密钥的到期日期。日期越短则越安全，但需要你更频繁地创建新密钥。 + 请注意，如果检测到应用程序 Secret 已过期，用户将无法登录 Rancher。为避免此问题，请在 Azure 中轮换 Secret 并在过期前在 Rancher 中更新它。 +1. 单击 **Add**（无需输入值，保存后会自动填充）。 + + +1. 稍后你将在 Rancher UI 中输入此密钥作为你的 **Application Secret**。由于你将无法在 Azure UI 中再次访问键值，因此请在其余设置过程中保持打开此窗口。 + +#### 3. 设置 Rancher 所需的权限 + +接下来，在 Azure 中为 Rancher 设置 API 权限。 + +:::caution + +确保你设置了 Application 权限，而*不是* Delegated 权限。否则，你将无法登录 Azure AD。 + +::: + +1. 在导航窗格中，选择 **API permissions**。 + +1. 单击 **Add a permission**。 + +1. 从 Microsoft Graph API 中，选择以下 **Application Permissions**: `Directory.Read.All`。 + + ![选择 API 权限](/img/api-permissions.png) + +1. 返回导航栏中的 **API permissions**。在那里，单击 **Grant admin consent**。然后单击 **Yes**。该应用程序的权限应如下所示： + +![Open Required Permissions](/img/select-req-permissions.png) + +:::note + +Rancher 不会验证你授予 Azure 应用程序的权限。你可以自由使用任何你所需的权限，只要这些权限允许 Rancher 使用 AD 用户和组。 + +具体来说，Rancher 需要允许以下操作的权限： +- 获取一个用户。 +- 列出所有用户。 +- 列出给定用户所属的组。 +- 获取一个组。 +- 列出所有组。 + +Rancher 执行这些操作来登录用户或搜索用户/组。请记住，权限必须是 `Application` 类型。 + +下面是几个满足 Rancher 需求的权限组合示例： +- `Directory.Read.All` +- `User.Read.All` 和 `GroupMember.Read.All` +- `User.Read.All` 和 `Group.Read.All` + +::: + +#### 4. 复制 Azure 应用数据 + +![Application ID](/img/app-configuration.png) + +1. 获取你的 Rancher **租户 ID**。 + + 1. 使用搜索打开 **App registrations**。 + + 1. 找到你为 Rancher 创建的项。 + + 1. 复制 **Directory ID** 并将其作为 **Tenant ID** 粘贴到 Rancher 中。 + +1. 获取你的 Rancher **Application (Client) ID**。 + + 1. 如果你还未在该位置，请使用搜索打开 **App registrations**。 + + 1. 在 **Overview**中，找到你为 Rancher 创建的条目。 + + 1. 复制 **Application (Client) ID** 并将其作为 **Application ID** 粘贴到 Rancher 中。 + +1. 你的端点选项通常是 [Standard](#global) 或 [China](#中国)。对于这两个选项，你只需要输入 **Tenant ID**、**Application ID** 和 **Application Secret**。 + +![标准端点选项](/img/tenant-application-id-secret.png) + +**对于自定义端点**： + +:::caution + +Rancher 未测试也未完全支持自定义端点。 + +::: + +你还需要手动输入 Graph、Token 和 Auth Endpoints。 + +- 从 App registrations 中，点击 Endpoints： + +![点击端点](/img/endpoints.png) + +- 以下端点将是你的 Rancher 端点值。请使用这些端点的 v1 版本。 + - **Microsoft Graph API endpoint**（Graph 端点） + - **OAuth 2.0 token endpoint (v1)**（Token 端点） + - **OAuth 2.0 authorization endpoint (v1)** (Auth 端点) + +#### 5. 在 Rancher 中配置 Azure AD + +要完成配置，请在 Rancher UI 中输入你的 AD 实例信息。 + +1. 登录到 Rancher。 + +1. 在左上角，单击 **☰ > 用户 & 认证**。 + +1. 在左侧导航栏，单击**认证**。 + +1. 单击 **AzureAD**。 + +1. 使用你在[复制 Azure 应用数据](#4-复制-azure-应用数据)时复制的信息，填写**配置 Azure AD 账号**的表单。 + + :::caution + + Azure AD 帐户将被授予管理员权限，因为其详细信息将映射到 Rancher 本地主体帐户。在继续之前确保此权限级别是适当的。 + + ::: + + **对于标准或中国端点：** + + 下表介绍了你在 Azure 门户中复制的值与 Rancher 中字段的映射： + + | Rancher 字段 | Azure 值 | + | ------------------ | ------------------------------------- | + | 租户 ID | Directory ID | + | Application ID | Application ID | + | 应用密文 | Key Value | + | 端点 | https://login.microsoftonline.com/ | + + **对于自定义端点**： + + 下表将你的自定义配置值映射到 Rancher 字段： + + | Rancher 字段 | Azure 值 | + | ------------------ | ------------------------------------- | + | Graph 端点 | Microsoft Graph API Endpoint | + | Token 端点 | OAuth 2.0 Token Endpoint | + | Auth 端点 | OAuth 2.0 Authorization Endpoint | + + **重要提示**：在自定义配置中输入 Graph Endpoint 时，请从 URL 中删除 Tenant ID： + + https://graph.microsoft.com/abb5adde-bee8-4821-8b03-e63efdc7701c + +1. 点击**启用**。 + +**结果**：Azure Active Directory 身份验证已配置。 + + +### 从 Azure AD Graph API 迁移到 Microsoft Graph API + +由于 [Azure AD Graph API](https://docs.microsoft.com/en-us/graph/migrate-azure-ad-graph-overview) 已弃用并计划于 2023 年 6 月停用，管理员应更新他们的 Azure AD 应用程序以在 Rancher 中使用 [Microsoft Graph API](https://docs.microsoft.com/en-us/graph/use-the-api)。 +你需要在端点弃用之前完成操作。 +如果在停用后 Rancher 仍配置为使用 Azure AD Graph API，用户可能无法使用 Azure AD 登录 Rancher。 + +#### 在 Rancher UI 中更新端点 + +:::caution + +管理员需要在迁移下述端点之前创建一个 [Rancher 备份](../../../new-user-guides/backup-restore-and-disaster-recovery/back-up-rancher.md)。 + +::: + +1. [更新](#3-设置-rancher-所需的权限) Azure AD 应用程序注册的权限。这个步骤非常关键。 + +1. 登录到 Rancher。 + +1. 在 Rancher UI 主页中，记下屏幕顶部的横幅，该横幅建议用户更新 Azure AD 身份验证。单击提供的链接以执行此操作。 + + ![Rancher UI 横幅](/img/rancher-ui-azure-update.png) + +1. 要完成新的 Microsoft Graph API 迁移，请单击 **Update Endpoint**。 + + **注意**：在开始更新之前，请确保你的 Azure 应用程序具有[新的权限集](#3-设置-rancher-所需的权限)。 + + ![更新端点](/img/rancher-button-to-update.png) + +1. 在收到弹出警告消息时，单击 **Update**： + + ![Azure 更新弹出窗口](/img/azure-update-popup.png) + +1. 有关 Rancher 执行的完整端点更改，请参阅下面的[表格](#global)。管理员不需要手动执行此操作。 + +#### 离线环境 + +在离线环境中，由于 Graph Endpoint URL 正在更改，因此管理员需要确保其端点被[列入白名单](#1-在-azure-注册-rancher)。 + +#### 回滚迁移 + +如果你需要回滚迁移，请注意以下事项： + +1. 如果管理员想要回滚，我们建议他们使用正确的恢复流程。有关参考信息，请参阅[备份文档](../../../new-user-guides/backup-restore-and-disaster-recovery/back-up-rancher.md)、[恢复文档](../../../new-user-guides/backup-restore-and-disaster-recovery/restore-rancher.md)和[示例](../../../../reference-guides/backup-restore-configuration/examples.md)。 + +1. 如果 Azure 应用程序所有者想要轮换应用程序密钥，他们也需要在 Rancher 中进行轮换（因为在 Azure 中更改应用程序密钥时，Rancher 不会自动更新应用程序密钥）。在 Rancher 中，它存储在名为 `azureadconfig-applicationsecret` 的 Kubernetes 密文中，该密文位于 `cattle-global-data` 命名空间中。 + +:::caution + +如果你使用现有的 Azure AD 设置升级到 Rancher v2.7.0+，并选择了禁用认证提供程序，你将无法恢复以前的设置。你也无法使用旧流程设置 Azure AD。你需要使用新的认证流程重新注册。由于 Rancher 现在使用 Graph API，因此用户需要[在 Azure 门户中设置适当的权限](#3-设置-rancher-所需的权限)。 + +::: + + +#### Global: + +| Rancher 字段 | 已弃用的端点 | +---------------- | ------------------------------------------------------------- +| Auth 端点 | https://login.microsoftonline.com/{tenantID}/oauth2/authorize | +| 端点 | https://login.microsoftonline.com/ | +| Graph 端点 | https://graph.windows.net/ | +| Token 端点 | https://login.microsoftonline.com/{tenantID}/oauth2/token | + +| Rancher 字段 | 新端点 | +---------------- | ------------------------------------------------------------------ +| Auth 端点 | https://login.microsoftonline.com/{tenantID}/oauth2/v2.0/authorize | +| 端点 | https://login.microsoftonline.com/ | +| Graph 端点 | https://graph.microsoft.com | +| Token 端点 | https://login.microsoftonline.com/{tenantID}/oauth2/v2.0/token | + +#### 中国： + +| Rancher 字段 | 已弃用的端点 | +---------------- | ---------------------------------------------------------- +| Auth 端点 | https://login.chinacloudapi.cn/{tenantID}/oauth2/authorize | +| 端点 | https://login.chinacloudapi.cn/ | +| Graph 端点 | https://graph.chinacloudapi.cn/ | +| Token 端点 | https://login.chinacloudapi.cn/{tenantID}/oauth2/token | + +| Rancher 字段 | 新端点 | +---------------- | ------------------------------------------------------------------------- +| Auth 端点 | https://login.partner.microsoftonline.cn/{tenantID}/oauth2/v2.0/authorize | +| 端点 | https://login.partner.microsoftonline.cn/ | +| Graph 端点 | https://microsoftgraph.chinacloudapi.cn | +| Token 端点 | https://login.partner.microsoftonline.cn/{tenantID}/oauth2/v2.0/token | + + +## 已弃用的 Azure AD Graph API + +> **重要提示**： +> +> - [Azure AD Graph API](https://docs.microsoft.com/en-us/graph/migrate-azure-ad-graph-overview) 已被弃用，Microsoft 将在 2023 年 6 月 30 日后随时停用它且不会另行通知。我们将更新我们的文档，以便在停用时向社区提供建议。Rancher 现在使用 [Microsoft Graph API](https://docs.microsoft.com/en-us/graph/use-the-api) 来将 Azure AD 设置为外部身份验证提供程序。 +> +> +> - 如果你是新用户或希望进行迁移，请参阅新的流程说明： Rancher v2.7.0+。 +> +> +> - 如果你不想在 Azure AD Graph API 停用后升级到 v2.7.0+，你需要： +> - 使用内置的 Rancher 身份认证，或者 +> - 使用另一个第三方身份认证系统并在 Rancher 中进行设置。请参阅[身份验证文档](./authentication-config.md)，了解如何配置其他开放式身份验证提供程序。 + diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/authentication-config/configure-freeipa.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/authentication-config/configure-freeipa.md new file mode 100644 index 00000000000..eab27ffb571 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/authentication-config/configure-freeipa.md @@ -0,0 +1,60 @@ +--- +title: 配置 FreeIPA +--- + +如果你的组织使用 FreeIPA 进行用户身份验证，你可以通过配置 Rancher 来允许你的用户使用 FreeIPA 凭证登录。 + +:::note 先决条件： + +- 你必须配置了 [FreeIPA 服务器](https://www.freeipa.org/)。 +- 在 FreeIPA 中创建一个具有 `read-only` 访问权限的 ServiceAccount 。当用户使用 API​​ 密钥发出请求时，Rancher 使用此账号来验证组成员身份。 +- 参见[外部身份验证配置和主体用户](./authentication-config.md#外部认证配置和用户主体)。 + +::: + +1. 使用分配了 `administrator` 角色（即 _本地主体_）的本地用户登录到 Rancher。 +1. 在左上角，单击 **☰ > 用户 & 认证**。 +1. 在左侧导航栏，单击**认证**。 +1. 单击 **FreeIPA**。 +1. 填写**配置 FreeIPA 服务器**表单， + + 你可能需要登录到域控制器，来查找表单中请求的信息。 + + :::note 使用 TLS？ + + 如果证书是自签名，或者不是来自公认的证书颁发机构的，请确保提供完整的证书链。Rancher 需要该链来验证服务器的证书。 + + ::: + + :::note 用户搜索库 vs. 组搜索库 + + 搜索库使 Rancher 可以搜索 FreeIPA 中的用户和组。这些字段仅用于搜索库，不适用于搜索筛选器。 + + * 如果你的用户和组位于同一搜索库中，则仅填写用户搜索库。 + * 如果你的组位于其他搜索库中，则可以选择填写组搜索库。该字段专用于搜索组，但不是必需的。 + + ::: + +1. 如果你的 FreeIPA 不同于标准的 AD Schema，则必须完成**自定义 Schema** 部分实现匹配。否则，调过此步骤。 + + :::note 搜索属性 + + `搜索属性`字段的默认值为三个特定值：`uid|sn|givenName`。配置 FreeIPA 后，当用户输入文本以添加用户或组时，Rancher 会自动查询 FreeIPA 服务器，并尝试按用户 ID，姓氏或名字来匹配字段。Rancher 专门搜索以在搜索字段中输入的文本开头的用户/组。 + + 默认字段值为 `uid|sn|givenName`，但是你可以将此字段配置为这些字段的子集。管道符 (`|`) 用于分隔各个字段。 + + * `uid`：用户 ID + * `sn`：姓 + * `givenName`：名 + + Rancher 使用此搜索属性为用户和组创建搜索筛选器，但是你*不能*在此字段中添加自己的搜索筛选器。 + + ::: + +1. 在 **Authenticate with FreeIPA** 中输入你的 FreeIPA 用户名和密码，确认已为 Rancher 配置 FreeIPA 身份验证。 +1. 点击**启用**。 + +**结果**： + +- FreeIPA 验证配置成功。 +- 你将使用你的 FreeIPA 账号（即 _外部主体_）登录到 Rancher。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/authentication-config/configure-github.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/authentication-config/configure-github.md new file mode 100644 index 00000000000..59eb79748fe --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/authentication-config/configure-github.md @@ -0,0 +1,56 @@ +--- +title: 配置 GitHub +--- + +在使用 GitHub 的环境中，你可以通过配置 Rancher 允许用户使用 GitHub 凭证登录。 + +:::note 先决条件： + +参见[外部身份验证配置和主体用户](./authentication-config.md#外部认证配置和用户主体)。 + +::: + +1. 使用分配了 `administrator` 角色（即 _本地主体_）的本地用户登录到 Rancher。 +1. 在左上角，单击 **☰ > 用户 & 认证**。 +1. 在左侧导航栏，单击**认证**。 +1. 单击 **GitHub**。 +1. 按照显示的说明设置 GitHub 应用。Rancher 会将你重定向到 GitHub 完成注册。 + + :::note 什么是授权回调 URL？ + + 授权回调 URL 是用户开始使用你的应用（即初始屏幕）的 URL。 + + 使用外部身份验证时，实际上不会在你的应用中进行身份验证。相反，身份验证在外部进行（在本例中为 GitHub）。在外部身份验证成功完成后，用户将通过授权回调 URL 重新进入应用。 + + ::: + +1. 从 GitHub 复制 **Client ID** 和 **Client Secret**。将它们粘贴到 Rancher 中。 + + :::note 在哪里可以找到 Client ID 和 Client Secret？ + + 在 GitHub 中，选择 **Settings > Developer Settings > OAuth Apps**。你可以在此处找到 Client ID 和 Client Secret。 + + ::: + +1. 单击**使用 GitHub 认证**。 + +1. 使用 **Site Access** 选项来配置用户授权的范围。 + + - **允许任何有效用户** + + _任何_ GitHub 用户都能访问 Rancher。通常不建议使用此设置。 + + - **允许集群和项目成员，以及授权的用户和组织** + + 添加为**集群成员**或**项目成员**的任何 GitHub 用户或组都可以登录 Rancher。此外，任何添加到**授权用户和组织**列表中的 GitHub 用户和组都能登录到 Rancher。 + + - **仅允许授权用户和组织** + + 只有添加到**授权用户和组织**的 GitHub 用户和组能登录 Rancher。 +
+1. 点击**启用**。 + +**结果**： + +- GitHub 验证配置成功。 +- 你将使用你的 GitHub 账号（即 _外部主体_）登录到 Rancher。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/authentication-config/configure-google-oauth.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/authentication-config/configure-google-oauth.md new file mode 100644 index 00000000000..ca4d522ba35 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/authentication-config/configure-google-oauth.md @@ -0,0 +1,111 @@ +--- +title: 配置 Google OAuth +--- + +如果你的组织使用 G Suite 进行用户身份验证，你可以通过配置 Rancher 来允许你的用户使用 G Suite 凭证登录。 + +只有 G Suite 域的管理员才能访问 Admin SDK。因此，只有 G Suite 管理员可以配置 Rancher 的 Google OAuth。 + +在 Rancher 中，只有具有 **Manage Authentication** [全局角色](../../authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/global-permissions.md)的管理员或用户才能配置身份验证。 + +## 先决条件 + +- 你必须配置了 [G Suite 管理员账号](https://admin.google.com)。 +- G Suite 需要一个[顶级私有域 FQDN](https://github.com/google/guava/wiki/InternetDomainNameExplained#public-suffixes-and-private-domains) 作为授权域。获取 FQDN 的一种方法是在 Route53 中为 Rancher Server 创建 A 记录。你不需要使用该记录更新 Rancher Server 的 URL 设置，因为可能有集群使用该 URL。 +- 你的 G Suite 域必须启用了 Admin SDK API。你可以按照[此页面](https://support.google.com/a/answer/60757?hl=en)中的步骤启用它。 + +启用 Admin SDK API 后，你的 G Suite 域的 API 页面应如下图所示： +![Enable Admin APIs](/img/Google-Enable-APIs-Screen.png) + +## 在 Rancher 中为 OAuth 设置 G Suite + +在 Rancher 中设置 Google OAuth 之前，你需要登录到你的 G Suite 账号并完成以下设置： + +1. [在 G Suite 中将 Rancher 添加为授权域](#1-将-rancher-添加为授权域) +1. [为 Rancher Server 生成 OAuth2 凭证](#2-为-rancher-server-生成-oauth2-凭证) +1. [为 Rancher Server 创建 ServiceAccount 凭证](#3-创建-serviceaccount-凭证) +1. [将 ServiceAccount 密钥注册成 OAuth Client](#4-将-serviceaccount-密钥注册成-oauth-client) + +### 1. 将 Rancher 添加为授权域 + +1. 点击[此处](https://console.developers.google.com/apis/credentials)前往你的 Google 域的凭证页面。 +1. 选择你的项目，然后点击 **OAuth consent screen**。 + ![OAuth Consent Screen](/img/Google-OAuth-consent-screen-tab.png) +1. 前往 **Authorized Domains**，并在列表中输入你的 Rancher Server URL 的顶级私有域。顶级私有域是最右边的超级域。例如，`www.foo.co.uk` 是 `foo.co.uk` 的顶级私有域。有关顶级私有域的更多信息，请参见[此处](https://github.com/google/guava/wiki/InternetDomainNameExplained#public-suffixes-and-private-domains)。 +1. 前往 **Scopes for Google APIs**，并确保已启用 **email**，**profile** 和 **openid**。 + +**结果**：Rancher 已被添加为 Admin SDK API 的授权域。 + +### 2. 为 Rancher Server 生成 OAuth2 凭证 + +1. 前往 Google API 控制台，选择你的项目并前往 [credentials ](https://console.developers.google.com/apis/credentials)页面。 + ![Credentials](/img/Google-Credentials-tab.png) +1. 在 **Create Credentials** 下拉框中，选择 **OAuth client ID**。 +1. 点击 **Web application**。 +1. 输入一个名称。 +1. 填写 **Authorized JavaScript origins** 和 **Authorized redirect URIs**。请注意，设置 Google OAuth 的 Rancher UI 页面（**Security > Authentication > Google** 下的全局视图）为你提供了这一步要输入的准确链接。 +- 在 **Authorized JavaScript origins** 处，输入你的 Rancher Server URL。 +- 在 **Authorized redirect URIs** 处，输入你的 Rancher Server 的 URL 并附加路径 `verify-auth`。例如，如果你的 URI 是 `https://rancherServer`，你需要输入 `https://rancherServer/verify-auth`。 +1. 点击 **Create**。 +1. 创建凭证之后，你将看到一个页面，其中显示你的凭证列表。选择刚刚创建的凭证，然后在最右边的行中单击 **Download JSON**。保存该文件，以便向 Rancher 提供这些凭证。 + +**结果**：你已成功创建 OAuth 凭证。 + +### 3. 创建 ServiceAccount 凭证 +由于 Google Admin SDK 只对管理员可用，普通用户不能使用它来检索其他用户或其组的配置文件。普通用户甚至不能检索他们自己的组。 + +由于 Rancher 提供基于组的成员访问，我们要求用户能够获得自己的组，并在需要时查找其他用户和组。 + +为了解决这个问题，G Suite 建议创建一个 ServiceAccount，并将你的 G Suite 域的权限委托给该 ServiceAccount。 + +本节介绍如何： + +- 创建一个 ServiceAccount +- 为 ServiceAccount 创建一个密钥并下载 JSON 格式的凭证 + +1. 点击[此处](https://console.developers.google.com/iam-admin/serviceaccounts)并选择要生成 OAuth 凭证的项目。 +1. 点击 **Create Service Account**。 +1. 输入名称，并点击 **Create**。 + ![Service account creation Step 1](/img/Google-svc-acc-step1.png) +1. 不要在 **Service account permissions** 页面设置任何角色，然后单击 **Continue**。 + ![Service account creation Step 2](/img/Google-svc-acc-step2.png) +1. 点击 **Create Key** 并选择 JSON 选项。下载并保存 JSON 文件，以便你可以将其作为 ServiceAccount 凭证提供给 Rancher。 + ![Service account creation Step 3](/img/Google-svc-acc-step3-key-creation.png) + +**结果**：你的 ServiceAccount 已创建成功。 + +### 4. 将 ServiceAccount 密钥注册成 OAuth Client + +你需要为在上一步中创建的 ServiceAccount 授予一些权限。Rancher 仅要求为用户和组授予只读权限。 + +使用 ServiceAccount 密钥的唯一 ID，按照以下步骤将其注册为 Oauth Client： + +1. 获取你刚刚创建的密钥的唯一 ID。如果它没有显示在你创建的键旁边的键列表中，你需要先启用 Unique ID 列。点击 **Unique ID** 然后点击 **OK**。这将向 ServiceAccount 密钥列表中添加 **Unique ID** 列。保存你创建的 ServiceAccount 对应的唯一 ID。注意：这是一个数字 Key，不要与字母数字字段 **Key ID** 混淆。 + + ![Service account Unique ID](/img/Google-Select-UniqueID-column.png) +1. 前往 [**Domain-wide Delegation** 页面。](https://admin.google.com/ac/owl/domainwidedelegation) +1. 在 **Client Name** 字段中添加上一步中获得的唯一 ID。 +1. 在 **One or More API Scopes** 字段中，添加以下作用域： + ``` + openid,profile,email,https://www.googleapis.com/auth/admin.directory.user.readonly,https://www.googleapis.com/auth/admin.directory.group.readonly + ``` +1. 点击 **Authorize**。 + +**结果**：ServiceAccount 在你的 G Suite 账号中已注册为 OAuth 客户端。 + +## 在 Rancher 中配置 Google OAuth + +1. 使用分配了 [administrator](../../authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/global-permissions.md) 角色的本地用户登录到 Rancher。这个用户也称为本地主体。 +1. 在左上角，单击 **☰ > 用户 & 认证**。 +1. 在左侧导航栏，单击**认证**。 +1. 单击 **Google**。UI 中的说明介绍了使用 Google OAuth 设置身份验证的步骤。 + 1. 管理员邮箱：提供 GSuite 设置中的管理员账户的电子邮箱。为了查找用户和组，Google API 需要管理员的电子邮件和 ServiceAccount 密钥。 + 1. 域名：提供配置了 G Suite 的域。请提供准确的域，而不是别名。 + 1. 属于多个用户组的用户：选中此框以启用嵌套组成员关系。Rancher 管理员可以在配置认证后的任何时候禁用它。 + - **步骤一**是将 Rancher 添加为授权域（详情请参见[本节](#1-将-rancher-添加为授权域)）。 + - **步骤二**提供你完成[本节](#2-为-rancher-server-生成-oauth2-凭证)后下载的 OAuth 凭证 JSON。你可以上传文件或将内容粘贴到 **OAuth Credentials** 字段。 + - **步骤三**提供在[本节](#3-创建-serviceaccount-凭证)末尾下载的 ServiceAccount 凭证 JSON。仅当你成功[在 G Suite 账号中将 ServiceAccount 密钥注册为 OAuth Client](#4-将-serviceaccount-密钥注册成-oauth-client) 后，凭证才能正常工作。 +1. 点击**使用 Google 认证**。 +1. 点击**启用**。 + +**结果**：Google 验证配置成功。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/authentication-config/configure-keycloak-oidc.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/authentication-config/configure-keycloak-oidc.md new file mode 100644 index 00000000000..1107624b52c --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/authentication-config/configure-keycloak-oidc.md @@ -0,0 +1,185 @@ +--- +title: 配置 Keycloak (OIDC) +description: 创建 Keycloak OpenID Connect (OIDC) 客户端并配置 Rancher 以使用 Keycloak。你的用户将能够使用他们的 Keycloak 登录名登录 Rancher。 +--- + +如果你的组织使用 [Keycloak Identity Provider (IdP)](https://www.keycloak.org) 进行用户身份验证，你可以通过配置 Rancher 来允许用户使用 IdP 凭证登录。Rancher 支持使用 OpenID Connect (OIDC) 协议和 SAML 协议来集成 Keycloak。与 Rancher 一起使用时，这两种实现在功能上是等效的。本文描述了配置 Rancher 以通过 OIDC 协议与 Keycloak 一起使用的流程。 + +如果你更喜欢将 Keycloak 与 SAML 协议一起使用，请参见[此页面](configure-keycloak-saml.md)。 + +如果你有使用 SAML 协议的现有配置并希望切换到 OIDC 协议，请参见[本节](#从-saml-迁移到-oidc)。 + +## 先决条件 + +- 已在 Rancher 上禁用 Keycloak (SAML)。 +- 你必须配置了 [Keycloak IdP 服务器](https://www.keycloak.org/guides#getting-started)。 +- Follow the [Keycloak documentation](https://www.keycloak.org/docs/latest/server_admin/#proc-creating-oidc-client_server_administration_guide) to create a new OIDC client with the settings below. + + | 设置 | 值 | + |------------|------------| + | `Client ID` | <client-id> (例如 `rancher`) | + | `Name` | <client-name> (例如 `rancher`) | + | `Client type` | `OpenID Connect` | + | `Client authentication` | `ON` | + | `Valid Redirect URI` | `https://yourRancherHostURL/verify-auth` | + +- 在新的 OIDC 客户端中，创建 [Mappers](https://www.keycloak.org/docs/latest/server_admin/#_protocol-mappers) 来公开用户字段。 + 1. In the navigation menu, click **Clients**. + 1. Click the **Clients list** tab. + 1. Find and click the client you created. + 1. Click the **Client scopes** tab. + 1. Find and click the link labeled `-dedicated`. For example, if you named your client `rancher`, look for the link named `rancher-dedicated`. + 1. Click the **Mappers** tab. + 1. Click **Configure a new mapper**. If you already have existing mappers configured, click the arrow next to **Add mapper** and select **By configuration**. Repeat this process and create these mappers: + - From the mappings table, select **Group Membership** and configure a new "Groups Mapper" with the settings below. For settings that are not mentioned, use the default value. + + | Setting | Value | + | ------------|------------| + | `Name` | `Groups Mapper` | + | `Mapper Type` | `Group Membership` | + | `Token Claim Name` | `groups` | + | `Full group path` | `OFF` | + | `Add to ID token` | `OFF` | + | `Add to access token` | `OFF` | + | `Add to user info` | `ON` | + + - From the mappings table, select **Audience** and configure a new "Client Audience" with the settings below. For settings that are not mentioned, use the default value. + + | Setting | Value | + | ------------|------------| + | `Name` | `Client Audience` | + | `Mapper Type` | `Audience` | + | `Included Client Audience` | <client-name> | + | `Add to ID token` | `OFF` | + | `Add to access token` | `ON` | + + - From the mappings table, select **Group Membership** and configure a new "Groups Path" with the settings below. For settings that are not mentioned, use the default value. + + | Setting | Value | + | ------------|------------| + | `Name` | `Group Path` | + | `Mapper Type` | `Group Membership` | + | `Token Claim Name` | `full_group_path` | + | `Full group path` | `ON` | + | `Add to ID token` | `ON` | + | `Add to access token` | `ON` | + | `Add to user info` | `ON` | + +- Add the following role mappings to all users or groups that need to query the Keycloak users. + + + + +1. In the navigation menu, click **Users**. +1. Click the user you want to add role mappings to. +1. Click the **Role mapping** tab. +1. Click **Assign role**. +1. Select the following roles: + - query-users + - query-groups + - view-users +1. Click **Assign**. + + + + +1. In the navigation menu, click **Groups**. +1. Click the group you want to add role mappings to. +1. Click the **Role mapping** tab. +1. Click **Assign role**. +1. Select the following roles: + - query-users + - query-groups + - view-users +1. Click **Assign**. + + + + +## 在 Rancher 中配置 Keycloak + +1. 在 Rancher UI 中，单击 **☰ > 用户 & 认证**。 +1. 单击左侧导航栏的**认证**。 +1. 选择 **Keycloak (OIDC)**。 +1. 填写**配置 Keycloak OIDC 账号**表单。有关填写表单的帮助，请参见[配置参考](#配置参考)。 + + :::note + + When configuring the **Endpoints** section using the **Generate** option, Rancher includes `/auth` as part of the context path in the **Issuer** and **Auth Endpoint** fields, which is only valid for Keycloak 16 or older. You must configure endpoints using the **Specify** option for [Keycloak 17](https://www.keycloak.org/docs/latest/release_notes/index.html#keycloak-17-0-0) and newer, which have [migrated to Quarkus](https://www.keycloak.org/migration/migrating-to-quarkus). + + ::: + +1. 完成**配置 Keycloak OIDC 账号**表单后，单击**启用**。 + + Rancher 会将你重定向到 IdP 登录页面。输入使用 Keycloak IdP 进行身份验证的凭证，来验证你的 Rancher Keycloak 配置。 + + :::note + + 你可能需要禁用弹出窗口阻止程序才能看到 IdP 登录页面。 + + ::: + +**结果**：已将 Rancher 配置为使用 OIDC 协议与 Keycloak 一起工作。你的用户现在可以使用 Keycloak 登录名登录 Rancher。 + +:::note SAML 认证警告 + +- Users and groups aren't validated when you assign permissions to them in Rancher. +- 添加用户时，必须正确输入确切的用户 ID（即 UID 字段）。键入用户 ID 时，将不会搜索可能匹配的其他用户 ID。 +- 添加组时，必须从文本框旁边的下拉列表中选择组。Rancher 假定来自文本框的任何输入都是用户。 +- The group drop-down shows only the groups that you are a member of. However, if you have Administrator permissions or Restricted Administrator permissions, you can join a group that you are not a member of. + +::: + +## 配置参考 + +| 字段 | 描述 | +| ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | +| 客户端 ID | 你的 Keycloak 客户端的 `Client ID`。 | +| 客户端密码 | 你的 Keycloak 客户端生成的 `Secret`。在 Keycloak 控制台中，单击 **Clients**，选择你创建的客户端，选择 **Credentials** 选项卡，然后复制 `Secret` 字段的值。 | +| 私钥/证书 | 在 Rancher 和你的 IdP 之间创建安全外壳（SSH）的密钥/证书对。如果你的 Keycloak 服务器上启用了 HTTPS/SSL，则为必填。 | +| 端点 | 选择为 `Rancher URL`、`发行者`和 `Auth 端点`字段使用生成的值，还是在不正确时进行手动覆盖。 | +| Keycloak URL | 你的 Keycloak 服务器的 URL。 | +| Keycloak Realm | 创建 Keycloak 客户端的 Realm 的名称。 | +| Rancher URL | Rancher Server 的 URL。 | +| Issuer | 你的 IdP 的 URL。 | +| Auth 端点 | 重定向用户进行身份验证的 URL。 | + +## 从 SAML 迁移到 OIDC + +本节描述了将使用 Keycloak (SAML) 的 Rancher 过渡到 Keycloak (OIDC) 的过程。 + +1. Reconfigure Keycloak. + 1. Configure a new `OpenID Connect` client according to the [Prerequisites](#先决条件). Ensure the same `Valid Redirect URIs` are set. + 1. Configure mappers for the new client according to the [Prerequisites](#先决条件). +1. Before configuring Rancher to use Keycloak (OIDC), Keycloak (SAML) must be first disabled. + 1. In the Rancher UI, click **☰ > Users & Authentication**. + 1. In the left navigation bar, click **Auth Provider**. + 1. Select **Keycloak (SAML)**. + 1. Click **Disable**. +1. Follow the steps in [Configuring Keycloak in Rancher](#在-rancher-中配置-keycloak). + +:::caution + +配置完成后，由于用户权限不会自动迁移，你需要重新申请 Rancher 用户权限。 + +::: + +## 附录：故障排除 + +如果你在测试与 Keycloak 服务器的连接时遇到问题，请先检查 OIDC 客户端的配置选项。你还可以检查 Rancher 日志来查明问题的原因。调试日志可能包含有关错误的更详细信息。详情请参见[如何启用调试日志](../../../../faq/technical-items.md#如何启用调试日志记录)。 + +所有与 Keycloak 相关的日志条目都将添加 `[generic oidc]` 或 `[keycloak oidc]`。 + +### 不能重定向到 Keycloak + +完成**配置 Keycloak OIDC 账号**表单并单击**启用**后，你没有被重定向到你的 IdP。 + +验证你的 Keycloak 客户端配置。 + +### 生成的 `Issuer` 和 `Auth 端点`不正确 + +在**配置 Keycloak OIDC 账号**表单中，将**端点**更改为`指定（高级设置）`并覆盖`发行者` 和 `Auth 端点`的值。要查找这些值，前往 Keycloak 控制台并选择 **Realm Settings**，选择 **General** 选项卡，然后单击 **OpenID Endpoint Configuration**。JSON 输出将显示 `issuer` 和 `authorization_endpoint` 的值。 + +### Keycloak 错误："Invalid grant_type" + +在某些情况下，这条错误提示信息可能有误导性，实际上造成错误的原因是 `Valid Redirect URI` 配置错误。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/authentication-config/configure-keycloak-saml.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/authentication-config/configure-keycloak-saml.md new file mode 100644 index 00000000000..9fbe04001f1 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/authentication-config/configure-keycloak-saml.md @@ -0,0 +1,194 @@ +--- +title: 配置 Keycloak (SAML) +description: 创建 Keycloak SAML 客户端并配置 Rancher 以使用 Keycloak。你的用户将能够使用他们的 Keycloak 登录名登录 Rancher。 +--- + +如果你的组织使用 Keycloak Identity Provider (IdP) 进行用户身份验证，你可以通过配置 Rancher 来允许用户使用 IdP 凭证登录。 + +## 先决条件 + +- 你必须配置了 [Keycloak IdP 服务器](https://www.keycloak.org/guides#getting-started)。 +- 在 Keycloak 中，使用以下设置创建一个[新的 SAML 客户端](https://www.keycloak.org/docs/latest/server_admin/#saml-clients)。如需获取帮助，请参见 [Keycloak 文档](https://www.keycloak.org/docs/latest/server_admin/#saml-clients)。 + + | 设置 | 值 | + ------------|------------ + | `Sign Documents` | `ON` 1 | + | `Sign Assertions` | `ON` 1 | + | 所有其他 `ON/OFF` 设置 | `OFF` | + | `Client ID` | 输入 `https://yourRancherHostURL/v1-saml/keycloak/saml/metadata`，或在 Rancher Keycloak 配置2 中 `Entry ID 字段`的值。 | + | `Client Name` | (例如 `rancher`) | + | `Client Protocol` | `SAML` | + | `Valid Redirect URI` | `https://yourRancherHostURL/v1-saml/keycloak/saml/acs` | + + > 1：可以选择启用这些设置中的一个或两个。 + > 2：在配置和保存 SAML 身份提供商之前，不会生成 Rancher SAML 元数据。 + + ![](/img/keycloak/keycloak-saml-client-configuration.png) + +- 在新的 SAML 客户端中，创建 Mappers 来公开用户字段。 + - 添加所有 "Builtin Protocol Mappers" + ![](/img/keycloak/keycloak-saml-client-builtin-mappers.png) + - 创建一个 "Group list" mapper，来将成员属性映射到用户的组： + ![](/img/keycloak/keycloak-saml-client-group-mapper.png) + +## 获取 IDP 元数据 + + + + +要获取 IDP 元数据，请从 Keycloak 客户端导出 `metadata.xml` 文件。 +在**安装**选项卡中，选择**SAML 元数据 IDPSSODescriptor** 格式选项并下载你的文件。 + + + + +1. 在**配置**中，单击 **Realm 设置**选项卡。 +1. 点击**通用**选项卡。 +1. 在**端点**字段中，单击 **SAML 2.0 身份提供者元数据**。 + +验证 IDP 元数据是否包含以下属性： + +``` +xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" +xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion" +xmlns:ds="http://www.w3.org/2000/09/xmldsig#" +``` + +某些浏览器（例如 Firefox）可能会渲染/处理文档，使得内容看起来已被修改，并且某些属性看起来可能有缺失。在这种情况下，请使用通过浏览器找到的原始响应数据。 + +以下是 Firefox 的示例流程，其他浏览器可能会略有不同： + +1. 按下 **F12** 访问开发者控制台。 +1. 点击 **Network** 选项卡。 +1. 从表中，单击包含 `descriptor` 的行。 +1. 在 details 窗格中，单击 **Response** 选项卡。 +1. 复制原始响应数据。 + +获得的 XML 以 `EntitiesDescriptor` 作为根元素。然而，Rancher 希望根元素是 `EntityDescriptor` 而不是 `EntitiesDescriptor`。因此，在将这个 XML 传递给 Rancher 之前，请按照以下步骤调整： + +1. 将所有不存在的属性从 `EntitiesDescriptor` 复制到 `EntityDescriptor`。 +1. 删除开头的 `` 标签。 +1. 删除 xml 末尾的 ``。 + +最后的代码会是如下： + +``` + +.... + +``` + + + + +1. 在**配置**中，单击 **Realm 设置**选项卡。 +1. 点击**通用**选项卡。 +1. 在**端点**字段中，单击 **SAML 2.0 身份提供者元数据**。 + +验证 IDP 元数据是否包含以下属性： + +``` +xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" +xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion" +xmlns:ds="http://www.w3.org/2000/09/xmldsig#" +``` + +某些浏览器（例如 Firefox）可能会渲染/处理文档，使得内容看起来已被修改，并且某些属性看起来可能有缺失。在这种情况下，请使用通过浏览器找到的原始响应数据。 + +以下是 Firefox 的示例流程，其他浏览器可能会略有不同： + +1. 按下 **F12** 访问开发者控制台。 +1. 点击 **Network** 选项卡。 +1. 从表中，单击包含 `descriptor` 的行。 +1. 在 details 窗格中，单击 **Response** 选项卡。 +1. 复制原始响应数据。 + + + + +## 在 Rancher 中配置 Keycloak + + +1. 在左上角，单击 **☰ > 用户 & 认证**。 +1. 在左侧导航栏，单击**认证**。 +1. 单击 **Keycloak SAML**。 +1. 填写**配置 Keycloak 账号**表单。有关填写表单的帮助，请参见[配置参考](#配置参考)。 +1. 完成**配置 Keycloak 账号**表单后，单击**启用**。 + + Rancher 会将你重定向到 IdP 登录页面。输入使用 Keycloak IdP 进行身份验证的凭证，来验证你的 Rancher Keycloak 配置。 + + :::note + + 你可能需要禁用弹出窗口阻止程序才能看到 IdP 登录页面。 + + ::: + +**结果**：已将 Rancher 配置为使用 Keycloak。你的用户现在可以使用 Keycloak 登录名登录 Rancher。 + +:::note SAML 身份提供商注意事项 + +- SAML 协议不支持搜索或查找用户或组。因此，将用户或组添加到 Rancher 时不会对其进行验证。 +- 添加用户时，必须正确输入确切的用户 ID（即 `UID` 字段）。键入用户 ID 时，将不会搜索可能匹配的其他用户 ID。 +- 添加组时，必须从文本框旁边的下拉列表中选择组。Rancher 假定来自文本框的任何输入都是用户。 +- 用户组下拉列表仅显示你所属的用户组。如果你不是某个组的成员，你将无法添加该组。 + +::: + +## 配置参考 + +| 字段 | 描述 | +| ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | +| 显示名称字段 | 包含用户显示名称的属性。

示例：`givenName` | +| 用户名字段 | 包含用户名/给定名称的属性。

示例：`email` | +| UID 字段 | 每个用户独有的属性。

示例：`email` | +| 用户组字段 | 创建用于管理组成员关系的条目。

示例：`member` | +| Entity ID 字段 | Keycloak 客户端中需要配置为客户端的 ID。

默认值：`https://yourRancherHostURL/v1-saml/keycloak/saml/metadata` | +| Rancher API 主机 | Rancher Server 的 URL。 | +| 私钥/证书 | 在 Rancher 和你的 IdP 之间创建安全外壳（SSH）的密钥/证书对。 | +| IDP 元数据 | 从 IdP 服务器导出的 `metadata.xml` 文件。 | + +:::tip + +你可以使用 openssl 命令生成一个密钥/证书对。例如： + +openssl req -x509 -sha256 -nodes -days 365 -newkey rsa:2048 -keyout myservice.key -out myservice.cert + +::: + +## 附录：故障排除 + +如果你在测试与 Keycloak 服务器的连接时遇到问题，请先检查 SAML 客户端的配置选项。你还可以检查 Rancher 日志来查明问题的原因。调试日志可能包含有关错误的更详细信息。详情请参见[如何启用调试日志](../../../../faq/technical-items.md#如何启用调试日志记录)。 + +### 不能重定向到 Keycloak + +点击**使用 Keycloak 认证**时，没有重定向到你的 IdP。 + +* 验证你的 Keycloak 客户端配置。 +* 确保 `Force Post Binding` 设为 `OFF`。 + + +### IdP 登录后显示禁止消息 + +你已正确重定向到你的 IdP 登录页面，并且可以输入凭证，但是之后收到 `Forbidden` 消息。 + +* 检查 Rancher 调试日志。 +* 如果日志显示 `ERROR: either the Response or Assertion must be signed`，确保 `Sign Documents` 或 `Sign assertions` 在 Keycloak 客户端中设置为 `ON`。 + +### 访问 `/v1-saml/keycloak/saml/metadata` 时返回 HTTP 502 + +常见原因：配置 SAML 提供商之前未创建元数据。 +尝试配置 Keycloak，并将它保存为你的 SAML 提供商，然后访问元数据。 + +### Keycloak 错误："We're sorry, failed to process response" + +* 检查你的 Keycloak 日志。 +* 如果日志显示 `failed: org.keycloak.common.VerificationException: Client does not have a public key`，请在 Keycloak 客户端中将 `Encrypt Assertions` 设为 `OFF`。 + +### Keycloak 错误："We're sorry, invalid requester" + +* 检查你的 Keycloak 日志。 +* 如果日志显示 `request validation failed: org.keycloak.common.VerificationException: SigAlg was null`，请在 Keycloak 客户端中将 `Client Signature Required` 设为 `OFF`。 + +## Configuring SAML Single Logout (SLO) + + diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/authentication-config/configure-okta-saml.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/authentication-config/configure-okta-saml.md new file mode 100644 index 00000000000..7e0ff7decb6 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/authentication-config/configure-okta-saml.md @@ -0,0 +1,111 @@ +--- +title: 配置 Okta (SAML) +--- + +如果你的组织使用 Okta Identity Provider (IdP) 进行用户身份验证，你可以通过配置 Rancher 来允许用户使用 IdP 凭证登录。 + +:::note + +Okta 集成仅支持服务提供商发起的登录。 + +::: +## 先决条件 + +在 Okta 中，使用以下设置创建一个新的 SAML 应用。如需获取帮助，请参见 [Okta 文档](https://developer.okta.com/standards/SAML/setting_up_a_saml_application_in_okta)。 + +| 设置 | 值 | +------------|------------ +| `Single Sign on URL` | `https://yourRancherHostURL/v1-saml/okta/saml/acs` | +| `Audience URI (SP Entity ID)` | `https://yourRancherHostURL/v1-saml/okta/saml/metadata` | + +## 在 Rancher 中配置 Okta + +你可以将 Okta 与 Rancher 集成，以便经过身份认证的用户通过组权限访问 Rancher 资源。Okta 会返回一个对用户进行身份认证的 SAML 断言，包括用户所属的组。 + +1. 在左上角，单击 **☰ > 用户 & 认证**。 +1. 在左侧导航栏，单击**认证**。 +1. 单击 **Okta**。 +1. 填写**配置 Okta 账号**表单。下面的示例描述了如何将 Okta 属性从属性语句映射到 Rancher 中的字段： + + | 字段 | 描述 | + | ------------------------- | ----------------------------------------------------------------------------- | + | 显示名称字段 | 属性语句中包含用户显示名称的属性名称。 | + | 用户名字段 | 属性语句中包含用户名/给定名称的属性名称。 | + | UID 字段 | 属性语句中每个用户唯一的属性名称。 | + | 用户组字段 | 组属性语句中公开你的组的属性名称。 | + | Rancher API 主机 | Rancher Server 的 URL。 | + | 私钥/证书 | 密钥/证书对，用于断言加密。 | + | 元数据 XML | 你在应用 `Sign On` 部分中找到的 `Identity Provider metadata` 文件。 | + + :::tip + + 你可以使用 openssl 命令生成一个密钥/证书对。例如： + + ``` + openssl req -x509 -sha256 -nodes -days 365 -newkey rsa:2048 -keyout myservice.key -out myservice.crt + ``` + + ::: + + +1. 完成**配置 Okta 账号**表单后，单击**启用**。 + + Rancher 会将你重定向到 IdP 登录页面。输入使用 Okta IdP 进行身份验证的凭证，来验证你的 Rancher Okta 配置。 + + :::note + + 如果什么都没有发生，很可能是因为你的浏览器阻止了弹出窗口。请在弹出窗口阻止程序中禁用 Rancher 域，并在其他类似扩展中将 Rancher 列入白名单。 + + ::: + +**结果**：已将 Rancher 配置为使用 Okta。你的用户现在可以使用 Okta 登录名登录 Rancher。 + +:::note SAML 身份提供商注意事项 + +如果你在没有 OpenLDAP 的情况下配置 Okta，你将无法搜索或直接查找用户或组。相关的警告如下： + +- 在 Rancher 中为用户和组分配权限时将不会验证用户和组。 +- 添加用户时，必须正确输入确切的用户 ID（即 `UID` 字段）。键入用户 ID 时，将不会搜索可能匹配的其他用户 ID。 +- 添加组时，必须从文本框旁边的下拉列表中选择组。Rancher 假定来自文本框的任何输入都是用户。 +- The group drop-down shows only the groups that you are a member of. However, if you have Administrator permissions or restricted Administrator permissions, you can join a group that you are not a member of. + +::: + +## Okta 与 OpenLDAP 搜索 + +你可以添加 OpenLDAP 后端来协助用户和组搜索。Rancher 将显示来自 OpenLDAP 服务的其他用户和组。这允许你将权限分配给用户不属于的组。 + +### OpenLDAP 先决条件 + +如果你使用 Okta 作为 IdP，你可以[设置 LDAP 接口](https://help.okta.com/en-us/Content/Topics/Directory/LDAP-interface-main.htm)以供 Rancher 使用。你还可以配置外部 OpenLDAP Server。 + +你必须使用 LDAP 绑定帐户（也称为 ServiceAccount）来配置 Rancher，以便搜索和检索应具有访问权限的用户和组的 LDAP 条目。不要使用管理员帐户或个人帐户作为 LDAP 绑定帐户。在 OpenLDAP 中[创建](https://help.okta.com/en-us/Content/Topics/users-groups-profiles/usgp-add-users.htm)一个专用帐户，对搜索库下的用户和组具有只读访问权限。 + +:::warning 安全注意事项 + +OpenLDAP ServiceAccount 用于所有搜索。无论用户个人的 SAML 权限是什么，Rancher 用户都将看到 OpenLDAP ServiceAccount 可以查看的用户和组。 + +::: + + +> **使用 TLS？** +> +> 如果 OpenLDAP Server 使用的证书是自签名的或来自无法识别的证书颁发机构，则 Rancher 需要 PEM 格式的 CA 证书（包含所有中间证书）。你需要在配置期间提供此证书，以便 Rancher 能够验证证书链。 + +### 在 Rancher 中配置 OpenLDAP + +[配置 OpenLDAP Server、组和用户的设置](../configure-openldap/openldap-config-reference.md)。请注意，不支持嵌套组成员。 + +> 在继续配置之前，请熟悉[外部身份认证配置和主要用户](./authentication-config.md#外部认证配置和用户主体)。 + +1. 使用分配了 [administrator](https://ranchermanager.docs.rancher.com/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/global-permissions) 角色（即 _本地主体_）的本地用户登录到 Rancher。 +1. 在左上角，单击 **☰ > 用户 & 认证**。 +1. 在左侧导航栏，单击**认证**。 +1. 单击 **Okta**，如果已配置 SAML，则单击**编辑配置**。 +1. 在**用户和组搜索**下，选中**配置 OpenLDAP Server**。 + +如果你在测试与 OpenLDAP Server 的连接时遇到问题，请确保你输入了ServiceAccount 的凭证并正确配置了搜索库。你可以检查 Rancher 日志来查明根本原因。调试日志可能包含有关错误的更详细信息。请参阅[如何启用调试日志](../../../../faq/technical-items.md#如何启用调试日志记录)了解更多信息。 + +## Configuring SAML Single Logout (SLO) + + diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/authentication-config/configure-pingidentity.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/authentication-config/configure-pingidentity.md new file mode 100644 index 00000000000..a37eb4015e3 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/authentication-config/configure-pingidentity.md @@ -0,0 +1,66 @@ +--- +title: 配置 PingIdentity (SAML) +--- + +如果你的组织使用 Ping Identity Provider (IdP) 进行用户身份验证，你可以通过配置 Rancher 来允许用户使用 IdP 凭证登录。 + +> **先决条件**： +> +> - 你必须配置了 [Ping IdP 服务器](https://www.pingidentity.com/)。 +> - 以下是 Rancher Service Provider 配置所需的 URL： +> 元数据 URL：`https:///v1-saml/ping/saml/metadata` +> 断言使用者服务 (ACS) URL：`https:///v1-saml/ping/saml/acs` +> 请注意，在 Rancher 中保存验证配置之前，这些 URL 不会返回有效数据。 +> - 从 IdP 服务器导出 `metadata.xml` 文件。详情请参见 [PingIdentity 文档](https://documentation.pingidentity.com/pingfederate/pf83/index.shtml#concept_exportingMetadata.html)。 + +1. 在左上角，单击 **☰ > 用户 & 认证**。 +1. 在左侧导航栏，单击**认证**。 +1. 单击 **Ping Identity**。 +1. 填写**配置 Ping 账号**表单。Ping IdP 允许你指定要使用的数据存储。你可以添加数据库或使用现有的 ldap 服务器。例如，如果你选择 Active Directory (AD) 服务器，下面的示例将描述如何将 AD 属性映射到 Rancher 中的字段： + + 1. **显示名称字段**：包含用户显示名称的 AD 属性（例如：`displayName`）。 + + 1. **用户名字段**：包含用户名/给定名称的 AD 属性（例如：`givenName`）。 + + 1. **UID 字段**：每个用户唯一的 AD 属性（例如：`sAMAccountName`、`distinguishedName`）。 + + 1. **用户组字段**: 创建用于管理组成员关系的条目（例如：`memberOf`）。 + + 1. **Entity ID 字段**（可选）：你的合作伙伴已公布的、依赖协议的、唯一的标识符。该 ID 将你的组织定义为将服务器用于 SAML 2.0 事务的实体。这个 ID 可以通过带外传输或 SAML 元数据文件获得。 + + 1. **Rancher API 主机**：你的 Rancher Server 的 URL。 + + 1. **私钥**和**证书**：密钥/证书对，用于在 Rancher 和你的 IdP 之间创建一个安全外壳（SSH）。 + + 你可以使用 openssl 命令进行创建。例如： + + ``` + openssl req -x509 -newkey rsa:2048 -keyout myservice.key -out myservice.cert -days 365 -nodes -subj "/CN=myservice.example.com" + ``` + 1. **IDP 元数据**：[从 IdP 服务器导出的 `metadata.xml` 文件](https://documentation.pingidentity.com/pingfederate/pf83/index.shtml#concept_exportingMetadata.html)。 + + +1. 完成**配置 Ping 账号**表单后，单击**启用**。 + + Rancher 会将你重定向到 IdP 登录页面。输入使用 Ping IdP 进行身份验证的凭证，来验证你的 Rancher PingIdentity 配置。 + + :::note + + 你可能需要禁用弹出窗口阻止程序才能看到 IdP 登录页面。 + + ::: + +**结果**：已将 Rancher 配置为使用 PingIdentity。你的用户现在可以使用 PingIdentity 登录名登录 Rancher。 + +:::note SAML 身份提供商注意事项 + +- SAML 协议不支持搜索或查找用户或组。因此，将用户或组添加到 Rancher 时不会对其进行验证。 +- 添加用户时，必须正确输入确切的用户 ID（即 `UID` 字段）。键入用户 ID 时，将不会搜索可能匹配的其他用户 ID。 +- 添加组时，必须从文本框旁边的下拉列表中选择组。Rancher 假定来自文本框的任何输入都是用户。 +- The group drop-down shows only the groups that you are a member of. However, if you have Administrator permissions or restricted Administrator permissions, you can join a group that you are not a member of. + +::: + +## Configuring SAML Single Logout (SLO) + + diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/authentication-config/create-local-users.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/authentication-config/create-local-users.md new file mode 100644 index 00000000000..e6589e67693 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/authentication-config/create-local-users.md @@ -0,0 +1,15 @@ +--- +title: 本地身份验证 +--- + +在配置外部验证提供程序之前，你将默认使用本地身份验证。Rancher 将用户帐户信息（例如用户名和密码）存储在本地。默认情况下，用于首次登录 Rancher 的 `admin` 用户就是一个本地用户。 + +## 添加本地用户 + +无论是否使用外部身份验证服务，你都应创建一些本地身份认证的用户，以便在外部验证服务遇到问题时继续使用 Rancher。 + +1. 在左上角，单击 **☰ > 用户 & 认证**。 +1. 在左侧导航栏，单击**用户**。 +1. 单击**创建**。 +1. 完成**添加用户**的表单。 +1. 单击**创建**。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/authentication-config/manage-users-and-groups.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/authentication-config/manage-users-and-groups.md new file mode 100644 index 00000000000..8cc43552492 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/authentication-config/manage-users-and-groups.md @@ -0,0 +1,77 @@ +--- +title: 用户和组 +--- + +Rancher 依赖用户和组来决定允许登录到 Rancher 的用户，以及他们可以访问哪些资源。你配置外部身份验证提供程序后，该提供程序的用户将能够登录到你的 Rancher Server。用户登录时，验证提供程序将向你的 Rancher Server 提供该用户所属的组列表。 + +你可以通过向资源添加用户或组，来控制其对集群、项目、全局 DNS 提供程序和相关资源的访问。将组添加到资源时，身份验证提供程序中属于该组的所有用户都将能够使用组的权限访问该资源。有关角色和权限的更多信息，请参见 [RBAC](../manage-role-based-access-control-rbac/manage-role-based-access-control-rbac.md)。 + +## 管理成员 + +向资源添加用户或用户组时，你可以通过输入用户或组的名称来搜索用户或组。Rancher Server 会查询身份验证提供程序，来查找与你输入的内容匹配的用户和组。搜索仅限于你登录时使用的身份验证提供程序。例如，如果你启用了 GitHub 身份验证，但使用[本地](create-local-users.md)用户登录，则无法搜索 GitHub 用户或组。 + +你可以查看和管理所有用户，包括本地用户和来自身份验证提供程序的用户。在左上角，单击 **☰ > 用户 & 认证**。在左侧导航栏中单击**用户**。 + +:::note SAML 认证警告 + +- Users and groups aren't validated when you assign permissions to them in Rancher. +- 添加用户时，必须正确输入确切的用户 ID（即 UID 字段）。键入用户 ID 时，将不会搜索可能匹配的其他用户 ID。 +- 添加组时，必须从文本框旁边的下拉列表中选择组。Rancher 假定来自文本框的任何输入都是用户。 +- The group drop-down shows only the groups that you are a member of. However, if you have Administrator permissions or Restricted Administrator permissions, you can join a group that you are not a member of. + +::: + +## 用户信息 + +Rancher 会维护通过身份验证提供程序登录的每个用户的信息，包括用户是否允许访问 Rancher Server，以及用户所属的组的列表。Rancher 保留此用户信息，以便 CLI、API 和 kubectl 能够准确地反映用户基于身份验证提供程序中的组成员关系的访问。 + +当用户使用身份验证提供程序登录到 UI 时，Rancher 将自动更新该用户信息。 + +### 自动刷新用户信息 + +Rancher 会定期刷新用户信息，甚至在用户通过 UI 登录之前也是如此。你可以控制 Rancher 执行刷新的频率。 + +有两个参数可以控制这个操作： + +- **`auth-user-info-max-age-seconds`** + + 此设置控制用户信息的最大老化时间，如果超过这个时间，Rancher 就会刷新信息。如果用户进行 API 调用（直接 UI 访问或通过使用 Rancher CLI 或 kubectl 调用），并且与 Rancher 上次刷新用户信息的时间间隔大于此设置，则 Rancher 将触发刷新。此设置默认为 `3600` 秒，即 1 小时。 + +- **`auth-user-info-resync-cron`** + + 此设置控制用于所有用户重新同步身份验证提供程序信息的定期任务周期。无论用户最近是否登录或使用 API，自动刷新任务都会按照指定的时间间隔刷新用户信息。此设置默认为 `0 0 * * *`，即每天午夜进行一次。有关此设置的有效值的更多信息，请参见 [Cron 文档](https://en.wikipedia.org/wiki/Cron)。 + +如果需要更改设置： + +1. 在左上角，单击 **☰ > 全局设置**。 +1. 前往你需要配置的设置，并点击 **⋮ > 编辑设置**。 + +:::note + +由于 SAML 不支持用户查找，因此基于 SAML 的身份验证提供程序不支持定期刷新用户信息。只有当用户登录到 Rancher UI 时，才会刷新用户信息。 + +::: +### 手动刷新用户信息 + +如果你不确定 Rancher 上一次执行用户信息自动刷新的时间，则可以通过手动刷新来刷新所有用户的信息。 + +1. 在左上角，单击 **☰ > 用户 & 认证**。 +1. 在**用户**页面，单击**刷新用户组成员名单**。 + +**结果**：Rancher 刷新了所有用户的信息。请求此刷新将更新哪些用户可以访问 Rancher 以及每个用户所属的所有组。 + +:::note + +由于 SAML 不支持用户查找，因此基于 SAML 的身份验证提供程序不支持手动刷新用户信息。只有当用户登录到 Rancher UI 时，才会刷新用户信息。 + +::: + +## 会话周期 + +用户会话的默认生命周期（TTL）是可调的。默认的会话周期是 16 小时。 + +1. 在左上角，单击 **☰ > 全局设置**。 +1. 前往 **`auth-user-session-ttl-minutes`** 并单击**⋮ > 编辑设置**。 +1. 输入会话应该持续的时间（以分钟为单位），然后单击**Save**。 + +**结果**：用户的 Rancher 登录会话在设定的分钟数后自动退出。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/authentication-permissions-and-global-configuration.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/authentication-permissions-and-global-configuration.md new file mode 100644 index 00000000000..91e31a8f0d0 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/authentication-permissions-and-global-configuration.md @@ -0,0 +1,78 @@ +--- +title: 认证、权限和全局配置 +--- + + + + + +安装完成后，[系统管理员](manage-role-based-access-control-rbac/global-permissions.md) 应该通过 Rancher 配置认证、授权、安全性、默认设置、安全策略、驱动和全局 DNS 条目。 + +## 首次登录 + +首次登录 Rancher 后，Rancher 会提示你输入 **Rancher Server URL**，你应该将 URL 设置为访问 Rancher Server 的主入口点。当负载均衡器运行在 Rancher Server 集群前面时，URL 应该设置为负载均衡地址。系统会自动尝试根据运行 Rancher Server 的主机 IP 地址或主机名推断 Rancher Server URL，但只有当 Rancher Server 以单节点方式安装时才有效。因此在大多数情况下，你都需要将 Rancher Server URL 设置为正确的值。 + +:::danger + +当设置完 Rancher Server URL 后，我们不支持修改它。请格外小心的设置此项配置。 + +::: + +## 认证 + +Rancher 为 Kubernetes 增加了一项关键特性是集中式的用户认证。此特性允许设置本地用户和/或连接到外部认证程序。通过连接到外部认证程序，你可以使用该程序提供的用户和组。 + +更多关于认证的工作原理以及如何配置对接各个认证程序，请参考[认证](authentication-config/authentication-config.md)。 + +## 授权 + +在 Rancher 中，每个人都是以 _用户_ 的身份进行鉴权，这是一个授予你访问 Rancher 的登录身份。用户登录 Rancher 后，他们的 _授权_ 或者他们在系统中的访问权限由用户的角色决定。Rancher 提供了内置的角色，允许你你轻松地配置用户对资源的权限，但是 Rancher 还提供了为每个 Kubernetes 资源自定义角色的功能。 + +更多关于授权的工作原理以及自定义角色的使用，请参考 [RBAC](manage-role-based-access-control-rbac/manage-role-based-access-control-rbac.md)。 +## Provisioning Drivers + +Rancher 中的驱动允许你管理哪些程序可以预置[托管的 Kubernetes 集群](../kubernetes-clusters-in-rancher-setup/set-up-clusters-from-hosted-kubernetes-providers/set-up-clusters-from-hosted-kubernetes-providers.md) 或 [云服务器节点](../launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/use-new-nodes-in-an-infra-provider.md)，允许 Rancher 部署和管理 Kubernetes。 + +更多信息请参考 [Provisioning Drivers](about-provisioning-drivers/about-provisioning-drivers.md)。 + +## 添加 Kubernetes 版本到 Rancher 中 + +使用此功能，你可以在最新版本的 Kubernetes 发布后立即升级，而不需要升级 Rancher。此功能允许你轻松升级 Kubernetes 的补丁版本（例如 `v1.15.X`），但不打算升级 Kubernetes 的次要版本（例如 `v1.X.0`），因为 Kubernetes 倾向于在次要版本之间弃用或添加 API。 + +Rancher 用于配置 [RKE 集群](../launch-kubernetes-with-rancher/launch-kubernetes-with-rancher.md) 的信息现在存储于 Rancher Kubernetes 元数据中，更多关于元数据的配置以及如何更改用于配置 RKE 集群的 Kubernetes 版本的信息，请参考 [Rancher Kubernetes 元数据](../../../getting-started/installation-and-upgrade/upgrade-kubernetes-without-upgrading-rancher.md)。 + +Rancher Kubernetes 元数据包含 Kubernetes 版本信息，Rancher 使用这些信息来配置 [RKE 集群](../launch-kubernetes-with-rancher/launch-kubernetes-with-rancher.md)。 + +关于元数据的工作原理以及如何配置元数据，请参考 [Rancher Kubernetes 元数据](../../../getting-started/installation-and-upgrade/upgrade-kubernetes-without-upgrading-rancher.md)。 + +## 全局设置 + +控制某些全局级别 Rancher 配置项可以在顶部的导航栏中找到。 + +点击左上角的 **☰** ，然后选择 **全局设置**，查看和配置以下设置： + +- **设置**: 各种 Rancher 默认值，例如用户密码的最小长度 (`password-min-length`)。在修改这些设置项时应该谨慎，因为设置无效的值可能会破坏 Rancher 的安装。 +- **功能开关**: 可以打开或关闭 Rancher 的某些功能，一些标志用于 [实验性功能](#启用实验性功能). +- **横幅**: 可以添加到门户上固定位置的元素，例如你可以使用这些选项在用户登录 Rancher 时为他们设置[自定义的横幅](custom-branding.md#固定横幅)。 +- **品牌**: 你可以[自定义](custom-branding.md) Rancher UI 的设计元素，你可以增加一个自定义的 logo 或 favicon，也可以修改 UI 的颜色。 +- **性能**: Rancher UI 的性能设置，例如增量资源加载。 +- **主页链接**: Rancher UI **主页**页面上显示的链接，你可以修改默认链接的可见性或者增加自己的链接。 + +### 启用实验性功能 + +Rancher 包含一些默认处于实验性和/或禁用的功能，功能开关允许你启用这些特性。更多信息请参考[功能开关](../../advanced-user-guides/enable-experimental-features/enable-experimental-features.md)。 + +### 全局配置 + +仅在激活 **legacy** [功能开关](../../advanced-user-guides/enable-experimental-features/enable-experimental-features.md) 时才可以看见**全局配置**选项。在 v2.6 及更新版本新安装的 Rancher 已经默认禁用了 **legacy** 特性。如果你是从早期的 Rancher 版本升级，或者在 Rancher v2.6 及更新版本上启用了 **legacy** 特性，顶部导航菜单中将会显示**全局配置**： + +1. 点击左上角的 **☰**。 +1. 在 **旧版应用** 中选择 **全局配置**。 + +**全局配置**提供以下功能： + +- **应用商店** +- **全局 DNS 条目** +- **全局 DNS 提供商** + +由于这些是旧版特性，请参考 Rancher v2.0-v2.4 的[应用商店](https://github.com/rancher/rancher-docs/tree/main/archived_docs/en/version-2.0-2.4/how-to-guides/new-user-guides/helm-charts-in-rancher/helm-charts-in-rancher.md), [全局 DNS 条目](https://github.com/rancher/rancher-docs/tree/main/archived_docs/en/version-2.0-2.4/how-to-guides/new-user-guides/helm-charts-in-rancher/globaldns.md#adding-a-global-dns-entry), 以及 [全局 DNS 提供商](https://github.com/rancher/rancher-docs/tree/main/archived_docs/en/version-2.0-2.4/how-to-guides/new-user-guides/helm-charts-in-rancher/globaldns.md#editing-a-global-dns-provider)。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/configure-microsoft-ad-federation-service-saml/configure-microsoft-ad-federation-service-saml.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/configure-microsoft-ad-federation-service-saml/configure-microsoft-ad-federation-service-saml.md new file mode 100644 index 00000000000..3b96b5f62ff --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/configure-microsoft-ad-federation-service-saml/configure-microsoft-ad-federation-service-saml.md @@ -0,0 +1,39 @@ +--- +title: 配置 Microsoft AD FS (SAML) +--- + + + + + +如果你的组织使用 Active Directory Federation Service (AD FS) 进行用户身份认证，你可以通过配置 Rancher 来允许用户使用 AD FS 凭证登录。 + +## 先决条件 + +已安装 Rancher。 + +- 获取你的 Rancher Server URL。配置 AD FS 时，请使用该 URL 替换 `` 占位符。 +- 你必须在 Rancher 安装时具有全局管理员账号。 + +你必须配置 [Microsoft AD FS 服务器](https://docs.microsoft.com/en-us/windows-server/identity/active-directory-federation-services)。 + +- 获取你的 AD FS 服务器 IP/DNS 名称。配置 AD FS 时，请使用该 IP/DNS 名称替换 `` 占位符。 +- 你必须有在 AD FS 服务器上添加 [Relying Party Trusts](https://docs.microsoft.com/en-us/windows-server/identity/ad-fs/operations/create-a-relying-party-trust) 的权限。 + +## 配置概要 + +要让 Rancher Server 使用 Microsoft AD FS，你需要在 Active Directory 服务器上配置 AD FS，并将 Rancher 配置为使用 AD FS 服务器。如果需要获取在 Rancher 中设置 Microsoft AD FS 身份认证的指南，请参见： + +- [1. 在 Microsoft AD FS 中配置 Rancher](configure-ms-adfs-for-rancher.md) +- [2. 在 Rancher 中配置 Microsoft AD FS](configure-rancher-for-ms-adfs.md) + +:::note SAML 身份提供商注意事项 + +- SAML 协议不支持搜索或查找用户或组。因此，将用户或组添加到 Rancher 时不会对其进行验证。 +- 添加用户时，必须正确输入确切的用户 ID（即 `UID` 字段）。键入用户 ID 时，将不会搜索可能匹配的其他用户 ID。 +- 添加组时，必须从文本框旁边的下拉列表中选择组。Rancher 假定来自文本框的任何输入都是用户。 +- 用户组下拉列表仅显示你所属的用户组。如果你不是某个组的成员，你将无法添加该组。 + +::: + +### [后续操作：在 Microsoft AD FS 中配置 Rancher](configure-ms-adfs-for-rancher.md) diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/configure-microsoft-ad-federation-service-saml/configure-ms-adfs-for-rancher.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/configure-microsoft-ad-federation-service-saml/configure-ms-adfs-for-rancher.md new file mode 100644 index 00000000000..ed1dcf5df1f --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/configure-microsoft-ad-federation-service-saml/configure-ms-adfs-for-rancher.md @@ -0,0 +1,88 @@ +--- +title: 1. 在 Microsoft AD FS 中配置 Rancher +--- + + + + + +在配置 Rancher 以支持 Active Directory Federation Service (AD FS) 之前，你必须在 AD FS 中将 Rancher 添加为 [relying party trust](https://docs.microsoft.com/en-us/windows-server/identity/ad-fs/technical-reference/understanding-key-ad-fs-concepts)（信赖方信任）。 + +1. 以管理用户身份登录 AD 服务器。 + +1. 打开 **AD FS Management** 控制台。在 **Actions** 菜单中选择 **Add Relying Party Trust...**。然后单击 **Start**。 + + ![](/img/adfs/adfs-overview.png) + +1. 选择 **Enter data about the relying party manually** 作为获取信赖方数据的选项。 + + ![](/img/adfs/adfs-add-rpt-2.png) + +1. 为 **Relying Party Trust** 设置**显示名称**，例如 `Rancher`。 + + ![](/img/adfs/adfs-add-rpt-3.png) + +1. 选择 **AD FS profile** 作为信赖方信任的配置文件。 + + ![](/img/adfs/adfs-add-rpt-4.png) + +1. 留空 **optional token encryption certificate**，因为 Rancher AD FS 不会使用它。 + + ![](/img/adfs/adfs-add-rpt-5.png) + +1. 选择 **Enable support for the SAML 2.0 WebSSO protocol** 并在 Service URL 处输入 `https:///v1-saml/adfs/saml/acs`。 + + ![](/img/adfs/adfs-add-rpt-6.png) + +1. 将 `https:///v1-saml/adfs/saml/metadata` 添加为 **Relying party trust identifier**。 + + ![](/img/adfs/adfs-add-rpt-7.png) + +1. 本教程不涉及多重身份认证。如果你想配置多重身份认证，请参见 [Microsoft 文档](https://docs.microsoft.com/en-us/windows-server/identity/ad-fs/operations/configure-additional-authentication-methods-for-ad-fs)。 + + ![](/img/adfs/adfs-add-rpt-8.png) + +1. 在 **Choose Issuance Authorization RUles** 中，你可以根据用例选择任何一个可用选项。但是考虑到本指南的目的，请选择 **Permit all users to access this relying party**。 + + ![](/img/adfs/adfs-add-rpt-9.png) + +1. 检查所有设置后，选择 **Next** 来添加信赖方信任。 + + ![](/img/adfs/adfs-add-rpt-10.png) + +1. 选择 **Open the Edit Claim Rules...**。然后单击 **Close**。 + + ![](/img/adfs/adfs-add-rpt-11.png) + +1. 在 **Issuance Transform Rules** 选项卡中，单击 **Add Rule...**。 + + ![](/img/adfs/adfs-edit-cr.png) + +1. 在 **Claim rule template** 中选择 **Send LDAP Attributes as Claims**。 + + ![](/img/adfs/adfs-add-tcr-1.png) + +1. 将 **Claim rule name** 设置为所需的名称（例如 `Rancher Attributes`）并选择 **Active Directory** 作为 **Attribute store**。创建对应下表的映射： + + | LDAP 属性 | 传出声明类型 | + | -------------------------------------------- | ------------ | + | Given-Name | Given Name | + | User-Principal-Name | UPN | + | Token-Groups - Qualified by Long Domain Name | Group | + | SAM-Account-Name | 名称 | + +
+ + ![](/img/adfs/adfs-add-tcr-2.png) + +1. 从 AD 服务器的以下位置下载 `federationmetadata.xml`： + +``` +https:///federationmetadata/2007-06/federationmetadata.xml +``` + +**结果**：你已将 Rancher 添加为依赖信任方。现在你可以配置 Rancher 来使用 AD。 + +## 后续操作 + +[在 Rancher 中配置 Microsoft AD FS ](configure-rancher-for-ms-adfs.md) diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/configure-microsoft-ad-federation-service-saml/configure-rancher-for-ms-adfs.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/configure-microsoft-ad-federation-service-saml/configure-rancher-for-ms-adfs.md new file mode 100644 index 00000000000..b29f42313d8 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/configure-microsoft-ad-federation-service-saml/configure-rancher-for-ms-adfs.md @@ -0,0 +1,57 @@ +--- +title: 2. 在 Rancher 中配置 Microsoft AD FS +--- + + + + + +完成[在 Microsoft AD FS 中配置 Rancher](configure-ms-adfs-for-rancher.md) 后，将你的 Active Directory Federation Service (AD FS) 信息输入 Rancher，以便 AD FS 用户可以通过 Rancher 进行身份认证。 + +:::note 配置 ADFS 服务器的重要说明： + +- SAML 2.0 WebSSO 协议服务 URL 为：`https:///v1-saml/adfs/saml/acs` +- 信赖方信任标识符 URL 为：`https:///v1-saml/adfs/saml/metadata` +- 你必须从 AD FS 服务器导出 `federationmetadata.xml` 文件。你可以在 `https:///federationmetadata/2007-06/federationmetadata.xml` 中找到该文件。 + +::: + +1. 在左上角，单击 **☰ > 用户 & 认证**。 +1. 在左侧导航栏，单击**认证**。 +1. 单击 **ADFS**。 +1. 填写**配置 AD FS 账号**表单。Microsoft AD FS 允许你指定现有的 Active Directory (AD) 服务器。[以下配置示例](#配置)描述了如何将 AD 属性映射到 Rancher 中的字段。 +1. 完成**配置 AD FS 账号**表单后，单击**启用**。 + + Rancher 会将你重定向到 AD FS 登录页面。输入使用 Microsoft AD FS 进行身份验证的凭证，来验证你的 Rancher AD FS 配置。 + + :::note + + 你可能需要禁用弹出窗口阻止程序才能看到 AD FS 登录页面。 + + ::: + +**结果**：已将 Rancher 配置为使用 AD FS。你的用户现在可以使用 AD FS 登录名登录 Rancher。 + +## 配置 + +| 字段 | 描述 | +| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| 显示名称字段 | 包含用户显示名称的 AD 属性。

示例：`http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name` | +| 用户名字段 | 包含用户名/给定名称的 AD 属性。

示例：`http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname` | +| UID 字段 | 每个用户独有的 AD 属性。

示例：`http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn` | +| 用户组字段 | 创建用于管理组成员关系的条目。

示例：`http://schemas.xmlsoap.org/claims/Group` | +| Rancher API 主机 | Rancher Server 的 URL。 | +| 私钥/证书 | 在 Rancher 和你的 AD FS 之间创建安全外壳（SSH）的密钥/证书对。确保将 Common Name (CN) 设置为 Rancher Server URL。

[证书创建命令](#example-certificate-creation-command) | +| 元数据 XML | 从 AD FS 服务器导出的 `federationmetadata.xml` 文件。

你可以在 `https:///federationmetadata/2007-06/federationmetadata.xml` 找到该文件。 | + +### Example Certificate Creation Command + +你可以使用 openssl 命令生成证书。例如： + +``` +openssl req -x509 -newkey rsa:2048 -keyout myservice.key -out myservice.cert -days 365 -nodes -subj "/CN=myservice.example.com" +``` + +## Configuring SAML Single Logout (SLO) + + diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/configure-openldap/configure-openldap.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/configure-openldap/configure-openldap.md new file mode 100644 index 00000000000..652e2457f37 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/configure-openldap/configure-openldap.md @@ -0,0 +1,56 @@ +--- +title: 配置 OpenLDAP +--- + + + + + +如果你的组织使用 LDAP 进行认证，则可以配置 Rancher 与 OpenLDAP 服务器通信以对用户进行认证。这时 Rancher 管理员可以对外部用户系统中的用户和组进行集群和项目的访问控制，同时允许终端用户在登录 Rancher UI 时使用其 LDAP 凭据进行身份认证。 + +## 先决条件 + +必须为 Rancher 配置 LDAP 绑定账号（即 ServiceAccount），来搜索和检索应该具有访问权限的用户和组的 LDAP 条目。建议不要使用管理员账号或个人账号，而应在 OpenLDAP 中创建一个专用账号，该账号对配置的搜索库下的用户和组需要具有只读权限（参见下文）。 + +> **使用 TLS?** +> +> 如果 OpenLDAP 服务器使用的证书是自签名的或不是来自认可的证书颁发机构，请确保手头有 PEM 格式的 CA 证书（包含所有中间证书）。你必须在配置期间粘贴此证书，以便 Rancher 能够验证证书链。 + +## 在 Rancher 中配置 OpenLDAP + +配置 OpenLDAP 服务器，组和用户的设置。有关填写每个字段的帮助，请参见[配置参考](openldap-config-reference.md) + +> 在开始之前，请熟悉[外部认证配置和用户主体](../authentication-config/authentication-config.md#外部认证配置和用户主体)的概念。 + +1. 在左上角，单击 **☰ > 用户 & 认证**。 +1. 在左侧导航栏，单击**认证**。 +1. 单击 **OpenLDAP**。填写**配置 OpenLDAP 服务器**表单。 +1. 点击**启用**。 + +### 测试认证 + +完成配置后，请测试与 OpenLDAP 服务器的连接。如果测试成功，则表明 OpenLDAP 认证已启用。 + +:::note + +于此步骤中输入的 OpenLDAP 用户凭证将映射到本地主体账号，并在 Rancher 中分配系统管理员权限。因此，你应该决定使用哪个 OpenLDAP 账号来执行此步骤。 + +::: + +1. 输入应映射到本地主体账号的 OpenLDAP 账号的**用户名**和**密码** 。 +2. 点击**启用 OpenLDAP 认证**来测试 OpenLDAP 的连接并完成设置。 + +**结果**： + +- OpenLDAP 认证配置成功。 +- 与输入凭证对应的 LDAP 用户被映射到本地主体（管理员）账号。 + +:::note + +如果 LDAP 服务中断，你仍然可以使用本地配置的 `admin` 账号和密码登录。 + +::: + +## 附录：故障排除 + +如果在测试与 OpenLDAP 服务器的连接时遇到问题，请首先仔细检查为 ServiceAccount 输入的凭证以及搜索库配置。你还可以检查 Rancher 日志来查明问题的原因。调试日志可能包含有关错误的更详细信息。详情请参见[如何启用调试日志](../../../../faq/technical-items.md#如何启用调试日志记录)。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/configure-openldap/openldap-config-reference.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/configure-openldap/openldap-config-reference.md new file mode 100644 index 00000000000..24c338fe708 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/configure-openldap/openldap-config-reference.md @@ -0,0 +1,81 @@ +--- +title: OpenLDAP 配置参考 +--- + + + + + +有关配置 OpenLDAP 认证的更多详细信息，请参见[官方文档](https://www.openldap.org/doc/)。 + +> 在开始之前，请熟悉[外部认证配置和用户主体](../authentication-config/authentication-config.md#外部认证配置和用户主体)的概念。 + +## 背景：OpenLDAP 认证流程 + +1. 当用户尝试使用其 LDAP 凭证登录时，Rancher 会使用具有搜索目录和读取用户/组属性权限的 ServiceAccount，创建与 LDAP 服务器的初始绑定。 +2. 然后，Rancher 使用搜索筛选器根据用户名和配置的属性映射为用户搜索目录。 +3. 找到用户后，将使用用户的 DN 和提供的密码，通过另一个 LDAP 绑定请求对用户进行身份认证。 +4. 认证成功后，Rancher 将基于用户对象的成员属性和配置的用户映射属性执行组搜索，来解析组成员。 + +## OpenLDAP 服务器配置 + +你将需要输入地址，端口和协议来连接到 OpenLDAP 服务器。不安全流量的标准端口为 `389`，TLS 流量的标准端口为 `636`。 + +> **使用 TLS？** +> +> 如果 OpenLDAP 服务器使用的证书是自签名的或不是来自认可的证书颁发机构，请确保手头有 PEM 格式的 CA 证书（包含所有中间证书）。你必须在配置期间粘贴此证书，以便 Rancher 能够验证证书链。 + +如果你不确定要在用户/组`搜索库`字段中输入什么值，请咨询你的 LDAP 管理员，或参见 Active Directory 身份验证文档中的[使用 ldapsearch 确定搜索库和 Schema](../../../../how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/authentication-config/configure-active-directory.md#附录使用-ldapsearch-确定搜索库和-schema) 章节。 + +
OpenLDAP 服务器参数
+ +| 参数 | 描述 | +| :---------------------- | :----------------------------------------------------------------------------------------------------------------------------------- | +| 主机名 | 指定 OpenLDAP 服务器的主机名或 IP 地址。 | +| 端口 | 指定 OpenLDAP 服务器监听连接的端口。未加密的 LDAP 通常使用 389 的标准端口，而 LDAPS 使用 636 端口。 | +| TLS | 选中此框可启用 SSL/TLS 上的 LDAP（通常称为 LDAPS）。如果服务器使用自签名/企业签名的证书，则还需要粘贴 CA 证书。 | +| 服务器连接超时 | Rancher 在认为无法访问服务器之前等待的时间（秒）。 | +| ServiceAccount 标识名称 | 输入用于绑定，搜索和检索 LDAP 条目的用户的标识名称（DN）。 | +| ServiceAccount 密码 | ServiceAccount 的密码。 | +| 用户搜索库 | 输入目录树中开始搜索用户对象的节点的标识名称（DN）。所有用户都必须是此基础标识名称的后代。例如，"ou=people,dc=acme,dc=com"。 | +| 组搜索库 | 如果组位于`用户搜索库`下配置的节点之外的其他节点下，则需要在此处提供标识名称。否则，将此字段留空。例如："ou=groups,dc=acme,dc=com"。 | + +## 用户/组 Schema 配置 + +如果你的 OpenLDAP 目录不同于标准的 OpenLDAP Schema，则必须完成**自定义 Schema** 部分实现匹配。 + +请注意，Rancher 使用本节中配置的属性映射来构造搜索筛选器和解析组成员。因此，我们建议你验证此处的配置是否与你在 OpenLDAP 中使用的 Schema 匹配。 + +如果你不确定 OpenLDAP 服务器中使用的用户/组 Schema，请咨询你的 LDAP 管理员，或参见 Active Directory 身份验证文档中的[使用 ldapsearch 确定搜索库和 Schema](../../../../how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/authentication-config/configure-active-directory.md#附录使用-ldapsearch-确定搜索库和-schema) 章节。 + +### 用户 Schema 配置 + +下表详细说明了用户 Schema 配置的参数。 + +
用户 Schema 配置参数
+ +| 参数 | 描述 | +| :---------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Object Class | 域中用于用户对象的对象类别名称。如果定义了此参数，则仅指定对象类别的名称 - *请勿*将其放在 LDAP 包装器中，例如 `&(objectClass=xxxx)`。 | +| Username Attribute | 用户属性的值适合作为显示名称。 | +| Login Attribute | 登录属性的值与用户登录 Rancher 时输入的凭证的用户名部分匹配。通常是 `uid`。 | +| User Member Attribute | 包含用户所属组的标识名称的用户属性。通常是 `memberOf` 或 `isMemberOf`。 | +| Search Attribute | 当用户输入文本以在用户界面中添加用户或组时，Rancher 会查询 LDAP 服务器，并尝试根据此设置中提供的属性匹配用户。可以通过使用管道（“\|”）符号分隔属性来指定多个属性。 | +| User Enabled Attribute | 如果 OpenLDAP 服务器的 Schema 支持使用用户属性的值来评估账号是禁用还是关闭，请输入该属性的名称。默认的 OpenLDAP Schema 不支持此功能，因此此字段通常留空。 | +| Disabled Status Bitmask | 禁用/锁定的用户账号的值。如果 `User Enabled Attribute` 是空的，则忽略此参数。 | + +### 组 Schema 配置 + +下表详细说明了组 Schema 配置的参数。 + +
组 Schema 配置参数
+ +| 参数 | 描述 | +| :----------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Object Class | 域中用于组条目的对象类别名称。如果定义了此参数，则仅指定对象类别的名称 - *请勿*将其放在 LDAP 包装器中，例如 `&(objectClass=xxxx)`。 | +| Name Attribute | 名称属性的值适合作为显示名称。 | +| Group Member User Attribute | **用户属性**的名称。它的格式与 `Group Member Mapping Attribute` 中的组成员匹配。 | +| Group Member Mapping Attribute | 包含组成员的组属性的名称。 | +| Search Attribute | 在 UI 中将组添加到集群或项目时，用于构造搜索筛选器的属性。请参见用户 Schema 的 `Search Attribute`。 | +| Group DN Attribute | 组属性的名称，其格式与用户的组成员属性中的值匹配。参见 `User Member Attribute`。 | +| Nested Group Membership | 此设置定义 Rancher 是否应解析嵌套组成员身份。仅当你的组织使用这些嵌套成员身份时才使用（即你有包含其他组作为成员的组）。如果你使用 Shibboleth，此选项会被禁用。 | diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/configure-shibboleth-saml/about-group-permissions.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/configure-shibboleth-saml/about-group-permissions.md new file mode 100644 index 00000000000..ab226898b81 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/configure-shibboleth-saml/about-group-permissions.md @@ -0,0 +1,32 @@ +--- +title: Shibboleth 和 OpenLDAP 的组权限 +--- + + + + + +由于 Shibboleth 是 SAML 提供者，因此它不支持搜索用户组的功能。虽然 Shibboleth 集成可以验证用户凭证，但是如果没有其他配置，Shibboleth 不能在 Rancher 中给用户组分配权限。 + +你可以通过配置 OpenLDAP 来解决这个问题。如果让 Shibboleth 使用 OpenLDAP 后端，你将能够在 Rancher 中搜索组，并从 Rancher UI 将集群、项目或命名空间等资源分配给用户组。 + +## 名词解释 + +- **Shibboleth**：用于计算机网络和互联网的单点登录系统。它允许用户仅使用一种身份登录到各种系统。它验证用户凭证，但不单独处理组成员身份。 +- **SAML**：安全声明标记语言（Security Assertion Markup Language），用于在身份提供程序和服务提供商之间交换认证和授权数据的开放标准。 +- **OpenLDAP**：轻型目录访问协议（LDAP）的免费开源实现。它用于管理组织的计算机和用户。OpenLDAP 对 Rancher 用户很有用，因为它支持组。只要组已存在于身份提供程序中，你就可以在 Rancher 中为组分配权限，从而让组访问资源（例如集群，项目或命名空间）。 +- **IdP 或 IDP**：身份提供程序。OpenLDAP 是身份提供程序的一个例子。 + +## 将 OpenLDAP 组权限添加到 Rancher 资源 + +下图说明了 OpenLDAP 组的成员如何访问 Rancher 中该组有权访问的资源。 + +例如，集群所有者可以将 OpenLDAP 组添加到集群，从而让组有权查看大多数集群级别的资源并创建新项目。然后，OpenLDAP 组成员在登录 Rancher 后就可以访问集群。 + +在这种情况下，OpenLDAP 允许集群所有者在分配权限时搜索组。如果没有 OpenLDAP，将不支持搜索组的功能。 + +当 OpenLDAP 组的成员登录到 Rancher 时，用户将被重定向到 Shibboleth 并在那里输入用户名和密码。 + +Shibboleth 会验证用户的凭证，并从 OpenLDAP 检索用户属性，其中包括用户所在的组信息。然后 Shibboleth 将向 Rancher 发送一个包含用户属性的 SAML 断言。Rancher 会使用组数据，以便用户可以访问他所在的组有权访问的所有资源。 + +![Adding OpenLDAP Group Permissions to Rancher Resources](/img/shibboleth-with-openldap-groups.svg) diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/configure-shibboleth-saml/configure-shibboleth-saml.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/configure-shibboleth-saml/configure-shibboleth-saml.md new file mode 100644 index 00000000000..7ba7aafb81c --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/configure-shibboleth-saml/configure-shibboleth-saml.md @@ -0,0 +1,110 @@ +--- +title: 配置 Shibboleth (SAML) +--- + + + + + +如果你的组织使用 Shibboleth Identity Provider (IdP) 进行用户身份认证，你可以通过配置 Rancher 来允许用户使用 Shibboleth 凭证登录。 + +在此配置中，当 Rancher 用户登录时，他们将被重定向到 Shibboleth IdP 来输入凭证。认证结束后，他们将被重定向回 Rancher UI。 + +如果你将 OpenLDAP 配置为 Shibboleth 的后端，SAML 断言会返回到 Rancher，其中包括用于引用组的用户属性。然后，通过认证的用户将能够访问其所在的组有权访问的 Rancher 资源。 + +> 本节假定你已了解 Rancher、Shibboleth 和 OpenLDAP 是如何协同工作的。有关工作原理的详细说明，请参见[本页](about-group-permissions.md) + +# 在 Rancher 中设置 Shibboleth + +### Shibboleth 先决条件 + +> - 你必须配置了 Shibboleth IdP 服务器。 +> - 以下是 Rancher Service Provider 配置所需的 URL： +> 元数据 URL：`https:///v1-saml/shibboleth/saml/metadata` +> 断言使用者服务 (ACS) URL：`https:///v1-saml/shibboleth/saml/acs` +> - 从 IdP 服务器导出 `metadata.xml` 文件。详情请参见 [Shibboleth 文档](https://wiki.shibboleth.net/confluence/display/SP3/Home)。 + +### 在 Rancher 中配置 Shibboleth + +如果你的组织使用 Shibboleth 进行用户身份认证，你可以通过配置 Rancher 来允许你的用户使用 IdP 凭证登录。 + +1. 在左上角，单击 **☰ > 用户 & 认证**。 +1. 在左侧导航栏，单击**认证**。 +1. 单击 **Shibboleth**。 +1. 填写**配置 Shibboleth 账号**表单。Shibboleth IdP 允许你指定要使用的数据存储。你可以添加数据库或使用现有的 ldap 服务器。例如，如果你选择 Active Directory (AD) 服务器，下面的示例将描述如何将 AD 属性映射到 Rancher 中的字段： + + 1. **显示名称字段**：包含用户显示名称的 AD 属性（例如：`displayName`）。 + + 1. **用户名字段**：包含用户名/给定名称的 AD 属性（例如：`givenName`）。 + + 1. **UID 字段**：每个用户唯一的 AD 属性（例如：`sAMAccountName`、`distinguishedName`）。 + + 1. **用户组字段**: 创建用于管理组成员关系的条目（例如：`memberOf`）。 + + 1. **Rancher API 主机**：你的 Rancher Server 的 URL。 + + 1. **私钥**和**证书**：密钥/证书对，用于在 Rancher 和你的 IdP 之间创建一个安全外壳（SSH）。 + + 你可以使用 openssl 命令进行创建。例如： + + ``` + openssl req -x509 -newkey rsa:2048 -keyout myservice.key -out myservice.cert -days 365 -nodes -subj "/CN=myservice.example.com" + ``` + + 1. **IDP 元数据**：从 IdP 服务器导出的 `metadata.xml` 文件。 + +1. 完成**配置 Shibboleth 账号**表单后，单击**启用**。 + + Rancher 会将你重定向到 IdP 登录页面。输入使用 Shibboleth IdP 的用户凭证，来验证你的 Rancher Shibboleth 配置。 + + :::note + + 你可能需要禁用弹出窗口阻止程序才能看到 IdP 登录页面。 + + ::: + +**结果**：已将 Rancher 配置为使用 Shibboleth。你的用户现在可以使用 Shibboleth 登录名登录 Rancher。 + +:::note SAML Provider Caveats + +SAML 协议不支持用户或用户组的搜索或查找。因此，如果你没有为 Shibboleth 配置 OpenLDAP，则请留意以下警告。 + +- 在 Rancher 中为用户或组分配权限时，不会对用户或组进行验证。 +- 添加用户时，必须正确输入准确的用户 ID（即 UID 字段）。在你输入用户 ID 时，将不会搜索可能匹配的其他用户 ID。 +- 添加组时，必须从文本框旁边的下拉列表中选择组。Rancher 假定来自文本框的任何输入都是用户。 +- The group drop-down shows only the groups that you are a member of. However, if you have Administrator permissions or restricted Administrator permissions, you can join a group that you are not a member of. + +要在 Rancher 中分配权限时启用搜索组，你需要为 SAML 身份认证服务配置支持组的后端（例如 OpenLDAP）。 + +::: + +### Configuring SAML Single Logout (SLO) + + + +# 在 Rancher 中设置 OpenLDAP + +如果你将 OpenLDAP 配置为 Shibboleth 的后端，SAML 断言会返回到 Rancher，其中包括用于引用组的用户属性。然后，通过认证的用户将能够访问其所在的组有权访问的 Rancher 资源。 + +### OpenLDAP 先决条件 + +必须为 Rancher 配置 LDAP 绑定账号（即 ServiceAccount），来搜索和检索应该具有访问权限的用户和组的 LDAP 条目。建议不要使用管理员账号或个人账号，而应在 OpenLDAP 中创建一个专用账号，该账号对配置的搜索库下的用户和组需要具有只读权限（参见下文）。 + +> **使用 TLS？** +> +> 如果 OpenLDAP 服务器使用的证书是自签名的或不是来自认可的证书颁发机构，请确保手头有 PEM 格式的 CA 证书（包含所有中间证书）。你必须在配置期间粘贴此证书，以便 Rancher 能够验证证书链。 + +### 在 Rancher 中配置 OpenLDAP + +配置 OpenLDAP 服务器，组和用户的设置。有关填写每个字段的帮助，请参见[配置参考](../configure-openldap/openldap-config-reference.md)。请注意，嵌套组成员资格不适用于 Shibboleth。 + +> 在开始之前，请熟悉[外部认证配置和用户主体](../authentication-config/authentication-config.md#外部认证配置和用户主体)的概念。 + +1. 使用初始的本地 `admin` 账号登录到 Rancher UI。 +1. 在左上角，单击 **☰ > 用户 & 认证**。 +1. 在左侧导航栏，单击**认证**。 +1. 单击 **OpenLDAP**。将显示**配置 OpenLDAP 服务器**表单。 + +## 故障排除 + +如果在测试与 OpenLDAP 服务器的连接时遇到问题，请首先仔细检查为 ServiceAccount 输入的凭证以及搜索库配置。你还可以检查 Rancher 日志来查明问题的原因。调试日志可能包含有关错误的更详细信息。详情请参见[如何启用调试日志](../../../../faq/technical-items.md#如何启用调试日志记录)。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/custom-branding.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/custom-branding.md new file mode 100644 index 00000000000..59bd02daf07 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/custom-branding.md @@ -0,0 +1,192 @@ +--- +title: 定制品牌 +--- + +## 先决条件 + +你至少需要拥有集群成员权限。 + +## 品牌配置 + +要配置品牌设置： + +1. 单击**☰ > 全局设置**。 +2. 单击**公司品牌**。 + +### 自有品牌公司名称 + +此选项将大多数出现的 “Rancher” 替换为你提供的值。名称中需要包含 Rancher 的文件，例如 `rancher-compose.yml`，不会被更改。 + +### 支持链接 + +使用 URL 地址发送新的`提交问题`报告，而不是让用户发送到 GitHub Issue 页面。可选择显示 Rancher 社区支持链接。 + +### Logo + +上传深色和浅色的 Logo 来替换顶层导航标题中的 Rancher logo。 + +### 主颜色 + +使用自定义颜色替换整个 UI 中使用的主颜色。 + +### 固定横幅 + +在页眉、页脚或两者中显示自定义固定横幅。 + +要配置横幅： + +1. 单击**☰ > 全局设置**。 +2. 点击**横幅**。 + +## 自定义导航链接 + +在本节中，你将了解如何配置**集群仪表板**左侧导航栏中的链接。要访问集群仪表板： + +1. 在左上角，单击 **☰ > 集群管理**。 +1. 在**集群**页面上，转到你想要自定义导航链接的集群，然后单击 **Explore**。 + +添加链接可以让你快速访问安装在集群上的服务。例如，你可以为安装了 Istio 的集群添加指向 Kiali UI 的链接，或者为安装了 Rancher Monitoring 的集群添加指向 Grafana UI 的链接。 + +自定义链接不会影响可以访问各项服务的用户。 + +可以在顶层创建链接，并且可以将多个链接组合在一起。 + +### 添加自定义导航链接 + +:::note 先决条件： + +你至少需要拥有集群成员或项目成员权限。 + +::: + +1. 点击 **☰ > 集群管理**。 +1. 在**集群**页面上，转到要添加自定义导航链接的集群，然后单击 **Explore**。 +2. 在顶部导航菜单中，单击 **🔍（资源搜索）**。 +3. 输入 **Nav** 并点击 **Nav Links**。 +4. 单击**使用 YAML 文件创建**。 +5. 创建导航链接的最简单方法是添加以下字段： + + name: linkname + toURL: https://example.com + + 有关设置链接（包括可选字段）的更多详细信息，请参阅[链接配置](#链接配置)。 +6. 单击**创建**。 + +## 链接配置 + +### `name` + +链接的显示名称。必填项。 + +### `group` + +单击时展开的一组链接的名称。 + +可选项。如果未提供，则显示为独立链接。 + +组与独立链接分开显示，如下所示： + +![Screenshot of group and standalone link](/img/grouped-vs-standalone-links.png) + +### `iconSrc` + +Base64 格式的 Logo 图标源。 + +以下是 Base64 格式的 Grafana Logo 示例： + +``` +data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAMgAAADICAYAAACtWK6eAAAgAElEQVR4Aey9d5xkZZn3zb/P+3mffZ9nDcDAzHTuqs49PZEhCBhBJc10nO7pHKbD9PR07p5AWlEEZM2ioph3dXGNqLgCxhVBRIYRmNy5cjqnTlWdqu/7ue5zTk+DiNIsCn4suOacrjrxvq/fle/7PofX+ycDZNT/pIAUaUUmaRBKp8FMQ1L9qL6S4+VYUikIeuBrn+LppiuJNG/BvHYd7HbhbXLBZ/dB8AkwFokCHsAH6Kb8IxTHJIyBHwgDMTBT6h7yWAmb1L3sxyEjfxkYxDDQMa0nWV0vyE2slwZ5JtUO8v5JUhgk0EkRw5TnUg9sgJm03lsezkyTIU0C2VrNJU2WsdtTPVQyAmYU4mGIhDESaULAcSG5RjwJEQ8YsxgEOZoOcSxjvXsyKM8nL24QJ4UmF5TnlL7IWLure/G/3lnn/PVu9SrdaQVApO3/CCAZAYjNSLIVBrD/VMwSnsf4/B38ofWthFu3krhhPZmaLJZuyEY7vJPIV++AwEnImJwJ66qTFcMLSswkGWKkiKqtMIICwB890zL/2lwoHGLYnCIMtMqP3Md5N7mMDRDTBkhKAURAqNBs3TOdspjWERgrmkYuJbQMEPUeKdAEIBrIuSIKEiZ+B0ShADz7W/Tjv8TMLOIjybxcJwNJOUgAkjHQSFoAkedMWn2g7rXKV/9rnfZ3DRCRjgoN0ik2A0nDLgMkbYD3aU7dPcRT7ZfhadmEVldA/IZ1RN6TRahxO8f37CTyxU/B4pySvOlYHNM0sZhQRKgwTRrRWALOZc0lWksoY30n0lPkuMBCPYCcKn/Ic632Iy/ivNvy+4k2EOAamDbJ/rIKFYEhx74AWPIWcpRhv8dyu5mQTEEkmUYTjSsaMBWDiA9mjsF/foWTH76Z33zqEL6jD5IgRkTeR64valfOQQSL6My0Ap/c32qvlNJgq339v8Z5fzcAkcayBKrFkNIBCiDOD/Lj8jG2iZWOwvGHefxQNY+3beHk7grCDS7067JhRwn6dZX4d72L3zVei/6Vz0HYB/EQJINKawRTQXVP+UfYQEjdRphITBlTNIrFqBopIsqcsZnaQYww0iv5yA1XkuJ+eRJREStJvrMFhnO8A5S09ewCDoMkCQUw67KxOMQMCBkpkok4JIIQnYGf3k/s7mlO7N3Fw7VX8J2Ot3Pi/rvBXMLMJKxbx+UR5L4CEJ0IKYUbeV0xAUXDZVSrvZIGeHXPff0DRDGE9PRZPhGec8jhBWcr30uXCWEG4Xf/wW+H38ajXVUcaS7GX+dGvyYX6jeQvL6MZO1lzFx7Mc81XkPyM3eC/xlIz5LJzBIz/bbUtUyKZaksUtPUIS06wzK/LGluM6jwrVg9wkCvECDOe51lE2kL5w2drdU+Ths5bSBbMacsVMtGtKDFug5+5Q00Iw2JFOhhmD0C3/goS6M1HKvfiqfxMo7t3MLv2i7F97nDoJ+BpG45IXLysgYRgIhvJPeRu4QVibZ7LX/+rgDiNLTT58IADjM4rPI8HyXpgYc+yXODF3G0ZyPPtZSxUFeM/9p8MrUVJK4rIX5NMfEdm1jauZ1j7Vfj/exNcPoRSB2HxIICiHI+Hb4U00mYSWkP4RAhHTKiUexggfCEPJDiUOepX/5W3tN5R9m3PpZZJ6bdWbJ+kWPkto51JyaVxbBnpYtcT35XwFDXt8Ee8cJ//wj9X6c40fF2TtZU4qspJV5bidawCU/HxWgfHoTwccuhl4srE0saRnwQwwaIZQKa+BH6B0CcfnvVttIBK8jmFId5zjKEmA+WhJTIkeoYYxY+t5/FtmJ8zeUEWzdypqmM07VFhGpK0W9wYVyXh15dQLxnG/NdF/NE00V4PzgAv/0OLB5RbyWKQD2CML5wV1KMbIlmCSgkapQEkcLCNPJ72mJAsdXl+Vb7cRh+mcnlQvKl0IomUfs2mOT28rwCaiErgiW+hXWOaBSnzRSw4/Mw/wR87zN4xht55vqNzNxQQXj3VoyWzRjX5ZPcWUigrozozU0QeMbSNAnIyA0EcaQRE1N8EPWn0hoSDxSSRnntfl73GkTMAsvXsDnCYZAXMERc2dei2i0HVnWMdpro4etYuv58orUujLatLLZsZKapkqXaYqINRZi7XWQ63ASacwh2lhPtvZwjdVs4M94ETz4M8ajFjI5TLlsJLavwsu0GCA84JpX4uEAAVHBYGHa1H3lVuZaQxXgvAIh86QDFDqu+ECDSIstS3AGWnCdmUnwRjv4Y/XMHON51OSerSwjv2kCqdRta81ZiDZWwqwjq8onWFKIfrIPQs5CIKl/ekJvZDyagFJJbWKFuiQFLePwfJtZq+//PnieNLc64lUuwTYoXMITwZowMgbSu3EIjE8NMiKMdhmd/zlzrRjJ12UQb3IQaKojUbiRUW8VSQynzjQV4mtfjbz6fSNN5hBvXsrjbzXzTZjz1V/Bs0/Xw0A9g7qRy3E3DRzARUJpKni0ZSljpEUkcCEBsQR3BYIEIC2mxw+WBV/dx3v950TP5UshpBxskqURG+cvCjtImwqyyDYZ9pDPiMKfR4hHQY5aJdPIIPPg1jrS/nZndW/E0lRJodBHY5SbYUEq4biOx2goi16+D1iLCO/PwDL0HfvdD5X9JFNwXP+vjyL2UMJDnUs8kRpzkjv4BkNX1/l9wlmiOhHL4RIbaDrA0vs0UwifSMVEkuSWJsyTxRACMIKSi8Nj3WWyphLr16PWFaPVlGDs3ou2swldXpgCy0LoWT+t5RJreqEASaMpRDGLs2E6w+u2c7mkgcM/t8IdHID2PSZAQUaJmSrkAypgXXrClaTIj5kZcRXXiKlH4ygAibXA2Yme3wUqAJDMWWDJgGEmiWgzDFL1hCRcjHkWP+kgaPkgHQUyqIz8l+fHDzLa/i0DdVrTaUmL1LsINBTZIignXVRCpK8W3cx3Jdjehnfl4970bHnsA0rpi/QWxLqUf7SiZ2pd/BBPio0kQQyVO/4LO/hsd8ro2sYQxRPYJSJSZJYwhHSBkWoJUABJRqTLRM0m08KKlPYwgiR99kZOdlRi71pOuKSS90wJIrLqK2M4yZTaEGy0N4ml9M96W89Hqs0lVu0nt2Ii+YztPv8XF8ZZ3EPrkAfj9dyF50gaJhscwEP5U0twGrZlKkEhKwDNkZ7gV27yC7ndUxYtfwkymMZMp5L7KF0pJNj2OmYiR0MMkRWsIoyY8MPsYia/fyZmxGzjdsInAjjKM6nIS1aUKJOH6UgK7LAo2FBPc5WKh9kJiYoJWF7I08G5SP7sfMrryLuZsYCjZJYlFp39EWKhIn4TBVy8gXvyN/2e/fd0DREoY4sqvsEo8lHQSCSV8Z5c8RDJJxAeRUKvmm4FEGDQ/S1+6k2NdG4g1ZWPWFJLZWUZi5wbiOypJXF9GfIcbrT6HYNNaPC0X4G2+AF0BxEVqZ7k6NvRuN96dGzjR+VZOva+LyMNfgOizYrwQJkIkY1qmhcMcSZGccTJmCF0XJ/UVAESuuRytOssY8rWjSGVf12MYsbDKyYh0z4SXyIQWIB60hIU2D7/6FjN37uVo56XMNpQSqXdj1LpIVBdj1JSi1WwgUrtBaQ4xscTc8u7O40z9hYTa3UR2uvD2vpPIA/dBJooXmLOfQwkIx7SS13X6RwIY/wDI2Y77n94TDWKVMCQtP0Q6QRpfJJRsJXyfgWhaoCFaJk5SACKM4ZnlxIemOd2+mWhTnvJB4nUlmDsqMK8vVwDRdxYr0yLSkEekIYfwrhyCjXkqmajVFlvMc0M++k43vh2lnKzfxqmpRrRvfRwWHlPVW7G0D40YyaSBGRVJLV66xSWmZPIV96yyZRQSnIy9JRDkK7m6NIES1CIYMgkykv0W3yvug+giaB7LnDrxK1LfvYeT040cqdvEUm0JdFRhtpbhr84mXF9MuL4crWYjevVG9JoKYhIKbypgsTmH0w3rCLcWkbjBTbD9SrxfuxvSfnyYLDmvpQIXKzSpoFceVJlX/9AgTjP9j2/FsYyRVKQcdWlr4QrHIzQhYUIsbSq7Py2Z8/CC0h4cO8rRw3uZb9mKvstFZJdoixISO8tJ3lCuTKxItUjSYiVNtTqXAotyVBtd6ju91gWNLpI7skheV4BevYHFhks4PnA9S/feQup3D4B+0o7WxIjrYUxdEogWs4j584o+DkCk3kku9YJIlTjikZROUsIGKfEvvJDyg+EB3wkSj3yD2dt7OTnwdk7UbySwq4pE0wYiNYUEavOJNJfiF5OqoVw55HpNOUICEKVBmgo4U7+OsBR2Xu8itvsyFu65GVIegsRUpkN1hiRNRVvY7+3UellZ9FfYBq+oAf/8ya9rE0sAItlZAclLAUTLpIkmJfQoUZoASNLrsV/x9Gg3vqaLSNcWkagtQq8rUY6nxPT9tWXKUQ/WVygJKlJUnFIHMFKSEqvPg+4K0rU5pG7IgdpSkjdUMn/NBmbarmLu1n7MR/4NPE8qkMTQCKSlhtcSnlIoqyTpn++nFz9CACKaUsiWyqI9RD5ICkLyDhF0YmYYQ1+CmJhVi7BwlNPf+zK/PtBGtPsSwlefy+w7z1P+RazrYhYbN3K6upTFunIFDvE35H0jDQVKMKg2qCtV2mWxJksFOHivi2TdxczdNQqJWaKZABKtIxO2KhZsh1we09JuVtWxFaJ/8dd7LXz7ugaINLb4FpZ/YYd5RZ07XJK0SoESaZOY5icj9dcSvZLy7Ie/y+mBBsINW0nXlJKsKVEAEfva11CCTyI0dWUogNRV2FEbkZ6lSoKKjR6pd5FoLMLcVUSqzkXyhgL09+ShS/a9fjvB7qs5PlJP8vufhugzKjEmxp4wsDyiVIorS8PGibP/oowhP4oIdrbOvi2V5VfHtLJyDhLhk5yPbmmN2Ax4j5L61bc58pGDPDTcyFNd78SoLoTq9dBUjL67grn6ck5Ul3GmpgJPQxXB+nLCDW4VwXLMSzG7YrVWW/h2ZqHX5cF1hcTrt+G5bS/EThNP+YjKmwowklEwJWJllZo4Cl4EnHqdF33h18aXr2uAqCa0TQtpaKvCVuobjGVTS3zAuCHJvCCYAZICEM2DcecowV0X2aZDKbo4ohLOFC2xTGJarKA66xjruGIideUqbyI5AUvTyPluxBwzatzqev66TXj73g2fvRWOPQpxj2KaU1qIZ2NhO5ttMbcw+LJ5btsjmYyE44QEHBKIcLZytDU2Q5KOkmqRrELELsBPZOKQDkPKC8YMnPkl+r/fydHhnfy+YRvzjdtJtl+GUVNMosaFVudW7y2ACDRUqPdR4Kh3tKZoEREK8t5WG4mppTfkE63OVu8c7ryMk/vq4fhvVeInYJorhJVIAyvULhUN8p6veXQAr2+ACCrEvLATcAlV8xNUA4WUHo+DRDWTCRnLEADTgxxDeAbz5naSNWXLwBCmf7kkibJw7VYCddvwN2zE21iKv9GlnHkV7arJg8ZKaLmUeP8NxO+cgF9+T4VUpZJ1MR1TCbuzDvXZ6FPaCYvKOzpaQrbCWYoEKOJbpfASZyEVYTERJGRKUFukdRik1mzpaXjk6yzePcLxve9ltmkbkboK0tUlZKrd6LVnGd5h/L90K8IgUZdPpCbb8km6L2W2fycc+ZXKhQTkOaV/RGWIv5XRVd9IxbAChy3cXhu64sWf4u8OIHGkFF23OiYOetQkrQoHxbySMYE6zD5FdLzOju8XK5NJpOHLJqVdJPy5Udnq3sZiPLsL8O7OIdyYrULEyVo3qcbNeOsv4Wjj2zl2yyCZn/4nhE6qkXppCSRImZZpkRPkUmkLqWdaaTeJ8xJNk4mYZMIp0mHNMhkTS6rM3Kpt8oG5CN4j8Mwj+L54JzOHezjW/HbmqrcSq5YQtovUNdkY165Hr7W1ggpGSEDiLycBiFGbpwAigsHTtZ2Z/hvg1z9WWjKsRk39AyAvDr2/xrciXYWBVmiQuCqjtgFiQDRkmSLL5obk1Z98mKW+d2PsLEHCtS8bGDaYRONIIk2rLVcOqwzTXWjJY6ElB//ubKVJQjuyiVaLlN7CfMOlHG27iuMHOkh842Nw9BcQ84IeAc2maBhiMuYiCJEgEm3j2afh6FNw5En4/eOkn3iUzOO/hsd+Bk88BI//CJ78L3juF3Div+G3P8T4z3vwfewQj7VdzTONV6roWrLxIlXGn7khH65bR2ZHNhKJezmgWHmsACReY2kQ365Cljq3MrPnGvjJf6j8SlTU4PM0iDUGRHyjf2iQvyZARHur6Ig4wFGVEFQdk4BYWPS8HCCOokhXP+Eff4XZjiuIVxe9IoCIeZLaKTa85bB7mwqYb81jti1HgUQ0iUR+gtflEb2uGKPhIoJNlzHbdDmefTtI3L4HfnUf/Pwe+OHd8B+3wudGMT7cQ/C23XhursV7Yw3ew9V4DlzP4tS1LIy/h7nRq5nd/w7m9l1FaLgeT88OllquI9xRjdm/G/qbibVdz2LNFczVXsJ8/RYWaivw1rgxGlywuwh25UN1tkoGrmT6l7MvANGr84hU5+JpzGexfSMz3e+Cb34GdC9xGaIrALESMsrekuG/UtHwD4D8DQAiDS9DPsVZd0I6CTFLRJJJNEUAEjnJwlc+yJmWi/4HAOLG3OkiVS0h3wKVPJtvKWCmLQ/Zirnlr8kjurOA5A1ukteXkthZgV5bRbhhM77GSuYb3cwJsHa7WGh2sdTsxtPqwt/qVhRocRNsLiDYlE+gMQ9/Qw6++vV469bhq87FaN5GtHoLwasriF1VBddeDDVXQt1boe5StOrNxHZVqfox784cwrXryezOh0YpmblQDTF+OaBYeawARNuZvwyQhfYK5trfCl+4EyLzmKrU3/ZDRE5lZEShjLBcAZC/Bp+8gnu8/n0Q24GV9heAWMM4ZRyG3TGSaLYdRFI+mP8tpz48ohKEEmmSTrZCti9/K5EfAUequkAlEcUOX2h2M9viZr65GE9TMUvX55KQ7HRtKZnrCkm8NwdzRyHpWpcybxJdm9G6thDr3EqkfSPR1irCzZWEdlcQ3F2Kt86Ft64An02B2gKVxJNEnqIGF776QjUSMlBfonI2oZoygjfIwK9CNfhL8jvplgqSzUWEG7Lw1a5hqfZNeOrWqPCtFcaVUO7LI2m72I48wjtzWGrMYb6tlPnWizE/cRiC4mNJlMQ2g6WfVFhXQs82QETtv8Y/r2+ASOPakRALICKh7LCW9YX6XUq9JcRI0gfHH+H0+9rxNm9RodhXChAJkUrNkoAssEtAUcrC7nI8jRX4d1UQra9QtUzmDS7YUQA78mBnNunq9aTq85h/73pmr8ln/rpCFm9w4a0uIVgrSbhyIg1lBGqKCFbLAC6poC2y/SUr6y8l+r7GXPxt+QQ6ixR5W4tZairEU5uPrzqPeEOxer5kvYtUc5Eqq5mvXcOJujczs+tCAo0FLxsYDpCk7aLXWwBZbMpisa2IxeatpP51BHzPWZM7SD8ICRgUIOz+Wf77tY2Q1z9A7Ia2+kEST45TbneMjHKNZ0gbGsTm4dff4Ll9V+HdVUFkR54aKBWuc7EakkFWMaGaIsK1JWpUnb+uEl99FYHaKjWuRKJGcSlf2VGiRt4ZNdnEa9cRq19DtH6dun+0RiqHy4jWlqhtrKYEi4rUtbWaIixyEa92Ea8pVNtoXT6epizmWtcx15JlUy4Lu3PxNeYTqi8kVluIVmNRTLROg5yTy1xLLvPNuYhzHWhwrYqkzVKitXbmEel2M9ucQ6BlI6cHr4VnfmbNpyUdY/uIFhRWRFVe29hQT/d3ARDBiAMQ9VYKNHZ9kgKIOIoJ0Bbgh59kpu9ygo1lRHfmvyKAWKCywBGqKyNUW6lAEarZpPyC2M5NaIoq0apLFLOG6yVnsA7f7jX4G9cpYMZqyrBIgCH7Jep4BYrqEhscAhKXTWcB4m/MwrN7Hb6mdch+qEEKDHMRMGi1+QpMAhABijyvgMG3y4WnsVCRf5XgkOvI9TKNlerawW4XpxsvVLVbZ/a8Ax7/nnLUpWOk9spRIhZabCH2D4C8+i3gaGoLILYaV2aX3QkSaZTaCylBic3BFw7i6d5MrEkYNl+Vi0id0epIRtcVWyPspCSjbgOxmo3Eajaj79yKXr3ZcpKlTFyNpXCrEvHFlmzm29YiWzlfEncWSb2X7MvWrv1a3p7NaIs5p0LT9S60+jwStdnKbEPqwa4VyoNrC1QBYXqHW5mSco5VmWuFtSUCJyFu+V7GdayG5Fx2b1ZmnL87n5O7zlNaa777Cvjp1yC2ZJm4diBL+mi5ImA5+/nq88grucPrXoM42kPgIPtn292ydSURJ9l09aPvGJHbWwm3lxFvLlYRHLHjpZJ3NRRqLCLYWKK0kfgL4m9odVUqShWv2YReu4loXZUayhtoKsHb7GapJZ+FtlwW2rNYaslV58t50Xo53yJ1rYYSIg0lRO1tZFcRFp191uguqX/KJ1mXT6Y6H3bkg+Q4ri+EGwphhxuzxi7ErC9S1crisCdqyzCry1TwQMbdhxrdqyI5l8aNGLtK8HbmcqrxXPRdBYR6r4AHP2dVDcuQAztXKH1k9Y/s2QLslXDvX+Hcvz+ALKsSVd+gZsuURLoCyPHH8Ey8B6PFhdkiYz0KiO0qItq4Ogo3FRFqKlYUbSwmtqsUvaGUeH05upSIN5QTbiwluLsYX0sRvhYXntYCfK15ioLNecQaXarcXkruHbK+KyDWWIDeKMesoKZcYjbJOJbw7gKCzS517aVWF/PtFkmoWL6X90vWF6mK5UxNMUIpSXDWW88qzx3aXbQqiu0qJlVTqTSIpyub2eY3k2krIrnvbfDtj1rjTaQWzh4DvwwQmfFFjc957YPkdQ0QR3sIJqSplQax2l6VlMiUm6rOT6KKaQj88gGWBq+E1nwyLUVEanPQmtzEmopXRZHdxUR2uxXJdYTijdY21uQm3Owm0FqIt80if2uh+jvcXIjWlE+8KR+tSfbPUmx3IbHd+RYJgGyKNOcRacl5PjXnWfdoKWapvZjZzmJOdbs52eNmpsvNggyFbZH3c5PY5casd5NqKCbRUEx8V4kyM+Udws2rIzFT9etLlgGy0HYedBeT2Xcl+hduBn1WFVeenWLIcRb/AZC/gvKzAOGAYxkgdhRRaq5UqbeNIhFaz/3nF/ANXKoAQoubUHWWYh6HyVezFYYWZtd259lkMXGoNQd/Ww6ejhyWOmWbR6A1TzF+QrLYdYVkJMrU5CYkz/I8soAk4LIoX4Vy/W15rKRQSz7xxmJl4lgMbwFWQCFg9LQXstRhkewLUOU3Aa7zrrK/WlJ+3LVFGA1leLuzWGw/HzpdJHsu4rRUCcwfeXGAqBGVMsJTek0lSP4q/LKam7yGNYg03AtImH0l2X9KM4udq5xASzjZVq8M2LF/MBIcue9u/AOXQ0chtOYS3HkuWnMBEdEmq6Boi4toSwFaS766jlxL9iOt+QTb8vF15CKmh5C3M5tgezZ6cy5mYz7UCxWo84JtBTyfXATank++dhe+9gLObgsIt7owmmQ8SolNRSTFZNttPVegvQBvRwGLXfksdMlWzrfuFWktUM8uzy/7kRbXi9AL26WESMsKai7FU+0i1FaqAOJrPRfackk2l3F85Fr43Q9UTZb0i5hZ0keqS6WPVg7DVUEV6UyJBzsduAI49kzyZ7veCuf/NQD2NweIemm7ASwbyW5FaShFYh8JOWMhbFTY2DH0FKFYnEBaJmawf9OTEI1DPIVKEkpnhDw8dfdBwmPXIqFW/7X/C63h/6J3FBDrKH4F5LbPLUVrq0Br20CsfQORjgrCnaUEu9wEevII9uQQ6c5C78wi1ZYDLXkgJlPTeQR3WxRqXkOweR3B3VmEmnMJiXllP1u0qwShSFcZEdnvLkXvKiXVWUK6vRizrYhUq4u4Ddjobjk/l+DuHIIt2YRa8wi35RNtK0BvdxHvcBPvLCTTX0Zqj7UfFaEhxyvKJbS7AL2t1KZy9LYK9NYNyxTs3MCZvnJO9RcR6F6P2boGGtbArlx8HZt5Yu+74blHIHpazSujy8yWUuErGJCpkJYk9C6DWVIQS9jDcmWAlcxbJgdYCRQVJl4xQbhUTJiq5k7mPZaLvXqfvz1AnBj5WfFgN4wARIAhWmAFQBylImLJljwpE8JpmXTZBoiIKl2mNMkQlepYmazg+GMcOdSJv/cdBGtz0Rr/mVjLG9A684h0Fq+Kwp3FBLtKCXQJEEoJd5YT6Sgn1lFqkwBPAOQm1ulC63Ap5jTaC0i0uZBttD2HyDIJE+cqRhZmDreKlrA0RailUDndgd2FquZLEnzeXXnonUXqurF2l2J+0QYWMCxm1zrc6nfZxtoLcY6LthUSEQ3TkoO3JQtfS5YCUrglj1hrAUabm1R7MYlWtyKjrRi9vRit3Xq3SEcp/p5iTvWXcKbfRbgzF7NlPTQK5aK1lnFqz0Wc/FAXxq+/BimZ4ySKaWhktKQFDBlyvDLEJdEUGXkY91ujEJVQtPIoAgM51NIvUq4SVmR98/cMEOHpleCQ/WU9LA6FTUqb2ClZOcYGhxxtJFLEjJTS2nYLKmUkQzp1meTTnIOf/RvHB65Fb96OUZ2P2VeAv20Nka4CIp3uVZGAwtu9AU9PBd49bvx7cgj3XECs+3z0rgswOrIsBmupING8WRUW6i1b0No2Kk0T7thAcM8lBHovw997Ef6erfh6qvB1leHvKsLfUUi8v1xRYk8ZiT0VJLorMbo2kOisIt6xAb13I9G+DUR6qwjvqSDUU0mop5xgdwXB7jKWWouQ6Ja3vQRfRzGBrnL1e3jPBoL9Vcz3livy9pap4/WOEhKtxdaUq40F0JxHujWHVJul/cI96/H3rmexfy3evvWEOwrR2oqItZURtSncXkKoo4iFnjKe6d3MiffVE/7OR+HMb0Am7ktrpE2ZsClD1ATNnsPMshIMezoima9LhuxafS7yUMAhW+vj8IYwwtH2mK0AACAASURBVKv3+ZtrkBf6FC8KDtU0KxpiBaDiCQMhmR9agUa2KUvaxJUenwf9d6S+cjNL3ZdD6zaodcPQRubb1qsSiWhXEashMXVC3WUEe0oI7ikk2JtFqG8N0T3nE+9eQ7IzC7O1ALO5HHP3ZhK7t6G1bCfcth1/5za8ndsI9V9OsO8tCij+nm0Eujfh79qAv70Uf0cx3uZ8fM35BHbnK5NHImDK92kW/8ClGFGAtJIsX8XyN8I9xaykUHcRDgX2lLDQVcRiVyn+7lJlthldZUpzpFvdpFsKSLflYrZnk+jMQutZR6j3Qnz9F7K0d41633SzG5rE9NpIoHMjiz0bWNhTgWdPsSU0ess51V7BM3vfhudTY/D7H0JK1qAKq8k2ZhI6c8kUkUzGsrClRF40iZhYQmI9KCjZUUpHOFqqxP7y7xkg8m4OwysOFyDI2zsSwop2yOwXzmErtzK6Wf5W/5j2HAEx0FOaWhIMjsLv72Pp5huItGyAzougqRRz31Zm2wsJdYttvzqA6J2FinnS7VkkOnPRugqXr6V1WXZ9ol2kbw6pVrH93Yjd7unaxkzPW5jv2U5kTxnx7gLiXUWWuSQmTGs5sdZKoi2WTyO+jfgClrlUgN6Vi96VTbxrHVrHhWida5ZJNNdKCrW8iXDrm4m0nUus43x1XLz7QoyetaR6sqC3CPaUwZ5i6Cki2eNSzxPtzifcnUeoJ5/Qntw/okhPrvJj2LUBdm0m0bJBaadZ8UkGyjk9UM7inlLlR9FZgtnmxtNejveDTfDYVyEzq2Zc8WCySEZNESTTM1n9qEqwQeYSUHPAyJgFMaDtyQGFPeRPoRVy89WAyd9egyyDwgGGAwirLFqcMGuCaqfe6vlbOdoBiClDVMW3k/GrMsWPcZzQo5/lzGc6ebarglBjIXRuhLYK4n2bWOouI9xTSqy7eFUU73JBe7aiTHuBkrzJ9kqMjg3EOyuJdxUrHyfWlaUcdHHU/T1uPD3lLPRsxttdgdaejdl+gTJhku35JDrcGJ2l6nytu4pY9xYi3VsI7dlCsG8zgf6N+Pduwje4Ed9QFWe6rNzH6Z4SzuwpZqa3jJneEoRRZ/tKWdi7gYW9FcwPVDLXX6a+l9/P7CllsdtNqrecdFcRiY5Com15hNoLCHQVEuotItxfQrC3yNrfU0S0pwi9u0iBOdlZRLqtlExzJWZLFVpHJYEeuUclswMVLPaVEepxk27NgqYLQbY9JSwObufY+xsJPHQvxI+rhT/DagWqJFEzoeYPVh0qnSrLRygUSKeqjrU6X76WiMzfP0DssJ74Fyu0howXsIBhgUN8CecIZyu2qFAsmSSeThNPmWoOWjVBmRGGM0/AL77KsX9t46n9F3O6w0203QWdpdBdTqijhEhvJdGeYtXx0vkvl2KKWYpJdhSTaSuGllKbykm3laN3lePtKWa+z83sgIv5/jy8vVmEe9aS6DxfASO9ex1mSzbptnzMrnxSfS4Sg0XEhyuIjFUxt7eS0/u3cmb87cwcvJ75W1tZ+mA/3rtGmf/INOZ370V/4F7iP7gP44efJ/ngl0j9+IuY//UV0j/5Mvz062qrP/B5fP/xUc588Q6euecmnvzIAf5wRz8nJt/J3P4tnOyt4GRnKTMdxfh6KtH3biWz/2IFVKOjklS79U7yXplWi8SJj3bnEugtZKm3ksU9W/D2bCXSWYnZng9ta6BnHVrdPyEROnPsYkKjb+NY18WEpnfCN2+HM/9F2jyhpmoVq0F8SS1h8b70tQjHsyCRCejsUYoCDvHa/741iAMQx5yytgIQmQjO+k/A8XyAOOCQBtRUOtCad1eNGpRZA71HSXzn4xw9UM+xfVfyXFsZsaHNJPZWqmiS0Vem6qBifWWEbcn4csEhx4v2CfVsINwtGqOcVHupKrVQ5RYSnu0uxttTynxfKbP9xcz3F+DvzVJOvNnxz5jt5xHtKFQOdaC3iuC+LQRGLsY/fQWLN76D2Vuvgf84AN+9HX5yLzz2HXjuUVg6DiEZHSnj1kPWeHZdVqKVCNCfIRn7LueF/OA/BY/+O/z4bmJfmWLu7g5OHtzByeGrmN/7Nvx9VxDu3I7esZVU20YyrZXQWm4JgdZiUh0u5YcsDmSz2F+EV4IEXRXEO0rItOVC6zqMhjcqX0zrkQBBKaHujST7Loaei1jq3U7gK1Okn/0OJGfUNEWJpEnAgGDaWqBKcGCFciWaac/Q6Mx9JoygzIdXw7iyrvk3NrEEIHYo9wU+h0gOAUYsqas1ti2QpNXU/VpcxzBkjiWZORD8yTAZAUZiFk79HP2rt3D64E4W979DRYciPZuI9FQR2VNBuLeEUL+bUH8h4b5CIr1uIr3Fq6JwbxmhgYsI7NtOaGgL4X0VBAeK8PVk42lfy1LzGrQ9Vpg30laI1llEvLcUY28xWl8eS31uToxdzLGb3sviv7ahf3EafvBJ+M234blfw+yzEPFDLAq6zPUlQ4nFiXVyRLIvs+OtklKylqBMYC1zZy2A/1l4+mFS3/8c/k8eYPHWDuZGriW4753oA5eS7tsCPRXQ6YaOPOjMJT5USnS/1F/lYu5dT7L3QrSutfhac5nfXajMQ61rE2ZHBbQXQ1shtBdidhYjkbRj+7ZjfGUcnvsRhE+QNmJqfi9ZWkfm+1KznCnr24CUzOIijrvARozrV//zGgGIo0EsA8oBh4BCZpaV5Q3ipoFuRLEmfLYYJGnGmUv41YqzSgL9/rtEPjPK7ORVeIYuITl2GWLHG50Wad0bCPWV4B9w49+bq8gCyWoBUkJo72Z8e7fgFZ9gpJLAeAWBURf+gWx8XRdi9rthsBIGt2Ds3YZv8BIWxt6B933VLH1sD8YPP0ryv78Gxx4C/x9AZlrXRDNEIBg5G/wXv1XW+FieVtQywxWLCAOthjIQ0ZJoyYwValeTLAgYF8H3DMz9Gn79NTJfO8zcjdfybO9G5nsr0PZvwhypwtxXQbK3HGOPi8SeCzH6ziW+91wi+9bhHShmsbeKQM+laB1vISPRw5YKCyAdORh7soj05ZIa2Yxn5C2EPjEIR36gZoGUyR7mE7AohpcpARd5P5lXQISpRjIZQktbK7682lOXvgYAskIa2supiea0oCLbNEY6QVQLocl0OCr0JwkliWzEVJ4jkzoGj99P7GNDLAxchlcy2AMlxPaVou8pJdlVCe0bSXdUofWWEtjrYnF/LovD2QT3uoj2Fa2aRFJG9pSgDVcR2l+JZ28xnoECtJEiOLABvS9XZdElJzAz9nY8HxtSfgKnnrKWbwuKiSTTg9raQGL/GV2tgmUtj+CYmxZWBCDin0oCWvalrVb7EQmsEttSki5zc6mtRAXl6iLDpdjwGOiPw6lvk3j4Q8x+dg9P3nw1j49cwrHeKlLid7WXkt5bTniomDP7cjk5uJ6FoXxi+ysxujeT7LiEZNtbSXRcjtazmUi/i+DQm4kOvgm616vk5cz+K1n8zCippx8EM6T632OkCMQzhGPidwhARAoY6EkfYdOrVl5XczKvtgH+gvP+tgBRkQp7PT+pwzkbrX0+QJKamhldqVgjjBlcsObXTcv6GsfxPPYFTt3ejm/gbZh9WzD7iwkN5OIbyEbrc5HsLoH2ckWJnlIFioXhXIReKUCMgVJCnYUsteYQ6HRhDFVhjm9BG97AQn8R0ZveQuTO64l/aQR+/jmYewIkiGAzpRIEUhKehFjcJBo3iCY04qZGAs2eBURmApGAhQWI/8mtU8Yhgb9oKkM4lSSc0YgisSUfCRaAU8AxQDTcb0g8803+8O338+Rd7cr8MnsvJdS3nfl+GW5bxtxgEYGhIuJD5eji8HdvJdJzGYHeS/AObMSzz4V3+M1E972BVOMboK8cfeRijo69g2c/PUbm2YfU9EwChlQiSTQSJ67ZdXWyTHVGpuQOqxls/r5LTQQgCiRnnS0l1VZoEGEGNQuGWndcJK3M0O6B6DzEjhH41Sc59slWZgcuJdWzFfZUoHVmsbh3HeEDLqKDOaR686FD7GY3qT3FRAfceIfcLO13E9orf6+OIgOl+PaUEeqtwOgpJdNdCj3lsHczxtTb8PzLTvj5p+H4g5A4LXljtU6JP5ViMawzGwgRNDQFCN1MIsuzyfuKNWGaGSsq5xTwKfPCWbZM5hqWBXGseiWnGVe3XVn45wRJ4qRFi2WiJNJBYkkfkZRHMWWcKBphvJlFwv6nmP/mR/D+6xBnRq9lrutSol2byfRvxezfRKyvAt9gBYv7y5gbKWVuxM3ScD6+/XmE9uUR788j05YNXW6SQ5vxT17Oczdew4l79pF54n5IzEBKSoV04ppOMmXlwtIk1eJ7ii9e5TDW316DOAARBWIXLQqTiGRVklJpFjHD7BIEWedCZicJncH87bd47Jb3MDu+lVTfRugsJ9GWh6f9As4MrcN/MJ/ovrWk+9ZCVxZ05ZDszVcACQ6KJikj8goBstTlVgDR+qvQ+jajD10Od7TC9z8Kz8oquIvq2WViackfz6QzLKUFKhLUzBCKB4kmIyQyoiXOJkOV7y02j+NbSORGrbEh64s4AJGrnHVWpSkdLfyXbOXiGbWIj5irTjLOWqJN1i6MabJMnMwSLzPoy8TYsGgmmU0nmFeGWIq0/wQceRi+fQ/6HYOE915NqGWLKtgUcza4rxDvcBaLYxewNHoBvuF1BPflERkoUwCS+jTJvxgD5SQnt7M0spWjo5exdO8gPHW/NfF2Okg6k0A3TeIpazHSjCwrZ8gqodY7v1r//u0B4jDACwCiwCHS1JnNXCIYRggML/hP4v31jzh272HmhreSEQ3R6YIOF+E9LuYHCzgxms2Z4QuI71sD/edC77nQvwZtMJfwYAnC0JIs1KSj9hatirS9LpjcgD5UxPzQJvx3NsGDn4b5p8CIKZQLvrUURAzQhcdVT6ZVLZKmiZ0vDJ5W852bmRSptEhHK/n5ohpBhIhNZ5ljZSO+jH2ZyC0WISMr28rAfclkv4gfGE0k8IdlASA7ky2HxSGyFLAEl0j5yAI8+RDpL91B+OYmYvsvJj3ottp+4J/IDP4TqcE3EB9cp9o6vHeTigDOdJYQGChH31tKRLL2XbkEhysJvO89nP54Jzz9HYgdVwBWII2nSciO4DlqC5BXCx0yu7u8qwVCJyehQgbqO8dRtjpVDnT8BZHo9okrStXVdV7498t+eOlgub5M/iYmlTT+HERmQJ8Bz+8JPvh5fvPhcZ44cAPcciUMCkByoN+NNlLG3LCL40NZzA+vUwDJDJyLUHLvGqL7cgnvKyLeV0Wytwqjv4j4gMvqtMESooNFimKDLrS9BcQHLBIQRQdLCA+WEdpnkX9ISr3LiN1VAz+5C+Z+CvE5VWQnTq/Id6nkliWRRQEobSDOpvRwRhxhXUlwicwlUjpGUkNPxRFzSyI5MuRLcmEOOf3hbJf7ZYXHptruL/1bhI+Ej6XUPGaQihsqfK4nU8iiQ/KEihclepZIk1RIF7SnIJqBeFqZPoYCV8oSCoFZePS7ZD49RnjyCuJ788kMnAf9b1JgSQ2st9p7oJLA3q3M79uOZ/92fH3l+NrWo7WdR2ZvLsbERmYPvgX/v43CyR9BJqiESzSWsCbhcBpFAdriWcWTTjvL1uFRtSti56yGtnj+zzPnOdIIEuZLRHzWRMpGkIweJRQHX8Jad0KTq0lvSLw9IYVkMjm0tVCNDGlVK4DZW8GQREaU8ycxBzt8n5Sl+WxGERvbuaSEcWUFc7VMmJQTqHU8vJCYA/0EBJ6EmZ/CE1+HH3yI1OeG8XygnpMT7+TkwEai+0tIDuaTHCwkPlRIdL+L0IiL4GghoZF8tOFc4vuzFen7c4kOW8doQyUqY53oySLZl4e+v5zo+EZi4xuIjZYQGxJgZMFQLum9uUT6i1jqK2F+oJyF4U0EDmxn7rZrmPv6nYR++6AFYDH/TA0jFkXTk6TsUv5lIbTcYbYQULkfQ6U6rVUUrVYQplT9smIrESvhCetazvmy1LSMo7BzI85WKjdtyiSd1W1F4NjHiaZQJHMi2ReWrf2gspF7Oc8hW/lbfSQULLNgJERD6giYxPSSY6TfVWjNG4Hjz8ETD+O9o5fZ4Svw7CmFsUoV2ZP2jPesx9hfgXffpfgmrsI79lY8feWkutfAwAUwlEVsbw6nRyvQ75+CpafsnE8aM2pYkb+krpZ6ULP5y4vI/QUrK7MG0lRKP69MPC+/qv1Sf3pzjrycNL6KMZuy4IosmSXrOFg2pyzMIq6gxdEyCCmo1vjLxCIktJgFBFuxpFMmYhsSF3tCA01UtzSmbkkXZxZzZ/bymAf96E+JHvkRoce/jf8XX2PpwXtY+vYdeP79MIEvj3Lqrnrmb78e7/veReCmywkf2kZ0spLoWCmx0SKL4YXpV0H6UCHJvhxM0RLDZUTHNxCcqCI4WkpoqIDI3vUw7ibRn6Wknj6xhfmRbfxh/3ZCH2uFR7+szD1JWjqfRCJBLBZD0zQljZ3vX3wrvWnZ/zJ+XiJVKxnTAYnDoMK4Vu/rloMumeWUQSadIiMqSqSVSB9RVbL5c1slzUTQ2bafLXUdPpNnEZKntLFjD2Kzw+xqQRxL0zjaRiaxFPmZ8SVhdhGO/Abzm59k7uYmTvZvwz9YRmaiBEbzVHLRN1BFYPhyAiOXEhnaBMMlMFkEY9kk+y9Q/ey9/Rq0733YWutEVqtKGKTj0ioy1WzMjmbZAHEALw8u+zZABB4yq7z4U897nxfvmOVvzxEAyMupj7Lzg6QTIaJxHa9usBCPs2RohBMBjKQPM+0V11I9WIogaWbI8BzwDKSPgnEEor+DwOPgeRROPgJP/wh+9Z8gSwR/+cNkPn4Lidsnid/aS+TA9cSm30ls+h1Ep68gOnUZkaltxKY2E5ssJzRWQHgsh/D4WiJj5xMZfxORsf9DZOz/IzL6RqIj2asChwBK2+9SmeDEUBnJkSLi48X4xzewOFbJ4nAxS4NuVQ+VGK2AkQLM0VICt1xF9L4x+O13rYnolJMr89IliMfjpFIpMlK6ncmofadpX3wrjCzhSyHLbBXmdCT4SuZUHa0Uhy3BJR8kmfCMwMoKdr7YViw6iY4JU8jvcm2HrCSb46BLyMAyQZbVuxxonWidZONOvhKRICR5KusJFCdawJRdeXjh4XgKluYxHrqfUx8Z4pnxK5kbLCYxlAWj64n2riXen0+mJ59kr5vwyDYiBy4iPOrC07de8cLMyEV4b3sP/PgOCB612wuloSWJLIsiSTDheRpkBQqsuj4Bk5AVKZRXUzLkxTtm+dtzfAYE4qBpcUjIEgGiQXyoiZ5lXTtZjEXq95NnVHUskT9A6Aj4nwLvf5M59XUyz34W44kPE3zkfSx8e5JTX+jj+CdaOHlXPSduuZaZm65h6dA1BKbeTXT83ehjV5EYfhfsv4K0lB60rrOofS10rCXTfSFmz/kkxLEeW09mYh2pqTUkp8/DOPBm9ANvInbwjcQOnE90NIfYiGt1NOzGGKtSlBgrQRsrwj9RwcJ4BXOj5cwNl+Ef30RkfBOJySrSH7gavvMvajkzlctIWhJbgBGJRBRAlltWBJiYpC/1UWgQ6b1CggtzvZBWMqpjPigT12JKh4dfbCsOdixpoKVSyq8xMk4pqMXcsqSoQUwZuSJd5Vbq/nIxYXKH5L5iItt8L5aHkPxsiWo7BJ0W/8qW5vJ4coK0kyyc+uzPCX39Vv5w8F0cE59utABz34UwKIGUtUqTL+zfyqmxS5gbrWRufwmBqYsIT28jNl1B5K6rMR7+FETFz4OIWPzqGawckWJ4555yXxsBFkAERJJ0PeuHOL+/VBedE08lEScrbUSs9fOiJyzJ/8y34NHPwoN3wPdvg/tvIfXlQ0TvGWPpQwPMvL+ThVvqWRi9FN/wJvwjm/GNbVQMFZjYiH9qE/6pjYQObyZwuArfwUoWD5QyN1nEmYkCTo/msTCUA6NlsK8Y9hXBYBH0F5Lqz1cx8uhArpLy0RE3oVE3ofEiAlPF+KdL8B8sJ3SgVEmaVwKQ1HgF8fEqgpOb8E5swDfhxjPhZmZqA3OTGwlOVOKd3Er0I+3w8/vAd8Raa1ySe7bzqurCEgkr4ma3tmiUaFTc9D/zkU50ACGdqrhcfAMxfSSDbPsJDvfLMSIsbV9PggGJjJVDEfloaRFHq5hKeyjZmZHsQep5f8tKHWFSyh6I2KFcuc3zJPELASIxhhf4RkozpXTSMlow4YOMU0Wlq+XvTPFX0mIO+sHzFNGHP8cfPt7PsQNXkh7Khv1vhulcMjeWEzq4lYWJS5mfuBzPgSuUsIrfUoV5sBD/SCGhuxvgN99S682L5SPPIs8szaIwYfu/0qwWCXjEz3PIEir2j3+mc+Ac9VKiNdIRCBwn9N9f59i9+znz/muIve8KEoc2Yx7YTHzqEiITbyE49jb8I1cSGroMfe8WGK6CoVIYKoEhqTsqJL0vj8S+XLShLEJDa/HvX4t/bC2+qfV4D67Hd2M2gZtzid5UQGK8EEaKyIyWYI6VKDMmNVZOcqxSRTK00SoiYxsJj2wiNLoF/8hWvCNb8I5sVcCMjJagjbpXTfGxMiLj5XgnqlicLMc/6cY37cJ7eAPew1uZP7Ad874BePJ7EJoDQypKlz0Ba3KOdFqZVIq3bPPKMbNeqgfOduJyb2LNdCdOthTnOSTOtQUMcYSFKcR6ERNHysPjCYmAxe0QsZSKOBGbF9864WQtIwCxAjGOLyq3UcyzUhLb9xZQOiFm59klEKFAmohjGCFMQxYp8trl60FSpoDFHs8hyU0zCAkv0T/8kvl/uw3/eBXpobXo0wXoN1eg37gR7/gmTo9eyszEJSyNFhCbyiE5uZ7wcA7+qYuJfX4M89nHl4fjOs8ijynkyBILOKI1rECI1WK2KeYIJTn5JT7npPynSIdnIBmA8Ck8D3+e37x/J8+OFmMeLoDRN8LIG0mOZhMdLyI0uYHQpER7yjAmpPAvm8DeLCKDOWj78zFGXSQnXKQni8hMuUmM5dqUTWIsG2M0i8ToOoyRtcRG1xM56CZ4qJjAwRKC08X4J4vwjxcTGCkjMFKhIkcS3ZDx0+GBzeiD2zGGLiO1/0qSIxersG5srJDVUGSsSDnkgZES/KMFeMfy8EwXEjjsJnmzm+htF6F9dRKe+xnEJaMLft3qbmlXMyVh2hSmaSpSOZuXaOwX/mR1rGPDixx27CdhfWdfutkyfWTPAYcDEHVN5b+IDyN5ColWSeTKIJOMk9AiJPUoqXjMmjBBQrLyezqpQC3Xs3wJxyKRu8i9rXs6v8tWgUcBR7SaDV47IJYwIW5CTGaXkSy8MsAkT7IEyNqQHtLxBTJSjStMLNp39jm0f59Ev+sqZqc3sTRRijblUn6nRK/OjJah7V9LYug8jLE8olOleCY3MHvr1cS+eYe1arDSThaopT3l6eV9HLJmQHkBQBzwy/bPAURlZePyItKwUcK/e4AnPtzOsclyuNUF+/8X7P9/SIydS2wyj/DBUsKHK4gfLiFxuJTgeAH+cReBCTehCTeRiSKi4y70CTfx8UIFltR4AamxfMyRPFJDOST3ZZMaXI+2fz3esRwWpnJZmipQzOmbLiI4XUJ0qhxtagPahPgIm0iObiY1shVz+CIYvkRRemSbKgpcDTjknPC4G+9IMZ4RFwHJ8I5egH86i9BNbqLv38T83deC/7dqzUDhKbF5fRlL4lpdIZ2dUqaVOOcrASKgEd/kpT/SQ1bnOSsvWdEWcTytDLbjBJ/VWfYKthkJKftAPw3h58D3NMz9Fk78itQfHiH++x8TfeKHJJ9+CPOZn6rv1e/+oxA7AfHTYMxb0UUpo3cYXkwhO6sugBVj7awTLuFKu6hSwsiqzN72n+xKY9FEEviRtXZ1Ff4JQnqRdPy0BZC0rFNoB4bk9aNPwX99kOMf2MGxye0EDlWg31RM+MZStEMu0vvXwPCFpCbdyg9ZHC9jZnIz0Q/VkfrG+6wlLdSzW0EOAbGAYzmqpt7BgYsEQ+zkohz4lwBE5a1slS0Pju7H+8h9PHf7e5mfKCA2/Ab0oX8iPHIBwSkXnuly5ibK8E+Xod20geBUGcGpCkWhyQqEIpNliqITJQjFbNLHixGSaJFFbvSJfPTJvGWKT+SzTOOFygQTMywxJtrITVJotFiR/C1AjE0Wroqik26lrbxKjWeRPHgh8Yl/JvIvJfDgYdCetMpaZGJ4ex1ykaSW0HEkvLTyS38EPLpujWER08v5SA4jri2RSPqUByDgEEhJ5wqjiQcTjmtkpP5MCjNTpyH0Gzj2Tfjlx0g/cCOBTzQS/WgN4bt34L/rOjwfeA/zt13F7C3v4Mwtb+fY9GWcOHwFc7e+E9+d16J9tJbUZ3bDfR3w5X2qnJ2nH4KFp60aNwmjSoLWtH3S9JI1mMk4qRK1GVl70IgSNNJEpTRAluU1ksrmk5GAQUAMLClVl9IaaTe1aKdjZknEzp6pRDGoVEZEn4Hf34/vi8OceP+78N6yidShtaT2/2+Sg2/CHF5HeiKPuPieN27Ff+M2jOkNykcJf+cTVhY/EcaMSvGqNf3TYjyCpoSM5YNYsEla95YucwDidMaf2J4jLyDk5DvEZDCO/YLFL45wfHoL4YlczIn1JCfy0cZF/ZUpM0tCsGJmCRhCU2VEJmxgONtlkJQRnRCywLJyG5sQoLjPgmA8n4RNFkjyiE+cBY/Yos+jyTxik/kvCQ5R2S9F/uFcQuM5hCbWEphah3nXBnigD05/H+ILymwRwSFttBwOtxX4yymWE5CIMy+RLdEulo8i/kJSMVw4GkI3pHpXACg9KEwXAP8JMid+jv6rL+K7/zBzn2rm1O3v5PTN21g4UI55axXcVAaHy0kdLCI5VUR8sgB9rIDYmGSkXepv0ebaeN7y97GRPPxjpfhueQ/zd7TgvWeU2P13wi++Bsd/CsGnWewSOQAAIABJREFUrahl4jikjoM5Axlh+6gan+PLZPALMGI6BMOkQgaiMB1eEpDMZ2TuEqvd5L2U1lUmoJPIdELWsrLvKTVoau7rh/j9wUtYGvg/MPZPcFMuifG1aENr0MfzCB3cRHi6HCZySB7exKm7u+Hx74MmGnEJUrIMuEwimCaUljCEFbZQ7SlWkoDT0RxnZdWfgAeoRKG8lLyIkPrI6Lxf3Mfs+68ndnAzTBXDaCEM5sCgC0bKYX8pZl8+KQmPThYRn7C22qSzLVLfy29/mkrQJsrRJiptKle5j9hkKdHpEsIHilRFbuigi9DBAgKH8vEfzrUpm8ChXGLTBS8JgJcChzBScjKb6NhavBPZ+O66nPSDN8HSTyB5gozhU1BQhpI0pmpQm3ntBJ/V2k7D/fFWolkCCgGIbJ19OVKYRq4dk7XSRTWpS8cgeAaO/hfmw/eyeO8w3o8147ntXSxOb2RJqgRGckiM55GeyleCy5i0BIs+nqtsdW0sh/hoLrLlcCncWAIHizEPujGnXDjHByeLmb3xLZw4fCUz0xfhnd6Cfsul8OHr4EsD8K33wZmfQeiYmi5GTC0pwg8SJYIMWJIKWystYbstjnqVOfsIJayRJSJYxMhRIJE2VOZZ1Brbk05jZsScFDEUJn3mlyx8dRrPwU1oI2tI35hN4uA64pNr0cfFhy0iNV4E09nKxD86fSVz98mIxAdAgVnK8wXESfyGGHp2vylgiI8mZDvqf9xdf/TNOVa1pl37lcpYGVnJpi88hv6Nmwh94N1KnaWH1sPgBTAsodkC2F+golWm+Bc2JScKEDImz5IwoZA2ZZEw9DJNFdmAqLSy41PlyvcIT5cSXgGQ8IECwgfzCR3KJXQo26b1hA9m/1mA6NNu/hQZ0wVwcxHBiRw8H3gLPHirFeJOLZJJBkiZcdWxwruKeUX6qQiRdKZjqyvD9I8a1vlC8iOiORz/RLYCFkVSniP952BOxpk/8wsSD3wC/z19LP3L1fimNiFCJzNZCFP5MJUH03lwoAAOFpAczyE+kWMx/VQeyelCktP5pA64SB0oIDFVsPy3hErTh4rIHHYr0Ji3lBG4uRLfjeVEDxRgjGeTHlkLYtIe2IL/pqsI3TuM/zsfRzvykLUwJ34y+EixoMaLCOOr9hHGl3yORN5kdsSkTsaQ3IP1+/OOU+UqkuiU8K+pJsEU40hpaIl0Lf0GfvAvRD70LuZG1pO8OZ/MbRXKWtCGs2HKBYfEesjDe/PFPHvL1YTvPwCen4J5EtIe9ERImaeqH6R9paHl+eTeapIQK8Ln9NOf2p6jXkYShAkdMx5VJM46yVk48QCeL/Vx5raLmBk+j8jUGzBvXoN2+Hy8h9YSuTGflHTYuE0TeTCRp+xFczJP/SYdJIwoYTztQAGxgxZFDhUgFDvgPksHC9EOCBWgH8jDmM4jMZ1DaipLkTm1HqH01FpF5lSWurZ1jnPu87f6QRcvRfFDbvzvu4zQNw/D4qNKikXSCbwJqYsS7rWljlOEqVryLwfICxteTCtHm6hybcl1BL2YR39J8PufZunTQyze9l6CUxswhBluzIcDa2HiPBg9F/avIbN/HYmRXKUlBBzxqWzVVsmDeaQOFZK+sZDMTUVkbnKp743pHLWV4+JTuep4fVLOuwB97P8lMfW/SRw4n8RNBRg3V2Hcsp34TZeh3XQ5wUOXMX/wck697z0sfWEvyUfvBd8vgTNqftyQDNu1eU/5LhLmjS9ZVdcyMExK9O2aNAGSEgiqUSypEIj6kJiXaFJxaSxTSIYzHIHffZngnVeRvHUzocMb8U4XEz6YS+qmfNKHRBMWwPu3MH9oI8++/53Ef/JBMJ6EzDwyGjMptWdyTUGpyDYFEvlHqgYkAGFVD7ywj1b+fQ4pAYc4ZGEy8TAyDkBFtERCmrPEfvkZTt1Ty7ED2YRuPI/UbRcQuvHNzNy4Dv9tJYqRxYESElA4JMBJKHo+QFaCRMAifys6mId2MG8ZGNKpFjhyMCdzSCvKgoksGLdIvhPwvRRA/n/e3gO6ruu689b62swksS1ZYhFI9F4JgBSpFpdxquM4TuI4zngmseOZzKRMkkkmK7YlkUTvAEH0QoIA2FQs23KXYjuO4xa5SLIkq8vsRH29l9+3/vvcB0KyLUfkzGCtg/vKfe/du/f+73b22UcA+GlD2biLLXcQvffvXNOAxJLNtCrQlEYT482tMq2z4T14BJZ2FISMq5tp+hMfK+4QMF7xlwzAc18i8+URLs7+Oc93/ibnD9yB/0CTaX8+tgP+7kb4nze4499tJfP3BaQ+VkHi7hpi+2sJfqyUwN2FBO8uIbS/mMiBcqItZUQPVhBrLScukLRVEGuptOc65t6PHyyEljeTPfgm4i03E2wpZf1gLWsHGlm/R9a8nszBRuJ3KdOnJQT1vNT5qyyf+Esy/zIHF75pzTKcKlHZiwJ8zXOsQUxLE/TcZZfMs/KsiYDiwJIhkgkSS0eJe3OiTq8nHG3TF+HRY8RnPsgLd+3j/D2NRLtqibeVEd9fDa31cLDMUvLP3r2Lp0beR+KJU5A556JGscbhwf2gQKLrsdIUxSeql35t/l1nlWWZhMuZJxLmOMjUKS4x5q/8kMgX+swFibdUQlsJyXuKWLm7hrXWZvwHawgdrLQROVCJRnT/lRG7pwo3aoypYuyVUUXi7ioS98ikv2rodRubz68jcXcdybvcMCG5p+Y1LUT8YA0/bSy338nlEx+DJ78IMZXSLBGO+S17pOktBZqiw4YLYb6ry17JZ47napdeIfU//kRxh4oXFY/oT2BZWVkh9NSXiB95L/RWE7pnB/67dhBuKSPRXUeso45AazXLd5Wwur+SYGsdkY5dxDp2EWmrJXSgytzOtf1lFospPlNMpqPvYBm+gxV2zL2v5/6WcgKtVQTbKgm11xDqrGWltYLltjKbvF1rKcR/sIDAgZ2EDuwkcqCQ5b/dRuxAFfTshZ7biO/fbe5w4uBt+A69h8Sj04TOPALhZ7117EpbuwIAzY3YxKJueqOCO7cAK2OrK6XJ1YQhHlGdX2xjnkeTj6aok0skHr2XlZkPstZ1p5tMPFhF9GA1mdZy+Nib4WAeq+31fL/jLTx2/G8Jq/5PYLVCtE0+3gZABA7FKWGviu3HeZZ75Tp/yN1QOu1KTsRCmbt1FeXqiUozH/88q0f+C6udd5Bsryd9sIrwXXVu7uNgDb7WSnwtVfhaagwwAk3wYJUxUYCJSfhfIfB1JO5qMGF/NUB07mZQRQWAe2Sp6ojsbyB6T8OmY50BUlozdLDcgdPOd6DRb4dbq4m0ViNwJw6WE28pJ9xaZ77rM92/R+Kxh12aUKXqcR/B0DqBVNqyesvqGu/R44olcbZapDFxlzR4SsjccM+i67H9STCSKbLWmCFmWRbOP84LDx/l8dEPsL5/O9x1HRz4t2Rb30yybQfR9lLCHbUEOxpZ72hmtXMPa+1NJgTrrVWst5ThaynCBLqjkvWOatbaq/C1ubHeVk5uBDqr0PB3VNr7662VaKy1CBiVnG2t5XxHLcudVQS7y4h17iTevo1YyxYi+7eSaCsmcHc+vr8vspQ8B13GjL8vx/+3pTx5cB/Pz3+I0LcnYPnrNuchDS3ayL5KX28EyoYT5ZVkc1RZmySuiT4VXmqZg601d+ltNbSOJNLus5EL8J1jrE7+By7cs4fQQSmJeoKysAe2kr3rBuhvYqnnTr7R8hYufL7TpY7Da+4idCGObRvunmZpsqb+XmXVc3zzjtcJDLoZVw9qmXd3aznG68sTARKPf5zHR97PSx23EOtugP0lcFcByZYqp9F0we27CHgj2F5PpK3GzHuypYy0xsEKktLoLbtsDiXS2kS8tda5AXIFNkYN8dYfH5pA0vkbx7Yqou3FRDoKCXYWE2qvInGwieSBZvt8qKOCpdZSIr01JNuLyLTuINmxgzP3lPPs4T8h/O0vuDb7tt5bvrKIdWXWWs82GGwEExLcMACozGI15NJQXgmIKKg158FU0vbCSMdyRVspiKzC9+7n8tQfcv5gFYGOmwn2bCXYcxOhru1EOgWOYosFRKf0gVrSB+pJHqwl0eJoGekoJtSZT7B7B76efNa7K1jvqmG9qwrfxqgg0PmTxuZzquwzq91VrHZX4OsuJdhVSLRjB4n2PJLteaTbdpBsyzeQyE1ztN9FtKXZSkKiLU1mXaQYz/XcwYXjf0zyiaOQesqcVFkE0UmeZUpC5imSZEa9zlQR7pSznaS5l2zcQCWrLbmU6Pm1nkWPkkvw1KcIHvvPLB/cQ/hgLQw1EW8vhJ5yaKm1xESwpZhLfXtIffEeiDwJkRDZtRgRrb7wem35jLFayeb3MiSvQsWmp7ZgShdyBSBrriGARfwuKWGB1vJTXPiHQzw19E4utdVDWxns30HmYKkJtsy+QCGA+Dp2EeioNYGNtpcZgdMtpQgoidYqoq31hFqbCbU1GbiiEvSrGe1lRDrzCXXtINBVTLCjinjLKwHi76/h/P6bCR7YQranEH9bHi9338rlz47DyiWX1dhEkNf1UAwPu10qxcdg0jWyE4OV4wqq4Zssh+q3tCXyN+9nfeqP8Xc2Q+cW6L/BgLHeU4yvu5hgZymR9jKibRUOJC1VZq1NsYh2baXEPYUQ6nRKQdbB11lLoKPGhmggxaDvsdFRahZJVkm8yA29F+oo2wBSsLOMiM7tKCTRnm/AEDiSbYXud9sqTOFJCfram1lv32v8o10ZpUJz5852N/PS7Hu4/PB+ki9/BmIvuSJFT6/YOvtE1lZPJtTAIhs0bFyxzq4qV+DQkECvqdOKiCsARV6C7x8jevQPWWm5Bd+BagLt5QQPFpFRVq+1Cva/mfWPXk94+l3wvWMQugShhLUz1QLnFa30FGpl1mJa3++h9qcwfsOC2Ps2kSJz57Wdt2rVlNXykF6Di9/g/MJf8lLb7SQ6a6GlwPLUsg7S/rIYwXYxS2C5ApB4WymJVoHDnScLIOsRad1FtK3m6sBh1qPMNJ40b7CjglC7rEu95celcQW61FA9F+/eynrrVoLdJbzcUs3K/B/Dy/9sltHSfj+FOP+ql0XfpDCgYj0tNHMzuaYBVfekVObqM2T+aZqzh3+f8wf3EO+phwFljPJItlQ469DqrlfCHegsM42+3l1qR1+XE2RZSCmieIvucZdZy2irrPEuu29peN23rLpAJeXFwWJQMH5AI3/T2GHvyVLLXdH3ihfio7JZOX4Zz9pUSLiZv/WeEqwnoc8drLCM5lJrOc8dqOCp7lu5cOrPiH57DvzPeVbatTbS3jnmlJAgquSQVUCahnbk1ky7uWAu/ltVWbspa7li6mTztLlbvpk/4kd3NxHpamTlYzutRCjTWQWtO4jdvZPVrn28NPZBOPeoldEIDz6to1e1SQ4gWuJqrsBP5/R1uhxZHPsTsy01JofNXWhErT9jEYfg+EUyXz/GhfEPsNzZRORgMdnWEmgpIdVWRqK9nGhHtfnPCgDDHdVEOyqJdZSTaK90o63aiBpra8BGey2x9uqrGx3l5jPHOguIttdZABdrq7PvT7bWWnYj2V1JrLcUf28BL7SW8MLgu+BbRyH2sosHbG4jR4DXd8zRWRv4JBPSd45msWQIdX20tjzrPyTw5RFeGHgnZ/dXE+2uhqF6/N3VXPhoIamWBrIHGu1owtZRTaizEn93OWu9Zaz1lrPWU4m/q5ZgZwOh9mairbegIDlxcB+Jlt0kWptJtjSSbGkg1VJHVu6H5joOVMKBcpsz4ECJc4v3F4GNAns9c7Bh4zs2f0/C6FhHzPhT6/FVvNX1uRHsrMXfXkegrY5Ie4XxOXCwiMsHyjjXfRsvj70P/5cOk9I2bEnFGBmLm0MpBeqebHoAkQCbrFrHlpAp+JxLJKoaLa29rEpTnod/WWB56kOsdr2V1YNVrHeWEuoqIbq/kExbPdGefTyx/y2saf1I+Ix9uRZ+ZjX772UlfxY49LPXuWpHl4qzqzKnW0hxacxQJkI8mySrzmJqjLz8FMmHB3l54Je4IC0lgBwsgBb5+CUeSCoJd3pDgOmsNALHBBIDiKuWzT2+FoAkOneS6Cgi1tpMrHU3UWNoJQJIpqXatEl2oJKLPSU83Xcrvi8M2T2QuAgpr0jz9eFi42wx1NyBTMra0rhIUAyIeKnOF7n8xT7OzPwel9oriXfsINtdQLgtn4utNSx37SHc3kiitYGcQG4+CuzR9gbCNhoJdjTj79iNr/MWfB37CLbfYvctcCRa3RBIHFAcWDIH67DRUmvAEXjcqCZ7sI7sgWYyB1T7tM+GyjcSLfre3UTbmu367Pc7aj2elhPtLCPaWUKoqxxfbyPB3iYHkLt3krpru1ksxSyXWhv5Yfcvc+nBj8JLD7vFd7h17FpLY4pZRPQeO4B4JfGeJZa7agAhSSq86rqvyN3yPQ/fu48LYx/kcvcdrPcXEuzdYUWvvv3NZHpvY7XvLTx39I9IvPAZNx8jFNr+h2tuojYHyg2O/viD61wkL6Z6pkRXrce6IOKEslpxBiGVsvojbrHQi1/iwvE/4+Xe20mq4rc1H1oLoa2YdHspSdPsFUS6qgh31diIdNYQ66wh3lFFsqOCdJsb+ny8Q69fxeisINlZaL+Xat1NsnUPkc46Yp1VpNrqoKXGViKGW4t5oaeWix//b7CkAsSwt1xWMx6yllf3J3qHbLbdBfZJdSuRo61KhMuPE/nnKX44/C6WDu0h1qfrvJHowZsIthbh67mF4ODb8HfvJty5y1K48fZ6Um31ZFtUHqIcvzumW3eRbNM5TQS6drPevZvVnj2s9zQR76izCcF0Ww2p9hq772R7nWUb9X3x9l02Yu1NvHok25rg4G44sAe07ufgXlIttxJvvZVI+62EO/YS7thDuLOJcFed8TPWVU68q5h4Vz6R7mJLgvh76o23sbsLSH30ZtifDy3FxPYXs9JWw/Pdt/PywodJPn7CGuhp8ZTcHO2zmrMcOtqfqollRWwSz4FDHR8jiaRrqCehlnyqgjd+iew3Frk4+X6ebdnGxfYtpjwCrXeQ6GgmPngrz/btZfWLH4Nz33OVy+qpFl8hop3Jchm23G//hON1Lpz0lkjqKjWsVMXlq0PeSjMtLU5Z0VAYwi8T+5djnJn9AKHOJmgthjYBpJBsezGpjmLineVEuioIddcQ6qqzISJLeAUgAcmBqcJe0+uvd8QNIKWk2itwQtREpLPeQCIhsaCtQynREi7M/hbZpxe9+EqqX9ZDSdxrAYgaFsQ2Mi7GOJWOX36O5FcmuDj2XlZ7dxEfLCbRl0eo4yYC7fnE+htI9N9GsGsfa917We/eY3TUHEe6VcBW4FvhuUflcLAcWitMGYmGEkh9r7+nhnRHPrRth/Y8aN9JuqNwE/2dggp0y6XbZUOg0ljrabLfNDAeEBh3kVWCo203sfY9BoxQp65rt513BSClxLsKSXXuJNmVz/KBbfjaipECTHU0uMLJllrMpTuQB4MV+A7czPP7izk/9154TIHzC+ojxLpfcyE5C5GTfEmpBND8IZsLUTtWvysYNqsTVY1XDlnhs6S+Ps6PRu/kTEcJgf47ifW9zVnezkp8PWVcPHwnwS90w+XHbFWj1qRoN6t/JUAkIF6K0wq6nN3R78tPVMQvXzDnM2ZDPrde/fJ3OHf/3Sz33EmqvYp0e7mBQwBJdxSTVEamq9wAEuiuQ0wSUGRVBJBsuwOTgPR6gbH5fFkk+31p0LY608ahrl2mWdNtVXCokXDvHmKf/xisP+Z8YNMUihY1HbgRgf0E/fHaL4lGIrI/rZy+Z3mjQVJfe4DlsT9iuaWRbG859OWRHMonNlxOeKCBgK6vvYlE5257LOENdeWArRKRGgeSlgpXaqJyk7ZSUh2lxEXX7lJCPToWQsdWaL8B2m+0x9mOPBNeaXk7r7uCQE+VgUmA2jzCXVVk25QidQAUvaRYBFRZDSm/QJfGrldYkGRnManOfJJdO8kOlRnoV/aXEm5vJttzJ3TeCm210FHkZeu2kurbwaWeal6eei/+r4zD0nPWTUV0Ew0tHthoLqHn8mpUzRG1OrbcBIR6GKtNlarP7XNKKCWeg0eHeHn4VzjX2kS4u5FYdx3J7nIYKuXiR29ibeJd8Ox9toZGa22UZRQ4za17DTZfl7swd3ruY1dWk+kiNPRlTpSEbK+kIPoMkfkP4ZPpb62GgXrSncpW7STdXUqsq5RQdxUCiLSejuHuCmNytiMfjVhHGeHO8qsaSgCkuhqtvit2oIB0Z4XNxay1NhLurCfZowRAJckj74FnPmlBuXzai+pkbskI3ZX5k69Bop/+lughJ031SM56aFL1q5wb/nNSg78BPU3QkU+m62bCfSWs99ey3ttMuKuZTFsDaNXigTxC7TuMVom+GpJ9TcS7mwm2NrC+v8YeJ7oaSHdVkeosJNN+M5n2G8h0/Dy0/zy03QBtN5Jpu4lMxzZSHZrr2WlaPiZXqLuEaGcR4bYdBFu2ET6wlcjBrTYRmGrdBl159p2a95C7muqrRNcR7Kpktb3ceGZ866rZcLGk/OQl6PxYdz7hnmIDeKBzL+H2O4m13UpaZSDyKto10/3/km7/OeL9hVzuv4VzY79H5stjth+I5E9S5/jgLIr60qXkQtkut5I397oBwnNyVAakoaJEsqrdet7iy5WhO4n3lZEarLbro7MADlWS6Skhcuo/WlcU/d6lgN+aWPxsgEg+7Cx9TDiVCLl8tK039laKCekK6LM57Cn1pqzCPw4RmX4vSwoauxtJ99aQ6Sol011MqrfMABHoqWG9VyCpI9RdgRgn10Aj1lFyVeAwUHVUk+7Za5mWRPsO0t3FRLt3E+y5lWDfLgK9Daz17IaH/hYuPm7VnBJoFUSL2BllM67hT59e9poMWhXrxSfJPjRIeOB3Sbfshu46aC8i0V1CoK+a9b4GfL3NRDsbnYZtKyPdmUei52biPQWEZRm6a1jvrGe5vZHLrY3Ehn+RcP8tbib8wA4C+28k1no9dL8RBncQ6akk0NNowbK/bzf+3lvw9d1CoG8vgf49BHsaCPfUkuiuId1dTqazyEBLWx60bSF04I1Eu24i2b+D1EAB0d4CAp078XUU4tOkZLfc5Arjo1zmWKcUXLl5AbJmod5iAr0CUj0BuWQdil/2uoqL9lLo2k6m5Q2k2n+BdO92/B2lXGrfRWL29+Gro1bek0jEyCTlp7j2RLYNQyJFRk0Kvepbiagstv501NmSVFecouW/wIUfwmf/gtWeUtZbtsOhCtBE4oGtZFpuIDhxJ0vfOkI4eMHm8TW/8rMBol8zJSqAyCf3AiRVYOY60lg1pkCTm573Yhah/OI34B86OT/8W5xr20usrxH6q8n2FMFgGdGeMoK9lfj6am3ocbSnhHRXgQ1ZGRH+qob83r59pHoarYgy3p1Hoq+ZyNAd+AaaOdfTxNLEb9rkkm1Kk4b1jNv5QgBJZLwNQD3Cv96DeLLkbZlH/DzZR4aJDP0WdN9maxfoqUPaP6R4oW+XgTba00CyS8CpIdtZSaq/iPhgAdGBIhM2X5c3M97TZMK+2r3bQO6XsA80ERxsIDBYjb+vlIt9jVw++iHOHP0fNs4e+2vOzf01F4/9FctH/4K1o39CYOYPCYz9Dv6+X8anyb2DSgTUgaohhhoI9exgvXc7Po2ePAI9eYR68wn3FRDtKzZeiYcacVn/rkobic5qIt3VxtP1vnoCvfVEuutJdNaT6qgl1VlNQuf2VeDvyDfQxfpLCHcVsX73zcRbS4iOvxOe/gSsv+S2V1PK3eaO0taFUzsebHg43ky7BFp013DuWYqQukSav5uBHz3I+vHfZFUKoDMP5NJ/JI9Y+82sDNTy4vT7SDz9oMm5Xw2wfwbTr7MzDEa6misWxC5MwNmwMLn3BZKUazOpb9e65pcfZuXev+OZjrey0tVEqq+ajPzjoRLiPUWEe8vw9TliCiCRnjJS3QU24t1lRLsrr2pEumuJ9ewhOdBMrCePcOcW4v01RIf3cXloN88PvoXApz8CF9R0IYlaNkW9mEoaKPKvXzfzE8mo2zf3QAHlS//A2ux/InigzhV03pVHtqeGUE+TaXRpdwEl0V1FuqvSwKGj6p/8A+VEhmoID1YT7K8k0FdBeLCO8OEm/MO3sHJoHxcHbuPs0Nu5OPluAif/mNRn/ob0l/tg+XFYfdEbL8CqxnOw8jQsfx9e/BI8fi98aZDU6f9JaPwD+Pp/g/WOt7PWuY+zHRWc7ytldagS36EKAkNlhAdLLLGQGiol0V3gjRLEK4HE8auacHc9a32NrPU3EOytJdpdQaqrhHRnCQkpvZ5KQkNNLHXXsNRZRWigllRfubl0tLyJTF8Nl+Y/TPrpT0HqsqvgCF22tqZG282pYC3BSIdMLC3es5WCScLErIe1lbLY9N2L8MMp0vO/xtpHt0KPJlQriQ/UstZfy/nOBlKf/4htnaFCSc86/ET+6kUvBtFD11XDlZyYSXHoNYBonkSi4LLSKhE25Jnd0z5350k9usjzY3/AGWVAuivIdBdAXz7JXmmiUoL9VajsQ8dIXzmJ3kKSPYXEesuJyqpczeipMdMeHdxFsDuP9Y43E+0vwD9UxdnhvTw/+3vw9AMQPKPmUWSEDrOGyj5lbYbW7uOnkudnveFlW8IvEvxcK0tDbzd3KttyI3Tnk+gpJ9DfjG/AuTvR3l0ke6vMH870FhHvreJSSx3LvXsJDu4lNCRNXMx69834+rfhGypgbayWlZk7WT/1BwQ/9zGS356H5/4Zln8EIc0uez6HbmTzkIq1Xsra3FPNHc65FPczD8PXjhH+ZA/rp/6Wx9ru4OXBO1mbejuh6bcQOiw3rdw0vcAhPmZ6dprCS/YUb/BL9W3BvgazjP7+BuOfeJru2Umydyex3mLjdXBkn9VGXehsZqWnkWg4+/l8AAAgAElEQVR/FdnefOi5AQYK+VF7E2v3/xU892mIvuB6Msd91g4sF/ua/pYFSav61lkPFxXHrdG3XLJkWP2lBR25Pefg0UGCw2/D39ZoMd/64K2s9zeR6CojPfsr8MRJW1hl2bLXYPN1OQTphzcPez2XSVCmwIYKykT5K2ZOKTerk1n6Lv7PHOTy8C+ZH20A6dlOujfP5gCkGX0DNfgHqgj1a3a7mERvsZngWF8VVzOiskrdtUSG6vF1F+Lr2kp0cAvLvTfzo7HbWfrsRyHwDKgSQK37NVQ5l3VrloNZr1r0NQj0mm8py6LdWZ/7JC9O/h5Lw7eSHa0g1v4GGMoj1ZdPuL/WQKKYINTXbPeZ7Csk1b/d/P611hJLYEQE8v4qVjuLudRZyNJABcvje0k++B/gKx+BZ4+D//uuMZs1lfO692hNkDwMrU60NqNXeCO8RCPy5dWxRn661v6sQfSitwfhN4h8vp31U/+VsyPv5kzf21jpv5XwQJNZg2iLXJSd0J1Htnsn6Z4C45sUnK412F9DpLeOWE+V8TLRt5NY/3aiA3kEB4rxidejt7M2eDuXuvey1NnEuiaQ5V733ES2P8+U6bnOvayc+jN4+XOg5hCJgDU9F0A0TOIsw5rT+HpFHo1iFK2CxeKVVDrrMlsCidrePjrKub63s9631yo/ZMEZqiMy2Ezsof8Boe+49SuvwWRvHkT9ZF13buvMbh/QBag8YNXrqKElkl4DM9PC7hJXVEem89We9NkHSN37QWKDzdBbAN0qENxOoreA4EC5EUxEE1hkVQSSWF/FVYFDgBJAZJUiI40OeAMFxIffyMXuX+D8kXfAD+bNLEuRpiVU2nBFBYQJVUzJiniW8DUI9JpvqT5t7Z9JfPYj/HDoHVwYv43wdA3BwZvIDLwJDm0l3V9gbl9gYB/rg/vwDzUQGSoiPaQg+9+Q7f6/oP/nYXArkd4iVnsaWBv5VaKn/pLUI0Nw6VFYeR4CWqUXcQrSEw8THGUU1fFEbYDMRVYFhGuCLQ6aK6ljNkMsk7BCwbSWxKpTSuwiBB+3lXvh+z/CxdH3szr4a0SGfpFkT70VKtK5Ezq3G0hkSTThGeovxT9QaYou21WMMkWyHAKGf2gn64cKWD0kt62KwKFmwkP7iA7eRrB3N6tdtaz0VLA2WEZwsNDiVK0/We65lewX7rGl3lK4ygpq2wjZhNwwS2LzI86TMWWtxtsJFc+rQthlu9RoxXVb+RHhz/xPwlNvs0VW9NWTGHkLl/puJTX7a/C9Qbdy9jWY/GMA2VjgYggV0QWQNWclcl3APTdFDFjSmgkz7apYfQ6+0odv8teJDtaS7M0j03ezaVIBISyNMqhjGbF+N+KyJgOVXM0xMlhNeLiO2FgjoUNVxEeKyYy9mbNdN/Hi8T+CpW9btaYW7jjbHCezvmSbZ+bW4hvRN/Vr3WxF7b1cHOatRReznGCKMVqWPI9v+le5MHQna6O3EhirIDqyg0D3z8Ooywzp/oKDjQQGmwgYQIpJHfoFGLoO+q9zQBnaYe9dGn03a/ffBd/9NFx+CdS+VJtYumpw85py+UYrJldvrOQFSC07PuGaiGpBqbSvRElDQMlp5Ki2184kSce1BuYyRF6Ey9+Fby5wee5veLHrnSy330aqvxm6S6Bnh41M3w5iA4UWo4QGHf/oLoLuQpL9+YSH8vENF7J6uIjVw2X4hlx5vWJEhu8ge2gfkcEmUxKrY3VGKwZ2wGCxxSO+sV8n/vVJp2yzKfwh3cUVi3gFIKKAZ02sY13MmtWFBRPNk0QduKx+68JDxD7xYWJDt8LoHQRGf8lcPsYa4BMfgOQLr/BMc/x3nlWK69zPu5jDXUAOTnpNFyEYeBOJVz7t+YLq46Qafq+Vik5dfp7ww/2cHXsHofE6ksMFMFwMh+rJ9lcbIeP9+SQGK0gMVJE4VEnsUOVVHquJDCgoryYyWkh2ugRmKjnbu5tL37qXpLZgyAm4lTXrfpRk8NYh6Fb1unZa8jSVYd1r2qbHJlXm2kZtn75lEq77i0qlg0+yNPMrpMbrjPkM7CEzWGpZqdBgCb7BcvyHqu0Y6S+0ib1wa4mluePDNxDr+39gVtm+Yla6dnFp6vdJf/soqD9yKkTCr7okL7ZQutMrstNLEnaR2/iXm3U2fgm+Wrh65aO5r9h8NF4bcVyhpTbPsS0rLr1A5GunWZn7c1b63krmUJNNtikFnBgoIDZURHyohPShMjhcTXKwjsRgnfEgNFJKcLTERvhwqfE0018HfQ3QI6+ikdSAOzc4Uk5wtIjo0M0k+7ZDbyGx/jpWFn8bnj1mnktOHjPaPiOrqUFHDyW7tMAvpcV8Of6+KkRw9xeG2LPw0oNcuv8veHbg7Vwc3kd4uBr63kx48hYuP3GvWZ71RIalQNqslegkmU/FVgSQq/9TQB+3jSmTLqsl+QtFyTz1CEsP/gXnx24lMFxKWqa0Twvsy8n2FZAa2ElS5d6DHkCGy22WWTPNr2sckqtWTWSwnPj4DtKTO2Gshosjv8nFpx4l4CmZjXy1uR6qLXOiZcLn5dklVnpVR7lfAr1ZCiX2JI3am5tLXLJmz0JT2LJ3genbYLQYBhpNAOgrJSH/e6iapUN1rIzsYn2onFh/Hpkel3ZUGjw+mkf40E0wVE5q8DbiJz4M35kDdT5Mhm22WNfvmOUlAxTzKC70wKzrdYJwdTzUd+s7AllYkfepG9YXqhXt9+8n+sm/4/LAW0iN7iNzuIZY906ivfkWZ6WGS1lu3070UB3hQw2EDlcTGiknNFJCeKSE2HAJqcFyS/nTWwc9DeiYGagmcajczgmNFhAbzSc5tMMSOqn+Utan9xH+yt/C0jddBa8tB9e+NRc9d9/F4bpMgcSuVyDRCxvE0Au6mSiZ6Hnr65V85jTPzP8hL/TfYpk6+m9k7VAVz365i0T2slUeBsIZ2yrFyuGzKbJJ37UCRH58VN2RHCNFcU3uBF+C70xzfvY9LA3X45f57Soi2VNKpr/EtGxSbtZguRHrdYFiM4g8gMgnjo/l20gdqiJ0/EPEL71o/aZMw9iEjoRIvvmrAKL3tDegJyy6BblfapBpANF0rZUFrZJkBbc7t9ImPlLfmMU3uQ9Gi2BAmrIe+svRvfkP1bA8Usf6WL2lT02w+opgaBccbiA6VoJvpIz1Q7eROPmf4bE5iD1j20/okgJagOix2dSkFfFpnY4uxpvI3SwTV4MRTQLr67z14i6DKfdFTRdegDMPE/9cK6Hp9xHpaoYele5UkBwsZKW/gKWhYqLDlabUoodL0ZDl0BBPk0OVBohsfy301ZoHkRrMnV9CdKSAzHgR6ZECkoMlluZeGmnkR3O/SeCbYxBTwzq/xZGZ5IoJbA4I4pOWnOeebxw9OrhmDHGS2hE5ex7ijxH6p27OzvwmlwcaifQVsDJUxeOL7ye7/AVXaRyJWB4jJYUopyiTuVaAgPabCKXFMKFWKk8r6Fbh4jeJfKGFy7O/wuWhSlY6dxLuKSQ9VGNDLlZ8qIzkcAXxw1c5hquI9FZZajQxXkBoZIelSnnkHtsJS6tdnYvi9Y81i/cqgJjr5dYnyJNyNNdzJ4TZHECiasK8ip+EbdiiJg+XH/gYvom9ZEeKwbRlFQxUkRysxne4hpXRWoLTjYQOK41dQLa3FA7vIjVcz9qhCi6O30Lw/j+F7y+4HrWpVeu4KBHVzyp2MJAat+ROKJvo/G9dp4RkQ2leLUD0dfZF+iX9oiaLFXsG3A6za98j85VDBMd/l8TQbWQPNRDpL7YYI3K03uK+9HA+qeFikgLGSBkx8XO4iuShGlLG7yrSQxoVHr/L7DzFjAIH46UWQ64N1bI03MgLg7dx4fR/gR/e56p/CZNKh60DpQXmuHUlWrPuGCYllxvuJUcb9R9Tlx7F0IqzHib7T21cnvkNLvXWszLSzGMje0l8tx2C33W7pwVd11VVIgmA1+hiOQaqeEyz7M5HVDcJBZbL8NKX8D30V1yafSsX+vIJDOSTGd5FZqjBxSCHSkkOlxE/fJXDA4jqnGITBQRGCvGP3Q6PTdtKPtMwopRUssBiluHVAHGvb86USPu4lpVeYki3lnAdyjUxZfe59G1emv0g/pE9pA8JIIUwUAoDNSQ1nzFax/p4DdHZBmLjtbZoS6U3HK61DNDZwTrOzv82PPMA+J51lkPdTuKwnAGVUQokuq5XWJBNbta1AiQHsmgsQcKv5MXKxv7rcl8StlOvD0JPw2NHuXzs/ZzpaSR4uIHUzC0kJ6tJH94OwzeRHd5pdDCFN1xDXMmT4ToDilOApcQPbx5lBqjE4E7S45WsjdZxabiB9dE9LA81szKhXmV/CuvfMIumWbqgJnvNgiYIxZIEtPmoaTSl7jUEkisAEX2Up0yoF0D8AiSfg0ufI/bFuzk3/m5e7N/NC4criXzyt+Hl+yB0zpltTR0pJLOJQmPA1f0zAstMW38usVN7QwRA2wpr5ZbM2+MnWP/EBzk/Usn6cB6ZkV2khxotQBcxEyPl1zAqbeIpKndtogDfZDnB+d+Cs582S2baN+eOGu2037cAolvPaU73MAcQ90xkFUu89I+2G7ZOWZeJmZZdgR/cy5nx38F/uJnkIQXaO2CokKyC1uFGgnKtJqoJTVSRnKwl0VdtFQbpkRqWBqo4N/F2/A/fDckX0W5VyZTbi1zrps8m4Ly3gaqzICLw/3oLovtTuiIUD5MIr0My6LZ1SyZtbkEC5hcvZU1SzxF+bJYfHf+PnBt5C6HRvTBZC4e3wMj1cPhmGC4iPVxpFjIx3EB0pJ7oaDWRsTIi40VEx4qIjxWRGCkznqcOlxMfLCIxVsHSeB3nDzcQHN1Damw38ZFaLkrZPTEBseeNF/6E5ntjqOmDwBHJlUIYODyQbEpQiHaK2BJqdapFbNotLfgkvPhpgp89wA8G38HFsRpWj94GT6gJ9osbKT9tuKZK9mu2IMKBJqiypu/E3iiJeNQaNlou2vc80X/q5vyRJtbH8yzjkz7UQHywhuRIHYmRSuKj5Vc19FnNzCoTFh3PJ3Cknuin/gR834JUzK7LLIdTJUbkDYAYup2PoocCiAmjnlga2+u6pzcCApTmGi7YnkwkzhD+UgerU79O4NAuEkPFZIa3wKE80oPSms0EJxrwT1WxcqiA5Fg1GZVZDNSRGG/g0kgTq/d9EF76lKVmtVgzqOF13VjKuhovPdflGJsNIF6ud1PnFfe+g/Xr/S9L6U+qC7oSxk77EtdKJm9vMz1MaxdbpTUElDMknrufyx//c/xj/x6mmmBkC4y+EQ5vM4BkDlUj/uYAEh6rJDhRQnCygOBkvgPJaAmpw5WkDlfbMThcweXxKi6N1jgXeawRFKMNlrL2iT+Giw/bfiYCSMTbFTkmoklvmdVQsC4o5LIyjpfGOq0jyRFJezqGzkLoOXj+YZYf+ihnJ27n/NSd8MQshF6EkLrVO6Wv/Mw1AySkCgDjjITIbylUlZL7c/6BOpp/7xTnjt/B6tQ2UhPSMLVunmS0kfg1AiQ2ICJXG0D8c3uIPHIXxJ81Kyba/WsAousXMe0+vM+oTseCVs1S+5VilHU8R1pBY+QF1j/xF0SPvIPAUJ2lPpPDbyZ1eItpz9jIbkKTuwhMV3OpZ5tpS1kWWc7k9G4uz7yV4MMHIKGgXLu0OsuuBgXy/kU6m7fIXVCuosEL0MVvfUYjx/vXCw6dL1Bo+zaXtXOFBrZE3wiSJOpXax53LYpMNB2npt688HFin/pzVoabLDGSHruJzIjc5zIyh2o3AaSW4EQ5vqkifNP5BKbyCU8UEM8BZLiWzESzxWMrY2WsjpVZZTCHqmC6kMxoAWfHb4UfztoqwFA8ixbwqVWpFzo6gOi6cgDxKj1yPF2JqHWQRyvpAK1n0vp47Wf/wuf5wcRv89z078Czn4DIefArRPBCh/8VABEBjY8miRIqEdxlRmVZzJu5+AOWHnwna7PbiI8VkB1zmiI62kRsrIbYePlVjcRoFYw2GUAyR8pZOnorPLvgUoK2/NW7OF2gN/t/xYJ4cYn3+gZAdK4pU1ebZmWllni/DFllRCKw8n3WTn+A6HgzsdFdJEcryIxvsZEYrSEy1oR/0lkQuRdyKZK9FWRHmgjP7GP9vt+HMw9BTFsKXJkMywm96OcEXxci5lsazfnZnqXLzYM42l8NPLzPbNDFeRf6Xl2Hl7qzZuY5QKrmyWbr0y+Q/eExzp1+PxfEg+N1ZKdrLHhnpJHMcAMRrSuZqCM0WY5/upj12QJ8MwWEpgqJjZeSHqkwDyIyupvg+C5CU8XEJgqRC8pwBRzeCqNbCY5Xc2bud2H9Sbt/TYMabHVRqo4wLSiKeRbEAOLmgXQfup/cJKnOMsKqIkTLrtWX4IXPwsuftyXSBC+5LKzR2GUyr9mC6EeNSTltbZNsTgvq4izRvvQjVj71btaObUXZJgEkeGgXIk70WgAyVgEjDUZUAWR54S2e2xIgq15KuYvTtW0IgtwFuSqvBIi0qLkZ3mdkPdTcOKNcu24ivQTZFcgmrEo2ePp3iY9XkhitMx86PbGF5MQWYmMVhMZ34RNAJmtsXiAzVkFmsJzsaCOBI3cQ+NyfweVvubZDpvlEqNyfLjYXdG4Gh3MfROsc40XfawGIZEyf1y1vFiRl8DSZakLnJThU7xTXHmuWRVsmtfYtVr8zzMr9v41vdg/B8SZSU3tgtJn0oVo313GoiNBkqQeQQtZnigkKCALIaDnJkRpCY7cYQCQX6fE8A05mRHzdbgBJjxWyMv1Wkt9dtNWAiiC1qYEtqLK9F0Q3j2YbINHzV96XQKI72pBV3ZdcrrWXwH8G1IVRnek9vidto4fAtbpYLh0qAhuVxUOvRFkmWV6rcXN9hfXPvIfgwjbSE8UwXk9guN6IGpuoJj5RcVUjOV5pAMmM1pIWQE7/GsmLX7OLyajn0WaAiB4mCDmAvLKuTEG5neEdBBYtEEvZPuhx0iq3kfOTUYDwfSKn30VqopDkWC26jtTkzSSnthKbLCM0VYt/ahcBjaEimKgETZiONeA79g4y39TWYS9dabG0YSFUfKdgfNOw9xw4JNC6vBxANhhu4vD6/+m7xCMNPXb/5SpruCSFZNC0bjpDMqJ9Gl3NV1Z7eYQeI/Hdfl4+8uucGb2T5Pw7SE40kzpUQXa0DH/fNqJTJQRmSvDNluGbrSA0XWE0yoyVkRqrJDTRbO5oZmIHjG/DvS6LXEh2fAeM7SQy2cT5U/8NVtRVft21LY2onsxZCtHFgcRztSxod5edo9VmK2LnC0O54SlPR1vJtFqnrhPj8rUBxE2oOR92g3Oe3Akg8qWNm/41Ap97D+GF7WQnq2G8Gd9IHb6pOqKTlVcFDoFKgpk9XG8WKX2kEt8nf5ek7wemDV1libeQRoTwgKvSGGvRLSJ66lcHWQsTEB1EZ7OEWmvu2h9pP1jLM4m6y08Qu/dXyU7m2TXEx6tJTu4gPrWN6HQhgekKA0hoopFAfxHYPZeQGq9hfUFroxdd5xO7rlyGKpel2lw57SYFxUn9bE7bO0Y6cXbCYRLyuv9JeLwCDvt+A6atu5CFdb+nCnJHpjjp+JrbxXajFiFkmw1d/Mzf8dzku1mefgexid3IYjJWSPzQNuKTRYSnyvBPV9sITVUSmxAAikiNlxGdqCc6UUt2PB/GbyY1XkR8ooz4RIkpICYKyEzV8OKht8D3pyFzxs2Qp5MkE25qM4dho8iGS6pXHY2kSGQhddQ92/2IcJ5M5N7XOe48RVtrpFi6doDEbPGit6xOv+RZkZxmMuD4zhL6zDuJzefB2G4Yu4P18SrWj1QSmS4nPnV1IzVRZQBhvJaUtNMX/iOpxHmb6jKOW5m3R5GfBBBHQyPYhkshCnrpdVcjKosjpyxiwaxpnaUnSdz3yzC5xZIOiYkaElNFxGfyCB/JI3CkGP9Mk9X6hAcqYKoSJnaSmq5m7eR74dIjZj0sRjNGea7Uj1kOd4GbgaHHV0AhhF39Xw4gpsjEOE3yqu5J5bCebtEuUcpxpQmTZp1Map2stxGnlWQkLpF+/iFevPeveGb47QSndsOUXKRtMJVvHkNsqsomTAPTTYSn64hPVpKdKLKhpE1istImCxFoJouIyw3zZILpMpit57JKWj75XyDwLbd5qZKLXqcTiZ0DcS5m87J9KhfxQOKx1cTxCv3c5/SegJGznTG0DEJrT66x1EQWRGJj+5YKGDmYZlxgJLNmV7T6FIGH3k78iCaVfhFGf5n16Qp8CyWEZ0qvASCVZIbrYKLBABL/yp+g7rjatsCIEPfUn2dBHCFkQVSyobUhTric0Hno1sEDSMx2kEgQsSSn61huMeHK0yTueztMv5nURDnxyRoSk6XEZnYSnNuCf26nA8jEPhKH60ECMLGV7JEqC+7xPWrmXfS5wlhdjOcimJZxVkOv/jhzJQhe4G6IvTqQODdSFlKiIffOS9/oorziA4UdcjWdIxYkk9GcTRS1EHVLYiWlZ1n/+gTPTP8WgZk9MFsGozfC7E4k9FIgKgwMTu4jPNVIfLKK7EQBTOTZMauYZLzKKZupAmIzBUSmK4lN1pCcqoIj9eZl+KZ/EZ5ZsK6Y4q+WO0sRS+w8Vjq6mKLRO1dcRd2SznG8lkA4emfScVKag9K0ne5JsZadp+RJ+NosiH4i7NUt2VoRXamG139VP2SLlC79M74H9hGd2goDvwoj78Z/pBL/qXzCs8XXBBAFhEzuMoBkvv6X5hKpKMQAoopbj9l64bUB4gmJBxB9TABxu0gkCXo70Cq2Y/kZDyBvIjVZagCRFRRjg3M34p/bbgAJTtxOdnw3jJfD2BthoYr1+z4EgadsT8L17BXmOsY5Qde163lOs+X0ziuEwFuC6kovrg4gBrLkZbfc1eusLtdYbtcGeFXMqeBVrVWTMdsXPpnN2PqSUEaWRWCKwvkv4//8X+Of20tmpgCmboLJmwwgqnaOjN+K6BGe3G0AscLSyS0wsQ3GC0iMNxKbaDQaxmbzDCCRqTqbcE3N1MNMoZXs8MW/h7Xv2e9e2HStopX9SXFYSY7WyXi1axZPuSSMc8oEeDFaMx1K3/vNauo2teWH9iYRraUYrimLJeK4qlepm9QVjnp5Z110JrgK5z6P73QzkfGtMPjvYfRdBI9UET5ZRHS2hMR0xVUNaRdNFqand6G6oPQ3/952JpIFMYFTJZ4eSOF6LpbsnWnMTVksCaRbn+y5il54ogU4mqXQ5JQ2rzQmCCArT+N78L2EjpQRmakmOlNNcrqE5MwO4nM3EDl6M6HpZqITt8FMswlJcuwGEieauPTgn0LwaaKRDD51c93kG4spulwNPdbviY25c/SaZdqkgZQ8sGXQYrbe0U16msG0gycvGy/pwjedY0pUM2JaA67da3WPrqGF6KfH9jXWKTIO4bDtcaLYTtfn9nF3v2yZvfgZeHKeS/O/juIM5gvIjr4BpnaQnKogOtVEdHIviYm9JCbrSczuID0rEG2HiWKSE7uITzYRnykheiTfaBs8Us3KWBXRiWqYyLe6r8SJ34LlLxKN+FHxT27OSBRw9/cqgJgVcTQSONxw0xHO/njrnTIpuw31IVGJl+PDNRYrOoaI6B7hRXRx1cOKbVGWUlnGAmtzjXCsGCb3kZ64g9hMA7HZSpKzVab9FUO83pE8UmHfEZlrwH/irfDUIeuWKIFywuTRzNMIrqAy559urmLdJFtecJoTTgmC7iORWkcVpbZ4LPUCgX8Z4fuTv8ZLU00Ej1TAfBEcuxlmbyQ5sZ3YaAPp0SY4vMOC+fhiHWcW38aTn/rvEH8SUhHXpdSzwB7ZbNmAkVPVCd61KMMmbaYNZ3Rebuge3TZwcicEGC91vQkLDmy50hmvXkkf3PgSCZRgqHPcy3qmx/Zn37mJxxuAE82SxBKCk1Zpxmzb7PVHOjl/5JdJzVeTmLmR+PxNxOa3E58rJj1db/FndnIvoYVCQovbSR0phekqmKqxuZTkbA2RuQr8i4WsHy/EN1tCbKqSzFgJmdlaLszW4//a39iW1NpuIncbjre6MV19LprwvAJzEV1Bbe7WdZZS+y5oFoCuKI/NeuaaLIgxRBpG6BPh9E+/5S2V1LwnqQvwgzn8RwWQQjIzDTabnJzSsYbUNQAkfrSC8NFSfAsNrJ78JXhyzNYY54TCBEgaT4v/jLEyDXK7LE11BUSbCtxyBLxCeImJAljtuXfR7X+XfpHVJz/J149+mOen9xI6Wgzz2+HYFpjZ7vzqsToYb4DRfDJT+QQWannp1Nt47KE/Bf8/u7XQlkN1gqlr1hANbWwIonxht5+eSz++2qpIGwog7p7sS/RFHr/d/UiQ9D06Ry6Tlh97aJCMXPWfmO0t9xXvEwkyT36OCyc/RPBYI/GFbYSO30R48SaSx7aTnVFscgeM324AWDu5ndhcmQHDgvHpCpIz9YTnalg7kc/ayTz8R4tIzAggFaRmarg4V8rKlz4A4ccM2LonKQ9XO6fr+UlDVBCdHaB067KQOopUr/V3bQCRiJmZ1yo9XaT3i0Z/IVZFbpccQObqYD6P9Gwt8dldJGaqScyWkzxSdtUjfrTMABKY9wDy1Ajax0TXIZJoCByvBZDNbol47ATKASr3Hc790szrZZArkT5D4uzX+N6J/86FiWYS09vJLNxIdnEr6aNlpGeqbGUjM7Wg1YbTVQSPbmflvjqee+B9ZF7+uPWINV7mfkSCugFUWQyXTFBCQWlpCYGbzPQUkWcldK9OezpQXLlx933ufrQOxgmSA5IHEr2pm77qP31BiHD4svsa9d4JvET4iy2sCiAndxJazCO8kGcAYaYURm83gAQWClk/uZXYXCnpmQr0ngDkAFJr1mP9xA6CR4vJHK0iO15OarqSpWNFnP3UO0mc+bR5C8o+ilqiwZWkb26idTNxHUAcPa7oh591+9cOEAt0AsvFCHwAACAASURBVF4a0HNQDSDy9TU7uWTNE/xz1bC4hdTRSuJHaokdKSF2tIjUXBmpo+VXNRJz5Q4gC3WsnnobPHXYNSfecE2c16FGFFcsiLp7iICe9hCFPOHMvZYja+5oK9ekb5JrrtgtcxF8T/PiQ/fgn2qG6ZuIL9xA9MR2YvMVpI7Vw9EaOFoP07eQmakjOPMGIvflc+H0W4g92g8KjqXCcppckm4AcRZDOzA5cAgoEgBPlj1gGBA8cus67R5ymkFKVOd54NHnlbJWulpAM8DbZJpnZtypV/FfQpnAH1hxIFWAHPHBE/dy+fg+Qid3ElwsIbJQQlru50wJjN1mbnZkoYDAyW3E54tMqXCkBFVDJI7WETlWR+B4CYHjRUSPlsJRxSBlpKdKWDtWxEsnbmftu4fdQigVx+aUYY5GdvOeW5h77FVK5EiU+8z/ZoCIE8p7aFLFZ8Q3ThpAVFK2Cl4M4jtWCYs3GCBiR6uIzu0kOpdH4liJA4mA8jpHYq7MCBicr2P91C/C04OWI7/iu3vh0StcLKUynWCIWBuC5Qle7rM5cNhRfXWk7lMh0kG5WW59gf8bo6Rnb4GZm2wSdP3kTgKnikicqAbFXEf2wuxe0keqic38HKkTb8Z/ooLgwx+G4DNYxzNxSmT0LkYa0c055DSj6zbzyuvU5KJLY+r6DPy6fu8ynel00uLcCvUOUBCudkculnHrXTwUXQU0ch+JRuOEoxGi6q6iOjW1Vlp5nNVP/QbLxwsILFYSPVZO5uhOmCmCsVtgcg/RhZ2ET2whPr+T9FGBxAEl7gEkuFBOcLEMeQkGkKkyMlPFBOcKeWmunkuP/A3EvmcWLCfsuv0NgdeDVw97yVkS0cVInruRn3K8RgsizrrOJwnW3Eo7/arlkj2AJNetSZdvvhxOXI+EOjJXRfjYzYTnt5GcLyZ9rPyqRvJYuQeQWnynboOne627R07IjWCeT29CJMmR9XAGJCeTzq/yAGJafJMF0mSe+i0ZktIxsjGf279Cu+I+/0k4/jY4VkDweAHLp3fiv/dm4qdK4KiAcxvZI3tIzZaRnXsTyfl/R+z4Vvwf/yV45iFYWbkCDuOsxF0mxeXvjcE5wc8hVs+lqY3usjLuE3aJuuHceXbzkhH53SmbrwqT0tq8jbkrJSDsZ3+KcPxrXg4EEpYWjWT8ZLNhL610kdS3/orLp+vwHa8nNl8FitNmS2GiCaZ3kVjIJ3piK8mFPNLz+aTnC0nOl5I4Vkd0vp7IQhXRhQrzOCw+mSknO11kivXisUouffJ9cP5+U845gOjWc5jYeJB7IXf0LInTjD9bQfwvAEiALGvE8RkjctpL5lwzkWgfusfvZW2+0gASP1ZOeK6K0PzNhBa2kFhwhBFxXvc4Vk7sSCnh+Wr8p/bC0x1uUcyGL38l4HXC4Pnem+JZ08yirATqp4FEk2WpjCtcTGsWUdYkAr7vwIPvg5O7CJ0sY+X0DgL3XU/slGKtW0hO3E5qtpH4bDGczCMy8/+ROnG9CU30kTY4q/0qvASHSaMuwAuk9VDXJR2UG7lrtDe0TZlK9zyA6PP6jM7JBV5Zl/uXACkolc3JDfUEU4pep1/1nzqze1NNccFO/bb0Q9EAnJth+aFfZvXELgeQI+UwXQGTdTBTRXp+J4njW0kubietGGUhn8R8KbH5GgNIdL6GxLEqMrOVruTkaDnM5BM7utOs0tp9byf5WDdwecPF+tcCxBFKZ2uIaD/97xoBoh/QlHzAupuIEcZMS/OK8VrXHDKA+I5Vw/EbiM9VWpYiOJ9HaH7btQFEBD1SQuRYNcFTzfB0K6TPmxrZUBgeWFyFqjfP8WqAmEBtAoho5lkefY/ejicypHNd9bJpsmqynDxD8rN/Dff/EqHT1ayf2kbw3jcSO7mV+Gw9sfFbSM40EZ0qgvsLWZ/8v0mduhHfXBmB0x+A5z/t9loxRomWHjhela7dDN7cfclF0CdeARAxW7PhueGVWogvSn1LdnNDDpyjyWsLyE8XHUejXN9oS0OnI07m1Jwv+lVWHv5Dlk7tIrpQDrM1lso1kBwpJDOfR1JJjQUHElmU2EIpUVmO+ToDSvJYFdmjFdYBhvlSOLKTxNGdxE+UEzrZSOSrfw7ZM0YH0ws/yYJ4vNywKAYIj9b/+wGiX48Ty4RYT/qNWQbnhJo56JKV+QmR+fYCsZO7SR65gfBMuQVhMd3kwg4SC8XmZsnVev2j1Fyz1Ik6/MdryHzzv9uiJk3+iiAJW5TuzK6yOJbl8LSxCb64bzNfV5ILRj9PCnPCuPlohNbn9GJqDZa/QuJz/5W1kzUkPr6D0OIbCc/dQPZkDSzuIT27l+RcvblWodNvImiZnRpiR29nae79pH74WQhdtM4dmpHOxCOkUgnDhG4jlFaoriDbyZ6oamlgZay9+Sa954ot5ZopFrgyg6wO9loguBJO4Yu7NKeyYQnNxMuGaH/FTMZGNpu1phGvCYrNb+bcVytHcXM1Ya3I04XFniHx/S7OLNYRO14Es41WxY2s6dFtJI9uIXnsJtKLWwwoscWdRI4XE1msMJAkjtWQnquCuTKYK7KJR+YLyS6UkjleRvJEGZfu/RVY/66xIpFME405axzTfSZc4bW9uZmBUj5KUGyY5ddWENdoQUzCiGcS1oI+Z0HEn1AsSkp9YONr8Ogs8ePNJKevJzpTQXxxF4lTNQTnCzyAyM0SQF7vsZjssQoyJ2os+E1/408grd1rnQCr2lMEEjDcDPoVCyJBs4kiESznkohWr9I4r6Cthwu9Zn8qsfA/D49PEPjEW/EvbiN5agepE3nEFgvJnqgnfWS3ASR0Mg/fvVtZO1VOaLEGZitIHLmdcw/8BclnP2kd/qzDeWydYGgdXzyCL6vlrqou04y+A4mu29DjTa/ruQO/nCclTLyOJBbHZAhFde+OJFpfZDeogFrd1JVlzAgkVw8Q0ctau3qxTiBqUmA9gONPHuPsqSZiJ/JhugkmG+FoPtn5LaSOaW7kJjILW8yKRI/nEzpeTOh4KZHFcmQ9MnPlFt9xbAcs7iS7WAiLVbBYAcdvZv30bbD0Vbu7dCpBQp0WBPtEBtWpWkX3qxmoC/4/CRAZCi29EFnECAFTfRuCwSDx8GXX3PnRw8QXmkhMXE9itpTMyWbS9zYRPFpCbKHYAjbFIjKzr+coUDFfSWaxitDJEmJf/U9uua2shGbPdbTyAjkUShp4KterYVRcYieKkhqmXTwUGKmvIOLVdDaQ6PxYABUfJr/631iaqyB5qhTuKyZ8bCeZE5WmBcXs4IlSVk+Vs3KqjpAYfGQrHMnn/HQTa5/9Y/jBGCz/o9sLnCTBDJyNWR5QuUDWSVviN6kYSF0y5CuZPCgF7FkOA0cOIK57pLXv9DS9aVNtkJk8A2vfIqG9XdIqQLxKgIg80jkxZ3k00+JPu6JOKZ3Ui1/k4ifuIHpyB8zsghlNFheY1UgJJPNbPIBsJ7pYSPBEsQ1ZEiVgsnPFsLATjm8nfSKP1PFi0ov1MC93fQvhU03wo4ecxUyGScmdV0ugZBrNwUrvbeZbjqWeuvCsiGmNK2+96tE1WxBrTOilUS2TIqaF427f8PQyxB6Df2kltdBAavx6kmq1eV8z3L+X4NEy4oslJBcLrmqkFmR6nUaJnCok8MhvQ+AJd/+qp/EQq5lm5W9+HCAyyR5IcsccRV9FKD3NvbX5aCDMLMOzR1i7/zfwK7g8WWL3FZ8vILOQj64zdLyW9ZMNrJ1qIHq8DI69CY69gfjCDpYWGrh477sIf+0gXPoyiG4qlMzmaqOyrKvlaTpMUn2e1FZJpR1S3RvaMGdBZEW0j4abuNVOssJTStZUiQVtDbD+T0S+P8xL2l8ktXL1ABHwFJtph9e0RSH4iFoiQG4gS4+z8vl3EjldADPVcHQXmYUiEioxOb7NgMLCNjKLO4ieKDElFzpVQPREAZn5Emc9FreRPbGFxGmXHUwu7IGFBlh8s3khsafnIbPutHJc27ElkTVRvJhbcGhu6Sb+/R8FiMmV/H1ZEYFDWw2oc7hptYtw+eMkv/6nZBY12XM96aN58EADPHALIU0aCiDH869qpBYLYEGFcaXETu1k9TO/CivfdvcvcJg/Yo1trC731QDR5JmbgZX4vwoor3j+E9DiEdw8CpWB+n5A6ls9nJ+/Df9CGdn76okc2UbmxPWkjm8lutBAaGGvAcVcjoU3wOK/IXP852w+QDHM2ifehf/Lf0/iBydh5QnH9HQuThCYZadlOhRnBLxq1Zya1A2LAa73sJ7p7KglGFQ2HHYZvsSj8OQQlz71+zzzwIcgffaaAGLOfjwqBFpdmCJRVQObcQudIfyP/4nwac2GF8HxalKL5cidSp/aTnrxBgwgSvkeLyNwqoTA6R1ET95MZqEA5nfAyTeTPn0Dkfu3E7q3jMTx22H+Fli8kezJKgL/Mux6XqmJtxoWqrIjE7e19IpBJQI5UdBjBxbRUu6F3vnfaUGkJfT9qkpVoy0pMRWvZdVHVcszn2XlsTYCj7wbTpbB9PVkj94I95fDx/cQPVZN4ngpqRMFVzXSx51Pmj1WQvz0Di4++Fay5796RUHYvcv9CFi7HgtkJTWeiyWAKA5xhHMpUWdRRLhXj80AcoDR7UtDxzQ5Jq1+8R9Z+9yHCdx3KzxYR3zuTWRP/QLpk1vMgibmbyG1WEXqxE7Sp64nffrnSJ1+I4lTNxK7txj/6V1cPvGLXLrv9wl/tRWefdAqf4mqe7sAoXuR6GkyUW6jHO1NfN6It5TCzcHFuRpypUg9C+cWWP38B7h8qonAI38AqeevHiD6cbl8aW14rmVVMes8qcXJcnYkC4lv/iXhU+Wkj26HUyU2iRo9XkH6vjxTHizkWWwRO1FJ8HQ5wfvyiNy7jezxnbCoz7yJ5H1vIPjAVgL3VxLVvNP87bBwo8nU0lfarMsMGVUmqLGGytxjqLFXPOEqEF7NSSlKDVeaYkLykzXgtXY1MZ8jnbGsogxHPCIOnQdeIBl8maUXP8sTX/gAlx/aC6eLYe4GMnM/D/fmw8ebiS/UGkASJwq4mmEAOV4Nx4qI33szZ+69lcTL/+BkW0DYAIhm+VUOc6UOX6DQXI3iEEdAN8MqojnC6VUv5bWhbXKkdmARQMICiAJmE9RlePE42X/4ANmPF8Dpf+uAcCKPrCzdXA3MVZJdLCB83434HthC7BPVhE5W2ERj/HQhiVOFRBaKiJ9qJv3J98BjnfDsKbj4bQircYRL2arzoqINSxbqXnVpnjHR01xaN6wgOp0iE3yJ1I8+ZZWwZxabid5fAI99ANJPXj1AFIOpEljzHxpErOOI1uPo+lTgmf3ufoKnakgeeyM8kE/8RD2h4/VkH1CM9iYEEHkAkRNVBE6XE7h/O5F7t5A9ngeL2+D0z5P4+C/g/8QWfA9UEznxKzD/Vpi/CY6Xcf5zH3HN4DLnXZeS/5+99wCvK7vuey+HBexEryQI9jKcrhLLlhRFUYrlOLFjRYmduDyX51jOs2PHzy+2FSdOHMe27Eh2JCeO7TiSZoYVBAESIFhBdICoLGCvYEXH7fee8sv33/scEBwNZ4ag9OaT7MtvcV/ce8655+y9/qvttdfWPimKEmn9TkZCxGrSQC4GvrICFyFI3hUgQc/qgUKNoFZkR/3x3p/5zp6nxFgJEa2nMWkG3g3w+0kPH+Rq62/Q9+bL3Nu7GjQgXyvA+4vl8GYF7H2FzNd2PBNAHGkQOcL/ew3ZXWUMv/4iXN4T2OjGQw8yYZXwJ6n7iOctQEJwSAmGAJEm0bO9Ez0CiNZsG7lu1JBWil2G/t9hatcLUFNBamcpmTdWY8D81XXwlxvwv7aO6d2rGd9bSaz6BSbf2GzylvzqCqguwH9zqZWuezbh7PsY3pGfgP4/hLuHIXnZaESbfBgkmYWKZbbVYMZPs3j3IN5L+vrr3G/+Ja7v/hRX/mIb6Vr11S+aiolzdtJNBFAMoHX00hvTJuImD2pC/aF0mL4vMfn6R0h+dSXUFJHauY2YUnH2VuK/XmCjU1/dgNUgG4jvKie1s8Q45Xy9BH9XLpm9uUxXlzG1dwupNz6K/7W/AV8thTe2cefAL8Jkn82yVgV4E8lThzikJLUDs0qjKWGouZ/3Cg6dG1FKulmPrQ7VQ4V8IR4wyzoVU5ddp/yfADPqGMMWWjgfOMNG2GoBzg0YP0i29xe5Vf0Sk3VFZGqWwe4iUDRj52rYuQHvzZdxRbu24O5eP2ealk9TvRn2V5KQ3d/4y5A6C9nbSqNDm6rIbZVE1eOFzyAnUo8a4j1sTY+GBz2xtUfpfHlbijKNKe6uPsjEYLIbzvxH4oe/l7Fdm4ntrSSzbzXe3rW4O9eTfXMLqV3Pk9i9nWT1RpLVlST3lhDfk0ty7zKy1ctwDuTi1JYQ21/JWPU27u77EMO1f5/Rpp8ideY/wJ3/CeMHIN4N0SsQGzPBEeOiyOSTuZHthZt/SLL9hxmv/zATh17l9u5XuPS1DxNv1sKtertPn32cp/9fnRbyCbIcVJrVztZLYpsgwnAz0T0/QqZ6De6BxWRqVxPbWYH7xhp4vQp2rjf84O7ahLN7A+7uKkPsqsLQ7tW4e1bj7Kkis2cD7s7n8XZugzcrcXa+yoM9Pws3DgfFHMaIE2XKi5NUiXYDYPGt5sBsJFOC0pimM/f+zo8dUYRnBiB62BAkRgJoMY11euxcQdghYg2hNGvX6MjgNQDRhu7tOKd/k9G672GqutyCozoHdufDLgFkA7z5PO7OF3F37kAdM1eAqENjr6/F27ce9pfh7NxItu5HYKIR3CtkmWQKz6h7yRITZVOniYLGasp37qQnfasu0nUFQJXFlDa1/TAJY21w7U94eOQHGa3/AGP7q5jcW0Jq7xq8vZtgz0uw+wXYtwl33xqye8rJ7Com9WYuyTdXkti5koTs75oy4nvLGNtZxv3X13D/jY2M73uFaP3HSDV+H+7Rn8A98StkW36fdMefEe38KhMtX2Hi5K8TO/rPyTZ+GK++Cu9gCfGaNdza9SpXq/8JsbN/CpnLgTnypCd8D58bgOjBh4F7xoQROyjEapK0bvUxtednSO5fS6ZuIdmDhcR2FeMKHPJLJSx3rZ8TJXe9xujuH4aLX7fzX0wHAtEnrXQgSSyFMs2CMIX5Y0E0U3wdKAMB5R1ej4d5jRgN5gTCuQFdaDaZC4ZXDxlCnSHtcRku/1eGD34vt9/YTqx6E44xr4pgT67VIm9uw3vzRZxdz+Ps3mKkhrNnPXOi3RvI7N5GRtJmf4H5reje74NbO8G5Y6I+kvCKqsxokFByCCDmed+hd97tq/BainKmPDzVtVXXCDlmYdZNkre+yoPun+PSgRe5truA2IEiOFQJ+7QKcT18bQN8bRN8XZNfWyxpnuSrG+z3e7fDni2wax3+m3Luy3Dk4O4rxzlQydiu1Yzs38BI/YuMHHmVh0df4cHhrYzUljCxbxmxNyL4e5ea4yd27uBuzQ8ycfr38cds1XSL6Hd70Hf4Xs9rQs1Wg0hzPAKIA7d6mNr706Rq1pOpW0TmUCHx3SV4byg/7dkAkt69g5E9fwuv9z9C9Kzpc5Ut0+/LjEopcBIKRFum26xR8iXcQ0Vg+PnJzxeZYX7zRpe2mmHGHwnBYa4RRnoeuSjupBbxqlTMLbzLf8ndY/+Y4dpXmTrwMun9L+Lu3o6/ewPsLYU95fi7tuLu3kF2z1Yy+zbi7t0wd9oj0+pVUm+sxd+/HKe6kLGd3w1n/hhSDw2zChgCiRk0PUPIwCbi8+SOeU/f6Fq6sCjj4afTpNJZEloKaraukFq5Rfx+Dfd7/jW3Gz/JWN1WsjUVsEtOZoExFYxW3bUZdj0PO1+ANxTnfwG+qkVmz5tiD3x9E7y5DnZXwp4y2FcK1SVk9xeTqCliqjaPsbqlTNTnEDu8AKdxHhyeD/ueg+oiMw5Te/8uifbfgtFmM4v+XqI479oPBiD6TzPzY2/RIA7c7mZq708agGTrlpA5VPw4QHYpJL5hTpTZu5XJ/a8wffJHYVg75Gr9kd3xV0ZVLJMwOLAYkJYL54qCWgUCybsCRAfp+YxtoAtYBycEiMn7MULRLuSxSxxtRXdjxEdVCmIYRvfzoOknuLhnB6N1W3GPvIpb+xLerpfwd76Av3uz6QR37zoy1etIVW80lN0ngKybGwkgNR+0E0v7c0jvX8bIzhdItfwaTN6dCecKJNZJD8KiQce8S9+8K2/Y5w9imhKdXoqEN8GoO8KIM82Yp0rAQmIC4lfg+k7iLf83o9UvMbVzMfHdEZyGlWQO5ZOpKzLmlHyV7M4qk2vkfG0L3td3wNdfwn/dkv5Of3ULib/cQPx/rYc9r8Gul3B2bia+s5LpXcXE9xXg7s+D/dLcq6H6Faj/AWj7DbhVD9mHZng10uqKZ3qpE01HWic91CAS3CbfY7iV6L4fJ1OzCad2BdlDZSR2l+FrScCbmwxPeHvWMRcSH8Xrt/Cw9ruh5/dg+oKZb1AQS+WKNNFqx143Ewh/41dbnjf3+C5MEDGDrPNNjdhAe+hPhbi1LmKmGohmozWfoOWfds2RERfJcXjQSKbvl7hT/z3c2rve2NvZui0QAuTN1/B3voK7ZyvZ6jWkasqJ799gHNTMMwFkI96+l40GcaoXk6pZzET1ZkYbfgLuXLRYN4l0EixKD1e0JeAKo0H0xzO8dLrsN8kVk+ikvpEdPMUUUSbNAiXbl7avJuBBA5z5fxk/9ho39y5j5GABD2vzeLg/l4f78pjYV0S8uoJMzQao3YovU2zvVti7w5AmIOWoOm9ux1M0aOfL8OYOM7ckXyZRXczk3gLGdxUz+vpaxt/4AG79j0L/H8Gdk6AFX1m7F59qQH3zACJPzFaqFytagCThbhPR6h8xAHHrVpE9VE5sT5kJVjwrQLL71pKuX8+DvVtIHFZ29Fdh/ApMJMzWcvIPZT2ofJMBiHwSw7wWIIGcfEcGiFgnRikLIhtINxGeIIIoiaDQWMasGNTKQaVsWDVmBv1hO5z+PA8PfZwHNZuYrN1IbH8Vmeq1ULcdf8/zsOtV/F0fxNnzItmaNaRqy4gfWE+iZiPZ/etxqqvmSBvJ7txKdvc6MvuWkqhZSrxhHXdqvheuttjZKj2AAYPmQSatsDMC4R375T1+6eE7SbxsAleFkM3MvECiPlL8TJVGAuFlR8ok8ZHpxbn9RUZO/xhjJ/8eE43fxcO6l7i/bxOj1WuJ1a3Bb6yE42tIV6/A2bfMkLdvJX51oBkOlMEBTaSthF1L8WqeI1kfYeJohAfHl3P/2HpuH/448bZfhbO74e51u1+3wKx5PUWkg4Vj7/Fh3/Yw48eZb3Rhm4elrBYjiBTRu9dAouYzFiC1BTj1FcT3lpvADLs2wt71+Puq5kTim/SBDUzv20h0/wtwSnuu1MDEPTN3qTuysA3sYIFDKiUYFv35LgqEiPHwTY2lIIw7S2uE6tKGxkIG088Gxyrdu//3SDR8L8NvbuDhntWk6jbi12+GgxvgwEb8vZsMSLzdL+PsfYF0TRWJ2jXEa6sMZfdX4eyvtAB52rZ6vdUee6pI7c0nXrOC9LE13K7+EFzYA9H4jEulaTWl/tkZ1PfQM2/LDo9/aFfraalQnKnsJAnHrs03PyqzypTCCUJd6rZQQWu2lxtAD9z8czj728Ta/hX3Gz7D7eq/yZ3qVxk9sI3pQ+tIHV5Dur6EVF0+yZpckjX5ZA8U49aVwcE1UF2Jt7+CWG0po42rGWnZzlj/p5i69C9JXP0CRLshqRBwIE7VamCVGiSz/BlfhsH0nzFd5BrbyxspqjX892tIHPh+sgc249YWBQApMwAxvocBSGUAkKdrFb1M7Nlorh3bnUviwA4499swNWhuQjETC5AgvPgNAJGn8s5WRMSIEhMKCyWt1UIWHCrXrIJpGVw/Y2qymlTd7Ah+8gZMH+b+wU+QqN1MsuZF0vt34NSsw62pxN+/FqrXQfVGQ17NetyazWRqXiB14HmSB6tIHlqDW7sW74Co6m1bt2atud7bt2vN6j1qN+HUrCVzsIL08RLuHtjCaOMvwd0ztockQJgmyR0eRm+RNqkINrbwLPyh/g75TuVJVWjBqi3lJgWaI5BYxsWzCtrwpz42zGX2c7wNYwNw6yjZ83/B9On/xFjL5xg98c+41/ApHjR8jJGGv8FYwwcZa3iNcVH9Bxk/9D1EG/4xsaM/Q6Ll10gP/BHO1Wq7tcLUdUjIaQ2KgolHdE+iQIOa33+WDtClpJ3N9SQ0fbPxpX7CAuQBXPwTotWfNP4R9atNQCG2rwRqt8C+DbB/PdSshZqqp2/3byaz60VczYMdWkaqeinj1R+Bi182m+RIu92Pxon6Lqr270xmbPqBKS3rEc3Kong3gISdFhhkOkErD2xVjRgJN246wfrwStWYAO8q7tgBJgd/gYn6DWTqCnD2b8WpfhF3/6YAHAJIJdSsgQMVeLUVZGvXk6l5idSBl0geXEvqUBlu7ZoAGCFQHm8Ftnei7G519nrky6TqqsicLOZhXQXjDZ+BK/tgUqvbNGJavz3CpDOM1k+LO73A/Jorj6jrHgHEbjFtfkyTqmLIwC80bWDs6yfDuROda8ZH32mFT3oSErfsjrfRdpg+Qvbqn+Fc+zL+tS/CtS/Atd+Ha79r6eofwd39JgeMBwMwph2SMvam9NshKAJA6Oc0vtKidjZZUcm5v3SuwZveCCkz/l7wXM4wXPg9YjUfNRVdLEAKie8vhroNVoDOAEMgeUravxktmzA+Wl0O1D5H4kAVbudPwugpM5OvqKI2/jGRaPGBOt8YQFlSbuI9AEQjpo40QFJ+ihxxrfO9h8MYWSWhqbNlQ0tAph7AZD0T5/8frh1+nujhlbgHF+PuX4e7bwf+vu341QJJJf6BEqgrwj9YhFe3Gq92A86BHWRrt5M9WIlzsNx+iNxyWgAAIABJREFUXleJ9wRyDqzmSeTWrMZTuLNmrVG1ybqNOKdKGT9cyOjBD+F1fR7GtB2b/CsFGSZJ8ZCoP4JWnRkp9wwcolOtpp2xWiy36QsxvbhnFpMaHAS40TgJINNmpl+bwqiCvNXWnjbpEYWJgEpTl6bJToEzYZfpOqopO4HvTpF1EmZDmWzaMRntM4drvPSjgeYSKFRjK8U0CcZNa1cizg0keszw8ULNFMpbA5jsFTjz6yRrP0hS0bRDFcRri+xc0EFN7lbBgSr82so5ETVKen0Z9m2DmuVwKIfsoVwmG14mPvAbJsUGd1ZIVzyuLcudJI6XfU8r8iNGus0ARPlKIzgMGzLLddQLAocy47Sr6EQP8b7Pc+Poa9xtzCd1eAkcXAZyGvfLnHoeb/8WozG8ukL8Q3kBQKrwajcFtM4C4z0ARBrmSSStRE2ZAWNszwYSBy1Aoo25jNRUMnXkH8GNg5AYMdJEjnMKpSOMkxBoxDx6vmd46XQTCg9MDRPnEEOK9JkJENif0s/ZteTKIrabKkSJMUXMGIBy6xUWNqFJreEIuU9t+F4caC9kri0MKJCmIVKuqOZfdJ7Bls4xzyetoXI/KvIQI8UkCSMs5DPpgnN76dLKhlYxa7PMOdAguj1T8Do5iN/zOdIHXzKpNn5dGfHaAkPGfzqwZk7ACAHFgXVwQDlvyu3Kx9+/FL9+KWM1hYwc/bv4V/8bZIZnKQBFZWM4fswsNdbYvNsrYkSg6SOpW0VfBJAHRnuYkpZCnVFNHkzfhPN/wp2Df4fhA4VkmwvIHsrHqyvGq8vHqy3Fq9mIe2Ajbl0x7sFc/Pp8/EPlJmTJgW1QVwEHpWLLg/dr8A8+mdzaCp5EBiC1miRcS6x6PbH6KtInS4keWcF47UpGa1+CPjltKlOpNAPVhRKDxNEaZpM79W499I7fiwMlOZTNaplY2lYRIpn+0i6PAhzKeQu9dHW4zpVWGwm09YiJss3YR8pk0DWFlpCkyeV5aofXjLaHU4DACxxRa9EZ5jSo1Y3rBFWdUXBC46qJvOngnuzl3wOPPLEHZK4pwqm0DpNmMwMQDy8zZdKO0m0/TKZ+G87+CqgtJXEw35B3sAxqy22gQcGGuVDdWji0CQ5uxtldQWpXHv6hXBIHcxmv28B002fhYYOZ95GNZarSe6rTr37ROAWq9YlPqF1u1aPGvLILi6yJpTmDQLJIa5g9z4fh0k4mjv4YD/dvJ3E4F5oEDqnIdVZLHMpDD+4cKsOpV0ivALe+HP+gkL4NDmyGulI4mA91AUgOVrwjQIxpJvPsbUiShAPrze/L6Y83VBI/WkyscQWx+kVM1FUwffKfw/B+8GQ6iv0yaJcpMYZjp7vfoXve7St1tFIVVSvLmlSKlivmod+ypL4ctyWQjFEVLJZWv2vQXG31NULWH8fxdJ1gIZRSVVRqXNmgIam0p8iohwwyxaQTQs2T9rWKzsNxHLOXeNrXdpcqxyRgKEQvsMjcnLm5Z9KgFiBBxUbFdmcAksVT5GzsKNMnvx+ncaPxQ2Vyi3mTh1aZ3DAOCiASmHMFSAXUr4H6dXj7NpLctcYIaw4Xkj5YxKiiWmd/C8aVOTBNwneY9jX6Fhi++PpdJETESixZw7bOklSmBtYkmylOrm18YsMwXM10288b2z7VsA4aC6FOam0HXs2Lxodw6nNxGueTPTKfbEMe2UOrceu24tdug9qNIMRLatQWQ22eBcrBclxFs55AzsHVPIkETmoEuk1kG9cSP1LK1KE84oeX4xxdQOpIIQ/qP0ri7Bcg8cDIApkk0pMaXLNB57t00DtDRKiQJpBmUB+K9F5kxH3wffDeJNAFzKnTgnXT0jTqcwk0Mbg2qElnYmTMfoCPrqfUEOEqBJ/RFvoj9CNVFE9FGHx5M3ESZvmrZmVmfFOrNnQ74a3q/Dm+LEDSpPwk2cCn0z2ZxVyJh/j3DzF65JM4R6qMteDVFBpwpBpW4R4shEMSls8AEAMwCdtSOLQDr+5F3AProaES6guJ7i8n3vSPyF79Y9zUJZR4orCvFLIBhgSQ1Q5P7IGIzaGRhLOTPDpZp5n13Or41Bjc3k+i++eZOPZxEkd34BxbS7ZhJXHlPx3YbgDi1FXh1OeRPTLPkgBysAq3bpsh/+BajMSQ31BbasBlNIkBSEUAkG9sLTjKA5A83kqrULsODm3AO1ZF8shqJmuKiB/Kh5OL8JpWcL9uPZMdPwsT/Qb1inzLsJEv4D1m2AfqVoB5K5lONGp2piPDQ+wH4jJBT9pEqyHU6u9gSwIdPDv5U1wUAEQ8rbQIs2RZZpmksOeazUMdXwaU9vASqWio/tnx0TjJjDNRGXn8Kd9qGhNREUDSZgY5hK05XvehC+iPbwJALJ95qJBENp0x2knmi5ZQuLHbcGcfIw0fgSMSjJX4e0vJ1JWQqi8kVZ9PtrHImN/+IQuSp20NPx1YhX+gAI6+CMc/aMx7o5GOFuDUrWKiYQuJgZ/FGzthxkQjpa4y5rUZUv1n1wBJAIVkgaP9QdwL4N03kkn9LItapL1nTOdPNOIP/hzRxh1m0so7+SLJk5t5cHIZd48uJN24Gk8MWl+J11CGd7jAkt7rs0PrLdUL1astqUPqywKqwGuowKtfPYe2DBoKoKEEt76KbP0WMod2kG1YT/bYQjInIsRPFDJxXFt3/RkkboIW9gdCdzKrFGhxipg5ULe2v6ykNe8FHKlSda3pUYMfKylDDa3P9b06LaTg+BBJT2hnO/LhIRZ04Y2Eg/Z4oqh+X8eb/3SoOXn2OXYBmO5CNHP8o0NmfWh/8an/12+q+0yKm2z7MaLcI+3fhvR1HrT/LtOHP2yiV1RvsNGmA9vM+ERPFDB9MpdsY4kZd/GG+OBpWuor4FCZvf6hqhleM583LsM9ugSvpYzx4x/GH/oSxIcgOYyTiptKPNFE0G3BpkrihTAlySwBIU3ELJF1Y6YCRMyz4FDI0Umrds8AXPk8tH836YNL4NBiOLKZ5PGtPGjK5cGp5WSOluI3rJk7HV6NP1dqLIYjK/AbC/AaNuIdegHn0Es4DRtxji0ne2IBiWPLiB/fQbrj5+DmPltWx1UMHKKeCg1I6UokBAAJOT/g70c5ajJ1JH5tp4aHGSZ9as76DjlBYAtki8cUSYZJowW3Kit0nJHWf0288RU4pIRJpZVshwPbcQ5vYPJUIZPNeZZ/5jj+NJRDQymmrV+L3yBSmk4x/tHleMeW4p0sJN30Aqn2H4crfwqxQcjGSacgqjVVZjwVvbVmaTj/p4CKQBIxYy7fL6mCW5YFHH8YEtUw/pskWz9K9nAZ1ETMRIx1qDYYcyZ1fA1O4zOAQw9jOqcc//AcSB0RAqR+qwWIwCGt1liKc6SYeH0BiRObud/wYaZO/yKkZGrFSCWSJnPK5mfJeQ0UxGMiV3+IA2ymqhWXdnLNdux3CKPP9TFkqpj6COqTSZL+/UCI3CF2/Q8Ybf00ySNbLUBq1oGobi1OYznRk8VMNRWSlYCdy9gfLofDxXA4DznlHLIpTv7hUrwjefhH8gwPZA9vxm1+jQdHNnO/9R+Zbau1dimbcEwdcw28xlK+t5YxK/iufwqLi8x6EBN5kWUQ6uJUL/7Ir+Fe/hST9ZW4tQVQuxRqta5Ys+Mb4dB6aNxgESsmD5n9ads5do7pVAOQPPzGQryGDTgNmw1gDUAa1uEcXke8roTEkUruH67iYcvfgzt/AdnL4GgpsawMJRfK1LKZy+E8hkWMNIY0jAASgkQdJdH51y8xlqpqJh2bnJlOaxJTxfmGGOn/UUabt5I5oiiTQvqiUuM8e0cKiZ8oJnailOyROQjGkGdkQTSugsY8oz28hnV4jeV44gsB5fBa3MPbcI5v537jSm4c3Ub6whdtpRhV59dgy4IOMtY1stYHF1gUrPKIRLlPQkvtLYxAD/mwlvTQDzPduo2E0tYP7oD656FuG+zfDvuVyr4eDlaCNMiRCvy5tjr3SNmcicYyOFKCf6QE92gJ7pE1uI3r8Ru24TdsIXmwlOThIlKtFUy2v8h474/C2C6zTUJoVdn5ChsMmq1AbM0s63Q+8s6kUWRu6ci/2kDRVECcaSY91X1Ut2gtfBRGD/Kg5UNMnVqFe7QIDhdBQyE05MORlfjHckkfLzOJpe4zjL/GnSOFcCQXjq3AP1qIf3ijGXsatsDh9XBsDenGQmInyhk9uZV77Z+G+18CX0JSmylZB01NCBALEssPkYdcYJrbJlpialqNNeFc+vdEOz7CZGMp2cMb4ejLcOQDcPAFqN0OhzbbUJom/BpD5g4Z/Wnb8Py5tBVwuMoA1D2+EufECpxjZThH1hvJIYBogU5aczany0h2r+P28RdJX/lVu5FmQuvtbUc8Aomteh7+bftPjrK80TCEIa2iCNU3IV/821gRaeJ1iklGmcTsMSQOmxyAi/+esRNVJE8shKO50JgPjSuNv2gY+ViuHaejFbhH5zLu4TkCSBEcXYl/IgfxgNu4EbfhRfz6HdCwEY7bbA+/ZS2pjm3cPL6O6NA/hWSdWQVrXIxZ4XaBwwQFA20SGeE8ca7hch9nopn4lV9lsvtjTDVVkjieS+p4Hl5TKeljVcTq15I6vBZOrYNTRbhHlsOxYjhaCkfL59jq3DnSkUo4vBWOrMM7uRS3aRHuiSLco2vxjmyynzeU4B/Nh5Z8Uq0FPDhRznjH98L1P4eoainZ2sICgt3yTHudaDsHK1FCoEhaKnxpTS2p578GiGbRJ5hmTCaqOEuK9eGfE2/7hNEQcpQ5mmfp+HI4sRKOFbwNz8xx/MV75nqr8E6swj1RgHusEq9RAvwFOLwJGpfhH1sEp8rJNK/l4ckiRjtewb/xKyYbnawmZAMtEqxAFEBCikS5RUZrE9whssP/i8nuTzF2tJh4YwE0lxA/lkPs5BLGGldy9+AqJo8V4Xeuga5csicW4R2f9cAhWN5rO1dghOeFAGncYDuoaRFOkzRJEd7R1SBqLIKThWQOLyJ+dAmp1jU8PPYSMc2NxNpmOkeTXjaLQLPOsRl1GwJFALKhP4FExQCCGXGZpn9FX7LTJ0iaYnFW7I7BvX/DpMyeYyU2BG8kfAHeiZW4J1fhHRMYVsORUjgSCte5AqQIjq2C46vwjhfhHi+1dGw13pEN0LgWrYOnKRfv6ApSR1eRbClnpKmKye6PwvgfgDKOBRAZA8EiwVCLCCSRTDZqioulbuxntOVzJJtfhpMlODUqCFBEtG4BY4efY+T4Ukab8phoKSTenofTtRg6l+E15eKfKMY/XvK2LSdKzfXettV3z0LHK+HIFji6BY5X4jcV4LUuNERTnr22BuJoARxfin8yl8zJKmInX2Sy6XsYPqnatNfMwiY/JSfclkBS/ELLUdVRIoHEmlryOYI5Eb0VfYcDJJlM4rrGw5gRA0plUbE59Uk438h0FG7W4PR+F7GGCN6BFXB0HWgW/dhqOzanivCPr4Nj66zFIRAdfxYeKIETeXCyAP9EFd7JKmPteKfyMON/UsK7HATKk0vh1EqyJzcRP7WFyY4S7rV/GGInbE2xVAIv7ZqJWo23lOG0r1ysWILszS7GOn6V0caPkT2sybw8qF8LTdugZQ20l5LtLCPRUUa8o5hE6yrSzYtwTi0OAFJowXHiG1uBjZOS4m/X6rOA3glIOubtvj8hLbEBjm6CYxvwmkpw2ubjtEfwmxcbyYGcRCPFVhnV7h3bSPbEVuLN6xhp+Qjc/e8Q7wHtXJuJ4SY8m2wYzLiGGkSmlmETASLAyaPZtxne+Y57k1UF+VkvgSOVSpHJZMxkm9GsWpE60YV76TdJd1bhHo9Ag6JLSknaEoxNqVmK4J3YYAEipj1WBCeeYfwNXxSYa4QA0XIHp2UlfstCaM6xADy22gLpRAH+8U2kT1UR75rHWOdquP3FIMviAXhR9LwSjgKIwB9h/C7x7v/O2PHvMrOOnFA4Ls+mghypgJPr4dQGaN0E7evw2yugvQRayuCUkFlkpIPfNJdW54RUErx/760BzbEqK6mOS3qU4LTm4LRF8Noi0LwQjss5FEgqbMqDgHSykmzLSqbaS7nb8Qmc2/8Zkn2QiJuisr7WUwWJd9bcUgasXU6qyKARnValfMdrkFnYMFojnU4jraLWJHuqH5K38O/9IdG+v028qQhOSVrLzKqAxu2g9KSmSpymciPlpe2NVDcAeYbxF0CkgY6X4mvsT5WSPbXaZJmLB/zWCDTJTy4H45NughOr8ZpXku6MMNWZS7Tvx+HO18HrM9u5+dkJ4umMqYov6yHC6HmiLb/JyPHV0LMYWjT5kgtHFkDjAlAlioPFpOvLSB8pIXN8hbH3OVYGRyugqdR2hjpkTlQMp+ZI+u3ja+DYWjhRgd9cjNu6Cqd9MW5HBNrmQdMSOFYIjZq3kaapNOrXb1tAqnMxd04UMNb1d+HG/4DoDSs2BBAzy6p1G9q9V6T3wfJSM2nyV8PECgGi7dlkakmDhCaWieIlJ01KefLSZxlrryB6LA9OFUCr+KECjm6DYy/gN63DbS6DpjI4KbOq2FLTHMdePKPxP1Fh6VQxbnMxmZZSMq35OO0L8NvnQctiOKmMi+ct6bdbF+F2Rkh0LmOi9WOkz/0bmHzd1ghQqkx6ykasDUCifcT6/h13W9cy0TmPZPNyaFkCp8VgEWhZhH8qzyDUbcrHPbUQ9+RCM/egORBOlUFLwZOpOR/eieYEqgCM6tzjZdb8kt3ZnIfTIhVbGHRQBP/UAjiuUKMiGpIgCj4shrbncDqeI9a8gPGmtaS7fgzu7oLkHe1nYBas+07UOO42/UCTR3Yy0ZhYf0V8kLCwtVqB5LGXKqmPt8Dl32SyZzvjrYtJyKIwTFgIHRqbdXBiI37TGiPANEacWgUnCi3jPuv4Gx9WwKvAbS4l07aCdMcy0vKTW/OgdbH9vaObQdSkiOYi/LbnSLevINYmf+Rv41xWTed9wEV8Z8xsnaDxjpC+Cnd3M33lJ5m88Alig99Dov9lol1FjJzIIdO5AbdtB27LDvzW9fgdi6H9OWjRepBiKykkLZ5E7wQefddcNHc6Jd9GpOvkGpC6LavJtpbjti/Ha8+xdujJXDhaaemkgCSALIT2+dC6ALelkHTLh/H6fgZG3gDnnNlsJjl536TFS3M8CveGVpU+lX0upHznvkKN8VZH3Txx5oZZJ+/2fpqp9nyi7QtJN5eQPVlmwdBRbiKhSHM0yyzPh9YlVgCfyoemkrmPvfjmlPwXgbAcmlbjtZSQ6VxKunM5mbYysq1l0Cq+yIWT5ZbEJ61LoXUlbls+XncZE80bmOz6Xrj/e+B2KlZt19QYJ13FAlLjuNNncSaPQ3QPzv0vMXH+3zLe86+Y6vgcsbafJtn8z0m3fJxM1woy3REyHRGy0jDtK6BVKvUJpE55Ij0jQKSZZO/KzhRYTpXjtpTbzmkrwW0rwD+10n5/cjmcXAUGIOqkJQFp0EqMepY0yV74LEx+GZIDZKeUOvFoD0aBRGkpZnvrmXV8Asp37is0q6RBwpc+m5qaInG/iWj3D+C0VxqJnWpbbswbmTlO8xoj0WlbDm3q65XQovcSSvOtQNOYPZOAVPBGjC8AFuC15ZLpyCfZWUC6XQCRv1EZgFPAXGjvwQjmcgMoTq8g1Z7PWPsHmTr3L2F8f1CIW7V9IaI1I1pPnFbRQVMoSTVWr4FzEbyLMNIM9w7BzTfg8m+RufgPiJ17kYnezYx3bCTd+jJOy6s4LS/itm7DbduI37YaX458Rz62g4TYgNRJLeqs3MD0eitIZLIV4bWtxGtbjteabx7EPuhqa8pJKrQKeJIOS+CUACJptBq3tYxsW4mRHnrvyR4WSKQ1TikmLpNPYNY9rIQuResK8ZoWku5YQqy3itjQ98OD/2krhodhLNXaDXK3lOCoORNVC58Jos947gJMSKEdFrLWW9vw+0fM99YjvvFvHTv7+sERb7F+vvG8Wcfp2JCMFgwnPYPU/mBdhCZHwyW11gOTxozhJm8yMdzC5MUv8PDoFtzWZdBZQKYtj3RrLm5HCdmWSpInCvDalwSaejm0CiALLZnx19iHJLBIy4iK8FpFBUbKu225hvnFC9ac17EKEgXgMD7PcmM1CCDpjiIyhgfK8Zqr7LHmd2X5iBdK4FQVXrP4NA+vp5ypzud50PV9pG79PtBrsibcdErp7rM6y3SyOkFBrqQtja9dUc1S0HG0nx3eADgdkGmD1Ammu3+HVOevkez4HIn2Hyba/kmibS8Saysn0bYMvzcHTs+DLmkbRZbmwcn5cCwHjkj654LUrbRBSwlKCXAUVj49n2xPhGRbDpm2cpyWl8k0bSPVtIx0i663AnpLwNiZYvhi/NZSQ15bMV6bfe+3hWZgqOH0d/CZAhIKNhzXdZZC53y8vgWk+0pJnP4E453K/r0KsYytjKCZI8OeWr6kPKQkqewkjjONp6WyBjBxfD+K40Uxc0yGmR9lAAdsOhMrDhfoaKJy9lA89kf4hTHnwvFREFKMHVxKuAmPe1Ib4nF2kCGtPdqDfdqVm5SeJp0cIZoeYcofNxOBYyZbz8wMmN3DmK4hdeHfMNr0UTJtimzm4bcJDCEVojHw2wrx21fhy8poywtoFbSJgvFoXmV8RxMRba7Ab60w45/pLCTVvYrk6aUkexaTOr2ITPdSnI5VZmy9lg34LeusCdW2xJjTbscSAxIDKAnW1gBIBnShQC2E5lJoroDmdbintnGvbjX3jlYy2vMhRs78E+LDvwsZ1TEYeRuAPKFzTeKjQp8qjZX2SKdc/MQUZJWuMQSJdhivgTtfxr/6a2Qv/ATZc/+QB03PM9a0jqlTFSSay0g3y4kuNSFlMTRdq/E6y030IXGqmERTKanWPLI9C/AGFpLpWoXftQE6PoDb+hLptkJSbYtwupbC6VVmYASCuRD6fWO/llrV27nQBid6l+L2rCfd9Sm48QV4cBQS9yFjCiqZ6Q8rQlwyaKGQdiHRbubSKAk8L2FLkqrqvUkPDpg3QIedtbf1qbRG3G4oGWiRsP9DZp7dmu/0gUAi1faWRV76Ssc8FkV4y0rJ8HohSJJBKSEJQbN92SiOPxqUBkrywFHdSNcsozXrPKL7cK/8IomeD5HUOLYXBmNQ8NStAY20T+uKwDKwgi3bUUyqq4Dk6RUGHMmeBaR6FpDpXozTucIAT/NzApPAkO1YOousJnHb5WMoB68YTpdCt3itFDpk2ZSYuT3a1kLXazjN20l2ljPds5oH3duZOP9ZmPg6+L08vj/II/H2De9kXphCG9peN+uS0QaJaS3JUpEBbUg/aXdl1TpqLdNNaOuvq7ao2d1quPUVvKufJzX0fxEd/D7G+j7CWM8Oome2MN27jrG29Yw2lTHZstSEX+nLh4FKaFday0Y4vRm6NuO0bTKZuYnOJWROL8KXGddeNDdqk6ottoMjqdaeCx1F0FmB172WdO9Wov0fxLn+4zD9v8A7axfOyMIxeTvSIirZM2FaUw5ADKjvQ69erfg5OEcdqzRqFQ5QqoYFR3hAwMxvZeKQmdXqOuHfBhCBRjG5YdIooU04u9Uxb0M6X1pR92h8qmEy3CLBXVOlS1eQTDC/qe2nJ0+QvfILTHa/xlR7LunORfid6rP8OZLOlXmWAxJOXTn4nctxO3NxO/Mtda00n9G5HDpWgpjemNgy11YabZPqqCDVWUqqU8DKM0I1073MaJx01xIe0VLrQ3etItOVZzQe/VXQVwI9EdLdEaY7lzLR/Tzu5Z+H+J+/O0AEjJBCgGgPakfFBVzHbHWVcFLGoTECVuMQMofpYY2N6uA8hPQgJI5A9HX86S/jTf4W0Zs/TvTqP2bq/A8x2fdJpk9vJdFdQbZD4FhrHT1FyLoK8bvKcNu3km7fQrxbEmaZ6UTaCwOAzKHVtY26z8NeZzV0VOJ1VZDpLWaqbwWT59YRv/YDMPoFSPWCmEUZJ1qVSNqYIZOoBI9vhIhhKPVByKN6L0YTQwZvw69kYs0s6Q21TQgQtSEYZrch0+ozk1EcACNYjz5jIpu5YJliYUJIYDrPmNCPcmm0Pj/JQ6a4yzSjpsCBWQKh8Uw8hFvVpPp/gWjnh4h2FpLuysE5LYZeOUdw5Btw6Xy/axm+wBEAxABOQk8CrK3IRkhbQodeJpL8xxzr/LeXmCCB07Eap6MCp7MEp6sQpyufbHcusZYc4go/ty0h2b6UlELAinLJMjGgWwYdEdxmmfMR3IEI8Z4iJrv+Jt7Fn353gMzUGnjrxlOqwOFbASTrW6TiZSFpd1UzZZ/FgEemmeeEeymo5pO83jH8dDskD8LUXnjwP+Dar+Ke/Qzprg+Sbi0j0zwfpyVCtjWC07aEbMdqMt2bSfZUkTxdjttVbBxEOiX5C3jqVuAyWiiUgrpeMV5XAU7PCtKDOUwN5jAyWMjEhe8iO/xvYbIBEhNGEIj39cyBR2Aqk5jl66GgCJk5ZPqA58OPH/Mhws42TC/zaRbjP/Ze380qHxSCT79hflzw0x3J5HvkG1ng6MZ0QmCO6TIKZHqPjtaZGipzmPacvPtnuAN/n2RrCamWZZaxThfA6aDPu/JgDmT6uLsUp6sct7PcmNq0r4Y2BWPWQnOQOd6kQMoaE8o1Gl9zKc2Knsq3CfwZ+Zptpfbc1rXQKv8kIJlSum57CX5HIZ78mI4VZsrCO6G5sgiJpgjxtgjZMxGifUsZ73wJZ+gH3h0g0haimbELNEooCbWb6Zg/kwQeBD89s/zd1uNQ7SbPTN0nHEhqP/UEJGKgTUgd1XkyVUDugXcJEi0w8jrc/E9w9V8YU8fpXkCyPUKiPUK6vYRM90bSfevJ9K3F7Q6BIXA8JWlQu1daEsA6iq0W6cjF61xKtlt+0HxSg88xPfgco70FjPZ+F6kLKox9GOIjNgYc+g1GSfhknCzxRIppVZcPlnTObi13iptnuQvSBobpW/u1AAAgAElEQVTBw0iSmFwSX+wqCqW/PhdApHmCc2bODZjecLaAIAqON5GpxwMBOl3Va6TgtUZf1T5mLC79XvYc2cu/Ded/EPrXQvcC6BDlQFe+te3nAIwQTJ7ModMFZE4X48gX7VDe3xpoXWNzAAWQpg3QpOUVa6BZ5rAm/wSMFdAus2uJpfaV0C5zW2NYZq/TVgkdG6FjA7Svx2+rxGkuI3WqhGRTEfGTinZuxu3cQra3nNRgKfGBKsb7XyN16Sdg/D+/O0A0UaS4dzijOns2VR0cDqM6Vqu8tVN2nAfEuE2Cm6S4Tdps7jhhlLhklzHZxAeu3Wdc+1QYZ1bF0hRvFnomJmCyBy7+PAy9QmZgAfFuAaSMbNdG3L5S/L58/O58mCudXgH986FP6l3Om6RMkYm6eJ0RXEXe+nLw+paT6VtJ7HQhk53rifV+DIZ+Dq5+Be6dhrG7kBizRd/MRpEJprwkDzOquWs1jPJ6JArUZ9Zx12KtoPxpaD4ZgIQH6Q91jCgAkzk3+D441jr5ykLW/Iwt56/fMBQIs3AjJNO+xWrzFVTw0wYoRvkId6lpstNv4D78Wcb7N+D0F0LfGji9Gjplii4BZXP3LA8ETC50Pz35PcvIDkQMub0r8but9raCShpB0UUBpgI6ZGYvg57n8PsieL05NkLasxB65sPpoO3VeNoxpW8x9OVCfwl+/zr8/m3Q9xp+/3dB/8dxej8DF34Xd+jLcPO/woMvkb31X0nf/EtTYhfn3nsHSAgSI/Vm/acCcyILHMFFal2p45pPuYNnViuqHcFjHOkWVQT0Xc9YWcbq0vyC4QchJli4p+IYIknqG79AamgLsf4ckt0FuKfL8HuKoEca4OkHJjxHA8Tgc/j98w3QvM5S/I4AIB3zcZXL02s1TLYzD6e7FG9gLe7AJjI9zxNt+YTdj+LqmzB2DNyztqIHWnSl1XYm99HssiugCCTCgl0LHdQoDRjdcrTtWBvynV3uZ5Yror4K+svCR9saq2qkStbY2YoQVo8BIzxvFkCM/2PGSoWwo5CagOlrZO/tYfziP+Nezxrigwtx+iK2n00EqBDkd3QrfC9aMecx8HtW4PblkO1fhNe7BL9nCfSE11WrlKcV+KdzcXsKSfWWEOtbw1R/FRP9m5ns20ayZysp0entJHu2E+/ZQaz3RaZ7X2Gq50Okzv0d0kM/gHv5x+DmL8Dd34SRL8DEV2ByP4xfIHvnEkQvgn/Njp+CTupETRTO4vU5vBUyZMTOIv09Q2FUJTQVQps4XLoqyRdIOyP9BLBAaEolhYffbyZ55WeZPqsiYItwJSVkTyoPTCZWz6q5Ue9y/L7F+P05RlPQuxxkW0ubGCqC7lXQLSCWQPdq6KrE75FEkgRbSeJUFdnOT8LQ5+D+VyDeaje1N7UxrPYI/TOjZV3XhMiduEs2ljUVFNPOFBlPJULF6KpwKVJwVaVoRCqXak2gpI8xV5Ne0JpAlN0YT6asjpMuMUVrfG2HbPfsMAWmFa71M2Qczd/ESKfDQndX7bzWw68Qv/gjTPR+gMmuzcS7V5s5oWz/KpyBHDzzzHm2j06vhNPqrzn2vcasu5xsy3YTmfT7lsPZCJyP4A3KUY4w2RkhdSFC8sJSYhe3Ebv4aaYv/Sumr/4Hpm7+B6K3fpvYtf9C4voXyd7+U3iwEyZk+nZCesguqXVGzF4hpjq+CnVoBaFK+GjORwWFJbFMirYV7D7jQSEP64c9I0AEs3BCUVPy+kFbKcIgcLbpICfG2MQCi25GIAm26TXhTlUWETPYpEBpFqPydfhkGu/OHuKX/qlxmJNKpOyQk7jeDpak/BzJ712FGRxjaklNSzqWQKfs10roEkgEkIKABMjlMBCx1CtToxS371WcMz+Ie+XX4OHXINkO/k18Rs0KxaSXJOlmTd1ps/4o0BxZL0nW1NC1GyGEhctsETNVXFHFS81oPwqKGbAEGkmgC0ldpe8eeR2BSacKHdkkmeQkWWkJV7pNY3AP6IP4Trw7nyd1/h+QHqjC61sJfUUwUIHTU066v4jk2RxSZxeSHViO17fKAuNZwBEAhK4PQOfL+D0FeAPzcM5FSJ2PED0zj9GBFSRvvED85qeJ3/4lUvf/B9mxo/iJPvDOABfsgjd3GNwR+1wh0wcaYCaiqh0lAtktv8vUT9beQmHcyFS/j5tKxyr7E/Zx5Bsmld46yfSOf+suQi9Erf7WyIcOp1UP8jmkKozvEah4fWTUh0BkTpF5oOrrsrJkuz8we1joigZX02M4t/6EyfNVTPVG8HsXwflSAwwx+JxI4JA2kLlm7NWF0KsJSGmRSujURFJpICVzQJqrV8eEtNisrNQMb6p7Gan+IjLnN+Fc+wT+7Z/CHf7PkD4JqSugOSP5zDJJg6Wd5tlCFaruMCnlvgmfy9FPOtrfS7P2tuC2ClUn3/Jv0plmyomZIngJ3xZTNf2tPhUJWWHgylTxiEL6ISRuQ6KD2J3PE7v+A8TOvkqmrwp61tgMhe4VZl5C/ldqYBWxMwXEzq4ieXYx2QEJBYEkz7TSpHMhc43+EhhcA4MbcPrKiPYuY2KwgOjlV0ne+imI1sPEdZiSbyrhK6tDGla1q4JAhfrQc021+2wmTiodJZGeJpqaCjYLst0gDn0raQysHBf/2cqKj8xVlR41vRj25tO2spPtTHCYKhEqDdMGdm94E2pnkwFJeEJQh0gAiZJkmltEGTaAMbeoJxs5TfL6DzN1tojU4AI4vwA0WP3LoF8O91O2koS9hdBTDL35oL/NZ7n2MzMLq+/0uX7nORiYB/0LoHeFOTbVtYBk7zwy/RGcs/Pwzi3COZtHZnAj8b6Pw93fgIf/G6ZaIH0zcOS1eUvW1OD1ZDNJBejBxcxhZwVDoWohUspWfEibqD69FnBpjYpMMn1jB9lEGnWNUEmbCIFCh5q3eQDuZUi2wsguYtf+iPGhX+Th4HczMbiGeO9yXK0HklaQ+dS1yKTe+P0ryAzkkzhTSvxsMalzS3DOLLL9HfbXXNv+JXjdETi3DC5WkT2zgdHTVYye+QjZe78M6Xq7kWKgIhXpVoFvdVnMc4m5jonAKZ9Q2M9mfLPSMZNNkHaiyHQN657ZfrLWibpodldbGaUIn0o8CYA2amgrKz4DQGzKxONMbwAgtRXSrJvRoiO7tkKFEe6ZTTWN3hNIBKYA4eoPYVll/RNmB4yslYKxEbMpZOrazzBxMY/xM2LK56B/SQCOubSLoE+OpsKYMtnKLEgGnoPBSHBtgUHREIFQQFF0ZAX+wDK8C4twLi4ge24h7uCSQJLmQW8xfs8asn1byJ79CM7lz+Ld/XUY/7pNy3HugqJ2GqnZYi3U7eFnihQnbAVDL+0bU0m5X9o2IasJSwFJnR5eR+CwHWjb2ChM9cCD1+H2b5C69hmmL36IyaF1TA+VkDxbQuZMAU7vIrPKLq3VmFps1rsAzhZBr8zHMpz+YgMUZyAXd2AZDEg4LXjUP6Zv1D9PQQOLyZ6O4A5GyAxFSFwoIXrxk2Tu/DokjoP/wFTz1opeJ4UpF6qa0Yp6ahMgU+ZUyHgrxxsmnFENto8MCtRZYehbroFsrVC6BBZN+L2ZdFXp0W8FQGZpCv1+KOGsWpR61IYuD5BDZMwsHSB//y1jLR4xm904U2aDeFIqqHoPRvYyeePT3DuziszZlTCwdI60BAYWghzEnnLoqYRe2d5LrcMop3FwCd5gLt5AkSEGVsLgUhhcjndmCdmhRTiXFsOlfLhQCufLYKDISGLNEDunl5DoXs5EVyljp19kcvAfkrr6y3D/yza12u8B9xw4lyGj4toPQflRiRTE3EfgERNkpU60h7N8Ny17jEImjukXTS5pdZ9209I+h8mzkFQm9p/DzX9n0vhj/a8x1VNMtH8B6XMRGFK4VH2QB2dXwJnnyPZFSPdE8Pol2eXbCSRltu0rAFH/SnMsZ2z/mD5RvzwtDS6BcxHivRHGTkeIDr0AD38dsifBVdjcagWlnaeUca6ijYGbq02BTJhTfaF+MTRr7/JQwDwGFplockQUPAoA8tj3gVkq4ATHRd5G/s9i7/DsJ7UhGnU3eh8au0Jq8LL6y3L/W9+H0k+XD7SIjb9oNyYb01fJRy+TxpeZoH23tVdf7AqJe/uYvvxLJBXbVkfPhfqXW80gp3Qgx4R8zaCfmR8AYyXeQB7uQBHuQImlwQLcMyvxzi7EPbuQZJ9MkGI4VwEXVsOFcjhTjNujXKXlMFiC119CuqeIeHehSWNI9pfinFtL8uJ2Jm/8LcZv/xDT93+S9Oj/B9NfhMROSJ+ATD8412xCaHYEU9hPrcwlkXcrAFcbJPeTnfxjEg9+hanhzzJ57buZurKVyaFyEufzyJ5bhX9mFQzkQ48icuUm58wsk+4shDOFcGkV/pUcspeso5wxgQgFLpbbYEWnzivARPsG50PQTwwoaDEHOpODfz5CvC+HidOvkLn4CzDRaKteah2OapYZ5ah6AFpeoK0lFPtXHyjJUoEGmUWWFMOTESVBrKkEV6onVABv5T39Lf4LNUjY6jOT8mN5O9Aguo2QW5+21U1Ir4tC2M4Cy+z8ovAm1M7GXPi5btpcR4FRXctmz5pGE4jZuO21dJLM5D0y9w8x1vd9JAfXkRkswT2z3A7aGZlHOVYTDIpJl+KdEc0C0oDMseXQK6koiRh5pDXOKtS43IJDgAgoa9o88zvuufkGIJwXcFS1cRVRrSfpzCGl+ZUzBTBURqYnD29A70vgSjFcWW4kt8yK6b4Ik5dzGL2Sz/iVtUxce4mpqx8nevUHiV/5KWKXfxnvzn/Bu/0l3Nt/gnvrT8ne/jMyt//MhDWzw3/M9LXfYPL6zzNx7UcYu/JJRi5t4eHFlYwMqdxAhNGBCNGBiIkOcUFh1FwYkLbcAF3roXuNiQhmOpeQ6FtI9sIS3GuL8a9H4FLE9ouWLGi+qUuRw1zokwZdaISE6degj42Qmq3N1e/qx8GVVgsP6rdX2n7vk+ZaTrwvzwQI0hc/B7e/DmMXIWHNJpM5bgAi01xb1N0K9pdX1oXdnFOTnOH+KWFrLRWBJvSPQ/4OzKgQLGL1t5LhQZkzOkfFq81LR+k1l1bnhNz+1l8L7CZdOryp2a0On/23uQd7YzN3Hn4fPokBXPgAw8Qe/jfunP8h7g++SOJSMdmhYGCv5sKFIvzBfOM0Z8+tIHt+Kd65pXBGJlng0A/KtJBJtQDOzTetf24R/tml+GeXPUbezN9Lsccstt+fWYEvmvl+1nmPfW7Ps781D//8PJyh+WSHFpAdWkxmaBmZ83lkzhaTOVNBZnAdqcGNpAY3kxrcSmpgu6HkYNhuJXlmM/Gz60meW0PyfCmpoVVkhhaTvTCf7IUIzoUI3lDESGr7fIvs8+q5B6VRVoHpg2Wmb7xzi3HOL8I7vwDf9IeOXwyDmlQNyPTXYnO8NJP61j+72PbhwCIQnVEfLsYZWk7qfB6pc6U4Z8vgrLSVwsjSTCXcaf0oYxd/Bab2WG2onXy1D6MsoWCLd+tiaApAQQlpEjnRllcfTarKyVbQSK2lGR6a4WvDYI/+C3krbB99M4OcZ5wHeeyK78Mfk2TSzTy8818YufpZoldfJHrWJpxxYQWcL8Y7U0j2bKFhnNTQMpzzGkgNYuC3nBWTv090TqCcZ+xw2eJzITGxf07MPFeyjDyXPpDAyJ7LI3s23wgII2gGF4EijGd1P4vInFtC4twK4mfzyZ4rsZpUWqx/vqm1Nn7mXzI9/HVIdmH3qlG6keVPhaslLi1ANBckTaKoXbBNYCBfv5WM920OEEmSGzjJg2Qe/g7pW59lerCS6e75NtJyvgD3bBHOuRLSQ/lkLyzHHVpow8NnckB0LgfOv1+ke3nOzB7PrdW5CnfrOnOlZ3j2czJp7YSiWbszKA2x/LE+VUg4O5hDdnAhvo6/WAgX8412muqvxB/5HfyYIlZK9VAoOmXTxGUkBJFNa5/IDxE47D6Nssol+L/Vr29zgMjXUSRMdmsjjH2BzOVPm5VhSUWmhlbinCsykit7vojs0ErcC2IoSevn4OxCOCfGegYmeaZz9du6HzH6XCiYC5ozOJ7x2c/Jj5A2CEAyWIF7Lh/3/DLcoRz8oQX4Z+bBWaslvbPPkT6zgtT5CjJXXiB54zPgVQPnbA6UP24mVJ1k1gaRAh9aGiPc0MZuSRGA4/8HhHybA0TLSpQHFofMXRvWfPgfyVz4W8QHC3AuLsW5UIBzvtSQO7QKLs7DOqvz4Px8OL8ILryPJI32rHRhIcyZnuHZBUwBQNGsc4vh/AqcoWIyFwpxLy6Ciza3yrSXrB80PbiUiaEPkb3972HyEDAUVBEZA2cSJxkjGU+YZd2O6xt/QuB45HAHfu3b+g3ffH3ybQ0Q9VEyyBq3AbQHkKiD4Z8mfqGM9JX5ZC6uMoMmkLhDeXbQNHBy5gUQMef7CpBFAUDm2M4ZGCGongEgQ4H/pPki9eeF+TgXVpG5mGcBoiiY+vpqBK5F8C+tJHbhg8Su/zKMd9mJUi3ZVl6eF8XNREmnEqb2bzqbQbvnWsfbAsR6JIFtFcaDvsVa5NseIJkw3V7uiJYxpgfgweeJXqkgcT1C5tJynKFC3POleOdnA2TeI8n9zEwWMtvTtrOYc2ixBerTtu/bvetZA2AYcFgweJciuJfmmwwDo60FjqsREzb2br8Gd34fJs7a1BpZyCYY5Zg9610nY0ubellcX4ZVOF0QtoH20DlyQtT+NUCerDbVN4pwKK0lE7VFOUwh5YdfYPL6ahK3IqQvLzKawztXDAKIBtVoEJk2YsqnZepv9vHSHIvnRkbzfbPv52muJ60R9Kf69DGah3dpHt61CPGLS5m8uJXM8Ocg3mUHLVwVocltOeOhoDM8H4ZsBQyFtNTOWkH51wB5MihmfxMCRGsjTDxQc5XOBKS/xtjtSkavRshcXYB3cSWcL7STZBpEqf4LS/AvrMC/mIN/acH7RIvs719cgj8n0r0vep/uXX22CG4sw72cg2f8uQVwcQlcXoh/KULsfITJC0VMX/t7ZLQvYKzT1uCSz+hlTI0CZTYrSjV7rtgu5HoLOKQuNOAijXdIsxniW/D+29zEUjzcIe27NpVewsZVbtJeRu+s5+H1COnr8+CSIlrSHsvh0jy4PM/Yw97lVfiXF5sB1aC+L3Rpsb2HS0ufukU5YJdz3p/7vrwQ70oO8cs5pK6thGv5cKUALmqCdjnOhRyiQ2vI3v8XpB9+hezEOUgZO9gWkvAn8bLKywusgEDGWQyEk8WB5ngrOEKQqP0Wv77NAaKYuGZYlbvl4GeVyKe850OM3N3G6M0QIDKllsIFMVMErszDubyK7JU8vCuL8a/Mf59oocl9EqMJqE/bKm/Kv6JrPAvN/dmz1+YzdT1CbHgp7s0KuFJhtfKFUvwrH8e9qYrpbZAew/fs/IWiUWaxljuFrw2LvgEgdgnFjGllEfNIY4RFML7FwAgv/20NEClnVTPMKn6ueirelF0qljnF6L0PMHYrggaRSznW11CI93IE/6qK2q8kbQAiJps7kzzrud5VK4kFjqemq88CDJ37bM+tvo3fWcz0neVMX80jeqGY5MX1cOP7YOSLEDsNWWUdWjNK/qIAYUBiFnBoCfAjDTLznQ1JfqPfEVhZOk6LpRT+tcgJ2fmb336bA8TD99K4qupoikQoy1MiqZ+Je59i4lYOzjXZxEpHj1jtEURU0tdXkL6+yiTmce053he6ugD/2iLcOZLO5apowbPRHJ9ffZu6XcbEjXxGrkcYv1lK+s6/gIk3ID5uI1WBby1RpjWAqqWmajZmnLQc4zGAyDmXnSxnUl58wP86XuCYmVlXzq6WI2vlvQb8W/f69gaIOtBRRpvWWA/bNdYSKpnrTN39DNO3i3CursLY6gLIFRuPd29ESN1YQuLmCsOc7ws4rj2Hb2gB7vUFFiRzaN8vcKjP3KsrSF5ea9Lqo3eex5n6p5B5E3zt92gDUI7WcHguGT9lSNEqJSEaVaLIVYAVtdb8CjPDNQEcHKcvtRRmJjdLK/VjM6b1tw4ez1zV5Ft5a+/h2gKIBI4q0JlU6LvBwDwgevcnid3egHe1CC4vseBQTP5GBO9WhMRwDonbS3FvLAQ58u8LzYfr8/FuiBbOoV0I156Rruse5vj8V3Nxr+yAG/8ERv4Akk1mrYakuoYl5vlmWWzKyZr14mZfu0BDSFPITJL8F+m91gLNFMkzi5ZmAWSWtlFJpYTZy16ZvZKI37rXt78Gyfi2IIJZTKNUaYFmgqm7v8T07VfIXiuxTBTM5gog7q0IyeH5hrybFjT6/BGJYcQ4Ak9Ilpm5MW/WcW85R98F5z1i+Hl4TzxH54fnBNc357/H999wXd3bbGafHwBoCVxdakkmp55p9rla+xHchwVreB2dn2OvoWMM5cD1HNRv2WtFMPxD8FD+Rp9d3aiSs6aMaYqEaoR4abP2/tEiJIFAzrnW1atVnlWoPULzSu1jDsfbahBpkb82sd5ROEj2hLULg8VVEiiph7jRL5Gd+H4SwyW4dyJwOwK3xAg5cHMZ7vB8nLsR0Hez6XYE//ZC/FvLcG8tnyH97d/KgdvPwXDE0h0da8m9GcG58RzpazmkruaQuLqI+JUFZG8vIDs8D2c4gnMngjdsSeeZ+7n5HNycPze6FcG/E8G9Z1u9N/cWXts8rwCRC0ZQlMD1fNBz6BkeO34+7u0cnGHRQtzh5+zz3iiAaysMOPxrEdwruTg38snciTA9vB7YbXaHxZ0GN2N3AJgpMiGtELzMG9lMoc7Qd/Z7e0w4saHv9X7Wef+nvXMNte266vg65+xzzj7Pe+7Nuff03pt3G1objG1ME7W9IpVQCTVSqpZUKkZMiSik2pp+CKgfzAcpVBFbNdoiFB/UQCBSIaCxRaGlEUKj1UaTe85+v9+P9V4/+c+51r773ua2+ZDmZF+yYbDW2WudNedce/zHGHOOMcfQDenqlT21pSNMVpP5e7P/eQ2Pi61BjLpo2fyFenN6twKI1yAYfgGv+wCj8gFBykAGJIe7cLhHUlw2zDVj9pTpzffFVcssxQ3C4gaRoXUiAUf/V7IMaRhMIBOVVgxDhUeb+IfbeEebuEdr+KVlw0xBeQ4gApWYV9pLx1ekZSjM0woUrqDisgG/gB6lNGN68/xlOBRAduHidRYcR1skxRU79jmA6DuBIyht4JUFEgsYLp6Bl09YgBw6hC/t4R+ewa+t06v+KPCNWVraLD3t/PE15NVjedSCA0RBbG0SJfkUQLIZn9cmGn+JsP8rDCoHeLWUoSVZ5wEiUBxtw+EpC5qjbZLChmEgaZ2M6SSZDSikPTIm1bmeV1mGSg7Ka1DKQ3ELSlvEpTxROWe0lJ5zuXRfsYx7tGo1wByDZ22a9tUHUUm0bLSeQJqRwBsW9ggLu/Z6phHNuASOdduOjuqrKAW3GY/uS7/XM/W8oLx+OUAO94y3XCBOjhyiQwmNMwT1c4waHzTlyuYBceX5sXD1a9jowgNEkaAJw0srI9IickxNvkwyfJhh5Rx+PZXyxSU4OgFHJ43Ej8s5OHwLXLzJHgsnoZg31y4zu8pLICqtXKJiDor6O2OyHJRWobgOZdEqSWWZuOIQV+fMOPWhoBCNbShsEpdXCGvWTAqrVx6XiCpLhFUdVwirK5cdo3KeqLBvSIBUW7N+q39qR6Q2pS10vWr7Y8ZeEqgtaOLSGmF5E7+Sx6+uEVbWDMiTw004WjX3xUUHX1TZJ27eRdB+xGQ3VMK7q9FryKvH8qhrACADU/4sVLmRTIOoypVqjkw/ybBy/rsBUjhBXF5CTBEfnic+vIm4cNL8PQNCYQcO9y1wdCxsg5hODJWZJjqXmXSZqSTQrBmQJBULkkQAEXOKStI8q1DYgKNdKJwkKl5HXLiOqHiSuHiCqLRDLO90OY8YWeBQfzXXENiiWnrUuUBS2jb3azy2jysWFCnzZyDIwGPGXs4ZcGZjEcAMQKpr+FVpPgFkjeRIgmDJ9F3j8CoOXv0MtD8Cg88DxauCQ6BZ9M+CA0TqYmQAIoetqvVaM0t5tP4VvN9nVLmZoGElp2XOXSjuoh87ruaIi6dJCgck5S0SmUoymaQBCqfg6ACOzkJhH4oblrkFDgMQSdVV4osOiZaOj7R8rIntBklph6SyTVzbJK6vkEiDZSSwGI0iIOVtO4XTcHTatqN2i3tQ3IGS2pQ2kgknU+6SFphpA2mfWo64sk5S3ki119y92f9Iu5W27DjLW8QpeM1zypqPbRFVdghqqwS1HFFV4F414zL3qJ26w7Tu4LbOQ+dRGP9zmsl/0WFw9f4vPEC0dq4sF0EYm4TEBiDBANxvgv8ZhtVb8RsOSU2MLem9C5LQ6Q8e1WQGrVqGETBKYsydOQYVYFKmFrPpXPMMAefoPMHhJkEhT1DcJSjvE1UPiOpvIWyeIWrv4TVX8VoOQdtS3HKImw5JMwWNeZ6kdEoFmWnSMK90FHA1n0iPpRxx3TECQMxrxqL5lsYqyjSXQCYAHp0nKZwnKe4bQOkdWNBdDSA5Qk329ZyWQ9R0GDUdJu3boPtn4B7aBGxX56+Fv7LgALGhCcqDpGTP0iIGICai97/A/3OGldssQIzUFhMKAFsWIA2HSFRPtUl5awYgM58QIPR/lzGbJvGnSApniUoHTKs7TGu7TGvXM629E7f2Ptz6B/DqP4vfuJ9h6f0My+9lXHkX49oPMandilu/Aa9+lrB+ykr8kky3V0tWc2VzHb+2wbSxjltfNeOUttSYYgkFM/fSsvSOAXRydKMBiLRmXNkgrl7SNJdpkPqy1SBVh1CTeD2n5eA3Hfoth3H73baisetjizIuPA6uOoCFB4h2nYmU7yJK4nQeotpuSjL2JOPq7YQtB2RmVVahvA2VzRlAdM1I9NoqSXUTypv2PgFDjNFO/7eYJzw8QVg4RVw5CXrZgg4AAAtoSURBVO1NktEq3bbDoJ/HG78L/Acg/AxET0P0gu1DUAXvJZh+E8ZfgcET0H2cpPVJks4DJK0fgc710DpH3NwnrO/h17bwqmu41WW8umx+B6/x3TSt5Um6dzOu30W3dJpBZQWv48DQgZEDfS3drpKUdqFyGqpnoLZPXN4lKGziyjko8NeXobpDUjtB1FgjauZIGjk7fr23ngNdh2HNodtycMf3wvg/bKzVnMviqly2wBcWHCByKcndZGM7zTZNpThX2Luv3K1fYVK7IwWImECTZwEkTyIp23TMtVAmT32JpLYC1ZRpxDiipv7OQ/mAuHQ9fuU00/oWk7ZDv+vQ7p+mN76bIHwQ+CPgqxBXLfMoM2ZGZiuEijMewvQ5m5zZ+xuYPgbex8F9CNwHYfIxkvFHiEcfJhrdz7DxfobNCwxb72XY+rHLqf4zMHiUuPfbBIMP4vVvZ9o9ybTtGLNO4Pc1udcSdG0DGinVNohKm4SFHMjUayxBfZu4sUvcXCdurUBTpPELaBlAlui0tnHHD8BEmeJTjb3AAPh+XV98gJgANoFEOkSe3DSpq+KzkmcZ1d5NIKmqH7y6DtUtqK0bE0TAkLQUGUbINI00R00T9h2oHED5RpLqzfiNc0xaJ+h3lul2HarNk/T6v8Zw9DmI/xH4lg2YNHn6bbIVw0RZaQOFsmq/ihIuKwI5Ua5ZBVkeXkEXbTkwlQTzXgTvf9KjzkWqN/J/4L4I4+fBfxaSv4LwEdz+Bbr1M3SqDoOqw7TmmFU8CQOjDVtL0MpBbQ2qcyCob84BRPdYs8ocew5xZ4lBbYtu++1Mp58CL417e1ODfD+MHd/1zDeo1V3l3FNu1kRhpAohVV3j+BvG/Ai7S9CUFM1DbRsa6ySadIrqW0SSrGIgMYWOAkhVK0L7UD5PVLkBt3aGcWufQfeAweAWBoMfptv7RfzpU/iT75AombRSYipUNTH1XAh8peyPbck1PyJRhgl5+udJ4eAaQLZMHdnVOFVDMqtyuq65laK/rzjOIgdUU8/klnoK3MeYdO6jU7uJTjXHpOnga5wyFWe0DNIS+jsDQiNP3Ngmaq0TtZcu3avrPYewk6PfOE2v89P43mchTOv4Lf5K7vdk4IXWIBlAxDeKH1X5MlOlT3HRRv0/z6R+D1FvGdrr1sSo70Azbxggbmsyu2fImFIZQBrSNntQvc7Y5V4jz6jt0Ovs0u/dyWT0q0STJ0imXzf17xJhMiviog2NgUK8lSAwxo083GiKH3oEQWTvU6oi5eFWOq8AVB5bKf7NMbT15ZXuX3Xm9RyVZ1ZMplFEc0cpJBNBYMKYhKgaRP8O7ufwex9l1Lwdt3OCsOsQSYvOAJKedx3Ivm+tkbS2iNt54s6y/V7XDUBWCDp5hs23Mug+SBT+A9A3+zNM+9+TxRb74jUEEC33XgmQbzNt/ARxfwU6eWhuQmPbAqTjkHQEkG2o71oTbAYQzTs2jV0uDeO39ph0rmc6uIA3fgS8v4egOB93Zwq8yKpTni5PlY5izYtk9qkYp6JOxzY1v8K2Vc5R6wjTtE55Visv3RCUKhS7IGeUi4LzsgC9YC7LoA0X97VXQgGwZhVPCRFeAO8JGD5E3LsLBmegl7NMn40xM7kEGoGklSNpbbwyQDrrBJ0NRq07mPQfI4m+ZnZwqp/XuALJsrsvJsqNBpltotEOs4HdU6BfTltEoheZNt9HPJREzENrywKktW5XZnoOSVvmRg5km18pYVs5osZJovZ7oKeUNV8A7zkIW2memjTwVB2RRSdGjxLCWKtq6o9KgGXFgurEtEzcWKLiLaaSZEzsTYi9MYk/MWSrsGpvvW/J7ItIH64G5klGZTRmjGtSH6kP1nyTSvoOeE9C52EY/DgMdu2YBRBjQq5BffWSpmivQnuDpLNB0l0xq1ZaudJ7STqb+J0dxq27mfY/C8l/ktAzuzmUSf1a/iy+BplJ3WzDjSoHmdJUEB/Rb96HPxRzbEB7DVoyr1ZIeg7RwCHpWk0ibWKo6xB3HWNSuK0bGFcvEDQ/AcOnIaxdmj+oqJFKHqkSkeFKa+jZdTUFUSqZRB8vruFTMRSmZecS7Z8XghPXFoFRIRjZW7Fr615okm9SqgagIhmKo8lIdpUSganZOGIYdEyZumy/t9EiMi81B4vK0Pw76PwOcfcCQec0QTN1LMr7LoAIBKIUIFq+pnNJgFjBsYHbyzPs3sN08NeQaGGhk9by07iv3c9CA0RAMOE+EmLSGjqa8lppYQma+NGniZO7jEc7C/kwXmzXIZSvYOLA2B4j18FzHSbuHsPBXXRbvwxodep/LcOKKWecqMYyu0bnGYlZdG73O1hO1n0Z6SGXwDQ7NzPwbD/qFUcB/pXIlAHQ8oTmX5bsttW0CfVV5L4Mk7/EG/wS7vBtuON1omkOvHW8wSphb90KjqY07J4xtYKuJubWl8JwnUnPYTB8D/CMWYyIgxrE3VQ4vAmQN+wbmAEkE+RGoqcOQwZMkj8k4l6C3qaVlNmk1F3DFUCCJZg6uAP5Ndbo925hNLmPIPhd4lCZxwvWrMmePzO89YVE9fFJUJk3mulYcNgkBjo3XbQYtQARSLxvEbt/QeB+FHf6TsajLYajJcbjNYLhBnRWQaZnW9p225il8UDaJQ+DTaaDJUbjnySOv27BqoDQWJrw+Mb/ejDlYmuQbJIoZsgY+DKAjHD5Y+B+kuGe9TDL6dVeIh6fYNhdI/KW8CcO49Eqo94dTFufhsHTELycMoCYQMtOWWNiCGkDgUNHXTiejwWIACESWNJIm6yrpm/qZ5r1JX4egi8RTn7DLFO3uuuM/FWCqQMCgzzm/TUQYCZ5GG9D6xR0zuIODphMfoFQBUfN+5apl6YsOZ7hvy6tLjRAZHWIKYz5MbNabLoY41tgyjT+PAk/TzLcTwGi5cwNgv4NdJtnGfZPMRnfSOz/FISPgvcv4CoaODVPDP8LfQKD3OFyjeuo744PHJY7sjiCOXCkczKZWppIJ5RT56Wck/JdfBvcv8V1H2Ls3s3QO4fnrs8BxCEZrRBNNmC8B63T0LqFYHAn/vS3CIKL1m+TCST9CNfw55oAiPmNMvEp71qWewmPSfBF4vhjBL2zYPwh20T1A/zunXRq9zDs30sw+TgEXwSesxNQ1S9XbXIpjxkOBAyFr6RfqtHjxkfaB5mZOrUaRWDRUvDYACSmSmKqwk7AV7HxLgT/DclTwOOMph/And5KMsgZEzToOfgDB3+cIx5uQ/skNG8j6X+I2PtT/KBpMi3JspL/xzT8JkDemG9ATJFVHJrZF2ZZNPVOyzoPv0wS/Tpe+3oSrWI194kb74DRzzHuChh/AsE/QfCSRYRQEcuZEZo0v+a5BggyVQQO1dhOwaHvdX5cH7UtzWnUqLqiRGpKhdMzWUOSNHtIGA8J/AmhOzXLyoQaR9XsJ/emjxO5H4bRLdBfwu87TAcOk5FDMNIqV564+TYYPAzBk3hB2zgtzWt+EyDH9cu/unYlMTVFNdktLFpsPIYWgQzTyAR5BpJH8btvNev5tG+G3gWIPwHTL0DUtNaTvG3hBCLtb1fohkgJ6dKJuJ4vEijm6dV19Qdzl/ohJpWWM1pEDskyCSUSswwbGLdJpKGFIUE0IIx7JhvlDPj+C2ZbANMPwehGgvEy3sRhqlU+1yHpO8Stm2D0KYifwY2qxtgMtYqctvuDGdwb46kLbmLNAyQtMGEcaRlA9JL/Dfg9wt7boasVmnfA+D7gD4BnLf9rSiFGk3POVDxSphTFVknKyqxKJ+kCXSaxj1t7aGjqg6ZGM0kuR+nLJLyUAiSe1d2QqIgZEtEhSnzj+Y+MM1UhKl8F/zfBvYPE3cL3HfzQIQwdkoEins/B+DHga0ySkpmeyRUj18yxatDXAUP/Dzulf7mPSc8LAAAAAElFTkSuQmCC +``` + +### `annotation` + +NavLink 自定义资源的 Kubernetes 注释。 + +### `label` + +NavLink 自定义资源的 Kubernetes 标签。 + +### `sideLabel` + +出现在左侧导航栏中的标签。 + +### `target` + +设置链接的锚标记 (``) 的目标属性。该属性（取决于浏览器）确定它是在新窗口中打开还是在当前选项卡中打开。 + +默认值为 `_self`，即在当前选项卡上打开链接。要在新窗口或选项卡中打开链接，请将目标设置为 `_blank`。 + +有关目标属性的详细信息，请参阅[此页面](https://www.w3schools.com/tags/att_a_target.asp)。 + +### `toService` + +有五个字段用于创建如下所示的 URL：`https:///k8s/clusters//k8s/namespace//service/: :/proxy/` + +例如，Monitoring 服务的链接可以这样设置： + +- 名称：`rancher-monitoring-grafana` +- 命名空间：`cattle-monitoring-system` +- 路径：`proxy/?orgId=1` +- 端口：`"80"` +- Scheme：`http` + +需要提供 `toService` 或 `toURL` 指令中的一个。 + +### `toUrl` + +可以是任何链接，甚至可以是集群外部的链接。 + +需要提供 `toService` 或 `toURL` 指令中的一个。 + +## 链接示例 + +### `toUrl` 的链接示例 + +以下 NavLink YAML 显示了将 NavLink 配置到 Grafana 仪表板的示例： + +```yaml +apiVersion: ui.cattle.io/v1 +kind: NavLink +metadata: + name: grafana +spec: + group: "Monitoring Dashboards" + toURL: https:///api/v1/namespaces/cattle-monitoring-system/services/http:rancher-monitoring-grafana:80/proxy/?orgId=1 +``` + +添加上述 YAML 会创建 Grafana 的链接，如以下截图所示： + +![Grafana 链接截图](/img/example-grafana-link.png) + +### `toService` 的链接示例 + +以下 YAML 显示了用于链接目标的 `toService` 示例： + +```yaml +apiVersion: ui.cattle.io/v1 +kind: NavLink +metadata: + annotations: + key: annotation + labels: + key: label + name: navlinkname +spec: + description: This is a description field # Optional. + group: "group1" # 可选。如果未提供，则显示为独立链接。 + iconSrc: data:image/jpeg;base64,[icon source string is clipped for brevity] + label: This is a label # 可选。 + sideLabel: A side label. # 可选。 + target: _blank # 可选。_blank 表示在新选项卡或窗口中打开链接。 + toService: # 需要提供 toService 或 #toUrl。 + name: rancher-monitoring-grafana + namespace: cattle-monitoring-system + path: proxy/?orgId=1 + port: "80" + scheme: http +``` + +添加上面的 `toService` 参数会创建 Grafana 的链接，如以下截图所示： + +![Grafana 链接截图](/img/example-service-link.png) + diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/global-default-private-registry.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/global-default-private-registry.md new file mode 100644 index 00000000000..bb7a5210a58 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/global-default-private-registry.md @@ -0,0 +1,57 @@ +--- +title: 配置全局默认私有镜像仓库 +--- + +:::note +本页介绍了安装 Rancher 后如何从 Rancher UI 配置全局默认私有镜像仓库。 + +有关如何在 Rancher 安装期间设置私有镜像仓库的说明，请参阅[离线安装指南](../../../getting-started/installation-and-upgrade/other-installation-methods/air-gapped-helm-cli-install/air-gapped-helm-cli-install.md)。 + +::: + +私有镜像仓库是集群中私有、一致且集中的容器镜像源。你可以使用私有容器镜像仓库，在组织内共享自定义基础镜像。 + +在 Rancher 中设置私有镜像仓库主要有两种方式： + +* 通过全局视图中的 **Settings** 选项卡设置全局默认镜像仓库。 +* 在集群级别设置下的高级选项中设置私有镜像仓库。 + +全局默认镜像仓库适用于离线环境，可用于不需要凭证的镜像仓库。而集群级私有镜像仓库用于需要凭证的私有镜像仓库。 + +## 将不需要凭证的私有镜像仓库设置为默认镜像仓库 + +1. 登录 Rancher 并配置默认管理员密码。 +1. 选择 **☰ > 全局设置**。 +1. 转到 `system-default-registry` 并选择 **⋮ > 编辑设置**。 +1. 输入你镜像仓库的主机名和端口（例如 `registry.yourdomain.com:port`）。不要在文本前加上 `http://` 或 `https://`。 + +**结果**：Rancher 会从你的私有镜像仓库中拉取系统镜像。 + +### 带 RKE2 下游集群的命名空间私有镜像仓库 + +默认情况下，大多数私有镜像仓库应该能与 RKE2 下游集群一起工作。 + +但是，如果你尝试设置 URL 格式为 `website/subdomain:portnumber` 的命名空间私有镜像仓库，则需要执行额外的步骤： + +1. 选择 **☰ > 集群管理**。 +1. 在列表中找到 RKE2 集群，然后点击 **⋮ > 编辑配置**。 +1. 从**集群配置**菜单中，选择**镜像仓库**。 +1. 在**镜像仓库**中，选择**配置高级 Containerd Mirror 和仓库认证选项**选项。 +1. 在 **Mirrors** 下的文本字段中，输入**镜像仓库主机名**和 **Mirror 端点**。 +1. 单击**保存**。 +1. 根据需要对每个下游 RKE2 集群重复操作。 + +## 创建集群时配置使用凭证的私有镜像仓库 + +无法为每个 Rancher 配置的集群全局设置具有授权认证的私有镜像仓库。因此，如果你希望 Rancher 配置的集群从使用凭证的私有镜像仓库中拉取镜像，则每次创建新集群时都必须通过高级集群选项传递镜像仓库凭证。 + +由于创建集群后无法配置私有镜像仓库，因此你需要在初始集群设置期间执行这些步骤。 + +1. 选择 **☰ > 集群管理**。 +1. 在**集群**页面上，单击**创建**。 +1. 选择集群类型。 +1. 在**集群配置**中，转到**镜像仓库**选项卡，然后选择**为 Rancher 从私有镜像仓库中拉取镜像**。 +1. 输入镜像仓库主机名和凭证。 +1. 单击**创建**。 + +**结果**：新集群将从私有镜像仓库中拉取镜像。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/cluster-and-project-roles.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/cluster-and-project-roles.md new file mode 100644 index 00000000000..8f293098c0c --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/cluster-and-project-roles.md @@ -0,0 +1,236 @@ +--- +title: 集群和项目角色 +--- + +集群和项目角色定义集群或项目内的用户授权。 + +要管理这些角色： + +1. 单击 **☰ > 用户 & 认证**。 +1. 在左侧导航栏中，单击**角色**并转到**集群**或**项目或命名空间**选项卡。 + +## 成员资格和角色分配 + +非管理用户可以访问的项目和集群由 _成员资格_ 决定。成员资格是根据该集群或项目中分配的角色而有权访问特定集群或项目的用户列表。每个集群和项目都包含一个选项卡，具有适当权限的用户可以使用该选项卡来管理成员资格。 + +创建集群或项目时，Rancher 会自动将创建者分配为`所有者`。分配了`所有者`角色的用户可以在集群或项目中给其他用户分配角色。 + +:::note + +默认情况下，非管理员用户无法访问任何现有项目/集群。具有适当权限的用户（通常是所有者）必须显式分配项目和集群成员资格。 + +::: + +## 集群角色 + +_集群角色_ 是你可以分配给用户的角色，以授予他们对集群的访问权限。集群的两个主要角色分别是`所有者`和`成员`。 + +- **集群所有者：** + + 可以完全控制集群及其中的所有资源。 + +- **集群成员：** + + 可以查看大多数集群级别的资源并创建新项目。 + +### 自定义集群角色 + +Rancher 支持将 _自定义集群角色_ 分配给普通用户，而不是典型的`所有者`或`成员`角色。这些角色可以是内置的自定义集群角色，也可以是 Rancher 管理员定义的角色。这些角色便于为集群内的普通用户定义更受限或特定的访问权限。有关内置自定义集群角色的列表，请参阅下表。 + +### 集群角色参考 + +下表列出了可用的内置自定义集群角色，以及默认的集群级别角色`集群所有者`和`集群成员`是否包含该权限： + +| 内置集群角色 | 所有者 | 成员 | +| ---------------------------------- | ------------- | --------------------------------- | +| 创建项目 | ✓ | ✓ | +| 管理集群备份             | ✓ | | +| 管理集群应用商店 | ✓ | | +| 管理集群成员 | ✓ | | +| 管理节点[（见下表）](#管理节点权限) | ✓ | | +| 管理存储 | ✓ | | +| 查看所有项目 | ✓ | | +| 查看集群应用商店 | ✓ | ✓ | +| 查看集群成员 | ✓ | ✓ | +| 查看节点 | ✓ | ✓ | + +### 管理节点权限 + +下表列出了 RKE 和 RKE2 中`管理节点`角色可用的权限： + +| 管理节点权限 | RKE | RKE2 | +|-----------------------------|-------- |--------- | +| SSH 访问 | ✓ | ✓ | +| 删除节点 | ✓ | ✓ | +| 集群的垂直扩缩容 | ✓ | * | +\***在 RKE2 中，你必须拥有编辑集群的权限才能对集群进行垂直扩缩容。** +
+ +如果需要了解各个集群角色如何访问 Kubernetes 资源，在 Rancher UI 中找到这些角色： + +1. 在左上角，单击 **☰ > 用户 & 认证**。 +1. 在左侧导航栏中，单击**角色**。 +1. 单击**集群**选项卡。 +1. 单击角色的名称。表格会显示角色授权的所有操作和资源。 + +:::note + +在查看 Rancher 创建的默认角色关联的资源时，如果在一行上有多个 Kubernetes API 资源，则该资源将带有 `(Custom)` 标识。这不代表这个资源是自定义资源，而只是表明多个 Kubernetes API 资源作为一个资源。 + +::: + +## 为集群成员提供自定义集群角色 + +在管理员[设置自定义集群角色后](custom-roles.md)，集群所有者和管理员可以将这些角色分配给集群成员。 + +要将自定义角色分配给新的集群成员，你可以使用 Rancher UI。要修改现有成员的权限，你需要使用 Rancher API 视图。 + +要将角色分配给新的集群成员： + + + + +1. 点击 **☰ > 集群管理**。 +1. 转到要将角色分配给成员的集群，然后单击 **Explore**。 +1. 单击**集群成员**。 +1. 单击**添加**。 +1. 在**集群权限**中，选择要分配给成员的自定义集群角色。 +1. 单击**创建**。 + + + + +1. 点击 **☰ > 集群管理**。 +1. 转到要将角色分配给成员的集群，然后单击 **Explore**。 +1. 点击**集群 > 集群成员**。 +1. 单击**添加**。 +1. 在**集群权限**中，选择要分配给成员的自定义集群角色。 +1. 单击**创建**。 + + + + +**结果**：成员具有所分配的角色。 + +要将自定义角色分配给现有集群成员： + +1. 单击 **☰ > 用户 & 认证**。 +1. 找到要分配角色的成员。单击 **⋮ > 编辑配置**。 +1. 如果你添加了自定义角色，它们将显示在**自定义**中。选择要分配给成员的角色。 +1. 单击**保存**。 + +**结果**：成员具有所分配的角色。 + +## 项目角色 + +_项目角色_ 是用于授予用户访问项目权限的角色。主要的项目角色分别是`所有者`、`成员`和`只读`。 + +- **项目所有者：** + + 可以完全控制项目及其中的所有资源。 + +- **项目成员：** + + 可以管理项目范围的资源，如命名空间和工作负载，但不能管理其他项目成员。 + +:::note + +默认情况下，Rancher 的`项目成员`角色继承自 `Kubernetes-edit` 角色，而`项目所有者`角色继承自 `Kubernetes-admin` 角色。因此，`项目成员`和`项目所有者`角色都能管理命名空间，包括创建和删除命名空间。 + +::: + +- **只读：** + + 可以查看项目中的所有内容，但不能创建、更新或删除任何内容。 + +:::danger + +如果用户分配到了项目的`所有者`或`成员`角色，用户会自动继承`命名空间创建`角色。然而，这个角色是 [Kubernetes ClusterRole](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#role-and-clusterrole)，这表示角色的范围会延展到集群中的所有项目。因此，对于显式分配到了项目`所有者`或`成员`角色的用户来说，即使只有`只读`角色，这些用户也可以在分配给他们的其他项目中创建命名空间。 + +::: + +### 自定义项目角色 + +Rancher 支持将 _自定义项目角色_ 分配给普通用户，而不是典型的`所有者`、`成员`或`只读`角色。这些角色可以是内置的自定义项目角色，也可以是 Rancher 管理员定义的角色。这些角色便于为项目内的普通用户定义更受限或特定的访问权限。有关内置自定义项目角色的列表，请参阅下表。 + +### 项目角色参考 + +下表列出了 Rancher 中可用的内置自定义项目角色，以及这些角色是否由`所有者`,`成员`或`只读`角色授予的： + +| 内置项目角色 | 所有者 | 成员 | 只读 | +| ---------------------------------- | ------------- | ----------------------------- | ------------- | +| 管理项目成员 | ✓ | | | +| 创建命名空间 | ✓ | ✓ | | +| 管理配置映射 | ✓ | ✓ | | +| 管理 Ingress | ✓ | ✓ | | +| 管理项目应用商店 | ✓ | | | +| 管理密文 | ✓ | ✓ | | +| 管理 ServiceAccount | ✓ | ✓ | | +| 管理服务 | ✓ | ✓ | | +| 管理卷 | ✓ | ✓ | | +| 管理工作负载 | ✓ | ✓ | | +| 查看密文 | ✓ | ✓ | | +| 查看配置图 | ✓ | ✓ | ✓ | +| 查看 Ingress | ✓ | ✓ | ✓ | +| 查看项目成员 | ✓ | ✓ | ✓ | +| 查看项目应用商店 | ✓ | ✓ | ✓ | +| 查看 ServiceAccount | ✓ | ✓ | ✓ | +| 查看服务 | ✓ | ✓ | ✓ | +| 查看卷 | ✓ | ✓ | ✓ | +| 查看工作负载 | ✓ | ✓ | ✓ | + +:::note 注意事项： + +- 上面列出的每个项目角色（包括`所有者`、`成员`和`只读`）均由多个规则组成，这些规则授予对各种资源的访问权限。你可以在**全局 > 安全 > 角色**页面上查看角色及其规则。 +- 在查看 Rancher 创建的默认角色关联的资源时，如果在一行上有多个 Kubernetes API 资源，则该资源将带有 `(Custom)` 标识。这不代表这个资源是自定义资源，而只是表明多个 Kubernetes API 资源作为一个资源。 +- `管理项目成员`角色允许项目所有者管理项目的所有成员，**并**授予这些成员任何项目范围的角色（不论他们是否有权访问项目资源）。单独分配此角色时要小心。 + +::: + +## 定义自定义角色 +如前所述，你可以定义自定义角色，并将这些角色用在集群或项目中。上下文字段定义了角色是否显示在集群成员页面、项目成员页面或同时显示在这两个页面。 + +定义自定义角色时，你可以授予对特定资源的访问权限，或指定自定义角色应继承的角色。自定义角色可以由特定授权和继承角色组成。所有授权都是累加的。换言之，如果你为特定资源定义更受限的授权，自定义角色继承的角色中定义的更广泛的授权**不会**被覆盖。 + +## 默认集群和项目角色 + +默认情况下，在普通用户创建新集群或项目时，他们会自动分配到所有者的角色，即[集群所有者](#集群角色)或[项目所有者](#项目角色)。但是，在某些组织中，这些角色可能会被认为有过多的管理访问权限。在这种情况下，你可以将默认角色更改为更具限制性的角色，例如一组单独的角色或一个自定义角色。 + +更改默认集群/项目角色有以下两种方法： + +- **分配自定义角色**：为你的[集群](#自定义集群角色)或[项目](#自定义项目角色)创建一个[自定义角色](custom-roles.md)，然后将自定义角色设置为默认。 + +- **分配单独的角色**：将多个[集群](#集群角色参考)/[项目](#项目角色参考)角色配置为默认角色，并分配给创建的用户。 + + 例如，你可以选择混合使用多个角色（例如`管理节点`和`管理存储`），而不是使用继承的角色（例如`集群所有者`）。 + +:::note + +- 虽然你可以[锁定](locked-roles.md)一个默认角色，但系统仍会将这个角色分配给创建集群/项目的用户。 +- 只有创建集群/项目的用户才能继承他们的角色。对于之后添加为集群/项目成员的用户，你必须显式分配角色。 + +::: + +## 为集群和项目创建者配置默认角色 + +你可以更改为创建集群或项目的用户自动创建的角色： + +1. 在左上角，单击 **☰ > 用户 & 认证**。 +1. 在左侧导航栏中，单击**角色**。 +1. 单击**集群**或**项目或命名空间**选项卡。 +1. 找到你要用作默认角色的自定义或单个角色。然后通过选择 **⋮ > 编辑配置**来编辑角色。 +1. 在**集群创建者的默认角色**或**项目创建者的默认角色**中，将角色启用为默认。 +1. 单击**保存**。 + +**结果**：默认角色已根据你的更改配置。分配给集群/项目创建者的角色会在**集群创建者的默认角色/项目创建者的默认角色**列中勾选。 + +如果要删除默认角色，请编辑权限，并在默认角色选项中选择**否**。 + +## 撤销集群成员资格 + +如果你撤销一个普通用户的集群成员资格，而且该用户已显式分配集群的集群 _和_ 项目的成员资格，该普通用户将[失去集群角色](#集群角色)但[保留项目角色](#项目角色)。换句话说，即使你已经撤销了用户访问集群和其中的节点的权限，但该普通用户仍然可以： + +- 访问他们拥有成员资格的项目。 +- 行使分配给他们的任何[单个项目角色](#项目角色参考)。 + +如果你想完全撤销用户在集群中的访问权限，请同时撤销他们的集群和项目成员资格。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/custom-roles.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/custom-roles.md new file mode 100644 index 00000000000..80d740addcc --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/custom-roles.md @@ -0,0 +1,120 @@ +--- +title: 自定义角色 +--- + +在 Rancher 中，_角色_ 决定了用户可以在集群或项目中执行哪些操作。 + +请注意，_角色_ 与 _权限_ 不同，权限决定的是你可以访问哪些集群和项目。 + +:::danger + +自定义角色可以启用权限提升。有关详细信息，请参阅[本节](#权限提升)。 + +::: + + +## 先决条件 + +要完成此页面上的任务，需要以下权限之一： + +- [管理员全局权限](global-permissions.md)。 +- 分配了[管理角色](global-permissions.md)的[自定义全局权限](global-permissions.md#自定义全局权限)。 + +## 创建自定义角色 + +虽然 Rancher 提供一组开箱即用的默认用户角色，但你还可以创建默认的自定义角色，从而在 Rancher 中为用户提供更精细的权限。 + +添加自定义角色的步骤因 Rancher 的版本而异。 + +1. 在左上角，单击 **☰ > 用户 & 认证**。 +1. 在左侧导航栏中，单击**角色**。 +1. 选择一个选项卡来确定要添加的角色的范围。这些选项卡是： + +- **全局**：仅在允许成员管理全局范围的资源时，可以分配该角色。 +- **集群**：仅在向集群添加/管理成员时，可以分配该角色。 +- **项目或命名空间**：仅在向项目或命名空间添加/管理成员时，可以分配该角色。 + +1. 根据所需要的范围，单击**创建全局角色**、**创建集群角色**或**创建项目或命名空间的角色**。 +1. 输入角色的**名称**。 +1. 可选：选择**集群创建者的默认角色/项目创建者的默认角色**选项，以将该角色分配给集群/项目创建者。使用此功能，你可以扩展或限制集群/项目创建者的默认角色。 + + > 开箱即用的**集群创建者的默认角色**和**项目创建者的默认角色**分别是`集群所有者`和`项目所有者`。 + +1. 使用**授权资源**选项将各个 [Kubernetes API 端点](https://kubernetes.io/docs/reference/)分配给角色。 + + > 在查看 Rancher 创建的默认角色关联的资源时，如果在一行上有多个 Kubernetes API 资源，则该资源将带有 `(Custom)` 标识。这不代表这个资源是自定义资源，而只是表明多个 Kubernetes API 资源作为一个资源。 + + > **资源**文本字段可以用来搜索预定义的 Kubernetes API 资源，或者为授权输入自定义资源名称。在此字段中输入资源名称后，必须从下拉列表中选择预定义或`（自定义）`资源。 + + 你还可以选择每个分配的端点可用的 cURL 方法（`Create`、`Delete`、`Get` 等）。 + +1. 使用 **Inherit from** 选项将各个 Rancher 角色分配给你的自定义角色。请注意，如果自定义角色从父角色继承，你需要先删除子角色才能删除父角色。 + +1. 单击**创建**。 + +## 创建从另一个角色继承的自定义角色 + +如果你有一组需要在 Rancher 中具有相同访问权限的用户，一种节省时间的方法是创建一个新的自定义角色，而该角色的规则都是从另一个角色（例如管理员角色）复制而来的。这样，你只需要配置现有角色和新角色之间不同的部分。 + +然后，你可以将自定义角色分配给用户或组。该角色在用户首次登录 Rancher 时生效。 + +要基于现有角色创建自定义角色： + +1. 在左上角，单击 **☰ > 用户 & 认证**。 +1. 在左侧导航栏中，单击**角色**。 +1. 单击**集群**或**项目或命名空间**选项卡。根据所需要的范围，单击**创建集群角色**或**创建项目或命名空间的角色**。请注意，只有集群角色和项目/命名空间角色可以从另一个角色继承。 +1. 输入角色的名称。 +1. 在 **Inherit From** 选项卡中，选择自定义角色需要从哪个角色继承权限。 +1. 在**授权资源**选项卡中，选择拥有自定义角色的用户要启用的 Kubernetes 资源操作。 + + > **资源**文本字段可以用来搜索预定义的 Kubernetes API 资源，或者为授权输入自定义资源名称。在此字段中输入资源名称后，必须从下拉列表中选择预定义或`（自定义）`资源。 +1. 可选：将角色设置为默认。 +1. 单击**创建**。 + +## 删除自定义角色 + +删除自定义角色时，具有此自定义角色的所有全局角色绑定（Global Role Bindings）都将被删除。 + +如果某个用户仅分配了一个自定义全局角色，而且你删除了这个角色，该用户将不能再访问 Rancher。要让用户重新获得访问权限，管理员需要编辑用户并应用新的全局权限。 + +自定义角色可以删除，但内置角色不能删除。 + +要删除自定义角色： + +1. 在左上角，单击 **☰ > 用户 & 认证**。 +1. 在左侧导航栏中，单击**角色**。 +2. 转到要删除的自定义全局角色，然后单击 **⋮ (…) > 删除**。 +3. 单击**删除**。 + +## 为组分配自定义角色 + +如果你有一组需要在 Rancher 中具有相同访问权限的用户，一种节省时间的方法是创建一个新的自定义角色。将角色分配给组时，组中的用户在首次登录 Rancher 时就会拥有配置的访问级别。 + +组中的用户登录时，他们默认获得内置的**普通用户**全局角色。他们还将获得分配给他们的组的权限。 + +如果将用户从外部身份验证系统的组中删除，用户将失去分配给该组的自定义全局角色的权限。但是，用户仍会拥有**普通用户**角色。 + +:::note 先决条件： + +只有在以下情况下，你才能将全局角色分配给组： + +* 你已设置[外部身份验证提供程序](../authentication-config/authentication-config.md#外部认证与本地认证)。 +* 外部身份验证提供程序支持[用户组](../../authentication-permissions-and-global-configuration/authentication-config/manage-users-and-groups.md)。 +* 你已使用身份验证提供程序设置了至少一个用户组。 + +::: + +要将自定义角色分配给组，请执行以下步骤： + +1. 在左上角，单击 **☰ > 用户 & 认证**。 +1. 在左侧导航栏中，单击**组**。 +1. 转到将分配自定义角色的组，然后单击 **⋮ > 编辑配置**。 +1. 如果你已创建角色，角色将显示在**自定义**中。选择要分配给组的自定义角色。 +1. 可选：在**全局权限**或**内置角色**中，选择要分配给该组的其他权限。 +1. 单击**保存**。 + +**结果**：自定义角色将在组内用户登录 Rancher 时生效。 + +## 权限提升 + +`配置应用商店`这个自定义权限很强大，应谨慎使用。如果管理员将`配置应用商店`权限分配给普通用户，可能会导致权限提升。在这种情况下，用户可以让自己对 Rancher 配置的集群进行管理员访问。因此，拥有此权限的任何用户都应被视为管理员。 \ No newline at end of file diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/global-permissions.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/global-permissions.md new file mode 100644 index 00000000000..e8a6c00c3f3 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/global-permissions.md @@ -0,0 +1,367 @@ +--- +title: 全局权限 +--- + + + + + + + +_权限_ 是你在为用户选择自定义权限时可以分配的个人访问权限。 + +全局权限定义用户在任何特定集群之外的授权。Rancher 提供四种开箱即用的默认全局权限：`Administrator` (管理员)、`Restricted Admin` (受限管理员)、`Standard User` (标准用户) 和 `User-Base` 用户。 + +- **管理员**：可以完全控制整个 Rancher 系统和其中的所有集群。 + +- **受限管理员**：可以完全控制下游集群，但不能更改本地 Kubernetes 集群。 + +- **普通用户**：可以创建新集群并使用它们。普通用户还可以在自己的集群中向其他用户分配集群权限。 + +- **User-Base 用户**：只有登录权限。 + +你无法更新或删除内置的全局权限。 + +## 分配全局权限 + +本地用户的全局权限分配与使用外部认证登录 Rancher 的用户不同。 + +### 新本地用户的全局权限 + +在创建新本地用户时，请在填写**添加用户**表单时为他分配全局权限。 + +如果需要查看新用户的默认权限： + +1. 在左上角，单击 **☰ > 用户 & 认证**。 +1. 在左侧导航栏中，单击**角色**。 +1. **角色**页面有按范围分组的角色选项卡。每个表都列出了范围内的角色。在**全局**选项卡的**新用户的默认角色**列中，默认授予新用户的权限用复选标记表示。 + +你可以[更改默认全局权限来满足你的需要](#配置默认的全局权限) + +### 使用外部认证登录的用户的全局权限 + +当用户首次使用外部认证登录 Rancher 时，他们会自动分配到**新用户的默认角色**的全局权限。默认情况下，Rancher 为新用户分配 **Standard User** 权限。 + +如果需要查看新用户的默认权限： + +1. 在左上角，单击 **☰ > 用户 & 认证**。 +1. 在左侧导航栏中，单击**角色**。 +1. **角色**页面有按范围分组的角色选项卡。每个表都列出了范围内的角色。在每个页面的**新用户的默认角色**列中，默认授予新用户的权限用复选标记表示。 + +你可以[更改默认权限来满足你的需要](#配置默认的全局权限) + +你可以按照[步骤](#为单个用户配置全局权限)操作来将权限分配给单个用户。 + +如果外部认证服务支持组，你可以[同时为组中的每个成员分配角色](#为组配置全局权限)。 + +## 自定义全局权限 + +使用自定义权限可以为用户提供 Rancher 中更为受限或特定的访问权限。 + +当来自[外部认证](../authentication-config/authentication-config.md)的用户首次登录 Rancher 时，他们会自动分配到一组全局权限（以下简称权限）。默认情况下，用户第一次登录后会被创建为用户，并分配到默认的`用户`权限。标准的`用户`权限允许用户登录和创建集群。 + +但是，在某些组织中，这些权限可能会被认为权限过大。你可以为用户分配一组更具限制性的自定义全局权限，而不是为用户分配 `Administrator` 或 `Standard User` 的默认全局权限。 + +默认角色（管理员和标准用户）都内置了多个全局权限。系统管理员角色包括所有全局权限，而默认用户角色包括三个全局权限，分别是创建集群、使用应用商店模板和 User Base（登录 Rancher 的最低权限）。换句话说，自定义全局权限是模块化的，因此，如果你要更改默认用户角色权限，你可以选择需要包括在新的默认用户角色中的全局权限子集。 + +管理员可以通过多种方式强制执行自定义全局权限： + +- [创建自定义全局角色](#自定义全局角色). +- [更改新用户的默认权限](#配置默认的全局权限). +- [为单个用户配置全局权限](#为单个用户配置全局权限). +- [为组配置全局权限](#为组配置全局权限). + +### 结合内置的全局角色 + +Rancher 提供了多个全局角色，它们为某些常见的用户场景授予了精细的权限。下表列出了每个内置的全局角色（`Administrator`, `Standard User` 和 `User-Base`）以及它包含的默认全局权限 + +| 自定义全局权限 | Administrator | Standard User | User-Base | +| --------------------------- | ------------- | ------------- | --------- | +| 创建集群 | ✓ | ✓ | | +| 创建 RKE 模板 | ✓ | ✓ | | +| 管理认证 | ✓ | | | +| 管理应用商店 | ✓ | | | +| 管理集群驱动 | ✓ | | | +| 管理主机驱动 | ✓ | | | +| 管理 PodSecurityPolicy 模板 | ✓ | | | +| 管理角色 | ✓ | | | +| 管理设置 | ✓ | | | +| Manage Users | ✓ | | | +| 使用应用商店模板 | ✓ | ✓ | | +| User-Base (基本登录访问) | ✓ | ✓ | | + +如果需要查看每个全局权限对应哪些 Kubernetes 资源： + +1. 在左上角，单击 **☰ > 用户 & 认证**。 +1. 在左侧导航栏中，单击**角色**。 +1. 如果单击单个角色的名称，表格会显示该角色授权的所有操作和资源。 + +:::note 注意事项： + +- 上面列出的每个权限都包含多个未在 Rancher UI 中列出的权限。如果需要获取完整权限列表以及组成权限的规则，请通过 `/v3/globalRoles` API 进行访问。 +- 在查看 Rancher 创建的默认角色关联的资源时，如果在一行上有多个 Kubernetes API 资源，则该资源将带有 `(Custom)` 标识。这不代表这个资源是自定义资源，而只是表明多个 Kubernetes API 资源作为一个资源。 + +::: + +### 自定义全局角色 + +当内置的全局角色无法直接满足你的需求时，可以创建自定义全局角色。 + +通过 UI 或自动化（例如 Rancher Kubernetes API） 创建自定义全局角色，你可以指定使用与上游角色和集群角色相同的规则。 + +#### Escalate 与 Bind + +当授予全局角色权限时，请注意 Rancher 遵循 `escalate` 与 `bind`，其方式类似于 [Kubernetes](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#restrictions-on-role-creation-or-update)。 + +在全局角色提供的这两项配置，都可以授予用户绕过 Rancher 提升校验的权限。这可能允许用户成为管理员。由于这有着极高的安全风险，因此应非常谨慎地将 `bind` 和 `escalate` 权限分发给用户。 + +`escalate` 允许用户更改全局角色并添加任何授权，即使用户没有当前或新版本的全局角色权限。 + +`bind` 允许用户对指定的全局角色进行授权（创建 ClusterRoleBinding），即使该用户没有访问全局角色的权限。 + +:::danger + +通配符动词 `*` 也包括 `bind` 和 `escalate`。这意味着为用户的全局角色设置 `*` 也会提供 `escalate` 和 `bind`。 + +::: + +##### 自定义全局角色示例 + +仅为名称为 `test-gr` 的全局角色授予 escalate 权限： + +```yaml +rules: + - apiGroups: + - "management.cattle.io" + resources: + - "globalroles" + resourceNames: + - "test-gr" + verbs: + - "escalate" +``` + +为所有的全局角色授予 escalate 权限： + +```yaml +rules: + - apiGroups: + - "management.cattle.io" + resources: + - "globalroles" + verbs: + - "escalate" +``` + +仅为名称为 `test-gr` 的全局角色授予创建角色绑定（绕过 escalation 检查）的权限 + +```yaml +rules: + - apiGroups: + - "management.cattle.io" + resources: + - "globalroles" + resourceNames: + - "test-gr" + verbs: + - "bind" + - apiGroups: + - "management.cattle.io" + resources: + - "globalrolebindings" + verbs: + - "create" +``` + +授予 `*` 权限（同时包含 `escalate` 与 `bind`） + +```yaml +rules: + - apiGroups: + - "management.cattle.io" + resources: + - "globalroles" + verbs: + - "*" +``` + +#### 下游集群的全局角色权限 + +全局角色可以通过 `inheritedClusterRoles` 字段在每个下游集群上授予一个或多个 RoleTemplate。此字段中引用的值必须是集群级别的 RoleTemplate 并且在集群 `context` 中存在。 + +通过此字段，用户将获取当前或未来的所有下游集群的指定权限，例如以下的全局角色示例： + +```yaml +apiVersion: management.cattle.io/v3 +kind: GlobalRole +displayName: All Downstream Owner +metadata: + name: all-downstream-owner +inheritedClusterRoles: + - cluster-owner +``` + +任何具有此权限的用户都将是所有下游集群的所有者（cluster-owner）。如果添加了新的集群，无论是什么类型的集群，用户也将是这个集群的所有者。 + +:::danger + +在[默认的全局角色](#配置默认的全局权限)中使用此字段可能会导致用户获得过多的权限。 + +::: + +### 配置默认的全局权限 + +如果你想限制新用户的默认权限，你可以删除作为默认角色的`用户`权限，然后分配多个单独的权限作为默认权限。你也可以在一组其他标准权限之上添加管理权限。 + +:::note + +默认角色仅分配给从外部认证登录的用户。对于本地用户，在将用户添加到 Rancher 时，必须显式分配全局权限。你可以在添加用户时自定义这些全局权限。 + +::: + +要更改在外部用户首次登录时分配给他们的默认全局权限，请执行以下步骤： + +1. 在左上角，单击 **☰ > 用户 & 认证**。 +1. 在左侧导航栏中，单击**角色**。在**角色**页面上，确保选择了**全局**选项卡。 +1. 查找要添加或删除的默认权限集。然后，通过选择 **⋮ > 编辑配置**来编辑权限。 +1. 如果要将权限添加为默认权限，请选择**是：新用户的默认角色**，然后单击**保存**。如果要删除默认权限，请编辑该权限并选择**否**。 + +**结果**：默认全局权限已根据你的更改配置。分配给新用户的权限会在**新用户的默认角色**列中显示为复选标记。 + +### 为单个用户配置全局权限 + +要为单个用户配置权限： + +1. 在左上角，单击 **☰ > 用户 & 认证**。 +1. 在左侧导航栏中，单击**用户**。 +1. 找到要更改访问级别的用户，然后单击 **⋮ > 编辑配置**。 +1. 在**全局权限**和**内置角色**部分中，选中你希望用户拥有的权限的复选框。如果你在**角色**页面创建了角色，这些角色将出现在**自定义**部分，你也可以选择这些角色。 +1. 单击**保存**。 + +**结果**：用户的全局权限已更新。 + +### 为组配置全局权限 + +如果你有一组需要在 Rancher 中有相同访问权限的用户，你可以一次性将权限分配给整个组来节省时间。这样，组中的用户在第一次登录 Rancher 时能拥有相应级别的访问权限。 + +将自定义全局角色分配给组后，该角色将在组中用户登录 Rancher 时分配给用户。 + +对于现有用户，新权限将在用户退出 Rancher 并重新登录时，或当管理员[刷新用户组成员名单](#刷新用户组成员名单)时生效。 + +对于新用户，新权限在用户首次登录 Rancher 时生效。除了**新用户的默认角色**全局权限外，来自该组的新用户还将获得自定义全局角色的权限。默认情况下，**新用户的默认角色**权限等同于 **Standard User** 全局角色，但默认权限可以[配置。](#配置默认的全局权限) + +如果从外部认证服务中将用户从组中删除，该用户将失去分配给该组的自定义全局角色的权限。他们将继续拥有分配给他们的其他剩余角色，这通常包括标记为**新用户的默认角色**的角色。Rancher 将在用户登出或管理员[刷新用户组成员名单](#刷新用户组成员名单)时删除与组关联的权限。 + +:::note 先决条件： + +只有在以下情况下，你才能将全局角色分配给组： + +- 你已设置[外部认证](../authentication-config/authentication-config.md#外部认证与本地认证) +- 外部认证服务支持[用户组](../authentication-config/manage-users-and-groups.md) +- 你已使用外部认证服务设置了至少一个用户组。 + +::: + +要将自定义全局角色分配给组，请执行以下步骤： + +1. 在左上角，单击 **☰ > 用户 & 认证**。 +1. 在左侧导航栏中，单击**组**。 +1. 转到你要分配自定义全局角色的组，然后单击 **⋮ > 编辑配置**。 +1. 在**全局权限**，**自定义**和/或**内置角色**部分中，选择该组应具有的权限。 +1. 单击**创建**。 + +**结果**：自定义全局角色会在组内用户登录 Rancher 时生效。 + +### 刷新用户组成员名单 + +当管理员更新组的全局权限时，更改将在组成员退出 Rancher 并重新登录后生效。 + +如果要让更改立即生效，管理员或集群所有者可以刷新用户组成员名单。 + +如果用户已经从外部认证服务中的组中删除，管理员也需要刷新用户组成员名单。在这种情况下，刷新操作会让 Rancher 知道用户已从组中删除。 + +要刷新用户组成员名单： + +1. 在左上角，单击 **☰ > 用户 & 认证**。 +1. 在左侧导航栏中，单击**用户**。 +1. 单击**刷新用户组成员名单**。 + +**结果**：对组成员权限的所有更改都会生效。 + +## 受限管理员 + +:::warning 已弃用 + +受限管理员角色已弃用，并将在未来的 Rancher 版本（2.10 或更高版本）中删除。你应该创建具有所需权限的自定义角色，而不是依赖此项内置角色。 + +::: + +Rancher 2.5 创建了一个新的 `restricted-admin` 角色，以防止本地 Rancher Server Kubernetes 集群的权限提升。此角色对 Rancher 管理的所有下游集群具有完全管理员权限，但没有更改本地 Kubernetes 集群的权限。 + +`restricted-admin` 可以创建其他具有同样访问权限的 `restricted-admin` 用户。 + +Rancher 还增加了一个新设置，来将初始启动的管理员设置为 `restricted-admin` 角色。该设置适用于 Rancher Server 首次启动时创建的第一个用户。如果设置了这个环境变量，则不会创建全局管理员，也就无法通过 Rancher 创建全局管理员。 + +要以 `restricted-admin` 作为初始用户来启动 Rancher，你需要使用以下环境变量来启动 Rancher Server： + +``` +CATTLE_RESTRICTED_DEFAULT_ADMIN=true +``` + +### `受限管理员` 的权限列表 + +下表列出了 `受限管理员` 与 `全局管理员` 和 `普通用户` 角色相比应具有的权限和操作： + +| 类别 | 操作 | 全局管理员 | 普通用户 | 受限管理员 | 受限管理员的注意事项 | +| -------- | ------ | ------------ | ------------- | ---------------- | ------------------------------- | +| 本地集群功能 | 管理本地集群（列出、编辑、导入主机） | 是 | 否 | 否 | | +| | 创建项目/命名空间 | 是 | 否 | 否 | | +| | 添加集群/项目成员 | 是 | 否 | 否 | | +| | 全局 DNS | 是 | 否 | 否 | | +| | 访问 CRD 和 CR 的管理集群 | 是 | 否 | 是 | | +| | 另存为 RKE 模板 | 是 | 否 | 否 | | +| 安全 | | | | | | +| 启用认证 | 配置认证 | 是 | 否 | 是 | | +| 角色 | 创建/分配 GlobalRoles | 是 | 否（可列出） | 是 | 认证 Webhook 允许为已经存在的权限创建 globalrole | +| | 创建/分配 ClusterRoles | 是 | 否（可列出） | 是 | 不在本地集群中 | +| | 创建/分配 ProjectRoles | 是 | 否（可列出） | 是 | 不在本地集群中 | +| 用户 | 添加用户/编辑/删除/停用用户 | 是 | 否 | 是 | | +| 组 | 将全局角色分配给组 | 是 | 否 | 是 | 在 Webhook 允许的范围内 | +| | 刷新组 | 是 | 否 | 是 | | +| PSP | 管理 PSP 模板 | 是 | 否（可列出） | 是 | 与 PSP 的全局管理员权限相同 | +| 工具 | | | | | | +| | 管理 RKE 模板 | 是 | 否 | 是 | | +| | 管理全局应用商店 | 是 | 否 | 是 | 无法编辑/删除内置系统应用商店。可以管理 Helm 库 | +| | 集群驱动 | 是 | 否 | 是 | | +| | 主机驱动 | 是 | 否 | 是 | | +| | GlobalDNS 提供商 | 是 | 是（自己） | 是 | | +| | GlobalDNS 条目 | 是 | 是（自己） | 是 | | +| 设置 | | | | | | +| | 管理设置 | 是 | 否（可列出） | 否（可列出） | | +| 用户 | | | | | | +| | 管理 API 密钥 | 是（管理所有） | 是（管理自己的） | 是（管理自己的） | | +| | 管理节点模板 | 是 | 是（管理自己的） | 是（管理自己的） | 只能管理自己的节点模板，不能管理其他用户创建的节点模板。 | +| | 管理云凭证 | 是 | 是（管理自己的） | 是（管理自己的） | 只能管理自己的云凭证，不能管理其他用户创建的云凭证。 | +| 下游集群 | 创建集群 | 是 | 是 | 是 | | +| | 编辑集群 | 是 | 是 | 是 | | +| | 轮换证书 | 是 | | 是 | | +| | 立即创建快照 | 是 | | 是 | | +| | 恢复快照 | 是 | | 是 | | +| | 另存为 RKE 模板 | 是 | 否 | 是 | | +| | 运行 CIS 扫描 | 是 | 是 | 是 | | +| | 添加成员 | 是 | 是 | 是 | | +| | 创建项目 | 是 | 是 | 是 | | +| 自 2.5 起的功能 Chart | | | | | | +| | 安装 Fleet | 是 | | 是 | 无法在本地集群中运行 Fleet | +| | 部署 EKS 集群 | 是 | 是 | 是 | | +| | 部署 GKE 集群 | 是 | 是 | 是 | | +| | 部署 AKS 集群 | 是 | 是 | 是 | | + + +### 将全局管理员更改为受限管理员 + +在之前的版本中，文档建议如果管理员角色正在使用中，应将所有用户都更改为受限管理员。现在鼓励用户使用集群权限的功能构建自定义的全局角色，并将受限管理员迁移到新的自定义角色使用。 + +你可以前往**安全 > 用户**，并将所有管理员角色转为受限管理员。 + +已登录的用户可以根据需要将自己更改为 `restricted-admin`，但这应该是他们的最后一步操作，否则他们将没有进行该操作的权限。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/locked-roles.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/locked-roles.md new file mode 100644 index 00000000000..cb0ad71fa38 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/locked-roles.md @@ -0,0 +1,38 @@ +--- +title: 锁定角色 +--- + +你可以将角色设置为`锁定`状态。锁定角色可防止把这些角色分配给用户。 + +处于锁定状态的角色具有如下特性： + +- 无法再分配给当下还没有被分配到该角色的用户。 +- 将用户添加到集群或项目时，不会在**成员角色**下拉列表中列出。 +- 不会影响在锁定该角色之前，已经分配了该角色的用户。即使后来锁定了该角色，这些用户仍然保留该角色提供的访问权限。 + + **示例**：假设你的组织制定了一个内部策略，禁止把创建项目的权限分配给集群用户。这时候你需要执行这个策略。 + + 因此，在将新用户添加到集群之前，你需要锁定以下角色：`集群所有者`，`集群成员`和`创建项目`。然后，创建一个新的自定义角色，该角色的权限与`集群成员`相同，但没有创建项目的权限。然后，在将用户添加到集群时使用这个新的自定义角色。 + +以下用户可以锁定角色： + +- 任何分配了`管理员`全局权限的用户。 +- 任何分配了带有`管理角色`权限的`自定义用户`。 + + +## 锁定/解锁角色 + +如果要防止将角色分配给用户，可以将其设置为`锁定`状态。 + +你可以在两种情况下锁定角色： + +- [添加自定义角色](custom-roles.md)时。 +- 编辑现有角色时（见下文）。 + +集群角色和项目/命名空间角色可以锁定，而全局角色不能锁定。 + +1. 在左上角，单击 **☰ > 用户 & 认证**。 +1. 在左侧导航栏中，单击**角色**。 +1. 转到**集群**选项卡或**项目或命名空间**选项卡。 +1. 找到要锁定（或解锁）的角色，选择 **⋮ > 编辑配置**。 +1. 从**锁定**选项中，选择**是** 或**否**。然后点击**保存**。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/manage-role-based-access-control-rbac.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/manage-role-based-access-control-rbac.md new file mode 100644 index 00000000000..0e8a5e89824 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/manage-role-based-access-control-rbac.md @@ -0,0 +1,29 @@ +--- +title: 管理 RBAC +--- + + + + + +Rancher 通过 _用户_ 进行授权管理。如[认证](../authentication-config/authentication-config.md)中所述，用户可以是本地用户，也可以是外部用户。 + +配置外部认证后，**用户**页面上显示的用户会发生变化。 + +- 如果你以本地用户身份登录，则仅显示本地用户。 + +- 如果你以外部用户身份登录，则会同时显示外部用户和本地用户。 + +## 用户和角色 + +一旦用户登录到 Rancher，他们的 _授权_，也就是他们在系统中的访问权限，将由 _全局权限_ 和 _集群和项目角色_ 决定。 + +- [全局权限](global-permissions.md): + + 定义用户在任何特定集群之外的授权。 + +- [集群和项目角色](cluster-and-project-roles.md): + + 定义用户在分配了角色的特定集群或项目中的授权。 + +全局权限以及集群和项目角色都是基于 [Kubernetes RBAC](https://kubernetes.io/docs/reference/access-authn-authz/rbac/) 实现的。因此，权限和角色的底层实现是由 Kubernetes 完成的。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/pod-security-standards.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/pod-security-standards.md new file mode 100644 index 00000000000..547fa2d2cf2 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/pod-security-standards.md @@ -0,0 +1,18 @@ +--- +title: Pod 安全标准 (PSS) 和 Pod 安全准入 (PSA) +--- + +[Pod 安全标准 (PSS)](https://kubernetes.io/docs/concepts/security/pod-security-standards/) 和 [Pod 安全准入 (PSA)](https://kubernetes.io/docs/concepts/security/pod-security-admission/) 为大量工作负载定义了安全限制。 +它们在 Kubernetes v1.23 中可用并默认打开，并在 Kubernetes v1.25 及更高版本中替换了 [Pod Security Policies (PSP)](https://kubernetes.io/docs/concepts/security/pod-security-policy/)。 + +PSS 定义了工作负载的安全级别。PSA 描述了 Pod 安全上下文和相关字段的要求。PSA 参考 PSS 级别来定义安全限制。 + +## Pod 安全准入配置模板 + +Rancher 提供了 PSA 配置模板。它们是可以应用到集群的预定义安全配置。Rancher 管理员（或具有权限的人员）可以[创建、管理和编辑](./psa-config-templates.md) PSA 模板。 + +### 受 PSA 限制的集群上的 Rancher + +Rancher system 命名空间也受到 PSA 模板描述的限制性安全策略的影响。你需要在分配模板后豁免 Rancher 的 system 命名空间，否则集群将无法正常运行。有关详细信息，请参阅 [Pod 安全准入 (PSA) 配置模板](./psa-config-templates.md#豁免必须的-rancher-命名空间)。 + +有关运行 Rancher 所需的所有豁免的完整文件，请参阅此[准入配置示例](../../../reference-guides/rancher-security/psa-restricted-exemptions.md)。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/psa-config-templates.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/psa-config-templates.md new file mode 100644 index 00000000000..22d7033980d --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/psa-config-templates.md @@ -0,0 +1,143 @@ +--- +title: Pod 安全准入 (PSA) 配置模板 +--- + +[Pod Security admission (PSA)](./pod-security-standards.md) 配置模板是 Rancher 自定义资源 (CRD)，在 Rancher v2.7.2 及更高版本中可用。这些模板提供了可应用于集群的预定义安全配置： + +:::info important +The policies shipped by default in Rancher aim to provide a trade-off between security and convenience. If a more strict policy configuration is needed, users are able to craft such policies themselves based on their specific requirements. In the case Rancher policies are preferred, you will need to deploy admission controllers that block the creation of any [exempted namespaces](#豁免必须的-rancher-命名空间) that won't be used within your environments. +::: + +- `rancher-privileged`：最宽松的配置。它不限制任何 Pod 行为，允许已知的权限升级。该策略没有豁免。 +- `rancher-restricted`：严格限制的配置，遵循当前加固 pod 的最佳实践。你必须对 Rancher 组件进行[命名空间级别豁免](./pod-security-standards.md#受-psa-限制的集群上的-rancher)。 + +## 分配 Pod 安全准入 (PSA) 配置模板 + +你可以在创建下游集群的同时分配 PSA 模板。你还可以通过配置现有集群来添加模板。 + +### 在集群创建期间分配模板 + + + +1. 在左上角，单击 **☰ > 集群管理**。 +1. 在**集群**页面上，单击**创建**按钮。 +1. 选择提供商。 +1. 在**集群: 创建**页面上，转到**基本信息 > 安全**。 +1. 在 **PSA 配置模板**下拉菜单中，选择要分配的模板。 +1. 单击**创建**。 + +### 将模板分配给现有集群 + +1. 在左上角，单击 **☰ > 集群管理**。 +1. 在**集群**表中找到要更新的集群，点击 **⋮**。 +1. 选择**编辑配置**。 +1. 在 **PSA 配置模板**下拉菜单中，选择要分配的模板。 +1. 单击**保存**。 + +### 加固集群 + +如果选择 **rancher-restricted** 模板但不选择 **CIS 配置文件**，你将无法满足 CIS Benchmark。有关详细信息，请参阅 [RKE2 加固指南](../../../reference-guides/rancher-security/hardening-guides/rke2-hardening-guide/rke2-hardening-guide.md)。 + + + + +1. 在左上角，单击 **☰ > 集群管理**。 +1. 在**集群**页面上，单击**创建**按钮。 +1. 选择提供商。 +1. 在**添加集群**页面上的**集群选项**下，单击 **高级选项**。 +1. 在 **PSA 配置模板**下拉菜单中，选择要分配的模板。 +1. 单击**创建**。 + +### 将模板分配给现有集群 + +1. 在左上角，单击 **☰ > 集群管理**。 +1. 在**集群**表中找到要更新的集群，点击 **⋮**。 +1. 选择**编辑配置**。 +1. 在**编辑集群**页面上，转到**集群选项 > 高级选项**。 +1. 在 **PSA 配置模板**中，选择要分配的模板。 +1. 单击**保存**。 + + + + +## 添加或编辑 Pod 安全准入 (PSA) 配置模板 + +如果你拥有管理员权限，则可以通过创建其他 PSA 模板或编辑现有模板来自定义安全限制和权限。 + +:::caution +如果编辑使用中的现有 PSA 模板，更改将应用​​于已分配给该模板的所有集群。 +::: + +1. 在左上角，单击 **☰ > 集群管理**。 +1. 点击**高级选项**打开下拉菜单。 +1. 选择 **Pod 安全准入**。 +1. 找到要修改的模板，点击 **⋮**。 +1. 选择**编辑配置**来编辑模板。 +1. 完成配置编辑后，单击**保存**。 + +### 允许非管理员用户管理 PSA 模板 + +如果你想允许其他用户管理模板，你可以将该用户绑定到一个角色，并为该角色授予 `management.cattle.io/podsecurityadmissionconfigurationtemplates` 上的所有操作 (`"*"`)。 + +:::caution +绑定到上述权限的用户都能够更改使用该 PSA 模板的_所有_托管集群的限制级别，包括用户没有权限的集群。 +::: + +## 豁免必须的 Rancher 命名空间 + +在默认执行限制性安全策略的 Kubernetes 集群上运行 Rancher 时，你需要[豁免以下命名空间](#豁免命名空间)，否则该策略可能会阻止 Rancher system pod 正常运行。 + +- `calico-apiserver` +- `calico-system` +- `cattle-alerting` +- `cattle-csp-adapter-system` +- `cattle-epinio-system` +- `cattle-externalip-system` +- `cattle-fleet-local-system` +- `cattle-fleet-system` +- `cattle-gatekeeper-system` +- `cattle-global-data` +- `cattle-global-nt` +- `cattle-impersonation-system` +- `cattle-istio` +- `cattle-istio-system` +- `cattle-logging` +- `cattle-logging-system` +- `cattle-monitoring-system` +- `cattle-neuvector-system` +- `cattle-prometheus` +- `cattle-sriov-system` +- `cattle-system` +- `cattle-ui-plugin-system` +- `cattle-windows-gmsa-system` +- `cert-manager` +- `cis-operator-system` +- `fleet-default` +- `fleet-local` +- `ingress-nginx` +- `istio-system` +- `kube-node-lease` +- `kube-public` +- `kube-system` +- `longhorn-system` +- `rancher-alerting-drivers` +- `security-scan` +- `tigera-operator` + +Rancher、Rancher 拥有的一些 Chart 以及 RKE2 和 K3s 发行版都使用这些命名空间。列出的命名空间的一个子集已经在内置的 Rancher `rancher-restricted` 策略中被豁免，用于下游集群。有关运行 Rancher 所需的所有豁免的完整模板，请参阅此[准入配置示例](../../../reference-guides/rancher-security/psa-restricted-exemptions.md)。 + +## 豁免命名空间 + +如果你将 `rancher-restricted` 模板分配给集群，默认情况下，限制会在命名空间级别应用于整个集群。要在此高度受限的策略下豁免特定的命名空间，执行以下操作： + +1. 在左上角，单击 **☰ > 集群管理**。 +1. 点击**高级选项**打开下拉菜单。 +1. 选择 **Pod 安全准入**。 +1. 找到要修改的模板，点击 **⋮**。 +1. 选择**编辑配置**。 +1. 选中**豁免**下的**命名空间**复选框以编辑**命名空间**字段。 +1. 豁免命名空间后，单击**保存**。 + +:::note +你需要更新目标集群才能让新模板在集群中生效。要触发更新，在不更改值的情况下编辑和保存集群。 +::: diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/back-up-docker-installed-rancher.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/back-up-docker-installed-rancher.md new file mode 100644 index 00000000000..51b24396cbd --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/back-up-docker-installed-rancher.md @@ -0,0 +1,74 @@ +--- +title: 备份 Docker 安装的 Rancher +--- + +成功使用 Docker 安装 Rancher 后，我们建议你定期创建备份。最近创建的备份能让你在意外灾难发生后快速进行恢复。 + +## 在你开始前 + +在创建备份的过程中，你将输入一系列命令。请使用环境中的数据替换占位符。占位符用尖括号和大写字母（如 ``）表示。以下是带有占位符的命令示例： + +``` +docker run --name busybox-backup- --volumes-from rancher-data- -v $PWD:/backup busybox tar pzcvf /backup/rancher-data-backup--.tar.gz /var/lib/rancher +``` + +在该命令中，`` 是数据容器和备份创建日期的占位符（例如，`9-27-18`）。 + +请交叉参考下方的图片和表格，了解获取此占位符数据的方法。在开始[以下步骤](#创建备份)之前，请记下或复制这些信息。 + +终端 docker ps 命令，显示如何找到 <RANCHER_CONTAINER_TAG> 和 <RANCHER_CONTAINER_NAME> + +![占位符参考](/img/placeholder-ref.png) + +| 占位符 | 示例 | 描述 | +| -------------------------- | -------------------------- | --------------------------------------------------------- | +| `` | `v2.0.5` | 首次安装拉取的 rancher/rancher 镜像。 | +| `` | `festive_mestorf` | 你的 Rancher 容器的名称。 | +| `` | `v2.0.5` | 你为其创建备份的 Rancher 版本。 | +| `` | `9-27-18` | 数据容器或备份的创建日期。 | +
+ +可以通过远程连接登录到 Rancher Server 所在的主机并输入命令 `docker ps` 以查看正在运行的容器，从而获得 `` 和 ``。你还可以运行 `docker ps -a` 命令查看停止了的容器。在创建备份期间，你随时可以运行这些命令来获得帮助。 + +## 创建备份 + +此步骤将创建一个备份文件。如果 Rancher 遇到灾难情况，你可以使用该备份文件进行还原。 + + +1. 使用远程终端连接，登录到运行 Rancher Server 的节点。 + +1. 停止当前运行 Rancher Server 的容器。将 `` 替换为你的 Rancher 容器的名称： + + ``` + docker stop + ``` +1. 运行以下命令，从刚才停止的 Rancher 容器创建一个数据容器。请替换命令中的占位符： + + ``` + docker create --volumes-from --name rancher-data- rancher/rancher: + ``` + +1. 从你刚刚创建的数据容器（rancher-data-<DATE>）中，创建一个备份 tar 包（rancher-data-backup-<RANCHER_VERSION>-<DATE>.tar.gz）。替换占位符来运行以下命令： + + ``` + docker run --name busybox-backup- --volumes-from rancher-data- -v $PWD:/backup:z busybox tar pzcvf /backup/rancher-data-backup--.tar.gz /var/lib/rancher + ``` + + **步骤结果**：屏幕上将运行命令流。 + +1. 输入 `ls` 命令，确认备份压缩包已创建成功。压缩包的名称格式类似 `rancher-data-backup--.tar.gz`。 + +1. 将备份压缩包移动到 Rancher Server 外的安全位置。然后从 Rancher Server 中删除 `rancher-data-` 和 `busybox-backup-` 容器。 + + ``` + docker rm rancher-data- + docker rm busybox-backup- + ``` + +1. 重启 Rancher Server。将 `` 替换为 Rancher 容器的名称： + + ``` + docker start + ``` + +**结果**：创建了 Rancher Server 数据的备份压缩包。如果你需要恢复备份数据，请参见[恢复备份：Docker 安装](restore-docker-installed-rancher.md)。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/back-up-rancher-launched-kubernetes-clusters.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/back-up-rancher-launched-kubernetes-clusters.md new file mode 100644 index 00000000000..3916af6a508 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/back-up-rancher-launched-kubernetes-clusters.md @@ -0,0 +1,307 @@ +--- +title: 备份集群 +--- + +在 Rancher UI 中，你可以轻松备份和恢复 [Rancher 启动的 Kubernetes 集群](../launch-kubernetes-with-rancher/launch-kubernetes-with-rancher.md)的 etcd。 + +Rancher 建议为所有生产集群配置定期 `etcd` 快照。此外，你还可以创建单次快照。 + +etcd 数据库的快照会保存在 [etcd 节点](#本地备份目标)或 [S3 兼容目标](#s3-备份目标)上。配置 S3 的好处是，如果所有 etcd 节点都丢失了，你的快照会保存到远端并能用于恢复集群。 + +## 快照工作原理 + +### 快照组件 + + + + +Rancher 创建快照时，快照里包括三个组件： + +- etcd 中的集群数据 +- Kubernetes 版本 +- `cluster.yml` 形式的集群配置 + +由于 Kubernetes 版本现在包含在快照中，因此你可以将集群恢复到原本的 Kubernetes 版本。 + + + + +Rancher 将快照创建任务委托给下游 Kubernetes 引擎。Kubernetes 引擎创建快照时包括了三个组件： + +- etcd 中的集群数据 +- Kubernetes 版本 +- 集群配置 + +由于 Kubernetes 版本包含在快照中，因此你可以将集群还原到之前的 Kubernetes 版本，同时还原 etcd 快照。 + + + + +如果你需要使用快照恢复集群，快照的多个组件允许你选择： + +- **仅恢复 etcd 内容**：类似于在 Rancher v2.4.0 之前版本中的使用快照恢复。 +- **恢复 etcd 和 Kubernetes 版本**：如果 Kubernetes 升级导致集群失败，并且你没有更改任何集群配置，则应使用此选项。 +- **恢复 etcd、Kubernetes 版本和集群配置**：如果你在升级时同时更改了 Kubernetes 版本和集群配置，则应使用此选项。 + +建议你在执行配置更改或升级之前创建新快照。 + + +### 从 etcd 节点生成快照 + + + + +集群中的每个 etcd 节点都会检查 etcd 集群的健康状况。如果节点报告 etcd 集群是健康的，则会从中创建一个快照，并可选择上传到 S3。 + +快照存储在 `/opt/rke/etcd-snapshots` 中。如果该目录在节点上配置为共享挂载，它将被覆盖。由于所有 etcd 节点都会上传快照并保留最后一个，因此 S3 上始终会保留最后一个上传的节点的快照。 + +在存在多个 etcd 节点的情况下，任何快照都是在集群健康检查通过后创建的，因此这些快照可以认为是 etcd 集群中数据的有效快照。 + + + + +快照是默认启动的。 + +快照目录默认为 `/var/lib/rancher//server/db/snapshots`，其中 `` 可以是 `rke2` 或 `k3s`。 + +在 RKE2 中，快照会存储在每个 etcd 节点上。如果你有多个 etcd 或 etcd + control plane 节点，你将拥有本地 etcd 快照的多个副本。 + + + + +### 快照命名规则 + + + + +快照的名称是自动生成的。在使用 RKE CLI 创建一次性快照时，你可以使用 `--name` 选项来指定快照的名称。 + +Rancher 在创建 RKE 集群的快照时，快照名称是基于快照创建类型（手动快照或定期快照）和目标（快照是保存在本地还是上传到 S3）决定的。命名规则如下： + +- `m` 代表手动 +- `r` 代表定期 +- `l` 代表本地 +- `s` 代表 S3 + +快照名称示例如下： + +- c-9dmxz-rl-8b2cx +- c-9dmxz-ml-kr56m +- c-9dmxz-ms-t6bjb +- c-9dmxz-rs-8gxc8 + + + + +快照的名称是自动生成的。使用 RKE2 或 K3s CLI 创建一次性快照时，`--name` 选项可用于覆盖快照的基本名称。 + +Rancher 在创建 RKE2 或 K3s 集群的快照时，快照名称是基于快照创建类型（手动快照或定期快照）和目标（快照是保存在本地还是上传到 S3）决定的。命名规则如下： + +`--` + +``：`--name` 设置的基本名称，可以是以下之一： + +- `etcd-snapshot`：位于定期快照前面 +- `on-demand`：位于手动按需快照之前 + +``：创建快照的节点的名称。 + +``：快照创建日期的 unix 时间戳。 + +快照名称示例如下： + +- `on-demand-my-super-rancher-k8s-node1-1652288934` +- `on-demand-my-super-rancher-k8s-node2-1652288936` +- `etcd-snapshot-my-super-rancher-k8s-node1-1652289945` +- `etcd-snapshot-my-super-rancher-k8s-node2-1652289948` + + + + +### 从快照恢复的工作原理 + + + + +在恢复时会发生以下过程： + +1. 如果配置了 S3，则从 S3 检索快照。 +2. 如果快照压缩了，则将快照解压缩。 +3. 集群中的一个 etcd 节点会将该快照文件提供给其他节点。 +4. 其他 etcd 节点会下载快照并验证校验和，以便都能使用相同的快照进行恢复。 +5. 集群已恢复，恢复后的操作将在集群中完成。 + + + + +在还原时，Rancher 会提供几组执行还原的计划。期间将包括以下阶段： + +- Started +- Shutdown +- Restore +- RestartCluster +- Finished + +如果 etcd 快照还原失败，阶段将设置为 `Failed`。 + +1. 收到 etcd 快照还原请求后，根据 `restoreRKEConfig` 协调集群配置和 Kubernetes 版本。 +1. 该阶段设置为 `Started`。 +1. 该阶段设置为 `Shutdown`，并使用运行 `killall.sh` 脚本的计划来关闭整个集群。一个新的初始节点会被选举出来。如果还原的快照是本地快照，则选择该快照所在的节点作为初始节点。如果使用 S3 还原快照，将使用现有的初始节点。 +1. 该阶段设置为 `Restore`，并且快照将还原到初始节点上。 +1. 该阶段设置为 `RestartCluster`，集群将重启并重新加入到具有新还原的快照信息的新初始节点。 +1. 该阶段设置为 `Finished`，集群被视为已成功还原。`cattle-cluster-agent` 将重新连接，集群将完成协调。 + + + + +## 配置定期快照 + + + + +选择创建定期快照的频率以及要保留的快照数量。时间的单位是小时。用户可以使用时间戳快照进行时间点恢复。 + +默认情况下，[Rancher 启动的 Kubernetes 集群](../launch-kubernetes-with-rancher/launch-kubernetes-with-rancher.md)会配置为创建定期快照（保存到本地磁盘）。为防止本地磁盘故障，建议使用 [S3 目标](#s3-备份目标)或复制磁盘上的路径。 + +在集群配置或编辑集群期间，可以在**集群选项**的高级部分中找到快照的配置。点击**显示高级选项**。 + +在集群的**高级选项**中可以配置以下选项： + +| 选项 | 描述 | 默认值 | +| --- | ---| --- | +| etcd 快照备份目标 | 选择要保存快照的位置。可以是本地或 S3 | 本地 | +| 启用定期 etcd 快照 | 启用/禁用定期快照 | 是 | +| 定期 etcd 快照的创建周期 | 定期快照之间的间隔（以小时为单位） | 12 小时 | +| 定期 etcd 快照的保留数量 | 要保留的快照数量 | 6 | + + + + +设置创建定期快照的方式以及要保留的快照数量。该计划采用传统的 Cron 格式。保留策略规定了在每个节点上要保留的匹配名称的快照数量。 + +默认情况下，[Rancher 启动的 Kubernetes 集群](../launch-kubernetes-with-rancher/launch-kubernetes-with-rancher.md)从凌晨 12 点开始每 5 小时创建一次定期快照（保存到本地磁盘）。为了防止本地磁盘故障，建议使用 [S3 目标](#s3-备份目标)或复制磁盘上的路径。 + +在集群配置或编辑集群期间，你可以在**集群配置**下找到快照配置。单击 **etcd**。 + +| 选项 | 描述 | 默认值 | +| --- | ---| --- | +| 启用定期 etcd 快照 | 启用/禁用定期快照 | 是 | +| 定期 etcd 快照的创建周期 | 定期快照的 Cron 计划 | `0 */5 * * *` | +| 定期 etcd 快照的保留数量 | 要保留的快照数量 | 5 | + + + + +## 单次快照 + + + + +除了定期快照之外，你可能还想创建“一次性”快照。例如，在升级集群的 Kubernetes 版本之前，最好备份集群的状态以防止升级失败。 + +1. 在左上角，单击 **☰ > 集群管理**。 +1. 在**集群**页面上，导航到要在其中创建一次性快照的集群。 +1. 单击 **⋮ > 拍摄快照**。 + + + + +除了定期快照之外，你可能还想创建“一次性”快照。例如，在升级集群的 Kubernetes 版本之前，最好备份集群的状态以防止升级失败。 + +1. 在左上角，单击 **☰ > 集群管理**。 +1. 在**集群**页面上，导航到要在其中创建一次性快照的集群。 +1. 导航至`快照`选项卡，然后单击`立即创建快照` + +### 创建一次性快照的工作原理 + +在创建一次性快照时，Rancher 会传递几组计划来执行快照创建。期间将包括以下阶段： + +- Started +- RestartCluster +- Finished + +如果 etcd 快照创建失败，阶段将设置为 `Failed`。 + +1. 收到 etcd 快照创建请求。 +1. 该阶段设置为 `Started`。集群中的所有 etcd 节点都会根据集群配置收到创建 etcd 快照的计划。 +1. 该阶段设置为 `RestartCluster`，并且每个 etcd 节点上的计划都将重置为 etcd 节点的原始计划。 +1. 该阶段设置为 `Finished`。 + + + + +**结果**：根据你的[快照备份目标](#快照备份目标)创建一次性快照，并将其保存在选定的备份目标中。 + +## 快照备份目标 + +Rancher 支持两种不同的备份目标： + +- [本地目标](#本地备份目标) +- [S3 目标](#s3-备份目标) + +### 本地备份目标 + + + + +默认情况下会选择 `local` 备份目标。此选项的好处是不需要进行外部配置。快照会在本地自动保存到 [Rancher 启动的 Kubernetes 集群](../launch-kubernetes-with-rancher/launch-kubernetes-with-rancher.md)中 etcd 节点的 `/opt/rke/etcd-snapshots` 中。所有定期快照都是按照配置的时间间隔创建的。使用 `local` 备份目标的缺点是，如果发生全面灾难并且丢失 _所有_ etcd 节点时，则无法恢复集群。 + + + + +默认情况下会选择 `local` 备份目标。此选项的好处是不需要进行外部配置。快照会自动保存到 [Rancher 启动的 Kubernetes 集群](../launch-kubernetes-with-rancher/launch-kubernetes-with-rancher.md)中的本地 etcd 节点上的 `/var/lib/rancher//server/db/snapshots` 中，其中 `` 可以是 `k3s` 或 `rke2`。所有定期快照均按照 Cron 计划进行。使用 `local` 备份目标的缺点是，如果发生全面灾难并且丢失 _所有_ etcd 节点时，则无法恢复集群。 + + + + +### S3 备份目标 + +我们建议你使用 `S3` 备份目标。你可以将快照存储在外部 S3 兼容的后端上。由于快照不存储在本地，因此即使丢失所有 etcd 节点，你仍然可以还原集群。 + +虽然 `S3` 比本地备份具有优势，但它需要额外的配置。 + +:::caution + +如果你使用 S3 备份目标，请确保每个集群都有自己的存储桶或文件夹。Rancher 将使用集群配置的 S3 存储桶或文件夹中的可用快照来填充快照信息。 + +::: + +| 选项 | 描述 | 必填 | +|---|---|---| +| S3 存储桶名称 | 用于存储备份的 S3 存储桶名称 | * | +| S3 区域 | 备份存储桶的 S3 区域 | | +| S3 区域端点 | 备份存储桶的 S3 区域端点 | * | +| S3 访问密钥 | 有权访问备份存储桶的 S3 访问密钥 | * | +| S3 密文密钥 | 有权访问备份存储桶的 S3 密文密钥 | * | +| 自定义 CA 证书 | 用于访问私有 S3 后端的自定义证书 | + +### 为 S3 使用自定义 CA 证书 + +备份快照可以存储在自定义 `S3` 备份中，例如 [minio](https://min.io/)。如果 S3 后端使用自签名或自定义证书，请使用`自定义 CA 证书`选项来提供自定义证书，从而连接到 S3 后端。 + +### 在 S3 中存储快照的 IAM 支持 + +除了使用 API 凭证之外，`S3` 备份目标还支持对 AWS API 使用 IAM 身份验证。IAM 角色会授予应用在对 S3 存储进行 API 调用时的临时权限。要使用 IAM 身份验证，必须满足以下要求： + +- 集群 etcd 节点必须具有实例角色，该角色具有对指定备份存储桶的读/写访问权限。 +- 集群 etcd 节点必须对指定的 S3 端点具有网络访问权限。 +- Rancher Server worker 节点必须具有实例角色，该实例角色具有对指定备份存储桶的读/写访问权限。 +- Rancher Server worker 节点必须对指定的 S3 端点具有网络访问权限。 + +要授予应用对 S3 的访问权限，请参阅[使用 IAM 角色向在 Amazon EC2 实例上运行的应用授予权限](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use_switch-role-ec2.html)的 AWS 文档。 + +## 查看可用快照 + +Rancher UI 中提供了集群所有可用快照的列表： + +1. 在左上角，单击 **☰ > 集群管理**。 +1. 在**集群**页面中，转到要查看快照的集群并单击其名称。 +1. 单击**快照**选项卡来查看已保存快照的列表。这些快照包括创建时间的时间戳。 + +## 安全时间戳（RKE） + +快照文件带有时间戳，从而简化使用外部工具和脚本处理文件的过程。但在某些与 S3 兼容的后端中，这些时间戳无法使用。 + +添加了选项 `safe_timestamp` 以支持兼容的文件名。当此标志设置为 `true` 时，快照文件名时间戳中的所有特殊字符都将被替换。 + +此选项不能直接在 UI 中使用，只能通过`以 YAML 文件编辑`使用。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/back-up-rancher.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/back-up-rancher.md new file mode 100644 index 00000000000..b113fda1c5e --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/back-up-rancher.md @@ -0,0 +1,92 @@ +--- +title: 备份 Rancher +--- + +在本节中，你将学习如何备份运行在任何 Kubernetes 集群上的 Rancher。要备份通过 Docker 安装的 Rancher，请参见[单节点备份](back-up-docker-installed-rancher.md)。 + +`backup-restore` operator 需要安装在 local 集群上，并且只对 Rancher 应用进行备份。备份和恢复操作仅在本地 Kubernetes 集群中执行。 + +请知悉，`rancher-backup` operator 的 2.x.x 版本用于 Rancher v2.6.x。 + +:::caution + +当把备份恢复到一个新的 Rancher 设置中时，新设置的版本应该与备份的版本相同。在恢复备份时还应考虑 Kubernetes 的版本，因为集群中支持的 apiVersion 和备份文件中的 apiVersion 可能不同。 + +::: + +## 先决条件 + +Rancher 必须是 2.5.0 或更高版本。 + +请参见[此处](migrate-rancher-to-new-cluster.md#2-使用-restore-自定义资源来还原备份)获取在 Rancher 2.6.3 中将现有备份文件恢复到 v1.22 集群的帮助。 + +## 1. 安装 Rancher Backup Operator + +备份存储位置是 operator 级别的设置，所以需要在安装或升级 `rancher backup` 应用时进行配置。 + +备份文件的格式是 `.tar.gz`。这些文件可以推送到 S3 或 Minio，也可以存储在一个持久卷中。 + +1. 在左上角，单击 **☰ > 集群管理**。 +1. 在**集群**页面上，转到 `local` 集群并单击 **Explore**。Rancher Server 运行在 `local` 集群中。 +1. 单击 **Apps > Charts**。 +1. 点击 **Rancher 备份**。 +1. 单击**安装**。 +1. 配置默认存储位置。如需获取帮助，请参见[存储配置](../../../reference-guides/backup-restore-configuration/storage-configuration.md)。 +1. 单击**安装**。 + +:::note + +使用 `backup-restore` operator 执行恢复后，Fleet 中会出现一个已知问题：用于 `clientSecretName` 和 `helmSecretName` 的密文不包含在 Fleet 的 Git 仓库中。请参见[此处](../../../integrations-in-rancher/fleet/overview.md#故障排除)获得解决方法。 + +::: + +## 2. 执行备份 + +要执行备份，必须创建 Backup 类型的自定义资源。 + +1. 在左上角，单击 **☰ > 集群管理**。 +1. 在**集群**页面上，转到 `local` 集群并单击 **Explore**。 +1. 在左侧导航栏中，点击 **Rancher 备份 > 备份**。 +1. 单击**创建**。 +1. 使用表单或 YAML 编辑器创建 Backup。 +1. 要使用该表单配置 Backup 详细信息，请单击**创建**，然后参见[配置参考](../../../reference-guides/backup-restore-configuration/backup-configuration.md)和[示例](../../../reference-guides/backup-restore-configuration/examples.md#备份)进行操作。 +1. 要使用 YAML 编辑器，单击**创建 > 使用 YAML 文件创建**。输入 Backup YAML。这个示例 Backup 自定义资源将在 S3 中创建加密的定期备份。这个应用使用 `credentialSecretNamespace` 值来确定在哪里寻找 S3 备份的密文： + + ```yaml + apiVersion: resources.cattle.io/v1 + kind: Backup + metadata: + name: s3-recurring-backup + spec: + storageLocation: + s3: + credentialSecretName: s3-creds + credentialSecretNamespace: default + bucketName: rancher-backups + folder: rancher + region: us-west-2 + endpoint: s3.us-west-2.amazonaws.com + resourceSetName: rancher-resource-set + encryptionConfigSecretName: encryptionconfig + schedule: "@every 1h" + retentionCount: 10 + ``` + + :::note + + 使用 YAML 编辑器创建 Backup 资源时，`resourceSetName` 必须设置为 `rancher-resource-set`。 + + ::: + + 如需获得配置 Backup 的帮助，请参见[配置参考](../../../reference-guides/backup-restore-configuration/backup-configuration.md)和[示例](../../../reference-guides/backup-restore-configuration/examples.md#备份)。 + + :::caution + + `rancher-backup` operator 不保存 `EncryptionConfiguration` 文件。创建加密备份时，必须保存 `EncryptionConfiguration` 文件的内容，而且在使用备份还原时必须使用同一个文件。 + + ::: + +1. 单击**创建**。 + +**结果**：备份文件创建在 Backup 自定义资源中配置的存储位置中。执行还原时使用该文件的名称。 + diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/back-up-restore-usage-guide.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/back-up-restore-usage-guide.md new file mode 100644 index 00000000000..03b4a704185 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/back-up-restore-usage-guide.md @@ -0,0 +1,129 @@ +--- +title: 备份恢复使用指南 +--- + +Rancher Backups Chart 是我们的灾难恢复和迁移解决方案。此 Chart 用于备份 Kubernetes 资源并将其保存到各种持久存储位置。 + +这个 Chart 是一个非常简单的工具，适用于 Rancher 生态系统的许多不同领域。但是，也因此出现了未记录功能的边缘用例。本文档旨在强调 Rancher Backups 正确的用法，并讨论我们遇到的一些边缘情况。 + +## 功能概述 + +### 备份 + +该 Operator 将 Chart 中的 resourceSet 捕获的所有资源收集为内存中的非结构化对象。收集资源后，资源的 tar 包将保存为 JSON 格式的清单集合，然后上传到用户定义的对象存储。该备份可以按重复计划进行，也可以进行加密。由于某些资源是敏感的，并且值以未加密的明文形式存储，因此此加密选项很重要。 + +有关配置备份的选项（包括加密），请参阅[备份配置文档](../../../reference-guides/backup-restore-configuration/backup-configuration.md)。 + +:::note + +如[备份 Rancher 文档](./back-up-rancher.md)所述，你必须手动保存加密配置文件的内容，因为 Operator **不会**备份它。 + +::: + +### 还原 + +有两种主要的还原场景：还原正在运行 Rancher 的集群以及还原新集群。只有将备份还原到该备份的源集群，且在还原过程中启用了 [`prune` 选项](../../../reference-guides/backup-restore-configuration/restore-configuration.md#还原过程中修剪)时，你才能还原正在运行 Rancher 的集群。还原具有与备份类似的输入。它需要备份文件名、encryptionConfigSecret 名称和存储位置。 + +资源按以下顺序还原： + +1. 自定义资源定义（CRD） +2. 集群范围资源 +3. 命名空间资源 + +有关配置还原的选项，请参阅[还原配置文档](../../../reference-guides/backup-restore-configuration/restore-configuration.md)。 + +### 资源集 + +ResourceSet 确定了 backup-restore-operator 在备份中收集哪些资源。它是一组 ResourceSelector，使用键/值对匹配、正则表达式匹配或 Kubernetes 客户端 labelSelector 来定义选择要求。 + +以下是可用于 resourceSelector 的字段： + +- apiVersion +- excludeKinds +- excludeResourceNameRegexp +- kinds +- kindsRegexp +- labelSelectors +- namespaceRegexp +- namespaces +- resourceNameRegexp +- resourceNames + +Rancher Backups Chart 包含了一个[默认 resourceSet](https://github.com/rancher/backup-restore-operator/tree/release/v3.0/charts/rancher-backup/files/default-resourceset-contents)，它是安装 Chart 时附加到一个大型 resourceSet 的 YAML 文件组合。文件顺序并不重要。不同版本的 resourceSet 可能有所不同。 + +:::caution + +如果你希望编辑 resourceSet，请在安装 Chart 之前进行**编辑**。 + +::: + +## 正确使用 + +本节概述了如何根据用例正确使用 Rancher Backups Chart。 + +### 所有案例 + +- Rancher Backups 必须安装在 local 集群上。 + - 注意：Rancher Backups 只会处理安装了它的集群。它可能会还原 local 集群上的集群资源，但不会联系或备份下游集群。 +- 要还原的 Rancher 版本必须与备份中的 Rancher 版本匹配。 +- 由于你可能需要还原已过时的资源（要还原的 Kubernetes 版本已弃用的资源），因此你需要考虑 Kubernetes 版本。 + +### 备份 + +- 用户生成的某些资源不会被备份，除非这些资源可以被默认 resourceSet 捕获，或者 resourceSet 已被更改为捕获这些资源。 + - 我们提供了一个 `resources.cattle.io/backup:true` 标签，将该标签添加到任何命名空间中的 Secret 时，命名空间将被备份。 +- 备份是不可改变的 +- 仅备份 local 集群 + +### 还原 + +- 还原是指将备份还原到原来的集群。可以在安装了 Rancher 的情况下进行（**必须启用 prune**），也可以在未安装 Rancher 的情况下进行（无特殊说明）。 +- 还原时需要注意的一件事是，你可能需要“擦除”集群中的所有 Rancher 资源。你可以通过将 [Rancher cleanup script](https://github.com/rancher/rancher-cleanup) 脚本作为 job 部署到集群来完成这点。这样，你可以再次安装 Rancher Backups 并还原到全新的集群。 + - 确保使用了 kubectl 来部署脚本。 + +### 迁移 + +由于我们要还原到不同的集群，因此对应的迁移有一些细微差别。以下是需要记住但又容易被忘记的事情。 + +- 迁移时 Rancher 域必须相同。换言之，你旧集群的域名现在必须指向新集群。 +- Rancher **不应该**已运行在你要迁移到的集群，这可能会导致 Rancher 备份和某些 Rancher 服务出现许多问题。 +- **还原备份后**，安装与备份**相同**的 Rancher 版本。 +- 在其他 Kubernetes 版本上配置新集群可能会出现各种不受支持的情况，这是因为可用的 Kubernetes API 可能与你备份的 API 不同。这可能会导致已弃用的资源被恢复，从而导致问题。 +- 在迁移期间**不要**执行任何升级操作。 + +## 边缘案例和不当使用 + +以下是 Rancher Backups 的一些**不当**使用示例。 + +### 升级 + +- 使用 Rancher Backups 来升级 Rancher 版本不是一个有效用法。推荐的做法是：先备份当前版本，然后按照[说明](../../../getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/upgrades.md)升级你的 Rancher 实例，在升级完成后再进行**另一个**备份。这样，如果升级失败，你就有一个可以用来还原的备份，而第二个备份将能用于还原到升级后的 Rancher 版本。 +- 使用 Rancher Backups 来升级 Kubernetes 版本也不是一个有效用法。由于 Kubernetes API 以及可用资源与版本相关，因此使用备份还原的方法来进行升级可能会导致资源集不对齐的问题，这些资源可能已被弃用、不受支持或已更新。升级集群版本的方式取决于其配置方式，但建议使用上述的流程（备份、升级、备份）。 + +### ResourceSet + +- 由于不同团队的资源和服务会不断发展，开发人员应要注意是否需要向默认 resourceSet 添加或删除新资源。 +- Rancher Backups 仅备份默认 resourceSet 捕获的内容（除非进行编辑）。我们为用户创建的 Secret 添加了特定标签，无论 Secret 的名称是什么，无论它属于哪个命名空间，具有该标签 Secret 都会被备份（请参阅[备份的正确用法](#备份)）。 + +### 下游集群 + +- Rancher Backups **仅**备份 local 集群上的 Kubernetes 资源。换言之，除了存在于 local 集群中的资源，下游集群**不会**被触及或备份。下游集群的更新和通信由 rancher-agent 和 rancher-webhook 负责。 + +### 还原已删除的资源 + +- 有些资源会产生外部结果，例如会配置下游集群。删除下游集群并还原 local 集群上的集群资源**不会**导致 Rancher 重新配置所述集群。某些资源可能无法通过还原回到可用状态。 +- “还原已删除的集群”**不是**受支持的功能。涉及下游集群时，无论集群是配置的还是导入的，删除集群都会执行一系列清理任务，导致我们无法还原已删除的集群。配置的集群节点以及与 Rancher 相关的配置资源将被销毁，而导入的集群的 Rancher Agent 以及与 local 集群注册相关的其他资源/服务可能会被销毁。 + +:::caution + +尝试删除和还原下游集群可能会导致 Rancher、Rancher Backups、rancher-webhook、Fleet 等出现各种问题。因此，我们不建议你这样做。 + +::: + +### Fleet、Harvester 和其他服务 + +由 Rancher Backups 支持的其他服务会经常发生变化和发展。发生这种情况时，他们的资源和备份需求也可能会发生变化。有些资源可能根本不需要备份。团队需要在开发过程中考虑这一点，并评估相关 resourceSet 是否能正确捕获正确的资源集来还原其服务。 + +## 结论 + +Rancher Backups 是一个非常有用的工具，但它的使用范围和使用目的有限的。为了避免出现问题，请遵循本文所述的流程来确保 Chart 能正确运作。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/backup-restore-and-disaster-recovery.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/backup-restore-and-disaster-recovery.md new file mode 100644 index 00000000000..d99c8f91f92 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/backup-restore-and-disaster-recovery.md @@ -0,0 +1,100 @@ +--- +title: 备份和灾难恢复 +keywords: [rancher 备份还原, rancher 备份与恢复, 备份恢复 rancher, rancher 备份与恢复 rancher] +--- + + + + + +在本节中，你将学习如何创建 Rancher 的备份，如何从备份中恢复 Rancher，以及如何将 Rancher 迁移到新的 Kubernetes 集群。 + +`rancher-backup` operator 可以用来备份和恢复任何 Kubernetes 集群上的 Rancher。这个应用是一个 Helm Chart，可以通过 Rancher 的 **Apps** 页面或使用 Helm CLI 部署。你可以访问[本页面](https://github.com/rancher/charts/tree/release-v2.6/charts/rancher-backup)获取 `rancher-backup` Helm Chart。 + +backup-restore operator 需要安装在 local 集群上，并且只对 Rancher 应用进行备份。备份和恢复操作仅在本地 Kubernetes 集群中执行。 + + +## 备份和恢复 Docker 安装的 Rancher + +对于使用 Docker 安装的 Rancher，请参见[备份](back-up-docker-installed-rancher.md)和[恢复](restore-docker-installed-rancher.md)对 Rancher 进行备份和恢复。 + +## 备份和恢复原理 + +`rancher-backup` operator 引入了三个自定义资源，分别是 Backups、Restores 和 ResourceSets。将以下集群范围的自定义资源定义添加到集群中： + +- `backups.resources.cattle.io` +- `resourcesets.resources.cattle.io` +- `restores.resources.cattle.io` + +ResourceSet 定义了需要备份哪些 Kubernetes 资源。由于备份 Rancher 所需的值是预设的，因此 ResourceSet 无法通过 Rancher UI 进行配置。请不要修改此 ResourceSet。 + +在创建 Backup 自定义资源时，`rancher-backup` operator 调用 `kube-apiserver` 来获取 Backup 自定义资源引用的 ResourceSet（即预设的 `rancher-resource-set`）资源。 + +然后，operator 以 .tar.gz 格式创建备份文件，并将其存储在 Backup 资源中配置的位置。 + +在创建 Restore 自定义资源时，operator 访问 Restore 指定的 tar.gz 备份文件，并从该文件恢复应用。 + +你可以使用 Rancher UI 或 `kubectl apply` 来创建 Backup 和 Restore 自定义资源。 + +:::note + +请参见[此处](migrate-rancher-to-new-cluster.md#2-使用-restore-自定义资源来还原备份)获取在 Rancher 2.6.3 中将现有备份文件恢复到 v1.22 集群的帮助。 + +::: + +## 安装 rancher-backup operator + +你可以使用 Rancher UI 或 Helm CLI 来安装 `rancher-backup` operator。两种安装方法都将 `rancher-backup` Helm Chart 安装在运行 Rancher Server 的 Kubernetes 集群上。它是集群管理员独有的功能，仅适用于 **local** 集群。（*如果你在 Rancher UI 中没有看到 `rancher-backup`，你可能选择了错误的集群。*） + +:::note + +使用 backup-restore-operator 执行恢复后，Fleet 中会出现一个已知问题：用于 clientSecretName 和 helmSecretName 的密文不包含在 Fleet 的 Git 仓库中。请参见[此处](../../../integrations-in-rancher/fleet/overview.md#故障排除)获得解决方法。 + +::: + +### 使用 Rancher UI 安装 rancher-backup + +1. 在左上角，单击 **☰ > 集群管理**。 +1. 在**集群**页面上，转到 `local` 集群并单击 **Explore**。 +1. 在左侧导航栏中，单击 **Apps > Charts**。 +1. 点击 **Rancher 备份**。 +1. 单击**安装**。 +1. 可选：配置默认存储位置。如需获取帮助，请参见[配置](../../../reference-guides/backup-restore-configuration/storage-configuration.md)。 +1. 单击**安装**。 + +**结果**：`rancher-backup` operator 已安装。 + +在**集群仪表板**中，你可以看到列在 **Deployments** 下的 `rancher-backup` operator。 + +如果需要在 Rancher 中配置备份应用，在左侧导航栏中单击 **Rancher 备份**。 + +### RBAC + +只有 Rancher 管理员和本地集群的所有者可以： + +* 安装 Chart +* 看到 Backup 和 Restore CRD 的导航链接 +* 通过分别创建 Backup CR 和 Restore CR 执行备份和恢复 +* 列出目前已执行的备份和恢复操作 + +## 备份 Rancher + +备份是通过创建 Backup 自定义资源实现的。如需查看教程，请参见[本页面](back-up-rancher.md)。 + +## 还原 Rancher + +还原是通过创建 Restore 自定义资源实现的。如需查看教程，请参见[本页面](restore-rancher.md)。 + +## 将 Rancher 迁移到新集群 + +你可以按照[这些步骤](migrate-rancher-to-new-cluster.md)执行迁移。 + +## 默认存储位置配置 + +配置一个用户保存备份文件的默认存储位置。有多种选项可以配置，例如将与 S3 兼容的对象存储作为单个备份文件的存储后端，或在安装 `backup-restore-operator` Helm Chart 时选择一个现有的 `StorageClass`。你还可以选择在每次备份时覆盖配置的存储位置，但这仅限于使用与 S3 兼容的对象存储或 Minio 对象存储。 + +如需了解各个选项的配置，请参见[本页面](../../../reference-guides/backup-restore-configuration/storage-configuration.md)。 + +### 示例 YAML 文件：Rancher Backup Helm Chart + +当使用 Helm CLI 安装时，可以使用示例 [values.yaml 文件](../../../reference-guides/backup-restore-configuration/storage-configuration.md#rancher-backup-helm-chart-的示例-valuesyaml) 来配置 `rancher-backup-operator`。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/migrate-rancher-to-new-cluster.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/migrate-rancher-to-new-cluster.md new file mode 100644 index 00000000000..4bc78b9cd40 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/migrate-rancher-to-new-cluster.md @@ -0,0 +1,183 @@ +--- +title: 将 Rancher 迁移到新集群 +--- + +如果你要将 Rancher 迁移到一个新的 Kubernetes 集群，先不要在新集群上安装 Rancher。这是因为如果将 Rancher 还原到已安装 Rancher 的新集群，可能会导致问题。 + +## 先决条件 + +以下说明假设你已经完成[备份创建](back-up-rancher.md)，并且已经安装了用于部署 Rancher 的新 Kubernetes 集群。 + +:::caution + +你需要使用与第一个集群中设置的 Server URL 相同的主机名。否则，下游集群会在 UI 的管理页面显示为不可用，并且你不能点击集群内或集群的 **Explore** 按钮。 + +::: + +Rancher 必须是 2.5.0 或更高版本。 + +Rancher 可以安装到任意 Kubernetes 集群上，包括托管的 Kubernetes 集群（如 Amazon EKS 集群）。如需获取安装 Kubernetes 的帮助，请参见 Kubernetes 发行版的文档。你也可以使用以下 Rancher 的 Kubernetes 发行版： + +- [RKE Kubernetes 安装文档](https://rancher.com/docs/rke/latest/en/installation/) +- [K3s Kubernetes 安装文档](https://rancher.com/docs/k3s/latest/en/installation/) + +## 1. 安装 rancher-backup Helm Chart + +安装 [rancher-backup chart](https://github.com/rancher/backup-restore-operator/tags)，请使用 2.x.x 主要版本内的版本： + +1. 添加 helm 仓库： + + ```bash + helm repo add rancher-charts https://charts.rancher.io + helm repo update + ``` + +1. 使用 2.x.x rancher-backup 版本设置 `CHART_VERSION` 变量： + ```bash + helm search repo --versions rancher-charts/rancher-backup + CHART_VERSION=<2.x.x> + ``` + +1. 安装 Chart： + ```bash + helm install rancher-backup-crd rancher-charts/rancher-backup-crd -n cattle-resources-system --create-namespace --version $CHART_VERSION + helm install rancher-backup rancher-charts/rancher-backup -n cattle-resources-system --version $CHART_VERSION + ``` + + :::note + + 以上假设你的环境具有到 Docker Hub 的出站连接。 + + 对于**离线环境**，在安装 rancher-backup Helm Chart 时，使用下面的 Helm 值从你的私有镜像仓库中拉取 `backup-restore-operator` 和 `kubectl` 镜像。 + + ```bash + --set image.repository /rancher/backup-restore-operator --set global.kubectl.repository=/rancher/kubectl + ``` + + ::: + +## 2. 使用 Restore 自定义资源来还原备份 + +:::note 重要提示： + +Kubernetes v1.22 是 Rancher 2.6.3 的实验功能，不支持使用 apiVersion `apiextensions.k8s.io/v1beta1`来还原包含 CRD 文件的备份文件。在 v1.22 中，`rancher-backup` 应用的默认 `resourceSet` 只收集使用 `apiextensions.k8s.io/v1` 的 CRD。你可以通过下面两种方法解决这个问题。 + +1. 使用 apiVersion v1 来更新默认 `resourceSet`，从而收集 CRD。 +1. 使用 `apiextensions.k8s.io/v1` 作为替代，来更新默认 `resourceSet` 和客户端，从而在内部使用新的 API。 + + :::note + + 在为 v1.22 版本制作或恢复备份时，Rancher 版本和本地集群的 Kubernetes 版本应该是一样的。由于集群中支持的 apiVersion 和备份文件中的 apiVersion 可能不同，因此在还原备份时请考虑 Kubernetes 的版本。 + + ::: + +::: + +1. 在使用 S3 对象存储作为需要使用凭证的还原的备份源时，请在此集群中创建一个 `Secret` 对象以添加 S3 凭证。Secret 数据必须有两个密钥，分别是包含 S3 凭证的 `accessKey` 和 `secretKey`。 + + 你可以在任何命名空间中创建 Secret，本示例使用 default 命名空间。 + + ```bash + kubectl create secret generic s3-creds \ + --from-literal=accessKey= \ + --from-literal=secretKey= + ``` + + :::note + + 在上面的命令中添加你的 Access Key 和 Secret Key 作为 `accessKey` 和 `secretKey` 的值。 + + ::: + +1. 创建一个 `Restore` 对象： + + 在迁移期间，`prune` 必须设置为 `false`。请参见下面的示例： + + ```yaml + # restore-migration.yaml + apiVersion: resources.cattle.io/v1 + kind: Restore + metadata: + name: restore-migration + spec: + backupFilename: backup-b0450532-cee1-4aa1-a881-f5f48a007b1c-2020-09-15T07-27-09Z.tar.gz + // highlight-next-line + prune: false + // highlight-next-line + encryptionConfigSecretName: encryptionconfig + storageLocation: + s3: + credentialSecretName: s3-creds + credentialSecretNamespace: default + bucketName: backup-test + folder: ecm1 + region: us-west-2 + endpoint: s3.us-west-2.amazonaws.com + ``` + + :::note 重要提示： + + 只有在创建备份时启用了加密功能时，才需要设置 `encryptionConfigSecretName` 字段。 + + 如果适用，请提供包含加密配置文件的 `Secret` 对象的名称。如果你只有加密配置文件，但没有在此集群中创建 Secret，请按照以下步骤创建 Secret。 + + 1. 创建[加密配置文件](../../../reference-guides/backup-restore-configuration/backup-configuration.md#加密) + 1. 下面的命令使用一个名为 `encryption-provider-config.yaml` 的文件，使用了 `--from-file` 标志。将 `EncryptionConfiguration` 保存到名为 `encryption-provider-config.yaml` 的文件中之后，运行以下命令： + + ```bash + kubectl create secret generic encryptionconfig \ + --from-file=./encryption-provider-config.yaml \ + -n cattle-resources-system + ``` + + ::: + +1. 应用清单，并监控 Restore 的状态： + 1. 应用 `Restore` 对象资源： + + ```bash + kubectl apply -f restore-migration.yaml + ``` + + 1. 观察 Restore 的状态： + ```bash + kubectl get restore + ``` + + 1. 查看恢复日志： + ```bash + kubectl logs -n cattle-resources-system --tail 100 -f -l app.kubernetes.io/instance=rancher-backup + ``` + + 1. Restore 资源的状态变成 `Completed` 后，你可以继续安装 cert-manager 和 Rancher。 + +## 3. 安装 cert-manager + +按照在 Kubernetes 上安装 cert-manager的步骤[安装 cert-manager](../../../getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/install-upgrade-on-a-kubernetes-cluster.md#4-安装-cert-manager)。 + +## 4. 使用 Helm 安装 Rancher + +使用与第一个集群上使用的相同版本的 Helm 来安装 Rancher： + +```bash +helm install rancher rancher-latest/rancher \ + --namespace cattle-system \ + --set hostname= \ + --version x.y.z +``` + +:::note + +如果原始的 Rancher 环境正在运行，你可以使用 kubeconfig 为原始环境收集当前值： + +```bash +helm get values rancher -n cattle-system -o yaml > rancher-values.yaml +``` + +你可以使用 `rancher-values.yaml` 文件来复用这些值。确保将 kubeconfig 切换到新的 Rancher 环境。 + +```bash +helm install rancher rancher-latest/rancher -n cattle-system -f rancher-values.yaml --version x.y.z +``` + +::: \ No newline at end of file diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/restore-docker-installed-rancher.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/restore-docker-installed-rancher.md new file mode 100644 index 00000000000..b491321f2bf --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/restore-docker-installed-rancher.md @@ -0,0 +1,72 @@ +--- +title: 恢复备份 - Docker 安装 +--- + +如果遇到灾难情况，你可以将 Rancher Server 恢复到最新的备份。 + +## 在你开始前 + +在恢复备份的过程中，你将输入一系列命令。请使用环境中的数据替换占位符。占位符用尖括号和大写字母（如 ``）表示。以下是带有占位符的命令示例： + +``` +docker run --volumes-from -v $PWD:/backup \ +busybox sh -c "rm /var/lib/rancher/* -rf && \ +tar pzxvf /backup/rancher-data-backup--" +``` + +在此命令中，`` 和 `-` 是用于 Rancher 部署的环境变量。 + +请交叉参考下方的图片和表格，了解获取此占位符数据的方法。在开始以下步骤之前，请先记下或复制此信息。 + +终端 docker ps 命令，显示如何找到 <RANCHER_CONTAINER_TAG> 和 <RANCHER_CONTAINER_NAME> + +![占位符参考](/img/placeholder-ref.png) + +| 占位符 | 示例 | 描述 | +| -------------------------- | -------------------------- | --------------------------------------------------------- | +| `` | `v2.0.5` | 首次安装拉取的 rancher/rancher 镜像。 | +| `` | `festive_mestorf` | 你的 Rancher 容器的名称。 | +| `` | `v2.0.5` | Rancher 备份的版本号。 | +| `` | `9-27-18` | 数据容器或备份的创建日期。 | +
+ +可以通过远程连接登录到 Rancher Server 所在的主机并输入命令 `docker ps` 以查看正在运行的容器，从而获得 `` 和 ``。你还可以运行 `docker ps -a` 命令查看停止了的容器。在创建备份期间，你随时可以运行这些命令来获得帮助。 + +## 恢复备份 + +使用你之前创建的[备份](back-up-docker-installed-rancher.md)，将 Rancher 恢复到最后已知的健康状态。 + +1. 使用远程终端连接，登录到运行 Rancher Server 的节点。 + +1. 停止当前运行 Rancher Server 的容器。将 `` 替换为 Rancher 容器的名称： + + ``` + docker stop + ``` +1. 将你在[创建备份 - Docker 安装](back-up-docker-installed-rancher.md)时创建的备份压缩包移动到 Rancher Server。切换到你将其移动到的目录。输入 `dir` 以确认它在该位置。 + + 如果你遵循了我们在[创建备份 - Docker 安装](back-up-docker-installed-rancher.md)中推荐的命名方式，它的名称会与 `rancher-data-backup--.tar.gz` 类似。 + +1. 输入以下命令删除当前状态数据，并将其替换为备份数据。请替换占位符。不要忘记关闭引号。 + + :::danger + + 该命令将删除 Rancher Server 容器中的所有当前状态数据。创建备份压缩包后保存的任何更改都将丢失。 + + ::: + + ``` + docker run --volumes-from -v $PWD:/backup \ + busybox sh -c "rm /var/lib/rancher/* -rf && \ + tar pzxvf /backup/rancher-data-backup--.tar.gz" + ``` + + **步骤结果**：屏幕上将运行命令流。 + +1. 重新启动 Rancher Server 容器，替换占位符。Rancher Server 将使用你的备份数据重新启动。 + + ``` + docker start + ``` + +1. 等待片刻，然后在浏览器中打开 Rancher。确认还原成功，并且你的数据已恢复。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/restore-rancher-launched-kubernetes-clusters-from-backup.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/restore-rancher-launched-kubernetes-clusters-from-backup.md new file mode 100644 index 00000000000..fc8066fe879 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/restore-rancher-launched-kubernetes-clusters-from-backup.md @@ -0,0 +1,129 @@ +--- +title: 使用备份恢复集群 +--- + +你可以轻松备份和恢复 [Rancher 启动的 Kubernetes 集群](../launch-kubernetes-with-rancher/launch-kubernetes-with-rancher.md)的 etcd。etcd 数据库的快照会保存在 etcd 节点或 S3 兼容目标上。配置 S3 的好处是，如果所有 etcd 节点都丢失了，你的快照会保存到远端并能用于恢复集群。 + +Rancher 建议启用 [etcd 定期快照的功能](back-up-rancher-launched-kubernetes-clusters.md#配置定期快照)，但你也可以轻松创建[一次性快照](back-up-rancher-launched-kubernetes-clusters.md#单次快照)。Rancher 允许使用[保存的快照](#使用快照恢复集群)进行恢复。如果你没有任何快照，你仍然可以[恢复 etcd](#在没有快照的情况下恢复-etcdrke)。 + +集群也可以恢复到之前的 Kubernetes 版本和集群配置。 + +## 查看可用快照 + +Rancher UI 中提供了集群所有可用快照的列表： + +1. 在左上角，单击 **☰ > 集群管理**。 +1. 在**集群**页面中，转到要查看快照的集群并点击集群名称。 +1. 单击**快照**选项卡。列出的快照包括创建时间的时间戳。 + +## 使用快照恢复集群 + +如果你的 Kubernetes 集群已损坏，你可以使用快照来恢复集群。 + +快照由 etcd 中的集群数据、Kubernetes 版本和 `cluster.yml` 中的集群配置组成。有了这些组件，你可以在使用快照恢复集群时选择： + +- **仅恢复 etcd 内容**：类似于在 Rancher v2.4.0 之前版本中的使用快照恢复。 +- **恢复 etcd 和 Kubernetes 版本**：如果 Kubernetes 升级导致集群失败，并且你没有更改任何集群配置，则应使用此选项。 +- **恢复 etcd、Kubernetes 版本和集群配置**：如果你在升级时同时更改了 Kubernetes 版本和集群配置，则应使用此选项。 + +回滚到之前的 Kubernetes 版本时，[升级策略选项](../../../getting-started/installation-and-upgrade/upgrade-and-roll-back-kubernetes.md#配置升级策略)会被忽略。在恢复到旧 Kubernetes 版本之前，Worker 节点不会被封锁或清空，因此可以更快地将不健康的集群恢复到健康状态。 + +:::note 先决条件： + +要恢复 S3 中的快照，需要将集群配置为[在 S3 上创建定期快照](back-up-rancher-launched-kubernetes-clusters.md#配置定期快照)。 + +::: + +1. 在左上角，单击 **☰ > 集群管理**。 +1. 在**集群**页面中，转到要查看快照的集群并点击集群名称。 +1. 单击**快照**选项卡来查看已保存快照的列表。 +1. 转到要恢复的快照，然后单击 **⋮ > 还原**。 +1. 选择一个**还原类型**。 +1. 点击**还原**。 + +**结果**：集群将进入 `updating` 状态，然后将开始使用快照恢复 `etcd` 节点。集群会在返回到 `active` 状态后被恢复。 + +## Control Plane/etcd 完全不可用时使用快照还原集群 + +在灾难恢复场景中，下游集群中 Rancher 管理的 Control Plane 和 etcd 节点可能不再可用或运行。你可以通过再次添加 Control Plane 和 etcd 节点来重建集群，然后使用可用快照来进行还原。 + + + + +请按照 [SUSE 知识库](https://www.suse.com/support/kb/doc/?id=000020695)中描述的流程进行操作。 + + + + +如果集群完全故障，则必须从集群中删除所有 etcd 节点和机器，然后才能添加新的 etcd 节点来进行还原。 + +:::note + +由于[已知问题](https://github.com/rancher/rancher/issues/41080)，此过程需要 Rancher v2.7.5 或更高版本。 + +::: + +:::note + +如果你使用[本地快照](./back-up-rancher-launched-kubernetes-clusters.md#本地备份目标)，那么请**务必**从要删除的 etcd 节点上的 `/var/lib/rancher//server/db/snapshots/` 文件夹中备份要还原的快照。你可以将快照复制到 `/var/lib/rancher//server/db/snapshots/` 文件夹中的新节点上。此外，如果使用本地快照并还原到新节点，目前还无法通过 UI 进行还原。 + +::: + +1. 从集群中删除所有 etcd 节点。 + + 1. 在左上角，单击 **☰ > 集群管理**。 + 1. 在**集群**页面中，转到要删除节点的集群。 + 1. 在**主机**选项卡中，找到要删除的每个节点并单击 **⋮ > 删除**。开始时，节点会挂在 `deleting` 状态，所有 etcd 节点都被删除后，它们将被一起删除。这是因为 Rancher 发现所有 etcd 节点都在删除，并开始 "短路" etcd 安全删除逻辑。 + +1. 删除所有 etcd 节点后，添加要用于还原的新 etcd 节点。 + + - 对于自定义集群，请转到**注册**选项卡，然后在节点上复制并运行注册命令。如果该节点之前已在集群中使用过，请先[清理该节点](../manage-clusters/clean-cluster-nodes.md#清理节点)。 + - 对于主机驱动集群，则会自动配置新节点。 + + 此时，Rancher 会提示你需要使用 etcd 快照进行还原。 + +1. 使用 etcd 快照还原。 + + - 对于 S3 快照，使用 UI 进行还原。 + 1. 单击**快照**选项卡来查看已保存快照的列表。 + 1. 转到要恢复的快照，然后单击 **⋮ > 还原**。 + 1. 选择一个**还原类型**。 + 1. 点击**还原**。 + - 对于本地快照，使用 UI 进行还原**不**可用。 + 1. 单击右上角的 **⋮> 编辑 YAML**。 + 1. 将 `spec.cluster.rkeConfig.etcdSnapshotRestore.name` 定义为 `/var/lib/rancher//server/db/snapshots/` 中磁盘上快照的文件名。 + +1. 还原成功后，你可以将 etcd 节点扩展至所需的冗余。 + + + + +## 在没有快照的情况下恢复 etcd（RKE） + +如果 etcd 节点组失去了仲裁（quorum），由于没有操作（例如部署工作负载）可以在 Kubernetes 集群中执行，Kubernetes 集群将报告失败。集群需要有三个 etcd 节点以防止仲裁丢失。如果你想恢复你的 etcd 节点集，请按照以下说明操作： + +1. 通过删除所有其他 etcd 节点，从而仅在集群中保留一个 etcd 节点。 + +2. 在剩余的单个 etcd 节点上，运行以下命令： + + ```bash + docker run --rm -v /var/run/docker.sock:/var/run/docker.sock assaflavie/runlike etcd + ``` + + 此命令会输出 etcd 要运行的命令，请保存此命令以备后用。 + +3. 停止正在运行的 `etcd` 容器并将其重命名为 `etcd-old`。 + + ```bash + docker stop etcd + docker rename etcd etcd-old + ``` + +4. 修改步骤 2 中获取保存的命令： + + - 如果你最初有超过 1 个 etcd 节点，则将 `--initial-cluster` 更改为仅包含剩余的单个节点。 + - 将 `--force-new-cluster` 添加到命令的末尾。 + +5. 运行修改后的命令。 + +6. 在单个节点启动并运行后，Rancher 建议向你的集群添加额外的 etcd 节点。如果你有一个[自定义集群](../../../reference-guides/cluster-configuration/rancher-server-configuration/use-existing-nodes/use-existing-nodes.md)，并且想要复用旧节点，则需要先[清理节点](../manage-clusters/clean-cluster-nodes.md)，然后再尝试将它们重新添加到集群中。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/restore-rancher.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/restore-rancher.md new file mode 100644 index 00000000000..b4331859f7f --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/restore-rancher.md @@ -0,0 +1,83 @@ +--- +title: 还原 Rancher +--- + +本页概述了如何使用 Rancher 执行恢复。 + +在以下情况下，请按照本页中的说明进行操作： + +- 正在运行的 Rancher 实例与备份时的版本相同。 +- 上游（本地）集群与备份的位置相同。 + +:::note 重要提示 + +在使用相同设置还原 Rancher 时，operator 将在还原开始时缩减 Rancher deployment，还原完成后又会扩展 deployment。因此，Rancher 在还原期间将不可用。 + +::: + +:::tip + +* 按照以下步骤[迁移 Rancher](migrate-rancher-to-new-cluster.md)。 +* 如果你需要在升级后将 Rancher 还原到先前版本，请参见[回滚](../../../getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/rollbacks.md)。 + +::: + +## 创建 Restore 自定义资源 + +还原是通过创建 Restore 自定义资源实现的。 + +1. 在左上角，单击 **☰ > 集群管理**。 +1. 在**集群**页面上，转到 `local` 集群并单击 **Explore**。Rancher Server 运行在 `local` 集群中。 +1. 在左侧导航栏中，单击 **Rancher 备份 > 还原**。 +1. 单击**创建**。 +1. 使用表单或 YAML 创建 Restore。如需获取使用表单创建 Restore 资源的更多信息，请参见[配置参考](../../../reference-guides/backup-restore-configuration/restore-configuration.md)和[示例](../../../reference-guides/backup-restore-configuration/examples.md)。 +1. 要使用 YAML 编辑器，单击**创建 > 使用 YAML 文件创建**。输入 Restore YAML。 + + ```yaml + apiVersion: resources.cattle.io/v1 + kind: Restore + metadata: + name: restore-migration + spec: + backupFilename: backup-b0450532-cee1-4aa1-a881-f5f48a007b1c-2020-09-15T07-27-09Z.tar.gz + encryptionConfigSecretName: encryptionconfig + storageLocation: + s3: + credentialSecretName: s3-creds + credentialSecretNamespace: default + bucketName: rancher-backups + folder: rancher + region: us-west-2 + endpoint: s3.us-west-2.amazonaws.com + ``` + + 如需获得配置 Restore 的帮助，请参见[配置参考](../../../reference-guides/backup-restore-configuration/restore-configuration.md)和[示例](../../../reference-guides/backup-restore-configuration/examples.md)。 + +1. 单击**创建**。 + +**结果**：rancher-operator 在还原过程中将 Rancher deployment 缩容，并在还原完成后将它重新扩容。资源还原顺序如下： + +1. 自定义资源定义（CRD） +2. 集群范围资源 +3. 命名空间资源 + +## 日志 + +如需查看还原的处理方式，请检查 Operator 的日志。查看日志的命令如下： + +``` +kubectl logs -n cattle-resources-system -l app.kubernetes.io/name=rancher-backup -f +``` + +## 清理 + +如果你使用 kubectl 创建了 Restore 资源，请删除该资源以防止与未来的还原发生命名冲突。 + +## 已知问题 +在某些情况下，恢复备份后，Rancher 日志会显示类似以下的错误： +``` +2021/10/05 21:30:45 [ERROR] error syncing 'c-89d82/m-4067aa68dd78': handler rke-worker-upgrader: clusters.management.cattle.io "c-89d82" not found, requeuing +``` +发生这种情况的原因是，刚刚还原的某个资源有 finalizer，但相关的资源已经被删除，导致处理程序无法找到该资源。 + +为了消除这些错误，你需要找到并删除导致错误的资源。详情请参见[此处](https://github.com/rancher/rancher/issues/35050#issuecomment-937968556)。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/helm-charts-in-rancher/create-apps.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/helm-charts-in-rancher/create-apps.md new file mode 100644 index 00000000000..b6605e51965 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/helm-charts-in-rancher/create-apps.md @@ -0,0 +1,126 @@ +--- +title: 创建应用 +--- + +:::tip + +有关开发 Chart 的完整演示，请参阅 Helm 官方文档中的 [Chart 模板开发者指南](https://helm.sh/docs/chart_template_guide/)。 + +::: + +## Chart 类型 + +Rancher 支持两种不同类型的 Chart，分别是 Helm Chart 和 Rancher Chart。 + +### Helm Chart + +原生 Helm Chart 包括一个应用以及运行它所需的软件。部署原生 Helm Chart 时，你可以在 YAML 编辑器中提供 Chart 的参数值。 + +### Rancher Chart + +Rancher Chart 是原生 helm Chart，包含两个可增强用户体验的文件 `app-readme.md` 和 `questions.yaml`。在 [Rancher Chart 的附加文件](#rancher-chart-的附加文件)中了解更多信息。 + +Rancher Chart 添加了简化的 Chart 描述和配置表单，使应用部署变得容易。Rancher 用户无需通读整个 Helm 变量列表即可了解如何启动应用。 + +## Chart 目录结构 + +你可以在基于 HTTP 的标准 Helm 仓库中提供 Helm Chart。有关更多信息，请参阅 Helm 官方文档中的 [Chart 仓库指南](https://helm.sh/docs/topics/chart_repository)。 + +或者，你可以在 Git 仓库中组织 Chart 并将其直接添加到应用市场。 + +下表演示了 Git 仓库的目录结构。`charts` 目录是仓库基础下的顶层目录。将仓库添加到 Rancher 将公开其中包含的所有 Chart。`questions.yaml`、`README.md` 和 `requirements.yml` 文件是针对于 Rancher Chart 的，但对于自定义 Chart 是可选的。 + +``` +/ + │ + ├── charts/ + │ ├── / # 这个目录名称将作为 Chart 名称出现在 Rancher UI 中。 + │ │ ├── / # 这个级别的每个目录提供了不同的应用版本，可以在 Rancher UI 的 Chart 中选择。 + │ │ │ ├── Chart.yaml # 必需的 Helm Chart 信息文件。 + │ │ │ ├── questions.yaml # 在 Rancher UI 中显示的表单问题。问题显示在配置选项中。* + │ │ │ ├── README.md # 可选：在 Rancher UI 中显示的 Helm 自述文件。此文本显示在详细说明中。 + │ │ │ ├── requirements.yml # 可选：列出 Chart 的依赖项的 YAML 文件。 + │ │ │ ├── values.yml # Chart 的默认配置值。 + │ │ │ ├── templates/ # 包含模板的目录，与 values.yml 一起能生成 Kubernetes YAML。 +``` + +## Rancher Chart 的附加文件 + +在创建你的自定义目录之前，你需要大致了解 Rancher chart 与原生 Helm chart 的区别。Rancher Chart 的目录结构与 Helm Chart 略有不同。Rancher Chart 包含两个 Helm Chart 没有的文件： + +- `app-readme.md` + + 在 Chart 的 UI 标头中提供描述性文本的文件。 + +- `questions.yml` + + 包含表单问题的文件。这些表单问题简化了 Chart 的部署。没有它，你必须使用更复杂的 YAML 配置来配置部署。下图显示了 Rancher Chart（包含 `questions.yml`）和原生 Helm Chart（不包含）之间的区别。 + +
带有 questions.yml 的 Rancher Chart（上）与 Helm Chart（下）
+ + ![questions.yml](/img/rancher-app-2.6.png) + ![values.yaml](/img/helm-app-2.6.png) + + +### Chart.yaml 注释 + +Rancher 支持你添加到 `Chart.yaml` 文件的其他注释。这些注释允许你定义应用依赖项或配置其他 UI 默认值： + +| 注解 | 描述 | 示例 | +| --------------------------------- | ----------- | ------- | +| catalog.cattle.io/auto-install | 如果设置，将在安装此 Chart 之前先安装指定 Chart 的指定版本。 | other-chart-name=1.0.0 | +| catalog.cattle.io/display-name | 要在应用市场中显示的名称，而不是 Chart 本身的名称。 | Chart 的显示名称 | +| catalog.cattle.io/namespace | 用于部署 Chart 的固定命名空间。如果设置，则用户无法更改。 | fixed-namespace | +| catalog.cattle.io/release-name | Helm 安装的固定版本名称。如果设置，则用户无法更改。 | fixed-release-name | +| catalog.cattle.io/requests-cpu | 应该在集群中保留的 CPU 总量。如果可用 CPU 资源少于该值，将显示警告。 | 2000m | +| catalog.cattle.io/requests-memory | 应该在集群中保留的内存总量。如果可用内存资源少于该值，将显示警告。 | 2Gi | +| catalog.cattle.io/os | 限制可以安装此 Chart 的操作系统。可用值：`linux`、`windows`。默认：无限制 | linux | + +### questions.yml + +`questions.yml` 中大部分是向最终用户提出的问题，但也有一部分可以在此文件中设置字段。 + +### 最低/最高 Rancher 版本 + +你可以为每个 Chart 添加最低和/或最高的 Rancher 版本，这决定了该 Chart 是否可以从 Rancher 部署。 + +:::note + +Rancher 版本带有 `v` 前缀，但是使用此选项时请*不要*包括前缀。 + +::: + +``` +rancher_min_version: 2.3.0 +rancher_max_version: 2.3.99 +``` + +### Question 变量参考 + +此参考包含可以嵌套在 `questions:` 下的 `questions.yml` 中的变量： + +| 变量 | 类型 | 必填 | 描述 | +| ------------- | ------------- | --- |------------- | +| variable | string | true | 定义 `values.yml` 文件中指定的变量名，嵌套对象使用 `foo.bar`。 | +| label | string | true | 定义 UI 标签。 | +| description | string | false | 指定变量的描述。 | +| type | string | false | 如果未指定，则默认为 `string`（支持的类型为 string、multiline、boolean、int、enum、password、storageclass、hostname、pvc 和 secret）。 | +| required | bool | false | 定义变量是否是必须的（true \| false）。 | +| default | string | false | 指定默认值。仅在 `values.yml` 文件中没有对应值时使用。 | +| group | string | false | 按输入值对问题进行分组。 | +| min_length | int | false | 最小字符长度。 | +| max_length | int | false | 最大字符长度。 | +| min | int | false | 最小整数长度。 | +| max | int | false | 最大整数长度。 | +| options | []string | false | 为 `enum` 类型的变量指定选项，例如：options:
- "ClusterIP"
- "NodePort"
- "LoadBalancer" | +| valid_chars | string | false | 输入字符验证的正则表达式。 | +| invalid_chars | string | false | 无效输入字符验证的正则表达式。 | +| subquestions | []subquestion | false | 添加一组子问题。 | +| show_if | string | false | 如果条件变量为 true，则显示当前变量。例如 `show_if: "serviceType=Nodeport"` | +| show\_subquestion_if | string | false | 如果为 true 或等于某个选项，则显示子问题。例如 `show_subquestion_if: "true"` | + +:::note + +`subquestions[]` 不能包含 `subquestions` 或 `show_subquestions_if` 键，但支持上表中的所有其他键。 + +::: diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/helm-charts-in-rancher/helm-charts-in-rancher.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/helm-charts-in-rancher/helm-charts-in-rancher.md new file mode 100644 index 00000000000..05f76f3769f --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/helm-charts-in-rancher/helm-charts-in-rancher.md @@ -0,0 +1,195 @@ +--- +title: Helm Charts 和 Apps +--- + + + + + +在本节中，你将学习如何在 Rancher 中管理 Helm Chart 仓库和应用。 + +## Helm Charts 在 Rancher 中的工作原理 + +在 Rancher 中 Helm chart 仓库是使用 **Apps** 进行管理的。 + +Rancher 使用应用商店系统导入一系列的 charts 包到仓库里，然后使用这些 charts 来部署自定义的 Kubernetes 应用程序或 Rancher 的工具，如监控（Monitoring）或 Istio。Rancher 工具预先集成进了仓库，并通过独立的 Helm chart 进行部署。如果你有自己的额外仓库只需要添加到当前的集群中就可以正常部署。 + +### Catalogs, Apps, Rancher UI + +[在 Rancher v2.4 及更早版本中](https://github.com/rancher/rancher-docs/tree/main/archived_docs/en/version-2.0-2.4/how-to-guides/new-user-guides/helm-charts-in-rancher/helm-charts-in-rancher.md), 存储部署的应用程序的仓库被称为 "catalogs"。这些仓库是通过 UI 的 **Catalogs** 进行管理的。 + +Rancher v2.5 用新的 **Apps & Marketplace** 功能替代了之前的 **应用商店**。 + +从 Rancher v2.6.5 开始, **Apps & Marketplace** 功能在 UI 中被命名为 **Apps**。 + +### Versioning Scheme + +Rancher chart 的版本设计方案主要围绕 charts 的主要版本以及与上游 charts 相关的 `+up` 注释进行设计。 + +**主要版本:** charts 的主要版本与 Rancher 的特定次要版本相关联。当你升级到新的 Rancher 次要版本时，你应该确保所有的功能 charts 也被升级对应的主版本。 + +**基于上游的 Charts:** 在升级时，确保上游 chart 的版本与你的 Rancher 版本兼容。chart 的 `+up` 注释指示 Rancher chart 正在跟踪的上游版本。例如，`100.x.x+up16.6.0` 的监控（Monitoring）跟踪上游的 kube-prometheus-stack `16.6.0` 并附带一些额外的 Rancher 补丁。 + +在升级 Rancher 版本时，不要降级你正在使用的 chart 版本。例如，如果你在 Rancher v2.5 中使用的监控版本比 `16.6.0` 还要高，你不应该升级到 `100.x.x+up16.6.0`，而是应该在下一个发布中升级到适当的版本。 + +#### 预发布版本 + +预发布版本遵循[语义化版本 2.0.0 ](https://semver.org/)的[规范](https://semver.org/#spec-item-9)。 例如，版本为 `0.1.3-dev.12ab4f` 的 Helm chart 被认为是一个预发布版本。预发布版本默认不显示，必须进行配置以显示。 + +如何显示预发布版本： + +1. 点击右上角的用户头像。 +2. 点击 **Preferences**. +3. 在 **Helm Charts** 下, 选择 **Include Prerelease Versions**. + +## 访问 Charts + +**Charts** 页面包含所有 Rancher、Rancher 合作伙伴和自定义 Chart。你可以通过选择左侧的下拉菜单来筛选 Chart： + +* Rancher 工具（例如 Logging 或 Monitoring）包含在 **Rancher** 标签下 +* Partner Chart 位于 **Partner** 标签下 +* 自定义 Chart 将显示在仓库的名称下 + +所有这三种类型都以相同的方式部署和管理。 + +:::note +由 Cluster Manager （旧版 Rancher UI 中的全局视图）管理的应用应继续仅由 Cluster Manager 管理，而在新 UI 中使用 Apps 管理的应用则仅能由 Apps 管理。 +::: + +访问 **Charts** 页面: + +1. 点击 **☰ > Cluster Management**。 +2. 找到你想要访问 Charts 的集群名称。点击集群行末尾的 **Explore**。 +3. 在 **Cluster Dashboard** 的左侧导航菜单中, 点击 **Apps > Charts**。 + +### 管理仓库 + +**Repositories** 页面列出了你的 Helm 仓库。 这包括传统的具有 index.yaml 的 Helm 端点，以及克隆并指向特定分支的 Git 仓库。要使用自定义 Charts，在这里可以添加你的仓库。添加仓库后，你可以在 **Charts** 页面中访问自定义 Charts，这些 Charts 将列在仓库的名称下。 + +访问 **Repositories** 页面: + +1. 点击 **☰ > Cluster Management**. +2. 找到你想要访问 Charts 的集群名称。点击集群行末尾的 **Explore**。 +3. 在 **Cluster Dashboard** 的左侧导航菜单中，点击 **Apps > Repositories**。 + +### 添加自定义 Git 仓库 + +要添加一个包含你的 Helm Charts 或集群模板定义的自定义 Git 仓库： + +1. 点击 **☰ > Cluster Management**。 +2. 找到你想要访问 Charts 的集群名称。点击集群行末尾的 **Explore**。 +3. 在 **Cluster Dashboard** 的左侧导航菜单中，点击 **Apps > Repositories**。 +4. 点击 **Create**。 +5. 选择 **Git repository containing Helm chart...**。 +6. 你必须输入名称和 Git 仓库的 URL。其他配置项包括描述，都是可选的。如果你不想设置默认的分支，可以输入你想要使用的分支名称。通常，默认分支名为 `main` 或 `master`。 +7. 点击 **Create** 添加。 + +在 Rancher 中添加 Charts 仓库后，它将立即生效。 + +### 添加自定义 Helm Chart 仓库 + +你可以将自己的 Helm chart 仓库添加到 Rancher。为了能正确添加 http 的 Helm Chart 仓库，你需要提供 chart 的服务器并能够响应 GET 请求并提供 YAML 文件和 tar 包。 + +有关 Helm chart 仓库的更多信息，请参阅 [官方 Helm 文档](https://helm.sh/docs/topics/chart_repository/)。 + +要将自定义 Helm chart 仓库添加到 Rancher： + +1. 点击 **☰ > Cluster Management**。 +2. 找到你想要访问 Charts 的集群名称。点击集群行末尾的 **Explore**。 +3. 在 **Cluster Dashboard** 的左侧导航菜单中，点击 **Apps > Repositories**。 +4. 点击 **Create**。 +5. 选择 **http(s) URL to an index generated by Helm**. +6. 输入仓库名称和 chart 的 index URL 地址。 +7. 点击 **Create** 添加。 + +### 添加私有 Git/Helm Chart 仓库 + +你可以使用 SSH 密钥凭据或 HTTP 基础认证秘密（如用户名和密码）添加私有 Git 或 Helm chart 仓库。 + +### 向仓库添加私有 CA + +向 Helm chart 仓库添加私有 CA，你必须将 DER 格式的 CA 证书的 base64 编码副本添加到 Chart 仓库的 `spec.caBundle 字段`，例如 `openssl x509 -outform der -in ca.pem | base64 -w0`。无论是基于 Git 还是 HTTP 的仓库，操作步骤都是相同的 + +1. 点击 **☰**。在左侧导航菜单的 **Explore Cluster**, 选择一个集群。 +2. 在 **Cluster Dashboard** 的左侧导航菜单中，点击 **Apps > Repositories**。 +3. 找到你想要向其添加私有 CA 证书的 Git 或 HTTP 的仓库。点击 **⋮ > Edit YAML**。 +4. 设置 `caBundle` 值，如以下示例： + + ```yaml + [...] + spec: + caBundle: + MIIFXzCCA0egAwIBAgIUWNy8WrvSkgNzV0zdWRP79j9cVcEwDQYJKoZIhvcNAQELBQAwPzELMAkGA1UEBhMCVVMxCzAJBgNVBAgMAkNBMRQwEgYDVQQKDAtNeU9yZywgSW5jLjENMAsGA1UEAwwEcm9vdDAeFw0yMTEyMTQwODMyMTdaFw0yNDEwMDMwODMyMT + ... + nDxZ/tNXt/WPJr/PgEB3hQdInDWYMg7vGO0Oz00G5kWg0sJ0ZTSoA10ZwdjIdGEeKlj1NlPyAqpQ+uDnmx6DW+zqfYtLnc/g6GuLLVPamraqN+gyU8CHwAWPNjZonFN9Vpg0PIk1I2zuOc4EHifoTAXSpnjfzfyAxCaZsnTptimlPFJJqAMj+FfDArGmr4= + [...] + ``` + +:::note 带有认证的 Helm chart 仓库 + +Repo.Spec 包含一个 `disableSameOriginCheck` 值，该值允许用户绕过相同源的检查，将仓库身份认证信息作为基本 Auth 标头与所有 API 调用一起发送。不建议采用这种做法，但这可以用作非标准 Helm Chart 仓库（例如重定向到不同源 URL 的仓库）的临时解决方案。 + +要将此功能用于现有 Helm Chart 仓库，请按照前面的步骤编辑 YAML。在 YAML 文件的 `spec` 部分，添加 `disableSameOriginCheck` 并将其设置为 `true`： + +```yaml +[...] +spec: + disableSameOriginCheck: true +[...] +``` + +::: + +### Helm 兼容性 + +仅支持 Helm 3 兼容 Chart 。 + +### 部署和升级 Chart + +安装和部署 chart: + +1. 点击 **☰ > Cluster Management**。 +2. 找到你想要访问 Charts 的集群名称。点击集群行末尾的 **Explore**。 +3. 在 **Cluster Dashboard** 的左侧导航菜单中，点击 **Apps > Charts**。 +4. 选择一个 chart 点击 **Install**。 + +Rancher 和 Partner Chart 可能通过自定义页面或 questions.yaml 文件进行额外的配置，但所有 Chart 安装都可以修改 values.yaml 和其他基本设置。单击安装后，将部署一个 Helm 操作作业，并显示该作业的控制台。 + +要查看所有最近的更改，点击左侧导航栏菜单中的 **APPs > Recent Operations**。你可以查看已进行的调用、条件、事件和日志 + +安装 Chart 后，点击左侧导航栏菜单中的 **Apps > Installed Apps**。在本节中，你可以升级或删除安装，并查看更多详细信息。选择升级时，呈现的形式和数值与安装相同。 + +大多数 Rancher 工具在 **Apps** 下方的工具栏中都有额外的页面，以帮助你管理和使用这些功能。这些页面包括指向仪表板的链接、可轻松添加自定义资源的表单以及其他信息。 + +:::caution + +如果在升级前使**自定义 Helm 选项**，并且你的 Chart 中包含不可更改的字段，使用 `--force` 选项可能会导致错误。这是因为 Kubernetes 中的某些对象一旦创建就无法更改。要避免该错误，你可以： + +* 使用默认升级选项（即不要使用 `--force` 选项） +* 卸载现有 Chart 并安装升级后的 Chart +* 在执行强制升级之前删除集群中具有不可更改字段的资源 + +::: + +#### 旧版应用 + +在 **Apps > Installed Apps** 页面上，旧版应用没有升级按钮。 + +如果你想升级已安装的旧版应用， 必须启用[旧版功能](../../advanced-user-guides/enable-experimental-features/enable-experimental-features.md)。 如果你在升级 Rancher 之前已经运行了旧版应用，此标志会自动启用。 + +1. 如果尚未启用，启用[旧版功能](../../advanced-user-guides/enable-experimental-features/enable-experimental-features.md)。 +2. 点击 **☰ > Cluster Management**。 +3. 找到你想要访问 Charts 的集群名称。点击集群行末尾的 **Explore**。 +4. 点击 **Legacy > Project > Apps**. + +如果在 **Legacy > Project** 下看不到 **Apps** ,请点击顶部导航栏的 **project/namespace** 搜索栏，并从下拉菜单中选择相关项目。 + +要升级旧版多集群应用： + +1. 点击 **☰**. +2. 在 **Legacy Apps** 下点击 **Multi-cluster Apps**. + + +### 限制 + +Rancher CLI 不能用于安装仪表板应用程序或 Rancher 功能 Chart。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/infrastructure-setup/amazon-elb-load-balancer.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/infrastructure-setup/amazon-elb-load-balancer.md new file mode 100644 index 00000000000..6486e4fc4ca --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/infrastructure-setup/amazon-elb-load-balancer.md @@ -0,0 +1,175 @@ +--- +title: 设置 Amazon NLB 网络负载均衡器 +--- + +本文介绍了如何在 Amazon EC2 服务中设置 Amazon NLB 网络负载均衡器，用于将流量转发到 EC2 上的多个实例中。 + +这些示例中，负载均衡器将流量转发到三个 Rancher Server 节点。如果 Rancher 安装在 RKE Kubernetes 集群上，则需要三个节点。如果 Rancher 安装在 K3s Kubernetes 集群上，则只需要两个节点。 + +本文介绍的只是配置负载均衡器的其中一种方式。其他负载均衡器如传统负载路由器（Classic Load Balancer）和应用负载路由器（Application Load Balancer），也可以将流量转发到 Rancher Server 节点。 + +Rancher 仅支持使用 Amazon NLB 以 `TCP` 模式终止 443 端口的流量，而不支持 `TLS` 模式。这试因为在 NLB 终止时，NLB 不会将正确的标头注入请求中。如果你想使用由 Amazon Certificate Manager (ACM) 托管的证书，请使用 ALB。 + + + +## 要求 + +你已在 EC2 中创建了 Linux 实例。此外，负载均衡器会把流量转发到这些节点。 + +## 1. 创建目标组 + +首先，为 **TCP** 协议创建两个目标组，其中一个使用 TCP 端口 443，另一个使用 TCP 端口 80（用于重定向到 TCP 端口 443）。然后，将 Linux 节点添加到这些组中。 + +配置 NLB 的第一个步骤是创建两个目标组。一般来说，只需要端口 443 就可以访问 Rancher。但是，由于端口 80 的流量会被自动重定向到端口 443，因此，你也可以为端口 80 也添加一个监听器。 + +不管使用的是 NGINX Ingress 还是 Traefik Ingress Controller，Ingress 都应该将端口 80 的流量重定向到端口 443。以下为操作步骤： + +1. 登录到 [Amazon AWS 控制台](https://console.aws.amazon.com/ec2/)。确保选择的**区域**是你创建 EC2 实例 （Linux 节点）的区域。 +1. 选择**服务** > **EC2**，找到**负载均衡器**并打开**目标组**。 +1. 单击**创建目标组**，然后创建用于 TCP 端口 443 的第一个目标组。 + +:::note + +不同 Ingress 的健康检查处理方法不同。详情请参阅[本节](#nginx-ingress-和-traefik-ingress-的健康检查路径)。 + +::: + +#### 目标组（TCP 端口 443） + +根据下表配置第一个目标组： + +| 选项 | 设置 | +|-------------------|-------------------| +| 目标组名称 | `rancher-tcp-443` | +| 目标类型 | `instance` | +| 协议 | `TCP` | +| 端口 | `443` | +| VPC | 选择 VPC | + +健康检查设置： + +| 选项 | 设置 | +|---------------------|-----------------| +| 协议 | TCP | +| 端口 | `override`,`80` | +| 健康阈值 | `3` | +| 不正常阈值 | `3` | +| 超时 | `6 秒` | +| 间隔 | `10 秒` | + +单击**创建目标组**，然后创建用于 TCP 端口 80 的第二个目标组。 + +#### 目标组（TCP 端口 80） + +根据下表配置第二个目标组： + +| 选项 | 设置 | +|-------------------|------------------| +| 目标组名称 | `rancher-tcp-80` | +| 目标类型 | `instance` | +| 协议 | `TCP` | +| 端口 | `80` | +| VPC | 选择 VPC | + + +健康检查设置： + +| 选项 | 设置 | +|---------------------|----------------| +| 协议 | TCP | +| 端口 | `traffic port` | +| 健康阈值 | `3` | +| 不正常阈值 | `3` | +| 超时 | `6 秒` | +| 间隔 | `10 秒` | + +## 2. 注册目标 + +接下来，将 Linux 节点添加到两个目标组中。 + +选择名为 **rancher-tcp-443** 的目标组，点击**目标**选项卡并选择**编辑**。 + +![](/img/ha/nlb/edit-targetgroup-443.png) + +选择你要添加的实例（Linux 节点），然后单击**添加到已注册**。 + +*** +**将目标添加到目标组 TCP 端口 443**
+ +![](/img/ha/nlb/add-targets-targetgroup-443.png) + +*** +**已将目标添加到目标组 TCP 端口 443**
+ +![](/img/ha/nlb/added-targets-targetgroup-443.png) + +添加实例后，单击右下方的**保存**。 + +将 **rancher-tcp-443** 替换为 **rancher-tcp-80**，然后重复上述步骤。你需要将相同的实例作为目标添加到此目标组。 + +## 3. 创建 NLB + +使用 Amazon 的向导创建网络负载均衡器。在这个过程中，你需要添加在 [1. 创建目标组](#1-创建目标组)中创建的目标组。 + +1. 在网页浏览器中，导航到 [Amazon EC2 控制台](https://console.aws.amazon.com/ec2/)。 + +2. 在导航栏中，选择**负载均衡** > **负载均衡器**。 + +3. 单击**创建负载均衡器**。 + +4. 选择**网络负载均衡器**并单击**创建**。然后，填写每个表格。 + +- [步骤 1：配置负载均衡器](#步骤-1配置负载均衡器) +- [步骤 2：配置路由](#步骤-2配置路由) +- [步骤 3：注册目标](#步骤-3注册目标) +- [步骤 4：审核](#步骤-4审核) + +### 步骤 1：配置负载均衡器 + +在表单中设置以下字段： + +- **名称**：`rancher` +- **Scheme**：`internal` 或 `internet-facing`。实例和 VPC 的配置决定了 NLB 的 Scheme。如果你的实例没有绑定公共 IP，或者你只需要通过内网访问 Rancher，请将 NLB 的 Scheme 设置为 `internal` 而不是 `internet-facing`。 +- **监听器**：负载均衡器协议需要是 `TCP`，而且负载均衡器端口需要设为 `443`。 +- **可用区：**选择你的**VPC**和**可用区**。 + +### 步骤 2：配置路由 + +1. 从**目标组**下拉列表中，选择 **现有目标组**。 +1. 从**名称**下拉列表中，选择 `rancher-tcp-443`。 +1. 打开**高级健康检查设置**，并将**间隔**设为 `10 秒`。 + +### 步骤 3：注册目标 + +由于你已经在先前步骤注册了目标，因此你只需单击 **下一步：审核**。 + +### 步骤 4：审核 + +检查负载均衡器信息无误后，单击**创建**。 + +AWS 完成 NLB 创建后，单击**关闭**。 + +## 4. 为 TCP 端口 80 向 NLB 添加监听器 + +1. 选择新创建的 NLB 并选择**监听器**选项卡。 + +2. 单击**添加监听器**。 + +3. 使用 `TCP`:`80` 作为**协议**:**端口**。 + +4. 单击**添加操作**并选择**转发到..**。 + +5. 从**转发到**下拉列表中，选择 `rancher-tcp-80`。 + +6. 单击右上角的**保存**。 + +## NGINX Ingress 和 Traefik Ingress 的健康检查路径 + +K3s 和 RKE Kubernetes 集群使用的默认 Ingress 不同，因此对应的健康检查方式也不同。 + +RKE Kubernetes 集群默认使用 NGINX Ingress，而 K3s Kubernetes 集群默认使用 Traefik Ingress。 + +- **Traefik**：默认健康检查路径是 `/ping`。默认情况下，不管主机如何，`/ping` 总是匹配，而且 [Traefik 自身](https://docs.traefik.io/operations/ping/)总会响应。 +- **NGINX Ingress**：NGINX Ingress Controller 的默认后端有一个 `/healthz` 端点。默认情况下，不管主机如何，`/healthz` 总是匹配，而且 [`ingress-nginx` 自身](https://github.com/kubernetes/ingress-nginx/blob/0cbe783f43a9313c9c26136e888324b1ee91a72f/charts/ingress-nginx/values.yaml#L212)总会响应。 + +想要精确模拟健康检查，最好是使用 Host 标头（Rancher hostname）加上 `/ping` 或 `/healthz`（分别对应 K3s 和 RKE 集群）来获取 Rancher Pod 的响应，而不是 Ingress 的响应。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/infrastructure-setup/ha-k3s-kubernetes-cluster.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/infrastructure-setup/ha-k3s-kubernetes-cluster.md new file mode 100644 index 00000000000..a8a10335f6b --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/infrastructure-setup/ha-k3s-kubernetes-cluster.md @@ -0,0 +1,73 @@ +--- +title: 为高可用 K3s Kubernetes 集群设置基础设施 +--- + +本教程旨在帮助你为 Rancher Management Server 配置底层基础设施。 + +我们根据 Rancher 的安装位置（K3s Kubernetes 集群、RKE Kubernetes 集群或单个 Docker 容器）为专用于 Rancher 的 Kubernetes 集群推荐不同基础设施。 + +有关每个安装选项的详情，请参见[本页](../../../getting-started/installation-and-upgrade/installation-and-upgrade.md)。 + +:::note 重要提示： + +这些节点必须位于同一个区域。但是你可以把这些服务器放在不同的可用区（数据中心）。 + +::: + +如需在高可用 K3s 集群中安装 Rancher Management Server，我们建议配置以下基础设施： + +- **2 个 Linux 节点**：可以是你的云提供商中的虚拟机。 +- **1 个外部数据库**：用于存储集群数据。建议使用 MySQL。 +- **1 个负载均衡器**：用于将流量转发到这两个节点中。 +- **1 个 DNS 记录**：用于将 URL 映射到负载均衡器。此 DNS 记录将成为 Rancher Server 的 URL，下游集群需要可以访问到这个地址。 + +## 1. 配置 Linux 节点 + +请确保你的节点满足[操作系统，容器运行时，硬件和网络](../../../getting-started/installation-and-upgrade/installation-requirements/installation-requirements.md)的常规要求。 + +如需获取配置 Linux 节点的示例，请参见[在 Amazon EC2 中配置节点](nodes-in-amazon-ec2.md)的教程。 + +## 2. 配置外部数据库 + +K3s 与其他 Kubernetes 发行版不同，在于其支持使用 etcd 以外的数据库来运行 Kubernetes。该功能让 Kubernetes 运维更加灵活。你可以根据实际情况选择合适的数据库。 + +对于 K3s 高可用安装，你需要配置一个 [MySQL](https://www.mysql.com/) 外部数据库。Rancher 已在使用 MySQL 5.7 作为数据存储的 K3s Kubernetes 集群上进行了测试。 + +在使用 K3s 安装脚本安装 Kubernetes 时，你需要传入 K3s 连接数据库的详细信息。 + +如需获取配置 MySQL 数据库示例，请参见[在 Amazon RDS 服务中配置 MySQL](mysql-database-in-amazon-rds.md) 的教程。 + +如需获取配置 K3s 集群数据库的所有可用选项，请参见 [K3s 官方文档](https://rancher.com/docs/k3s/latest/en/installation/datastore/)。 + +## 3. 配置负载均衡器 + +你还需要设置一个负载均衡器，来将流量重定向到两个节点上的 Rancher 副本。配置后，当单个节点不可用时，继续保障与 Rancher Management Server 的通信。 + +在后续步骤中配置 Kubernetes 时，K3s 工具会部署一个 Traefik Ingress Controller。该 Controller 将侦听 worker 节点的 80 端口和 443 端口，以响应发送给特定主机名的流量。 + +在安装 Rancher 后（也是在后续步骤中），Rancher 系统将创建一个 Ingress 资源。该 Ingress 通知 Traefik Ingress Controller 监听发往 Rancher 主机名的流量。Traefik Ingress Controller 在收到发往 Rancher 主机名的流量时，会将其转发到集群中正在运行的 Rancher Server Pod。 + +在你的实现中，你可以考虑是否需要使用 4 层或 7 层的负载均衡器： + +- **4 层负载均衡器**：两种选择中较为简单的一种，它将 TCP 流量转发到你的节点中。我们建议使用 4 层负载均衡器，将流量从 TCP/80 端口和 TCP/443 端口转发到 Rancher Management 集群节点上。集群上的 Ingress Controller 会将 HTTP 流量重定向到 HTTPS，并在 TCP/443 端口上终止 SSL/TLS。Ingress Controller 会将流量转发到 Rancher deployment 中 Ingress Pod 的 TCP/80 端口。 +- **7 层负载均衡器**：相对比较复杂，但功能更全面。例如，与 Rancher 本身进行 TLS 终止相反，7 层负载均衡器能够在负载均衡器处处理 TLS 终止。如果你需要集中在基础设施中进行 TLS 终止，7 层负载均衡可能会很适合你。7 层负载均衡还能让你的负载均衡器基于 HTTP 属性（例如 cookie 等）做出决策，而 4 层负载均衡器则不能。如果你选择在 7 层负载均衡器上终止 SSL/TLS 流量，则在安装 Rancher 时（后续步骤）需要使用 `--set tls=external` 选项。详情请参见 [Rancher Helm Chart 选项](../../../getting-started/installation-and-upgrade/installation-references/helm-chart-options.md#外部-tls-终止)。 + +如需获取配置 NGINX 负载均衡器的示例，请参见[本页](nginx-load-balancer.md)。 + +如需获取如何配置 Amazon ELB 网络负载均衡器的指南，请参见[本页](amazon-elb-load-balancer.md)。 + +:::caution + +安装后，请勿将此负载均衡（例如 `local` 集群 Ingress）用于 Rancher 以外的应用。如果此 Ingress 与其他应用共享，在其他应用的 Ingress 配置重新加载后，可能导致 Rancher 出现 websocket 错误。我们建议把 `local` 集群专用给 Rancher，不要在集群内部署其他应用。 + +::: + +## 4. 配置 DNS 记录 + +配置完负载均衡器后，你将需要创建 DNS 记录，以将流量发送到该负载均衡器。 + +根据你的环境，DNS 记录可以是指向负载均衡器 IP 的 A 记录，也可以是指向负载均衡器主机名的 CNAME。无论是哪种情况，请确保该记录是你要 Rancher 进行响应的主机名。 + +在安装 Rancher 时（后续步骤），你需要指定此主机名。请知悉，此主机名无法修改。请确保你设置的主机名是你想要的。 + +有关设置 DNS 记录以将域流量转发到 Amazon ELB 负载均衡器的指南，请参见 [AWS 官方文档](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/routing-to-elb-load-balancer)。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/infrastructure-setup/ha-rke1-kubernetes-cluster.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/infrastructure-setup/ha-rke1-kubernetes-cluster.md new file mode 100644 index 00000000000..0f27336f53e --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/infrastructure-setup/ha-rke1-kubernetes-cluster.md @@ -0,0 +1,66 @@ +--- +title: 为高可用 RKE Kubernetes 集群设置基础设施 +--- + + + +本教程旨在帮助你创建一个高可用的 RKE 集群，用于安装 Rancher Server。 + +:::note 重要提示： + +这些节点必须位于同一个区域。但是你可以把这些服务器放在不同的可用区（数据中心）。 + +::: + +如需在高可用 RKE 集群中安装 Rancher Management Server，我们建议配置以下基础设施： + +- **3 个 Linux 节点**：可以是你的云提供商（例如 Amazon EC2，GCE 或 vSphere）中的虚拟机。 +- **1 个负载均衡器**：用于将前端流量转发到这三个节点中。 +- **1 个 DNS 记录**：用于将 URL 映射到负载均衡器。此 DNS 记录将成为 Rancher Server 的 URL，下游集群需要可以访问到这个地址。 + +这些节点必须位于同一个区域或数据中心。但是你可以把这些服务器放在不同的可用区。 + +## 为什么使用三个节点？ + +在 RKE 集群中，Rancher Server 的数据存储在 etcd 中。而这个 etcd 数据库在这三个节点上运行。 + +为了选举出大多数 etcd 节点认可的 etcd 集群 leader，etcd 数据库需要奇数个节点。如果 etcd 数据库无法选出 leader，etcd 可能会出现[脑裂（split brain）](https://www.quora.com/What-is-split-brain-in-distributed-systems)的问题，此时你需要使用备份恢复集群。如果三个 etcd 节点之一发生故障，其余两个节点可以选择一个 leader，因为它们是 etcd 节点总数的大多数部分。 + +## 1. 配置 Linux 节点 + +请确保你的节点满足[操作系统，容器运行时，硬件和网络](../../../getting-started/installation-and-upgrade/installation-requirements/installation-requirements.md)的常规要求。 + +如需获取配置 Linux 节点的示例，请参见[在 Amazon EC2 中配置节点](nodes-in-amazon-ec2.md)的教程。 + +## 2. 配置负载均衡器 + +你还需要设置一个负载均衡器，来将流量重定向到三个节点中的任意一个节点上的 Rancher 副本。配置后，当单个节点不可用时，继续保障与 Rancher Management Server 的通信。 + +在后续步骤中配置 Kubernetes 时，RKE 工具会部署一个 NGINX Ingress Controller。该 Controller 将侦听 worker 节点的 80 端口和 443 端口，以响应发送给特定主机名的流量。 + +在安装 Rancher 后（也是在后续步骤中），Rancher 系统将创建一个 Ingress 资源。该 Ingress 通知 NGINX Ingress Controller 监听发往 Rancher 主机名的流量。NGINX Ingress Controller 在收到发往 Rancher 主机名的流量时，会将其转发到集群中正在运行的 Rancher Server Pod。 + +在你的实现中，你可以考虑是否需要使用 4 层或 7 层的负载均衡器： + +- **4 层负载均衡器**：两种选择中较为简单的一种，它将 TCP 流量转发到你的节点中。我们建议使用 4 层负载均衡器，将流量从 TCP/80 端口和 TCP/443 端口转发到 Rancher Management 集群节点上。集群上的 Ingress Controller 会将 HTTP 流量重定向到 HTTPS，并在 TCP/443 端口上终止 SSL/TLS。Ingress Controller 会将流量转发到 Rancher deployment 中 Ingress Pod 的 TCP/80 端口。 +- **7 层负载均衡器**：相对比较复杂，但功能更全面。例如，与 Rancher 本身进行 TLS 终止相反，7 层负载均衡器能够在负载均衡器处处理 TLS 终止。如果你需要集中在基础设施中进行 TLS 终止，7 层负载均衡可能会很适合你。7 层负载均衡还能让你的负载均衡器基于 HTTP 属性（例如 cookie 等）做出决策，而 4 层负载均衡器则不能。如果你选择在 7 层负载均衡器上终止 SSL/TLS 流量，则在安装 Rancher 时（后续步骤）需要使用 `--set tls=external` 选项。详情请参见 [Rancher Helm Chart 选项](../../../getting-started/installation-and-upgrade/installation-references/helm-chart-options.md#外部-tls-终止)。 + +如需获取配置 NGINX 负载均衡器的示例，请参见[本页](nginx-load-balancer.md)。 + +如需获取如何配置 Amazon ELB 网络负载均衡器的指南，请参见[本页](amazon-elb-load-balancer.md)。 + +:::caution + +安装后，请勿将此负载均衡（例如 `local` 集群 Ingress）用于 Rancher 以外的应用。如果此 Ingress 与其他应用共享，在其他应用的 Ingress 配置重新加载后，可能导致 Rancher 出现 websocket 错误。我们建议把 `local` 集群专用给 Rancher，不要在集群内部署其他应用。 + +::: + +## 3. 配置 DNS 记录 + +配置完负载均衡器后，你将需要创建 DNS 记录，以将流量发送到该负载均衡器。 + +根据你的环境，DNS 记录可以是指向负载均衡器 IP 的 A 记录，也可以是指向负载均衡器主机名的 CNAME。无论是哪种情况，请确保该记录是你要 Rancher 进行响应的主机名。 + +在安装 Rancher 时（后续步骤），你需要指定此主机名。请知悉，此主机名无法修改。请确保你设置的主机名是你想要的。 + +有关设置 DNS 记录以将域流量转发到 Amazon ELB 负载均衡器的指南，请参见 [AWS 官方文档](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/routing-to-elb-load-balancer)。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/infrastructure-setup/ha-rke2-kubernetes-cluster.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/infrastructure-setup/ha-rke2-kubernetes-cluster.md new file mode 100644 index 00000000000..b474cf073db --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/infrastructure-setup/ha-rke2-kubernetes-cluster.md @@ -0,0 +1,58 @@ +--- +title: 为高可用 RKE2 Kubernetes 集群设置基础设施 +--- + +本教程旨在帮助你为 Rancher Management Server 配置底层基础设施。 + +我们根据 Rancher 的安装位置（RKE2 Kubernetes 集群、RKE Kubernetes 集群或单个 Docker 容器）为专用于 Rancher 的 Kubernetes 集群推荐不同基础设施。 + +:::note 重要提示： + +这些节点必须位于同一个区域。但是你可以把这些服务器放在不同的可用区（数据中心）。 + +::: + +如需在高可用 RKE2 集群中安装 Rancher Management Server，我们建议配置以下基础设施： + +- **3 个 Linux 节点**：可以是你的云提供商中的虚拟机。 +- **1 个负载均衡器**：用于将流量转发到这两个节点中。 +- **1 个 DNS 记录**：用于将 URL 映射到负载均衡器。此 DNS 记录将成为 Rancher Server 的 URL，下游集群需要可以访问到这个地址。 + +## 1. 配置 Linux 节点 + +请确保你的节点满足[操作系统，容器运行时，硬件和网络](../../../getting-started/installation-and-upgrade/installation-requirements/installation-requirements.md)的常规要求。 + +如需获取配置 Linux 节点的示例，请参见[在 Amazon EC2 中配置节点](nodes-in-amazon-ec2.md)的教程。 + +## 2. 配置负载均衡器 + +你还需要设置一个负载均衡器，来将流量重定向到所有节点上的 Rancher 副本。配置后，当单个节点不可用时，继续保障与 Rancher Management Server 的通信。 + +在后续步骤中配置 Kubernetes 时，RKE2 工具会部署一个 NGINX Ingress Controller。该 Controller 将侦听 worker 节点的 80 端口和 443 端口，以响应发送给特定主机名的流量。 + +在安装 Rancher 后（也是在后续步骤中），Rancher 系统将创建一个 Ingress 资源。该 Ingress 通知 NGINX Ingress Controller 监听发往 Rancher 主机名的流量。NGINX Ingress Controller 在收到发往 Rancher 主机名的流量时，会将其转发到集群中正在运行的 Rancher Server Pod。 + +在你的实现中，你可以考虑是否需要使用 4 层或 7 层的负载均衡器： + +- **4 层负载均衡器**：两种选择中较为简单的一种，它将 TCP 流量转发到你的节点中。我们建议使用 4 层负载均衡器，将流量从 TCP/80 端口和 TCP/443 端口转发到 Rancher Management 集群节点上。集群上的 Ingress Controller 会将 HTTP 流量重定向到 HTTPS，并在 TCP/443 端口上终止 SSL/TLS。Ingress Controller 会将流量转发到 Rancher deployment 中 Ingress Pod 的 TCP/80 端口。 +- **7 层负载均衡器**：相对比较复杂，但功能更全面。例如，与 Rancher 本身进行 TLS 终止相反，7 层负载均衡器能够在负载均衡器处处理 TLS 终止。如果你需要集中在基础设施中进行 TLS 终止，7 层负载均衡可能会很适合你。7 层负载均衡还能让你的负载均衡器基于 HTTP 属性（例如 cookie 等）做出决策，而 4 层负载均衡器则不能。如果你选择在 7 层负载均衡器上终止 SSL/TLS 流量，则在安装 Rancher 时（后续步骤）需要使用 `--set tls=external` 选项。详情请参见 [Rancher Helm Chart 选项](../../../getting-started/installation-and-upgrade/installation-references/helm-chart-options.md#外部-tls-终止)。 + +如需获取配置 NGINX 负载均衡器的示例，请参见[本页](nginx-load-balancer.md)。 + +如需获取如何配置 Amazon ELB 网络负载均衡器的指南，请参见[本页](amazon-elb-load-balancer.md)。 + +:::caution + +安装后，请勿将此负载均衡（例如 `local` 集群 Ingress）用于 Rancher 以外的应用。如果此 Ingress 与其他应用共享，在其他应用的 Ingress 配置重新加载后，可能导致 Rancher 出现 websocket 错误。我们建议把 `local` 集群专用给 Rancher，不要在集群内部署其他应用。 + +::: + +## 4. 配置 DNS 记录 + +配置完负载均衡器后，你将需要创建 DNS 记录，以将流量发送到该负载均衡器。 + +根据你的环境，DNS 记录可以是指向负载均衡器 IP 的 A 记录，也可以是指向负载均衡器主机名的 CNAME。无论是哪种情况，请确保该记录是你要 Rancher 进行响应的主机名。 + +在安装 Rancher 时（后续步骤），你需要指定此主机名。请知悉，此主机名无法修改。请确保你设置的主机名是你想要的。 + +有关设置 DNS 记录以将域流量转发到 Amazon ELB 负载均衡器的指南，请参见 [AWS 官方文档](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/routing-to-elb-load-balancer)。 \ No newline at end of file diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/infrastructure-setup/infrastructure-setup.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/infrastructure-setup/infrastructure-setup.md new file mode 100644 index 00000000000..aa3c433b873 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/infrastructure-setup/infrastructure-setup.md @@ -0,0 +1,11 @@ +--- +title: Kubernetes 集群基础设施 +--- + + + + + +要为具有外部数据库的高可用 K3s Kubernetes 集群设置基础设施，请参见[本页面](ha-k3s-kubernetes-cluster.md)。 + +要为高可用 RKE Kubernetes 集群设置基础设施，请参见[本页面](ha-rke1-kubernetes-cluster.md)。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/infrastructure-setup/mysql-database-in-amazon-rds.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/infrastructure-setup/mysql-database-in-amazon-rds.md new file mode 100644 index 00000000000..d312a5f6207 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/infrastructure-setup/mysql-database-in-amazon-rds.md @@ -0,0 +1,34 @@ +--- +title: 在 Amazon RDS 中创建 MySQL 数据库 +--- + +本教程介绍如何在 Amazon Relational Database Service (RDS) 中创建 MySQL 数据库。 + +该数据库可用作高可用 K3s Kubernetes 集群的外部数据存储。 + +1. 登录到 [Amazon AWS RDS 控制台](https://console.aws.amazon.com/rds/)。确保选择的**区域**是你创建 EC2 实例 （Linux 节点）的区域。 +1. 在左侧面板中，点击**数据库**。 +1. 点击**创建数据库**。 +1. 在**引擎类型**中，点击 **MySQL**。 +1. 在**版本**中，选择 **MySQL 5.7.22**。 +1. 在**设置**部分的**凭证设置**下，输入 **admin** 主用户名的密码。确认密码。 +1. 展开**其它配置**。在**初始数据库名称**字段，设置数据库名称。该名称仅可包含字母，数字和下划线。这个名称会用于连接到数据库。 +1. 点击**创建数据库**。 + +你需要获取新数据库的以下信息，以便 K3s Kubernetes 集群可以连接到该数据库。 + +如需在 Amazon RDS 控制台查看此信息，点击**数据库**，然后点击你创建的数据库的名称。 + +- **用户名**：使用 admin 用户名。 +- **密码**：使用 admin 密码。 +- **主机名**：使用**端点**作为主机名。端点可以在**连接性和安全性**部分找到。 +- **端口**：默认为 3306。你可以在**连接性和安全性**处确认端口。 +- **数据库名称**：前往**配置**选项卡确认数据库名称。名称会在**数据库名称**中列出。 + +以下方格式使用上述信息，连接到数据库： + +``` +mysql://username:password@tcp(hostname:3306)/database-name +``` + +有关为 K3s 配置数据库的详情，请参见 [K3s 官方文档](https://rancher.com/docs/k3s/latest/en/installation/datastore/)。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/infrastructure-setup/nginx-load-balancer.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/infrastructure-setup/nginx-load-balancer.md new file mode 100644 index 00000000000..b686c28221a --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/infrastructure-setup/nginx-load-balancer.md @@ -0,0 +1,102 @@ +--- +title: 配置 NGINX 负载均衡器 +--- + +将 NGINX 配置为四层负载均衡器（TCP），用于将连接转发到 Rancher 节点。 + +在此配置中，负载均衡器位于节点的前面。负载均衡器可以是任何能运行 NGINX 的主机。 + +:::note + +不要使用 Rancher 节点作为负载均衡器。 + +::: + +> 这些示例中，负载均衡器将流量转发到三个 Rancher Server 节点。如果 Rancher 安装在 RKE Kubernetes 集群上，则需要三个节点。如果 Rancher 安装在 K3s Kubernetes 集群上，则只需要两个节点。 + +## 安装 NGINX + +首先，在要用作负载均衡器的节点上安装 NGINX。NGINX 有适用于所有已知操作系统的软件包。已测试的版本为 `1.14` 和 `1.15`。如需获得安装 NGINX 的帮助，请参见[安装文档](https://www.nginx.com/resources/wiki/start/topics/tutorials/install/)。 + +`stream` 模块是必需的，NGINX 官方安装包包含了该模块。请参见你操作系统的文档，了解如何在操作系统上安装和启用 NGINX 的 `stream` 模块。 + +## 创建 NGINX 配置 + +安装 NGINX 后，使用节点的 IP 地址更新 NGINX 配置文件 `nginx.conf`。 + +1. 将以下的示例代码复制并粘贴到你使用的文本编辑器中。将文件保存为 `nginx.conf`。 + +2. 在 `nginx.conf` 中，将所有（端口 80 和端口 443）的 ``，``和 `` 替换为你节点的 IP 地址。 + + :::note + + 参见 [NGINX 文档：TCP 和 UDP 负载均衡](https://docs.nginx.com/nginx/admin-guide/load-balancer/tcp-udp-load-balancer/)了解所有配置选项。 + + ::: + +
示例 NGINX 配置
+ + ``` + worker_processes 4; + worker_rlimit_nofile 40000; + + events { + worker_connections 8192; + } + + stream { + upstream rancher_servers_http { + least_conn; + server :80 max_fails=3 fail_timeout=5s; + server :80 max_fails=3 fail_timeout=5s; + server :80 max_fails=3 fail_timeout=5s; + } + server { + listen 80; + proxy_pass rancher_servers_http; + } + + } + + http { + + upstream rancher_servers_https { + least_conn; + server :443 max_fails=3 fail_timeout=5s; + server :443 max_fails=3 fail_timeout=5s; + server :443 max_fails=3 fail_timeout=5s; + } + server { + listen 443 ssl; + proxy_pass rancher_servers_https; + ssl_certificate /path/to/tls.crt; + ssl_certificate_key /path/to/key.key; + location / { + proxy_pass https://rancher_servers_https; + proxy_set_header Host ; + proxy_ssl_server_name on; + proxy_ssl_name + } + } + } + ``` + + +3. 将 `nginx.conf` 保存到你的负载均衡器的 `/etc/nginx/nginx.conf` 路径上。 + +4. 运行以下命令重新加载 NGINX 配置： + + ``` + # nginx -s reload + ``` + +## 可选 - 将 NGINX 作为 Docker 容器运行 + +除了将 NGINX 作为软件包安装在操作系统上外，你也可以将其作为 Docker 容器运行。将编辑后的 **NGINX 配置示例** 保存为`/etc/nginx.conf`，并运行以下命令来启动 NGINX 容器： + +``` +docker run -d --restart=unless-stopped \ + -p 80:80 -p 443:443 \ + -v /etc/nginx.conf:/etc/nginx/nginx.conf \ + nginx:1.14 +``` diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/infrastructure-setup/nodes-in-amazon-ec2.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/infrastructure-setup/nodes-in-amazon-ec2.md new file mode 100644 index 00000000000..bb480d6fb63 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/infrastructure-setup/nodes-in-amazon-ec2.md @@ -0,0 +1,74 @@ +--- +title: 在 Amazon EC2 中配置节点 +--- + +在本教程中，你将学习一种为 Rancher Mangement Server 创建 Linux 节点的方法。这些节点将满足[操作系统、Docker、硬件和网络的要求](../../../getting-started/installation-and-upgrade/installation-requirements/installation-requirements.md)。 + +如果 Rancher Server 安装在 RKE Kubernetes 集群上，你需要配置三个实例。 + +如果 Rancher Server 安装在 K3s Kubernetes 集群上，你只需要配置两个实例。 + +如果 Rancher Server 安装在单个 Docker 容器中，你只需要配置一个实例。 + +## 1. 准备工作（可选） + +- **创建 IAM 角色**：要允许 Rancher 操作 AWS 资源，例如创建新存储或新节点，你需要将 Amazon 配置为云提供商。要在 EC2 上设置云提供商，你需要进行几个操作，其中包括为 Rancher Server 节点设置 IAM 角色。有关设置云提供商的详情，请参见[本页](../kubernetes-clusters-in-rancher-setup/set-up-cloud-providers/set-up-cloud-providers.md)。 +- **创建安全组**：我们建议为 Rancher 节点设置一个符合 [Rancher 节点端口要求](../../../getting-started/installation-and-upgrade/installation-requirements/installation-requirements.md#端口要求)的安全组。 + +## 2. 配置实例 + +1. 登录到 [Amazon AWS EC2 控制台](https://console.aws.amazon.com/ec2/)。由于 Rancher Management Server 的所有基础设施都需要位于同一区域，因此，请务必记下创建 EC2 实例（Linux 节点）的**区域**。 +1. 在左侧面板中，点击**实例**。 +1. 点击**启动示例**。 +1. 在**步骤 1：选择 Amazon Machine Image (AMI)** 中，使用 `ami-0d1cd67c26f5fca19 (64-bit x86)` 来使用 Ubuntu 18.04 作为 Linux 操作系统。去到 Ubuntu AMI 并点击**选择**。 +1. 在**步骤 2：选择实例类型**中，选择 `t2.medium`。 +1. 点击**下一步：配置实例详细信息**。 +1. 在**实例数量**字段中，输入实例数量。创建高可用 K3s 集群仅需要两个实例，而高可用 RKE 集群则需要三个实例。 +1. 可选：如果你为 Rancher 创建了一个 IAM 角色来操作 AWS 资源，请在 **IAM 角色**字段中选择新 IAM 角色。 +1. 分别点击**下一步：添加存储**，**下一步：添加标签**和**下一步：配置安全组**。 +1. 在**步骤 6：配置安全组**中，选择一个符合 Rancher 节点[端口要求](../../../getting-started/installation-and-upgrade/installation-requirements/installation-requirements.md#端口要求)的安全组。 +1. 点击**查看并启动**。 +1. 点击**启动**。 +1. 选择一个新的或现有的密钥对，用于之后连接到你的实例。如果使用现有密钥对，请确保你有访问私钥的权限。 +1. 点击**启动实例**。 + + +**结果**：你已创建满足操作系统、硬件和网络要求的 Rancher 节点。 + +:::note + +如果节点用于 RKE Kubernetes 集群，请在下一步操作中为每个节点安装 Docker 。如果节点用于 K3s Kubernetes 集群，你可以开始在节点上安装 K3s 了。 + +::: + +## 3. 为 RKE Kubernetes 集群节点安装 Docker 并创建用户 + +1. 在 [AWS EC2 控制台](https://console.aws.amazon.com/ec2/)中，点击左侧面板中的**实例**。 +1. 转到你想要安装 Docker 的实例。选择实例，并点击**操作 > 连接**。 +1. 按照屏幕上的说明连接到实例。复制实例的公共 DNS。SSH 进入实例的示例命令如下： +``` +sudo ssh -i [path-to-private-key] ubuntu@[public-DNS-of-instance] +``` +1. 在实例上运行以下命令，使用 Rancher 的其中一个安装脚本来安装 Docker： +``` +curl https://releases.rancher.com/install-docker/18.09.sh | sh +``` +1. 连接到实例后，在实例上运行以下命令来创建用户： +``` +sudo usermod -aG docker ubuntu +``` +1. 在每个节点上重复上述步骤，以确保 Docker 安装到每个用于运行 Rancher Management Server 的节点上。 + +:::tip + +要了解我们是否提供指定的 Docker 版本的安装脚本，请访问此 [GitHub 仓库](https://github.com/rancher/install-docker)，该仓库包含 Rancher 的所有 Docker 安装脚本。 + +::: + +**结果**：你已配置满足操作系统、Docker、硬件和网络要求的 Rancher Server 节点。 + +## RKE Kubernetes 集群节点的后续步骤 + +如需在新节点上安装 RKE 集群，请记住每个节点的 **IPv4 公共 IP** 和 **私有 IP**。创建节点后，此信息可以在每个节点的**描述**选项卡中找到。公共和私有 IP 将用于设置 RKE 集群配置文件 `rancher-cluster.yml` 中每个节点的 `address` 和 `internal_address`。 + +RKE 还需要访问私钥才能连接到每个节点。因此，请记住连接到节点的私钥的路径，该路径也可用于设置 `rancher-cluster.yml` 中每个节点的 `ssh_key_path`。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/kubernetes-cluster-setup/high-availability-installs.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/kubernetes-cluster-setup/high-availability-installs.md new file mode 100644 index 00000000000..c53bf4de731 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/kubernetes-cluster-setup/high-availability-installs.md @@ -0,0 +1,23 @@ +--- +title: 高可用安装 +--- + +我们建议使用 Helm（ Kubernetes 包管理器 ）在专用的 Kubernetes 集群上安装 Rancher。由于 Rancher 运行在多个节点上提升了可用性，因此这种安装方式叫做高可用 Kubernetes 安装。 + +在标准安装中，先将 Kubernetes 安装在托管在云提供商（例如 Amazon 的 EC2 或 Google Compute Engine）中的三个节点上。 + +然后使用 Helm 在 Kubernetes 集群上安装 Rancher。Helm 使用 Rancher 的 Helm Chart 在 Kubernetes 集群的三个节点中均安装 Rancher 的副本。我们建议使用负载均衡器将流量转发到集群中的每个 Rancher 副本中，以提高 Rancher 的可用性。 + +Rancher Server 的数据存储在 etcd 中。etcd 数据库可以在所有三个节点上运行。为了选举出大多数 etcd 节点认同的 etcd 集群 leader，节点的数量需要是奇数。如果 etcd 数据库不能选出 leader，etcd 可能会失败。这时候就需要使用备份来还原集群。 + +有关 Rancher 如何工作的详情（与安装方法无关），请参见[架构](../../../reference-guides/rancher-manager-architecture/rancher-manager-architecture.md)。 + +## 推荐架构 + +- Rancher 的 DNS 应该解析为 4 层负载均衡器。 +- 负载均衡器应该把 TCP/80 端口和 TCP/443 端口的流量转发到 Kubernetes 集群的全部 3 个节点上。 +- Ingress Controller 会把 HTTP 重定向到 HTTPS，在 TCP/443 端口终结 SSL/TLS。 +- Ingress Controller 会把流量转发到 Rancher deployment 的 Pod 上的 TCP/80 端口。 + +![Rancher 的高可用 Kubernetes 安装](/img/ha/rancher2ha.svg) +使用 4 层负载均衡器在 Kubernetes 集群中安装 Rancher：Ingress Controller 的 SSL 终止 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/kubernetes-cluster-setup/k3s-for-rancher.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/kubernetes-cluster-setup/k3s-for-rancher.md new file mode 100644 index 00000000000..4d8ca8ac24c --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/kubernetes-cluster-setup/k3s-for-rancher.md @@ -0,0 +1,136 @@ +--- +title: 为 Rancher 设置高可用 K3s Kubernetes 集群 +--- + +本文介绍了如何根据 [Rancher Server 环境的最佳实践](../../../reference-guides/rancher-manager-architecture/architecture-recommendations.md#kubernetes-安装环境)安装 Kubernetes 集群。 + +如果你的系统无法直接访问互联网，请参见离线安装说明。 + +:::tip 单节点安装提示： + +在单节点 Kubernetes 集群中，Rancher Server 不具备高可用性，而高可用性对在生产环境中运行 Rancher 非常重要。但是，如果你想要短期内使用单节点节省资源，同时又保留高可用性迁移路径，把 Rancher 安装到单节点集群也是合适的。 + +要配置单节点 K3s 集群，你只需要在单个节点上运行 Rancher Server 安装命令（不需要在两个节点上运行命令）。 + +在这两种单节点设置中，Rancher 可以与 Helm 一起安装在 Kubernetes 集群上，安装方法与安装到其他集群上一样。 + +::: + +## 先决条件 + +以下说明假设你已参见[此章节](../infrastructure-setup/ha-k3s-kubernetes-cluster.md)配置好两个节点，一个负载均衡器，一个 DNS 记录和一个外部 MySQL 数据库。 + +Rancher 需要安装在支持的 Kubernetes 版本上。如需了解你使用的 Rancher 版本支持哪些 Kubernetes 版本，请参见 [Rancher 支持矩阵](https://rancher.com/support-maintenance-terms/)。 + +如需指定 K3s（Kubernetes）版本，在运行 K3s 安装脚本时使用 `INSTALL_K3S_VERSION` 环境变量（例如 `INSTALL_K3S_VERSION="v1.24.10+k3s1"`）。 + +## 安装 Kubernetes + +### 1. 安装 Kubernetes 并设置 K3s Server + +在运行启动 K3s Kubernetes API Server 的命令时，你会传入使用之前设置的外部数据存储的选项。 + +1. 连接到你准备用于运行 Rancher Server 的其中一个 Linux 节点。 +1. 在 Linux 节点上，运行以下命令来启动 K3s Server，并将其连接到外部数据存储。 + ``` + curl -sfL https://get.k3s.io | INSTALL_K3S_VERSION= sh -s - server \ + --datastore-endpoint="" + ``` + + 其中 `` 是数据存储的连接 URI。例如，如果你使用的是 MySQL，则为 `mysql://username:password@tcp(hostname:3306)/database-name`。有效的数据存储包括 etcd、MySQL、PostgreSQL 或 SQLite（默认）。 + + :::note + + 你也可以使用 `$K3S_DATASTORE_ENDPOINT` 环境变量来传递数据存储端点。 + + ::: + +1. 获取主 Server 节点令牌： + ``` + cat /var/lib/rancher/k3s/server/token + ``` + +1. 在第二个 K3s Server 节点上运行命令： + ``` + curl -sfL https://get.k3s.io | INSTALL_K3S_VERSION= sh -s - server \ + --datastore-endpoint="" \ + --token "" + ``` + +### 2. 检查 K3s 是否正常运行 + +在其中一个 K3s Server 节点上运行以下命令，来确认 K3s 是否已经设置成功： +``` +sudo k3s kubectl get nodes +``` + +然后你会看到两个具有 master 角色的节点。 +``` +ubuntu@ip-172-31-60-194:~$ sudo k3s kubectl get nodes +NAME STATUS ROLES AGE VERSION +ip-172-31-60-194 Ready master 44m v1.17.2+k3s1 +ip-172-31-63-88 Ready master 6m8s v1.17.2+k3s1 +``` + +测试集群 Pod 的健康状况： +``` +sudo k3s kubectl get pods --all-namespaces +``` + +**结果**：你已成功配置 K3s Kubernetes 集群。 + +### 3. 保存并开始使用 kubeconfig 文件 + +在每个 Rancher Server 节点安装 K3s 时，会在每个节点的 `/etc/rancher/k3s/k3s.yaml` 中生成一个 `kubeconfig` 文件。该文件包含访问集群的凭证。请将该文件保存在安全的位置。 + +如要使用该 `kubeconfig` 文件： + +1. 安装 Kubernetes 命令行工具 [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/#install-kubectl)。 +2. 复制 `/etc/rancher/k3s/k3s.yaml` 文件并保存到本地主机的 `~/.kube/config` 目录上。 +3. 在 kubeconfig 文件中，`server` 的参数为 localhost。你需要将 `server` 配置为负载均衡器的 DNS，并指定端口 6443（通过端口 6443 访问 Kubernetes API Server，通过端口 80 和 443 访问 Rancher Server）。以下是一个 `k3s.yaml` 示例： + +```yml +apiVersion: v1 +clusters: +- cluster: + certificate-authority-data: [CERTIFICATE-DATA] + server: [LOAD-BALANCER-DNS]:6443 # 编辑此行 + name: default +contexts: +- context: + cluster: default + user: default + name: default +current-context: default +kind: Config +preferences: {} +users: +- name: default + user: + password: [PASSWORD] + username: admin +``` + +**结果**：你可以开始使用 `kubectl` 来管理你的 K3s 集群。如果你有多个 `kubeconfig` 文件，在使用 `kubectl` 时，你可以传入文件路径来指定要使用的 `kubeconfig` 文件： + +``` +kubectl --kubeconfig ~/.kube/config/k3s.yaml get pods --all-namespaces +``` + +有关 `kubeconfig` 文件的详情，请参见 [K3s 官方文档](https://rancher.com/docs/k3s/latest/en/cluster-access/) 或 [ Kubernetes 官方文档](https://kubernetes.io/docs/concepts/configuration/organize-cluster-access-kubeconfig/)中关于使用 `kubeconfig` 文件管理集群访问的部分。 + +### 4. 检查集群 Pod 的健康状况 + +现在你已经设置了 `kubeconfig` 文件。你可以使用 `kubectl` 在本地主机访问集群。 + +检查所有需要的 Pod 和容器是否健康： + +``` +ubuntu@ip-172-31-60-194:~$ sudo kubectl get pods --all-namespaces +NAMESPACE NAME READY STATUS RESTARTS AGE +kube-system metrics-server-6d684c7b5-bw59k 1/1 Running 0 8d +kube-system local-path-provisioner-58fb86bdfd-fmkvd 1/1 Running 0 8d +kube-system coredns-d798c9dd-ljjnf 1/1 Running 0 8d +``` + +**结果**：你可通过使用 `kubectl` 访问集群，并且 K3s 集群能成功运行。现在，你可以在集群上安装 Rancher Management Server。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/kubernetes-cluster-setup/kubernetes-cluster-setup.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/kubernetes-cluster-setup/kubernetes-cluster-setup.md new file mode 100644 index 00000000000..f8213ffbbac --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/kubernetes-cluster-setup/kubernetes-cluster-setup.md @@ -0,0 +1,11 @@ +--- +title: "Kubernetes 使用教程" +--- + + + + + +本章节介绍如何安装 Kubernetes 集群，使得 Rancher Server 可以安装在该集群上。 + +Rancher 可以在任何 Kubernetes 集群上运行。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/kubernetes-cluster-setup/rke2-for-rancher.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/kubernetes-cluster-setup/rke2-for-rancher.md new file mode 100644 index 00000000000..cc61efd50e4 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/kubernetes-cluster-setup/rke2-for-rancher.md @@ -0,0 +1,165 @@ +--- +title: 为 Rancher 设置高可用的 RKE2 Kubernetes 集群 +--- + +本文介绍了如何根据 [Rancher Server 环境的最佳实践](../../../reference-guides/rancher-manager-architecture/architecture-recommendations.md#kubernetes-安装环境)安装 Kubernetes 集群。 + +## 先决条件 + +以下说明假设你已参见[此章节](../infrastructure-setup/ha-rke2-kubernetes-cluster.md)配置好三个节点，一个负载均衡器和一个 DNS 记录。 + +为了让 RKE2 与负载均衡器正常工作，你需要设置两个监听器，一个用于 9345 端口，另一个用于 6443 端口的 Kubernetes API。 + +Rancher 需要安装在支持的 Kubernetes 版本上。如需了解你使用的 Rancher 版本支持哪些 Kubernetes 版本，请参见[支持维护条款](https://rancher.com/support-maintenance-terms/)。如需指定 RKE2 版本，请在运行 RKE2 安装脚本时，使用 `INSTALL_RKE2_VERSION` 环境变量。 + +## 安装 Kubernetes + +### 1. 安装 Kubernetes 并设置 RKE2 Server + +RKE2 Server 使用嵌入式 etcd 运行。因此你不需要设置外部数据存储就可以在 HA 模式下运行。 + +在第一个节点上，使用你的预共享密文作为 Token 来设置配置文件。Token 参数可以在启动时设置。 + +如果你不指定预共享密文，RKE2 会生成一个预共享密文并将它放在 `/var/lib/rancher/rke2/server/node-token` 中。 + +为了避免固定注册地址的证书错误，请在启动 Server 时设置 `tls-san` 参数。这个选项在 Server 的 TLS 证书中增加一个额外的主机名或 IP 作为 Subject Alternative Name。如果你想通过 IP 和主机名访问，你可以将它指定为一个列表。 + +首先，创建用于存放 RKE2 配置文件的目录： + +``` +mkdir -p /etc/rancher/rke2/ +``` + +然后，参见以下示例在 `/etc/rancher/rke2/config.yaml` 中创建 RKE2 配置文件： + +``` +token: my-shared-secret +tls-san: + - my-kubernetes-domain.com + - another-kubernetes-domain.com +``` +之后，运行安装命令并启用和启动 RKE2： + +``` +curl -sfL https://get.rke2.io | sh - +systemctl enable rke2-server.service +systemctl start rke2-server.service +``` +1. 要加入其余的节点，使用同一个共享或自动生成的 Token 来配置每个额外的节点。以下是配置文件的示例： + + token: my-shared-secret + server: https://:9345 + tls-san: + - my-kubernetes-domain.com + - another-kubernetes-domain.com +运行安装程序，然后启用并启动 RKE2： + + curl -sfL https://get.rke2.io | sh - + systemctl enable rke2-server.service + systemctl start rke2-server.service + + +1. 在第三 RKE2 Server 节点上运行同样的命令。 + +### 2. 检查 RKE2 是否正常运行 + +在所有 Server 节点上启动了 RKE2 Server 进程后，确保集群已经正常启动，请运行以下命令： + +``` +/var/lib/rancher/rke2/bin/kubectl \ + --kubeconfig /etc/rancher/rke2/rke2.yaml get nodes +现在，Server 节点的状态应该是 Ready。 +``` + +测试集群 Pod 的健康状况： +``` +/var/lib/rancher/rke2/bin/kubectl \ + --kubeconfig /etc/rancher/rke2/rke2.yaml get pods --all-namespaces +``` + +**结果**：你已成功配置 RKE2 Kubernetes 集群。 + +### 3. 保存并开始使用 kubeconfig 文件 + +在每个 Rancher Server 节点安装 RKE2 时，会在每个节点的 `/etc/rancher/rke2/rke2.yaml` 中生成一个 `kubeconfig` 文件。该文件包含访问集群的凭证。请将该文件保存在安全的位置。 + +如要使用该 `kubeconfig` 文件： + +1. 安装 Kubernetes 命令行工具 [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/#install-kubectl)。 +2. 复制 `/etc/rancher/rke2/rke2.yaml` 文件并保存到本地主机的 `~/.kube/config` 目录上。 +3. 在 kubeconfig 文件中，`server` 的参数为 localhost。在端口 6443 上将服务器配置为 controlplane 负载均衡器的 DNS（RKE2 Kubernetes API Server 使用端口 6443，而 Rancher Server 将通过 NGINX Ingress 在端口 80 和 443 上提供服务。）以下是一个示例 `rke2.yaml`： + +```yml +apiVersion: v1 +clusters: +- cluster: + certificate-authority-data: [CERTIFICATE-DATA] + server: [LOAD-BALANCER-DNS]:6443 # 编辑此行 + name: default +contexts: +- context: + cluster: default + user: default + name: default +current-context: default +kind: Config +preferences: {} +users: +- name: default + user: + password: [PASSWORD] + username: admin +``` + +**结果**：你可以开始使用 `kubectl` 来管理你的 RKE2 集群。如果你有多个 `kubeconfig` 文件，在使用 `kubectl` 时，你可以传入文件路径来指定要使用的 `kubeconfig` 文件： + +``` +kubectl --kubeconfig ~/.kube/config/rke2.yaml get pods --all-namespaces +``` + +有关 `kubeconfig` 文件的详情，请参见 [RKE2 官方文档](https://docs.rke2.io/cluster_access)或 [ Kubernetes 官方文档](https://kubernetes.io/docs/concepts/configuration/organize-cluster-access-kubeconfig/)中关于使用 `kubeconfig` 文件管理集群访问的部分。 + +### 4. 检查集群 Pod 的健康状况 + +现在你已经设置了 `kubeconfig` 文件。你可以使用 `kubectl` 在本地主机访问集群。 + +检查所有需要的 Pod 和容器是否健康： + +``` +/var/lib/rancher/rke2/bin/kubectl --kubeconfig /etc/rancher/rke2/rke2.yaml get pods -A +NAMESPACE NAME READY STATUS RESTARTS AGE +kube-system cloud-controller-manager-rke2-server-1 1/1 Running 0 2m28s +kube-system cloud-controller-manager-rke2-server-2 1/1 Running 0 61s +kube-system cloud-controller-manager-rke2-server-3 1/1 Running 0 49s +kube-system etcd-rke2-server-1 1/1 Running 0 2m13s +kube-system etcd-rke2-server-2 1/1 Running 0 87s +kube-system etcd-rke2-server-3 1/1 Running 0 56s +kube-system helm-install-rke2-canal-hs6sx 0/1 Completed 0 2m17s +kube-system helm-install-rke2-coredns-xmzm8 0/1 Completed 0 2m17s +kube-system helm-install-rke2-ingress-nginx-flwnl 0/1 Completed 0 2m17s +kube-system helm-install-rke2-metrics-server-7sggn 0/1 Completed 0 2m17s +kube-system kube-apiserver-rke2-server-1 1/1 Running 0 116s +kube-system kube-apiserver-rke2-server-2 1/1 Running 0 66s +kube-system kube-apiserver-rke2-server-3 1/1 Running 0 48s +kube-system kube-controller-manager-rke2-server-1 1/1 Running 0 2m30s +kube-system kube-controller-manager-rke2-server-2 1/1 Running 0 57s +kube-system kube-controller-manager-rke2-server-3 1/1 Running 0 42s +kube-system kube-proxy-rke2-server-1 1/1 Running 0 2m25s +kube-system kube-proxy-rke2-server-2 1/1 Running 0 59s +kube-system kube-proxy-rke2-server-3 1/1 Running 0 85s +kube-system kube-scheduler-rke2-server-1 1/1 Running 0 2m30s +kube-system kube-scheduler-rke2-server-2 1/1 Running 0 57s +kube-system kube-scheduler-rke2-server-3 1/1 Running 0 42s +kube-system rke2-canal-b9lvm 2/2 Running 0 91s +kube-system rke2-canal-khwp2 2/2 Running 0 2m5s +kube-system rke2-canal-swfmq 2/2 Running 0 105s +kube-system rke2-coredns-rke2-coredns-547d5499cb-6tvwb 1/1 Running 0 92s +kube-system rke2-coredns-rke2-coredns-547d5499cb-rdttj 1/1 Running 0 2m8s +kube-system rke2-coredns-rke2-coredns-autoscaler-65c9bb465d-85sq5 1/1 Running 0 2m8s +kube-system rke2-ingress-nginx-controller-69qxc 1/1 Running 0 52s +kube-system rke2-ingress-nginx-controller-7hprp 1/1 Running 0 52s +kube-system rke2-ingress-nginx-controller-x658h 1/1 Running 0 52s +kube-system rke2-metrics-server-6564db4569-vdfkn 1/1 Running 0 66s +``` + +**结果**：你可通过使用 `kubectl` 访问集群，并且 RKE2 集群能成功运行。现在，你可以在集群上安装 Rancher Management Server。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/checklist-for-production-ready-clusters/checklist-for-production-ready-clusters.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/checklist-for-production-ready-clusters/checklist-for-production-ready-clusters.md new file mode 100644 index 00000000000..0347c6e10ba --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/checklist-for-production-ready-clusters/checklist-for-production-ready-clusters.md @@ -0,0 +1,52 @@ +--- +title: 生产就绪集群检查清单 +--- + + + + + +本节将介绍创建生产就绪型 Kubernetes 集群的最佳实践。这个集群可用于运行你的应用和服务。 + +有关集群的要求（包括对 OS/Docker、硬件和网络的要求），请参阅[节点要求](../node-requirements-for-rancher-managed-clusters.md)部分。 + +本文介绍了我们推荐用于所有生产集群的最佳实践的简短列表。 + +如需获取推荐的所有最佳实践的完整列表，请参阅[最佳实践](../../../../reference-guides/best-practices/best-practices.md)部分。 + +## 节点要求 + +* 确保你的节点满足所有[节点要求](../node-requirements-for-rancher-managed-clusters.md)，包括端口要求。 + +## 备份 etcd + +* 启用 etcd 快照。验证是否正在创建快照，并执行灾难恢复方案，从而验证快照是否有效。etcd 是存储集群状态的位置，丢失 etcd 数据意味着丢失集群。因此，请确保为集群配置 etcd 的定期快照，并确保快照也是存储在外部（节点外）的。 + +## 集群架构 + +* 节点应具有以下角色配置之一： + * `etcd` + * `controlplane` + * `etcd` 和 `controlplane` + * `worker`（不应在具有 `etcd` 或 `controlplane` 角色的节点上使用或添加 `worker` 角色） +* 至少拥有三个角色为 `etcd` 的节点，来确保失去一个节点时仍能存活。增加 etcd 节点数量能提高容错率，而将 etcd 分散到不同可用区甚至能获取更好的容错能力。 +* 为两个或更多节点分配 `controlplane` 角色，能实现主组件的高可用性。 +* 为两个或多个节点分配 `worker` 角色，以便在节点故障时重新安排工作负载。 + +有关每个角色的用途的更多信息，请参阅 [Kubernetes 中的节点角色](roles-for-nodes-in-kubernetes.md)。 + +有关每个 Kubernetes 角色的节点数的详细信息，请参阅[推荐架构](../../../../reference-guides/rancher-manager-architecture/architecture-recommendations.md)部分。 + +## Logging 和 Monitoring + +* 为 Kubernetes 组件（系统服务）配置告警/通知程序。 +* 为集群分析和事后剖析配置 Logging。 + +## 可靠性 + +* 在集群上执行负载测试，以验证硬件是否可以支持你的工作负载。 + +## 网络 + +* 最小化网络延迟。Rancher 建议尽量减少 etcd 节点之间的延迟。`heartbeat-interval` 的默认设置是 `500`，`election-timeout` 的默认设置是 `5000`。这些 [etcd 调优设置](https://etcd.io/docs/v3.5/tuning/) 允许 etcd 在大多数网络（网络延迟特别高的情况下除外）中运行。 +* 集群节点应位于单个区域内。大多数云厂商在一个区域内提供多个可用区，这可以提高你集群的可用性。任何角色的节点都可以使用多个可用区。如果你使用 [Kubernetes Cloud Provider](../set-up-cloud-providers/set-up-cloud-providers.md) 资源，请查阅文档以了解限制（即区域存储限制）。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/checklist-for-production-ready-clusters/recommended-cluster-architecture.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/checklist-for-production-ready-clusters/recommended-cluster-architecture.md new file mode 100644 index 00000000000..6473225d264 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/checklist-for-production-ready-clusters/recommended-cluster-architecture.md @@ -0,0 +1,73 @@ +--- +title: 推荐的集群架构 +--- + +有三个角色可以分配给节点，分别是 `etcd`、`controlplane` 和 `worker`。 + +## 将 Worker 节点与具有其他角色的节点分开 + +在设计集群时，你有两种选择： + +* 为每个角色使用专用节点。这确保了特定角色所需组件的资源可用性。它还根据[端口要求](../node-requirements-for-rancher-managed-clusters.md#网络要求)严格隔离每个角色之间的网络流量。 +* 将 `etcd` 和 `controlplane` 角色分配给相同的节点。该节点必须满足这两个角色的硬件要求。 + +无论在哪种情况下，都不应该在具有 `etcd` 或 `controlplane` 角色的节点中使用或添加 `worker` 角色。 + +因此，每个节点的角色都有如下几种配置选择： + +* `etcd` +* `controlplane` +* `etcd` 和 `controlplane` +* `worker` + +## 每个角色的推荐节点数 + +集群应该有： + +- 至少拥有三个角色为 `etcd` 的节点，来确保失去一个节点时仍能存活。增加 etcd 节点数量能提高容错率，而将 etcd 分散到不同可用区甚至能获取更好的容错能力。 +- 至少两个节点具有 `controlplane` 角色，以实现主组件高可用性。 +- 至少两个具有 `worker` 角色的节点，用于在节点故障时重新安排工作负载。 + +有关每个角色的用途的更多信息，请参阅 [Kubernetes 中的节点角色](roles-for-nodes-in-kubernetes.md)。 + + +### controlplane 节点数 + +添加多个具有 `controlplane` 角色的节点，使每个主组件都具有高可用性。 + +### etcd 节点数 + +在保持集群可用性的同时，可以一次丢失的节点数由分配了 `etcd` 角色的节点数决定。对于具有 n 个成员的集群，最小值为 (n/2)+1。因此，我们建议在一个区域内的 3 个不同可用区中各创建一个 `etcd` 节点，以在一个可用区丢失的情况下存活。如果你只使用两个区域，那么在“多数节点”所在的可用区不可用时，你将会丢失 etcd 集群。 + +| 具有 `etcd` 角色的节点 | 多数节点 | 容错能力 | +|--------------|------------|-------------------| +| 1 | 1 | 0 | +| 2 | 2 | 0 | +| 3 | 2 | **1** | +| 4 | 3 | 1 | +| 5 | 3 | **2** | +| 6 | 4 | 2 | +| 7 | 4 | **3** | +| 8 | 5 | 3 | +| 9 | 5 | **4** | + +参考： + +* [最佳 etcd 集群大小的官方 etcd 文档](https://etcd.io/docs/v3.5/faq/#what-is-failure-tolerance) +* [为 Kubernetes 操作 etcd 集群的官方 Kubernetes 文档](https://kubernetes.io/docs/tasks/administer-cluster/configure-upgrade-etcd/) + +### Worker 节点数 + +添加多个具有 `worker` 角色的节点能确保一个节点出现故障时可以重新安排工作负载。 + +### 为什么 Rancher 集群和运行应用的集群的生产要求不同 + +你可能已经注意到我们的 [Kubernetes 安装](../../../../getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/install-upgrade-on-a-kubernetes-cluster.md)说明并不符合我们对生产就绪集群的要求，这是因为 `worker` 角色没有专用节点。然而，你 Rancher 中的这个三节点集群是有效的，因为： + +* 它允许一个 `etcd` 节点故障。 +* 它通过多个 `controlplane` 节点来维护 master 组件的多个实例。 +* 此集群上没有创建除 Rancher 之外的其他工作负载。 + +## 参考 + +* [Kubernetes：主组件](https://kubernetes.io/docs/concepts/overview/components/#master-components) diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/checklist-for-production-ready-clusters/roles-for-nodes-in-kubernetes.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/checklist-for-production-ready-clusters/roles-for-nodes-in-kubernetes.md new file mode 100644 index 00000000000..cac53d51604 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/checklist-for-production-ready-clusters/roles-for-nodes-in-kubernetes.md @@ -0,0 +1,50 @@ +--- +title: Kubernetes 中节点的角色 +--- + +本节介绍 Kubernetes 中 etcd 节点、controlplane 节点和 worker 节点的角色，以及这些角色如何在集群中协同工作。 + +此图适用于 [Rancher 通过 RKE 部署的 Kubernetes 集群](../../launch-kubernetes-with-rancher/launch-kubernetes-with-rancher.md)： + +![集群图](/img/clusterdiagram.svg)
+线条表示组件之间的通信。而颜色纯粹用于视觉辅助。 + +## etcd + +具有 `etcd` 角色的节点运行 etcd，这是一个一致且高可用的键值存储，用作 Kubernetes 所有集群数据的后备存储。etcd 将数据复制到每个节点。 + +:::note + +具有 `etcd` 角色的节点在 UI 中显示为`不可调度`，即默认情况下不会将 Pod 调度到这些节点。 + +::: + +## controlplane + +具有 `controlplane` 角色的节点运行 Kubernetes 主组件（不包括 `etcd`，因为它是一个单独的角色）。有关组件的详细列表，请参阅 [Kubernetes：主组件](https://kubernetes.io/docs/concepts/overview/components/#master-components)。 + +:::note + +具有 `controlplane` 角色的节点在 UI 中显示为`不可调度`，即默认情况下不会将 Pod 调度到这些节点。 + +::: + +### kube-apiserver + +Kubernetes API Server (`kube-apiserver`) 能水平扩展。如果节点具有需要访问 Kubernetes API Server 的组件，则每个具有 `controlplane` 角色的节点都将被添加到节点上的 NGINX 代理中。这意味着如果一个节点变得不可访问，该节点上的本地 NGINX 代理会将请求转发到列表中的另一个 Kubernetes API Server。 + +### kube-controller-manager + +Kubernetes Controller Manager 使用 Kubernetes 中的端点进行 Leader 选举。`kube-controller-manager` 的一个实例将在 Kubernetes 端点中创建一个条目，并在配置的时间间隔内更新该条目。其他实例将看到一个状态为 Active 的 Leader，并等待该条目过期（例如节点无响应）。 + +### kube-scheduler + +Kubernetes 调度器使用 Kubernetes 中的端点进行 Leader 选举。`kube-scheduler` 的一个实例将在 Kubernetes 端点中创建一个条目，并在配置的时间间隔内更新该条目。其他实例将看到一个状态为 Active 的 Leader，并等待该条目过期（例如节点无响应）。 + +## worker + +具有 `worker` 角色的节点运行 Kubernetes 节点组件。有关组件的详细列表，请参阅 [Kubernetes：节点组件](https://kubernetes.io/docs/concepts/overview/components/#node-components)。 + +## 参考 + +* [Kubernetes：节点组件](https://kubernetes.io/docs/concepts/overview/components/#node-components) \ No newline at end of file diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/kubernetes-clusters-in-rancher-setup.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/kubernetes-clusters-in-rancher-setup.md new file mode 100644 index 00000000000..c64ddfc51f9 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/kubernetes-clusters-in-rancher-setup.md @@ -0,0 +1,78 @@ +--- +title: Rancher 中的 Kubernetes 集群设置 +description: 配置 Kubernetes 集群 +--- + + + + + +Rancher 允许你通过 Rancher UI 来创建集群，从而简化了集群的创建流程。Rancher 提供了多种启动集群的选项。你可以选择最适合你的用例的选项。 + +本节默认你已对 Docker 和 Kubernetes 有一定的了解。如果你需要了解 Kubernetes 组件如何协作，请参见 [Kubernetes 概念](../../../reference-guides/kubernetes-concepts.md)页面。 + +有关 Rancher Server 配置集群的方式，以及使用什么工具来创建集群的详细信息，请参阅[产品架构](../../../reference-guides/rancher-manager-architecture/rancher-manager-architecture.md)页面。 + +## 不同类型集群的管理功能 + +下表总结了每一种类型的集群和对应的可编辑的选项和设置： + +import ClusterCapabilitiesTable from '../../../shared-files/\_cluster-capabilities-table.md'; + + + +## 在托管的 Kubernetes 提供商中设置集群 + +在这种情况下，Rancher 不会配置 Kubernetes，因为它是由 Google Kubernetes Engine (GKE)、Amazon Elastic Container Service for Kubernetes 或 Azure Kubernetes Service 等提供商安装的。 + +如果你使用 Kubernetes 提供商，例如 Google GKE，Rancher 将与对应的云 API 集成，允许你从 Rancher UI 为托管集群创建和管理 RBAC。 + +详情请参阅[托管 Kubernetes 集群](set-up-clusters-from-hosted-kubernetes-providers/set-up-clusters-from-hosted-kubernetes-providers.md)部分。 + +## 使用 Rancher 启动 Kubernetes + +在你自己的节点上配置 Kubernetes 时，Rancher 使用 [Rancher Kubernetes Engine (RKE)](https://rancher.com/docs/rke/latest/en/) 作为库。RKE 是 Rancher 自己的轻量级 Kubernetes 安装程序。 + +在 RKE 集群中，Rancher 管理 Kubernetes 的部署。这些集群可以部署在任何裸机服务器、云提供商或虚拟化平台上。 + +这些节点可以通过 Rancher 的 UI 动态配置，该 UI 调用 [Docker Machine](https://github.com/docker/docs/blob/vnext-engine/machine/overview.md) 在各种云提供商上启动节点。 + +如果你已经有一个想要添加到 RKE 集群的节点，你可以通过在节点上运行 Rancher Agent 容器将节点添加到集群中。 + +有关详细信息，请参阅 [RKE 集群](../launch-kubernetes-with-rancher/launch-kubernetes-with-rancher.md)部分。 + +### 在基础设施提供商中启动 Kubernetes 并配置节点 + +Rancher 可以在 Amazon EC2、DigitalOcean、Azure 或 vSphere 等基础设施提供商中动态配置节点，然后在节点上安装 Kubernetes。 + +使用 Rancher，你可以基于[节点模板](../launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/use-new-nodes-in-an-infra-provider.md#节点模板)创建节点池。此模板定义了要在云提供商中启动的节点的参数。 + +使用由基础设施提供商托管的节点的一个好处是，如果一个节点与集群失去连接，Rancher 可以自动替换它，从而维护集群配置。 + +Rancher UI 中状态为 Active 的[主机驱动](../launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/use-new-nodes-in-an-infra-provider.md#主机驱动)决定了可用于创建节点模板的云提供商。 + +如需更多信息，请参阅[基础设施提供商托管的节点](../launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/use-new-nodes-in-an-infra-provider.md)部分。 + +### 在现有自定义节点上启动 Kubernetes + +在设置这种类型的集群时，Rancher 会在现有的[自定义节点](../../../reference-guides/cluster-configuration/rancher-server-configuration/use-existing-nodes/use-existing-nodes.md)上安装 Kubernetes，从而创建一个自定义集群。 + +你可以使用任何节点，在 Rancher 中创建一个集群。 + +这些节点包括本地裸机服务器、云托管虚拟机或本地虚拟机。 + +## 注册现有集群 + +集群注册功能取代了导入集群的功能。 + +注册 EKS 集群的优点更多。在大多数情况下，注册的 EKS 集群和在 Rancher 中创建的 EKS 集群在 Rancher UI 中的处理方式相同（除了删除）。 + +删除在 Rancher 中创建的 EKS 集群后，该集群将被销毁。删除在 Rancher 中注册的 EKS 集群时，它与 Rancher Server 会断开连接，但它仍然存在。你仍然可以像在 Rancher 中注册之前一样访问它。 + +详情请参见[本页面](register-existing-clusters.md)。 + +## 以编程方式创建集群 + +通过 Rancher 以编程方式部署 Kubernetes 集群的最常见方法是使用 Rancher 2 Terraform Provider。详情请参见[使用 Terraform 创建集群](https://registry.terraform.io/providers/rancher/rancher2/latest/docs/resources/cluster)。 + +你可以使用 Terraform 创建或导入 EKS、GKE、AKS 集群和 RKE 集群。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/migrate-to-an-out-of-tree-cloud-provider/migrate-to-out-of-tree-amazon.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/migrate-to-an-out-of-tree-cloud-provider/migrate-to-out-of-tree-amazon.md new file mode 100644 index 00000000000..fb21c4e82ef --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/migrate-to-an-out-of-tree-cloud-provider/migrate-to-out-of-tree-amazon.md @@ -0,0 +1,194 @@ +--- +title: 将 Amazon 从树内迁移到树外 +--- + + + + + +Kubernetes 不再在树内维护云提供商。在 Kubernetes v1.27 及更高版本中，树内云提供商已被移除。当你从树内提供商迁移到树外提供商时，Rancher UI 允许你升级到 Kubernetes v1.27。 + +不过，如果你执行的是手动迁移，现有集群必须在迁移后升级到 Kubernetes v1.27 才能继续运行。 + +要从树内云提供商迁移到树外 AWS 云提供商，必须停止现有集群的 kube 控制器管理器，并安装 AWS 云控制器管理器。有许多方法可以做到这一点。有关详情，请参阅有关[外部云控制器管理器](https://cloud-provider-aws.sigs.k8s.io/getting_started/)的 AWS 官方文档。 + +如果可以接受迁移过程中出现一些停机，请按照说明[设置外部云提供商](../set-up-cloud-providers/amazon.md#using-the-out-of-tree-aws-cloud-provider)。这些说明概述了如何为新配置的集群配置树外云提供商。在设置过程中，会有一些停机，因为从旧云提供商停止运行到新云提供商开始运行之间会有一段时间的间隔。 + +如果您的设置不能容忍任何控制平面停机，则必须启用领导者迁移。这有助于从 kube 控制器管理器中的控制器顺利过渡到云控制器管理器中的对应控制器。有关详细信息，请参阅 AWS 官方文档[使用领导者迁移](https://cloud-provider-aws.sigs.k8s.io/getting_started/)。 + +:::note Important: +Kubernetes [云控制器迁移文档](https://kubernetes.io/docs/tasks/administer-cluster/controller-manager-leader-migration/#before-you-begin)指出，可以使用相同的 Kubernetes 版本进行迁移，但假设迁移是 Kubernetes 升级的一部分。请参考有关[迁移到要使用的云控制器管理器](https://kubernetes.io/docs/tasks/administer-cluster/controller-manager-leader-migration/)的 Kubernetes 文档，了解迁移前是否需要自定义设置。确认[迁移配置值](https://kubernetes.io/docs/tasks/administer-cluster/controller-manager-leader-migration/#default-configuration)。如果您的云提供商提供 Node IPAM 控制器的实现，您还需要迁移 [IPAM 控制器](https://kubernetes.io/docs/tasks/administer-cluster/controller-manager-leader-migration/#node-ipam-controller-migration)。 +::: + + + + +1. 更新集群配置，启用领导者迁移： + +```yaml +spec: + rkeConfig: + machineSelectorConfig: + - config: + kube-controller-manager-arg: + - enable-leader-migration + machineLabelSelector: + matchExpressions: + - key: rke.cattle.io/control-plane-role + operator: In + values: + - "true" +``` + +请注意，云提供商在此步骤中仍是 `aws` + +```yaml +spec: + rkeConfig: + machineGlobalConfig: + cloud-provider-name: aws +``` + +2. 标记控制平面节点不可调度，以便 AWS 云控制器 pod 仅在升级到外部云提供商后才在节点上运行： + +```shell +kubectl cordon -l "node-role.kubernetes.io/control-plane=true" +``` + +3. 要安装启用了领导者迁移的 AWS 云控制器管理器，请遵循[部署云控制器管理器 Chart](../set-up-cloud-providers/amazon.md#using-the-out-of-tree-aws-cloud-provider) 的步骤 1-3。从 Kubernetes 1.22 起，kube-controller-manager 将使用默认配置，该配置将满足 controller-to-manager 的迁移。更新 `spec.rkeConfig.additionalManifest` 下 `aws-cloud-controller-manager` 的容器参数，以启用领导者迁移： + +```shell +- '--enable-leader-migration=true' +``` + +4. 安装 Chart 并确认 Daemonset `aws-cloud-controller-manager` 已成功部署： + +```shell +kubectl rollout status daemonset -n kube-system aws-cloud-controller-manager +``` + +5. 更新配置集群以更改云提供商，并从 kube 控制器中移除领导者迁移 参数。如果升级 Kubernetes 版本，也要在集群 YAML 文件的 `spec.kubernetesVersion` 部分设置 Kubernetes 版本 + +:::note Important + +如果不依赖 rke2 监管程序正确设置提供商 ID，则只移除 `cloud-provider-name: aws`。 + +::: + +如果不想在集群中启用 `enable-leader-migration` 功能，请将其移除： + +```yaml +spec: + rkeConfig: + machineGlobalConfig: + cloud-provider-name: external +``` + +移除 `enable-leader-migration`： + +```yaml +spec: + rkeConfig: + machineSelectorConfig: + - config: + kube-controller-manager-arg: + - enable-leader-migration + machineLabelSelector: + matchExpressions: + - key: rke.cattle.io/control-plane-role + operator: In + values: + - "true" +``` + +:::tip + +您也可以在升级后禁用领导者迁移，因为由于只有一个云控制器管理器，不再需要领导者迁移，可以将其移除。升级 Chart 并从容器参数中删除以下部分： + +```yaml +- --enable-leader-migration=true +``` + +::: + +使用以下命令验证云控制器管理器更新是否成功上线： + +```shell +kubectl rollout status daemonset -n kube-system aws-cloud-controller-manager +``` + +6. 云提供商负责设置节点的 ProviderID。检查是否所有节点都用 ProviderID 进行了初始化： + +```shell +kubectl describe nodes | grep "ProviderID" +``` + + + + + +1. 更新集群配置，在 `cluster.yml` 中启用领导者迁移： + +```yaml +services: + kube-controller: + extra_args: + enable-leader-migration: "true" +``` + +请注意，云提供商在此步骤中仍是 `aws` + +```yaml +cloud_provider: + name: aws +``` + +2. 标记控制平面节点不可调度，以便 AWS 云控制器 pod 仅在升级到外部云提供商后才在节点上运行： + +```shell +kubectl cordon -l "node-role.kubernetes.io/controlplane=true" +``` + +3. 要安装 AWS 云控制器管理器，必须启用领导者迁移，并遵循在新集群上安装 AWS 时的相同步骤。要启用领导者迁移，请在步骤 7 中的容器参数中添加以下内容，同时[按照步骤安装 Chart](../set-up-cloud-providers/amazon.md#helm-chart-installation-from-ui)： + +```yaml +- "--enable-leader-migration=true" +``` + +4. 确认 Chart 已安装，但由于控制面板节点不可调度，新的 pod 尚未运行。在下一步更新集群后，RKE 将升级并允许对每个节点的调度，并调度 `aws-controller-manager` pod。 + +5. 更新 `cluster.yml`以更改云提供商，并从 kube-controller 中移除领导者迁移参数。 + +选择 **External Amazon (out-of-tree)** 可设置 `--cloud-provider=external`，并启用 `useInstanceMetadataHostname`。节点驱动集群和自定义集群必须启用 `useInstanceMetadataHostname`，否则无法通过 `--node-name`提供自定义节点名称。启用 `useInstanceMetadataHostname` 会查询 ec2 元数据服务，并为 `kubelet` 和 `kube-proxy`将 `/hostname` 设置为 `hostname-override` ： + +```yaml +rancher_kubernetes_engine_config: + cloud_provider: + name: external-aws + useInstanceMetadataHostname: true/false +``` + +如果不想在集群中启用 `enable-leader-migration`，请移除它： + +```yaml +services: + kube-controller: + extra_args: + enable-leader-migration: "true" +``` + +:::tip +完成迁移后，还可以禁用领导者迁移。升级 Chart 并从容器参数中删除以下部分： + +```yaml +- --enable-leader-migration=true +``` + +::: + +6. 如果要升级集群的 Kubernetes 版本，也要设置 Kubernetes 版本。 + +7. 更新集群。现在，`aws-cloud-controller-manager` pod 应该已经运行。 + + + diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/migrate-to-an-out-of-tree-cloud-provider/migrate-to-out-of-tree-vsphere.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/migrate-to-an-out-of-tree-cloud-provider/migrate-to-out-of-tree-vsphere.md new file mode 100644 index 00000000000..bda5e415a7d --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/migrate-to-an-out-of-tree-cloud-provider/migrate-to-out-of-tree-vsphere.md @@ -0,0 +1,111 @@ +--- +title: 将 vSphere 从树内迁移到树外 +--- + + + + + +Kubernetes 不再在树内维护云提供商。vSphere 有一个树外云提供商，可以通过安装 vSphere 云提供商和云存储插件来使用。 + +本页面介绍如何从树内 vSphere 云提供商迁移到树外，并在迁移后管理现有虚拟机。 + +它遵循官方 [vSphere 迁移文档](https://vsphere-csi-driver.sigs.k8s.io/features/vsphere_csi_migration.html)中提供的步骤，并提供在 Rancher 中执行的步骤。 + +## Cloud-config 格式限制 + +由于 vSphere Cloud Storage Interface (CSI) 中的一个现有错误，使用以下 cloud-config 格式配置的现有卷将无法迁移。 + +如果 cloud-config 中的数据存储和资源池路径采用这种格式，vsphere CSI 驱动程序将无法识别它： + +```yaml +default-datastore: /datastore/ +resourcepool-path: "/host//Resources/" +``` + +使用树内提供商以下列格式配置的卷将正确迁移： + +```yaml +default-datastore: +resourcepool-path: "/Resources/" +``` + +上游 bug: https://github.com/kubernetes-sigs/vsphere-csi-driver/issues/628 + +Rancher 问题跟踪此 bug: https://github.com/rancher/rancher/issues/31105 + +## 前提条件 + +- vSphere CSI 迁移需要 vSphere 7.0u1。为了能够管理现有树内 vSphere 卷，请将 vSphere 升级到 7.0u1。 +- Kubernetes 版本必须为 1.19 或更高。 + +## 迁移 + +### 1. 安装 CPI 插件 + +安装 CPI 之前，我们需要用 `node.cloudprovider.kubernetes.io/uninitialized=true:NoSchedule` 标记所有节点。 + +可以通过运行以下命令来完成： + +``` +curl -O https://raw.githubusercontent.com/rancher/helm3-charts/56b622f519728378abeddfe95074f1b87ab73b1e/charts/vsphere-cpi/taints.sh +``` + +或: + +``` +wget https://raw.githubusercontent.com/rancher/helm3-charts/56b622f519728378abeddfe95074f1b87ab73b1e/charts/vsphere-cpi/taints.sh +chmod +x taints.sh +./taints.sh +``` + +运行脚本并标记所有节点后，启动 Helm vSphere CPI Chart。 + +1. 点击 **☰ > Cluster Management**. +1. 转到将要安装 vSphere CPI Chart 的集群，然后点击 **Explore**. +1. 点击 **Apps > Charts**. +1. 点击 **vSphere CPI**. +1. 点击 **Install**. +1. 填写所需的 vCenter 详细信息，然后单击 **Install**. + +vSphere CPI 会使用 ProviderID 初始化所有节点，这是 vSphere CSI 驱动程序所需要的。 + +使用以下命令检查是否用 ProviderID 初始化了所有节点： + +``` +kubectl describe nodes | grep "ProviderID" +``` + +### 2. 安装 CSI 驱动程序 + +1. 点击 **☰ > Cluster Management**. +1. 转到将要安装 vSphere CSI Chart 的集群，点击 **Explore**. +1. 点击 **Apps > Charts**. +1. 点击 **vSphere CSI**. +1. 点击 **Install**. +1. 填写所需的 vCenter 详细信息，然后单击 **Install**. +1. 选中 **Customize Helm options before install**，然后单击 **Next**. +1. 在 **Features** 选项卡上， 选中 **Enable CSI Migration**. +1. （可选）转到 **Storage** 选项卡设置数据存储。此 Chart 会创建一个以 `csi.vsphere.vmware.com` 作为供应商的 StorageClass。在创建此 StorageClass 时，您可以提供用于 CSI 卷配置的数据存储的 URL。数据存储 URL 可在 vSphere 客户端中通过选择数据存储并转到摘要选项卡找到。填写 StorageClass 的详细信息。 +1. 点击 **Install**. + +### 3. 编辑集群以启用 CSI 迁移功能标志 + +1. 编辑集群时，如果 Kubernetes 版本低于 1.19，请从 **Kubernetes Version** 下拉菜单中选择 1.19 或更高版本。 +2. 要启用功能标志，请单击 "Edit as YAML", 然后在 kube-controller 和 kubelet 下添加以下内容: + + ```yaml + extra_args: + feature-gates: "CSIMigration=true,CSIMigrationvSphere=true" + ``` + +### 4. 清空工作节点 + +在升级过程中，必须先清空工作节点，然后再更改kubelet和kube-controller-manager参数。 + +1. 点击 **☰ > Cluster Management**。 +1. 转到要清空工作节点的集群，点击 **⋮ > Edit Config**。 +1. 在 **Advanced Options** 部分，将 **Maximum Worker Nodes Unavailable** 字段设为 1。 +1. 要在升级期间清空节点，请选择 **Drain Nodes > Yes**. +1. 将 **Force** 和 **Delete Local Data** 设置为 **true**. +1. 点击 **Save** 升级集群。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/node-requirements-for-rancher-managed-clusters.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/node-requirements-for-rancher-managed-clusters.md new file mode 100644 index 00000000000..4d44e8df40e --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/node-requirements-for-rancher-managed-clusters.md @@ -0,0 +1,129 @@ +--- +title: Rancher 管理集群的节点要求 +--- + +本页描述了 Rancher 管理的 Kubernetes 集群的要求，你的应用和服务将安装在这些集群中。这些下游集群应该与运行 Rancher 的三节点集群分开。 + +:::note + +如果 Rancher 安装在高可用的 Kubernetes 集群上，Rancher Server 的三节点集群和下游集群有不同的要求。有关 Rancher 的安装要求，请参考[安装文档](../../../getting-started/installation-and-upgrade/installation-requirements/installation-requirements.md)中的节点要求。 + +::: + +## 操作系统和容器运行时要求 + +Rancher 兼容当前所有的主流 Linux 发行版和任何通用的 Docker 版本。所有下游集群的 etcd 和 controlplane 节点都需要运行在 Linux 上。而 Worker 节点可以运行在 Linux 或 [Windows Server](#windows-节点) 上。 + +如需了解各个 Rancher 版本通过了哪些操作系统和 Docker 版本测试，请参见[支持和维护条款](https://rancher.com/support-maintenance-terms/)。 + +所有支持的操作系统都使用 64-bit x86 架构。 + +如果你想使用 ARM64，请参阅[在 ARM64 上运行（实验功能）。](../../advanced-user-guides/enable-experimental-features/rancher-on-arm64.md) + +有关如何安装 Docker 的信息，请参阅 [Docker 官方文档](https://docs.docker.com/)。 + +### Oracle Linux 和 RHEL 衍生的 Linux 节点 + +某些源自 RHEL 的 Linux 发行版（包括 Oracle Linux）的默认防火墙规则可能会阻止与 Helm 的通信。我们建议禁用 firewalld。如果你的 Kubernetes 版本是 1.19，请务必禁用 firewalld。 + +:::note + +在 RHEL 8.4 中，NetworkManager 上有两个额外的服务，即 `nm-cloud-setup.service` 和 `nm-cloud-setup.timer`。这些服务增加了一个路由表，干扰了 CNI 插件的配置。如果启用了这些服务，你必须使用以下命令禁用它们，然后重新启动节点以恢复连接： + +``` +systemctl disable nm-cloud-setup.service nm-cloud-setup.timer +reboot +``` + +::: + +### SUSE Linux 节点 + +SUSE Linux 可能有一个防火墙，默认情况下会阻止所有端口。在这种情况下，请按照[步骤](../../../getting-started/installation-and-upgrade/installation-requirements/port-requirements.md#打开-suse-linux-端口)打开将主机添加到自定义集群所需的端口。 + +### Flatcar Container Linux 节点 + +使用 Flatcar Container Linux 节点[通过 Rancher 启动 Kubernetes](../launch-kubernetes-with-rancher/launch-kubernetes-with-rancher.md) 时，需要在 [Cluster Config 文件](../../../reference-guides/cluster-configuration/rancher-server-configuration/rke1-cluster-configuration.md#rke-集群配置文件参考)中使用如下配置： + + + + +```yaml +rancher_kubernetes_engine_config: + network: + plugin: canal + options: + canal_flex_volume_plugin_dir: /opt/kubernetes/kubelet-plugins/volume/exec/nodeagent~uds + flannel_backend_type: vxlan + + services: + kube-controller: + extra_args: + flex-volume-plugin-dir: /opt/kubernetes/kubelet-plugins/volume/exec/ +``` + + + + +```yaml +rancher_kubernetes_engine_config: + network: + plugin: calico + options: + calico_flex_volume_plugin_dir: /opt/kubernetes/kubelet-plugins/volume/exec/nodeagent~uds + flannel_backend_type: vxlan + + services: + kube-controller: + extra_args: + flex-volume-plugin-dir: /opt/kubernetes/kubelet-plugins/volume/exec/ +``` + + + + +还需要启用 Docker 服务，你可以使用以下命令启用 Docker 服务： + +``` +systemctl enable docker.service +``` + +使用[主机驱动](../authentication-permissions-and-global-configuration/about-provisioning-drivers/about-provisioning-drivers.md#主机驱动)时会自动启用 Docker 服务。 + +### Windows 节点 + +运行 Windows Server 节点必须使用 Docker 企业版。 + +Windows 节点只能用于 Worker 节点。请参阅[配置 Windows 自定义集群](./use-windows-clusters/use-windows-clusters.md)。 + +## 硬件要求 + +你的工作负载决定了具有 `worker` 角色的节点的硬件要求。运行 Kubernetes 节点组件的最低要求是 1 个 CPU（核心）和 1GB 内存。 + +关于 CPU 和内存，建议将 Kubernetes 集群的不同平面（etcd、controlplane 和 worker）托管在不同的节点上，以便它们可以相互独立扩展。 + +有关大型 Kubernetes 集群的硬件建议，请参阅[构建大型集群](https://kubernetes.io/docs/setup/best-practices/cluster-large/)的官方 Kubernetes 文档。 + +有关生产环境中 etcd 集群的硬件建议，请参阅官方 [etcd 文档](https://etcd.io/docs/v3.5/op-guide/hardware/)。 + +## 网络要求 + +对于生产集群，我们建议你通过仅打开以下端口要求中定义的端口来限制流量。 + +需要开放的端口根据下游集群的启动方式而有所不同。以下列出了需要为不同[集群创建选项](./kubernetes-clusters-in-rancher-setup.md)打开的端口。 + +有关 Kubernetes 集群中 etcd 节点、controlplane 节点和 Worker 节点的端口要求的详细信息，请参阅 [Rancher Kubernetes Engine 的端口要求](https://rancher.com/docs/rke/latest/en/os/#ports)。 + +在[下游集群端口要求](../../../getting-started/installation-and-upgrade/installation-requirements/port-requirements.md#下游-kubernetes-集群节点)中，你可以找到在各种情况下使用的端口的详细信息。 + +:::caution + +不要使用与现有节点相同的主机名或 IP 地址来注册节点。这样做会导致 RKE 阻止节点加入，并导致配置挂起。主机驱动和自定义集群都可能发生这种情况。如果节点必须重用现有节点的主机名或 IP，则必须在注册节点之前设置 `hostname_override` [RKE 选项](https://rke.docs.rancher.com/config-options/nodes#overriding-the-hostname)，以便节点能够正确加入。 + +::: + +## 可选：安全注意事项 + +如果你要配置符合 CIS（互联网安全中心）Kubernetes 基准的 Kubernetes 集群，我们建议你在安装 Kubernetes 之前按照我们的强化指南来配置节点。 + +有关强化指南的更多信息，以及了解哪个指南版本对应于你的 Rancher 和 Kubernetes 版本，请参阅[安全](../../../reference-guides/rancher-security/rancher-security.md#rancher-加固指南)。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/register-existing-clusters.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/register-existing-clusters.md new file mode 100644 index 00000000000..e155a38a4f9 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/register-existing-clusters.md @@ -0,0 +1,273 @@ +--- +title: 注册现有集群 +--- + +集群注册功能取代了导入集群的功能。 + +Rancher 管理注册集群的范围取决于集群的类型。详情请参见[对注册集群的管理能力](#对注册集群的管理能力)。 + + +## 先决条件 + +### Kubernetes 节点角色 + +已注册的 RKE Kubernetes 集群必须具有所有三个节点角色，分别是 etcd、controlplane 和 worker。只有 controlplane 组件的集群无法在 Rancher 中注册。 + +有关 RKE 节点角色的更多信息，请参阅[最佳实践](./checklist-for-production-ready-clusters/checklist-for-production-ready-clusters.md#集群架构)。 + +### 权限 + +要在 Rancher 中注册集群，你必须在该集群中拥有 `cluster-admin` 权限。如果没有，请运行以下命令将权限授予用户： + +```plain +kubectl create clusterrolebinding cluster-admin-binding \ + --clusterrole cluster-admin \ + --user [USER_ACCOUNT] +``` + +由于默认情况下 Google Kubernetes Engine (GKE) 不授予 `cluster-admin` 角色，因此你必须先在 GKE 集群上运行命令，然后才能注册。要详细了解 GKE RBAC，请参阅 [Google 官方文档](https://cloud.google.com/kubernetes-engine/docs/how-to/role-based-access-control)。 + +### EKS、AKS 和 GKE 集群 + +要成功将这些集群导入 Rancher 或从 Rancher 中配置它们，Elastic Kubernetes Service (EKS)、Azure Kubernetes Service (AKS) 和 Google Kubernetes Engine (GKE) 集群必须至少有一个托管节点组。此外，不支持 GKE Autopilot 集群。有关 GKE 模式之间差异，请参阅[比较 GKE Autopilot 和 Standard](https://cloud.google.com/kubernetes-engine/docs/resources/autopilot-standard-feature-comparison)。 + +## 注册集群 + +1. 点击 **☰ > 集群管理**。 +2. 在**集群**页面上，单击**导入集群**。 +3. 选择集群类型。 +4. 使用**成员角色**为集群配置用户授权。点击**添加成员**添加可以访问集群的用户。使用**角色**下拉菜单为每个用户设置权限。 +5. 如果你在 Rancher 中导入一个通用 Kubernetes 集群，请执行以下步骤：
+ a. 点击**集群选项**下的 **Agent 环境变量**，为 [rancher cluster agent](../launch-kubernetes-with-rancher/about-rancher-agents.md) 设置环境变量。你可以使用键值对设置环境变量。如果 Rancher Agent 需要使用代理与 Rancher Server 通信，则可以使用 Agent 环境变量设置 `HTTP_PROXY`，`HTTPS_PROXY` 和 `NO_PROXY` 环境变量。
+ b. 启用项目网络隔离，确保集群支持 Kubernetes `NetworkPolicy` 资源。用户可以通过**项目网络隔离**选项下的**高级选项**下拉菜单进行操作。 +6. 单击**创建**。 +7. 此处会显示 `cluster-admin` 权限的先决条件（参见上文的**先决条件**），其中包括满足先决条件的示例命令。 +8. 将 `kubectl` 命令复制到剪贴板，并在配置了 kubeconfig 的节点上运行该命令，从而指向要导入的集群。如果你不确定配置是否正确，请在运行 Rancher 显示的命令之前运行 `kubectl get nodes` 进行验证。 +9. 如果你使用自签名证书，你将收到 `certificate signed by unknown authority` 的消息。要解决此验证问题，请将 Rancher 中显示的以 `curl` 开头的命令复制到剪贴板。然后在配置了 kubeconfig 的节点上运行该命令，从而指向要导入的集群。 +10. 在节点上运行完命令后，单击**完成**。 + +**结果**： + +- 集群已注册并分配了 **Pending** 状态。Rancher 正在部署资源来管理你的集群。 +- 当集群状态变为 **Active** 后，你可访问集群。 +- **Active** 集群分配了两个项目，分别是 `Default`（包含命名空间 `default`）和 `System`（包含命名空间 `cattle-system`、`ingress-nginx`、`kube-public` 和 `kube-system`）。 + + +:::note + +无法重新注册当前在 Rancher 中处于 Active 状态的集群。 + +::: + +### 使用 Terraform 配置导入的 EKS、AKS 或 GKE 集群 + +你**仅**需要定义 Rancher 使用 Terraform 导入 EKS、AKS 或 GKE 集群所需的最少字段。请谨记这点，因为 Rancher 会使用用户提供的任何配置覆盖集群的配置。 + +:::caution + +即使当前集群的配置与用户提供的配置之间只存在微小差异，但是微小的差异也有可能产生很大的影响。 + +::: + +Rancher 通过 `eks_config_v2` 使用 Terraform 导入 EKS 集群所需的最少配置字段如下： + +- cloud_credential_id +- name +- region +- imported （对于导入的集群，此字段应始终设置为 `true`） + +导入的 EKS 集群的示例 YAML 配置： + +``` +resource "rancher2_cluster" "my-eks-to-import" { + name = "my-eks-to-import" + description = "Terraform EKS Cluster" + eks_config_v2 { + cloud_credential_id = rancher2_cloud_credential.aws.id + name = var.aws_eks_name + region = var.aws_region + imported = true + } +} +``` + +你可以在 [Rancher2 Terraform Provider 文档](https://registry.terraform.io/providers/rancher/rancher2/latest/docs/resources/cluster)中找到其他云提供商的更多示例。 + +## 对注册集群的管理能力 + +Rancher 管理注册集群的范围取决于集群的类型。 + +- [所有已注册集群的功能](#所有已注册集群的功能) +- [已注册 RKE2 和 K3s 集群的附加功能](#已注册-rke2-和-k3s-集群的附加功能) +- [已注册 EKS, AKS 和 GKE 集群的附加功能](#已注册-eksaks-和-gke-集群的附加功能) + +### 所有已注册集群的功能 + +注册集群后，集群所有者可以： + +- 通过 RBAC [管理集群访问](../authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/cluster-and-project-roles.md) +- 启用[Monitoring、告警和 Notifiers](../../../integrations-in-rancher/monitoring-and-alerting/monitoring-and-alerting.md) +- 启用 [Logging](../../../integrations-in-rancher/logging/logging.md) +- 启用 [Istio](../../../integrations-in-rancher/istio/istio.md) +- 管理项目和工作负载 + +### 已注册 RKE2 和 K3s 集群的附加功能 + +[K3s](https://rancher.com/docs/k3s/latest/en/) 是用于边缘安装的轻量级、完全兼容的 Kubernetes 发行版。 +[RKE2](https://docs.rke2.io) 是 Rancher 用于数据中心和云安装的下一代 Kubernetes 发行版。 + +RKE2 或 K3s 集群注册到 Rancher 后，Rancher 会识别它。Rancher UI 将开放[所有已注册集群](#所有已注册集群的功能)的功能，以及以下用于编辑和升级集群的功能： + +- [升级 Kubernetes 版本](../../../getting-started/installation-and-upgrade/upgrade-and-roll-back-kubernetes.md)的能力 + :::danger + + 将集群导入 Rancher 后，你需要使用 Rancher 执行升级。**不**支持在 Rancher 之外升级导入的集群。 + + ::: +- 配置能同时升级的最大节点数 +- 查看集群的配置参数和用于启动集群中每个节点的环境变量的只读版本 + +### 已注册 EKS，AKS 和 GKE 集群的附加功能 + +Rancher 处理注册的 EKS、AKS 或 GKE 集群的方式与处理在 Rancher 中创建的集群的方式类似。但是，如果你通过 Rancher UI 删除已注册的集群，Rancher 不会销毁这些集群。 + +如果你在 Rancher 中创建 EKS、AKS 或 GKE 集群，然后将其删除，Rancher 会销毁该集群。通过 Rancher 删除已注册的集群时，Rancher Server 会_断开_与集群的连接。该集群仍然存在，只是它不再在 Rancher 中。你仍然可以像注册前一样访问已注销的集群。 + +有关可用于管理已注册集群的功能，请参阅[按集群类型划分的集群管理功能](./kubernetes-clusters-in-rancher-setup.md)。 + +## 配置 RKE2 和 K3s 集群升级 + +:::tip + +Kubernetes 的最佳实践是在升级之前备份集群。使用外部数据库升级高可用 K3s 集群时，请使用关系数据库提供商推荐的方式备份数据库。 + +::: + +**并发**是升级期间允许不可用的最大节点数。如果不可用节点的数量大于**并发**，升级将失败。如果升级失败，你可能需要修复或移除失败的节点，然后升级才能成功。 + +- **controlplane 并发**：可以同时升级的最大服务器节点数；也是最大不可用服务器节点数 +- **Worker 并发**：可以同时升级的最大 worker 节点数；也是最大不可用 worker 节点数 + +在 RKE2 和 K3s 文档中，control plane 节点也称为 Server 节点。Kubernetes master 节点运行在这些节点上，用于维护集群的状态。默认情况下，control plane 节点默认能够让工作负载调度到节点上。 + +类似的，在 RKE2 和 K3s 文档中，具有 worker 角色的节点称为 Agent 节点。默认情况下，部署在集群中的任何工作负载或 Pod 都能调度到这些节点上。 + +## 已注册 RKE2 和 K3s 集群的 Logging 调试和故障排除 + +节点由运行在下游集群中的 `system-upgrade-controller` 升级。基于集群配置，Rancher 部署了两个[计划](https://github.com/rancher/system-upgrade-controller#example-upgrade-plan)来升级节点，分别用于升级 control plane 节点和 worker 节点。`system-upgrade-controller` 会按照计划对节点进行升级。 + +要在 `system-upgrade-controller` deployment 上启用调试日志记录，请编辑 [configmap](https://github.com/rancher/system-upgrade-controller/blob/50a4c8975543d75f1d76a8290001d87dc298bdb4/manifests/system-upgrade-controller.yaml#L32) 以将调试环境变量设置为 true。然后重启 `system-upgrade-controller` pod。 + +你可以运行以下命令查看 `system-upgrade-controller` 创建的日志： + +``` +kubectl logs -n cattle-system system-upgrade-controller +``` + +运行以下命令查看计划的当前状态： + +``` +kubectl get plans -A -o yaml +``` + +如果集群卡在升级中，请重启 `system-upgrade-controller`。 + +为防止升级时出现问题，应遵循 [Kubernetes 升级最佳实践](https://kubernetes.io/docs/tasks/administer-cluster/kubeadm/kubeadm-upgrade/)进行操作。 + +## 对 RKE2 和 K3s 集群的授权集群端点支持 + +_从 v2.6.3 起可用_ + +授权集群端点 (ACE) 已支持注册的 RKE2 和 K3s 集群。此支持还包括你在下游集群上启用 ACE 的手动步骤。有关授权集群端点的更多信息，请单击[这里](../manage-clusters/access-clusters/authorized-cluster-endpoint.md)。 + +:::note 注意事项： + +- 只需要在下游集群的 controlplane 节点上执行这些步骤。你必须单独配置每个 controlplane 节点。 + +- 以下步骤适用于在 v2.6.x 中注册的 RKE2 和 K3s 集群，以及从先前的 Rancher 版本注册（或导入）并升级到 v2.6.x 的集群。 + +- 这些步骤将改变下游 RKE2 和 K3s 集群的配置并部署 `kube-api-authn-webhook`。如果 ACE 的未来实现需要更新 `kube-api-authn-webhook`，那么这也必须手动完成。有关此 webhook 的更多信息，请单击[此处](../manage-clusters/access-clusters/authorized-cluster-endpoint.md#关于-kube-api-auth-身份验证-webhook)。 + +::: + +###### **在每个下游集群的 controlplane 上启用 ACE 的手动执行步骤**： + +1. 在 `/var/lib/rancher/{rke2,k3s}/kube-api-authn-webhook.yaml` 创建一个文件，内容如下： + ```yaml + apiVersion: v1 + kind: Config + clusters: + - name: Default + cluster: + insecure-skip-tls-verify: true + server: http://127.0.0.1:6440/v1/authenticate + users: + - name: Default + user: + insecure-skip-tls-verify: true + current-context: webhook + contexts: + - name: webhook + context: + user: Default + cluster: Default + ``` + +2. 将以下内容添加到配置文件中（如果文件不存在，则创建一个）。请注意，默认位置是 `/etc/rancher/{rke2,k3s}/config.yaml`： + ```yaml + kube-apiserver-arg: + - authentication-token-webhook-config-file=/var/lib/rancher/{rke2,k3s}/kube-api-authn-webhook.yaml + ``` + +3. 运行以下命令： + + sudo systemctl stop {rke2,k3s}-server + sudo systemctl start {rke2,k3s}-server + +4. 最后，你**必须**返回 Rancher UI 并在那里编辑导入的集群，从而完成 ACE 启用。单击 **⋮ > 编辑配置**，然后单击**集群配置**下的**网络**选项卡。最后，单击**授权端点**的**启用**按钮。启用 ACE 后，你可以输入完全限定的域名 (FQDN) 和证书信息。 + +:::note + +FQDN 字段是可选的。如果指定了该字段，它应该指向下游集群。仅当下游集群前面有使用了不受信任证书的负载均衡器时才需要证书信息。如果你使用的是有效证书，则不需要填写 CA 证书字段。 + +::: + +## 注释已注册的集群 + +Rancher 没有注册的 Kubernetes 集群（除了 RKE2 和 K3s Kubernetes 集群之外）如何预置或配置集群的任何信息。 + +因此，当 Rancher 注册集群时，它假设某些功能是默认禁用的。Rancher 这样做是为了避免向用户暴露 UI 选项（即使注册的集群没有启用这些功能）。 + +但是，如果集群具有某种功能（例如使用 pod 安全策略），那么该集群的用户可能仍希望在 Rancher UI 中为集群选择 pod 安全策略。为此，用户需要手动让 Rancher 知道集群已启用 pod 安全策略。 + +通过对已注册的集群进行注释，你可以向 Rancher 表明集群在 Rancher 之外被赋予了 Ingress 功能或其他功能。以下注释表示 Ingress 功能。请注意，非原始对象的值需要进行 JSON 编码，并转义引号： + +```json +"capabilities.cattle.io/ingressCapabilities": "[ + { + "customDefaultBackend":true, + "ingressProvider":"asdf" + } +]" +``` + +你可以为集群注释以下功能： + +- `ingressCapabilities` +- `loadBalancerCapabilities` +- `nodePoolScalingSupported` +- `nodePortRange` +- `taintSupport` + +所有功能及其类型定义都可以在 Rancher API 视图中查看，地址是 `[Rancher Server URL]/v3/schemas/capabilities`。 + +要注释已注册的集群： + +1. 点击 **☰ > 集群管理**。 +2. 在**集群**页面上，转到要注释的自定义集群，然后单击 **⋮ > 编辑配置**。 +3. 展开**标签 & 注释**。 +4. 单击**添加注释**。 +5. 使用 `capabilities/: ` 格式向集群添加注释，其中 `value` 是要使用注释覆盖的集群功能。在这种情况下，Rancher 在你添加注释之前都不知道集群的任何功能。 +6. 单击**保存**。 + +**结果**：注释并不是给集群提供功能，而是告知 Rancher 集群具有这些功能。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-cloud-providers/amazon.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-cloud-providers/amazon.md new file mode 100644 index 00000000000..72848467ff2 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-cloud-providers/amazon.md @@ -0,0 +1,730 @@ +--- +title: 设置 Amazon 云提供商 +weight: 1 +--- + +使用 `Amazon` 云提供商时，你可以利用以下功能： + +- **负载均衡器**：在 **Port Mapping** 中选择 `Layer-4 Load Balancer` 或使用 `type: LoadBalancer` 启动 `Service` 时，启动 AWS 弹性负载均衡器 (ELB)。 +- **持久卷**：允许你将 AWS 弹性块存储 (EBS) 用于持久卷。 + +有关 Amazon 云提供商的所有信息，请参阅 [cloud-provider-aws 自述文件](https://kubernetes.github.io/cloud-provider-aws/)。 + +要设置 Amazon 云提供商： + +1. [创建一个 IAM 角色并附加到实例](#1-创建-iam-角色并附加到实例) +2. [配置 ClusterID](#2-创建-clusterid) + +:::note 重要提示： + +从 Kubernetes 1.23 开始，你必须停用 `CSIMigrationAWS` 特性开关才能使用树内 AWS 云提供商。为此，你可以在高级集群配置中将 `feature-gates=CSIMigrationAWS=false` 设置为集群 Kubelet、Controller Manager、API Server 和 Scheduler 的附加参数。 + +::: + +## 1. 创建 IAM 角色并附加到实例 + +添加到集群的所有节点都必须能够与 EC2 交互，以便它们可以创建和删除资源。你可以使用附加到实例的 IAM 角色来启用交互。请参阅 [Amazon 文档：创建 IAM 角色](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/iam-roles-for-amazon-ec2.html#create-iam-role) 来创建 IAM 角色。有两个示例策略： + +* 第一个策略适用于具有 `controlplane` 角色的节点。这些节点必须能够创建/删除 EC2 资源。以下 IAM 策略是一个示例，请根据你的实际用例移除不需要的权限。 +* 第二个策略适用于具有 `etcd` 或 `worker` 角色的节点。这些节点只需能够从 EC2 检索信息。 + +在创建 [Amazon EC2 集群](../../launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/create-an-amazon-ec2-cluster.md)时，你必须在创建**节点模板**时填写创建的 IAM 角色的 **IAM Instance Profile Name**（不是 ARN）。 + +创建[自定义集群](../../../../reference-guides/cluster-configuration/rancher-server-configuration/use-existing-nodes/use-existing-nodes.md)时，你必须手动将 IAM 角色附加到实例。 + +具有 `controlplane` 角色的节点的 IAM 策略： + +```json +{ + "Version": "2012-10-17", + "Statement": [ + { + "Effect": "Allow", + "Action": [ + "autoscaling:DescribeAutoScalingGroups", + "autoscaling:DescribeLaunchConfigurations", + "autoscaling:DescribeTags", + "ec2:DescribeInstances", + "ec2:DescribeRegions", + "ec2:DescribeAvailabilityZones", + "ec2:DescribeRouteTables", + "ec2:DescribeSecurityGroups", + "ec2:DescribeSubnets", + "ec2:DescribeVolumes", + "ec2:CreateSecurityGroup", + "ec2:CreateTags", + "ec2:CreateVolume", + "ec2:ModifyInstanceAttribute", + "ec2:ModifyVolume", + "ec2:AttachVolume", + "ec2:AuthorizeSecurityGroupIngress", + "ec2:CreateRoute", + "ec2:DeleteRoute", + "ec2:DeleteSecurityGroup", + "ec2:DeleteVolume", + "ec2:DetachVolume", + "ec2:RevokeSecurityGroupIngress", + "ec2:DescribeVpcs", + "elasticloadbalancing:AddTags", + "elasticloadbalancing:AttachLoadBalancerToSubnets", + "elasticloadbalancing:ApplySecurityGroupsToLoadBalancer", + "elasticloadbalancing:CreateLoadBalancer", + "elasticloadbalancing:CreateLoadBalancerPolicy", + "elasticloadbalancing:CreateLoadBalancerListeners", + "elasticloadbalancing:ConfigureHealthCheck", + "elasticloadbalancing:DeleteLoadBalancer", + "elasticloadbalancing:DeleteLoadBalancerListeners", + "elasticloadbalancing:DescribeLoadBalancers", + "elasticloadbalancing:DescribeLoadBalancerAttributes", + "elasticloadbalancing:DetachLoadBalancerFromSubnets", + "elasticloadbalancing:DeregisterInstancesFromLoadBalancer", + "elasticloadbalancing:ModifyLoadBalancerAttributes", + "elasticloadbalancing:RegisterInstancesWithLoadBalancer", + "elasticloadbalancing:SetLoadBalancerPoliciesForBackendServer", + "elasticloadbalancing:AddTags", + "elasticloadbalancing:CreateListener", + "elasticloadbalancing:CreateTargetGroup", + "elasticloadbalancing:DeleteListener", + "elasticloadbalancing:DeleteTargetGroup", + "elasticloadbalancing:DescribeListeners", + "elasticloadbalancing:DescribeLoadBalancerPolicies", + "elasticloadbalancing:DescribeTargetGroups", + "elasticloadbalancing:DescribeTargetHealth", + "elasticloadbalancing:ModifyListener", + "elasticloadbalancing:ModifyTargetGroup", + "elasticloadbalancing:RegisterTargets", + "elasticloadbalancing:SetLoadBalancerPoliciesOfListener", + "iam:CreateServiceLinkedRole", + "kms:DescribeKey" + ], + "Resource": [ + "*" + ] + } + ] +} +``` + +具有 `etcd` 或 `worker` 角色的节点的 IAM 策略： + +```json +{ + "Version": "2012-10-17", + "Statement": [ + { + "Effect": "Allow", + "Action": [ + "ec2:DescribeInstances", + "ec2:DescribeRegions", + "ec2:DescribeAvailabilityZones", + "ecr:GetAuthorizationToken", + "ecr:BatchCheckLayerAvailability", + "ecr:GetDownloadUrlForLayer", + "ecr:GetRepositoryPolicy", + "ecr:DescribeRepositories", + "ecr:ListImages", + "ecr:BatchGetImage" + ], + "Resource": "*" + } + ] +} +``` + +## 2. 创建 ClusterID + +以下资源需要使用 `ClusterID` 进行标记： + +- **Nodes**：Rancher 中添加的所有主机。 +- **Subnet**：集群使用的子网。 +- **Security Group**：用于你的集群的安全组。 + +:::note + +不要标记多个安全组。创建弹性负载均衡器 (ELB) 时，标记多个组会产生错误。 + +::: + +创建 [Amazon EC2 集群](../../launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/create-an-amazon-ec2-cluster.md)时，会自动为创建的节点配置 `ClusterID`。其他资源仍然需要手动标记。 + +使用以下标签： + +**Key** = `kubernetes.io/cluster/CLUSTERID` **Value** = `owned` + +`CLUSTERID` 可以是任何字符串，只要它在所有标签集中相同即可。 + +将标签的值设置为 `owned` 会通知集群带有该标签的所有资源都由该集群拥有和管理。如果你在集群之间共享资源，你可以将标签更改为： + +**Key** = `kubernetes.io/cluster/CLUSTERID` **Value** = `shared`. + +## 使用 Amazon Elastic Container Registry (ECR) + +在将[创建 IAM 角色并附加到实例](#1-创建-iam-角色并附加到实例)中的 IAM 配置文件附加到实例时，kubelet 组件能够自动获取 ECR 凭证。使用低于 v1.15.0 的 Kubernetes 版本时，需要在集群中配置 Amazon 云提供商。从 Kubernetes 版本 v1.15.0 开始，kubelet 无需在集群中配置 Amazon 云提供商即可获取 ECR 凭证。 + +## Using the Out-of-Tree AWS Cloud Provider + + + + +1. [Node name conventions and other prerequisites](https://cloud-provider-aws.sigs.k8s.io/prerequisites/) must be followed for the cloud provider to find the instance correctly. + +2. Rancher managed RKE2/K3s clusters don't support configuring `providerID`. However, the engine will set the node name correctly if the following configuration is set on the provisioning cluster object: + +```yaml +spec: + rkeConfig: + machineGlobalConfig: + cloud-provider-name: aws +``` + +This option will be passed to the configuration of the various Kubernetes components that run on the node, and must be overridden per component to prevent the in-tree provider from running unintentionally: + + +**Override on Etcd:** + +```yaml +spec: + rkeConfig: + machineSelectorConfig: + - config: + kubelet-arg: + - cloud-provider=external + machineLabelSelector: + matchExpressions: + - key: rke.cattle.io/etcd-role + operator: In + values: + - 'true' +``` + +**Override on Control Plane:** + +```yaml +spec: + rkeConfig: + machineSelectorConfig: + - config: + disable-cloud-controller: true + kube-apiserver-arg: + - cloud-provider=external + kube-controller-manager-arg: + - cloud-provider=external + kubelet-arg: + - cloud-provider=external + machineLabelSelector: + matchExpressions: + - key: rke.cattle.io/control-plane-role + operator: In + values: + - 'true' +``` + +**Override on Worker:** + +```yaml +spec: + rkeConfig: + machineSelectorConfig: + - config: + kubelet-arg: + - cloud-provider=external + machineLabelSelector: + matchExpressions: + - key: rke.cattle.io/worker-role + operator: In + values: + - 'true' +``` + +2. Select `Amazon` if relying on the above mechanism to set the provider ID. Otherwise, select **External (out-of-tree)** cloud provider, which sets `--cloud-provider=external` for Kubernetes components. + +3. Specify the `aws-cloud-controller-manager` Helm chart as an additional manifest to install: + +```yaml +spec: + rkeConfig: + additionalManifest: |- + apiVersion: helm.cattle.io/v1 + kind: HelmChart + metadata: + name: aws-cloud-controller-manager + namespace: kube-system + spec: + chart: aws-cloud-controller-manager + repo: https://kubernetes.github.io/cloud-provider-aws + targetNamespace: kube-system + bootstrap: true + valuesContent: |- + hostNetworking: true + nodeSelector: + node-role.kubernetes.io/control-plane: "true" + args: + - --configure-cloud-routes=false + - --v=5 + - --cloud-provider=aws +``` + + + + + +1. [Node name conventions and other prerequisites ](https://cloud-provider-aws.sigs.k8s.io/prerequisites/) must be followed so that the cloud provider can find the instance. Rancher provisioned clusters don't support configuring `providerID`. + +:::note + +If you use IP-based naming, the nodes must be named after the instance followed by the regional domain name (`ip-xxx-xxx-xxx-xxx.ec2..internal`). If you have a custom domain name set in the DHCP options, you must set `--hostname-override` on `kube-proxy` and `kubelet` to match this naming convention. + +::: + +To meet node naming conventions, Rancher allows setting `useInstanceMetadataHostname` when the `External Amazon` cloud provider is selected. Enabling `useInstanceMetadataHostname` will query ec2 metadata service and set `/hostname` as `hostname-override` for `kubelet` and `kube-proxy`: + +```yaml +rancher_kubernetes_engine_config: + cloud_provider: + name: external-aws + 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**. + +2. Select the cloud provider. + +Selecting **External Amazon (out-of-tree)** sets `--cloud-provider=external` and enables `useInstanceMetadataHostname`. As mentioned in step 1, enabling `useInstanceMetadataHostname` will query the EC2 metadata service and set `http://169.254.169.254/latest/meta-data/hostname` as `hostname-override` for `kubelet` and `kube-proxy`. + +:::note + +You must disable `useInstanceMetadataHostname` when setting a custom node name for custom clusters via `node-name`. + +::: + +```yaml +rancher_kubernetes_engine_config: + cloud_provider: + name: external-aws + useInstanceMetadataHostname: true/false +``` + +Existing clusters that use an **External** cloud provider will set `--cloud-provider=external` for Kubernetes components but won't set the node name. + +3. Install the AWS cloud controller manager after the cluster finishes provisioning. Note that the cluster isn't successfully provisioned and nodes are still in an `uninitialized` state until you deploy the cloud controller manager. This can be done manually, or via [Helm charts in UI](#helm-chart-installation-from-ui). + +Refer to the offical AWS upstream documentation for the [cloud controller manager](https://kubernetes.github.io/cloud-provider-aws). + + + + +## Helm Chart Installation from CLI + + + + +Official upstream docs for [Helm chart installation](https://github.com/kubernetes/cloud-provider-aws/tree/master/charts/aws-cloud-controller-manager) can be found on GitHub. + +1. Add the Helm repository: + +```shell +helm repo add aws-cloud-controller-manager https://kubernetes.github.io/cloud-provider-aws +helm repo update +``` + +2. Create a `values.yaml` file with the following contents to override the default `values.yaml`: + +```yaml +# values.yaml +hostNetworking: true +tolerations: + - effect: NoSchedule + key: node.cloudprovider.kubernetes.io/uninitialized + value: 'true' + - effect: NoSchedule + value: 'true' + key: node-role.kubernetes.io/control-plane +nodeSelector: + node-role.kubernetes.io/control-plane: 'true' +args: + - --configure-cloud-routes=false + - --use-service-account-credentials=true + - --v=2 + - --cloud-provider=aws +clusterRoleRules: + - apiGroups: + - "" + resources: + - events + verbs: + - create + - patch + - update + - apiGroups: + - "" + resources: + - nodes + verbs: + - '*' + - apiGroups: + - "" + resources: + - nodes/status + verbs: + - patch + - apiGroups: + - "" + resources: + - services + verbs: + - list + - patch + - update + - watch + - apiGroups: + - "" + resources: + - services/status + verbs: + - list + - patch + - update + - watch + - apiGroups: + - '' + resources: + - serviceaccounts + verbs: + - create + - get + - apiGroups: + - "" + resources: + - persistentvolumes + verbs: + - get + - list + - update + - watch + - apiGroups: + - "" + resources: + - endpoints + verbs: + - create + - get + - list + - watch + - update + - apiGroups: + - coordination.k8s.io + resources: + - leases + verbs: + - create + - get + - list + - watch + - update + - apiGroups: + - "" + resources: + - serviceaccounts/token + verbs: + - create +``` + +3. Install the Helm chart: + +```shell +helm upgrade --install aws-cloud-controller-manager aws-cloud-controller-manager/aws-cloud-controller-manager --values values.yaml +``` + +Verify that the Helm chart installed successfully: + +```shell +helm status -n kube-system aws-cloud-controller-manager +``` + +4. (Optional) Verify that the cloud controller manager update succeeded: + +```shell +kubectl rollout status daemonset -n kube-system aws-cloud-controller-manager +``` + + + + + +Official upstream docs for [Helm chart installation](https://github.com/kubernetes/cloud-provider-aws/tree/master/charts/aws-cloud-controller-manager) can be found on GitHub. + +1. Add the Helm repository: + +```shell +helm repo add aws-cloud-controller-manager https://kubernetes.github.io/cloud-provider-aws +helm repo update +``` + +2. Create a `values.yaml` file with the following contents, to override the default `values.yaml`: + +```yaml +# values.yaml +hostNetworking: true +tolerations: + - effect: NoSchedule + key: node.cloudprovider.kubernetes.io/uninitialized + value: 'true' + - effect: NoSchedule + value: 'true' + key: node-role.kubernetes.io/controlplane +nodeSelector: + node-role.kubernetes.io/controlplane: 'true' +args: + - --configure-cloud-routes=false + - --use-service-account-credentials=true + - --v=2 + - --cloud-provider=aws +clusterRoleRules: + - apiGroups: + - "" + resources: + - events + verbs: + - create + - patch + - update + - apiGroups: + - "" + resources: + - nodes + verbs: + - '*' + - apiGroups: + - "" + resources: + - nodes/status + verbs: + - patch + - apiGroups: + - "" + resources: + - services + verbs: + - list + - patch + - update + - watch + - apiGroups: + - "" + resources: + - services/status + verbs: + - list + - patch + - update + - watch + - apiGroups: + - '' + resources: + - serviceaccounts + verbs: + - create + - get + - apiGroups: + - "" + resources: + - persistentvolumes + verbs: + - get + - list + - update + - watch + - apiGroups: + - "" + resources: + - endpoints + verbs: + - create + - get + - list + - watch + - update + - apiGroups: + - coordination.k8s.io + resources: + - leases + verbs: + - create + - get + - list + - watch + - update + - apiGroups: + - "" + resources: + - serviceaccounts/token + verbs: + - create +``` + +3. Install the Helm chart: + +```shell +helm upgrade --install aws-cloud-controller-manager -n kube-system aws-cloud-controller-manager/aws-cloud-controller-manager --values values.yaml +``` + +Verify that the Helm chart installed successfully: + +```shell +helm status -n kube-system aws-cloud-controller-manager +``` + +4. If present, edit the Daemonset to remove the default node selector `node-role.kubernetes.io/control-plane: ""`: + +```shell +kubectl edit daemonset aws-cloud-controller-manager -n kube-system +``` + +5. (Optional) Verify that the cloud controller manager update succeeded: + +```shell +kubectl rollout status daemonset -n kube-system aws-cloud-controller-manager +``` + + + + +## Helm Chart Installation from UI + + + + +1. Click **☰**, then select the name of the cluster from the left navigation. + +2. Select **Apps** > **Repositories**. + +3. Click the **Create** button. + +4. Enter `https://kubernetes.github.io/cloud-provider-aws` in the **Index URL** field. + +5. Select **Apps** > **Charts** from the left navigation and install **aws-cloud-controller-manager**. + +6. Select the namespace, `kube-system`, and enable **Customize Helm options before install**. + +7. Add the following container arguments: + +```yaml + - '--use-service-account-credentials=true' + - '--configure-cloud-routes=false' +``` + +8. Add `get` to `verbs` for `serviceaccounts` resources in `clusterRoleRules`. This allows the cloud controller manager to get service accounts upon startup. + +```yaml + - apiGroups: + - '' + resources: + - serviceaccounts + verbs: + - create + - get +``` + +9. Rancher-provisioned RKE2 nodes are tainted `node-role.kubernetes.io/control-plane`. Update tolerations and the nodeSelector: + +```yaml +tolerations: + - effect: NoSchedule + key: node.cloudprovider.kubernetes.io/uninitialized + value: 'true' + - effect: NoSchedule + value: 'true' + key: node-role.kubernetes.io/control-plane + +``` + +```yaml +nodeSelector: + node-role.kubernetes.io/control-plane: 'true' +``` + +:::note + +There's currently a [known issue](https://github.com/rancher/dashboard/issues/9249) where nodeSelector can't be updated from the Rancher UI. Continue installing the chart and then edit the Daemonset manually to set the `nodeSelector`: + +```yaml +nodeSelector: + node-role.kubernetes.io/control-plane: 'true' +``` + +::: + +10. Install the chart and confirm that the Daemonset `aws-cloud-controller-manager` is running. Verify `aws-cloud-controller-manager` pods are running in target namespace (`kube-system` unless modified in step 6). + + + + + +1. Click **☰**, then select the name of the cluster from the left navigation. + +2. Select **Apps** > **Repositories**. + +3. Click the **Create** button. + +4. Enter `https://kubernetes.github.io/cloud-provider-aws` in the **Index URL** field. + +5. Select **Apps** > **Charts** from the left navigation and install **aws-cloud-controller-manager**. + +6. Select the namespace, `kube-system`, and enable **Customize Helm options before install**. + +7. Add the following container arguments: + +```yaml + - '--use-service-account-credentials=true' + - '--configure-cloud-routes=false' +``` + +8. Add `get` to `verbs` for `serviceaccounts` resources in `clusterRoleRules`. This allows the cloud controller manager to get service accounts upon startup: + +```yaml + - apiGroups: + - '' + resources: + - serviceaccounts + verbs: + - create + - get +``` + +9. Rancher-provisioned RKE nodes are tainted `node-role.kubernetes.io/controlplane`. Update tolerations and the nodeSelector: + +```yaml +tolerations: + - effect: NoSchedule + key: node.cloudprovider.kubernetes.io/uninitialized + value: 'true' + - effect: NoSchedule + value: 'true' + key: node-role.kubernetes.io/controlplane + +``` + +```yaml +nodeSelector: + node-role.kubernetes.io/controlplane: 'true' +``` + +:::note + +There's currently a [known issue](https://github.com/rancher/dashboard/issues/9249) where `nodeSelector` can't be updated from the Rancher UI. Continue installing the chart and then Daemonset manually to set the `nodeSelector`: + +``` yaml +nodeSelector: + node-role.kubernetes.io/controlplane: 'true' +``` + +::: + +10. Install the chart and confirm that the Daemonset `aws-cloud-controller-manager` deploys successfully: + +```shell +kubectl rollout status deployment -n kube-system aws-cloud-controller-manager +``` + + + \ No newline at end of file diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-cloud-providers/azure.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-cloud-providers/azure.md new file mode 100644 index 00000000000..85d2c0b05ef --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-cloud-providers/azure.md @@ -0,0 +1,545 @@ +--- +title: 设置 Azure 云提供商 +--- + +使用 `Azure` 云提供商时，你可以使用以下功能： + +- **负载均衡器**：在特定网络安全组中启动 Azure 负载均衡器。 + +- **持久卷**：支持将 Azure Blob 磁盘和 Azure 托管磁盘与标准和高级 Storage Account 一起使用。 + +- **网络存储**：通过 CIFS 挂载支持 Azure 文件。 + +Azure 订阅不支持以下账号类型： + +- 单租户账号（即没有订阅的账号）。 +- 多订阅账号。 + +## RKE 和 RKE2 的先决条件 + +要为 RKE 和 RKE2 设置 Azure 云提供商，你需要配置以下凭证： + +1. [设置 Azure 租户 ID](#1-设置-azure-租户-id) +2. [设置 Azure 客户端 ID 和 Azure 客户端密码](#2-设置-azure-客户端-id-和-azure-客户端密码) +3. [配置应用注册权限](#3-配置应用注册权限) +4. [设置 Azure 网络安全组名称](#4-设置-azure-网络安全组名称) + +### 1. 设置 Azure 租户 ID + +访问 [Azure 门户](https://portal.azure.com)，登录并转到 **Azure Active Directory**，然后选择 **Properties**。你的 **Directory ID** 是你的 **Tenant ID** (tenantID)。 + +如果要使用 Azure CLI，你可以运行 `az account show` 命令来获取信息。 + +### 2. 设置 Azure 客户端 ID 和 Azure 客户端密码 + +访问 [Azure 门户](https://portal.azure.com)，登录并按照以下步骤创建 **App Registration** 和对应的 **Azure Client ID** (aadClientId) 以及 **Azure Client Secret** (aadClientSecret)。 + +1. 选择 **Azure Active Directory**。 +1. 选择 **App registrations**。 +1. 选择 **New application registration**。 +1. 选择 **Name**，选择 `Web app/API` 作为 **Application Type**，并选择任意 **Sign-on URL**。 +1. 选择 **Create**。 + +在 **App registrations** 视图中，你应该会看到你创建的应用注册。**APPLICATION ID** 列中显示的值是需要用作 **Azure Client ID** 的值。 + +下一步是生成 **Azure Client Secret**： + +1. 打开你创建的应用注册。 +1. 在 **Settings** 视图中，打开 **Keys**。 +1. 输入 **Key description**，选择过期时间，然后选择 **Save**。 +1. **Value** 列中显示的生成值是需要用作 **Azure Client Secret** 的值。该值只会显示一次。 + +### 3. 配置应用注册权限 + +最后，为你的应用注册分配适当的权限： + +1. 前往 **More services**，搜索 **Subscriptions** 并打开它。 +1. 打开 **Access control (IAM)**。 +1. 选择 **Add**。 +1. 在 **Role** 中选择 `Contributor`。 +1. 在 **Select** 中选择你创建的应用注册的名称。 +1. 选择 **Save**。 + +### 4. 设置 Azure 网络安全组名称 + +要使 Azure 负载均衡器正常工作，你需要自定义一个 Azure 网络安全组 (securityGroupName)。 + +如果你使用 Rancher Machine Azure 驱动来配置主机，则需要手动编辑主机，从而将主机分配给此网络安全组。 + +你需要在配置期间将自定义主机分配给此网络安全组。 + +只有需要成为负载均衡器后端的主机才需要分配到该组。 + +## Rancher 中的 RKE2 集群设置 + +1. 在**集群配置**中的**云提供商**下拉列表中选择 **Azure**。 + +1. + * 配置云提供商。请注意，Rancher 会自动创建新的网络安全组、资源组、可用性集、子网和虚拟网络。如果你已经创建了其中的一部分或全部，则需要在创建集群之前指定它们。 + * 你可以单击**显示高级选项**以查看更多自动生成的名称，并在需要的时候更新它们。你的云提供商配置**必须**与**主机池**中的字段匹配。如果你有多个池，它们必须使用相同的资源组、可用性集、子网、虚拟网络和网络安全组。 + * 下面提供了一个示例。你可以根据需要对其进行修改。 + +
+ 云提供商配置示例 + + ```yaml + { + "cloud":"AzurePublicCloud", + "tenantId": "YOUR TENANTID HERE", + "aadClientId": "YOUR AADCLIENTID HERE", + "aadClientSecret": "YOUR AADCLIENTSECRET HERE", + "subscriptionId": "YOUR SUBSCRIPTIONID HERE", + "resourceGroup": "docker-machine", + "location": "westus", + "subnetName": "docker-machine", + "securityGroupName": "rancher-managed-KA4jV9V2", + "securityGroupResourceGroup": "docker-machine", + "vnetName": "docker-machine-vnet", + "vnetResourceGroup": "docker-machine", + "primaryAvailabilitySetName": "docker-machine", + "routeTableResourceGroup": "docker-machine", + "cloudProviderBackoff": false, + "useManagedIdentityExtension": false, + "useInstanceMetadata": true + } + ``` + +
+ +1. 在**集群配置 > 高级选项**、中，单击**补充的 Controller Manager 参数**下的**添加**，并添加 `--configure-cloud-routes=false` 标志。 + +1. 单击**创建**按钮来提交表单并创建集群。 + +## Cloud Provider Configuration + +Rancher automatically creates a new Network Security Group, Resource Group, Availability Set, Subnet, and Virtual Network. If you already have some or all of these created, you will need to specify them before creating the cluster. You can check **RKE1 Node Templates** or **RKE2 Machine Pools** to view or edit these automatically generated names. + +**Refer to the full list of configuration options in the [upstream docs](https://cloud-provider-azure.sigs.k8s.io/install/configs/).** + +:::note +1. `useInstanceMetadata` must be set to `true` for the cloud provider to correctly configure `providerID`. +2. `excludeMasterFromStandardLB` must be set to `false` if you need to add nodes labeled `node-role.kubernetes.io/master` to the backend of the Azure Load Balancer (ALB). +3. `loadBalancerSku` can be set to `basic` or `standard`. Basic SKU will be deprecated in September 2025. Refer to the [Azure upstream docs](https://learn.microsoft.com/en-us/azure/virtual-network/ip-services/public-ip-basic-upgrade-guidance#basic-sku-vs-standard-sku) for more information. +::: + +Azure supports reading the cloud config from Kubernetes secrets. The secret is a serialized version of the azure.json file. When the secret is changed, the cloud controller manager reconstructs itself without restarting the pod. It is recommended for the Helm chart to read the Cloud Provider Config from the secret. + +Note that the chart reads the Cloud Provider Config from a given secret name in the `kube-system` namespace. Since Azure reads Kubernetes secrets, RBAC also needs to be configured. An example secret for the Cloud Provider Config is shown below. Modify it as needed and create the secret. + + ```yaml +# azure-cloud-config.yaml +apiVersion: v1 +kind: Secret +metadata: + name: azure-cloud-config + namespace: kube-system +type: Opaque +stringData: + cloud-config: |- + { + "cloud": "AzurePublicCloud", + "tenantId": "", + "subscriptionId": "", + "aadClientId": "", + "aadClientSecret": "", + "resourceGroup": "docker-machine", + "location": "westus", + "subnetName": "docker-machine", + "securityGroupName": "rancher-managed-kqmtsjgJ", + "securityGroupResourceGroup": "docker-machine", + "vnetName": "docker-machine-vnet", + "vnetResourceGroup": "docker-machine", + "primaryAvailabilitySetName": "docker-machine", + "routeTableResourceGroup": "docker-machine", + "cloudProviderBackoff": false, + "useManagedIdentityExtension": false, + "useInstanceMetadata": true, + "loadBalancerSku": "standard", + "excludeMasterFromStandardLB": false, + } + ``` + +## Using the Out-of-tree Azure Cloud Provider + + + + +1. Select **External** from the **Cloud Provider** drop-down in the **Cluster Configuration** section. + +2. Under **Cluster Configuration > Advanced**, click **Add** under **Additional Controller Manager Args** and add this flag: `--configure-cloud-routes=false`. + +3. Prepare the Cloud Provider Configuration to set it in the next step. Note that Rancher automatically creates a new Network Security Group, Resource Group, Availability Set, Subnet, and Virtual Network. If you already have some or all of these created, you must specify them before creating the cluster. + + Click **Show Advanced** to view or edit these automatically generated names. Your Cloud Provider Configuration **must** match the fields in the **Machine Pools** section. If you have multiple pools, they must all use the same Resource Group, Availability Set, Subnet, Virtual Network, and Network Security Group. + +4. Under **Cluster Configuration > Add-on Config**, add the cloud controller manager manifest shown below into **Additional Manifest**. +Note that this chart reads the Cloud Provider Config from the secret in the `kube-system` namespace. An example secret for the Cloud Provider Config is shown below; modify it as needed. Refer to the full list of configuration options in the [upstream docs](https://cloud-provider-azure.sigs.k8s.io/install/configs/). + + Alternatively, you can also install the cloud controller manager using the [Helm CLI](#helm-chart-installation-from-cli). + + ```yaml + apiVersion: helm.cattle.io/v1 + kind: HelmChart + metadata: + name: azure-cloud-controller-manager + namespace: kube-system + spec: + chart: cloud-provider-azure + repo: https://raw.githubusercontent.com/kubernetes-sigs/cloud-provider-azure/master/helm/repo + targetNamespace: kube-system + bootstrap: true + valuesContent: |- + infra: + clusterName: + cloudControllerManager: + cloudConfigSecretName: azure-cloud-config + cloudConfig: null + clusterCIDR: null + enableDynamicReloading: 'true' + nodeSelector: + node-role.kubernetes.io/control-plane: 'true' + allocateNodeCidrs: 'false' + hostNetworking: true + caCertDir: /etc/ssl + configureCloudRoutes: 'false' + enabled: true + tolerations: + - effect: NoSchedule + key: node-role.kubernetes.io/master + - effect: NoSchedule + key: node-role.kubernetes.io/control-plane + value: 'true' + - effect: NoSchedule + key: node.cloudprovider.kubernetes.io/uninitialized + value: 'true' + --- + apiVersion: v1 + kind: Secret + metadata: + name: azure-cloud-config + namespace: kube-system + type: Opaque + stringData: + cloud-config: |- + { + "cloud": "AzurePublicCloud", + "tenantId": "", + "subscriptionId": "", + "aadClientId": "", + "aadClientSecret": "", + "resourceGroup": "docker-machine", + "location": "westus", + "subnetName": "docker-machine", + "securityGroupName": "rancher-managed-kqmtsjgJ", + "securityGroupResourceGroup": "docker-machine", + "vnetName": "docker-machine-vnet", + "vnetResourceGroup": "docker-machine", + "primaryAvailabilitySetName": "docker-machine", + "routeTableResourceGroup": "docker-machine", + "cloudProviderBackoff": false, + "useManagedIdentityExtension": false, + "useInstanceMetadata": true, + "loadBalancerSku": "standard", + "excludeMasterFromStandardLB": false, + } + ``` + +5. Click **Create** to submit the form and create the cluster. + + + + + +1. Choose **External** from the **Cloud Provider** drop-down in the **Cluster Options** section. This sets `--cloud-provider=external` for Kubernetes components. + +2. Install the `cloud-provider-azure` chart after the cluster finishes provisioning. Note that the cluster is not successfully provisioned and nodes are still in an `uninitialized` state until you deploy the cloud controller manager. This can be done [manually using CLI](#helm-chart-installation-from-cli), or via [Helm charts in UI](#helm-chart-installation-from-ui). + +Refer to the [official Azure upstream documentation](https://cloud-provider-azure.sigs.k8s.io/install/azure-ccm/) for more details on deploying the Cloud Controller Manager. + + + + +### Helm Chart Installation from CLI + +Official upstream docs for [Helm chart installation](https://github.com/kubernetes-sigs/cloud-provider-azure/tree/master/helm/cloud-provider-azure) can be found on Github. + +1. Create a `azure-cloud-config` secret with the required [cloud provider config](#cloud-provider-configuration). + +```shell +kubectl apply -f azure-cloud-config.yaml +``` + +2. Add the Helm repository: + +```shell +helm repo add azure-cloud-controller-manager https://raw.githubusercontent.com/kubernetes-sigs/cloud-provider-azure/master/helm/repo +helm repo update +``` + +3. Create a `values.yaml` file with the following contents to override the default `values.yaml`: + + + + +```yaml +# values.yaml +infra: + clusterName: +cloudControllerManager: + cloudConfigSecretName: azure-cloud-config + cloudConfig: null + clusterCIDR: null + enableDynamicReloading: 'true' + configureCloudRoutes: 'false' + allocateNodeCidrs: 'false' + caCertDir: /etc/ssl + enabled: true + replicas: 1 + hostNetworking: true + nodeSelector: + node-role.kubernetes.io/control-plane: 'true' + tolerations: + - effect: NoSchedule + key: node-role.kubernetes.io/master + - effect: NoSchedule + key: node-role.kubernetes.io/control-plane + value: 'true' + - effect: NoSchedule + key: node.cloudprovider.kubernetes.io/uninitialized + value: 'true' +``` + + + + + +```yaml +# values.yaml +cloudControllerManager: + cloudConfigSecretName: azure-cloud-config + cloudConfig: null + clusterCIDR: null + enableDynamicReloading: 'true' + configureCloudRoutes: 'false' + allocateNodeCidrs: 'false' + caCertDir: /etc/ssl + enabled: true + replicas: 1 + hostNetworking: true + nodeSelector: + node-role.kubernetes.io/controlplane: 'true' + node-role.kubernetes.io/control-plane: null + tolerations: + - effect: NoSchedule + key: node-role.kubernetes.io/controlplane + value: 'true' + - effect: NoSchedule + key: node.cloudprovider.kubernetes.io/uninitialized + value: 'true' +infra: + clusterName: +``` + + + + +4. Install the Helm chart: + +```shell +helm upgrade --install cloud-provider-azure azure-cloud-controller-manager/cloud-provider-azure -n kube-system --values values.yaml +``` + +Verify that the Helm chart installed successfully: + +```shell +helm status cloud-provider-azure -n kube-system +``` + +5. (Optional) Verify that the cloud controller manager update succeeded: + +```shell +kubectl rollout status deployment -n kube-system cloud-controller-manager +kubectl rollout status daemonset -n kube-system cloud-node-manager +``` + +6. The cloud provider is responsible for setting the ProviderID of the node. Check if all nodes are initialized with the ProviderID: + +```shell +kubectl describe nodes | grep "ProviderID" +``` + +### Helm Chart Installation from UI + +1. Click **☰**, then select the name of the cluster from the left navigation. + +2. Select **Apps** > **Repositories**. + +3. Click the **Create** button. + +4. Enter `https://raw.githubusercontent.com/kubernetes-sigs/cloud-provider-azure/master/helm/repo` in the **Index URL** field. + +5. Select **Apps** > **Charts** from the left navigation and install **cloud-provider-azure** chart. + +6. Select the namespace, `kube-system`, and enable **Customize Helm options before install**. + +7. Replace `cloudConfig: /etc/kubernetes/azure.json` to read from the Cloud Config Secret and enable dynamic reloading: + +```yaml + cloudConfigSecretName: azure-cloud-config + enableDynamicReloading: 'true' +``` + +8. Update the following fields as required: + +```yaml + allocateNodeCidrs: 'false' + configureCloudRoutes: 'false' + clusterCIDR: null +``` + + + + +9. Rancher-provisioned RKE2 nodes have the selector `node-role.kubernetes.io/control-plane` set to `true`. Update the nodeSelector: +```yaml +nodeSelector: + node-role.kubernetes.io/control-plane: 'true' +``` + + + + +10. Rancher-provisioned RKE nodes are tainted `node-role.kubernetes.io/controlplane`. Update tolerations and the nodeSelector: + +```yaml +tolerations: + - effect: NoSchedule + key: node.cloudprovider.kubernetes.io/uninitialized + value: 'true' + - effect: NoSchedule + value: 'true' + key: node-role.kubernetes.io/controlplane +``` + +```yaml +nodeSelector: + node-role.kubernetes.io/controlplane: 'true' +``` + + + +11. Install the chart and confirm that the cloud controller and cloud node manager deployed successfully: + +```shell +kubectl rollout status deployment -n kube-system cloud-controller-manager +kubectl rollout status daemonset -n kube-system cloud-node-manager +``` + +12. The cloud provider is responsible for setting the ProviderID of the node. Check if all nodes are initialized with the ProviderID: + +```shell +kubectl describe nodes | grep "ProviderID" +``` + +### Installing CSI Drivers + +Install [Azure Disk CSI driver](https://github.com/kubernetes-sigs/azuredisk-csi-driver) or [Azure File CSI Driver](https://github.com/kubernetes-sigs/azurefile-csi-driver) to access [Azure Disk](https://azure.microsoft.com/en-us/services/storage/disks/) or [Azure File](https://azure.microsoft.com/en-us/services/storage/disks/) volumes respectively. + +The steps to install the Azure Disk CSI driver are shown below. You can install the Azure File CSI Driver in a similar manner by following the [helm installation documentation](https://github.com/kubernetes-sigs/azurefile-csi-driver/blob/master/charts/README.md). + +::: note Important: + +Clusters must be provisioned using `Managed Disk` to use Azure Disk. You can configure this when creating **RKE1 Node Templates** or **RKE2 Machine Pools*. + +::: + +Official upstream docs for [Helm chart installation](https://github.com/kubernetes-sigs/azuredisk-csi-driver/blob/master/charts/README.md) can be found on Github. + +1. Add and update the helm repository: + +```shell +helm repo add azuredisk-csi-driver https://raw.githubusercontent.com/kubernetes-sigs/azuredisk-csi-driver/master/charts +helm repo update azuredisk-csi-driver +``` + +1. Install the chart as shown below, updating the --version argument as needed. Refer to the full list of latest chart configurations in the [upstream docs](https://github.com/kubernetes-sigs/azuredisk-csi-driver/blob/master/charts/README.md#latest-chart-configuration). + +```shell +helm install azuredisk-csi-driver azuredisk-csi-driver/azuredisk-csi-driver --namespace kube-system --version v1.30.1 --set controller.cloudConfigSecretName=azure-cloud-config --set controller.cloudConfigSecretNamespace=kube-system --set controller.runOnControlPlane=true +``` + +2. (Optional) Verify that the azuredisk-csi-driver installation succeeded: + +```shell +kubectl --namespace=kube-system get pods --selector="app.kubernetes.io/name=azuredisk-csi-driver" --watch +``` + +3. Provision an example Storage Class: + +```shell +cat < 集群管理**。 +1. 在**集群**页面上，单击**创建**。 +1. 单击 **VMware vSphere** 或 **自定义**。 +1. 在**集群配置**的**基本信息**选项卡中，将**云提供商**设置为 **vSphere**。 +1. 在**附加配置**选项卡中，设置 vSphere Cloud Provider (CPI) 和 Storage Provider (CSI) 选项。 +1. 完成集群创建。 + +### 2. 安装 CPI 插件 + +1. 点击 **☰ > 集群管理**。 +1. 转到将安装 vSphere CPI 插件的集群，然后单击 **Explore**。 +1. 单击 **Apps > Charts**。 +1. 单击 **vSphere CPI**。 +1. 填写所需的 vCenter 详细信息。 +1. vSphere CPI 使用 vSphere CSI 驱动所需的 ProviderID 来初始化所有节点。在使用以下命令安装 CSI 驱动之前，检查是否所有节点都使用 ProviderID 进行了初始化： + + ``` + kubectl describe nodes | grep "ProviderID" + ``` + +### 3. 安装 CSI 插件 + +1. 点击 **☰ > 集群管理**。 +1. 转到将安装 vSphere CSI 插件的集群，然后单击 **Explore**。 +1. 单击 **Apps > Charts**。 +1. 单击 **vSphere CSI**。 +1. 单击**安装**。 +1. 填写所需的 vCenter 详细信息。在**功能**选项卡中，将**启用 CSI 迁移**设置为 **false**。 +3. 在**存储**选项卡中，填写 StorageClass 的详细信息。此 Chart 使用 `csi.vsphere.vmware.com` 作为置备程序来创建一个 StorageClass。 +1. 单击**安装**。 + + +## 使用 CSI 驱动来置备卷 + +CSI chart 默认创建一个 storageClass。 + +如果在启动 chart 时未选择该选项，请使用 `csi.vsphere.vmware.com` 作为置备程序来创建一个 storageClass。 + +使用此 StorageClass 置备的所有卷都将由 CSI 驱动配置。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-cloud-providers/google-compute-engine.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-cloud-providers/google-compute-engine.md new file mode 100644 index 00000000000..377a2929010 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-cloud-providers/google-compute-engine.md @@ -0,0 +1,57 @@ +--- +title: 设置 Google Compute Engine 云提供商 +--- + +在本节中，你将了解如何在 Rancher 中为自定义集群启用 Google Compute Engine (GCE) 云提供商。自定义集群指的是 Rancher 在现有节点上安装 Kubernetes 的集群。 + +详情请参见 [GCE 云提供商的官方 Kubernetes 文档](https://github.com/kubernetes/website/blob/release-1.18/content/en/docs/concepts/cluster-administration/cloud-providers.md#gce)。 + +:::note 先决条件： + +GCE 上的 `Identity` ServiceAccount 和 API 访问需要`Computer Admin`权限。 + +::: + +如果你使用 Calico： + +1. 点击 **☰ > 集群管理**。 +1. 在**集群**页面中，进入自定义集群，点击 **⋮ > 编辑 YAML** 并输入如下配置： + + ```yaml + rancher_kubernetes_engine_config: + cloud_provider: + name: gce + customCloudProvider: |- + [Global] + project-id= + network-name= + subnetwork-name= + node-instance-prefix= + node-tags= + network: + options: + calico_cloud_provider: "gce" + plugin: "calico" + ``` + +如果你使用 Canal 或 Flannel： + +1. 点击 **☰ > 集群管理**。 +1. 在**集群**页面中，进入自定义集群，点击 **⋮ > 编辑 YAML** 并输入如下配置： + + ```yaml + rancher_kubernetes_engine_config: + cloud_provider: + name: gce + customCloudProvider: |- + [Global] + project-id= + network-name= + subnetwork-name= + node-instance-prefix= + node-tags= + services: + kube_controller: + extra_args: + configure-cloud-routes: true # we need to allow the cloud provider configure the routes for the hosts + ``` diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-cloud-providers/migrate-from-in-tree-to-out-of-tree.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-cloud-providers/migrate-from-in-tree-to-out-of-tree.md new file mode 100644 index 00000000000..cda5dbafed4 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-cloud-providers/migrate-from-in-tree-to-out-of-tree.md @@ -0,0 +1,108 @@ +--- +title: 将 vSphere 树内卷迁移到树外 +--- + +Kubernetes 正在逐渐不在树内维护云提供商。vSphere 有一个树外云提供商，可通过安装 vSphere 云提供商和云存储插件来使用。 + +本页介绍如何从树内 vSphere 云提供商迁移到树外，以及如何在迁移后管理现有虚拟机。 + +本文遵循官方 [vSphere 迁移文档](https://vsphere-csi-driver.sigs.k8s.io/features/vsphere_csi_migration.html)中提供的步骤，并介绍了要在 Rancher 中执行的步骤。 + +## Cloud-config 格式限制 + +由于 vSphere CSI 中的现有错误，使用以下 cloud-config 格式配置的现有卷将不会迁移。 + +如果 cloud-config 具有以下格式的 datastore 和资源池路径，vsphere CSI 驱动将无法识别它： + +```yaml +default-datastore: /datastore/ +resourcepool-path: "/host//Resources/" +``` + +格式如下的使用树内提供商预置的卷将能正确迁移： + +```yaml +default-datastore: +resourcepool-path: "/Resources/" +``` + +上游 bug：https://github.com/kubernetes-sigs/vsphere-csi-driver/issues/628 + +跟踪此 bug 的 Rancher issue：https://github.com/rancher/rancher/issues/31105 + +## 先决条件 + +- vSphere CSI 迁移需要 vSphere 7.0u1。为了管理现有的树内 vSphere 卷，请将 vSphere 升级到 7.0u1。 +- Kubernetes 版本必须为 1.19 或更高版本。 + +## 迁移 + +### 1. 安装 CPI 插件 + +在安装 CPI 之前，我们需要使用 `node.cloudprovider.kubernetes.io/uninitialized=true:NoSchedule` 为所有节点添加污点。 + +这可以通过运行以下命令来完成： + +``` +curl -O https://raw.githubusercontent.com/rancher/helm3-charts/56b622f519728378abeddfe95074f1b87ab73b1e/charts/vsphere-cpi/taints.sh +``` + +或者： + +``` +wget https://raw.githubusercontent.com/rancher/helm3-charts/56b622f519728378abeddfe95074f1b87ab73b1e/charts/vsphere-cpi/taints.sh +chmod +x taints.sh +./taints.sh +``` + +通过运行脚本为所有节点添加污点后，启动 Helm vSphere CPI Chart： + +1. 点击 **☰ > 集群管理**。 +1. 转到将安装 vSphere CPI chart 的集群，然后单击 **Explore**。 +1. 单击 **Apps > Charts**。 +1. 单击 **vSphere CPI**。 +1. 单击**安装**。 +1. 填写所需的 vCenter 详细信息，然后单击**安装**。 + +vSphere CPI 使用 vSphere CSI 驱动所需的 ProviderID 来初始化所有节点。 + +运行以下命令，检查是否已使用 ProviderID 初始化了所有节点： + +``` +kubectl describe nodes | grep "ProviderID" +``` + +### 2. 安装 CSI 驱动 + +1. 点击 **☰ > 集群管理**。 +1. 转到将安装 vSphere CSI chart 的集群，然后单击 **Explore**。 +1. 单击 **Apps > Charts**。 +1. 单击 **vSphere CSI**。 +1. 单击**安装**。 +1. 填写所需的 vCenter 详细信息，然后单击**安装**。 +1. 选中**在安装前自定义 Helm 选项**，然后单击**下一步**。 +1. 在**功能**选项卡中，选中**启用 CSI 迁移**。 +1. 你也可以转到**存储**选项卡并设置 datastore。此 Chart 使用 `csi.vsphere.vmware.com` 作为置备程序来创建一个 StorageClass。在创建此 StorageClass 时，你也可以提供用于配置 CSI 卷的 datastore URL。通过选择 datastore 并转到**概述**选项卡，你可以在 vSphere 客户端中找到 datastore URL。填写 StorageClass 的详细信息。 +1. 单击**安装**。 + +### 3. 编辑集群以启用 CSI 迁移的功能开关 + +1. 在编辑集群时，如果 Kubernetes 版本低于 1.19，请从 **Kubernetes 版本**下拉菜单中选择 Kubernetes 1.19 或更高版本。 +2. 要启用功能开关，请单击**以 YAML 文件编辑**，然后在 kube-controller 和 kubelet 下添加以下内容： + + ```yaml + extra_args: + feature-gates: "CSIMigration=true,CSIMigrationvSphere=true" + ``` + +### 4. 清空 worker 节点 + +在更改 kubelet 和 kube-controller-manager 参数之前，必须在升级期间清空 worker 节点： + + +1. 点击 **☰ > 集群管理**。 +1. 转到要清空 worker 节点的集群，然后单击 **⋮ > 编辑配置**。 +1. 在**高级选项**中，将**最大不可用的 Worker 节点数**字段设置为 1。 +1. 要在升级期间清空节点，请选择**清空节点 > 是**。 +1. 将**强制**和**删除本地数据**设置为 **true**。 +1. 点击**保存**以升级集群。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-cloud-providers/set-up-cloud-providers.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-cloud-providers/set-up-cloud-providers.md new file mode 100644 index 00000000000..2dff10dc67c --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-cloud-providers/set-up-cloud-providers.md @@ -0,0 +1,47 @@ +--- +title: 设置 Cloud Provider +--- + + + + + +_cloud provider_ 是 Kubernetes 中的一个模块，它提供了一个用于管理节点、负载均衡器和网络路由的接口。 + +在 Rancher 中设置 cloud provider 时，如果你使用的云提供商支持自动化，Rancher Server 可以在启动 Kubernetes 定义时自动配置新节点、负载均衡器或持久存储设备。 + +如果你配置的节点云提供商集群不满足先决条件，集群将无法正确配置。 + +**Cloud Provider** 选项默认设置为 `None`。 + +可以启用的云提供商包括： + +* Amazon +* Azure +* GCE (Google Compute Engine) +* vSphere + +## 设置 Amazon 云提供商 + +有关启用 Amazon 云提供商的详细信息，请参阅[此页面](amazon.md)。 + +## 设置 Azure 云提供商 + +有关启用 Azure 云提供商的详细信息，请参阅[此页面](azure.md)。 + +## 设置 GCE 云提供商 + +有关启用 Google Compute Engine 云提供商的详细信息，请参阅[此页面](google-compute-engine.md)。 + +## 设置 vSphere 云提供商 + +有关启用 vSphere 云提供商的详细信息，请参阅[树内 vSphere 配置](configure-in-tree-vsphere.md) 和 [树外 vSphere 配置](configure-out-of-tree-vsphere.md)。 + +## 设置自定义云提供商 + +如果您想配置其他 Kubernetes 云提供商，则可使用 `自定义` 云提供商。 + +关于自定义云提供商选项，您可以参考 [RKE 文档](https://rancher.com/docs/rke/latest/en/config-options/cloud-providers/)，了解如何为你的云提供商编辑 yaml 文件。特定云提供商的详细配置说明如下： + +- [vSphere](https://rke.docs.rancher.com/config-options/cloud-providers/vsphere) +- [OpenStack](https://rancher.com/docs/rke/latest/en/config-options/cloud-providers/openstack/) diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-clusters-from-hosted-kubernetes-providers/aks.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-clusters-from-hosted-kubernetes-providers/aks.md new file mode 100644 index 00000000000..d3a15f44ea7 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-clusters-from-hosted-kubernetes-providers/aks.md @@ -0,0 +1,153 @@ +--- +title: 创建 AKS 集群 +--- + +你可以使用 Rancher 创建托管在 Microsoft Azure Kubernetes 服务 (AKS) 中的集群。 + + +## Microsoft Azure 中的先决条件 + +:::caution + +部署到 AKS 会产生费用。 + +::: + +若要与 Azure API 交互，AKS 集群需要 Azure Active Directory (AD) 服务主体。服务主体是动态创建和管理其他 Azure 资源所必需的，它为集群提供凭证来与 AKS 通信。有关服务主体的详细信息，请参阅 [AKS 文档](https://docs.microsoft.com/en-us/azure/aks/kubernetes-service-principal)。 + +在创建服务主体之前，你需要从 [Microsoft Azure 门户](https://portal.azure.com)获取以下信息： + +- 订阅 ID +- 客户端 ID +- 客户端密码 + +以下介绍如何使用 Azure 命令行工具或 Azure 门户进行设置，从而满足先决条件。 + +### 使用 Azure 命令行工具设置服务主体 + +运行以下命令来创建服务主体： + +``` +az ad sp create-for-rbac --skip-assignment +``` + +结果应显示新服务主体的信息： +``` +{ + "appId": "xxxx--xxx", + "displayName": "", + "name": "http://", + "password": "", + "tenant": "" +} +``` + +你还需要向服务主体添加角色，以便它具有与 AKS API 通信的权限。它还需要访问权限才能创建和列出虚拟网络。 + +下面是将参与者角色分配给服务主体的示例命令。参与者可以管理 AKS 上的任何内容，但不能授予其他人访问权限： + +``` +az role assignment create \ + --assignee $appId \ + --scope /subscriptions/$/resourceGroups/$ \ + --role Contributor +``` + +你还可以通过合并两个命令，来创建服务主体并授予参与者权限。在此命令中，`scope` 需要提供 Azure 资源的完整路径： + +``` +az ad sp create-for-rbac \ + --scope /subscriptions/$/resourceGroups/$ \ + --role Contributor +``` + +### 从 Azure 门户设置服务主体 + +你还可以按照这些说明设置服务主体，并从 Azure 门户为它授予基于角色的访问权限。 + +1. 转到 Microsoft Azure 门户[主页](https://portal.azure.com)。 + +1. 单击 **Azure Active Directory**。 +1. 单击 **App registrations**。 +1. 单击 **New registration**。 +1. 输入名称。这将是你服务主体的名称。 +1. 可选：选择可以使用服务主体的账号。 +1. 单击 **Register**。 +1. 你现在应该能在 **Azure Active Directory > App registrations** 下看到服务主体的名称。 +1. 单击你的服务主体的名称。记下应用 ID（也称为应用 ID 或客户端 ID），以便在预配 AKS 集群时使用。然后单击 **Certificates & secrets**。 +1. 单击 **New client secret**。 +1. 输入简短说明，选择过期时间，然后单击 **Add**。记下客户端密码，以便在预配 AKS 集群时使用它。 + +**结果**：你已经创建了一个服务主体，现在你能够在 **App registrations** 下的 **Azure Active Directory** 中找到它。你仍然需要向服务主体授予对 AKS 的访问权限。 + +要授予对服务主体基于角色的访问权限： + +1. 点击左侧导航栏中的 **All Services**。然后单击 **Subscriptions**。 +1. 单击要与 Kubernetes 集群关联的订阅的名称。记下订阅 ID，以便在预配 AKS 集群时使用它。 +1. 单击 **Access Control (IAM)**。 +1. 在 **Add role assignment** 中，单击 **Add**。 +1. 在 **Role** 字段中，选择将有权访问 AKS 的角色。例如，你可以使用 **Contributor** 角色，该角色有权管理除授予其他用户访问权限之外的所有内容。 +1. 在 **Assign access to** 字段中，选择 **Azure AD 用户、组或服务主体**。 +1. 在 **Select** 字段中，选择服务主体的名称，然后单击 **Save**。 + +**结果**：你的服务主体现在可以访问 AKS。 + +## 1. 创建 AKS 云凭证 + +1. 在 Rancher UI 中，单击 **☰ > 集群管理**。 +1. 单击**云凭证**。 +1. 单击**创建**。 +1. 单击 **Azure**。 +1. 填写表单。有关填写表格的帮助，请参阅[配置参考](../../../../reference-guides/cluster-configuration/rancher-server-configuration/aks-cluster-configuration.md#云凭证)。 +1. 单击**创建**。 + +## 2. 创建 AKS 集群 + +使用 Rancher 配置你的 Kubernetes 集群。 + +1. 点击 **☰ > 集群管理**。 +1. 在**集群**中，单击**创建**。 +1. 单击 **Azure AKS**。 +1. 填写表单。有关填写表格的帮助，请参阅[配置参考](../../../../reference-guides/cluster-configuration/rancher-server-configuration/aks-cluster-configuration.md)。 +1. 单击**创建**。 + +**结果**：集群已创建，并处于 **Provisioning** 状态。Rancher 已在你的集群中。 + +当集群状态变为 **Active** 后，你可访问集群。 + +## RBAC +在 Rancher UI 中配置 AKS 集群时，由于 RBAC 需要启用，因此 RBAC 不可配置。 + +注册或导入到 Rancher 的 AKS 集群需要 RBAC。 + +## AKS 集群配置参考 + +有关如何在 Rancher UI 配置 AKS 集群的更多信息，请参阅[配置参考](../../../../reference-guides/cluster-configuration/rancher-server-configuration/aks-cluster-configuration.md)。 + +## 私有集群 + +通常情况下，无论集群是否为私有，AKS worker 节点都不会获得公共 IP。在私有集群中，controlplane 没有公共端点。 + +Rancher 可以通过以下两种方式之一连接到私有 AKS 集群。 + +第一种方法是确保 Rancher 运行在与 AKS 节点相同的 [NAT](https://docs.microsoft.com/en-us/azure/virtual-network/nat-overview) 上。 + +第二种方法是运行命令向 Rancher 注册集群。配置集群后，你可以在任何能连接到集群的 Kubernetes API 的地方运行显示的命令。配置启用了私有 API 端点的 AKS 集群时，此命令将显示在弹出窗口中。 + +:::note + +注册现有 AKS 集群时，集群可能需要一些时间（可能是数小时）才会出现在 `Cluster To register` 下拉列表中。不同区域的结果可能不同。 + +::: + +有关连接到 AKS 专用集群的详细信息，请参阅 [AKS 文档](https://docs.microsoft.com/en-us/azure/aks/private-clusters#options-for-connecting-to-the-private-cluster)。 + +## 同步 + +AKS 配置者可以在 Rancher 和提供商之间同步 AKS 集群的状态。有关其工作原理的技术说明，请参阅[同步](../../../../reference-guides/cluster-configuration/rancher-server-configuration/sync-clusters.md)。 + +有关配置刷新间隔的信息，请参阅[本节](../../../../reference-guides/cluster-configuration/rancher-server-configuration/gke-cluster-configuration/gke-cluster-configuration.md#配置刷新间隔)。 + +## 以编程方式创建 AKS 集群 + +通过 Rancher 以编程方式部署 AKS 集群的最常见方法是使用 Rancher 2 Terraform Provider。详情请参见[使用 Terraform 创建集群](https://registry.terraform.io/providers/rancher/rancher2/latest/docs/resources/cluster)。 \ No newline at end of file diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-clusters-from-hosted-kubernetes-providers/eks.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-clusters-from-hosted-kubernetes-providers/eks.md new file mode 100644 index 00000000000..ede4d2dad7a --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-clusters-from-hosted-kubernetes-providers/eks.md @@ -0,0 +1,329 @@ +--- +title: 创建 EKS 集群 +--- + +Amazon EKS 为 Kubernetes 集群提供托管的 controlplane。Amazon EKS 跨多个可用区运行 Kubernetes controlplane 实例，以确保高可用性。Rancher 提供了一个直观的用户界面，用于管理和部署你运行在 Amazon EKS 中的 Kubernetes 集群。通过本指南，你将使用 Rancher 在你的 AWS 账户中快速轻松地启动 Amazon EKS Kubernetes 集群。有关 Amazon EKS 的更多信息，请参阅此[文档](https://docs.aws.amazon.com/eks/latest/userguide/what-is-eks.html)。 + + +## Amazon Web 服务的先决条件 + +:::caution + +部署到 Amazon AWS 会产生费用。有关详细信息，请参阅 [EKS 定价页面](https://aws.amazon.com/eks/pricing/)。 + +::: + +要在 EKS 上设置集群，你需要设置 Amazon VPC（虚拟私有云）。你还需要确保用于创建 EKS 集群的账号具有适当的[权限](#最小-eks-权限)。详情请参阅 [Amazon EKS 先决条件官方指南](https://docs.aws.amazon.com/eks/latest/userguide/getting-started-console.html#eks-prereqs)。 + +### Amazon VPC + +你需要建立一个 Amazon VPC 来启动 EKS 集群。VPC 使你能够将 AWS 资源启动到你定义的虚拟网络中。你可以自己设置一个 VPC，并在 Rancher 中创建集群时提供它。如果你创建过程中没有提供，Rancher 将创建一个 VPC。详情请参阅[教程：为你的 Amazon EKS 集群创建具有公有和私有子网的 VPC](https://docs.aws.amazon.com/eks/latest/userguide/create-public-private-vpc.html)。 + +### IAM 策略 + +Rancher 需要访问你的 AWS 账户才能在 Amazon EKS 中预置和管理你的 Kubernetes 集群。你需要在 AWS 账户中为 Rancher 创建一个用户，并定义该用户可以访问的内容。 + +1. 按照[此处](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users_create.html)的步骤创建具有编程访问权限的用户。 + +2. 创建一个 IAM 策略，定义该用户在 AWS 账户中有权访问的内容。请务必仅授予此用户所需的最小访问权限。[此处](#最小-eks-权限)列出了 EKS 集群所需的最低权限。请按照[此处](https://docs.aws.amazon.com/eks/latest/userguide/EKS_IAM_user_policies.html)的步骤创建 IAM 策略并将策略绑定到你的用户。 + +3. 最后，按照[此处](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html#Using_CreateAccessKey)的步骤为该用户创建访问密钥和密文密钥。 + +:::note 重要提示： + +定期轮换访问密钥和密文密钥非常重要。有关详细信息，请参阅此[文档](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html#rotating_access_keys_console)。 + +::: + +有关 EKS 的 IAM 策略的更多详细信息，请参阅 [Amazon EKS IAM 策略、角色和权限的官方文档](https://docs.aws.amazon.com/eks/latest/userguide/IAM_policies.html)。 + + +## 创建 EKS 集群 + +使用 Rancher 配置你的 Kubernetes 集群。 + +1. 点击 **☰ > 集群管理**。 +1. 在**集群**页面上，单击**创建**。 +1. 选择 **Amazon EKS**。 +1. 输入**集群名称**。 +1. 使用**成员角色**为集群配置用户授权。点击**添加成员**添加可以访问集群的用户。使用**角色**下拉菜单为每个用户设置权限。 +1. 完成表单的其余部分。如需帮助，请参阅[配置参考](#eks-集群配置参考)。 +1. 单击**创建**。 + +**结果**： + +你已创建集群，集群的状态是**配置中**。Rancher 已在你的集群中。 + +当集群状态变为 **Active** 后，你可访问集群。 + +**Active** 状态的集群会分配到两个项目： + +- `Default`：包含 `default` 命名空间 +- `System`：包含 `cattle-system`，`ingress-nginx`，`kube-public` 和 `kube-system` 命名空间。 + +## EKS 集群配置参考 + +有关 EKS 集群配置选项的完整列表，请参阅[此页面](../../../../reference-guides/cluster-configuration/rancher-server-configuration/eks-cluster-configuration.md)。 + +## 架构 + +下图展示了 Rancher 2.x 的上层架构。下图中，Rancher Server 管理两个 Kubernetes 集群，其中一个由 RKE 创建，另一个由 EKS 创建。 + +
通过 Rancher 的认证代理管理 Kubernetes 集群
+ +![架构](/img/rancher-architecture-rancher-api-server.svg) + +## AWS 服务事件 + +有关 AWS 服务事件的信息，请参阅[此页面](https://status.aws.amazon.com/)。 + +## 安全与合规 + +默认情况下，只有创建集群的 IAM 用户或角色才能访问该集群。在没有额外配置的情况下，使用其他用户或角色访问集群将导致错误。在 Rancher 中，这意味着使用映射到未用于创建集群的用户或角色的凭证，导致未经授权的错误。除非用于注册集群的凭证与 EKSCtl 使用的角色或用户匹配，否则 EKSCtl 集群将不会注册到 Rancher。通过将其他用户和角色添加到 kube-system 命名空间中的 aws-auth configmap，可以授权其他用户和角色访问集群。如需更深入的解释和详细说明，请参阅此[文档](https://aws.amazon.com/premiumsupport/knowledge-center/amazon-eks-cluster-access/)。 + +有关 Amazon EKS Kubernetes 集群的安全性和合规性的更多信息，请参阅此[文档](https://docs.aws.amazon.com/eks/latest/userguide/shared-responsibilty.html)。 + +## 教程 + +AWS 开源博客上的这篇[教程](https://aws.amazon.com/blogs/opensource/managing-eks-clusters-rancher/)将指导你使用 Rancher 设置一个 EKS 集群，部署一个可公开访问的示例应用来测试集群，并部署一个使用其他开源软件（如 Grafana 和 influxdb）来实时监控地理信息的示例项目。 + +## 最小 EKS 权限 + +这些是访问 Rancher EKS 驱动程序的全部功能所需的最低权限集。你需要 Rancher 的其他权限才能配置 `Service Role` 和 `VPC` 资源。如果你在创建集群**之前**创建了这些资源，你在配置集群时将可以使用这些资源。 + +| 资源 | 描述 | +---------|------------ +| 服务角色 | 提供允许 Kubernetes 代表你管理资源的权限。Rancher 可以使用以下[服务角色权限](#服务角色权限)来创建服务角色。 | +| VPC | 提供 EKS 和 Worker 节点使用的隔离网络资源。Rancher 使用以下 [VPC 权限](#vpc-权限)创建 VPC 资源。 | + + +资源定位使用 `*` 作为在 Rancher 中创建 EKS 集群之前，无法已知创建的资源的名称（ARN）。 + +```json +{ + "Version": "2012-10-17", + "Statement": [ + { + "Sid": "EC2Permissions", + "Effect": "Allow", + "Action": [ + "ec2:RunInstances", + "ec2:RevokeSecurityGroupIngress", + "ec2:RevokeSecurityGroupEgress", + "ec2:DescribeInstanceTypes", + "ec2:DescribeRegions", + "ec2:DescribeVpcs", + "ec2:DescribeTags", + "ec2:DescribeSubnets", + "ec2:DescribeSecurityGroups", + "ec2:DescribeRouteTables", + "ec2:DescribeLaunchTemplateVersions", + "ec2:DescribeLaunchTemplates", + "ec2:DescribeKeyPairs", + "ec2:DescribeInternetGateways", + "ec2:DescribeImages", + "ec2:DescribeAvailabilityZones", + "ec2:DescribeAccountAttributes", + "ec2:DeleteTags", + "ec2:DeleteLaunchTemplate", + "ec2:DeleteSecurityGroup", + "ec2:DeleteKeyPair", + "ec2:CreateTags", + "ec2:CreateSecurityGroup", + "ec2:CreateLaunchTemplateVersion", + "ec2:CreateLaunchTemplate", + "ec2:CreateKeyPair", + "ec2:AuthorizeSecurityGroupIngress", + "ec2:AuthorizeSecurityGroupEgress" + ], + "Resource": "*" + }, + { + "Sid": "CloudFormationPermissions", + "Effect": "Allow", + "Action": [ + "cloudformation:ListStacks", + "cloudformation:ListStackResources", + "cloudformation:DescribeStacks", + "cloudformation:DescribeStackResources", + "cloudformation:DescribeStackResource", + "cloudformation:DeleteStack", + "cloudformation:CreateStackSet", + "cloudformation:CreateStack" + ], + "Resource": "*" + }, + { + "Sid": "IAMPermissions", + "Effect": "Allow", + "Action": [ + "iam:PassRole", + "iam:ListRoles", + "iam:ListRoleTags", + "iam:ListInstanceProfilesForRole", + "iam:ListInstanceProfiles", + "iam:ListAttachedRolePolicies", + "iam:GetRole", + "iam:GetInstanceProfile", + "iam:DetachRolePolicy", + "iam:DeleteRole", + "iam:CreateRole", + "iam:AttachRolePolicy" + ], + "Resource": "*" + }, + { + "Sid": "KMSPermissions", + "Effect": "Allow", + "Action": "kms:ListKeys", + "Resource": "*" + }, + { + "Sid": "EKSPermissions", + "Effect": "Allow", + "Action": [ + "eks:UpdateNodegroupVersion", + "eks:UpdateNodegroupConfig", + "eks:UpdateClusterVersion", + "eks:UpdateClusterConfig", + "eks:UntagResource", + "eks:TagResource", + "eks:ListUpdates", + "eks:ListTagsForResource", + "eks:ListNodegroups", + "eks:ListFargateProfiles", + "eks:ListClusters", + "eks:DescribeUpdate", + "eks:DescribeNodegroup", + "eks:DescribeFargateProfile", + "eks:DescribeCluster", + "eks:DeleteNodegroup", + "eks:DeleteFargateProfile", + "eks:DeleteCluster", + "eks:CreateNodegroup", + "eks:CreateFargateProfile", + "eks:CreateCluster" + ], + "Resource": "*" + } + ] +} +``` + +### 服务角色权限 + +这些是 EK​​S 集群创建期间所需的权限，以便 Rancher 可以代表用户创建服务角色。 + +```json +{ + "Version": "2012-10-17", + "Statement": [ + { + "Sid": "IAMPermissions", + "Effect": "Allow", + "Action": [ + "iam:AddRoleToInstanceProfile", + "iam:AttachRolePolicy", + "iam:CreateInstanceProfile", + "iam:CreateRole", + "iam:CreateServiceLinkedRole", + "iam:DeleteInstanceProfile", + "iam:DeleteRole", + "iam:DetachRolePolicy", + "iam:GetInstanceProfile", + "iam:GetRole", + "iam:ListAttachedRolePolicies", + "iam:ListInstanceProfiles", + "iam:ListInstanceProfilesForRole", + "iam:ListRoles", + "iam:ListRoleTags", + "iam:PassRole", + "iam:RemoveRoleFromInstanceProfile" + ], + "Resource": "*" + } + ] +} +``` + +当你创建 EKS 集群时，Rancher 会创建一个具有以下信任策略的服务角色： + +```json +{ + "Version": "2012-10-17", + "Statement": [ + { + "Action": "sts:AssumeRole", + "Principal": { + "Service": "eks.amazonaws.com" + }, + "Effect": "Allow", + "Sid": "" + } + ] +} +``` + +此角色还有两个角色策略，它们具有以下策略的 ARN： + +``` +arn:aws:iam::aws:policy/AmazonEKSClusterPolicy +arn:aws:iam::aws:policy/AmazonEKSServicePolicy +``` + +### VPC 权限 + +这些是 Rancher 创建虚拟私有云 (VPC) 和相关资源所需的权限。 + +```json +{ + "Version": "2012-10-17", + "Statement": [ + { + "Sid": "VPCPermissions", + "Effect": "Allow", + "Action": [ + "ec2:ReplaceRoute", + "ec2:ModifyVpcAttribute", + "ec2:ModifySubnetAttribute", + "ec2:DisassociateRouteTable", + "ec2:DetachInternetGateway", + "ec2:DescribeVpcs", + "ec2:DeleteVpc", + "ec2:DeleteTags", + "ec2:DeleteSubnet", + "ec2:DeleteRouteTable", + "ec2:DeleteRoute", + "ec2:DeleteInternetGateway", + "ec2:CreateVpc", + "ec2:CreateSubnet", + "ec2:CreateSecurityGroup", + "ec2:CreateRouteTable", + "ec2:CreateRoute", + "ec2:CreateInternetGateway", + "ec2:AttachInternetGateway", + "ec2:AssociateRouteTable" + ], + "Resource": "*" + } + ] +} +``` + +## 同步 + +EKS 配置者可以在 Rancher 和提供商之间同步 EKS 集群的状态。有关其工作原理的技术说明，请参阅[同步](../../../../reference-guides/cluster-configuration/rancher-server-configuration/sync-clusters.md)。 + +有关配置刷新间隔的信息，请参阅[本节](../../../../reference-guides/cluster-configuration/rancher-server-configuration/eks-cluster-configuration.md#配置刷新间隔)。 + +## 故障排除 + +如果你的更改被覆盖，可能是集群数据与 EKS 同步的方式导致的。不要在使用其他源（例如 EKS 控制台）对集群进行更改后，又在五分钟之内在 Rancher 中进行更改。有关其工作原理，以及如何配置刷新间隔的信息，请参阅[同步](#同步)。 + +如果在修改或注册集群时返回未经授权的错误，并且集群不是使用你的凭证所属的角色或用户创建的，请参阅[安全与合规](#安全与合规)。 + +有关 Amazon EKS Kubernetes 集群的任何问题或故障排除详细信息，请参阅此[文档](https://docs.aws.amazon.com/eks/latest/userguide/troubleshooting.html)。 + +## 以编程方式创建 EKS 集群 + +通过 Rancher 以编程方式部署 EKS 集群的最常见方法是使用 Rancher 2 Terraform Provider。详情请参见[使用 Terraform 创建集群](https://registry.terraform.io/providers/rancher/rancher2/latest/docs/resources/cluster)。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-clusters-from-hosted-kubernetes-providers/gke.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-clusters-from-hosted-kubernetes-providers/gke.md new file mode 100644 index 00000000000..f0168f45262 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-clusters-from-hosted-kubernetes-providers/gke.md @@ -0,0 +1,101 @@ +--- +title: 创建 GKE 集群 +--- + +## 先决条件 + +你需要在 Google Kubernetes Engine 中进行一些设置。 + +### ServiceAccount 令牌 + +使用 [Google Kubernetes Engine](https://console.cloud.google.com/projectselector/iam-admin/serviceaccounts) 创建服务帐号。GKE 使用这个账号来操作你的集群。创建此账号还会生成用于身份验证的私钥。 + +该 ServiceAccount 需要以下角色： + +- **Compute Viewer:** `roles/compute.viewer` +- **Project Viewer:** `roles/viewer` +- **Kubernetes Engine Admin:** `roles/container.admin` +- **Service Account User:** `roles/iam.serviceAccountUser` + +[Google 文档：创建和启用 ServiceAccount](https://cloud.google.com/compute/docs/access/create-enable-service-accounts-for-instances) + +有关获取 ServiceAccount 的私钥的详细信息，请参阅[此 Google 云文档](https://cloud.google.com/iam/docs/creating-managing-service-account-keys#creating_service_account_keys)。你需要将密钥保存为 JSON 格式。 + +### Google 项目 ID + +你的集群需要包括到谷歌项目中。 + +要创建新项目，请参阅[此 Google 云文档](https://cloud.google.com/resource-manager/docs/creating-managing-projects#creating_a_project)。 + +要获取现有项目的项目 ID，请参阅[此 Google 云文档](https://cloud.google.com/resource-manager/docs/creating-managing-projects#identifying_projects)。 + +## 配置 GKE 集群 + +:::caution + +部署到 GKE 会产生费用。 + +::: + +### 1. 创建云凭证 + +1. 点击 **☰ > 集群管理**。 +1. 在左侧导航栏中，单击**云凭证**。 +1. 单击**创建**。 +1. 输入你 Google 云凭证的名称。 +1. 在 **ServiceAccount** 文本框中，粘贴你的 ServiceAccount 私钥 JSON，或上传 JSON 文件。 +1. 单击**创建**。 + +**结果**：你已创建 Rancher 用于配置新 GKE 集群的凭证。 + +### 2. 创建 GKE 集群 +使用 Rancher 配置你的 Kubernetes 集群。要使用 Rancher 成功创建 GKE 集群，GKE 必须处于 Standard 模式。GKE 在创建 Kubernetes 集群时有两种运行模式，分别是 Autopilot 和 Standard 模式。Autopilot 模式的集群配置对编辑 kube-system 命名空间有限制。但是，Rancher 在安装时需要在 kube-system 命名空间中创建资源。因此，你将无法创建 Autopilot 模式的 GKE 集群。如需详细了解 GKE Autopilot 模式和 Standard 模式之间的差异，请访问[比较 GKE Autopilot 和 Standard ](https://cloud.google.com/kubernetes-engine/docs/resources/autopilot-standard-feature-comparison)。 + + +1. 点击 **☰ > 集群管理**。 +1. 在**集群**页面上，单击**创建**。 +1. 单击 **Google GKE**。 +1. 输入**集群名称**。 +1. 可选：使用**成员角色**为集群配置用户授权。点击**添加成员**添加可以访问集群的用户。使用**角色**下拉菜单为每个用户设置权限。 +1. 可选：将 Kubernetes [标签](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/)或[注释](https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations/)添加到集群。 +1. 输入你的 Google 项目 ID 和 Google 云凭证。 +1. 完成表单的其余部分。如需帮助，请参阅 [GKE 集群配置参考](../../../../reference-guides/cluster-configuration/rancher-server-configuration/gke-cluster-configuration/gke-cluster-configuration.md)。 +1. 单击**创建**。 + +**结果**：你已成功部署 GKE 集群。 + +你已创建集群，集群的状态是**配置中**。Rancher 已在你的集群中。 + +当集群状态变为 **Active** 后，你可访问集群。 + +**Active** 状态的集群会分配到两个项目： + +- `Default`：包含 `default` 命名空间 +- `System`：包含 `cattle-system`，`ingress-nginx`，`kube-public` 和 `kube-system` 命名空间。 + +## 私有集群 + +支持私有 GKE 集群。注意，此高级设置可能涉及更多步骤。有关详细信息，请参阅[本节](../../../../reference-guides/cluster-configuration/rancher-server-configuration/gke-cluster-configuration/gke-private-clusters.md)。 + +## 配置参考 + +有关在 Rancher 中配置 GKE 集群的详细信息，请参阅[此页面](../../../../reference-guides/cluster-configuration/rancher-server-configuration/gke-cluster-configuration/gke-cluster-configuration.md)。 +## 更新 Kubernetes 版本 + +集群的 Kubernetes 版本可以升级到 GKE 集群所在区域或地区中可用的任何版本。升级 Kubernetes 主版本不会自动升级 Worker 节点。节点可以独立升级。 + +:::note + +GKE 在 1.19+ 中取消了基本身份验证。要将集群升级到 1.19+，必须在谷歌云中禁用基本身份认证。否则，在升级到 1.19+ 时，Rancher 会出现错误。你可以按照 [Google 文档](https://cloud.google.com/kubernetes-engine/docs/how-to/api-server-authentication#disabling_authentication_with_a_static_password)进行操作。然后，你就可以使用 Rancher 将 Kubernetes 版本更新到 1.19+。 + +::: + +## 同步 + +GKE 配置者可以在 Rancher 和提供商之间同步 GKE 集群的状态。有关其工作原理的技术说明，请参阅[同步](../../../../reference-guides/cluster-configuration/rancher-server-configuration/sync-clusters.md)。 + +有关配置刷新间隔的信息，请参阅[本节](../../../../reference-guides/cluster-configuration/rancher-server-configuration/gke-cluster-configuration/gke-cluster-configuration.md#配置刷新间隔)。 + +## 以编程方式创建 GKE 集群 + +通过 Rancher 以编程方式部署 GKE 集群的最常见方法是使用 Rancher 2 Terraform Provider。详情请参见[使用 Terraform 创建集群](https://registry.terraform.io/providers/rancher/rancher2/latest/docs/resources/cluster)。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-clusters-from-hosted-kubernetes-providers/set-up-clusters-from-hosted-kubernetes-providers.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-clusters-from-hosted-kubernetes-providers/set-up-clusters-from-hosted-kubernetes-providers.md new file mode 100644 index 00000000000..b034f3df70a --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-clusters-from-hosted-kubernetes-providers/set-up-clusters-from-hosted-kubernetes-providers.md @@ -0,0 +1,27 @@ +--- +title: 通过托管 Kubernetes 提供商设置集群 +--- + + + + + +在这种情况下，Rancher 不会配置 Kubernetes，因为它是由 Google Kubernetes Engine (GKE)、Amazon Elastic Container Service for Kubernetes 或 Azure Kubernetes Service 等提供商安装的。 + +如果你使用 Kubernetes 提供商，例如 Google GKE，Rancher 将与对应的云 API 集成，允许你从 Rancher UI 为托管集群创建和管理 RBAC。 + +在这个用例中，Rancher 使用提供商的 API 向托管提供商发送请求。然后，提供商会为你配置和托管集群。集群创建成功后，你可以像管理本地集群或云上集群一样，通过 Rancher UI 对集群进行管理。 + +Rancher 支持以下 Kubernetes 提供商： + +- [Google GKE (Google Kubernetes Engine)](https://cloud.google.com/kubernetes-engine/) +- [Amazon EKS (Amazon Elastic Container Service for Kubernetes)](https://aws.amazon.com/eks/) +- [Microsoft AKS (Azure Kubernetes Service)](https://azure.microsoft.com/en-us/services/kubernetes-service/) + +## 托管 Kubernetes 提供商的认证 + +使用 Rancher 创建由提供商托管的集群时，你需要输入认证信息。Rancher 会使用认证信息来访问云厂商的 API。有关如何获取此信息的详情，请参阅： + +- [创建 GKE 集群](gke.md) +- [创建 EKS 集群](eks.md) +- [创建 AKS 集群](aks.md) diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/use-windows-clusters/azure-storageclass-configuration.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/use-windows-clusters/azure-storageclass-configuration.md new file mode 100644 index 00000000000..3003cab8733 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/use-windows-clusters/azure-storageclass-configuration.md @@ -0,0 +1,41 @@ +--- +title: Azure 中存储类的配置 +--- + +如果你的节点使用 Azure VM，则可以使用 [Azure 文件](https://docs.microsoft.com/en-us/azure/aks/azure-files-dynamic-pv)作为集群的存储类（StorageClass）。 + +为了让 Azure 创建所需的存储资源，请执行以下步骤操作： + +1. [配置 Azure 云提供商](../../kubernetes-clusters-in-rancher-setup/set-up-cloud-providers/azure.md)。 +1. 配置 `kubectl` 以连接到你的集群。 +1. 复制 ServiceAccount 的 `ClusterRole` 和 `ClusterRoleBinding` 清单： + ```yml + --- + apiVersion: rbac.authorization.k8s.io/v1 + kind: ClusterRole + metadata: + name: system:azure-cloud-provider + rules: + - apiGroups: [''] + resources: ['secrets'] + verbs: ['get','create'] + --- + apiVersion: rbac.authorization.k8s.io/v1 + kind: ClusterRoleBinding + metadata: + name: system:azure-cloud-provider + roleRef: + kind: ClusterRole + apiGroup: rbac.authorization.k8s.io + name: system:azure-cloud-provider + subjects: + - kind: ServiceAccount + name: persistent-volume-binder + namespace: kube-system + ``` + +1. 使用以下命令在集群中进行创建： + + ``` + # kubectl create -f + ``` diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/use-windows-clusters/network-requirements-for-host-gateway.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/use-windows-clusters/network-requirements-for-host-gateway.md new file mode 100644 index 00000000000..bfe8fd56a59 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/use-windows-clusters/network-requirements-for-host-gateway.md @@ -0,0 +1,36 @@ +--- +title: Host Gateway (L2bridge) 的网络要求 +--- + +本节介绍如何配置使用 *Host Gateway (L2bridge)* 模式的自定义 Windows 集群。 + +## 禁用私有 IP 地址检查 + +如果你使用 *Host Gateway (L2bridge)* 模式，并将节点托管在下面列出的云服务上，则必须在启动时禁用 Linux 或 Windows 主机的私有 IP 地址检查。要为每个节点禁用此检查，请按照以下各个云服务对应的说明进行操作： + +| 服务 | 禁用私有 IP 地址检查的说明 | +--------|------------------------------------------------ +| Amazon EC2 | [禁用源/目标检查](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_NAT_Instance.html#EIP_Disable_SrcDestCheck) | +| Google GCE | [为实例启用 IP 转发](https://cloud.google.com/vpc/docs/using-routes#canipforward)（默认情况下，VM 无法转发由另一个 VM 发起的数据包） | +| Azure VM | [启用或禁用 IP 转发](https://docs.microsoft.com/en-us/azure/virtual-network/virtual-network-network-interface#enable-or-disable-ip-forwarding) | + +## 云托管虚拟机的路由配置 + +如果是使用 Flannel 的 [**Host Gateway (L2bridge)**](https://github.com/coreos/flannel/blob/master/Documentation/backends.md#host-gw) 后端，同一节点上的所有容器都属于私有子网，流量通过主机网络从一个节点上的子网路由到在另一个节点上的子网。 + +- 在 AWS、虚拟化集群或裸机服务器上配置 worker 节点时，请确保它们属于同一个第 2 层子网。如果节点不属于同一个第 2 层子网，`host-gw` 网络将不起作用。 + +- 在 GCE 或 Azure 上配置 worker 节点时，节点不在同一个第 2 层子网上。GCE 和 Azure 上的节点属于可路由的第 3 层网络。按照以下说明配置 GCE 和 Azure，以便云网络知道如何在每个节点上传送主机子网。 + +要在 GCE 或 Azure 上配置主机子网路由，首先运行以下命令，以找出每个 worker 节点上的主机子网： + +```bash +kubectl get nodes -o custom-columns=nodeName:.metadata.name,nodeIP:status.addresses[0].address,routeDestination:.spec.podCIDR +``` + +然后按照各个云提供商的说明，为每个节点配置路由规则： + +| 服务 | 说明 | +--------|------------- +| Google GCE | 为每个节点添加静态路由：[添加静态路由](https://cloud.google.com/vpc/docs/using-routes#addingroute)。 | +| Azure VM | 创建一个路由表：[自定义路由：用户定义](https://docs.microsoft.com/en-us/azure/virtual-network/virtual-networks-udr-overview#user-defined)。 | diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/use-windows-clusters/use-windows-clusters.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/use-windows-clusters/use-windows-clusters.md new file mode 100644 index 00000000000..d48f0484231 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/use-windows-clusters/use-windows-clusters.md @@ -0,0 +1,283 @@ +--- +title: 在 Windows 集群上启动 Kubernetes +--- + + + + + +使用 Rancher 配置[自定义集群](../../../../reference-guides/cluster-configuration/rancher-server-configuration/use-existing-nodes/use-existing-nodes.md)时，Rancher 通过 RKE（Rancher Kubernetes Engine）在现有节点上安装 Kubernetes。 + +在使用 Rancher 配置的 Windows 集群中，集群必须同时包含 Linux 和 Windows 节点。Kubernetes controlplane 只能运行在 Linux 节点上，Windows 节点只能有 Worker 角色。Windows 节点只能用于部署工作负载。 + +Windows 集群的其他要求如下： + +- 只有在创建集群时启用了 Windows 支持的集群才能添加 Windows 节点。无法为现有集群启用 Windows 支持。 +- 需要 Kubernetes 1.15+。 +- 必须使用 Flannel 网络提供商。 +- Windows 节点必须有 50 GB 的磁盘空间。 + +有关完整的要求列表，请参阅[本节](#windows-集群的要求)。 + +有关支持 Windows 的 Kubernetes 功能摘要，请参阅[在 Windows 中使用 Kubernetes 支持的功能和限制](https://kubernetes.io/docs/setup/production-environment/windows/intro-windows-in-kubernetes/#supported-functionality-and-limitations)的 Kubernetes 文档，或[在 Kubernetes 中调度 Windows 容器的指南](https://kubernetes.io/docs/setup/production-environment/windows/user-guide-windows-containers/)。 + +## RKE2 Windows + +RKE2 配置功能还包括在 Windows 集群上安装 RKE2。RKE2 的 Windows 功能包括： + +- 由 containerd 提供支持的使用 RKE2 的 Windows 容器 +- 直接从 Rancher UI 配置 Windows RKE2 自定义集群 +- 用于 Windows RKE2 自定义集群的 Calico CNI +- 技术预览包含了 Windows Server 的 SAC 版本（2004 和 20H2） + +要使 Windows 支持 RKE2 自定义集群，请选择 Calico 作为 CNI。 + +:::note + +默认情况下，Rancher 允许 Windows 工作负载 pod 部署在 Windows 和 Linux Worker 节点上。在 RKE2 中创建混合集群时，你必须编辑 Chart 中的 `nodeSelector`，从而将 Pod 放置到兼容的 Windows 节点上。有关如何使用 `nodeSelector` 将 pod 分配给节点的更多信息，请参阅 [Kubernetes 文档](https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node/#nodeselector)。 +::: + +- Kubernetes v1.24.1 及更高版本支持 Windows RKE2 中的 HostProcess 容器。有关详细信息，请参阅[上游文档](https://kubernetes.io/docs/tasks/configure-pod-container/create-hostprocess-pod/)。 + +## Windows 集群的要求 + +网络、操作系统和 Docker 的一般节点要求与 [Rancher 安装](../../../../getting-started/installation-and-upgrade/installation-requirements/installation-requirements.md) 的节点要求相同。 + +### 操作系统和 Docker 要求 + +我们对 Windows Server 和 Windows 容器的支持与 LTSC（长期服务渠道）和 SAC（半年渠道）的 Microsoft 官方生命周期相匹配。 + +有关 Windows Server 的支持生命周期的日期，请参阅 [Microsoft 文档](https://docs.microsoft.com/en-us/windows-server/get-started/windows-server-release-info)。 + +### Kubernetes 版本 + +需要 Kubernetes v1.15+。 + +如果你在 Windows Server 20H2 Standard Core 上使用 Kubernetes v1.21，则必须在节点上安装补丁“2019-08 Servicing Stack Update for Windows Server”。 + +### 节点要求 + +集群中的主机至少需要： + +- 2 核 CPU +- 5 GB 内存 +- 50 GB 磁盘空间 + +Rancher 不会配置不满足要求的节点。 + +### 网络要求 + +在配置新集群之前，请确保你已经在接收入站网络流量的设备上安装了 Rancher。这是集群节点与 Rancher 通信所必需的。如果你尚未安装 Rancher，请在继续阅读本指南之前先参阅[安装文档](../../../../getting-started/installation-and-upgrade/installation-and-upgrade.md)进行安装。。 + +Rancher 仅支持使用 Flannel 作为网络提供商的 Windows。 + +有两个网络选项：[**Host Gateway (L2bridge)**](https://github.com/coreos/flannel/blob/master/Documentation/backends.md#host-gw) 和 [**VXLAN (Overlay)**](https://github.com/coreos/flannel/blob/master/Documentation/backends.md#vxlan)。默认选项是 **VXLAN (Overlay)** 模式。 + +对于 **Host Gateway (L2bridge)** 网络，最好为所有节点使用相同的第 2 层网络。否则，你需要为它们配置路由规则。有关详细信息，请参阅[配置云托管 VM 路由的文档](network-requirements-for-host-gateway.md#云托管虚拟机的路由配置)。如果你使用的是 Amazon EC2、Google GCE 或 Azure 虚拟机，你需要[禁用私有 IP 地址检查](network-requirements-for-host-gateway.md#禁用私有-ip-地址检查)。 + +对于 **VXLAN (Overlay)** 网络，你必须安装 [KB4489899](https://support.microsoft.com/en-us/help/4489899) 补丁。大多数云托管的 VM 已经具有此修补程序。 + +如果你在为 AWS 虚拟私有云配置 DHCP 选项集，请注意，你只能在 `domain-name` 选项字段中指定一个域名。详情请参见 [DHCP 选项文档](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_DHCP_Options.html)： + +:::note + +一些 Linux 操作系统支持以空格分隔的多个域名。但是，其他 Linux 操作系统和 Windows 将该值视为单个域名，从而导致意外错误。如果你的 DHCP 选项集与具有多个操作系统实例的 VPC 相关联，请仅指定一个域名。 + +::: + +### 带有 ESXi 6.7u2 及更高版本的 vSphere 上的 Rancher + +如果你在带有 ESXi 6.7u2 或更高版本的 VMware vSphere 上使用 Rancher，并使用 Red Hat Enterprise Linux 8.3、CentOS 8.3 或 SUSE Enterprise Linux 15 SP2 或更高版本，你需要禁用 `vmxnet3` 虚拟网络适配器硬件卸载功能。否则，不同集群节点上的 pod 之间的所有网络连接会因为超时错误而失败。从 Windows pod 到在 Linux 节点上运行的关键服务（例如 CoreDNS）的所有连接也将失败。外部连接也可能失败。出现这个问题的原因是 Linux 发行版在 `vmxnet3` 中启用了硬件卸载功能，而且 `vmxnet3` 硬件卸载功能中存在一个会丢弃客户覆盖流量的数据包的 bug。要解决此问题，必须禁用 `vmxnet3` 硬件卸载功能。此设置不会在重启后继续生效，因此需要在每次启动时禁用。推荐的做法是在 `/etc/systemd/system/disable_hw_offloading.service` 中创建一个 systemd 单元文件，这会在启动时禁用 `vmxnet3` 硬件卸载功能。禁用 `vmxnet3` 硬件卸载功能的示例 systemd 单元文件如下所示。注意，`` 必须自定义为主机的 `vmxnet3` 网络接口，如 `ens192`： + +``` +[Unit] +Description=Disable vmxnet3 hardware offloading feature + +[Service] +Type=oneshot +ExecStart=ethtool -K tx-udp_tnl-segmentation off +ExecStart=ethtool -K tx-udp_tnl-csum-segmentation off +StandardOutput=journal + +[Install] +WantedBy=multi-user.target +``` + +然后在 systemd 单元文件上设置适当的权限： + +``` +chmod 0644 /etc/systemd/system/disable_hw_offloading.service +``` + +最后，启用 systemd 服务： + +``` +systemctl enable disable_hw_offloading.service +``` + +### 架构要求 + +Kubernetes 集群管理节点（`etcd` 和 `controlplane`）必须运行在 Linux 节点上。 + +部署工作负载的 `worker` 节点通常是 Windows 节点，但必须至少有一个 `worker` 节点运行在 Linux 上，才能按顺序运行 Rancher Cluster Agent、DNS、Metrics Server 和 Ingress 相关容器。 + +#### 推荐架构 + +我们推荐下表中列出的三节点架构，但你始终可以添加额外的 Linux 和 Windows worker 节点来扩展集群，从而实现冗余： + +| 节点 | 操作系统 | Kubernetes 集群角色 | 用途 | +| ------ | --------------------------------------------- | --------------------------- | ----------------------------------------------------------- | +| 节点 1 | Linux (推荐 Ubuntu Server 18.04) | Control plane, etcd, worker | 管理 Kubernetes 集群 | +| 节点 2 | Linux (推荐 Ubuntu Server 18.04) | Worker | 支持集群的 Rancher Cluster Agent、Metrics Server、DNS 和 Ingress | +| 节点 3 | Windows（Windows Server 核心版本 1809 或更高版本） | Worker | 运行 Windows 容器 | + +### 容器要求 + +Windows 要求容器的版本必须与部署容器的 Windows Server 的版本一致。因此，你必须在 Windows Server 核心版本 1809 或更高版本上构建容器。如果你已经使用早期的 Windows Server 核心版本构建了容器，则必须使用 Windows Server 核心版本 1809 或更高版本重新构建容器。 + +### 云提供商要求 + +如果你在集群中设置了 Kubernetes 云提供商，则需要进行一些额外的操作。如果你想使用云提供商的功能，例如为集群自动配置存储、负载均衡器或其他基础设施，你可能需要设置云提供商。有关如何配置满足条件的云提供商集群节点，请参阅[此页面](../set-up-cloud-providers/set-up-cloud-providers.md)。 + +如果你的云提供商是 GCE（Google Compute Engine），则必须执行以下操作： + +- 按照[步骤](../set-up-cloud-providers/google-compute-engine.md)在`cluster.yml` 中启用 GCE 云提供商。 +- 在 Rancher 中配置集群时，在 Rancher UI 中选择**自定义云提供商**作为云提供商。 + +## 教程：如何创建支持 Windows 的集群 + +本教程描述了如何使用[推荐架构](#推荐架构)中的三个节点创建由 Rancher 配置的集群。 + +在现有节点上使用 Rancher 配置集群时，你需要在每个节点上安装 [Rancher Agent](../../../../reference-guides/cluster-configuration/rancher-server-configuration/use-existing-nodes/rancher-agent-options.md) 来将节点添加到集群中。在 Rancher UI 中创建或编辑集群时，你会看到一个**自定义节点运行命令**，你可以在每台服务器上运行该命令，从而将服务器添加到集群中。 + +要设置支持 Windows 节点和容器的集群，你需要完成以下任务： + +### 1. 配置主机 + +要在具有 Windows 支持的现有节点上配置集群，请准备好你的主机。 + +主机可以是： + +- 云托管的虚拟机 +- 虚拟化集群中的虚拟机 +- 裸金属服务器 + +你将配置三个节点： + +- 一个 Linux 节点，用于管理 Kubernetes controlplane 并存储你的 `etcd`。 +- 第二个 Linux 节点，它将作为 worker 节点。 +- Windows 节点，它将作为 worker 节点运行 Windows 容器。 + +| 节点 | 操作系统 | +| ------ | --------------------------------------------- | +| 节点 1 | Linux (推荐 Ubuntu Server 18.04) | +| 节点 2 | Linux (推荐 Ubuntu Server 18.04) | +| 节点 3 | Windows（Windows Server 核心版本 1809 或更高版本） | + +如果你的节点托管在**云提供商**上，并且你需要自动化支持（例如负载均衡器或持久存储设备），你的节点还需要满足额外的配置要求。详情请参见[选择云提供商](../set-up-cloud-providers/set-up-cloud-providers.md)。 + +### 2. 在现有节点上创建集群 + +在现有节点上创建 Windows 集群的说明与一般[创建自定义集群的说明](../../../../reference-guides/cluster-configuration/rancher-server-configuration/use-existing-nodes/use-existing-nodes.md)非常相似，但有一些特定于 Windows 的要求。 + +1. 在左上角，单击 **☰ > 集群管理**。 +1. 在**集群**页面上，单击**创建**。 +1. 单击**自定义**。 +1. 在**集群名称**字段中输入集群的名称。 +1. 在 **Kubernetes 版本**下拉菜单中，选择 v1.19 或更高版本。 +1. 在**网络提供商**字段中，选择 **Flannel**。 +1. 在 **Windows 支持**中，单击**启用**。 +1. 可选：启用 Windows 支持后，你将能够选择 Flannel 后端模式。有两个网络选项：[**Host Gateway (L2bridge)**](https://github.com/coreos/flannel/blob/master/Documentation/backends.md#host-gw) 和 [**VXLAN (Overlay)**](https://github.com/coreos/flannel/blob/master/Documentation/backends.md#vxlan)。 默认选项是 **VXLAN (Overlay)** 模式。 +1. 点击**下一步**。 + +:::note 重要提示： + +对于 Host Gateway (L2bridge) 网络，最好为所有节点使用相同的第 2 层网络。否则，你需要为它们配置路由规则。有关详细信息，请参阅[配置云托管 VM 路由的文档](network-requirements-for-host-gateway.md#云托管虚拟机的路由配置)。如果你使用的是 Amazon EC2、Google GCE 或 Azure 虚拟机，你需要[禁用私有 IP 地址检查](network-requirements-for-host-gateway.md#禁用私有-ip-地址检查)。 + +::: + +### 3. 将节点添加到集群 + +本节介绍如何将 Linux 和 Worker 节点注册到集群。你将在每个节点上运行一个命令，该命令将安装 Rancher Agent 并允许 Rancher 管理每个节点。 + +#### 添加 Linux master 节点 + +在本节中，你需要在 Rancher UI 上填写表单以获取自定义命令，从而在 Linux master 节点上安装 Rancher Agent。然后，复制该命令并在 Linux master 节点上运行命令，从而在集群中注册该节点。 + +集群中的第一个节点应该是具有 **controlplane** 和 **etcd** 角色的 Linux 主机。至少必须为此节点启用这两个角色，并且必须先将此节点添加到集群中，然后才能添加 Windows 主机。 + +1. 在**节点操作系统**中，单击 **Linux**。 +1. 在**节点角色**中，至少选择 **etcd** 和 **controlplane**。推荐选择所有的三个角色。 +1. 可选：如果点击**显示高级选项**，你可以自定义 [Rancher Agent](../../../../reference-guides/cluster-configuration/rancher-server-configuration/use-existing-nodes/rancher-agent-options.md)和[节点标签](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/)的设置。 +1. 将屏幕上显示的命令复制到剪贴板。 +1. SSH 到你的 Linux 主机，然后运行复制到剪贴板的命令。 +1. 完成配置 Linux 节点后，选择**完成**。 + +**结果**： + +你已创建集群，集群的状态是**配置中**。Rancher 已在你的集群中。 + +当集群状态变为 **Active** 后，你可访问集群。 + +**Active** 状态的集群会分配到两个项目： + +- `Default`：包含 `default` 命名空间 +- `System`：包含 `cattle-system`，`ingress-nginx`，`kube-public` 和 `kube-system` 命名空间。 + + +节点可能需要几分钟才能注册到集群中。 + +#### 添加 Linux Worker 节点 + +在本节中，我们通过运行命令将 Linux Worker 节点注册到集群中。 + +在初始配置集群之后，你的集群只有一个 Linux 主机。接下来，我们添加另一个 Linux `worker` 主机，用于支持集群的 _Rancher Cluster Agent_、_Metrics Server_、_DNS_ 和 _Ingress_。 + +1. 在左上角，单击 **☰ > 集群管理**。 +1. 转到你创建的集群，然后单击 **⋮ > 编辑配置**。 +1. 向下滚动到**节点操作系统**。选择 **Linux**。 +1. 在**自定义节点运行命令**中，转到**节点选项**并选择 **Worker** 角色。 +1. 将屏幕上显示的命令复制到剪贴板。 +1. 使用远程终端连接登录到你的 Linux 主机。粘贴剪贴板的命令并运行。 +1. 在 **Rancher**中，单击**保存**。 + +**结果**：**Worker** 角色已安装在你的 Linux 主机上，并且节点会向 Rancher 注册。节点可能需要几分钟才能注册到集群中。 + +:::note + +Linux Worker 节点上的污点 + +以下污点将添加集群中的 Linux Worker 节点中。将此污点添加到 Linux Worker 节点后，添加到 Windows 集群的任何工作负载都将自动调度到 Windows Worker 节点。如果想将工作负载专门调度到 Linux Worker 节点上，则需要为这些工作负载添加容忍度。 + +| 污点键 | 污点值 | 污点效果 | +| -------------- | ---------- | ------------ | +| `cattle.io/os` | `linux` | `NoSchedule` | + +::: + +#### 添加 Windows Worker 节点 + +在本节中，我们通过运行命令将 Windows Worker 节点注册到集群中。 + +你可以通过编辑集群并选择 **Windows** 选项，从而将 Windows 主机添加到集群中。 + +1. 在左上角，单击 **☰ > 集群管理**。 +1. 转到你创建的集群，然后单击 **⋮ > 编辑配置**。 +1. 向下滚动到**节点操作系统**。选择 **Windows**。注意：你将看到 **worker** 角色是唯一可用的角色。 +1. 将屏幕上显示的命令复制到剪贴板。 +1. 使用你喜欢的工具（例如 [Microsoft 远程桌面](https://docs.microsoft.com/en-us/windows-server/remote/remote-desktop-services/clients/remote-desktop-clients)）登录到 Windows 主机。在 **Command Prompt (CMD)** 中运行复制到剪贴板的命令。 +1. 在 Rancher 中，单击**保存**。 +1. 可选：如果要向集群添加更多 Windows 节点，请重复这些操作。 + +**结果**：**Worker** 角色已安装在你的 Windows 主机上，并且节点会向 Rancher 注册。节点可能需要几分钟才能注册到集群中。你现在已拥有一个 Windows Kubernetes 集群。 + +### 可选的后续步骤 + +创建集群后，你可以通过 Rancher UI 访问集群。最佳实践建议你设置以下访问集群的备用方式： + +- **通过 kubectl CLI 访问你的集群**：按照[这些步骤](../../manage-clusters/access-clusters/use-kubectl-and-kubeconfig.md#在工作站使用-kubectl-访问集群)在你的工作站上使用 kubectl 访问集群。在这种情况下，你将通过 Rancher Server 的身份验证代理进行身份验证，然后 Rancher 会让你连接到下游集群。此方法允许你在没有 Rancher UI 的情况下管理集群。 +- **通过 kubectl CLI 使用授权的集群端点访问你的集群**：按照[这些步骤](../../manage-clusters/access-clusters/use-kubectl-and-kubeconfig.md#直接使用下游集群进行身份验证)直接使用 kubectl 访问集群，而无需通过 Rancher Server 进行身份验证。我们建议设置此替代方法来访问集群，以便在无法连接到 Rancher 时访问集群。 + +## Azure 中存储类的配置 + +如果你的节点使用 Azure VM，则可以使用 [Azure 文件](https://docs.microsoft.com/en-us/azure/aks/azure-files-dynamic-pv)作为集群的存储类（StorageClass）。详情请参见[此部分](azure-storageclass-configuration.md)。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/use-windows-clusters/windows-linux-cluster-feature-parity.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/use-windows-clusters/windows-linux-cluster-feature-parity.md new file mode 100644 index 00000000000..81d832577f2 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/use-windows-clusters/windows-linux-cluster-feature-parity.md @@ -0,0 +1,42 @@ +--- +title: Windows 和 Linux 集群的功能奇偶一致性 +--- + +Windows 集群与 Linux 集群的功能支持不相同。 + +下图描述了 Rancher 上 Windows 和 Linux 之间的功能奇偶一致性： + +| **组件** | **Linux** | **Windows** | +--- | --- | --- +| **发行版** | | +| RKE | 支持 | 支持 | +| RKE2 | 支持 | 支持 | +| K3S | 支持 | 不支持 | +| EKS | 支持 | 不支持 | +| GKE | 支持 | 不支持 | +| AKS | 支持 | 不支持 | +| **Rancher 组件** | | +| Server | 支持 | 不支持 | +| Agent | 支持 | 支持 | +| Fleet | 支持 | 支持 | +| EKS Operator | 支持 | 不支持 | +| AKS Operator | 不支持 | 不支持 | +| GKE Operator | 不支持 | 不支持 | +| Monitoring/Alerting v2 | 支持 | 支持 | +| Logging v2 | 支持 | 支持 | +| Istio | 支持 | 不支持 | +| Catalog v2 | 支持 | 不支持 | +| OPA | 支持 | 不支持 | +| Longhorn | 支持 | 不支持 | +| CIS 扫描 | 支持 | 不支持 | +| Backup/Restore Operator | 支持 | 不支持 | +| **CNI/附加组件** | | +| Flannel | 支持 | 支持 | +| Canal | 支持 | 不支持 | +| Calico | 支持 | 支持（仅 RKE2） | +| Cilium | 支持 | 不支持 | +| Multus | 支持 | 不支持 | +| Traefik | 支持 | 不支持 | +| NGINX Ingress | 支持 | 不支持 | + +有关功能支持的更新信息，你可以访问 GitHub 上的 [rancher/windows](https://github.com/rancher/windows)。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/use-windows-clusters/workload-migration-guidance.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/use-windows-clusters/workload-migration-guidance.md new file mode 100644 index 00000000000..ce334bc5382 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/use-windows-clusters/workload-migration-guidance.md @@ -0,0 +1,303 @@ +--- +title: 将 Windows 工作负载从 RKE2 迁移到 RKE2 +--- + +**注意**：Rancher Support 的 SLA 不涵盖本文档的内容。因此，请谨慎继续。 + +本文档介绍了如何将 Windows 工作负载从 RKE1 迁移到 RKE2。 + +## RKE1 Windows 调度 + +RKE1 Windows 工作负载是基于污点和容忍度调度的。 + +RKE1 Windows 集群中的每个 Linux 节点（无论分配了什么角色）都会有一个默认污点，除非工作负载配置了容忍度，否则该污点会阻止工作负载调度到节点上。这是 RKE1 Windows 集群的一个主要特性，目的是为了仅运行 Windows 工作负载。 + +- 默认 RKE1 Linux 节点 `NoSchedule` 污点： + +```yml +apiVersion: v1 +kind: Node +spec: + ... + taints: + - effect: NoSchedule + key: cattle.io/os + value: linux +``` +
+ +- RKE1 Linux `NoSchedule` 对工作负载的容忍度 + +以下容忍度允许将最终用户的工作负载调度到 RKE1 Windows 集群中的任何 Linux 节点上。这些容忍度用于核心的 Rancher 服务和工作负载： + +```yml +apiVersion: apps/v1 +kind: Deployment +spec: + ... + template: + ... + spec: + tolerations: + - effect: NoSchedule + key: cattle.io/os + operator: Equal + value: linux +``` +
+ +- 根据最佳实践，在 Linux 节点上运行的任何最终用户工作负载都将仅调度到具有 worker 角色的节点上： + +```yml +apiVersion: apps/v1 +kind: Deployment +spec: + ... + template: + ... + spec: + tolerations: + - effect: NoSchedule + key: cattle.io/os + operator: Equal + value: linux + affinity: + nodeAffinity: + requiredDuringSchedulingIgnoredDuringExecution: + - preference: + matchExpressions: + - key: node-role.kubernetes.io/worker + operator: In + values: + - "true" + weight: 100 + ... +``` + +## RKE2 Windows 调度 + +根据对混合工作负载支持的反馈和请求，RKE2 Windows 默认支持 Linux 和 Windows 工作负载。RKE2 调度默认依赖节点选择器。这是不同于 RKE1 的一个显着变化，因为 RKE2 中没有包含污点和容忍。节点选择器是 RKE1 Windows 集群的关键部分，可以帮助你轻松迁移工作负载。 + +## 示例迁移 + +### 将 Windows 工作负载从 RKE1 迁移到 RKE2 + +- 迁移前的 RKE1 Windows Deployment： + +```yaml +apiVersion: apps/v1 +kind: Deployment +spec: + ... + template: + ... + spec: + affinity: + nodeAffinity: + requiredDuringSchedulingIgnoredDuringExecution: + nodeSelectorTerms: + - matchExpressions: + - key: kubernetes.io/os + operator: NotIn + values: + - linux +``` +
+ +- 使用 `nodeAffinity` 迁移后的 RKE2 Windows Deployment： + +```yaml +apiVersion: apps/v1 +kind: Deployment +... +spec: + ... + template: + ... + spec: + ... + affinity: + nodeAffinity: + requiredDuringSchedulingIgnoredDuringExecution: + nodeSelectorTerms: + - matchExpressions: + - key: kubernetes.io/os + operator: In + values: + - windows +``` + +### RKE1 Windows 集群的 Linux-Only Deployment + +> **重要提示**：在利用 `nodeSelector` 和 `nodeAffinity` 时，请注意以下几点： +> +> - 如果同时指定了 `nodeSelector` 和 `nodeAffinity`，则必须满足这两个条件才能将 `Pod` 调度到节点上。 +> - 如果指定了与单个 `nodeSelectorTerms` 关联的多个 `matchExpressions`，则只有当所有 `matchExpressions` 都符合要求时才会调度 `Pod`。 + +
+ +- 迁移前的 RKE1 Windows 集群 Linux-only Deployment（针对 RKE1 Linux Worker 节点）： + +```yml +apiVersion: apps/v1 +kind: Deployment +spec: + ... + template: + ... + spec: + tolerations: + - effect: NoSchedule + key: cattle.io/os + operator: Equal + value: linux + affinity: + nodeAffinity: + requiredDuringSchedulingIgnoredDuringExecution: + - weight: 100 + preference: + matchExpressions: + - key: node-role.kubernetes.io/worker + operator: In + values: + - "true" + +``` +
+ +- 使用 `nodeSelector` 迁移后的 RKE2 混合集群 Linux-only Deployment（针对 RKE2 Linux Worker 节点） + +```yml +apiVersion: apps/v1 +kind: Deployment +spec: + ... + template: + ... + spec: + nodeSelector: + kubernetes.io/os: "linux" + node-role.kubernetes.io/worker: "true" +``` +
+ +- 使用 `nodeAffinity` 迁移后的 RKE2 混合集群 Linux-only Deployment（针对 RKE2 Linux Worker 节点） + +```yaml +apiVersion: apps/v1 +kind: Deployment +spec: + ... + template: + ... + spec: + affinity: + nodeAffinity: + requiredDuringSchedulingIgnoredDuringExecution: + - weight: 100 + preference: + matchExpressions: + - key: node-role.kubernetes.io/worker + operator: In + values: + - "true" + nodeSelectorTerms: + - matchExpressions: + - key: kubernetes.io/os + operator: In + values: + - linux +``` +## RKE1 Windows - 支持的 Windows Server 版本 + +### 长期服务渠道（LTSC） + +- Windows Server 2019 LTSC ✅ 将于 2024 年 1 月 9 日 达到 Mainstream EOL 并于 2029 年 1 月 9 日 达到 Extended EOL + +### 半年频道 (SAC) + +- Windows Server 20H2 SAC ❌ 2022 年 8 月 9 日已达到 EOL +- Windows Server 2004 SAC ❌ 2021 年 12 月 14 日已达到 EOL +- Windows Server 1909 SAC ❌ 2021 年 5 月 11 日已达到 EOL +- Windows Server 1903 SAC ❌ 2020 年 12 月 8 日已达到 EOL +- Windows Server 1809 SAC ❌ 2020 年 11 月 10 日已达到 EOL + +## RKE2 Windows - 支持的 Windows Server 版本 + +### RKE2 中的长期服务通道（LTSC） + +- Windows Server 2019 LTSC ✅ 将于 2024 年 1 月 9 日 达到 Mainstream EOL 并于 2029 年 1 月 9 日 达到 Extended EOL +- Windows Server 2022 LTSC ✅ 将于 2026 年 10 月 13 日达到 Mainstream EOL，并于 2031 年 10 月 13 日达到 Extended EOL + +> **注意**：RKE2 不支持 SAC。 + + +有关详细信息，请参阅以下参考资料： + +- [Windows Server SAC 生命周期](https://docs.microsoft.com/en-us/lifecycle/products/windows-server) + +- [Windows Server 2022 LTSC 生命周期](https://docs.microsoft.com/en-us/lifecycle/products/windows-server-2022) + +- [Windows Server 2019 LTSC 生命周期](https://docs.microsoft.com/en-us/lifecycle/products/windows-server-2019) + + +## Kubernetes 版本支持 + +> **注意**：根据 [Rancher 2.6.7 支持矩阵](https://www.suse.com/suse-rancher/support-matrix/all-supported-versions/rancher-v2-6-7/)，下面列出的所有版本均支持 SLA。未列出的版本都视为为已达到 EOL 且不受 SUSE SLA 支持。 + +### 对比 Rancher 2.5 与 Rancher 2.6：Windows 集群的支持矩阵 + +**对比 RKE1 与 RKE2：Windows 集群支持的 Kubernetes 版本**： + +| Kubernetes 版本 | RKE1 | RKE2 | +|-------------- |:----: |:----: | +| 1.18 | ✓ | | +| 1.19 | ✓ | | +| 1.20 | ✓ | | +| 1.21 | ✓ | | +| 1.22 | ✓ | ✓ | +| 1.23 | | ✓ | +| 1.24 | | ✓ | +| 1.25+ | | ✓ | + + +### 对比 Rancher 2.5 与 Rancher 2.6：支持用于配置 RKE1 和 RKE2 Windows 集群的 Kubernetes 版本 + +| Rancher 版本 | Kubernetes 版本 | RKE1 | RKE2 | +|:-----------------------: |:------------------------: |:----: |:----: | +| 2.5 - RKE1 配置 | 1.18 1.19 1.20 | ✓ | | +| 2.6 - RKE1 配置 | 1.18 1.19 1.20 1.21 1.22 | ✓ | | +| 2.6 - RKE2 配置 | 1.22 1.23 1.24 1.25+ | | ✓ | + + +## 将工作负载迁移到 RKE2 Windows 的指南 + +参考[对比 Rancher 2.5 与 Rancher 2.6：Windows 集群的支持矩阵](#对比-rancher-25-与-rancher-26windows-集群的支持矩阵)和[对比 Rancher 2.5 与 Rancher 2.6：支持用于配置 RKE1 和 RKE2 Windows 集群的 Kubernetes 版本](#对比-rancher-25-与-rancher-26支持用于配置-rke1-和-rke2-windows-集群的-kubernetes-版本)中的表格，你会发现 RKE1 和 RKE2 的 Kubernetes 1.22 版本发生了重叠。因此，当遵循 Rancher 推荐的方法时，这将是迁移 RKE1 Windows 工作负载所需的基本版本。 + +### Rancher 2.5 的就地升级 + +1. 将 Rancher 版本升级到 2.6.5+。 +1. 使用最新的可用补丁版本将 RKE1 Windows 下游集群升级到 RKE1 v1.22。 +1. 通过 RKE1 Windows 集群所在的匹配补丁版本，使用 RKE2 v1.22 配置新的 RKE2 Windows 下游集群。 +1. 开始将 Windows 工作负载从 RKE1 迁移到 RKE2 集群。 +1. 执行验证测试，确保在将应用程序从 RKE1 迁移到 RKE2 时没有丢失或更改功能。 +1. 验证测试成功后，你可以选择将 RKE2 1.22.x 集群升级到新的次要版本，例如 1.23 或 1.24。 + + +### 将 Windows 工作负载迁移到新的 Rancher 环境 + +> **重要提示**：要执行以下任一选项，你需要使用 Rancher 2.6.5 或更高版本。 + +**为 RKE1 和 RKE2 使用匹配的 Kubernetes 补丁版本时**： + +1. 通过 RKE1 Windows 集群所在的匹配补丁版本，使用 RKE2 v1.22 配置新的 RKE2 Windows 下游集群。 +1. 开始将 Windows 工作负载从 RKE1 迁移到 RKE2 集群。 +1. 执行验证测试，确保在将应用程序从 RKE1 迁移到 RKE2 时没有丢失或更改功能。 +1. 验证测试成功后，你可以选择将 RKE2 1.22.x 集群升级到新的次要版本，例如 1.23 或 1.24。 + + +**为 RKE2 使用更新的 Kubernetes 补丁版本时**： + +1. 使用 RKE2 v1.23 或 v1.24 配置新的 RKE2 Windows 下游集群。 +1. 开始将 Windows 工作负载从 RKE1 迁移到 RKE2 集群。 +1. 执行验证测试，确保在将应用程序从 RKE1 迁移到 RKE2 时没有丢失或更改功能。 \ No newline at end of file diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/kubernetes-resources-setup/configmaps.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/kubernetes-resources-setup/configmaps.md new file mode 100644 index 00000000000..e66e26a3975 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/kubernetes-resources-setup/configmaps.md @@ -0,0 +1,35 @@ +--- +title: ConfigMap +--- + +大多数 Kubernetes 密文用于存储敏感信息，但是 [ConfigMap](https://kubernetes.io/docs/tasks/configure-pod-container/configure-pod-configmap/) 会存储一般配置信息，例如一组配置文件。由于 ConfigMap 不存储敏感信息，因此 ConfigMap 可以自动更新，不需要在更新后重启其容器（其他类型的密文大多需要手动更新和重启容器后才能生效）。 + +ConfigMap 接受常见字符串格式的键值对，例如配置文件或 JSON Blob。上传配置映射后，任何工作负载都可以将其引用为环境变量或卷挂载。 + +1. 在左上角，单击 **☰ > 集群管理**。 +1. 转到具有要引用 ConfigMap 的工作负载的集群，然后单击 **Explore**。 +1. 在左侧导航栏中，单击**更多资源 > 核心 > ConfigMaps**。 +1. 单击**创建**。 +1. 输入 ConfigMap 的**名称**。 + + :::note + + Kubernetes 将 ConfigMap 归类为[密文](https://kubernetes.io/docs/concepts/configuration/secret/)，项目或命名空间中的密文不能重名。因此，为了避免冲突，ConfigMap 的名称必须与工作空间中的其他证书、镜像仓库和密文不一样。 + + ::: + +1. 选择要添加 ConfigMap 的**命名空间**。 + +1. 在**数据**选项卡上，将键值对添加到你的 ConfigMap。你可以根据需要添加任意数量的值。通过复制和粘贴的方式将多个键值对添加到 ConfigMap。你也可以使用**从文件读取**来添加数据。请注意，如果要存储敏感数据，请[使用密文](secrets.md)，不要使用 ConfigMap。 +1. 单击**创建**。 + +**结果**：已将 ConfigMap 添加到命名空间。你可以在 Rancher UI 的**资源 > ConfigMaps** 视图中查看它。 + +## 后续操作 + +现在你已经将 ConfigMap 添加到命名空间，你可以将其添加到原始命名空间部署的工作负载中。你可以使用 ConfigMap 指定应用程序使用的信息，例如： + +- 应用程序环境变量。 +- 指定安装到工作负载的卷的参数。 + +有关将 ConfigMap 添加到工作负载的更多信息，请参阅[部署工作负载](workloads-and-pods/deploy-workloads.md)。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/kubernetes-resources-setup/create-services.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/kubernetes-resources-setup/create-services.md new file mode 100644 index 00000000000..2c9be4b41c9 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/kubernetes-resources-setup/create-services.md @@ -0,0 +1,29 @@ +--- +title: Services +--- + +Deployment、StatefulSet 和 Daemonset 会管理 Pod 配置，而 Service 使用选择器将流量引导到 Pod。 + +每个工作负载（至少配置一个端口）都会创建一个补充的服务发现条目。此服务发现条目使用以下命名约定为工作负载的 pod 启用 DNS 解析： +`..svc.cluster.local`。 + +你可以创建其它 service，这样，指定的命名空间就可以使用一个或多个外部 IP 地址、外部主机名、另一个 DNS 记录的别名、其他工作负载或与你创建的选择器匹配的一组 pod 来进行解析。 + +1. 在左上角，单击 **☰ > 集群管理**。 +1. 转到要添加 service 的集群，然后单击 **Explore**。 +1. 点击**服务发现 > 服务**。 +1. 单击**创建**。 +1. 选择要创建的 service 类型。 +1. 从下拉列表中选择一个的**命名空间**。 +1. 输入 service 的**名称**。此名称会用于 DNS 解析。 +1. 完成表单的其余部分。如需帮助，请参阅 [service 的上游 Kubernetes 文档](https://kubernetes.io/docs/concepts/services-networking/service/)。 +1. 单击**创建**。 + +**结果**：创建了一个新 service。 + +- 你可以从项目的**服务发现**选项卡查看记录。 +- 访问你创建的新记录的新 DNS 名称 (`..svc.cluster.local`) 时，它会解析所选的命名空间。 + +## 相关链接 + +- [使用 HostAliases 向 Pod /etc/hosts 文件添加条目](https://kubernetes.io/docs/concepts/services-networking/add-entries-to-pod-etc-hosts-with-host-aliases/) diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/kubernetes-resources-setup/encrypt-http-communication.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/kubernetes-resources-setup/encrypt-http-communication.md new file mode 100644 index 00000000000..ccef1846703 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/kubernetes-resources-setup/encrypt-http-communication.md @@ -0,0 +1,38 @@ +--- +title: 加密 HTTP 通信 +description: 了解如何添加 SSL 证书或 TLS 证书 +--- + +在 Rancher/Kubernetes 中创建 Ingress 时，你必须提供包含 TLS 私钥和证书的密文，用于加密和解密通过 Ingress 的通信。你可以通过将证书添加到 Ingress Deployment 来让 Ingress 使用证书。 + +:::note 先决条件： + +你必须具有可上传的 TLS 私钥和证书。 + +::: + +## 1. 创建一个密文 + + +1. 在左上角，单击 **☰ > 集群管理**。 +1. 转到要部署 Ingress 的集群，然后单击**更多资源 > 核心 > 密文**。 +1. 单击**创建**。 +1. 单击 **TLS 证书**。 +1. 输入密文的名称。请注意，密文的名称必须与项目/工作空间中的其他证书、镜像仓库和密文不一样。 +1. 在**私钥**字段中，将证书的私钥复制并粘贴到文本框中（包括标头和页脚），或者单击**从文件读取**选择文件系统上的私钥。如果可能，我们建议使用**从文件读取**以减少出错的可能性。请注意，私钥文件的扩展名是 `.key`。 +1. 在**证书**字段中，将你的证书复制并粘贴到文本框中（包括标头和页脚），或者单击**从文件读取**选择文件系统上的证书文件。如果可能，我们建议使用**从文件读取**以减少出错的可能性。请注意，证书文件的扩展名是 `.crt`。 +1. 单击**创建**。 + +## 2. 将密文添加到 Ingress + +1. 在左上角，单击 **☰ > 集群管理**。 +1. 转到要部署 Ingress 的集群，然后单击**服务发现 > Ingress**。 +1. 单击**创建**。 +1. 选择 Ingress 的**命名空间**。 +1. 输入 Ingress 的**名称**。 +1. 在**证书**选项卡中，选择包含你的证书和私钥的密文。 +1. 单击**创建**。 + +## 后续操作 + +现在，你可以在该项目或命名空间中启动 Ingress 时添加证书。如需更多信息，请参阅[添加 Ingress](load-balancer-and-ingress-controller/add-ingresses.md)。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/kubernetes-resources-setup/horizontal-pod-autoscaler/about-hpas.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/kubernetes-resources-setup/horizontal-pod-autoscaler/about-hpas.md new file mode 100644 index 00000000000..eb60cb4c97b --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/kubernetes-resources-setup/horizontal-pod-autoscaler/about-hpas.md @@ -0,0 +1,39 @@ +--- +title: Horizontal Pod Autoscaler 介绍 +--- + +[Horizontal Pod Autoscaler（HPA）](https://kubernetes.io/docs/tasks/run-application/horizontal-pod-autoscale/)是一项 Kubernetes 功能，用于将集群配置为自动扩缩其运行的服务。本节介绍 HPA 如何与 Kubernetes 一起工作。 + +## 为什么要使用 Horizo​​ntal Pod Autoscaler？ + +你可以使用 HPA 来自动扩缩 ReplicationController、Deployment 或 ReplicaSet 中的 pod 数量。HPA 会自动扩缩正在运行的 pod 数量以实现最高效率。影响 pod 数量的因素包括： + +- 允许运行的最小和最大 pod 数，由用户定义。 +- 资源指标中报告的 CPU/内存使用情况。 +- 第三方指标应用程序（如 Prometheus、Datadog 等）提供的自定义指标。 + +HPA 通过以下方式改进你的服务： + +- 释放硬件资源，避免资源被过多的 pod 浪费。 +- 按需提高/降低性能以达到服务级别协议。 + +## HPA 的工作原理 + +![HPA 架构](/img/horizontal-pod-autoscaler.jpg) + +HPA 实现为一个控制循环，其周期由以下 `kube-controller-manager` 标志控制： + +| 标志 | 默认 | 描述 | +---------|----------|----------| +| `--horizontal-pod-autoscaler-sync-period` | `30s` | HPA 在 deployment 中审核资源/自定义指标的频率。 | +| `--horizontal-pod-autoscaler-downscale-delay` | `5m0s` | 完成缩减操作后，HPA 必须等待多长时间才能启动另一个缩减操作。 | +| `--horizontal-pod-autoscaler-upscale-delay` | `3m0s` | 完成扩展操作后，HPA 必须等待多长时间才能启动另一个扩展操作。 | + + +有关 HPA 的完整文档，请参阅 [Kubernetes 文档](https://kubernetes.io/docs/tasks/run-application/horizontal-pod-autoscale/)。 + +## Horizo​​ntal Pod Autoscaler API 对象 + +HPA 是 Kubernetes `autoscaling` API 组中的 API 资源。当前的稳定版本是 `autoscaling/v1`，它只支持对 CPU 自动扩缩。要获得内存和自定义指标的扩缩支持，请改用 beta 版本 `autoscaling/v2beta1`。 + +有关 HPA API 对象的更多信息，请参阅 [HPA GitHub 自述文件](https://github.com/kubernetes/design-proposals-archive/blob/main/autoscaling/horizontal-pod-autoscaler.md#horizontalpodautoscaler-object)。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/kubernetes-resources-setup/horizontal-pod-autoscaler/horizontal-pod-autoscaler.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/kubernetes-resources-setup/horizontal-pod-autoscaler/horizontal-pod-autoscaler.md new file mode 100644 index 00000000000..b50aecb39a9 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/kubernetes-resources-setup/horizontal-pod-autoscaler/horizontal-pod-autoscaler.md @@ -0,0 +1,30 @@ +--- +title: Horizontal Pod Autoscaler +description: 了解 Pod 水平自动扩缩 (HPA)。如何管理 HPA 以及如何使用服务部署来进行测试 +--- + + + + + +[Horizontal Pod Autoscaler（HPA）](https://kubernetes.io/docs/tasks/run-application/horizontal-pod-autoscale/)是一项 Kubernetes 功能，用于将集群配置为自动扩缩其运行的服务。 + +Rancher 提供了一些附加功能来帮助管理 HPA，具体取决于 Rancher 的版本。 + +你可以使用 Rancher UI 创建、管理和删除 HPA。仅在 `autoscaling/v2beta2` API 中支持 HPA。 + +## 管理 HPA + +管理 HPA 的方式因你的 Kubernetes API 版本而异： + +- **Kubernetes API 版本 autoscaling/V2beta1**：允许根据应用程序的 CPU 和内存利用率自动扩缩 pod。 +- **Kubernetes API 版本 autoscaling/V2beta2**：允许根据 CPU 和内存利用率以及自定义指标自动扩缩 pod。 + +你可以使用 Rancher UI 创建、管理和删除 HPA。在 Rancher UI 中，你可以将 HPA 配置为根据 CPU 和内存利用率进行扩缩。有关详细信息，请参阅[使用 Rancher UI 管理 HPA](manage-hpas-with-ui.md)。如需根据自定义指标进行 HPA，你仍然需要使用 `kubectl`。有关详细信息，请参阅[配置 HPA 以使用 Prometheus 自定义指标进行扩缩](manage-hpas-with-kubectl.md#使用资源指标cpu-和内存配置-hpa-以进行扩缩)。 + +在 Rancher 2.0.7 及更高版本中创建的集群自动满足使用 HPA 的所有要求（metrics-server 和 Kubernetes 集群配置）。 +## 使用服务部署测试 HPA + +你可以转到你的项目并单击 **资源 > HPA** 来查看​​ HPA 当前的副本数。有关详细信息，请参阅[获取 HPA 指标和状态](manage-hpas-with-ui.md)。 + +你还可以使用 `kubectl` 来获取你使用负载测试工具测试的 HPA 的状态。有关详细信息，请参阅[使用 kubectl 测试 HPA](test-hpas-with-kubectl.md)。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/kubernetes-resources-setup/horizontal-pod-autoscaler/manage-hpas-with-kubectl.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/kubernetes-resources-setup/horizontal-pod-autoscaler/manage-hpas-with-kubectl.md new file mode 100644 index 00000000000..a8ff4dd0879 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/kubernetes-resources-setup/horizontal-pod-autoscaler/manage-hpas-with-kubectl.md @@ -0,0 +1,204 @@ +--- +title: 使用 kubectl 管理 HPA +--- + +本文介绍如何使用 `kubectl` 管理 HPA。本文对以下操作进行了说明： + +- 创建 HPA +- 获取 HPA 的信息 +- 删除 HPA +- 配置 HPA 以根据 CPU 或内存利用率进行扩缩 +- 如果你使用 Prometheus 等第三方工具的指标，配置 HPA 以使用自定义指标进行扩缩 + + +你可以在 Rancher UI 中创建、查看和删除 HPA。你还可以根据 Rancher UI 中的 CPU/内存使用情况进行扩缩。有关详细信息，请参阅[使用 Rancher UI 管理 HPA](./manage-hpas-with-ui.md)。如果要使用 CPU/内存以外的指标来扩缩 HPA，你需要使用 `kubectl`。 + +## 管理 HPA 的基本 kubectl 命令 + +如果你有 HPA 清单文件，则可以使用 `kubectl` 来创建、管理和删除 HPA： + +- 创建 HPA + + - 有清单：`kubectl create -f ` + + - 没有清单（仅支持 CPU）：`kubectl autoscale deployment hello-world --min=2 --max=5 --cpu-percent=50` + +- 获取 HPA 信息 + + - 基本：`kubectl get hpa hello-world` + + - 详细描述：`kubectl describe hpa hello-world` + +- 删除 HPA + + - `kubectl delete hpa hello-world` + +## HPA 清单定义示例 + +HPA 清单是用于使用 `kubectl` 管理 HPA 的配置文件。 + +以下代码片段在 HPA 清单中使用了不同的指令。请参阅示例下方的列表以了解每个指令的用途。 + +```yml +apiVersion: autoscaling/v2beta1 +kind: HorizontalPodAutoscaler +metadata: + name: hello-world +spec: + scaleTargetRef: + apiVersion: extensions/v1beta1 + kind: Deployment + name: hello-world + minReplicas: 1 + maxReplicas: 10 + metrics: + - type: Resource + resource: + name: cpu + targetAverageUtilization: 50 + - type: Resource + resource: + name: memory + targetAverageValue: 100Mi +``` + + +| 指令 | 描述 | +---------|----------| +| `apiVersion: autoscaling/v2beta1` | 正在使用的 Kubernetes `autoscaling` API 组的版本。此示例清单使用 beta 版本，因此启用了按 CPU./内存进行扩缩。 | +| `name: hello-world` | 表示 HPA 在为 `hello-word` deployment 执行自动扩缩。 | +| `minReplicas: 1` | 表示运行的最小副本数不能低于 1。 | +| `maxReplicas: 10` | 指示 deployment 中的最大副本数不能超过 10。 | +| `targetAverageUtilization: 50` | 表示当平均运行的 pod 使用超过请求 CPU 的 50% 时，deployment 将扩展 pod。 | +| `targetAverageValue: 100Mi` | 表示当平均运行的 pod 使用超过 100Mi 的内存时，deployment 将扩展 pod。 | +
+ +## 使用资源指标（CPU 和内存）配置 HPA 以进行扩缩 + +在 Rancher 2.0.7 及更高版本中创建的集群满足使用 Horizontal Pod Autoscaler 的所有要求（metrics-server 和 Kubernetes 集群配置）。 + +运行以下命令以检查你的安装中是否有可用的指标： + +``` +$ kubectl top nodes +NAME CPU(cores) CPU% MEMORY(bytes) MEMORY% +node-controlplane 196m 9% 1623Mi 42% +node-etcd 80m 4% 1090Mi 28% +node-worker 64m 3% 1146Mi 29% +$ kubectl -n kube-system top pods +NAME CPU(cores) MEMORY(bytes) +canal-pgldr 18m 46Mi +canal-vhkgr 20m 45Mi +canal-x5q5v 17m 37Mi +canal-xknnz 20m 37Mi +kube-dns-7588d5b5f5-298j2 0m 22Mi +kube-dns-autoscaler-5db9bbb766-t24hw 0m 5Mi +metrics-server-97bc649d5-jxrlt 0m 12Mi +$ kubectl -n kube-system logs -l k8s-app=metrics-server +I1002 12:55:32.172841 1 heapster.go:71] /metrics-server --source=kubernetes.summary_api:https://kubernetes.default.svc?kubeletHttps=true&kubeletPort=10250&useServiceAccount=true&insecure=true +I1002 12:55:32.172994 1 heapster.go:72] Metrics Server version v0.2.1 +I1002 12:55:32.173378 1 configs.go:61] Using Kubernetes client with master "https://kubernetes.default.svc" and version +I1002 12:55:32.173401 1 configs.go:62] Using kubelet port 10250 +I1002 12:55:32.173946 1 heapster.go:128] Starting with Metric Sink +I1002 12:55:32.592703 1 serving.go:308] Generated self-signed cert (apiserver.local.config/certificates/apiserver.crt, apiserver.local.config/certificates/apiserver.key) +I1002 12:55:32.925630 1 heapster.go:101] Starting Heapster API server... +[restful] 2018/10/02 12:55:32 log.go:33: [restful/swagger] listing is available at https:///swaggerapi +[restful] 2018/10/02 12:55:32 log.go:33: [restful/swagger] https:///swaggerui/ is mapped to folder /swagger-ui/ +I1002 12:55:32.928597 1 serve.go:85] Serving securely on 0.0.0.0:443 +``` + + +## 配置 HPA 以使用 Prometheus 自定义指标进行扩缩 + +你可以将 HPA 配置为根据第三方软件提供的自定义指标进行自动扩缩。使用第三方软件进行自动扩缩的最常见用例是使用应用程序级别的指标（即每秒 HTTP 请求数）。HPA 使用 `custom.metrics.k8s.io` API 来使用这些指标。通过为指标收集解决方案部署自定义指标适配器，你可以启用此 API。 + +对于这个例子，我们将使用 [Prometheus](https://prometheus.io/)。我们假设： + +- Prometheus 部署在集群中。 +- Prometheus 配置正确，并从 pod、节点、命名空间等收集合适的指标。 +- Prometheus 暴露在以下 URL 和端口：`http://prometheus.mycompany.io:80` + +Prometheus 可用于 Rancher 2.0 应用商店中的 Deployment。如果它还没有运行在你的集群中，请在 Rancher 应用商店中部署它。 + +为了让 HPA 使用来自 Prometheus 的自定义指标，[k8s-prometheus-adapter](https://github.com/DirectXMan12/k8s-prometheus-adapter) 包需要在你集群的 `kube-system` 命名空间中。要安装 `k8s-prometheus-adapter`，使用 [banzai-charts](https://github.com/banzaicloud/banzai-charts) 提供的 Helm Chart。 + +1. 在集群中初始化 Helm。 + ``` + # kubectl -n kube-system create serviceaccount tiller + kubectl create clusterrolebinding tiller --clusterrole cluster-admin --serviceaccount=kube-system:tiller + helm init --service-account tiller + ``` + +1. 从 GitHub 克隆 `banzai-charts` 仓库： + ``` + # git clone https://github.com/banzaicloud/banzai-charts + ``` + +1. 安装 `prometheus-adapter` Chart，指定 Prometheus URL 和端口号： + ``` + # helm install --name prometheus-adapter banzai-charts/prometheus-adapter --set prometheus.url="http://prometheus.mycompany.io",prometheus.port="80" --namespace kube-system + ``` + +1. 检查 `prometheus-adapter` 是否正常运行。检查服务 pod 并在 `kube-system` 命名空间中登录。 + + 1. 检查服务 pod 是否处于 `Running` 状态。输入以下命令： + ``` + # kubectl get pods -n kube-system + ``` + 在输出结果中查找 `Running` 状态。 + ``` + NAME READY STATUS RESTARTS AGE + ... + prometheus-adapter-prometheus-adapter-568674d97f-hbzfx 1/1 Running 0 7h + ... + ``` + 1. 通过输入以下命令检查服务日志，确保服务正常运行： + ``` + # kubectl logs prometheus-adapter-prometheus-adapter-568674d97f-hbzfx -n kube-system + ``` + 然后查看日志输出以确认服务正在运行。 + +
+ Prometheus Adaptor 日志 + + ... + I0724 10:18:45.696679 1 round_trippers.go:436] GET https://10.43.0.1:443/api/v1/namespaces/default/pods?labelSelector=app%3Dhello-world 200 OK in 2 milliseconds + I0724 10:18:45.696695 1 round_trippers.go:442] Response Headers: + I0724 10:18:45.696699 1 round_trippers.go:445] Date: Tue, 24 Jul 2018 10:18:45 GMT + I0724 10:18:45.696703 1 round_trippers.go:445] Content-Type: application/json + I0724 10:18:45.696706 1 round_trippers.go:445] Content-Length: 2581 + I0724 10:18:45.696766 1 request.go:836] Response Body: {"kind":"PodList","apiVersion":"v1","metadata":{"selfLink":"/api/v1/namespaces/default/pods","resourceVersion":"6237"},"items":[{"metadata":{"name":"hello-world-54764dfbf8-q6l82","generateName":"hello-world-54764dfbf8-","namespace":"default","selfLink":"/api/v1/namespaces/default/pods/hello-world-54764dfbf8-q6l82","uid":"484cb929-8f29-11e8-99d2-067cac34e79c","resourceVersion":"4066","creationTimestamp":"2018-07-24T10:06:50Z","labels":{"app":"hello-world","pod-template-hash":"1032089694"},"annotations":{"cni.projectcalico.org/podIP":"10.42.0.7/32"},"ownerReferences":[{"apiVersion":"extensions/v1beta1","kind":"ReplicaSet","name":"hello-world-54764dfbf8","uid":"4849b9b1-8f29-11e8-99d2-067cac34e79c","controller":true,"blockOwnerDeletion":true}]},"spec":{"volumes":[{"name":"default-token-ncvts","secret":{"secretName":"default-token-ncvts","defaultMode":420}}],"containers":[{"name":"hello-world","image":"rancher/hello-world","ports":[{"containerPort":80,"protocol":"TCP"}],"resources":{"requests":{"cpu":"500m","memory":"64Mi"}},"volumeMounts":[{"name":"default-token-ncvts","readOnly":true,"mountPath":"/var/run/secrets/kubernetes.io/serviceaccount"}],"terminationMessagePath":"/dev/termination-log","terminationMessagePolicy":"File","imagePullPolicy":"Always"}],"restartPolicy":"Always","terminationGracePeriodSeconds":30,"dnsPolicy":"ClusterFirst","serviceAccountName":"default","serviceAccount":"default","nodeName":"34.220.18.140","securityContext":{},"schedulerName":"default-scheduler","tolerations":[{"key":"node.kubernetes.io/not-ready","operator":"Exists","effect":"NoExecute","tolerationSeconds":300},{"key":"node.kubernetes.io/unreachable","operator":"Exists","effect":"NoExecute","tolerationSeconds":300}]},"status":{"phase":"Running","conditions":[{"type":"Initialized","status":"True","lastProbeTime":null,"lastTransitionTime":"2018-07-24T10:06:50Z"},{"type":"Ready","status":"True","lastProbeTime":null,"lastTransitionTime":"2018-07-24T10:06:54Z"},{"type":"PodScheduled","status":"True","lastProbeTime":null,"lastTransitionTime":"2018-07-24T10:06:50Z"}],"hostIP":"34.220.18.140","podIP":"10.42.0.7","startTime":"2018-07-24T10:06:50Z","containerStatuses":[{"name":"hello-world","state":{"running":{"startedAt":"2018-07-24T10:06:54Z"}},"lastState":{},"ready":true,"restartCount":0,"image":"rancher/hello-world:latest","imageID":"docker-pullable://rancher/hello-world@sha256:4b1559cb4b57ca36fa2b313a3c7dde774801aa3a2047930d94e11a45168bc053","containerID":"docker://cce4df5fc0408f03d4adf82c90de222f64c302bf7a04be1c82d584ec31530773"}],"qosClass":"Burstable"}}]} + I0724 10:18:45.699525 1 api.go:74] GET http://prometheus-server.prometheus.34.220.18.140.xip.io/api/v1/query?query=sum%28rate%28container_fs_read_seconds_total%7Bpod_name%3D%22hello-world-54764dfbf8-q6l82%22%2Ccontainer_name%21%3D%22POD%22%2Cnamespace%3D%22default%22%7D%5B5m%5D%29%29+by+%28pod_name%29&time=1532427525.697 200 OK + I0724 10:18:45.699620 1 api.go:93] Response Body: {"status":"success","data":{"resultType":"vector","result":[{"metric":{"pod_name":"hello-world-54764dfbf8-q6l82"},"value":[1532427525.697,"0"]}]}} + I0724 10:18:45.699939 1 wrap.go:42] GET /apis/custom.metrics.k8s.io/v1beta1/namespaces/default/pods/%2A/fs_read?labelSelector=app%3Dhello-world: (12.431262ms) 200 [[kube-controller-manager/v1.10.1 (linux/amd64) kubernetes/d4ab475/system:serviceaccount:kube-system:horizontal-pod-autoscaler] 10.42.0.0:24268] + I0724 10:18:51.727845 1 request.go:836] Request Body: {"kind":"SubjectAccessReview","apiVersion":"authorization.k8s.io/v1beta1","metadata":{"creationTimestamp":null},"spec":{"nonResourceAttributes":{"path":"/","verb":"get"},"user":"system:anonymous","group":["system:unauthenticated"]},"status":{"allowed":false}} + ... +
+ + + +1. 检查是否可以从 kubectl 访问 metrics API。 + + - 如果你直接访问集群，请在 kubectl 配置中输入你的服务器 URL，格式是 `https://:6443`： + ``` + # kubectl get --raw /apis/custom.metrics.k8s.io/v1beta1 + ``` + 如果 API 可访问，你应该会看到类似以下内容的输出： + +
+ API 响应 + + {"kind":"APIResourceList","apiVersion":"v1","groupVersion":"custom.metrics.k8s.io/v1beta1","resources":[{"name":"pods/fs_usage_bytes","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/memory_rss","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/spec_cpu_period","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/cpu_cfs_throttled","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_io_time","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_read","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_sector_writes","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/cpu_user","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/last_seen","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/tasks_state","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/spec_cpu_quota","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/start_time_seconds","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_limit_bytes","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_write","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/memory_cache","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/memory_usage_bytes","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/cpu_cfs_periods","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/cpu_cfs_throttled_periods","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_reads_merged","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/memory_working_set_bytes","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/network_udp_usage","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_inodes_free","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_inodes","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_io_time_weighted","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/memory_failures","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/memory_swap","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/spec_cpu_shares","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/spec_memory_swap_limit_bytes","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/cpu_usage","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_io_current","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_writes","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/memory_failcnt","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_reads","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_writes_bytes","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_writes_merged","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/network_tcp_usage","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/memory_max_usage_bytes","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/spec_memory_limit_bytes","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/spec_memory_reservation_limit_bytes","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/cpu_load_average_10s","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/cpu_system","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_reads_bytes","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_sector_reads","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]}]} +
+ + - 如果你通过 Rancher 访问集群，请在 kubectl 配置中输入你的服务器 URL，格式是 `https:///k8s/clusters/`。将 `/k8s/clusters/` 后缀添加到 API 路径： + ``` + # kubectl get --raw /k8s/clusters//apis/custom.metrics.k8s.io/v1beta1 + ``` + 如果 API 可访问，你应该会看到类似以下内容的输出： + +
+ API 响应 + + {"kind":"APIResourceList","apiVersion":"v1","groupVersion":"custom.metrics.k8s.io/v1beta1","resources":[{"name":"pods/fs_usage_bytes","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/memory_rss","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/spec_cpu_period","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/cpu_cfs_throttled","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_io_time","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_read","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_sector_writes","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/cpu_user","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/last_seen","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/tasks_state","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/spec_cpu_quota","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/start_time_seconds","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_limit_bytes","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_write","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/memory_cache","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/memory_usage_bytes","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/cpu_cfs_periods","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/cpu_cfs_throttled_periods","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_reads_merged","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/memory_working_set_bytes","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/network_udp_usage","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_inodes_free","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_inodes","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_io_time_weighted","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/memory_failures","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/memory_swap","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/spec_cpu_shares","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/spec_memory_swap_limit_bytes","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/cpu_usage","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_io_current","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_writes","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/memory_failcnt","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_reads","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_writes_bytes","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_writes_merged","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/network_tcp_usage","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/memory_max_usage_bytes","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/spec_memory_limit_bytes","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/spec_memory_reservation_limit_bytes","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/cpu_load_average_10s","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/cpu_system","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_reads_bytes","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_sector_reads","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]}]} +
diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/kubernetes-resources-setup/horizontal-pod-autoscaler/manage-hpas-with-ui.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/kubernetes-resources-setup/horizontal-pod-autoscaler/manage-hpas-with-ui.md new file mode 100644 index 00000000000..42fbec1785a --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/kubernetes-resources-setup/horizontal-pod-autoscaler/manage-hpas-with-ui.md @@ -0,0 +1,51 @@ +--- +title: 使用 Rancher UI 管理 HPA +--- + +Rancher UI 支持创建、管理和删除 HPA。你可以将 CPU 或内存使用情况配置为用于 HPA 扩缩的指标。 + +如果你想使用 CPU/内存之外的其他指标创建 HPA，请参阅[配置 HPA 以使用 Prometheus 的自定义指标进行扩缩](./manage-hpas-with-kubectl.md#配置-hpa-以使用-prometheus-自定义指标进行扩缩)。 + +## 创建 HPA + +1. 在左上角，单击 **☰ > 集群管理**。 +1. 转到要创建 HPA 的集群，然后单击 **Explore**。 +1. 在左侧导航栏中，单击**服务发现 > Horizo​​ntalPodAutoscalers**。 +1. 单击**创建**。 +1. 为 HPA 选择 **命名空间**。 +1. 输入 HPA 的**名称**。 +1. 选择**目标引用**作为 HPA 的扩缩目标。 +1. 为 HPA 指定**最小副本数**和**最大副本数**。 +1. 配置 HPA 的指标。你可以将内存或 CPU 使用率作为让 HPA 扩缩服务的指标。在**数量**字段中，输入让 HPA 扩缩服务的工作负载内存/CPU 使用率的百分比。要配置其他 HPA 指标，包括 Prometheus 提供的指标，你需要[使用 kubectl 管理 HPA](./manage-hpas-with-kubectl.md#配置-hpa-以使用-prometheus-自定义指标进行扩缩)。 + +1. 单击**创建**以创建HPA。 + +:::note 结果： + +HPA 已被部署到选定的命名空间。你可以在项目的**资源 > HPA** 视图中查看 HPA 的状态。 + +::: + +## 获取 HPA 指标和状态 + +1. 在左上角，单击 **☰ > 集群管理**。 +1. 转到具有 HPA 的集群并单击 **Explore**。 +1. 在左侧导航栏中，单击**服务发现 > Horizo​​ntalPodAutoscalers**。**Horizo​​ntalPodAutoscalers** 页面显示当前副本的数量。 + +有关特定 HPA 的更详细指标和状态，请单击 HPA 的名称。你会转到 HPA 的详情页面。 + + +## 删除 HPA + +1. 在左上角，单击 **☰ > 集群管理**。 +1. 转到要删除的 HPA 的集群，然后单击 **Explore**。 +1. 在左侧导航栏中，单击**服务发现 > Horizo​​ntalPodAutoscalers**。 +1. 单击**资源 > HPA**。 +1. 找到要删除的 HPA，然后单击 **⋮ > 删除**。 +1. 单击**删除**以进行确认。 + +:::note 结果： + +HPA 已从当前集群中删除。 + +::: \ No newline at end of file diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/kubernetes-resources-setup/horizontal-pod-autoscaler/test-hpas-with-kubectl.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/kubernetes-resources-setup/horizontal-pod-autoscaler/test-hpas-with-kubectl.md new file mode 100644 index 00000000000..d48c98b3e8c --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/kubernetes-resources-setup/horizontal-pod-autoscaler/test-hpas-with-kubectl.md @@ -0,0 +1,531 @@ +--- +title: 使用 kubectl 测试 HPA +--- + +本文介绍如何在使用负载测试工具扩缩 HPA 后检查 HPA 的状态。有关使用 Rancher UI（最低版本 2.3.x）检查状态的信息，请参阅[使用 Rancher UI 管理 HPA](./manage-hpas-with-kubectl.md)。 + +要让 HPA 正常工作，服务部署应该具有容器的资源请求定义。按照以下 hello-world 示例测试 HPA 是否正常工作。 + +1. 将 `kubectl` 连接到你的 Kubernetes 集群。 + +1. 复制下方的 `hello-world` 部署清单。 + +
+ Hello World 清单 + + ``` + apiVersion: apps/v1beta2 + kind: Deployment + metadata: + labels: + app: hello-world + name: hello-world + namespace: default + spec: + replicas: 1 + selector: + matchLabels: + app: hello-world + strategy: + rollingUpdate: + maxSurge: 1 + maxUnavailable: 0 + type: RollingUpdate + template: + metadata: + labels: + app: hello-world + spec: + containers: + - image: rancher/hello-world + imagePullPolicy: Always + name: hello-world + resources: + requests: + cpu: 500m + memory: 64Mi + ports: + - containerPort: 80 + protocol: TCP + restartPolicy: Always + --- + apiVersion: v1 + kind: Service + metadata: + name: hello-world + namespace: default + spec: + ports: + - port: 80 + protocol: TCP + targetPort: 80 + selector: + app: hello-world + ``` + +
+ +1. 将其部署到你的集群。 + + ``` + # kubectl create -f + ``` + +1. 根据你使用的指标类型复制以下其中一个 HPA： + +
+ Hello World HPA：资源指标 + + ``` + apiVersion: autoscaling/v2beta1 + kind: HorizontalPodAutoscaler + metadata: + name: hello-world + namespace: default + spec: + scaleTargetRef: + apiVersion: extensions/v1beta1 + kind: Deployment + name: hello-world + minReplicas: 1 + maxReplicas: 10 + metrics: + - type: Resource + resource: + name: cpu + targetAverageUtilization: 50 + - type: Resource + resource: + name: memory + targetAverageValue: 1000Mi + ``` + +
+
+ Hello World HPA：自定义指标 + + ``` + apiVersion: autoscaling/v2beta1 + kind: HorizontalPodAutoscaler + metadata: + name: hello-world + namespace: default + spec: + scaleTargetRef: + apiVersion: extensions/v1beta1 + kind: Deployment + name: hello-world + minReplicas: 1 + maxReplicas: 10 + metrics: + - type: Resource + resource: + name: cpu + targetAverageUtilization: 50 + - type: Resource + resource: + name: memory + targetAverageValue: 100Mi + - type: Pods + pods: + metricName: cpu_system + targetAverageValue: 20m + ``` + +
+ +1. 查看 HPA 信息和描述。确认显示的指标数据。 + +
+ 资源指标 + + 1. 输入以下命令： + ``` + # kubectl get hpa + NAME REFERENCE TARGETS MINPODS MAXPODS REPLICAS AGE + hello-world Deployment/hello-world 1253376 / 100Mi, 0% / 50% 1 10 1 6m + # kubectl describe hpa + Name: hello-world + Namespace: default + Labels: + Annotations: + CreationTimestamp: Mon, 23 Jul 2018 20:21:16 +0200 + Reference: Deployment/hello-world + Metrics: ( current / target ) + resource memory on pods: 1253376 / 100Mi + resource cpu on pods (as a percentage of request): 0% (0) / 50% + Min replicas: 1 + Max replicas: 10 + Conditions: + Type Status Reason Message + ---- ------ ------ ------- + AbleToScale True ReadyForNewScale the last scale time was sufficiently old as to warrant a new scale + ScalingActive True ValidMetricFound the HPA was able to successfully calculate a replica count from memory resource + ScalingLimited False DesiredWithinRange the desired count is within the acceptable range + Events: + ``` + +
+
+ 自定义指标 + + 1. 输入以下命令： + ``` + # kubectl describe hpa + ``` + 你应该会看到类似以下的输出： + ``` + Name: hello-world + Namespace: default + Labels: + Annotations: + CreationTimestamp: Tue, 24 Jul 2018 18:36:28 +0200 + Reference: Deployment/hello-world + Metrics: ( current / target ) + resource memory on pods: 3514368 / 100Mi + "cpu_system" on pods: 0 / 20m + resource cpu on pods (as a percentage of request): 0% (0) / 50% + Min replicas: 1 + Max replicas: 10 + Conditions: + Type Status Reason Message + ---- ------ ------ ------- + AbleToScale True ReadyForNewScale the last scale time was sufficiently old as to warrant a new scale + ScalingActive True ValidMetricFound the HPA was able to successfully calculate a replica count from memory resource + ScalingLimited False DesiredWithinRange the desired count is within the acceptable range + Events: + ``` + +
+ +1. 为服务生成负载，从而测试你的 pod 是否按预期进行了自动扩缩。你可以使用任何负载测试工具（Hey、Gatling 等），我们使用的是 [Hey](https://github.com/rakyll/hey)。 + +1. 测试 pod 自动扩缩是否按预期工作。

+ **使用资源指标测试自动扩缩：** + +
+ 扩展到两个 Pod：CPU 用量达到目标 + + 使用你的负载测试工具根据 CPU 使用情况扩展到两个 Pod。 + + 1. 查看你的 HPA。 + ``` + # kubectl describe hpa + ``` + 你应该会看到类似以下的输出： + ``` + Name: hello-world + Namespace: default + Labels: + Annotations: + CreationTimestamp: Mon, 23 Jul 2018 22:22:04 +0200 + Reference: Deployment/hello-world + Metrics: ( current / target ) + resource memory on pods: 10928128 / 100Mi + resource cpu on pods (as a percentage of request): 56% (280m) / 50% + Min replicas: 1 + Max replicas: 10 + Conditions: + Type Status Reason Message + ---- ------ ------ ------- + AbleToScale True SucceededRescale the HPA controller was able to update the target scale to 2 + ScalingActive True ValidMetricFound the HPA was able to successfully calculate a replica count from cpu resource utilization (percentage of request) + ScalingLimited False DesiredWithinRange the desired count is within the acceptable range + Events: + Type Reason Age From Message + ---- ------ ---- ---- ------- + Normal SuccessfulRescale 13s horizontal-pod-autoscaler New size: 2; reason: cpu resource utilization (percentage of request) above target + ``` + 1. 输入以下命令，确认你已扩展到两个 pod： + ``` + # kubectl get pods + ``` + 你应该会看到类似以下的输出： + ``` + NAME READY STATUS RESTARTS AGE + hello-world-54764dfbf8-k8ph2 1/1 Running 0 1m + hello-world-54764dfbf8-q6l4v 1/1 Running 0 3h + ``` + +
+
+ 扩展到三个 Pod：CPU 用量达到目标 + + 使用你的负载测试工具根据 CPU 用量扩展到三个 Pod，并将 `horizo​​ntal-pod-autoscaler-upscale-delay` 设置为 3 分钟。 + + 1. 输入以下命令： + ``` + # kubectl describe hpa + ``` + 你应该会看到类似以下的输出： + ``` + Name: hello-world + Namespace: default + Labels: + Annotations: + CreationTimestamp: Mon, 23 Jul 2018 22:22:04 +0200 + Reference: Deployment/hello-world + Metrics: ( current / target ) + resource memory on pods: 9424896 / 100Mi + resource cpu on pods (as a percentage of request): 66% (333m) / 50% + Min replicas: 1 + Max replicas: 10 + Conditions: + Type Status Reason Message + ---- ------ ------ ------- + AbleToScale True SucceededRescale the HPA controller was able to update the target scale to 3 + ScalingActive True ValidMetricFound the HPA was able to successfully calculate a replica count from cpu resource utilization (percentage of request) + ScalingLimited False DesiredWithinRange the desired count is within the acceptable range + Events: + Type Reason Age From Message + ---- ------ ---- ---- ------- + Normal SuccessfulRescale 4m horizontal-pod-autoscaler New size: 2; reason: cpu resource utilization (percentage of request) above target + Normal SuccessfulRescale 16s horizontal-pod-autoscaler New size: 3; reason: cpu resource utilization (percentage of request) above target + ``` + 2. 输入以下命令，确认三个 pod 正在运行： + ``` + # kubectl get pods + ``` + 你应该会看到类似以下的输出： + ``` + NAME READY STATUS RESTARTS AGE + hello-world-54764dfbf8-f46kh 0/1 Running 0 1m + hello-world-54764dfbf8-k8ph2 1/1 Running 0 5m + hello-world-54764dfbf8-q6l4v 1/1 Running 0 3h + ``` + +
+
+ 缩减到 1 个 Pod：所有指标均低于目标 + + 当 `horizontal-pod-autoscaler-downscale-delay` 的所有指标均低于目标（默认为 5 分钟）时，使用你的负载测试工具缩减到 1 个 pod。 + + 1. 输入以下命令： + ``` + # kubectl describe hpa + ``` + 你应该会看到类似以下的输出： + ``` + Name: hello-world + Namespace: default + Labels: + Annotations: + CreationTimestamp: Mon, 23 Jul 2018 22:22:04 +0200 + Reference: Deployment/hello-world + Metrics: ( current / target ) + resource memory on pods: 10070016 / 100Mi + resource cpu on pods (as a percentage of request): 0% (0) / 50% + Min replicas: 1 + Max replicas: 10 + Conditions: + Type Status Reason Message + ---- ------ ------ ------- + AbleToScale True SucceededRescale the HPA controller was able to update the target scale to 1 + ScalingActive True ValidMetricFound the HPA was able to successfully calculate a replica count from memory resource + ScalingLimited False DesiredWithinRange the desired count is within the acceptable range + Events: + Type Reason Age From Message + ---- ------ ---- ---- ------- + Normal SuccessfulRescale 10m horizontal-pod-autoscaler New size: 2; reason: cpu resource utilization (percentage of request) above target + Normal SuccessfulRescale 6m horizontal-pod-autoscaler New size: 3; reason: cpu resource utilization (percentage of request) above target + Normal SuccessfulRescale 1s horizontal-pod-autoscaler New size: 1; reason: All metrics below target + ``` + +
+ + **使用自定义指标测试自动缩放：** + +
+ 扩展到两个 Pod：CPU 用量达到目标 + + 使用负载测试工具根据 CPU 用量扩展到两个 Pod。 + + 1. 输入以下命令： + ``` + # kubectl describe hpa + ``` + 你应该会看到类似以下的输出： + ``` + Name: hello-world + Namespace: default + Labels: + Annotations: + CreationTimestamp: Tue, 24 Jul 2018 18:01:11 +0200 + Reference: Deployment/hello-world + Metrics: ( current / target ) + resource memory on pods: 8159232 / 100Mi + "cpu_system" on pods: 7m / 20m + resource cpu on pods (as a percentage of request): 64% (321m) / 50% + Min replicas: 1 + Max replicas: 10 + Conditions: + Type Status Reason Message + ---- ------ ------ ------- + AbleToScale True SucceededRescale the HPA controller was able to update the target scale to 2 + ScalingActive True ValidMetricFound the HPA was able to successfully calculate a replica count from cpu resource utilization (percentage of request) + ScalingLimited False DesiredWithinRange the desired count is within the acceptable range + Events: + Type Reason Age From Message + ---- ------ ---- ---- ------- + Normal SuccessfulRescale 16s horizontal-pod-autoscaler New size: 2; reason: cpu resource utilization (percentage of request) above target + ``` + 1. 输入以下命令，确认两个 pod 正在运行： + ``` + # kubectl get pods + ``` + 你应该会看到类似以下的输出： + ``` + NAME READY STATUS RESTARTS AGE + hello-world-54764dfbf8-5pfdr 1/1 Running 0 3s + hello-world-54764dfbf8-q6l82 1/1 Running 0 6h + ``` + +
+
+ 扩展到三个 Pod：CPU 用量达到目标 + + 当 cpu_system 用量达到目标时，使用你的负载测试工具扩展到三个 Pod。 + + 1. 输入以下命令： + ``` + # kubectl describe hpa + ``` + 你应该会看到类似以下的输出： + ``` + Name: hello-world + Namespace: default + Labels: + Annotations: + CreationTimestamp: Tue, 24 Jul 2018 18:01:11 +0200 + Reference: Deployment/hello-world + Metrics: ( current / target ) + resource memory on pods: 8374272 / 100Mi + "cpu_system" on pods: 27m / 20m + resource cpu on pods (as a percentage of request): 71% (357m) / 50% + Min replicas: 1 + Max replicas: 10 + Conditions: + Type Status Reason Message + ---- ------ ------ ------- + AbleToScale True SucceededRescale the HPA controller was able to update the target scale to 3 + ScalingActive True ValidMetricFound the HPA was able to successfully calculate a replica count from cpu resource utilization (percentage of request) + ScalingLimited False DesiredWithinRange the desired count is within the acceptable range + Events: + Type Reason Age From Message + ---- ------ ---- ---- ------- + Normal SuccessfulRescale 3m horizontal-pod-autoscaler New size: 2; reason: cpu resource utilization (percentage of request) above target + Normal SuccessfulRescale 3s horizontal-pod-autoscaler New size: 3; reason: pods metric cpu_system above target + ``` + 1. 输入以下命令，确认三个 pod 正在运行： + ``` + # kubectl get pods + ``` + 你应该会看到类似以下的输出： + ``` + # kubectl get pods + NAME READY STATUS RESTARTS AGE + hello-world-54764dfbf8-5pfdr 1/1 Running 0 3m + hello-world-54764dfbf8-m2hrl 1/1 Running 0 1s + hello-world-54764dfbf8-q6l82 1/1 Running 0 6h + ``` + +
+
+ 扩展到四个 Pod：CPU 用量达到目标 + + 使用负载测试工具根据 CPU 用量扩展到四个 Pod。`horizontal-pod-autoscaler-upscale-delay` 默认设置为 3 分钟。 + + 1. 输入以下命令： + ``` + # kubectl describe hpa + ``` + 你应该会看到类似以下的输出： + ``` + Name: hello-world + Namespace: default + Labels: + Annotations: + CreationTimestamp: Tue, 24 Jul 2018 18:01:11 +0200 + Reference: Deployment/hello-world + Metrics: ( current / target ) + resource memory on pods: 8374272 / 100Mi + "cpu_system" on pods: 27m / 20m + resource cpu on pods (as a percentage of request): 71% (357m) / 50% + Min replicas: 1 + Max replicas: 10 + Conditions: + Type Status Reason Message + ---- ------ ------ ------- + AbleToScale True SucceededRescale the HPA controller was able to update the target scale to 3 + ScalingActive True ValidMetricFound the HPA was able to successfully calculate a replica count from cpu resource utilization (percentage of request) + ScalingLimited False DesiredWithinRange the desired count is within the acceptable range + Events: + Type Reason Age From Message + ---- ------ ---- ---- ------- + Normal SuccessfulRescale 5m horizontal-pod-autoscaler New size: 2; reason: cpu resource utilization (percentage of request) above target + Normal SuccessfulRescale 3m horizontal-pod-autoscaler New size: 3; reason: pods metric cpu_system above target + Normal SuccessfulRescale 4s horizontal-pod-autoscaler New size: 4; reason: cpu resource utilization (percentage of request) above target + ``` + + 1. 输入以下命令，确认四个 pod 正在运行： + ``` + # kubectl get pods + ``` + 你应该会看到类似以下的输出： + ``` + NAME READY STATUS RESTARTS AGE + hello-world-54764dfbf8-2p9xb 1/1 Running 0 5m + hello-world-54764dfbf8-5pfdr 1/1 Running 0 2m + hello-world-54764dfbf8-m2hrl 1/1 Running 0 1s + hello-world-54764dfbf8-q6l82 1/1 Running 0 6h + ``` + +
+
+ 缩减到 1 个 Pod：所有指标均低于目标 + + 当 `horizontal-pod-autoscaler-downscale-delay` 的所有指标均低于目标时，使用你的负载测试工具缩减到 1 个 pod。 + + 1. 输入以下命令： + ``` + # kubectl describe hpa + ``` + 你应该会看到类似以下的输出： + ``` + Name: hello-world + Namespace: default + Labels: + Annotations: + CreationTimestamp: Tue, 24 Jul 2018 18:01:11 +0200 + Reference: Deployment/hello-world + Metrics: ( current / target ) + resource memory on pods: 8101888 / 100Mi + "cpu_system" on pods: 8m / 20m + resource cpu on pods (as a percentage of request): 0% (0) / 50% + Min replicas: 1 + Max replicas: 10 + Conditions: + Type Status Reason Message + ---- ------ ------ ------- + AbleToScale True SucceededRescale the HPA controller was able to update the target scale to 1 + ScalingActive True ValidMetricFound the HPA was able to successfully calculate a replica count from memory resource + ScalingLimited False DesiredWithinRange the desired count is within the acceptable range + Events: + Type Reason Age From Message + ---- ------ ---- ---- ------- + Normal SuccessfulRescale 10m horizontal-pod-autoscaler New size: 2; reason: cpu resource utilization (percentage of request) above target + Normal SuccessfulRescale 8m horizontal-pod-autoscaler New size: 3; reason: pods metric cpu_system above target + Normal SuccessfulRescale 5m horizontal-pod-autoscaler New size: 4; reason: cpu resource utilization (percentage of request) above target + Normal SuccessfulRescale 13s horizontal-pod-autoscaler New size: 1; reason: All metrics below target + ``` + 1. 输入以下命令，确认单个 pod 正在运行： + ``` + # kubectl get pods + ``` + 你应该会看到类似以下的输出： + ``` + NAME READY STATUS RESTARTS AGE + hello-world-54764dfbf8-q6l82 1/1 Running 0 6h + ``` + +
diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/kubernetes-resources-setup/kubernetes-and-docker-registries.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/kubernetes-resources-setup/kubernetes-and-docker-registries.md new file mode 100644 index 00000000000..6231ec1697a --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/kubernetes-resources-setup/kubernetes-and-docker-registries.md @@ -0,0 +1,178 @@ +--- +title: Kubernetes 镜像仓库和容器镜像仓库 +description: 了解容器镜像仓库和 Kubernetes 镜像仓库、它们的用例以及如何在 Rancher UI 中使用私有镜像仓库 +--- + +镜像仓库是 Kubernetes 密文（Secret），包含用于向[私有容器镜像仓库](https://kubernetes.io/docs/tasks/configure-pod-container/pull-image-private-registry/)进行身份验证的凭证。 + +“Registry” 这个词可能有两种意思，可指代容器或 Kubernetes 镜像仓库： + +- **容器镜像仓库**（以前称为“Docker 镜像仓库”）包含你可以拉取和部署的容器镜像。镜像仓库是一个无状态、可扩展的服务器端应用程序，用于存储和分发容器镜像。 +- **Kubernetes 镜像仓库**是一个镜像拉取密文，你的 deployment 使用该密文来向容器镜像仓库进行身份验证。 + +Deployment 使用 Kubernetes 镜像仓库密文向私有容器镜像仓库进行身份验证，然后拉取托管在仓库上的容器镜像。 + +目前，只有在 Rancher UI 中创建工作负载时（通过 kubectl 创建的工作负载不可以），Deployment 才会自动拉取私有镜像仓库凭证。 + +## 在命名空间中创建镜像仓库 + +:::note 先决条件： + +你必须已经部署了一个可用的私有镜像仓库。 + +如果你需要创建私有镜像仓库，请参阅相应运行时的文档： + +* [Containerd](https://github.com/containerd/containerd/blob/main/docs/cri/config.md#registry-configuration). + * [Nerdctl 命令和镜像仓库托管服务](https://github.com/containerd/nerdctl/blob/main/docs/registry.md) +* [Docker](https://docs.docker.com/registry/deploying/). + +::: + +1. 在左上角，单击 **☰ > 集群管理**。 +1. 转到要添加镜像仓库的集群，然后单击 **Explore**。 +1. 在左侧导航中，单击**存储 > 密文**或**更多资源 > 核心 > 密文**。 +1. 单击**创建**。 +1. 单击**镜像仓库**。 +1. 输入镜像仓库的**名称**。 + + :::note + + Kubernetes 将密文、证书和镜像仓库都归类为[密文](https://kubernetes.io/docs/concepts/configuration/secret/)，命名空间或项目中的密文名称不能重复。因此，为了避免冲突，镜像仓库的名称必须与工作空间中的其他密文不一样。 + + ::: + +1. 为镜像仓库选择一个命名空间。 +1. 选择托管你的私人镜像仓库的网站。然后，输入向镜像仓库进行身份验证的凭证。例如，如果你使用 DockerHub，请提供你的 DockerHub 用户名和密码。 +1. 单击**保存**。 + +**结果**： + +- 已将你的密文添加到命名空间中。 +- 你可以通过单击**存储 > 密文**或**更多资源 > 核心 > 密文**在 Rancher UI 中查看密文。 +- 如果工作负载在镜像仓库的范围内，你在 Rancher UI 中创建的任何工作负载都将具有访问镜像仓库的凭证。 + +## 在项目中创建镜像仓库 + +:::note 先决条件： + +你必须已经部署了一个可用的私有镜像仓库。 + +如果你需要创建私有镜像仓库，请参阅相应运行时的文档： + +* [Containerd](https://github.com/containerd/containerd/blob/main/docs/cri/config.md#registry-configuration). + * [Nerdctl 命令和镜像仓库托管服务](https://github.com/containerd/nerdctl/blob/main/docs/registry.md) +* [Docker](https://docs.docker.com/registry/deploying/). + +::: + +在 Rancher 2.6 之前，密文必须创建在项目级别。现在不再需要项目级别，你可以采用命名空间级别。因此，Rancher UI 进行了更新以反映这一新功能。但是，你仍然可以按照需要创建项目级别的镜像仓库。执行以下步骤进行操作： + +1. 在左上角，单击下拉菜单中的 **☰ > 全局设置**。 +1. 单击**功能开关**。 +1. 转到 `Legacy` 功能开关并单击**激活**。 +1. 在左上角，单击 **☰ > 集群管理**。 +1. 转到要添加镜像仓库的集群，然后单击 **Explore**。 +1. 在左侧导航中，单击**存储 > 密文**或**更多资源 > 核心 > 密文**。 +1. 单击**创建**。 +1. 单击**镜像仓库**。 +1. 在顶部导航栏中进行过滤，从而仅查看一个项目。 +1. 输入镜像仓库的**名称**。 + + :::note + + Kubernetes 将密文、证书和镜像仓库都归类为[密文](https://kubernetes.io/docs/concepts/configuration/secret/)，命名空间或项目中的密文名称不能重复。因此，为了避免冲突，镜像仓库的名称必须与工作空间中的其他密文不一样。 + + ::: + +1. 为镜像仓库选择一个命名空间。 +1. 选择托管你的私人镜像仓库的网站。然后，输入向镜像仓库进行身份验证的凭证。例如，如果你使用 DockerHub，请提供你的 DockerHub 用户名和密码。 +1. 单击**保存**。 + +**结果**： + +- 密文已添加到你选择的项目中。 +- 你可以通过单击**存储 > 密文**或**更多资源 > 核心 > 密文**在 Rancher UI 中查看密文。 +- 如果工作负载在镜像仓库的范围内，你在 Rancher UI 中创建的任何工作负载都将具有访问镜像仓库的凭证。 + +:::note + +local 集群上的项目级别镜像仓库仅在选择单个项目时可见。 + +::: + +## 使用私有镜像仓库 + +你可以通过 Rancher UI 或 `kubectl` 使用私有镜像仓库的镜像来部署工作负载。 + +### 在 Rancher UI 中使用私有镜像仓库 + +要使用私有镜像仓库中的镜像来部署工作负载： + +1. 在左上角，单击 **☰ > 集群管理**。 +1. 转到要部署工作负载的集群，然后单击 **Explore**。 +1. 点击**工作负载**。 +1. 单击**创建**。 +1. 选择要创建的工作负载类型。 +1. 输入工作负载的独特名称，并选择命名空间。 +1. 在**容器镜像**字段中，输入私有镜像仓库中镜像的路径 URL。例如，如果你的私有镜像仓库位于 Quay.io，你可以使用 `quay.io//`。 +1. 单击**创建**。 + +**结果**：你的 deployment 能启动，能使用你在 Rancher UI 中添加的私有镜像仓库凭证进行身份验证，并拉取指定的容器镜像。 + +### 通过 kubectl 使用私有镜像仓库 + +使用 `kubectl`创建工作负载时，你需要配置 pod，从而使其 YAML 具有私有镜像仓库中镜像的路径。如果 Pod 是在 Rancher UI 中创建的，它只会自动获取对私有镜像仓库凭证的访问权限，因此你还必须创建和引用镜像仓库密文。 + +密文必须创建在部署工作负载的同一命名空间中。 + +下面是一个示例 `pod.yml`，它用于使用私有镜像仓库的镜像的工作负载。在此示例中，pod 使用来自 Quay.io 的镜像，而且 .yml 指定了镜像的路径。pod 使用存储在名为 `testquay` 的 Kubernetes 密文中的凭证来向镜像仓库进行身份验证，该密文在 `name` 字段的 `spec.imagePullSecrets` 中指定： + +```yaml +apiVersion: v1 +kind: Pod +metadata: + name: private-reg +spec: + containers: + - name: private-reg-container + image: quay.io// + imagePullSecrets: + - name: testquay +``` + +在此示例中，名为 `testquay` 的密文位于 Default 命名空间中。 + +你可以通过 `kubectl` 使用私有镜像仓库凭证来创建密文。此命令创建名为 `testquay` 的密文： + +``` +kubectl create secret docker-registry testquay \ + --docker-server=quay.io \ + --docker-username= \ + --docker-password= +``` + +要查看密文是如何存储在 Kubernetes 中的，可以使用以下命令： + +``` +kubectl get secret testquay --output="jsonpath={.data.\.dockerconfigjson}" | base64 --decode +``` + +结果如下所示： + +``` +{"auths":{"quay.io":{"username":"","password":"","auth":"c291bXlhbGo6dGVzdGFiYzEyMw=="}}} +``` + +部署工作负载后，你可以检查镜像是否已拉取成功： + +``` +kubectl get events +``` +结果应如下所示： +``` +14s Normal Scheduled Pod Successfully assigned default/private-reg2 to minikube +11s Normal Pulling Pod pulling image "quay.io//" +10s Normal Pulled Pod Successfully pulled image "quay.io//" +``` + +有关详细信息，请参阅 Kubernetes 文档中的[创建使用你密文的 pod](https://kubernetes.io/docs/tasks/configure-pod-container/pull-image-private-registry/#create-a-pod-that-uses-your-secret)。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/kubernetes-resources-setup/kubernetes-resources-setup.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/kubernetes-resources-setup/kubernetes-resources-setup.md new file mode 100644 index 00000000000..8b80ea3272d --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/kubernetes-resources-setup/kubernetes-resources-setup.md @@ -0,0 +1,67 @@ +--- +title: Kubernetes 资源 +--- + + + + + +你可以在 Rancher UI 中查看和操作 Kubernetes 集群中的所有自定义资源和 CRD。 + +## 工作负载 + +使用[工作负载](workloads-and-pods/workloads-and-pods.md)将应用部署到集群节点，工作负载是包含用于运行应用的 pod 的对象，以及为部署行为设置规则的元数据。工作负载可以部署在集群范围内，也可以部署在一个命名空间内。 + +部署工作负载时，你可以使用任何镜像进行部署。可供选择的[工作负载类型](workloads-and-pods/workloads-and-pods.md#工作负载类型)有多种，工作负载类型决定了你的应用程序的运行方式。 + +在工作负载部署之后，你可以继续使用它。你可以： + +- 将工作负载[升级](workloads-and-pods/upgrade-workloads.md)到它运行的应用的更新版本。 +- 如果升级出现问题，将工作负载[回滚](workloads-and-pods/roll-back-workloads.md)到以前的版本。 +- [添加一个 sidecar](workloads-and-pods/add-a-sidecar.md)，这是一个支持主要工作负载的工作负载。 + +## 负载均衡和 Ingress + +### 负载均衡器 + +启动应用程序后，它仅在集群中可用。无法从外部访问它。 + +如果你希望你的应用程序可以从外部访问，则必须向集群添加负载均衡器。如果用户知道负载均衡器的 IP 地址和应用的端口号，负载均衡器可以为外部连接创建一个访问集群的网关。 + +Rancher 支持两种类型的负载均衡器： + +- [Layer-4 负载均衡器](./load-balancer-and-ingress-controller/layer-4-and-layer-7-load-balancing.md#四层负载均衡器) +- [Layer-7 负载均衡器](./load-balancer-and-ingress-controller/layer-4-and-layer-7-load-balancing.md#七层负载均衡器) + +有关详细信息，请参阅[负载均衡器](./load-balancer-and-ingress-controller/layer-4-and-layer-7-load-balancing.md)。 + +#### Ingress + +负载均衡器只能处理每个 service 的一个 IP 地址。换言之，如果你在集群中运行了多个 service，则必须为每个 service 配备一个负载均衡器。运行多个负载均衡器的花费可能非常高昂。因此，你可以使用 Ingress 来解决此问题。 + +Ingress 是一组充当负载均衡器的规则。Ingress 与一个或多个 Ingress Controller 一起动态路由 service 的请求。Ingress 收到请求时，集群中的 Ingress Controller 会对负载均衡器进行配置，从而根据你配置的 service 子域或路径规则将请求定向到正确的 service。 + +有关详细信息，请参阅 [Ingress](load-balancer-and-ingress-controller/add-ingresses.md)。 + +在项目中使用 Ingress 时，你可以通过设置全局 DNS 条目来将 Ingress 主机名编程到外部 DNS。 + +## 服务发现 + +使用负载均衡器和/或 Ingress 将集群公开给外部请求后，你只能通过 IP 地址访问集群。要创建可解析的主机名，你必须创建服务记录，该记录将 IP 地址、外部主机名、DNS 记录别名、工作负载或标记的 pod 映射到特定主机名。 + +有关详细信息，请参阅[服务发现](create-services.md)。 + +## 应用程序 + +除了启动应用程序的各个组件外，你还可以使用 Rancher 应用商店来启动应用，即 Helm Chart。 + +## Kubernetes 资源 + +在 Rancher 项目或命名空间的上下文中，_资源_ 是支持 Pod 操作的文件和数据。在 Rancher 中，证书、镜像仓库和密文都被视为资源。但是，Kubernetes 将资源划分为不同类型的[密文（secret）](https://kubernetes.io/docs/concepts/configuration/secret/)。因此，在单个项目或命名空间中，各个资源必须具有唯一的名称以避免冲突。资源主要用于承载敏感信息，但也有其他用途。 + +资源包括： + +- [证书](encrypt-http-communication.md)：用于加密/解密进入或离开集群的数据的文件。 +- [ConfigMap](configmaps.md)：存储一般配置信息的文件，例如一组配置文件。 +- [密文](secrets.md)：存储密码、token 或密钥等敏感数据的文件。 +- [镜像仓库](kubernetes-and-docker-registries.md)：携带用于验证私有镜像仓库的凭证的文件。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/kubernetes-resources-setup/load-balancer-and-ingress-controller/add-ingresses.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/kubernetes-resources-setup/load-balancer-and-ingress-controller/add-ingresses.md new file mode 100644 index 00000000000..5717ca726a5 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/kubernetes-resources-setup/load-balancer-and-ingress-controller/add-ingresses.md @@ -0,0 +1,18 @@ +--- +title: 添加 Ingress +description: 你可以为工作负载添加 Ingress，从而提供负载均衡、SSL 终止和基于主机/路径的路由。了解如何添加 Rancher Ingress +--- + +你可以为工作负载添加 Ingress，从而提供负载均衡、SSL 终止和基于主机/路径的路由。在项目中使用 Ingress 时，你可以通过设置全局 DNS 条目来将 Ingress 主机名编程到外部 DNS。 + +1. 在左上角，单击 **☰ > 集群管理**。 +1. 转到要添加 Ingress 的集群，然后单击 **Explore**。 +1. 点击**服务发现 > Ingresses**。 +1. 单击**创建**。 +1. 从下拉列表中选择一个现有的**命名空间**。 +1. 输入 Ingress 的**名称**。 +1. [创建](./ingress-configuration.md) Ingress 转发**规则**。如果你的任何 Ingress 规则处理加密端口的请求，请添加证书以加密/解密通信。 +1. **可选**：点击**添加规则**来创建其他 Ingress 规则。例如，在创建 Ingress 规则以引导主机名请求后，你可能想创建一个默认后端来处理 404。 +1. 点击右下角的**创建**。 + +**结果**：已将 Ingress 添加到项目中。Ingress 会开始执行你的 Ingress 规则。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/kubernetes-resources-setup/load-balancer-and-ingress-controller/ingress-configuration.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/kubernetes-resources-setup/load-balancer-and-ingress-controller/ingress-configuration.md new file mode 100644 index 00000000000..3ff047bc108 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/kubernetes-resources-setup/load-balancer-and-ingress-controller/ingress-configuration.md @@ -0,0 +1,41 @@ +--- +title: Ingress 配置 +description: Ingress 配置 +--- + +:::note + +在 Kubernetes v1.21 及更高版本中，NGINX Ingress Controller 不再默认运行在 hostNetwork 中。它改为将 hostPorts 用于端口 80 和端口 443，因此你可以将准入 Webhook 配置为只能通过 ClusterIP 访问。这确保了只能从集群内部访问 webhook。 + +由于 controller 的这一更改，默认 RKE1 配置不再将 `hostNetwork` 设置为 `true`。但是，你必须将 `hostNetwork` 设置为 `true` 才能使基于 TCP 和 UDP 的 Service 正常工作。为此，请[编辑](../../../../reference-guides/cluster-configuration/rancher-server-configuration/rke1-cluster-configuration.md#使用-yaml-编辑集群)集群的 YAML 并按照[官方 RKE1 文档](https://rke.docs.rancher.com/config-options/add-ons/ingress-controllers#configuring-network-options)中的步骤操作。 + +::: + +## 指定要使用的主机名 + +如果使用此选项，Ingress 会将主机名请求路由到你指定的服务或工作负载。 + +1. 指定类型为 `Prefix` 的路径并指定路径，例如 `/`。 +1. 添加一个**目标服务**。 +1. **可选**：如果你想在将请求发送到特定主机名路径时指定工作负载或服务，请为目标添加**路径**。例如，如果你希望将 `www.mysite.com/contact-us` 的请求发送到与 `www.mysite.com` 不同的服务，在**路径**字段中输入 `/contact-us`。通常情况下，你创建的第一条规则不包含路径。 +1. 输入每个目标操作的**端口**号。 + +## 证书 + +:::note + +你必须具有 SSL 证书，Ingress 可使用该证书来加密和解密通信。有关详细信息，请参阅[添加 SSL 证书](../encrypt-http-communication.md)。 + +::: + +1. 要创建 Ingress Controller，单击**证书**选项卡。 +1. 单击**添加证书**。 +1. 从下拉列表中选择一个**证书 - 密文名称**。 +1. 使用加密通信进入主机。 +1. 要添加使用证书的其他主机，请单击**添加主机**。 + +## 标签和注释 + +添加[标签](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/)和/或[注释](https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations/)来为你的 Ingress Controller 提供元数据。 + +有关可用的注释列表，请参阅 [Nginx Ingress Controller 文档](https://kubernetes.github.io/ingress-nginx/user-guide/nginx-configuration/annotations/)。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/kubernetes-resources-setup/load-balancer-and-ingress-controller/layer-4-and-layer-7-load-balancing.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/kubernetes-resources-setup/load-balancer-and-ingress-controller/layer-4-and-layer-7-load-balancing.md new file mode 100644 index 00000000000..c13f8dbf75e --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/kubernetes-resources-setup/load-balancer-and-ingress-controller/layer-4-and-layer-7-load-balancing.md @@ -0,0 +1,68 @@ +--- +title: "四层和七层负载均衡" +description: "Kubernetes 支持四层负载均衡和七层负载均衡。了解对不同 deployment 的支持" +--- + +Kubernetes 支持四层负载均衡和七层负载均衡。 + +## 四层负载均衡器 + +四层负载均衡器（或外部负载均衡器）将流量转发到 Nodeport。四层负载均衡器支持转发 HTTP 和 TCP 流量。 + +通常情况下，四层负载均衡器由底层云提供商支持，因此，如果你在裸金属服务器和 vSphere 集群上部署 RKE 集群，则不支持四层负载均衡器。但是，单个[全局管理的 config-map](https://kubernetes.github.io/ingress-nginx/user-guide/exposing-tcp-udp-services/) 可用于在 NGINX 或第三方 Ingress 上公开服务。 + +:::note + +你可以使用非云负载均衡器（例如 [MetalLB](https://metallb.universe.tf/)）来部署集群。但是，该用例比云提供商支持的四层负载均衡器更高级，而且不可以在 Rancher 或 RKE 中配置。 + +::: + +### 四层负载均衡支持 + +不同底层云提供商对四层负载均衡器的支持有所不同： + +| 集群部署 | 四层负载均衡器支持 | +----------------------------------------------|-------------------------------- +| Amazon EKS | 由 AWS 云提供商支持 | +| Google GKE | 由 GCE 云提供商支持 | +| Azure AKS | 由 Azure 云提供商支持 | +| EC2 上的 RKE | 由 AWS 云提供商支持 | +| DigitalOcean 上的 RKE | 受限的 NGINX 或第三方 Ingress\* | +| vSphere 上的 RKE | 受限的 NGINX 或第三方 Ingress\* | +| 自定义主机上的 RKE
（例如裸金属服务器） | 受限的 NGINX 或第三方 Ingress\* | +| 第三方 MetalLB | 受限的 NGINX 或第三方 Ingress\* | + +\* 可以通过单个[全局管理的 config-map](https://kubernetes.github.io/ingress-nginx/user-guide/exposing-tcp-udp-services/) 来公开服务。 + +## 七层负载均衡器 + +七层负载均衡器（或 Ingress Controller）支持基于主机和路径的负载均衡和 SSL 终止。七层负载均衡器仅转发 HTTP 和 HTTPS 流量，因此它们仅侦听端口 80 和 443。亚马逊和谷歌等云提供商支持七层负载均衡器。此外，RKE 集群部署了 Nginx Ingress Controller。 + +### 七层负载均衡支持 + +不同底层云提供商对七层负载均衡器的支持有所不同： + +| 集群部署 | 七层负载均衡器支持 | +----------------------------------------------|-------------------------------- +| Amazon EKS | 由 AWS 云提供商支持 | +| Google GKE | 由 GKE 云提供商支持 | +| Azure AKS | 不支持 | +| EC2 上的 RKE | Nginx Ingress Controller | +| DigitalOcean 上的 RKE | Nginx Ingress Controller | +| vSphere 上的 RKE | Nginx Ingress Controller | +| 自定义主机上的 RKE
（例如裸金属服务器） | Nginx Ingress Controller | + +### 七层负载均衡器中的主机名 + +一些托管在云上的七层负载均衡器（例如 AWS 上的 ALB Ingress Controller）会为 Ingress 规则公开 DNS 地址。你需要（使用 CNAME）将你的域名映射到七层负载均衡器生成的 DNS 地址。 + +其他七层负载均衡器（例如 Google Load Balancer 或 Nginx Ingress Controller）会直接公开一个或多个 IP 地址。Google Load Balancer 提供了一个可路由的 IP 地址。Nginx Ingress Controller 公开了运行 Nginx Ingress Controller 的所有节点的外部 IP。你可以执行以下任一操作： + +1. 配置你自己的 DNS，从而（使用 A 记录）将你的域名映射到七层负载均衡器公开的 IP 地址。 +2. 让 Rancher 为你的 Ingress 规则生成一个 xip.io 主机名。Rancher 将使用你公开的其中一个 IP（假设是 `a.b.c.d`）生成一个主机名（即 `..a.b.c.d.xip.io`）。 + +使用 xip.io 的好处是你可以在创建 Ingress 规则后立即获得一个有效的入口点 URL。此外，如果你设置自己的域名，则需要配置 DNS 服务器并等待 DNS 传播。 + +## 相关链接 + +- [创建外部负载均衡器](https://kubernetes.io/docs/tasks/access-application-cluster/create-external-load-balancer/) diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/kubernetes-resources-setup/load-balancer-and-ingress-controller/load-balancer-and-ingress-controller.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/kubernetes-resources-setup/load-balancer-and-ingress-controller/load-balancer-and-ingress-controller.md new file mode 100644 index 00000000000..00ae5a04894 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/kubernetes-resources-setup/load-balancer-and-ingress-controller/load-balancer-and-ingress-controller.md @@ -0,0 +1,65 @@ +--- +title: 在 Rancher 中设置负载均衡器和 Ingress Controller +description: 了解如何设置负载均衡器和 Ingress Controller 以在 Rancher 中重定向服务请求，并了解负载均衡器的限制 +--- + + + + + +在 Rancher 中，你可以通过设置负载均衡器和 Ingress Controller 来重定向服务请求。 + +## 负载均衡器 + +启动应用程序后，该应用程序仅在集群内可用。你无法从集群外部访问它。 + +如果你希望从外部访问应用程序，则必须向集群添加负载均衡器或 Ingress。如果用户知道负载均衡器的 IP 地址和应用的端口号，负载均衡器可以为外部连接创建一个访问集群的网关。 + +Rancher 支持两种类型的负载均衡器： + +- [Layer-4 负载均衡器](layer-4-and-layer-7-load-balancing.md#四层负载均衡器) +- [Layer-7 负载均衡器](layer-4-and-layer-7-load-balancing.md#七层负载均衡器) + +有关详细信息，请参阅[负载均衡器](layer-4-and-layer-7-load-balancing.md)。 + +### 负载均衡器限制 + +负载均衡器有几个需要注意的限制： + +- 负载均衡器只能处理每个 service 的一个 IP 地址。换言之，如果你在集群中运行了多个 service，则必须为每个 service 配备一个负载均衡器。运行多个负载均衡器的花费可能非常高昂。 + +- 如果你想将负载均衡器与托管的 Kubernetes 集群（即托管在 GKE、EKS 或 AKS 中的集群）一起使用，则负载均衡器必须运行在该云提供商的基础设施上。请根据你配置集群的方式查看负载均衡器的兼容列表： + +- [支持 Layer-4 负载均衡](layer-4-and-layer-7-load-balancing.md#四层负载均衡支持) + +- [支持 Layer-7 负载均衡](layer-4-and-layer-7-load-balancing.md#七层负载均衡支持) + +## Ingress + +如上所述，使用负载均衡器的缺点是： + +- 每个服务负载均衡器只能处理一个 IP 地址。 +- 如果你在集群中运行多个服务，则每个服务都必须配备一个负载均衡器。 +- 为每个服务配备负载均衡器的花费可能非常高昂。 + +相反，如果将某个 Ingress 用作集群的入口点，Ingress 可以更灵活地将流量路由到多个 service。它可以将多个 HTTP 请求映射到 service，而无需为每个 service 提供单独的 IP 地址。 + +因此，如果你需要使用相同的 IP 地址、Layer 7 协议或特权节点端口（80 和 443）来公开多个 service，你可以使用一个 Ingress。 + +Ingress 与一个或多个 Ingress Controller 一起动态路由 service 的请求。Ingress 收到请求时，集群中的 Ingress Controller 会根据你配置的 service 子域或路径规则将请求定向到正确的 service。 + +每个 Kubernetes Ingress 资源都对应一个 `/etc/nginx/sites-available/` 中的文件，其中包含一个配置对特定文件和文件夹的请求的 `server{}` 配置块。 + +Ingress 能为你的集群创建一个入口端口（与负载均衡器类似），可以位于集群的内部或外部。RKE 启动的集群中的 Ingress 和 Ingress Controller 由 [Nginx](https://www.nginx.com/) 提供支持。 + +Ingress 还支持其他功能，例如 SSL 终止、基于名称的虚拟主机等。 + +:::note 在高可用性配置中使用 Rancher： + +请避免将 Ingress 添加到 `local` 集群。Rancher 将 Nginx Ingress Controller 作为 Rancher 管理的 _所有_ 集群的全局入口点，其中包括 `local` 集群。因此，当用户尝试访问应用程序时，Rancher 可能会由于重新加载 Nginx 配置而断开连接。要解决这个问题，我们建议你仅在通过 Rancher 启动的集群中部署应用程序。 + +::: + +- 有关如何在 Rancher 中设置 Ingress 的更多信息，请参阅 [Ingress](add-ingresses.md)。 +- 有关 Ingress 和 Ingress Controller 的完整信息，请参阅 [Kubernetes Ingress 文档](https://kubernetes.io/docs/concepts/services-networking/ingress/)。 +- 在项目中使用 Ingress 时，你可以通过设置全局 DNS 条目来将 Ingress 主机名编程到外部 DNS。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/kubernetes-resources-setup/secrets.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/kubernetes-resources-setup/secrets.md new file mode 100644 index 00000000000..d4618d910e1 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/kubernetes-resources-setup/secrets.md @@ -0,0 +1,78 @@ +--- +title: 密文 +--- + +[密文（secret）](https://kubernetes.io/docs/concepts/configuration/secret/#overview-of-secrets)存储敏感数据，例如密码、令牌或密钥。它们可能包含一个或多个键值对。 + +:::note + +本文介绍密文的概述。有关设置私有镜像仓库的详细信息，请参阅[镜像仓库](kubernetes-and-docker-registries.md)。 + +::: + +配置工作负载时，你能够选择要包含的密文。与 ConfigMap 一样，工作负载可以将密文引用为环境变量或卷挂载。 + +除非作为子路径卷挂载，否则挂载的密文会自动更新。有关如何传播更新的密文，请参阅 [Kubernetes 文档](https://kubernetes.io/docs/concepts/configuration/secret/#mounted-secrets-are-updated-automatically)。 + +## 在命名空间中创建密文 + +1. 在左上角，单击 **☰ > 集群管理**。 +1. 转到要添加密文的集群，然后单击 **Explore**。 +1. 要导航到密文，单击**存储 > 密文**或**更多资源 > 核心 > 密文**。 +1. 单击**创建**。 +1. 选择要创建的密文类型。 +1. 为密文选择一个**命名空间**。 +1. 输入密文的**名称**。 + + :::note + + Kubernetes 将密文、证书和镜像仓库都归类为[密文](https://kubernetes.io/docs/concepts/configuration/secret/)，命名空间中的密文名称不能重复。因此，为了避免冲突，密文的名称必须与工作空间中的其他密文不一样。 + + ::: + +1. 在**数据**中，单击**添加**以添加键值对。你可以根据需要添加任意数量的值。 + + :::tip + + 你可以通过复制和粘贴的方式将多个键值对添加到密文中。 + + ::: + + ![](/img/bulk-key-values.gif) + +1. 单击**保存**。 + +**结果**：密文已添加到你选择的命名空间中。你可以在 Rancher UI 中单击**存储 > 密文**或**更多资源 > 核心 > 密文**来查看密文。 + +除非作为子路径卷挂载，否则挂载的密文会自动更新。有关如何传播更新的密文，请参阅 [Kubernetes 文档](https://kubernetes.io/docs/concepts/configuration/secret/#mounted-secrets-are-updated-automatically)。 + + +## 在项目中创建密文 + +在 Rancher 2.6 之前，密文必须创建在项目级别。现在不再需要项目级别，你可以采用命名空间级别。因此，Rancher UI 进行了更新以反映这一新功能。但是，你仍然可以按照需要创建项目级别的密文。请注意，你必须先启用`旧版`功能开关并查看单个项目。执行以下步骤设置你的项目级别密文： + +1. 在左上角，单击下拉菜单中的 **☰ > 全局设置**。 +1. 单击**功能开关**。 +1. 转到 `Legacy` 功能开关并单击**激活**。 +1. 点击左上角下拉菜单中的 **☰ > 集群管理**。 +1. 转到你创建的集群，然后单击 **Explore**。 +1. 单击 **Legacy > 项目**。 +1. 在顶部导航栏中进行过滤，从而仅查看一个项目。 +1. 在左侧导航栏中，单击**密文**。 +1. 单击**添加密文**。 + +**结果**：密文已添加到你选择的项目中。你可以在 Rancher UI 中单击**存储 > 密文**或**更多资源 > 核心 > 密文**来查看密文。 + +由于项目范围的 Secret 是在项目级别设置的，因此在命名空间级别所做的任何更改都将被覆盖。 + +:::note + +local 集群上的项目级别密文仅在选择单个项目时可见。 + +::: + +## 后续操作 + +现在你已将密文添加到命名空间，你可以将其添加到你部署的工作负载中。 + +有关将密文添加到工作负载的更多信息，请参阅[部署工作负载](workloads-and-pods/deploy-workloads.md)。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/kubernetes-resources-setup/workloads-and-pods/add-a-sidecar.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/kubernetes-resources-setup/workloads-and-pods/add-a-sidecar.md new file mode 100644 index 00000000000..fe840f7005f --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/kubernetes-resources-setup/workloads-and-pods/add-a-sidecar.md @@ -0,0 +1,35 @@ +--- +title: 添加 Sidecar +--- + +_sidecar_ 是一个容器，用于扩展或增强 pod 中的主容器。主容器和 Sidecar 共享一个 pod，因此共享相同的网络空间和存储。你可以使用**添加 Sidecar** 选项将 Sidecar 添加到现有工作负载。 + +1. 在左上角，单击 **☰ > 集群管理**。 +1. 转到要添加 Sidecar 的集群，然后单击 **Explore**。 +1. 在左侧导航栏中，单击**工作负载**。 + +1. 找到要扩展的工作负载。选择 **⋮ > + 添加 Sidecar**。 + +1. 输入 Sidecar 的**名称**。 + +1. 在**通用**中，选择 Sidecar 类型。此选项确定 Sidecar 容器是在主容器之前还是之后部署。 + + - **标准容器**： + + Sidecar 容器部署在主容器之后。 + + - **初始化容器**： + + Sidecar 容器部署在主容器之前。 + +1. 在**容器镜像**字段中，输入要部署来支持主容器的容器镜像的名称。部署时，Rancher 会从 [Docker Hub](https://hub.docker.com/explore/) 拉取这个镜像。输入与 Docker Hub 上完全相同的名称。 + +1. 设置其余选项。你可以在[部署工作负载](deploy-workloads.md)中了解它们。 + +1. 点击**启动**。 + +**结果**：已根据你的参数部署 Sidecar。部署后，你可以选择 **⋮ > 编辑** 来查看 Sidecar。 + +## 相关链接 + +- [分布式系统工具包：复合容器的模式](https://kubernetes.io/blog/2015/06/the-distributed-system-toolkit-patterns/) diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/kubernetes-resources-setup/workloads-and-pods/deploy-workloads.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/kubernetes-resources-setup/workloads-and-pods/deploy-workloads.md new file mode 100644 index 00000000000..036f7a617c0 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/kubernetes-resources-setup/workloads-and-pods/deploy-workloads.md @@ -0,0 +1,57 @@ +--- +title: 部署工作负载 +description: 阅读此步骤指南以部署工作负载。部署工作负载以在一个或多个容器中运行应用程序。 +--- + +部署工作负载以在一个或多个容器中运行应用程序。 + +1. 在左上角，单击 **☰ > 集群管理**。 +1. 转到要升级工作负载的集群，然后单击 **Explore**。 +1. 在左侧导航栏中，单击**工作负载**。 +1. 单击**创建**。 +1. 选择工作负载的类型。 +1. 选择要部署工作负载的命名空间。 +1. 为工作负载设置**名称**。 + +1. 在**容器镜像**字段中，输入要部署到项目的 Docker 镜像的名称。你可以选择在前面加上镜像仓库主机（例如 `quay.io`、`registry.gitlab.com` 等）。部署时，Rancher 从指定的公共或私有镜像仓库中拉取镜像。如果没有提供镜像仓库主机，Rancher 将从 [Docker Hub](https://hub.docker.com/explore/) 拉取镜像。输入与镜像仓库服务器中显示的名称完全相同的名称，任何所需的路径，也可以选择所需的标签（例如 `registry.gitlab.com/user/path/image:tag`）。如果没有提供标签，将自动使用 `latest` 标签。 + +1. 选择现有命名空间，或单击**添加到新命名空间**并输入新命名空间。 + +1. 点击**添加端口**进入端口映射，这让你可以访问集群内外的应用程序。如需更多信息，请参阅 [Service](./workloads-and-pods.md#services)。 + +1. 配置其余选项： + + - **环境变量** + + 你可以在这里为工作负载指定环境变量以即时使用它们，或者从其他来源（例如密文或 [ConfigMap](../configmaps.md)）拉取它们。 + + - **节点调度** + - **健康检查** + - **卷** + + 在此处为你的工作负载添加存储。你可以手动指定要添加的卷，使用持久卷声明为工作负载动态创建卷，或从 [ConfigMap](../configmaps.md) 等文件中读取要使用的卷数据。 + + 部署 StatefulSet 时，应在使用持久卷时使用卷声明模板。这将确保在扩展 StatefulSet 时能动态创建持久卷。 + + - **扩展/升级策略** + + :::note AWS 卷注意事项： + + 要挂载 Amazon EBS 卷： + + - 在 [AWS](https://aws.amazon.com/) 中，节点必须位于同一可用区中并具有附加/分离卷的 IAM 权限。 + + - 集群必须使用 [AWS 云提供商](https://github.com/kubernetes/website/blob/release-1.18/content/en/docs/concepts/cluster-administration/cloud-providers.md#aws)选项。有关启用此选项的更多信息，请参阅[创建 AWS EC2 集群](../../launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/create-an-amazon-ec2-cluster.md)或[创建自定义集群](../../../../reference-guides/cluster-configuration/rancher-server-configuration/use-existing-nodes/use-existing-nodes.md)。 + + ::: + +1. 点击**显示高级选项**并配置： + + - **命令** + - **网络** + - **标签 & 注释** + - **安全和主机配置** + +1. 点击**启动**。 + +**结果**：工作负载已部署到选定的命名空间。你可以在项目的**工作负载**视图查看工作负载的状态。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/kubernetes-resources-setup/workloads-and-pods/roll-back-workloads.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/kubernetes-resources-setup/workloads-and-pods/roll-back-workloads.md new file mode 100644 index 00000000000..c12dfdd469a --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/kubernetes-resources-setup/workloads-and-pods/roll-back-workloads.md @@ -0,0 +1,14 @@ +--- +title: 回滚工作负载 +--- + +在调试或升级不顺利时，你可能需要将应用程序回滚到先前的版本。 + +1. 在左上角，单击 **☰ > 集群管理**。 +1. 转到要升级工作负载的集群，然后单击 **Explore**。 +1. 在左侧导航栏中，单击**工作负载**。 +1. 找到要回滚的工作负载，然后选择 **⋮ > 回滚**。 + +1. 选择要回滚到的修订版。单击**回滚**。 + +**结果**：你的工作负载已恢复到你选择的先前版本。等待几分钟待操作完成。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/kubernetes-resources-setup/workloads-and-pods/upgrade-workloads.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/kubernetes-resources-setup/workloads-and-pods/upgrade-workloads.md new file mode 100644 index 00000000000..6d2313f5514 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/kubernetes-resources-setup/workloads-and-pods/upgrade-workloads.md @@ -0,0 +1,21 @@ +--- +title: 升级工作负载 +--- + +如果 Docker Hub 发布新版本的应用程序镜像，你可以将运行旧版应用程序的工作负载升级到新版本。 + +1. 在左上角，单击 **☰ > 集群管理**。 +1. 转到要升级工作负载的集群，然后单击 **Explore**。 +1. 在左侧导航栏中，单击**工作负载**。 + +1. 找到要升级的工作负载并选择 **⋮ > 编辑配置**。 + +1. 更新**容器镜像**和要更改的选项。 + +1. 查看和编辑工作负载的**扩展/升级策略**。 + + 这些选项能控制升级如何在运行的容器中进行。例如，对于可扩展的 deployment，你可以选择是否要在部署新 Pod 之前停止旧 Pod，以及选择升级的批数量。 + +1. 单击**保存**。 + +**结果**：工作负载会根据你的设置来升级容器。请注意，扩展 deployment 或更新升级/扩展策略不会导致 Pod 重新创建。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/kubernetes-resources-setup/workloads-and-pods/workloads-and-pods.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/kubernetes-resources-setup/workloads-and-pods/workloads-and-pods.md new file mode 100644 index 00000000000..19ba2245972 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/kubernetes-resources-setup/workloads-and-pods/workloads-and-pods.md @@ -0,0 +1,82 @@ +--- +title: "Kubernetes 工作负载和 Pod" +description: "了解在 Kubernetes 中构建复杂容器化应用程序的两种结构：Kubernetes 工作负载和 Pod" +--- + + + + + +你可以使用两种基本结构（pod 和工作负载）在 Kubernetes 中构建复杂的容器化应用程序。构建应用程序后，你可以使用第三种结构（service）在集群中或互联网上公开应用程序。 + +## Pod + +[_Pod_](https://kubernetes.io/docs/concepts/workloads/pods/pod-overview/) 是一个或多个共享网络命名空间和存储卷的容器。大多数 pod 只有一个容器。因此，我们讨论的 _pod_ 通常等同于 _容器_。扩展 pod 的方式与扩展容器的方式相同，即配置实现服务的同一 pod 的多个实例。通常，Pod 会根据工作负载进行扩展和管理。 + +## 工作负载 + +_工作负载_ 是为 pod 设置部署规则的对象。Kubernetes 基于这些规则执行部署，并根据应用程序的当前状态来更新工作负载。 +工作负载让你可以定义应用程序调度、扩展和升级的规则。 + +### 工作负载类型 + +Kubernetes 将工作负载分为不同的类型。Kubernetes 支持的最流行的类型是： + +- [Deployment](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/) + + _Deployment_ 最适合用于无状态应用程序（即不需要维护工作负载的状态）。由 Deployment 类型工作负载管理的 Pod 是独立且一次性的。如果 pod 中断了，Kubernetes 会删除该 pod 然后重新创建它。一个示例应用程序是 Nginx Web 服务器。 + +- [StatefulSet](https://kubernetes.io/docs/concepts/workloads/controllers/statefulset/) + + 与 Deployment 相比，_StatefulSet_ 最适合在需要维护身份和存储数据的应用程序中使用。适用的应用程序类似于 Zookeeper（一个需要数据库进行存储的应用程序）。 + +- [DaemonSet](https://kubernetes.io/docs/concepts/workloads/controllers/daemonset/) + + _Daemonset_ 确保集群中的每个节点都运行 pod 的副本。如果你需要收集日志或监控节点性能，这种类似 daemon 的工作负载效果是最好的。 + +- [Job](https://kubernetes.io/docs/concepts/workloads/controllers/jobs-run-to-completion/) + + _Job_ 启动一个或多个 Pod 并确保指定数量的 Pod 能成功终止。Job 最好用于运行有限任务至完成状态，而不是管理正在进行的应用程序的所需状态。 + +- [CronJob](https://kubernetes.io/docs/concepts/workloads/controllers/cron-jobs/) + + _CronJobs_ 与 Job 类似。但是，CronJob 会基于 cron 的计划运行到完成状态。 + +## Services + +在许多用例中，工作负载必须： + +- 由集群中的其他工作负载访问。 +- 暴露给外部。 + +你可以通过创建一个 _Service_ 实现这些目的。Service 使用[选择器/标签（查看代码示例）](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/#service-and-replicationcontroller)来映射到底层工作负载的 pod。Rancher UI 使用你选择的服务端口和类型来自动创建 service 以及工作负载，从而简化此映射过程。 + +### Service 类型 + +Rancher 中有几种可用的 Service 类型。以下描述来自 [Kubernetes 文档](https://kubernetes.io/docs/concepts/services-networking/service/#publishing-services-service-types)。 + +- **ClusterIP** + + > 在集群内部 IP 上公开 Service。如果你选择此值，Service 只能从集群内访问。这是默认的 `ServiceType`。 + +- **NodePort** + + > 在每个节点 IP 上的静态端口（`NodePort`）上暴露 Service。`ClusterIP` service 是自动创建的，而 `NodePort` service 会路由到 ClusterIP service。你可以通过请求 `:` 在集群外部联系 `NodePort` service。 + +- **LoadBalancer** + + > 使用云提供商的负载均衡器向外部公开服务。`NodePort` 和 `ClusterIP` service 是自动创建的，外部负载均衡器会路由到这些 service。 + +## 工作负载选项 + +以下文档介绍了如何部署工作负载和使用工作负载选项。 + +- [部署工作负载](deploy-workloads.md) +- [升级工作负载](upgrade-workloads.md) +- [回滚工作负载](roll-back-workloads.md) + +## 相关链接 + +### 外部链接 + +- [Service](https://kubernetes.io/docs/concepts/services-networking/service/) diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/launch-kubernetes-with-rancher/about-rancher-agents.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/launch-kubernetes-with-rancher/about-rancher-agents.md new file mode 100644 index 00000000000..e01f1b6fc24 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/launch-kubernetes-with-rancher/about-rancher-agents.md @@ -0,0 +1,43 @@ +--- +title: Rancher Agent +--- + +Rancher 管理的集群上部署了两种不同的 Agent 资源： + +- [cattle-cluster-agent](#cattle-cluster-agent) +- [cattle-node-agent](#cattle-node-agent) + +有关 Rancher Server 如何配置集群并与集群通信的概述，请参阅[产品架构](../../../reference-guides/rancher-manager-architecture/rancher-manager-architecture.md)。 + +## cattle-cluster-agent + +`cattle-cluster-agent` 用于连接 [Rancher 启动的 Kubernetes](./launch-kubernetes-with-rancher.md) 集群的 Kubernetes API。`cattle-cluster-agent` 使用 Deployment 资源进行部署。 + +## cattle-node-agent + +`cattle-node-agent` 用于在执行集群操作时与 [Rancher 启动的 Kubernetes](./launch-kubernetes-with-rancher.md) 集群中的节点进行交互。集群操作包括升级 Kubernetes 版本和创建/恢复 etcd 快照。`cattle-node-agent` 使用 DaemonSet 资源进行部署，以确保能在每个节点上运行。当 `cattle-cluster-agent` 不可用时，`cattle-node-agent` 可以作为备选方案，用来连接 [Rancher 启动的 Kubernetes](./launch-kubernetes-with-rancher.md) 集群的 Kubernetes API。 + +## 调度规则 + +`cattle-cluster-agent` 使用一组固定的容忍度，或基于应用于 control plane 节点的污点动态添加的容忍度。这种结构允许[基于污点进行驱逐](https://kubernetes.io/docs/concepts/scheduling-eviction/taint-and-toleration/#taint-based-evictions)为 `cattle-cluster-agent` 正常工作。 + +如果集群中存在 control plane 节点，则默认容忍度将替换为与 control plane 节点的污点匹配的容忍度。默认的容忍度如下。 + +| 组件 | nodeAffinity nodeSelectorTerms | nodeSelector | 容忍度 | +| ---------------------- | ------------------------------------------ | ------------ | ------------------------------------------------------------------------------ | +| `cattle-cluster-agent` | `beta.kubernetes.io/os:NotIn:windows` | none | **注意**：这些是默认容忍度，并将替换为与 controlplane 节点的污点匹配的容忍度。

`effect:NoSchedule`
`key:node-role.kubernetes.io/controlplane`
`value:true`

`effect:NoSchedule`
`key:node-role.kubernetes.io/control-plane`
`operator:Exists`

`effect:NoSchedule`
`key:node-role.kubernetes.io/master`
`operator:Exists` | +| `cattle-node-agent` | `beta.kubernetes.io/os:NotIn:windows` | none | `operator:Exists` | + +`cattle-cluster-agent` Deployment 使用 `preferredDuringSchedulingIgnoredDuringExecution` 的首选调度规则，倾向于在具有 `controlplane` 节点的节点上进行调度。当集群中没有可见的 controlplane 节点时（通常是使用[提供商托管的 Kubernetes 的集群](../kubernetes-clusters-in-rancher-setup/set-up-clusters-from-hosted-kubernetes-providers/set-up-clusters-from-hosted-kubernetes-providers.md)），你可以在节点上添加 `cattle.io/cluster-agent=true` 标签，从而优先将 `cattle-cluster-agent` pod 调度到该节点。 + +有关调度规则的更多信息，请参阅 [Kubernetes：将 Pod 分配给节点](https://kubernetes.io/docs/concepts/configuration/assign-pod-node/)。 + +`preferredDuringSchedulingIgnoredDuringExecution` 配置如下表所示： + +| 权重 | 表达式 | +| ------ | ------------------------------------------------ | +| 100 | `node-role.kubernetes.io/controlplane:In:"true"` | +| 100 | `node-role.kubernetes.io/control-plane:In:"true"` | +| 100 | `node-role.kubernetes.io/master:In:"true"` | +| 1 | `cattle.io/cluster-agent:In:"true"` | + diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/launch-kubernetes-with-rancher/launch-kubernetes-with-rancher.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/launch-kubernetes-with-rancher/launch-kubernetes-with-rancher.md new file mode 100644 index 00000000000..dd01f90c645 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/launch-kubernetes-with-rancher/launch-kubernetes-with-rancher.md @@ -0,0 +1,60 @@ +--- +title: 使用 Rancher 启动 Kubernetes +--- + + + + + +Rancher allows you to launch a Kubernetes cluster on different types of nodes, including bare-metal servers, on-premise virtual machines, and virtual machines from an infrastructure provider. When deploying Kubernetes to these nodes, Rancher gives you the option to use [RKE2](https://docs.rke2.io). + +Rancher can install Kubernetes on existing nodes, or it can dynamically provision nodes in an infrastructure provider and install Kubernetes on them. + +Rancher can also create pools of machines. One benefit of installing Kubernetes on machine pools hosted by an infrastructure provider is that if a node loses connectivity with the cluster, Rancher can automatically create another node to join the cluster to ensure that the count of the machine pool is as expected. + +## RKE2 + +Rancher v2.6 introduced provisioning for [RKE2](https://docs.rke2.io/) clusters directly from the Rancher UI. RKE2, also known as RKE Government, is a fully conformant Kubernetes distribution that focuses on security and compliance within the U.S. Federal Government sector. In Rancher v.2.6.4 and earlier, RKE2 provisioning was in tech preview. + +Note that in Rancher v2.6.5, RKE2 provisioning became GA. + +### Requirements + +If you use RKE2 to set up a cluster, your nodes must meet the [requirements](https://docs.rke2.io/install/requirements) for nodes in downstream user clusters. + +### Launching Kubernetes on New Nodes in an Infrastructure Provider + +RKE2 provisioning is built on top of a new provisioning framework that leverages the upstream [Cluster API (CAPI)](https://github.com/kubernetes-sigs/cluster-api) project. With this new provisioning framework, you can: + +- Provision RKE2 clusters onto any provider for which Rancher has a node driver. +- Fully configure RKE2 clusters within Rancher. +- Choose CNI options Calico, Cilium, and Multus in addition to Canal. + +When you make changes to your cluster configuration in RKE2, this may result in nodes reprovisioning. This is controlled by CAPI controllers and not by Rancher itself. Note that for etcd nodes, the same behavior does not apply. + +The following are some specific example configuration changes that may cause the described behavior: + +- When editing the cluster and enabling drain before delete, the existing control plane nodes and worker are deleted and new nodes are created. + +RKE2 provisioning also includes installing RKE2 on clusters with Windows nodes. + +Windows features for RKE2 include: + +- Windows supports the vSphere node driver +- Calico and Flannel CNI for Windows RKE2 custom clusters +- Project Network Isolation (PNI) for Calico +- Windows Containers with RKE2 powered by containerd +- Provisioning of Windows RKE2 clusters through Terraform +- Provisioning of Windows RKE2 custom clusters directly from the Rancher UI + +Windows Support for RKE2 Custom Clusters requires choosing Calico as the CNI. + +### Launching Kubernetes on Existing Custom Nodes + +RKE2 provisioning also allows you to install custom clusters on previously provisioned VMs or bare-metal nodes. + +If you want to reuse a node from a previous custom cluster, [clean the node](../manage-clusters/clean-cluster-nodes.md#cleaning-up-nodes) before using it in a cluster again. If you reuse a node that hasn't been cleaned, cluster provisioning may fail. + +### Programmatically Creating RKE2 Clusters + +The most common way to programmatically deploy RKE2 clusters through Rancher is by using the [Rancher2 Terraform provider](https://registry.terraform.io/providers/rancher/rancher2/latest/docs/resources/cluster_v2). diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/create-a-digitalocean-cluster.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/create-a-digitalocean-cluster.md new file mode 100644 index 00000000000..656d9bd74a6 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/create-a-digitalocean-cluster.md @@ -0,0 +1,99 @@ +--- +title: 创建 DigitalOcean 集群 +--- + +在本节中，你将学习如何使用 Rancher 在 DigitalOcean 中安装 [RKE](https://rancher.com/docs/rke/latest/en/) Kubernetes 集群。 + +首先，在 Rancher 中设置你的 DigitalOcean 云凭证。然后，使用云凭证创建一个节点模板，Rancher 将使用该模板在 DigitalOcean 中配置新节点。 + +然后，在 Rancher 中创建一个 DigitalOcean 集群，并在配置新集群时为集群定义节点池。每个节点池都有一个 etcd、controlplane 或 worker 的 Kubernetes 角色。Rancher 会在新节点上安装 RKE Kubernetes，并为每个节点设置节点池定义的 Kubernetes 角色。 + + + + +1. [创建云凭证](#1-创建云凭证) +2. [使用云凭证创建节点模板](#2-使用云凭证创建节点模板) +3. [使用节点模板创建具有节点池的集群](#3-使用节点模板创建具有节点池的集群) + +### 1. 创建云凭证 + +1. 点击 **☰ > 集群管理**。 +1. 单击**云凭证**。 +1. 单击**创建**。 +1. 单击 **DigitalOcean**。 +1. 输入你的 Digital Ocean 凭证。 +1. 单击**创建**。 + +**结果**：已创建用于在集群中配置节点的云凭证。你可以在其他节点模板或集群中复用这些凭证。 + +### 2. 使用云凭证创建节点模板 + +为 DigitalOcean 创建[节点模板](./use-new-nodes-in-an-infra-provider.md#节点模板) 会允许 Rancher 在 DigitalOcean 中配置新节点。其他集群可以复用节点模板。 + +1. 点击 **☰ > 集群管理**。 +1. 单击 **RKE1 配置 > 节点模板**。 +1. 单击**添加模板**。 +1. 单击 **DigitalOcean**。 +1. 填写 DigitalOcean 的节点模板。有关填写表单的帮助，请参阅 [DigitalOcean 节点模板配置](../../../../reference-guides/cluster-configuration/downstream-cluster-configuration/node-template-configuration/digitalocean.md)。 + +### 3. 使用节点模板创建具有节点池的集群 + +1. 点击 **☰ > 集群管理**。 +1. 在**集群**页面上，单击**创建**。 +1. 单击 **DigitalOcean**。 +1. 输入**集群名称**。 +1. 将一个或多个节点池添加到你的集群。将一个或多个节点池添加到你的集群。每个节点池都使用节点模板来配置新节点。有关节点池的更多信息，包括为节点分配 Kubernetes 角色的最佳实践，请参阅[本节](./use-new-nodes-in-an-infra-provider.md)。 +1. 在**集群配置**中，选择要安装的 Kubernetes 版本、要使用的网络提供商，以及是否启用项目网络隔离。要查看更多集群选项，请单击**显示高级选项**。如需获取配置集群的帮助，请参阅 [RKE 集群配置参考](../../../../reference-guides/cluster-configuration/rancher-server-configuration/rke1-cluster-configuration.md)。 +1. 使用**成员角色**为集群配置用户授权。点击**添加成员**添加可以访问集群的用户。使用**角色**下拉菜单为每个用户设置权限。 +1. 单击**创建**。 + + + + +### 1. 创建云凭证 + +如果你已经有一组可用的云凭证，请跳过此部分。 + +1. 点击 **☰ > 集群管理**。 +1. 单击**云凭证**。 +1. 单击**创建**。 +1. 单击 **DigitalOcean**。 +1. 输入你的 Digital Ocean 凭证。 +1. 单击**创建**。 + +### 2. 创建你的集群 + +使用 Rancher 在 DigitalOcean 中创建 Kubernetes 集群。 + +1. 点击 **☰ > 集群管理**。 +1. 在**集群**页面上，单击**创建**。 +1. 将开关切换到 **RKE2/K3s**。 +1. 单击 **DigitalOcean**。 +1. 选择一个**云凭证**。如果存在多个则需要选择。否则，它是预选的。 +1. 输入**集群名称**。 +1. 为每个 Kubernetes 角色创建一个主机池。请参阅[最佳实践](./use-new-nodes-in-an-infra-provider.md#节点角色)了解角色分配和计数的建议。 + 1. 为每个主机池定义主机配置。有关配置选项的信息，请参阅 [DigitalOcean 主机配置参考](../../../../reference-guides/cluster-configuration/downstream-cluster-configuration/machine-configuration/digitalocean.md)。 +1. 使用**集群配置**，选择要安装的 Kubernetes 版本、要使用的网络提供商，以及是否启用项目网络隔离。有关配置集群的帮助，请参阅 [RKE2 集群配置参考](../../../../reference-guides/cluster-configuration/rancher-server-configuration/rke2-cluster-configuration.md)。 +1. 使用**成员角色**为集群配置用户授权。点击**添加成员**添加可以访问集群的用户。使用**角色**下拉菜单为每个用户设置权限。 +1. 单击**创建**。 + + + + +**结果**： + +你已创建集群，集群的状态是**配置中**。Rancher 已在你的集群中。 + +当集群状态变为 **Active** 后，你可访问集群。 + +**Active** 状态的集群会分配到两个项目： + +- `Default`：包含 `default` 命名空间 +- `System`：包含 `cattle-system`，`ingress-nginx`，`kube-public` 和 `kube-system` 命名空间。 + +## 可选的后续步骤 + +创建集群后，你可以通过 Rancher UI 访问集群。最佳实践建议你设置以下访问集群的备用方式： + +- **通过 kubectl CLI 访问你的集群**：按照[这些步骤](../../../new-user-guides/manage-clusters/access-clusters/use-kubectl-and-kubeconfig.md#在工作站使用-kubectl-访问集群)在你的工作站上使用 kubectl 访问集群。在这种情况下，你将通过 Rancher Server 的身份验证代理进行身份验证，然后 Rancher 会让你连接到下游集群。此方法允许你在没有 Rancher UI 的情况下管理集群。 +- **通过 kubectl CLI 使用授权的集群端点访问你的集群**：按照[这些步骤](../../../new-user-guides/manage-clusters/access-clusters/use-kubectl-and-kubeconfig.md#直接使用下游集群进行身份验证)直接使用 kubectl 访问集群，而无需通过 Rancher 进行身份验证。我们建议设置此替代方法来访问集群，以便在无法连接到 Rancher 时访问集群。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/create-an-amazon-ec2-cluster.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/create-an-amazon-ec2-cluster.md new file mode 100644 index 00000000000..c7fe813394f --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/create-an-amazon-ec2-cluster.md @@ -0,0 +1,283 @@ +--- +title: 创建 Amazon EC2 集群 +description: 了解使用 Rancher 创建 Amazon EC2 集群所需的先决条件和步骤 +--- + +在本节中，你将学习如何使用 Rancher 在 Amazon EC2 中安装 [RKE](https://rancher.com/docs/rke/latest/en/) Kubernetes 集群。 + +首先，在 Rancher 中设置你的 EC2 云凭证。然后，使用云凭证创建一个节点模板，Rancher 将使用该模板在 EC2 中配置新节点。 + +然后，在 Rancher 中创建一个 EC2 集群，并在配置新集群时为集群定义节点池。每个节点池都有一个 etcd、controlplane 或 worker 的 Kubernetes 角色。Rancher 会在新节点上安装 RKE Kubernetes，并为每个节点设置节点池定义的 Kubernetes 角色。 + +## 先决条件 + +- **AWS EC2 访问密钥和密文密钥**，用于创建实例。请参阅 [Amazon 文档：创建访问密钥](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html#Using_CreateAccessKey)来创建访问密钥和密文密钥。 +- **已创建 IAM 策略**，用于为用户添加的访问密钥和密文密钥。请参阅 [Amazon 文档：创建 IAM 策略（控制台）](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_create.html#access_policies_create-start)来创建 IAM 策略。参阅下面的三个示例 JSON 策略： + - [IAM 策略示例](#iam-策略示例) + - [带有 PassRole 的 IAM 策略示例](#带有-passrole-的-iam-策略示例)（如果要使用 [Kubernetes 云提供商](../../kubernetes-clusters-in-rancher-setup/set-up-cloud-providers/set-up-cloud-providers.md)，或将 IAM 配置文件传递给实例，则需要） + - [允许加密 EBS 卷的 IAM 策略示例](#允许加密-ebs-卷的-iam-策略示例) +- 为用户添加 **IAM 策略权限**。请参阅 [Amazon 文档：为用户添加权限（控制台）](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users_change-permissions.html#users_change_permissions-add-console)，来将权限添加给用户。 + +## 创建 EC2 集群 + +创建集群的步骤因 Rancher 版本而异。 + + + + +1. [创建云凭证](#1-创建云凭证) +2. [使用云凭证和 EC2 的信息来创建节点模板](#2-使用云凭证和-ec2-的信息来创建节点模板) +3. [使用节点模板创建具有节点池的集群](#3-使用节点模板创建具有节点池的集群) + +### 1. 创建云凭证 + +1. 点击 **☰ > 集群管理**。 +1. 单击**云凭证**。 +1. 单击**创建**。 +1. 单击 **Amazon**。 +1. 输入云凭证的名称。 +1. 在**默认区域**字段中，选择集群节点所在的 AWS 区域。 +1. 输入 AWS EC2 **Access Key** 和 **Secret Key**。 +1. 单击**创建**。 + +**结果**：已创建用于在集群中配置节点的云凭证。你可以在其他节点模板或集群中复用这些凭证。 + +### 2. 使用云凭证和 EC2 的信息来创建节点模板 + +为 EC2 创建[节点模板](./use-new-nodes-in-an-infra-provider.md#节点模板)会允许 Rancher 在 EC2 中配置新节点。其他集群可以复用节点模板。 + +1. 点击 **☰ > 集群管理**。 +1. 单击 **RKE1 配置 > 节点模板**。 +1. 单击**添加模板**。 +1. 填写 EC2 的节点模板。有关填写表单的帮助，请参阅 [EC2 节点模板配置](../../../../reference-guides/cluster-configuration/downstream-cluster-configuration/node-template-configuration/amazon-ec2.md)。 +1. 单击**创建**。 + + :::note + + 如果要使用[双栈](https://kubernetes.io/docs/concepts/services-networking/dual-stack/)功能，请关注其他额外的[要求](https://rancher.com/docs/rke//latest/en/config-options/dual-stack#requirements)。 + + ::: + +### 3. 使用节点模板创建具有节点池的集群 + +将一个或多个节点池添加到你的集群。有关节点池的更多信息，请参阅[本节](./use-new-nodes-in-an-infra-provider.md)。 + +1. 点击 **☰ > 集群管理**。 +1. 在**集群**页面上，单击**创建**。 +1. 单击 **Amazon EC2**。 +1. 为每个 Kubernetes 角色创建一个节点池。为每个节点池选择你已创建的节点模板。有关节点池的更多信息，包括为节点分配 Kubernetes 角色的最佳实践，请参阅[本节](./use-new-nodes-in-an-infra-provider.md)。 +1. 点击**添加成员**添加可以访问集群的用户。使用**角色**下拉菜单为每个用户设置权限。 +1. 使用**集群选项**选择要安装的 Kubernetes 版本、要使用的网络提供商，以及是否启用项目网络隔离。参见[选择云提供商](../../kubernetes-clusters-in-rancher-setup/set-up-cloud-providers/set-up-cloud-providers.md)来配置 Kubernetes 云提供商。如需获取配置集群的帮助，请参阅 [RKE 集群配置参考](../../../../reference-guides/cluster-configuration/rancher-server-configuration/rke1-cluster-configuration.md)。 + + :::note + + 如果要使用[双栈](https://kubernetes.io/docs/concepts/services-networking/dual-stack/)功能，请关注其他额外的[要求](https://rancher.com/docs/rke//latest/en/config-options/dual-stack#requirements)。 + + ::: + +1. 单击**创建**。 + + + + +### 1. 创建云凭证 + +如果你已经有一组可用的云凭证，请跳过此部分。 + +1. 点击 **☰ > 集群管理**。 +1. 单击**云凭证**。 +1. 单击**创建**。 +1. 单击 **Amazon**。 +1. 输入云凭证的名称。 +1. 在**默认区域**字段中，选择集群节点所在的 AWS 区域。 +1. 输入 AWS EC2 **Access Key** 和 **Secret Key**。 +1. 单击**创建**。 + +**结果**：已创建用于在集群中配置节点的云凭证。你可以在其他节点模板或集群中复用这些凭证。 + +### 2. 创建你的集群 + +1. 点击 **☰ > 集群管理**。 +1. 在**集群**页面上，单击**创建**。 +1. 将开关切换到 **RKE2/K3s**。 +1. 单击 **Amazon EC2**。 +1. 选择一个**云凭证**。如果存在多个则需要选择。否则，它是预选的。 +1. 输入**集群名称**。 +1. 为每个 Kubernetes 角色创建一个主机池。请参阅[最佳实践](./use-new-nodes-in-an-infra-provider.md#节点角色)了解角色分配和计数的建议。 + 1. 为每个主机池定义主机配置。有关配置选项的信息，请参阅 [EC2 主机配置参考](../../../../reference-guides/cluster-configuration/downstream-cluster-configuration/machine-configuration/amazon-ec2.md)。 +1. 使用**集群配置**，选择要安装的 Kubernetes 版本、要使用的网络提供商，以及是否启用项目网络隔离。有关配置集群的帮助，请参阅 [RKE2 集群配置参考](../../../../reference-guides/cluster-configuration/rancher-server-configuration/rke2-cluster-configuration.md)。 +1. 使用**成员角色**为集群配置用户授权。点击**添加成员**添加可以访问集群的用户。使用**角色**下拉菜单为每个用户设置权限。 +1. 单击**创建**。 + + + + +**结果**： + +你已创建集群，集群的状态是**配置中**。Rancher 已在你的集群中。 + +当集群状态变为 **Active** 后，你可访问集群。 + +**Active** 状态的集群会分配到两个项目： + +- `Default`：包含 `default` 命名空间 +- `System`：包含 `cattle-system`，`ingress-nginx`，`kube-public` 和 `kube-system` 命名空间。 + +### 可选的后续步骤 + +创建集群后，你可以通过 Rancher UI 访问集群。最佳实践建议你设置以下访问集群的备用方式： + +- **通过 kubectl CLI 访问你的集群**：按照[这些步骤](../../../new-user-guides/manage-clusters/access-clusters/use-kubectl-and-kubeconfig.md#在工作站使用-kubectl-访问集群)在你的工作站上使用 kubectl 访问集群。在这种情况下，你将通过 Rancher Server 的身份验证代理进行身份验证，然后 Rancher 会让你连接到下游集群。此方法允许你在没有 Rancher UI 的情况下管理集群。 +- **通过 kubectl CLI 使用授权的集群端点访问你的集群**：按照[这些步骤](../../../new-user-guides/manage-clusters/access-clusters/use-kubectl-and-kubeconfig.md#直接使用下游集群进行身份验证)直接使用 kubectl 访问集群，而无需通过 Rancher 进行身份验证。我们建议设置此替代方法来访问集群，以便在无法连接到 Rancher 时访问集群。 + +## IAM 策略 + +### IAM 策略示例 + +```json +{ + "Version": "2012-10-17", + "Statement": [ + { + "Sid": "VisualEditor0", + "Effect": "Allow", + "Action": [ + "ec2:AuthorizeSecurityGroupIngress", + "ec2:Describe*", + "ec2:ImportKeyPair", + "ec2:CreateKeyPair", + "ec2:CreateSecurityGroup", + "ec2:CreateTags", + "ec2:DeleteKeyPair", + "ec2:ModifyInstanceMetadataOptions" + ], + "Resource": "*" + }, + { + "Sid": "VisualEditor1", + "Effect": "Allow", + "Action": [ + "ec2:RunInstances" + ], + "Resource": [ + "arn:aws:ec2:REGION::image/ami-*", + "arn:aws:ec2:REGION:AWS_ACCOUNT_ID:instance/*", + "arn:aws:ec2:REGION:AWS_ACCOUNT_ID:placement-group/*", + "arn:aws:ec2:REGION:AWS_ACCOUNT_ID:volume/*", + "arn:aws:ec2:REGION:AWS_ACCOUNT_ID:subnet/*", + "arn:aws:ec2:REGION:AWS_ACCOUNT_ID:key-pair/*", + "arn:aws:ec2:REGION:AWS_ACCOUNT_ID:network-interface/*", + "arn:aws:ec2:REGION:AWS_ACCOUNT_ID:security-group/*" + ] + }, + { + "Sid": "VisualEditor2", + "Effect": "Allow", + "Action": [ + "ec2:RebootInstances", + "ec2:TerminateInstances", + "ec2:StartInstances", + "ec2:StopInstances" + ], + "Resource": "arn:aws:ec2:REGION:AWS_ACCOUNT_ID:instance/*" + } + ] +} +``` + +### 带有 PassRole 的 IAM 策略示例 + +```json +{ + "Version": "2012-10-17", + "Statement": [ + { + "Sid": "VisualEditor0", + "Effect": "Allow", + "Action": [ + "ec2:AuthorizeSecurityGroupIngress", + "ec2:Describe*", + "ec2:ImportKeyPair", + "ec2:CreateKeyPair", + "ec2:CreateSecurityGroup", + "ec2:CreateTags", + "ec2:DeleteKeyPair", + "ec2:ModifyInstanceMetadataOptions" + ], + "Resource": "*" + }, + { + "Sid": "VisualEditor1", + "Effect": "Allow", + "Action": [ + "iam:PassRole", + "ec2:RunInstances" + ], + "Resource": [ + "arn:aws:ec2:REGION::image/ami-*", + "arn:aws:ec2:REGION:AWS_ACCOUNT_ID:instance/*", + "arn:aws:ec2:REGION:AWS_ACCOUNT_ID:placement-group/*", + "arn:aws:ec2:REGION:AWS_ACCOUNT_ID:volume/*", + "arn:aws:ec2:REGION:AWS_ACCOUNT_ID:subnet/*", + "arn:aws:ec2:REGION:AWS_ACCOUNT_ID:key-pair/*", + "arn:aws:ec2:REGION:AWS_ACCOUNT_ID:network-interface/*", + "arn:aws:ec2:REGION:AWS_ACCOUNT_ID:security-group/*", + "arn:aws:iam::AWS_ACCOUNT_ID:role/YOUR_ROLE_NAME" + ] + }, + { + "Sid": "VisualEditor2", + "Effect": "Allow", + "Action": [ + "ec2:RebootInstances", + "ec2:TerminateInstances", + "ec2:StartInstances", + "ec2:StopInstances" + ], + "Resource": "arn:aws:ec2:REGION:AWS_ACCOUNT_ID:instance/*" + } + ] +} +``` +### 允许加密 EBS 卷的 IAM 策略示例 +```json +{ + "Version": "2012-10-17", + "Statement": [ + { + "Effect": "Allow", + "Action": [ + "kms:Decrypt", + "kms:GenerateDataKeyWithoutPlaintext", + "kms:Encrypt", + "kms:DescribeKey", + "kms:CreateGrant", + "ec2:DetachVolume", + "ec2:AttachVolume", + "ec2:DeleteSnapshot", + "ec2:DeleteTags", + "ec2:CreateTags", + "ec2:CreateVolume", + "ec2:DeleteVolume", + "ec2:CreateSnapshot" + ], + "Resource": [ + "arn:aws:ec2:REGION:AWS_ACCOUNT_ID:volume/*", + "arn:aws:ec2:REGION:AWS_ACCOUNT_ID:instance/*", + "arn:aws:ec2:REGION:AWS_ACCOUNT_ID:snapshot/*", + "arn:aws:kms:REGION:AWS_ACCOUNT_ID:key/KMS_KEY_ID" + ] + }, + { + "Effect": "Allow", + "Action": [ + "ec2:DescribeInstances", + "ec2:DescribeTags", + "ec2:DescribeVolumes", + "ec2:DescribeSnapshots" + ], + "Resource": "*" + } + ] +} +``` diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/create-an-azure-cluster.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/create-an-azure-cluster.md new file mode 100644 index 00000000000..e9e2c6fbfb8 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/create-an-azure-cluster.md @@ -0,0 +1,141 @@ +--- +title: 创建 Azure 集群 +--- + +在本节中，你将学习如何通过 Rancher 在 Azure 中安装 [RKE](https://rancher.com/docs/rke/latest/en/) Kubernetes 集群。 + +首先，在 Rancher 中设置你的 Azure 云凭证。然后，使用云凭证创建一个节点模板，Rancher 将使用该模板在 Azure 中配置新节点。 + +然后，在 Rancher 中创建一个 Azure 集群，并在配置新集群时为集群定义节点池。每个节点池都有一个 etcd、controlplane 或 worker 的 Kubernetes 角色。Rancher 会在新节点上安装 Kubernetes，并为每个节点设置节点池定义的 Kubernetes 角色。 + +:::caution + +当 Rancher RKE 集群在 Azure 中运行并且前面有 Azure 负载均衡器时，出站流量会失败。问题的解决方法如下： + +- 终止内部负载均衡器上的 SSL/TLS +- 使用 L7 负载均衡器 + +详情请参见 [Azure 负载均衡器限制](https://docs.microsoft.com/en-us/azure/load-balancer/components#limitations)。 + +::: + +有关 Rancher 在 Azure 节点上安装的 Kubernetes 集群的更多信息，请参阅 [RKE 集群配置参考](../../../../reference-guides/cluster-configuration/rancher-server-configuration/rke1-cluster-configuration.md)。 + +有关配置 Azure 节点模板的详细信息，请参阅 [Azure 节点模板配置参考](../../../../reference-guides/cluster-configuration/downstream-cluster-configuration/node-template-configuration/azure.md)。 + +- [Azure 中的准备工作](#azure-中的准备工作) +- [创建 Azure 集群](#创建-azure-集群) + +## Azure 中的准备工作 + +在使用 Azure 等云厂商在 Rancher 中创建节点模板之前，必须先配置 Rancher 以允许操作 Azure 订阅中的资源。 + +为此，首先在 Azure 的 **Active Directory (AD)** 中创建一个新的 Azure **service principal (服务主体，缩写是 SP)**，它是具有管理 Azure 权限的应用用户。 + +以下是创建服务主体必须运行的 `az cli` 脚本模板，你必须在其中输入你的服务主体名称、角色和范围： + +``` +az ad sp create-for-rbac \ + --name="" \ + --role="Contributor" \ + --scopes="/subscriptions/" +``` + +创建服务主体后会返回三个标识信息，分别是*应用 ID（也称为客户端 ID）*，以及*客户端密码*。为 Azure 创建节点模板时将使用这些信息。 + +## 创建 Azure 集群 + + + + +1. [创建云凭证](#1-创建云凭证) +2. [使用云凭证创建节点模板](#2-使用云凭证创建节点模板) +3. [使用节点模板创建具有节点池的集群](#3-使用节点模板创建具有节点池的集群) + +### 1. 创建云凭证 + +1. 点击 **☰ > 集群管理**。 +1. 单击**云凭证**。 +1. 单击**创建**。 +1. 单击 **Azure**。 +1. 输入你的 Azure 凭证。 +1. 单击**创建**。 + +**结果**：已创建用于在集群中配置节点的云凭证。你可以在其他节点模板或集群中复用这些凭证。 + +### 2. 使用云凭证创建节点模板 + +为 Azure 创建[节点模板](./use-new-nodes-in-an-infra-provider.md#节点模板)会允许 Rancher 在 Azure 中配置新节点。其他集群可以复用节点模板。 + +1. 点击 **☰ > 集群管理**。 +1. 单击 **RKE1 配置 > 节点模板**。 +1. 单击**添加模板**。 +1. 单击 **Azure**。 +1. 填写 Azure 的节点模板。有关填写表单的帮助，请参阅 [Azure 节点模板配置](../../../../reference-guides/cluster-configuration/downstream-cluster-configuration/node-template-configuration/azure.md)。 + +### 3. 使用节点模板创建具有节点池的集群 + +使用 Rancher 在 Azure 中创建 Kubernetes 集群。 + +1. 点击 **☰ > 集群管理**。 +1. 在**集群**页面上，单击**创建**。 +1. 单击 **Azure**。 +1. 输入**集群名称**。 +1. 将一个或多个节点池添加到你的集群。每个节点池都使用节点模板来配置新节点。有关节点池及其最佳实践的更多信息，请参阅[本节](./use-new-nodes-in-an-infra-provider.md)。 +1. 在**集群配置**中，选择要安装的 Kubernetes 版本、要使用的网络提供商，以及是否启用项目网络隔离。要查看更多集群选项，请单击**显示高级选项**。如需获取配置集群的帮助，请参阅 [RKE 集群配置参考](../../../../reference-guides/cluster-configuration/rancher-server-configuration/rke1-cluster-configuration.md)。 +1. 使用**成员角色**为集群配置用户授权。点击**添加成员**添加可以访问集群的用户。使用**角色**下拉菜单为每个用户设置权限。 +1. 单击**创建**。 + + + + +### 1. 创建云凭证 + +如果你已经有一组可用的云凭证，请跳过此部分。 + +1. 点击 **☰ > 集群管理**。 +1. 单击**云凭证**。 +1. 单击**创建**。 +1. 单击 **Azure**。 +1. 输入你的 Azure 凭证。 +1. 单击**创建**。 + +**结果**：已创建用于在集群中配置节点的云凭证。你可以在其他节点模板或集群中复用这些凭证。 + +### 2. 创建你的集群 + +使用 Rancher 在 Azure 中创建 Kubernetes 集群。 + +1. 点击 **☰ > 集群管理**。 +1. 在**集群**页面上，单击**创建**。 +1. 将开关切换到 **RKE2/K3s**。 +1. 单击 **Azure**。 +1. 选择一个**云凭证**。如果存在多个则需要选择。否则，它是预选的。 +1. 输入**集群名称**。 +1. 为每个 Kubernetes 角色创建一个主机池。请参阅[最佳实践](./use-new-nodes-in-an-infra-provider.md#节点角色)了解角色分配和计数的建议。 + 1. 为每个主机池定义主机配置。有关配置选项的信息，请参阅 [Azure 主机配置参考](../../../../reference-guides/cluster-configuration/downstream-cluster-configuration/machine-configuration/azure.md)。 +1. 使用**集群配置**，选择要安装的 Kubernetes 版本、要使用的网络提供商，以及是否启用项目网络隔离。有关配置集群的帮助，请参阅 [RKE2 集群配置参考](../../../../reference-guides/cluster-configuration/rancher-server-configuration/rke2-cluster-configuration.md)。 +1. 使用**成员角色**为集群配置用户授权。点击**添加成员**添加可以访问集群的用户。使用**角色**下拉菜单为每个用户设置权限。 +1. 单击**创建**。 + + + + +**结果**： + +你已创建集群，集群的状态是**配置中**。Rancher 已在你的集群中。 + +当集群状态变为 **Active** 后，你可访问集群。 + +**Active** 状态的集群会分配到两个项目： + +- `Default`：包含 `default` 命名空间 +- `System`：包含 `cattle-system`，`ingress-nginx`，`kube-public` 和 `kube-system` 命名空间。 + + +### 可选的后续步骤 + +创建集群后，你可以通过 Rancher UI 访问集群。最佳实践建议你设置以下访问集群的备用方式： + +- **通过 kubectl CLI 访问你的集群**：按照[这些步骤](../../../new-user-guides/manage-clusters/access-clusters/use-kubectl-and-kubeconfig.md#在工作站使用-kubectl-访问集群)在你的工作站上使用 kubectl 访问集群。在这种情况下，你将通过 Rancher Server 的身份验证代理进行身份验证，然后 Rancher 会让你连接到下游集群。此方法允许你在没有 Rancher UI 的情况下管理集群。 +- **通过 kubectl CLI 使用授权的集群端点访问你的集群**：按照[这些步骤](../../../new-user-guides/manage-clusters/access-clusters/use-kubectl-and-kubeconfig.md#直接使用下游集群进行身份验证)直接使用 kubectl 访问集群，而无需通过 Rancher 进行身份验证。我们建议设置此替代方法来访问集群，以便在无法连接到 Rancher 时访问集群。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/nutanix/nutanix.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/nutanix/nutanix.md new file mode 100644 index 00000000000..c32a765cb3c --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/nutanix/nutanix.md @@ -0,0 +1,21 @@ +--- +title: 创建 Nutanix AOS 集群 +description: 使用 Rancher 创建 Nutanix AOS (AHV) 集群。集群可能包括具有不同属性的 VM 组，这些属性可用于细粒度控制节点的大小。 +--- + + + + + +[Nutanix Acropolis 操作系统](https://www.nutanix.com/products/acropolis) (Nutanix AOS) 是适用于 Nutanix 超融合基础架构平台的操作系统。AOS 带有一个名为 [Acropolis Hypervisor（AHV）](https://www.nutanix.com/products/ahv)的内置虚拟机监控程序。你可以结合使用 Rancher 与 Nutanix AOS (AHV)，从而在本地体验云环境的操作。 + +Rancher 可以在 AOS (AHV) 中配置节点并在其上安装 Kubernetes。在 AOS 中创建 Kubernetes 集群时，Rancher 首先与 Prism Central API 通信来配置指定数量的虚拟机。然后在虚拟机上安装 Kubernetes。 + +Nutanix 集群可能由多组具有不同属性（例如内存或 vCPU 数量）的 VM 组成。这种分组允许对每个 Kubernetes 角色的节点大小进行细粒度控制。 + +- [创建 Nutanix 集群](./provision-kubernetes-clusters-in-aos.md#1-创建节点模板) +- [配置存储](./provision-kubernetes-clusters-in-aos.md) + +## 创建 Nutanix 集群 + +在[本节](./provision-kubernetes-clusters-in-aos.md)中，你将学习如何使用 Rancher 在 Nutanix AOS 中安装 [RKE](https://rancher.com/docs/rke/latest/en/) Kubernetes 集群。 \ No newline at end of file diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/nutanix/provision-kubernetes-clusters-in-aos.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/nutanix/provision-kubernetes-clusters-in-aos.md new file mode 100644 index 00000000000..1ce64df1fe9 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/nutanix/provision-kubernetes-clusters-in-aos.md @@ -0,0 +1,92 @@ +--- +title: 在 Nutanix AOS 中配置 Kubernetes 集群 +--- + +要使用 Rancher 在 Nutanix AOS (AHV) 中安装 [RKE](https://rancher.com/docs/rke/latest/en/) Kubernetes 集群： + +1. 找到 Rancher 的内置 Nutanix [主机驱动并激活它](../../../authentication-permissions-and-global-configuration/about-provisioning-drivers/manage-node-drivers.md#激活停用主机驱动)。 + +1. 创建一个节点模板，Rancher 将使用该模板在 Nutanix AOS 中配置节点。 + +1. 在 Rancher 中创建 Nutanix AOS 集群。配置新集群时，你需要为它定义节点池。每个节点池都有一个 etcd、controlplane 或 worker 的 Kubernetes 角色。Rancher 会在新节点上安装 RKE Kubernetes，并为每个节点设置节点池定义的 Kubernetes 角色。 + +有关配置 Nutanix AOS 节点模板的详细信息，请参阅 [Nutanix AOS 节点模板配置参考](../../../../../reference-guides/cluster-configuration/downstream-cluster-configuration/node-template-configuration/nutanix.md)。 + +有关在 Rancher 中配置 RKE Kubernetes 集群的详细信息，请参阅[集群配置参考](../../../../../reference-guides/cluster-configuration/rancher-server-configuration/rke1-cluster-configuration.md)。 + +- [Nutanix AOS 中的准备工作](#nutanix-aos-中的准备工作) +- [创建 Nutanix AOS 集群](#创建-nutanix-aos-集群) + +## Nutanix AOS 中的准备工作 + +下文介绍了设置 Nutanix AOS 的要求，以便 Rancher 可以配置虚拟机和集群。 + +:::note + +节点模板已使用 Nutanix AOS 5.20.2 和 6.0.1 版本进行记录和测试。 + +::: + +### 在 Nutanix AOS 中创建凭证 + +在继续创建集群之前，请确保你拥有具有管理员权限的 [Nutanix Prism Central 用户账号](https://portal.nutanix.com/page/documents/details?targetId=Nutanix-Security-Guide-v6_0:wc-user-create-wc-t.html)。设置节点模板时，模板将需要使用这些凭证。 + +### 网络权限 + +必须确保运行 Rancher Server 的主机能够建立以下网络连接： + +- 连接到 Nutanix Prism Central API（通常是端口 9440/TCP）。 +- 连接到创建的 VM 上的 22/TCP 和 2376/TCP 端口。 + +有关在基础设施提供商上创建节点的端口要求，请参阅[节点网络要求](../../../kubernetes-clusters-in-rancher-setup/node-requirements-for-rancher-managed-clusters.md#网络要求)。 + +### VM-VM 反亲和性策略 + +建议设置 [VM-VM 反亲和性策略](https://portal.nutanix.com/page/documents/details?targetId=AHV-Admin-Guide-v6_1:ahv-vm-anti-affinity-t.html)。这些规则允许分配了 etcd 和 controlplane 角色的虚拟机在分配给不同节点池时，在单独的 AHV 主机上运行。这种做法可确保单个物理机的故障不会影响这些平面的可用性。 + +## 创建 Nutanix AOS 集群 + +1. [创建节点模板](#1-创建节点模板) +2. [使用节点模板创建具有节点池的集群](#2-使用节点模板创建具有节点池的集群) + +### 1. 创建节点模板 + +为 Nutanix AOS 创建[节点模板](../use-new-nodes-in-an-infra-provider.md#节点模板)会允许 Rancher 在 Nutanix AOS 中配置新节点。其他集群可以复用节点模板。 + +1. 点击 **☰ > 集群管理**。 +1. 单击 **RKE1 配置 > 节点模板**。 +1. 单击**创建**。 +1. 单击**添加模板**。 +1. 单击 **Nutanix**。 +1. 填写 Nutanix AOS 的节点模板。有关填写表格的帮助，请参阅 Nutanix AOS 节点模板[配置参考](../../../../../reference-guides/cluster-configuration/downstream-cluster-configuration/node-template-configuration/nutanix.md)。 +1. 单击**创建**。 + +### 2. 使用节点模板创建具有节点池的集群 + +使用 Rancher 在 Nutanix AOS 中创建 Kubernetes 集群。 + +1. 点击 **☰ > 集群管理**。 +1. 在**集群**页面上，单击**创建**。 +1. 单击 **Nutanix**。 +1. 输入**集群名称**，然后点击**继续**。 +1. 使用**成员角色**为集群配置用户授权。点击**添加成员**添加可以访问集群的用户。使用**角色**下拉菜单为每个用户设置权限。 +1. 使用**集群选项**选择要安装的 Kubernetes 版本、要使用的网络提供商，以及是否启用项目网络隔离。要查看更多集群选项，请单击**显示高级选项**。如需获取配置集群的帮助，请参阅 [RKE 集群配置参考](../../../../../reference-guides/cluster-configuration/rancher-server-configuration/rke1-cluster-configuration.md)。 +1. 将一个或多个节点池添加到你的集群。每个节点池都使用节点模板来配置新节点。有关节点池的更多信息，包括为节点分配 Kubernetes 角色的最佳实践，请参阅[本节](../../../launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/use-new-nodes-in-an-infra-provider.md#节点池)。 +1. 检查并确认你的选项。然后单击**创建**。 + +**结果**：集群已创建，并处于 **Provisioning** 状态。Rancher 已在你的集群中。 + +当集群状态变为 **Active** 后，你可访问集群。 + +**Active** 状态的集群会分配到两个项目： + +- `Default`：包含 `default` 命名空间 +- `System`：包含 `cattle-system`，`ingress-nginx`，`kube-public` 和 `kube-system` 命名空间。 + +## 可选的后续步骤 + +创建集群后，你可以通过 Rancher UI 访问集群。最佳实践建议你设置以下访问集群的备用方式： + +- **通过 kubectl CLI 访问你的集群**：按照[这些步骤](../../../../new-user-guides/manage-clusters/access-clusters/use-kubectl-and-kubeconfig.md#在工作站使用-kubectl-访问集群)在你的工作站上使用 kubectl 访问集群。在这种情况下，你将通过 Rancher Server 的身份验证代理进行身份验证，然后 Rancher 会让你连接到下游集群。此方法允许你在没有 Rancher UI 的情况下管理集群。 + +- **通过 kubectl CLI 使用授权的集群端点访问你的集群**：按照[这些步骤](../../../../new-user-guides/manage-clusters/access-clusters/use-kubectl-and-kubeconfig.md#直接使用下游集群进行身份验证)直接使用 kubectl 访问集群，而无需通过 Rancher 进行身份验证。我们建议设置此替代方法来访问集群，以便在无法连接到 Rancher 时访问集群。 \ No newline at end of file diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/use-new-nodes-in-an-infra-provider.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/use-new-nodes-in-an-infra-provider.md new file mode 100644 index 00000000000..74855aac6b1 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/use-new-nodes-in-an-infra-provider.md @@ -0,0 +1,156 @@ +--- +title: 在云厂商的新节点上启动 Kubernetes +--- + + + + + +在 Rancher 中使用节点模板来创建 RKE 或 RKE2 集群时，每个生成的节点池都会显示在新的**主机池**选项卡中。你可以通过执行以下操作来查看主机池： + +1. 点击**☰ > 集群管理**。 +1. 单击 RKE 或 RKE2 集群的名称。 + +## RKE 集群 + +使用 Rancher，你可以基于[节点模板](use-new-nodes-in-an-infra-provider.md#节点模板)创建节点池。此节点模板定义了要用于在基础设施提供商或云厂商中启动节点的参数。 + +在托管在云厂商的节点池上安装 Kubernetes 的一个好处是，如果一个节点与集群断开连接，Rancher 可以自动创建另一个节点并将其加入集群，从而确保节点池的数量符合要求。 + +可用于创建节点模板的云提供商是由[主机驱动](use-new-nodes-in-an-infra-provider.md#主机驱动)决定的。 + +### 节点模板 + +节点模板保存了用于在特定云提供商中配置节点时要使用的参数。这些节点可以从 UI 启动。Rancher 使用 [Docker Machine](https://github.com/docker/docs/blob/vnext-engine/machine/overview.md) 来配置这些节点。可用于创建节点模板的云提供商取决于 Rancher 中状态是 Active 的主机驱动。 + +在 Rancher 中创建节点模板后，模板会被保存，以便你可以再次使用该模板来创建节点池。节点模板绑定到你的登录名。添加模板后，你可以将其从用户配置文件中删除。 + +#### 节点标签 + +你可以为每个节点模板添加[标签](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/)，这样，使用节点模板创建的节点都会自动带有这些标签。 + +无效标签会阻止升级，或阻止 Rancher 启动。有关标签语法的详细信息，请参阅 [Kubernetes 文档](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/#syntax-and-character-set)。 + +#### 节点污点 + +你可以为每个节点模板添加[污点](https://kubernetes.io/docs/concepts/configuration/taint-and-toleration/)，这样，使用节点模板创建的节点都会自动带有这些污点。 + +由于污点可以同时添加到节点模板和节点池中，因此如果添加了相同键的污点效果没有冲突，则所有污点都将添加到节点中。如果存在具有相同键但不同效果的污点，则节点池中的污点将覆盖节点模板中的污点。 + +#### 节点模板的管理员控制 + +管理员可以控制所有节点模板。现在，管理员可以维护 Rancher 中的所有节点模板。当节点模板所有者不再使用 Rancher 时，他们创建的节点模板可以由管理员管理，以便继续更新和维护集群。 + +要访问所有节点模板，管理员需要执行以下操作： + +1. 点击 **☰ > 集群管理**。 +1. 单击 **RKE1 配置 > 节点模板**。 + +**结果**：列出所有节点模板。你可以通过单击 **⋮** 来编辑或克隆模板。 + +### 节点池 + +使用 Rancher，你可以基于[节点模板](#节点模板)创建节点池。 + +节点模板定义了节点的配置，例如要使用的操作系统、CPU 数量和内存量。 + +使用节点池的好处是，如果一个节点被销毁或删除，你可以增加 Active 节点的数量来补偿丢失的节点。节点池可以帮助你确保节点池的计数符合要求。 + +每个节点池必须分配一个或多个节点角色。 + +每个节点角色（即 etcd、controlplane 和 worker）都应分配给不同的节点池。虽然你可以将多个节点角色分配给同一个节点池，但不要在生产集群中执行此操作。 + +推荐的设置： + +- 具有 etcd 角色且计数为 3 的节点池 +- 具有 controlplane 角色且计数至少为 2 的节点池 +- 具有 worker 角色且计数至少为 2 的节点池 + +**离线环境中的 RKE1 下游集群节点**： + +默认情况下，在配置 RKE1 下游集群节点时（例如在 vSphere 中），Rancher 会尝试运行 Docker 安装脚本。但是，Rancher Docker 安装脚本在离线环境中会运行失败。要解决此问题，如果 Docker 已预安装到 VM 镜像上，你可以选择在创建节点模板时跳过安装 Docker。为此，你可以在 Rancher UI **引擎选项**下的 `Docker 安装 URL` 下拉列表中选择 **无**。 + +
**引擎选项下拉列表**
+ +![引擎选项下拉列表](/img/node-template-engine-options-rke1.png) + +#### 节点池污点 + +如果你没有在节点模板上定义[污点](https://kubernetes.io/docs/concepts/configuration/taint-and-toleration/)，则可以为每个节点池添加污点。将污点添加到节点池的好处是你可以更改节点模板，而不需要先确保污点存在于新模板中。 + +每个污点都将自动添加到节点池中已创建的节点。因此，如果你在已有节点的节点池中添加污点，污点不会应用到已有的节点，但是添加到该节点池中的新节点都将获得该污点。 + +如果污点同时添加到节点模板和节点池中，且添加了相同键的污点效果没有冲突，则所有污点都将添加到节点中。如果存在具有相同键但不同效果的污点，则节点池中的污点将覆盖节点模板中的污点。 + +#### 节点自动替换 + +Rancher 可以自动替换节点池中无法访问的节点。如果节点在指定的时间中处于 Inactive 状态，Rancher 将使用该节点池的节点模板来重新创建节点。 + +:::caution + +自我修复节点池的功能帮助你替换无状态应用的 worker 节点。不建议在 master 节点或连接了持久卷的节点的节点池上启用节点自动替换，因为虚拟机会被临时处理。节点池中的节点与集群断开连接时，其持久卷将被破坏，从而导致有状态应用的数据丢失。 + +::: + +节点自动替换基于 Kubernetes 节点控制器工作。节点控制器定期检查所有节点的状态（可通过 `kube-controller` 的 `--node-monitor-period` 标志配置）。一个节点不可访问时，节点控制器将污染该节点。发生这种情况时，Rancher 将开始其删除倒计时。你可以配置 Rancher 等待删除节点的时间。如果在删除倒计时结束前污点没有被删除，Rancher 将继续删除该节点。Rancher 会根据节点池设置的数量来创建新的节点。 + +#### 启用节点自动替换 + +创建节点池时，你可以指定 Rancher 替换无响应节点的等待时间（以分钟为单位）。 + +1. 在创建或编辑集群的表单中，转到**节点池**。 +1. 转到要启用节点自动替换的节点池。在 **Recreate Unreachable After** 字段中，输入 Rancher 在替换节点之前应该等待节点响应的分钟数。 +1. 填写表单的其余部分以创建或编辑集群。 + +**结果** ：已为节点池启用节点自动替换。 + +#### 禁用节点自动替换 + +你可以执行以下步骤从 Rancher UI 禁用节点自动替换： + +1. 点击 **☰ > 集群管理**。 +1. 在**集群**页面上，转到要禁用节点自动替换的集群，然后单击 **⋮ > 编辑配置**。 +1. 在**节点池**部分中，转到要启用节点自动替换的节点池。在 **Recreate Unreachable After** 字段中，输入 0。 +1. 单击**保存**。 + +**结果**：已禁用节点池的节点自动替换。 + +### 云凭证 + +节点模板可以使用云凭证，来存储用于在云提供商中启动节点的凭证，其优点是： + +- 凭证会存储为更安全的 Kubernetes 密文，而且你无需每次都输入凭证便可编辑节点模板。 + +- 创建云凭证后，你可以重新使用该凭证来创建其他节点模板。 + +- 多个节点模板可以使用相同的云凭证来创建节点池。如果你的密钥被泄露或过期，则可以在一个位置更新云凭证，从而一次更新所有使用该凭证的节点模板。 + +创建云凭证后，用户可以[管理创建的云凭证](../../../../reference-guides/user-settings/manage-cloud-credentials.md)。 + +### 主机驱动 + +如果你找不到想要的主机驱动，你可以在 Rancher 的[内置主机驱动](../../authentication-permissions-and-global-configuration/about-provisioning-drivers/manage-node-drivers.md#激活停用主机驱动)中查看并激活它，也可以[添加自定义主机驱动](../../authentication-permissions-and-global-configuration/about-provisioning-drivers/manage-node-drivers.md#添加自定义主机驱动)。 + +## RKE2 集群 + +Rancher 2.6 支持直接使用 Rancher UI 配置 [RKE2](https://docs.rke2.io/) 集群。RKE2，也称为 RKE Government，是一个完全符合标准的 Kubernetes 发行版，它专注于安全性和合规性。 + +:::note + +对于 RKE2 集群模板，请参阅[此页面](../../manage-clusters/manage-cluster-templates.md#rke2-集群模板)了解更多信息。 + +::: + +### 节点角色 + +RKE2 CLI 公开了 `server` 和 `agent` 两个角色，它们分别代表 Kubernetes 节点角色 `etcd` + `controlplane` 和 `worker`。通过 Rancher 2.6 中的 RKE2 集成，RKE2 节点池可以分配更细粒度的角色，例如 `etcd` 和 `controlplane`。 + +你可以在 RKE2 CLI 中使用标志和节点污染，来控制调度工作负载和 Kubernetes master 节点的位置，从而使用 `etcd`，`controlplane` 和 `worker` 节点功能。这些角色没有在 RKE2 CLI 中实现为第一级角色的原因是，RKE2 被概念化为一组原始构建块，使用 Rancher 等编排系统得到最佳利用。 + +在 Rancher 中实现这三个节点角色，表示 Rancher 管理的 RKE2 集群能够轻松使用为 RKE 集群推荐的相同架构的所有最佳实践。 + +在[推荐的集群架构](../../kubernetes-clusters-in-rancher-setup/checklist-for-production-ready-clusters/recommended-cluster-architecture.md)中，我们概述了每个角色集群应该有多少节点： + +- 至少拥有三个角色为 etcd 的节点，来确保失去一个节点时仍能存活。 +- 至少两个节点具有 controlplane 角色，以实现主组件高可用性。 +- 至少两个具有 worker 角色的节点，用于在节点故障时重新安排工作负载。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/vsphere/create-a-vm-template.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/vsphere/create-a-vm-template.md new file mode 100644 index 00000000000..611765b1fdd --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/vsphere/create-a-vm-template.md @@ -0,0 +1,162 @@ +--- +title: 创建 vSphere 虚拟机模板 +--- + +要重复且可靠地创建虚拟机通常非常困难。VMware vSphere 支持构建可以转换为模板的虚拟机。然后，你可以使用该模板来创建配置相同的虚拟机。Rancher 会在节点池中利用此功能来创建相同的 RKE1 和 RKE2 节点。 + +为了使用模板创建新的虚拟机，Rancher 有虚拟机必须预先安装的[特定要求](#要求)。根据这些要求配置虚拟机后，你需要[准备虚拟机](#准备虚拟机)，然后再[创建模板](#创建模板)。准备工作完成后，虚拟机可以[转换为模板](#转换为模板)并[移动到内容库中](#移动到内容库)，然后 Rancher 节点池就可以使用它了。 + + +## 要求 + +Linux 和 Windows 虚拟机都需要特定工具才能供 vSphere 主机驱动使用。最关键的依赖项是 Linux 的 [cloud-init](https://cloud-init.io/) 和 Windows 的 [cloudbase-init](https://cloudbase.it/cloudbase-init/)。二者都用于通过配置主机名和设置 SSH 访问以及默认 Rancher 用户来配置虚拟机。如果需要其他配置，用户可以根据需要添加其他内容。此外，下面列出了其他要求以供参考。 + +:::note + +如果你有任何特定的防火墙规则或配置，则需要在创建模板之前将其添加到虚拟机。 + +::: + +## Linux 依赖项 + +下面列出了需要在模板上安装的包。不同的发行版对应的名称会略有不同，例如，某些发行版会默认提供。 + +* curl +* wget +* git +* net-tools +* unzip +* apparmor-parser +* ca-certificates +* cloud-init +* cloud-guest-utils +* cloud-image-utils +* growpart (part of cloud-guest-utils) +* cloud-initramfs-growroot +* open-iscsi +* openssh-server +* [open-vm-tools](https://docs.vmware.com/en/VMware-Tools/11.3.0/com.vmware.vsphere.vmwaretools.doc/GUID-8B6EA5B7-453B-48AA-92E5-DB7F061341D1.html) + +## Windows 依赖项 + +模板上需要安装的包如下： + +* Windows 容器功能 +* [cloudbase-init](https://cloudbase.it/cloudbase-init/#download) +* [Docker EE](https://docs.microsoft.com/en-us/virtualization/windowscontainers/quick-start/set-up-environment?tabs=Windows-Server#install-docker) - 仅限 RKE1 + +:::note + +RKE1 和 RKE2 对应的 Windows 模板的配置有所不同： + +- RKE1 使用 Docker，因此任何 RKE1 模板都需要预先安装 Docker EE +- RKE2 不需要 Docker EE，因此不需要安装 + +::: + +## 创建模板 + +你可以手动创建虚拟机，也可以使用[其他替代方法](#手动创建的替代方案)来创建虚拟机。 + +### 手动创建 +1. 在 VMware 中按照[这些说明](https://docs.vmware.com/en/VMware-vSphere/7.0/com.vmware.vsphere.vm_admin.doc/GUID-AE8AFBF1-75D1-4172-988C-378C35C9FAF2.html)手动创建虚拟机。虚拟机运行后，你可以手动安装上面列出的依赖项，以便为 vSphere 主机驱动正确配置虚拟机。 +2. 根据你的特定环境和要求按需定制。 +3. 在创建模板之前进行最后的准备工作。 + +### 手动创建的替代方案 + +下面列出了创建虚拟机的其他替代选项： + +* [VMware PowerCLI](https://developer.vmware.com/powercli) +* [Packer](https://www.packer.io/) +* [SaltStack](https://saltproject.io/) +* [Ansible](https://www.ansible.com/) + +Packer 是一种常用的替代方案。有关将其与 vSphere 一起使用的示例，请参阅[参考](https://github.com/vmware-samples/packer-examples-for-vsphere)。 + +## 准备虚拟机 + +创建具有所有必需依赖项（以及任何其他必需项）的虚拟机后，你必须执行最关键的下一个步骤，即准备将虚拟机转换为模板。此准备步骤会重置关键数据（例如虚拟机主机名、IP 等）以防止这些信息被带入新虚拟机。如果你无法执行此步骤，你也可以创建一个具有相同主机名、IP 地址等的虚拟机。 + +请注意，Linux 和 Windows 对应的准备步骤有所不同。 + +### Linux 准备 + +以下命令将在 Linux 中重置你的虚拟机： + +```bash +# 清理日志。 +if [ -f /var/log/audit/audit.log ]; then + cat /dev/null > /var/log/audit/audit.log +fi +if [ -f /var/log/wtmp ]; then + cat /dev/null > /var/log/wtmp +fi +if [ -f /var/log/lastlog ]; then + cat /dev/null > /var/log/lastlog +fi + +# 清理 udev 规则。 +if [ -f /etc/udev/rules.d/70-persistent-net.rules ]; then + rm /etc/udev/rules.d/70-persistent-net.rules +fi + +# 清理 /tmp 路径。 +rm -rf /tmp/* +rm -rf /var/tmp/* + +# 清理 SSH 主机密钥。 +rm -f /etc/ssh/ssh_host_* + +# 清理 machine-id。 +truncate -s 0 /etc/machine-id +rm /var/lib/dbus/machine-id +ln -s /etc/machine-id /var/lib/dbus/machine-id + +# 清理 shell 历史。 +unset HISTFILE +history -cw +echo > ~/.bash_history +rm -fr /root/.bash_history + +# 截断主机名、主机和 resolv.conf，并将主机名设置为 localhost。 +truncate -s 0 /etc/{hostname,hosts,resolv.conf} +hostnamectl set-hostname localhost + +# 清理 cloud-init。 +cloud-init clean -s -l +``` + +### Windows 准备 + +Windows 有一个名为 [sysprep](https://learn.microsoft.com/en-us/windows-hardware/manufacture/desktop/sysprep--generalize--a-windows-installation?view=windows-11) 的实用程序，用于一般化镜像并重置上述 Linux 项目。命令如下： + +```PowerShell +sysprep.exe /generalize /shutdown /oobe +``` + +## 转换为模板 + +1. 关闭并停止虚拟机。 +2. 右键单击清单列表中的虚拟机，然后选择**模板**。 +3. 点击**转换为模板**。 + +**结果**：流程完成后，即可使用模板。 + +有关将虚拟机转换为模板的更多信息，请参阅 [VMware 指南](https://docs.vmware.com/en/VMware-vSphere/7.0/com.vmware.vsphere.vm_admin.doc/GUID-5B3737CC-28DB-4334-BD18-6E12011CDC9F.html)。 + +## 移动到内容库 + +Rancher 支持使用内容库提供的模板。内容库在 vSphere 中存储和管理内容，还支持发布和共享该内容。 + +以下是有关内容库的一些有用链接： + +* [创建内容库](https://docs.vmware.com/en/VMware-vSphere/7.0/com.vmware.vsphere.vm_admin.doc/GUID-2A0F1C13-7336-45CE-B211-610D39A6E1F4.html) +* [将模板克隆到内容库](https://docs.vmware.com/en/VMware-vSphere/7.0/com.vmware.vsphere.vm_admin.doc/GUID-AC1545F0-F8BA-4CD2-96EB-21B3DFAA1DC1.html) + +## 其他资源 + +以下是可能有用的其他资源列表： + +* [Linux 模板创建教程](https://docs.microsoft.com/en-us/azure/cloud-adoption-framework/manage/hybrid/server/best-practices/vmware-ubuntu-template) +* [Windows 模板创建教程](https://docs.microsoft.com/en-us/azure/cloud-adoption-framework/manage/hybrid/server/best-practices/vmware-windows-template) diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/vsphere/create-credentials.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/vsphere/create-credentials.md new file mode 100644 index 00000000000..8e1905f7ecc --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/vsphere/create-credentials.md @@ -0,0 +1,45 @@ +--- +title: 在 vSphere 控制台中创建凭证 +--- + +本节介绍如何创建 vSphere 用户名和密码。你需要将这些 vSphere 凭证提供给 Rancher，Rancher 才能在 vSphere 中配置资源。 + +下表列出了 vSphere 用户账号所需的权限： + +| 特权组 | 操作 | +|:-------------------------|:-----------------------------------------------------------------------| +| Cns Privileges | Searchable | +| Content library | Read Storage
(Required only if deploying Template from Content Library) | +| Cryptographic operations | Direct Access | +| Datastore | AllocateSpace
Browse
FileManagement (Low level file operations)
UpdateVirtualMachineFiles
UpdateVirtualMachineMetadata | +| 全局 | Set custom attribute | +| 网络 | Assign | +| 资源 | AssignVMToPool | +| 虚拟机 | Config (All)
GuestOperations (All)
Interact (All)
Inventory (All)
Provisioning (All) | +| vSphere 标签 | Assign or Unassign vSphere Tag
Assign or Unassign vSphere Tag on Object | + +以下步骤创建具有所需权限的角色，然后在 vSphere 控制台中将角色分配给新用户： + +1. 在 **vSphere** 控制台中转到 **Administration** 页面。 + +2. 转到 **Roles** 选项卡。 + +3. 创建一个新角色。为新角色命名，并选择上面权限表中列出的权限。 + + ![](/img/rancherroles1.png) + +4. 转到 **Users and Groups** 选项卡。 + +5. 创建一个新用户。填写表单，然后单击 **OK**。请务必记下用户名和密码，因为在 Rancher 中配置节点模板时将需要用到这些信息。 + + ![](/img/rancheruser.png) + +6. 转到 **Global Permissions** 选项卡。 + +7. 创建一个新的全局权限。添加之前创建的用户，并为其分配之前创建的角色。单击 **OK**。 + + ![](/img/globalpermissionuser.png) + + ![](/img/globalpermissionrole.png) + +**结果**：你已拥有 Rancher 所需的操作 vSphere 资源的凭证。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/vsphere/provision-kubernetes-clusters-in-vsphere.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/vsphere/provision-kubernetes-clusters-in-vsphere.md new file mode 100644 index 00000000000..6defefed5a6 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/vsphere/provision-kubernetes-clusters-in-vsphere.md @@ -0,0 +1,110 @@ +--- +title: 在 vSphere 中配置 Kubernetes 集群 +--- + +在本节中，你将学习如何使用 Rancher 在 vSphere 中安装 [RKE](https://rancher.com/docs/rke/latest/en/) Kubernetes 集群。 + +首先，在 Rancher 中设置你的 vSphere 云凭证。然后，使用云凭证创建一个节点模板，Rancher 将使用该模板在 vSphere 中配置节点。 + +然后，在 Rancher 中创建一个 vSphere 集群，并在配置新集群时为集群定义节点池。每个节点池都有一个 etcd、controlplane 或 worker 的 Kubernetes 角色。Rancher 会在新节点上安装 RKE Kubernetes，并为每个节点设置节点池定义的 Kubernetes 角色。 + +有关配置 vSphere 节点模板的详细信息，请参阅 [vSphere 节点模板配置参考](../../../../../reference-guides/cluster-configuration/downstream-cluster-configuration/node-template-configuration/vsphere.md)。 + +有关在 Rancher 中配置 RKE Kubernetes 集群的详细信息，请参阅[集群配置参考](../../../../../reference-guides/cluster-configuration/rancher-server-configuration/rke1-cluster-configuration.md#rke-集群配置文件参考)。 + + +- [vSphere 中的准备工作](#vsphere-中的准备工作) +- [创建 vSphere 集群](#创建-vsphere-集群) + +## vSphere 中的准备工作 + +本节介绍设置 vSphere 的要求，以便 Rancher 可以配置虚拟机和集群。 + +节点模板已使用 vSphere Web Services API 6.5 版本进行记录和测试。 + +### 在 vSphere 中创建凭证 + +在继续创建集群之前，确保你的 vSphere 用户拥有足够的权限。设置节点模板时，模板将需要使用这些 vSphere 凭证。 + +有关如何在 vSphere 中创建具有所需权限的用户的说明，请参阅此[操作指南](create-credentials.md)。这些步骤会产生需要向 Rancher 提供的用户名和密码，从而允许 Rancher 在 vSphere 中配置资源。 + +### 网络权限 + +必须确保运行 Rancher Server 的主机能够建立以下网络连接： + +- 连接到 vCenter Server 上的 vSphere API（通常是端口 443/TCP）。 +- 连接到用于实例化集群虚拟机的所有 ESXi 主机上的 Host API（端口 443/TCP）（*仅在使用 ISO 创建模式时需要*）。 +- 连接到创建的 VM 上的 22/TCP 和 2376/TCP 端口。 + +有关在基础设施提供商上创建节点的端口要求，请参阅[节点网络要求](../../../kubernetes-clusters-in-rancher-setup/node-requirements-for-rancher-managed-clusters.md#网络要求)。 + +### 用于 vSphere API 访问的有效 ESXi 许可证 + +免费的 ESXi 许可证不支持 API 访问。vSphere Server 必须具有有效或评估的 ESXi 许可证。 + +### 具有 DRS 的集群的 VM-VM 关联规则 + +如果你的集群启用了 DRS，建议设置 [VM-VM 关联规则](https://docs.vmware.com/en/VMware-vSphere/6.5/com.vmware.vsphere.resmgmt.doc/GUID-7297C302-378F-4AF2-9BD6-6EDB1E0A850A.html)。这些规则允许分配了 etcd 和 controlplane 角色的虚拟机在分配给不同节点池时，在单独的 ESXi 主机上运行。这种做法可确保单个物理机的故障不会影响这些平面的可用性。 + +## 创建 vSphere 集群 + +1. [创建云凭证](#1-创建云凭证) +2. [使用云凭证创建节点模板](#2-使用云凭证创建节点模板) +3. [使用节点模板创建具有节点池的集群](#3-使用节点模板创建具有节点池的集群) + +### 1. 创建云凭证 + +1. 点击 **☰ > 集群管理**。 +1. 单击**云凭证**。 +1. 单击**创建**。 +1. 单击 **VMware vSphere**。 +1. 输入你的 vSphere 凭证。如需帮助，请参见[节点模板配置参考](../../../../../reference-guides/cluster-configuration/downstream-cluster-configuration/node-template-configuration/vsphere.md)中的**账号访问**。 +1. 单击**创建**。 + +**结果**：已创建用于在集群中配置节点的云凭证。你可以在其他节点模板或集群中复用这些凭证。 + +### 2. 使用云凭证创建节点模板 + +为 vSphere 创建[节点模板](../use-new-nodes-in-an-infra-provider.md#节点模板)会允许 Rancher 在 vSphere 中配置新节点。其他集群可以复用节点模板。 + +1. 点击 **☰ > 集群管理**。 +1. 单击 **RKE1 配置 > 节点模板**。 +1. 单击**创建**。 +1. 单击**添加模板**。 +1. 单击 **vSphere**。 +1. 填写 vSphere 的节点模板。有关填写表格的帮助，请参阅 vSphere 节点模板[配置参考](../../../../../reference-guides/cluster-configuration/downstream-cluster-configuration/node-template-configuration/vsphere.md)。 +1. 单击**创建**。 + +### 3. 使用节点模板创建具有节点池的集群 + +使用 Rancher 在 vSphere 中创建 Kubernetes 集群。 + +1. 在左上角，单击 **☰ > 集群管理**。 +1. 在**集群**页面上，单击**创建**。 +1. 单击 **VMware vSphere**。 +1. 输入**集群名称**并使用你的 vSphere 云凭证。点击**继续**。 +1. 使用**成员角色**为集群配置用户授权。点击**添加成员**添加可以访问集群的用户。使用**角色**下拉菜单为每个用户设置权限。 +1. 使用**集群选项**选择要安装的 Kubernetes 版本、要使用的网络提供商，以及是否启用项目网络隔离。要查看更多集群选项，请单击**显示高级选项**。如需获取配置集群的帮助，请参阅 [RKE 集群配置参考](../../../../../reference-guides/cluster-configuration/rancher-server-configuration/rke1-cluster-configuration.md)。 +1. 如果你想稍后动态配置持久存储或其他基础设施，你需要修改集群 YAML 文件来启用 vSphere 云提供商。有关更多信息，请参阅[树内 vSphere cloud provider 文档](../../../../../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-cloud-providers/configure-in-tree-vsphere.md)和[树外 vSphere cloud provider 文档](../../../../../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-cloud-providers/configure-out-of-tree-vsphere.md)。 +1. 将一个或多个节点池添加到你的集群。每个节点池都使用节点模板来配置新节点。有关节点池的更多信息，包括为节点分配 Kubernetes 角色的最佳实践，请参阅[本节](../use-new-nodes-in-an-infra-provider.md#节点池)。 +1. 检查并确认你的选项。然后单击**创建**。 + +**结果**： + +你已创建集群，集群的状态是**配置中**。Rancher 已在你的集群中。 + +当集群状态变为 **Active** 后，你可访问集群。 + +**Active** 状态的集群会分配到两个项目： + +- `Default`：包含 `default` 命名空间 +- `System`：包含 `cattle-system`，`ingress-nginx`，`kube-public` 和 `kube-system` 命名空间。 + + +## 可选的后续步骤 + +创建集群后，你可以通过 Rancher UI 访问集群。最佳实践建议你设置以下访问集群的备用方式： + +- **通过 kubectl CLI 访问你的集群**：按照[这些步骤](../../../../new-user-guides/manage-clusters/access-clusters/use-kubectl-and-kubeconfig.md#在工作站使用-kubectl-访问集群)在你的工作站上使用 kubectl 访问集群。在这种情况下，你将通过 Rancher Server 的身份验证代理进行身份验证，然后 Rancher 会让你连接到下游集群。此方法允许你在没有 Rancher UI 的情况下管理集群。 +- **通过 kubectl CLI 使用授权的集群端点访问你的集群**：按照[这些步骤](../../../../new-user-guides/manage-clusters/access-clusters/use-kubectl-and-kubeconfig.md#直接使用下游集群进行身份验证)直接使用 kubectl 访问集群，而无需通过 Rancher 进行身份验证。我们建议设置此替代方法来访问集群，以便在无法连接到 Rancher 时访问集群。 +- **配置存储**：有关如何使用 Rancher 在 vSphere 中配置存储的示例，请参阅[本节](../../../manage-clusters/provisioning-storage-examples/provisioning-storage-examples.md)。要在 vSphere 中动态配置存储，你必须启用 vSphere 云提供商。有关更多信息，请参阅[树内 vSphere cloud provider 文档](../../../../../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-cloud-providers/configure-in-tree-vsphere.md)和[树外 vSphere cloud provider 文档](../../../../../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-cloud-providers/configure-out-of-tree-vsphere.md)。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/vsphere/vsphere.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/vsphere/vsphere.md new file mode 100644 index 00000000000..396f6370108 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/vsphere/vsphere.md @@ -0,0 +1,60 @@ +--- +title: 创建 vSphere 集群 +description: 使用 Rancher 创建 vSphere 集群。集群可能包括具有不同属性的 VM 组，这些属性可用于细粒度控制节点的大小。 +--- + + + + + +import YouTube from '@site/src/components/YouTube' + +你可以结合使用 Rancher 与 vSphere，从而在本地体验云环境的操作。 + +Rancher 可以在 vSphere 中配置节点并在其上安装 Kubernetes。在 vSphere 中创建 Kubernetes 集群时，Rancher 首先与 vCenter API 通信来配置指定数量的虚拟机。然后在它们之上安装 Kubernetes。 + +vSphere 集群可能由多组具有不同属性（例如内存或 vCPU 数量）的 VM 组成。这种分组允许对每个 Kubernetes 角色的节点大小进行细粒度控制。 + +## Rancher v2.3 中的 vSphere 增强功能 + +我们更新了 vSphere 节点模板，使你可以通过以下增强功能在本地体验云操作： + +### 自我修复的节点池 + +使用 Rancher 配置 vSphere 节点的最大优势之一，是允许你在本地集群中使用 Rancher 的自我修复节点池（也称为[节点自动替换功能](../use-new-nodes-in-an-infra-provider.md#节点自动替换)）。自我修复节点池的功能帮助你替换无状态应用的 worker 节点。当 Rancher 使用节点模板配置节点时，Rancher 可以自动替换无法访问的节点。 + +:::caution + +不建议在 master 节点或连接了持久卷的节点的节点池上启用节点自动替换，因为虚拟机会被临时处理。节点池中的节点与集群断开连接时，其持久卷将被破坏，从而导致有状态应用的数据丢失。 + +::: + +### 实例和调度的动态填充选项 + +vSphere 的节点模板已更新。当你使用 vSphere 凭证创建节点模板时，该模板会自动填充你在 vSphere 控制台中可以访问的相同的虚拟机配置选项。 + +要填充的字段设置需要满足[先决条件](provision-kubernetes-clusters-in-vsphere.md#vsphere-中的准备工作)。 + +### 更多支持的操作系统 + +你可以使用任何支持 `cloud-init` 的操作系统来配置 VM。[cloud config](https://cloudinit.readthedocs.io/en/latest/topics/examples.html) 仅支持 YAML 格式。 + +### v2.3.3 节点模板功能的视频介绍 + +在这段 YouTube 视频中，我们演示了如何使用新的节点模板在本地环境体验云环境一样的操作。 + + + +## 创建 vSphere 集群 + +在[本节](provision-kubernetes-clusters-in-vsphere.md)中，你将学习如何使用 Rancher 在 vSphere 中安装 [RKE](https://rancher.com/docs/rke/latest/en/) Kubernetes 集群。 + +## 配置存储 + +有关如何使用 Rancher 在 vSphere 中配置存储的示例，请参阅[本节](../../../manage-clusters/provisioning-storage-examples/vsphere-storage.md)。要在 vSphere 中动态配置存储，你必须启用 vSphere 云提供商。请参阅[树内 vSphere 配置](../../../kubernetes-clusters-in-rancher-setup/set-up-cloud-providers/configure-in-tree-vsphere.md)和[树外 vSphere 配置](../../../kubernetes-clusters-in-rancher-setup/set-up-cloud-providers/configure-out-of-tree-vsphere.md)。 + +## 启用 vSphere 云提供商 + +在 Rancher 中设置云提供商时，Rancher Server 可以自动为集群配置新的基础设施，包括新节点或持久存储设备。 + +有关启用 vSphere 云提供商的详细信息，请参阅[树内 vSphere 配置](../../../kubernetes-clusters-in-rancher-setup/set-up-cloud-providers/configure-in-tree-vsphere.md)和[树外 vSphere 配置](../../../kubernetes-clusters-in-rancher-setup/set-up-cloud-providers/configure-out-of-tree-vsphere.md)。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/manage-clusters/access-clusters/access-clusters.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/manage-clusters/access-clusters/access-clusters.md new file mode 100644 index 00000000000..ba82844f0f4 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/manage-clusters/access-clusters/access-clusters.md @@ -0,0 +1,65 @@ +--- +title: 访问集群 +--- + + + + + +本节介绍可以用来访问 Rancher 管理的集群的工具。 + +有关如何授予用户访问集群的权限的信息，请参阅[将用户添加到集群](add-users-to-clusters.md)部分。 + +有关 RBAC 的更多信息，请参阅[本节](../../authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/manage-role-based-access-control-rbac.md)。 + +有关如何设置认证的信息，请参阅[本节](../../authentication-permissions-and-global-configuration/authentication-config/authentication-config.md)。 + +## Rancher UI 中的集群 + +我们提供了多种通过 Rancher UI 查看和管理集群的方法。 + +### 集群页面 + +从 **☰** 菜单访问**集群**页面： + +1. 单击 **☰**。 +1. 选择**集群管理**。 + +你还可以通过单击 Rancher UI **主页**集群表格上方的**管理**按钮来访问**集群**页面。 + +在**集群**页面上，选择每行末尾的 **⁝** 以查看包含以下选项的子菜单： + +* [Kubectl Shell](use-kubectl-and-kubeconfig.md) +* 下载 KubeConfig +* 将 KubeConfig 复制到剪切板 +* 编辑配置 +* 查看 YAML +* 下载 YAML + +### 集群仪表板 + +在**集群**页面上，选择每行末尾的**浏览**按钮查看该集群的**集群仪表板**。你还可以通过单击表中集群的名称，然后单击**集群**页面上的**浏览**按钮来查看仪表板。 + +也可以通过单击集群名称从 Rancher UI **主页**访问**集群仪表板**。 + +你还可以从顶部导航栏中的 **☰** 访问**集群仪表板**： + +1. 单击 **☰**。 +1. 从**浏览集群**菜单中选择集群的名称。 + +**集群仪表板**列出了集群相关的信息，例如节点数量、内存使用情况、事件和资源。 + +## kubectl + +你可以使用 Kubernetes 命令行工具 [kubectl](https://kubernetes.io/docs/reference/kubectl/overview/)，来管理你的集群。使用 kubectl 有两种选择： + +- **Rancher kubectl shell**：通过启动 Rancher UI 中可用的 kubectl shell 与集群交互。此选项不需要你进行任何配置操作。有关详细信息，请参阅[使用 kubectl Shell 访问集群](use-kubectl-and-kubeconfig.md)。 +- **终端远程连接**：你也可以通过在本地桌面上安装 [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/)，然后将集群的 kubeconfig 文件复制到本地 `~/.kube/config` 目录来与集群交互。有关更多信息，请参阅[使用 kubectl 和 kubeconfig 文件访问集群](use-kubectl-and-kubeconfig.md)。 + +## Rancher CLI + +你可以下载 Rancher 自己的命令行工具 [Rancher CLI](../../../../reference-guides/cli-with-rancher/cli-with-rancher.md) 来控制你的集群。这个 CLI 工具可以直接与不同的集群和项目进行交互，或者向它们传递 `kubectl` 命令。 + +## Rancher API + +最后，你可以通过 Rancher API 与集群进行交互。在使用 API 之前，你必须先获取 [API 密钥](../../../../reference-guides/user-settings/api-keys.md)。要查看 API 对象的不同资源字段和操作，请打开 API UI（API UI 可以通过单击 Rancher UI 对象的**在 API 中查看**访问）。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/manage-clusters/access-clusters/add-users-to-clusters.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/manage-clusters/access-clusters/add-users-to-clusters.md new file mode 100644 index 00000000000..290bf7ecfca --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/manage-clusters/access-clusters/add-users-to-clusters.md @@ -0,0 +1,74 @@ +--- +title: 将用户添加到集群 +--- + +To provide a user access to view certain cluster-level resources and create new projects, assign the user a **Cluster Membership**. Cluster members can create projects and manage resources in those projects. However, not all resources, namespaces and workloads in a cluster are accessible by cluster members. + +:::tip + +如果你想为用户提供对集群内 _特定_ 项目的访问权限，请参见[添加项目成员](../../../new-user-guides/add-users-to-projects.md)。 + +::: + +你可以在两种情况下添加集群成员： + +- 将成员添加到新集群 + + 你可以在创建集群时将成员添加到集群（推荐）。 + +- [向现有集群添加成员](#编辑集群成员) + + 配置集群后，你始终可以向集群添加成员。 + +## 编辑集群成员 + +集群管理员可以编辑集群的成员，控制哪些 Rancher 用户可以访问集群以及他们可以使用哪些功能。 + +1. 点击 **☰ > 集群管理**。 +1. 转到要添加成员的集群，然后单击 **⋮ > 编辑配置**。 +1. 在**成员角色**选项卡中，单击**添加成员**。 +1. 搜索要添加到集群的用户或组。 + + :::note Notes: + + - At least 2 characters must be typed in the search box for results to appear. + - Users can be searched based on their username or display name. + - Search is prefix-based (e.g., a user named `Stan Dard` will appear when searching for `Sta`, but not when searching for `Dar`) and case-sensitive. + + ::: + + 如果配置了外部身份验证： + + - 在你键入时，Rancher 会从你的[外部身份验证](../../authentication-permissions-and-global-configuration/authentication-config/authentication-config.md)源返回用户。 + + :::note 使用 AD 但找不到你的用户？ + + 你的搜索属性配置可能存在问题。请参阅[配置 Active Directory 身份验证：步骤 5](../../../new-user-guides/authentication-permissions-and-global-configuration/authentication-config/configure-active-directory.md)。 + + ::: + + - 你可以在下拉菜单中添加组，而不是单个用户。下拉列表仅列出你（登录用户）所属的组。 + + :::note + + 如果你以本地用户身份登录，外部用户不会显示在你的搜索结果中。有关详细信息，请参阅[外部身份验证配置和主体用户](../../authentication-permissions-and-global-configuration/authentication-config/authentication-config.md#外部认证配置和用户主体)。 + + ::: + +1. 分配用户或组的**集群**角色。 + + [什么是集群角色？](../../../new-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/cluster-and-project-roles.md) + + :::tip + + 对于自定义角色，你可以修改可分配的单个角色列表。 + + - 要将角色添加到列表中，请[添加自定义角色](../../../new-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/custom-roles.md)。 + - 要从列表中删除角色，请[锁定/解锁角色](../../../new-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/locked-roles.md)。 + + ::: + +**结果**：已将选中的用户添加到集群中。 + +- 要撤销集群成员资格，请选择用户并单击**删除**。此操作会删除成员资格，而不会删除用户。 +- 要修改集群中的用户角色，请将其从集群中删除，然后使用修改后的角色重新添加用户。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/manage-clusters/access-clusters/authorized-cluster-endpoint.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/manage-clusters/access-clusters/authorized-cluster-endpoint.md new file mode 100644 index 00000000000..587d3b1fc3b --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/manage-clusters/access-clusters/authorized-cluster-endpoint.md @@ -0,0 +1,49 @@ +--- +title: 授权集群端点的工作原理 +--- + +本文介绍 kubectl CLI、kubeconfig 文件和授权集群端点如何协同工作，使你可以直接访问下游 Kubernetes 集群，而无需通过 Rancher Server 进行身份验证。本文旨在为[设置 kubectl 以直接访问集群的说明](use-kubectl-and-kubeconfig.md#直接使用下游集群进行身份验证)提供背景信息和上下文。 + +## Kubeconfig 文件说明 + +kubeconfig 文件是与 kubectl 命令行工具（或其他客户端）结合使用时用于配置 Kubernetes 访问的文件。 + +kubeconfig 文件及其内容特定于各个集群。你可以从 Rancher 的**集群**页面进行下载： + +1. 点击左上角的 **☰**。 +1. 选择**集群管理**。 +1. 找到要下载其 kubeconfig 的集群，然后选择行末尾的 **⁝**。 +1. 从子菜单中选择**下载 KubeConfig**。 + +在 Rancher 中可以访问的每个集群都需要一个单独的 kubeconfig 文件。 + +下载 kubeconfig 文件后，你将能够使用 kubeconfig 文件及其 Kubernetes [上下文](https://kubernetes.io/docs/reference/kubectl/cheatsheet/#kubectl-context-and-configuration)访问下游集群。 + +如果管理员[关闭了 kubeconfig 令牌生成](../../../../api/api-tokens.md#在生成的-kubeconfig-中禁用令牌)，则 kubeconfig 文件要求 [Rancher CLI](../../../../reference-guides/cli-with-rancher/rancher-cli.md) 存在于你的 PATH 中。 + +## RKE 集群的两种身份验证方法 + +如果集群不是 [RKE 集群](../../launch-kubernetes-with-rancher/launch-kubernetes-with-rancher.md)，kubeconfig 文件只允许你以一种方式访问​​集群，即通过 Rancher Server 进行身份验证，然后 Rancher 允许你在集群上运行 kubectl 命令。 + +对于 RKE 集群，kubeconfig 文件允许你通过两种方式进行身份验证： + +- **通过 Rancher Server 身份验证代理**：Rancher 的身份验证代理会验证你的身份，然后将你连接到要访问的下游集群。 +- **直接使用下游集群的 API Server**：RKE 集群默认启用授权集群端点。此端点允许你使用 kubectl CLI 和 kubeconfig 文件访问下游 Kubernetes 集群，且 RKE 集群默认启用该端点。在这种情况下，下游集群的 Kubernetes API server 通过调用 Rancher 设置的 webhook（`kube-api-auth` 微服务）对你进行身份验证。 + +第二种方法（即直接连接到集群的 Kubernetes API server）非常重要，因为如果你无法连接到 Rancher，这种方法可以让你访问下游集群。 + +要使用授权集群端点，你需要配置 kubectl，从而使用 Rancher 在创建 RKE 集群时生成的 kubeconfig 文件中的额外 kubectl 上下文。该文件可以从 Rancher UI 的**集群**视图中下载，配置 kubectl 的说明在[此页面](use-kubectl-and-kubeconfig.md#直接使用下游集群进行身份验证)。 + +[架构介绍](../../../../reference-guides/rancher-manager-architecture/communicating-with-downstream-user-clusters.md)也详细解释了这些与下游 Kubernetes 集群通信的方法，并介绍了 Rancher 的工作原理以及 Rancher 如何与下游集群通信的详细信息。 + +## 关于 kube-api-auth 身份验证 Webhook + +`kube-api-auth` 微服务是为[授权集群端点](../../../../reference-guides/rancher-manager-architecture/communicating-with-downstream-user-clusters.md#4-授权集群端点)提供用户认证功能而部署的。当你使用 `kubectl` 访问下游集群时，集群的 Kubernetes API server 会使用 `kube-api-auth` 服务作为 webhook 对你进行身份验证。 + +在集群配置期间会部署 `/etc/kubernetes/kube-api-authn-webhook.yaml` 文件，并使用 `--authentication-token-webhook-config-file=/etc/kubernetes/kube-api-authn-webhook.yaml` 配置 `kube-apiserver`。这会将 `kube-apiserver` 配置为通过查询 `http://127.0.0.1:6440/v1/authenticate` 来确定持有者 token 的身份验证。 + +`kube-api-auth` 的调度规则如下： + +| 组件 | nodeAffinity nodeSelectorTerms | nodeSelector | 容忍度 | +| -------------------- | ------------------------------------------ | ------------ | ------------------------------------------------------------------------------ | +| kube-api-auth | `beta.kubernetes.io/os:NotIn:windows`
`node-role.kubernetes.io/controlplane:In:"true"` | none | `operator:Exists` | diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/manage-clusters/access-clusters/use-kubectl-and-kubeconfig.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/manage-clusters/access-clusters/use-kubectl-and-kubeconfig.md new file mode 100644 index 00000000000..327e035803b --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/manage-clusters/access-clusters/use-kubectl-and-kubeconfig.md @@ -0,0 +1,105 @@ +--- +title: "使用 Kubectl 和 kubeconfig 访问集群" +description: "了解如何通过 kubectl Shell 使用 kubectl，或通过 kubectl CLI 和 kubeconfig 文件，来访问和管理 Kubernetes 集群。kubeconfig 文件用于配置对 Kubernetes 的访问。当你使用 Rancher 创建集群时，Rancher 会自动为你的集群创建 kubeconfig。" +--- + +本文介绍如何通过 Rancher UI 或工作站来使用 kubectl 操作下游 Kubernetes 集群。 + +有关使用 kubectl 的更多信息，请参阅 [Kubernetes 文档：kubectl 概述](https://kubernetes.io/docs/reference/kubectl/overview/)。 + +## 在 Rancher UI 中使用 kubectl shell 访问集群 + +你可以通过登录 Rancher 并在 UI 中打开 kubectl shell 来访问和管理你的集群。你无需进一步配置。 + +1. 点击 **☰ > 集群管理**。 +1. 转到要使用 kubectl 访问的集群，然后单击 **Explore**。 +1. 在顶部导航菜单中，单击 **Kubectl Shell** 按钮。使用打开的窗口与你的 Kubernetes 集群进行交互。 + +## 在工作站使用 kubectl 访问集群 + +本节介绍如何下载集群的 kubeconfig 文件、从工作站启动 kubectl 以及访问下游集群。 + +这种访问集群的替代方法允许你在不使用 Rancher UI 的情况下通过 Rancher 进行身份验证并管理集群。 + +:::note 先决条件： + +以下说明假设你已经创建了一个 Kubernetes 集群，并且已将 kubectl 安装在工作站上。有关安装 kubectl 的帮助，请参阅官方 [Kubernetes 文档](https://kubernetes.io/docs/tasks/tools/install-kubectl/)。 + +::: + +1. 点击左上角的 **☰**。 +1. 选择**集群管理**。 +1. 找到要下载其 kubeconfig 的集群，然后选择行末尾的 **⁝**。 +1. 从子菜单中选择**下载 KubeConfig**。 +1. 将 YAML 文件保存在本地计算机上。将文件移动到 `~/.kube/config`。注意：kubectl 用于 kubeconfig 文件的默认位置是 `~/.kube/config`。但是你也可以运行类似以下的命令，使用 `--kubeconfig` 标志指定任何其他目录： +``` +kubectl --kubeconfig /custom/path/kube.config get pods +``` +1. 从工作站启动 kubectl。使用它与 Kubernetes 集群进行交互。 + + +## 使用 kubectl 创建的资源的注意事项 + +Rancher 会发现并显示由 `kubectl` 创建的资源。但是在发现资源的时候，这些资源可能没有包括所有必须的注释。如果资源已经使用 Rancher UI/API 进行操作（例如，扩展工作负载），但是由于缺少注释，资源的重新创建可能会触发。只有在首次对发现的资源进行操作时，这种情况才会发生。 + +## 直接使用下游集群进行身份验证 + +本节旨在帮助你设置访问 [Rancher-launched 集群的替代方法](../../launch-kubernetes-with-rancher/launch-kubernetes-with-rancher.md)。 + +此方法仅适用于启用了[授权集群端点](../../../../reference-guides/rancher-manager-architecture/communicating-with-downstream-user-clusters.md#4-授权集群端点)的 RKE2 和 K3s集群。在 Rancher 创建集群时，Rancher 会生成一个 kubeconfig 文件，其中包含用于访问集群的额外 kubectl 上下文。该上下文允许你使用 kubectl 通过下游集群进行身份验证，而无需通过 Rancher 进行身份验证。有关授权集群端点如何工作的详细说明，请参阅[此页面](authorized-cluster-endpoint.md)。 + +在 RKE2 和 K3s 集群上，你需要[手动启用](../../kubernetes-clusters-in-rancher-setup/register-existing-clusters.md#对-rke2-和-k3s-集群的授权集群端点支持)授权集群端点。 + +我们的最佳实践是使用此方法来访问 RKE2 和 K3s集群。这样，万一你无法连接到 Rancher，你仍然可以访问该集群。 + +:::note 先决条件： + +以下步骤假设你已经创建了一个 Kubernetes 集群，并按照步骤[从工作站使用 kubectl 连接到集群](#在工作站使用-kubectl-访问集群)。 + +::: + +要在下载的 kubeconfig 文件中查找上下文的名称，请运行： + +``` +kubectl config get-contexts --kubeconfig /custom/path/kube.config +CURRENT NAME CLUSTER AUTHINFO NAMESPACE +* my-cluster my-cluster user-46tmn + my-cluster-controlplane-1 my-cluster-controlplane-1 user-46tmn +``` + +在此示例中，当你将 `kubectl` 与第一个上下文 `my-cluster` 一起使用时，你将通过 Rancher Server 进行身份验证。 + +使用第二个上下文 `my-cluster-controlplane-1`，你将使用授权集群端点进行身份验证，直接与下游 RKE2/K3s 集群通信。 + +我们建议使用具有授权集群端点的负载均衡器。有关详细信息，请参阅[推荐的架构](../../../../reference-guides/rancher-manager-architecture/architecture-recommendations.md#授权集群端点架构)。 + +现在你已经有了直接使用集群进行身份验证所需的上下文名称，你可以在运行 kubectl 命令时将上下文名称作为选项传入。根据你的集群是否定义了 FQDN，这些命令会有所不同。以下几节提供了示例。 + +当 `kubectl` 正常工作时，它确认你可以绕过 Rancher 的身份验证代理访问集群。 + +## 直接连接到定义了 FQDN 的集群 + +如果集群定义了 FQDN，将会创建一个引用 FQDN 的上下文。上下文将命名为 `-fqdn`。当你想在没有 Rancher 的情况下使用 `kubectl` 访问这个集群时，你需要使用这个上下文。 + +假设 kubeconfig 文件位于 `~/.kube/config`： + +``` +kubectl --context -fqdn get nodes +``` +直接引用 kubeconfig 文件的位置： +``` +kubectl --kubeconfig /custom/path/kube.config --context -fqdn get pods +``` + +## 直接连接到未定义 FQDN 的集群 + +如果集群没有定义 FQDN，则会创建额外的上下文来引用 controlplane 中每个节点的 IP 地址。每个上下文将被命名为 `-`。当你想在没有 Rancher 的情况下使用 `kubectl` 访问这个集群时，你需要使用这个上下文。 + +假设 kubeconfig 文件位于 `~/.kube/config`： +``` +kubectl --context - get nodes +``` +直接引用 kubeconfig 文件的位置： +``` +kubectl --kubeconfig /custom/path/kube.config --context - get pods +``` diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/manage-clusters/clean-cluster-nodes.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/manage-clusters/clean-cluster-nodes.md new file mode 100644 index 00000000000..cd96b8d1f39 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/manage-clusters/clean-cluster-nodes.md @@ -0,0 +1,378 @@ +--- +title: 从节点中移除 Kubernetes 组件 +description: 了解从 Rancher 启动的 Kubernetes 集群中删除节点时的集群清理过程。了解删除了的内容，以及如何手动进行操作 +--- + +本文介绍如何断开 Rancher 创建的 Kubernetes 集群中的一个节点，并删除该节点中的所有 Kubernetes 组件。此过程允许你将节点用于其他用途。 + +在通过 Rancher 在基础设施提供商的新节点上安装 Kubernetes 时，会创建资源（容器/虚拟网络接口）和配置项（证书/配置文件）。 + +从 Rancher 启动的 Kubernetes 集群中移除节点时（前提是它们处于 `Active` 状态），这些资源会被自动清理，唯一需要的操作是重启节点。如果节点变得不可访问并且无法自动清理进程时，请先执行我们提供的步骤，然后该节点才能重新添加到集群。 + +## 移除了什么？ + +清理使用 Rancher 配置的节点时，会根据要删除的集群节点类型移除以下组件： + +| 移除的组件 | [由基础设施提供商托管的节点][1] | [自定义节点][2] | [托管集群][3] | [注册节点][4] | +|--------------------------------------------------------------------------------|----------------------------------------------|-------------------|---------------------|-----------------------| +| Rancher deployment 命名空间（默认：`cattle-system`） | ✓ | ✓ | ✓ | ✓ | +| 由 Rancher 标记的 `serviceAccount`、`clusterRoles` 和 `clusterRoleBindings` | ✓ | ✓ | ✓ | ✓ | +| 标签、注释和终结器 | ✓ | ✓ | ✓ | ✓ | +| Rancher Deployment | ✓ | ✓ | ✓ | | +| 主机、集群、项目和用户的自定义资源定义 (CRD) | ✓ | ✓ | ✓ | | +| 在 `management.cattle.io` API Group 下创建的所有资源 | ✓ | ✓ | ✓ | | +| Rancher v2.x 创建的所有 CRD | ✓ | ✓ | ✓ | | + +[1]: ../launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/use-new-nodes-in-an-infra-provider.md +[2]: ../../../reference-guides/cluster-configuration/rancher-server-configuration/use-existing-nodes/use-existing-nodes.md +[3]: ../kubernetes-clusters-in-rancher-setup/set-up-clusters-from-hosted-kubernetes-providers/set-up-clusters-from-hosted-kubernetes-providers.md +[4]: ../../../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/register-existing-clusters.md + +## 通过 Rancher UI 删除集群中的节点 + +如果节点处于 `Active` 状态，删除集群中的节点会触发清理节点的进程。完成自动清理后请重启节点，以确保所有非持久性数据已正确删除。 + +**重启节点**： + +``` +# 使用重启 +$ sudo reboot + +# 使用关机 +$ sudo shutdown -r now +``` + +## 手动移除集群中的 Rancher 组件 + +当节点不可达并已从集群中移除时，由于该节点不可达，则无法触发自动清理过程。请按照以下步骤手动删除 Rancher 组件。 + +:::danger + +下面列出的命令将删除节点中的数据。在执行命令之前，由于数据将会丢失，请确保你已经备份了要保留的文件。 + +::: + +### 移除注册集群中的 Rancher 组件 + +移除注册集群中的 Rancher 的过程略有不同。你可以选择在 Rancher UI 中简单地删除集群，也可以运行脚本从节点中删除 Rancher 组件。两个选项的删除效果是一样的。 + +将注册集群分离 Rancher 后，集群的工作负载将不受影响，你可以使用与集群注册到 Rancher 之前相同的方法来访问集群。 + + + + +:::danger + +此过程将删除你的集群数据。在执行命令之前，由于数据将会丢失，请确保你已经备份了要保留的文件。 + +::: + +使用 Rancher UI（或 API）删除注册集群后，会发生以下事件： + +1. Rancher 创建一个 `serviceAccount`，用于删除集群中的 Rancher 组件。此账号分配了 [clusterRole](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#role-and-clusterrole) 和 [clusterRoleBinding](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#rolebinding-and-clusterrolebinding) 权限，这些权限是删除 Rancher 组件所必需的。 + +1. Rancher 会使用 `serviceAccount` 调度并运行一个 [job](https://kubernetes.io/docs/concepts/workloads/controllers/jobs-run-to-completion/)，以将 Rancher 组件从集群中清除。该 job 还将 `serviceAccount` 及其角色作为依赖引用，因此该 job 在完成之前会删除它们。 + +1. 已从集群中移除 Rancher。然而，集群仍然存在，运行着原生版本的 Kubernetes。 + +**结果**：已删除[移除了什么](#移除了什么)章节中为注册集群列出的所有组件。 + + + + +你可以运行脚本，而不是使用 Rancher UI 来清理已注册的集群节点。 + +:::note 先决条件： + +安装 [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/)。 + +::: + +1. 打开浏览器并导航到 [GitHub](https://github.com/rancher/rancher/blob/master/cleanup/user-cluster.sh)，然后下载 `user-cluster.sh`。 + +1. 在 `user-cluster.sh` 所在的目录下运行以下命令，使脚本可执行： + + ``` + chmod +x user-cluster.sh + ``` + +1. **仅限离线环境**：打开 `user-cluster.sh` 并将 `yaml_url` 替换为 `user-cluster.yml` 中的 URL。 + + 如果你没有使用离线环境，请跳过此步骤。 + +1. 在同一目录中，运行脚本并提供 `rancher/rancher-agent` 镜像版本，该版本应与用于管理集群的 Rancher 版本相同（``）： + + :::tip + + 你可以添加 `-dry-run` 标志来预览脚本的结果，但不进行更改。 + ``` + ./user-cluster.sh rancher/rancher-agent: + ``` + + ::: + +**结果**：脚本已运行。已删除[移除了什么](#移除了什么)章节中为注册集群列出的所有组件。 + + + + +## 清理节点 + + + + +:::note + +For instructions on cleaning nodes in RKE2 clusters that weren't deployed by Rancher, see the [official RKE2 documentation](https://docs.rke2.io/install/uninstall) on uninstalling clusters. + +::: + +你需要从 Rancher 提供的 RKE2 节点中删除以下组件： + +* rancher-system-agent，用于连接 Rancher 并安装和管理 RKE2。 +* RKE2 本身。 + +### 删除 rancher-system-agent + +要删除 rancher-system-agent，请运行 [system-agent-uninstall.sh](https://github.com/rancher/system-agent/blob/main/system-agent-uninstall.sh) 脚本： + +``` +curl https://raw.githubusercontent.com/rancher/system-agent/main/system-agent-uninstall.sh > system-agent-uninstall.sh +sudo sh system-agent-uninstall.sh +``` + +### 删除 RKE2 + +要删除 RKE2，请运行节点上已存在的 `rke2-uninstall` 脚本： + +``` +sudo rke2-uninstall.sh +``` + + + + +你需要从 Rancher 提供的 K3s 节点中删除以下组件： + +* rancher-system-agent：连接 Rancher 并安装和管理 K3s。 +* K3s 本身。 + +### 删除 rancher-system-agent + +要删除 rancher-system-agent，请运行 [system-agent-uninstall.sh](https://github.com/rancher/system-agent/blob/main/system-agent-uninstall.sh) 脚本： + +``` +curl https://raw.githubusercontent.com/rancher/system-agent/main/system-agent-uninstall.sh > system-agent-uninstall.sh +sudo sh system-agent-uninstall.sh +``` + +### 删除 K3s + +要删除 K3s，请运行节点上已存在的 `k3s-uninstall` 脚本： + +``` +sudo k3s-uninstall.sh +``` + + + + +### 目录和文件 + +以下目录在将节点添加到集群时使用，应将该目录删除。你可以使用 `rm -rf /directory_name` 来删除目录。 + +:::important + +节点分配的角色决定了出现在节点上的目录。 + +::: + + + + +| 目录 | +|------------------------------| +| `/etc/ceph` | +| `/etc/cni` | +| `/etc/kubernetes` | +| `/etc/rancher` | +| `/opt/cni` | +| `/run/calico` | +| `/run/flannel` | +| `/run/secrets/kubernetes.io` | +| `/var/lib/calico` | +| `/var/lib/cni` | +| `/var/lib/etcd` | +| `/var/lib/kubelet` | +| `/var/lib/rancher` | +| `/var/lib/weave` | +| `/var/log/containers` | +| `/var/log/pods` | +| `/var/run/calico` | + +**清理目录**： + +```shell +rm -rf /etc/ceph \ + /etc/cni \ + /etc/kubernetes \ + /etc/rancher \ + /opt/cni \ + /run/calico \ + /run/flannel \ + /run/secrets/kubernetes.io \ + /var/lib/calico \ + /var/lib/cni \ + /var/lib/etcd \ + /var/lib/kubelet \ + /var/lib/rancher \ + /var/lib/weave \ + /var/log/containers \ + /var/log/pods \ + /var/run/calico +``` + + + + +| 目录 | +|------------------------------| +| `/etc/ceph` | +| `/etc/cni` | +| `/etc/kubernetes` | +| `/etc/rancher` | +| `/etc/systemd/system/k3s` | +| `/opt/cni` | +| `/run/calico` | +| `/run/flannel` | +| `/run/secrets/kubernetes.io` | +| `/usr/local/bin/k3s` | +| `/var/lib/calico` | +| `/var/lib/cni` | +| `/var/lib/etcd` | +| `/var/lib/kubelet` | +| `/var/lib/rancher` | +| `/var/lib/weave` | +| `/var/log/containers` | +| `/var/log/pods` | +| `/var/run/calico` | + +**清理目录**： + +```shell +rm -rf /etc/ceph \ + /etc/cni \ + /etc/kubernetes \ + /etc/rancher \ + /etc/systemd/system/k3s \ + /opt/cni \ + /run/calico \ + /run/flannel \ + /run/secrets/kubernetes.io \ + /usr/local/bin/k3s \ + /var/lib/calico \ + /var/lib/cni \ + /var/lib/etcd \ + /var/lib/kubelet \ + /var/lib/rancher \ + /var/lib/weave \ + /var/log/containers \ + /var/log/pods \ + /var/run/calico +``` + + + + +### 网络接口和 iptables + +其余两个更改/配置的组件是（虚拟）网络接口和 iptables 规则。两者都对节点不持久，这意味着它们将在节点重新启动后被清除。要删除这些组件，建议重新启动它们。 + +**重启节点**： + +``` +# 使用重启 +$ sudo reboot + +# 使用关机 +$ sudo shutdown -r now +``` + +如果你想了解更多关于（虚拟）网络接口或 iptables 规则的信息，请参阅下面的具体内容。 + +### 网络接口 + +:::note + +节点所在的集群所配置的网络提供商决定了节点上将出现的接口。 + +::: + +| 接口 | +|--------------------------------------------| +| `flannel.1` | +| `cni0` | +| `tunl0` | +| `caliXXXXXXXXXXX` (random interface names) | +| `vethXXXXXXXX` (random interface names) | + +**列出所有接口**： + +``` +# 使用 ip +ip address show + +# 使用 ifconfig +ifconfig -a +``` + +**删除接口**： + +``` +ip link delete interface_name +``` + +### Iptables + +:::note + +节点所在的集群所配置的网络提供商决定了节点上将出现的链。 + +::: + +iptables 规则用于将流量从容器路由到容器。创建的规则不是持久性的，因此重新启动节点会将 iptables 恢复到原始状态。 + +| 链 | +|--------------------------------------------------| +| `cali-failsafe-in` | +| `cali-failsafe-out` | +| `cali-fip-dnat` | +| `cali-fip-snat` | +| `cali-from-hep-forward` | +| `cali-from-host-endpoint` | +| `cali-from-wl-dispatch` | +| `cali-fw-caliXXXXXXXXXXX` (random chain names) | +| `cali-nat-outgoing` | +| `cali-pri-kns.NAMESPACE` (chain per namespace) | +| `cali-pro-kns.NAMESPACE` (chain per namespace) | +| `cali-to-hep-forward` | +| `cali-to-host-endpoint` | +| `cali-to-wl-dispatch` | +| `cali-tw-caliXXXXXXXXXXX` (random chain names) | +| `cali-wl-to-host` | +| `KUBE-EXTERNAL-SERVICES` | +| `KUBE-FIREWALL` | +| `KUBE-MARK-DROP` | +| `KUBE-MARK-MASQ` | +| `KUBE-NODEPORTS` | +| `KUBE-SEP-XXXXXXXXXXXXXXXX` (random chain names) | +| `KUBE-SERVICES` | +| `KUBE-SVC-XXXXXXXXXXXXXXXX` (random chain names) | + +**列出所有 iptables 规则**： + +``` +iptables -L -t nat +iptables -L -t mangle +iptables -L +``` diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/manage-clusters/create-kubernetes-persistent-storage/create-kubernetes-persistent-storage.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/manage-clusters/create-kubernetes-persistent-storage/create-kubernetes-persistent-storage.md new file mode 100644 index 00000000000..4c4f0aaee77 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/manage-clusters/create-kubernetes-persistent-storage/create-kubernetes-persistent-storage.md @@ -0,0 +1,79 @@ +--- +title: "Kubernetes 持久存储： 卷和存储类" +description: "了解在 Kubernetes 中创建持久存储的两种方法：持久卷和存储类" +--- + + + + + +在部署需要保​​留数据的应用时，你需要创建持久存储。持久存储允许你在运行应用的 pod 之外存储应用数据。即使运行应用的 pod 发生故障，这种存储方式也能让你保留应用数据。 + +本文假设你已了解 Kubernetes 的持久卷、持久卷声明和存储类的概念。如需更多信息，请参阅[存储的工作原理](manage-persistent-storage/about-persistent-storage.md)部分。 + +## 先决条件 + +设置持久存储需要`管理卷`的[角色](../../authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/cluster-and-project-roles.md#项目角色参考)。 + +如果你要为云集群配置存储，则存储和集群主机必须使用相同的云提供商。 + +要使用 Rancher 配置新存储，则必须启用云提供商。有关启用云提供商的详细信息，请参阅[此页面](../../kubernetes-clusters-in-rancher-setup/set-up-cloud-providers/set-up-cloud-providers.md)。 + +如果要将现有的持久存储连接到集群，则不需要启用云提供商。 + +## 设置现有存储 + +设置现有存储的总体流程如下： + +1. 设置你的持久存储。可以是云存储或你自己的存储。 +2. 添加引用持久存储的持久卷 (PV)。 +3. 添加引用 PV 的持久卷声明 (PVC)。 +4. 将 PVC 挂载为工作负载中的卷。 + +有关详细信息和先决条件，请参阅[此页面](manage-persistent-storage/set-up-existing-storage.md)。 + +## 在 Rancher 中动态配置新存储 + +配置新存储的总体流程如下： + +1. 添加一个 StorageClass 并将它配置为使用你的存储提供商。StorageClass 可以引用云存储或你自己的存储。 +2. 添加引用存储类的持久卷声明 (PVC)。 +3. 将 PVC 挂载为工作负载的卷。 + +有关详细信息和先决条件，请参阅[此页面](manage-persistent-storage/dynamically-provision-new-storage.md)。 + +## Longhorn 存储 + +[Longhorn](https://longhorn.io/) 是一个轻量级、可靠、易用的 Kubernetes 分布式块存储系统。 + +Longhorn 是免费的开源软件。Longhorn 最初由 Rancher Labs 开发，现在正在作为云原生计算基金会的沙盒项目进行开发。它可以通过 Helm、kubectl 或 Rancher UI 安装在任何 Kubernetes 集群上。 + +如果你有块存储池，Longhorn 可以帮助你为 Kubernetes 集群提供持久存储，而无需依赖云提供商。有关 Longhorn 功能的更多信息，请参阅[文档](https://longhorn.io/docs/latest/what-is-longhorn/)。 + +Rancher v2.5 简化了在 Rancher 管理的集群上安装 Longhorn 的过程。详情请参见[本页面](../../../../integrations-in-rancher/longhorn/longhorn.md)。 + +## 配置存储示例 + +我们提供了如何使用 [NFS](../provisioning-storage-examples/nfs-storage.md)， [vSphere](../provisioning-storage-examples/vsphere-storage.md)，和 [Amazon 的 EBS](../provisioning-storage-examples/persistent-storage-in-amazon-ebs.md) 来配置存储的示例。 + +## GlusterFS 卷 + +在将数据存储在 GlusterFS 卷上的集群中，你可能会遇到重启 `kubelet` 后 pod 无法挂载卷的问题。有关避免此情况发生的详细信息，请参阅[此页面](manage-persistent-storage/about-glusterfs-volumes.md)。 + +## iSCSI 卷 + +在将数据存储在 iSCSI 卷上的 [Rancher 启动的 Kubernetes 集群](../../launch-kubernetes-with-rancher/launch-kubernetes-with-rancher.md)中，你可能会遇到 kubelet 无法自动连接 iSCSI 卷的问题。有关解决此问题的详细信息，请参阅[此页面](manage-persistent-storage/install-iscsi-volumes.md)。 + +## hostPath 卷 + +在创建 hostPath 卷之前，你需要在集群配置中设置 [extra_bind](https://rancher.com/docs/rke/latest/en/config-options/services/services-extras/#extra-binds/)。这会将路径作为卷安装在你的 kubelet 中，可用于工作负载中的 hostPath 卷。 + +## 将 vSphere Cloud Provider 从树内迁移到树外 + +Kubernetes 正在逐渐不在树内维护云提供商。vSphere 有一个树外云提供商，可通过安装 vSphere 云提供商和云存储插件来使用。 + +有关如何从树内 vSphere 云提供商迁移到树外，以及如何在迁移后管理现有虚拟机，请参阅[此页面](../../kubernetes-clusters-in-rancher-setup/set-up-cloud-providers/configure-out-of-tree-vsphere.md)。 + +## 相关链接 + +- [Kubernetes 文档: 存储](https://kubernetes.io/docs/concepts/storage/) diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/manage-clusters/create-kubernetes-persistent-storage/manage-persistent-storage/about-glusterfs-volumes.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/manage-clusters/create-kubernetes-persistent-storage/manage-persistent-storage/about-glusterfs-volumes.md new file mode 100644 index 00000000000..69dd77f4d7e --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/manage-clusters/create-kubernetes-persistent-storage/manage-persistent-storage/about-glusterfs-volumes.md @@ -0,0 +1,37 @@ +--- +title: GlusterFS 卷 +--- + +:::note + +本文仅适用于 [RKE 集群](../../../launch-kubernetes-with-rancher/launch-kubernetes-with-rancher.md)。 + +::: + +在将数据存储在 GlusterFS 卷上的集群中，你可能会遇到重启 `kubelet` 后 pod 无法挂载卷的问题。`kubelet` 的日志将显示 `transport endpoint is not connected`。为了避免这种情况，你可以在集群中将 `systemd-run` 二进制文件挂载到 `kubelet` 容器中。在更改集群配置之前有两个要求： + +- 该节点需要安装了 `systemd-run` 二进制文件（可以通过在每个集群节点上运行 `which systemd-run` 命令来检查）。 +- `systemd-run` 二进制文件需要与 hyperkube 镜像所基于的 Debian OS 兼容（可以通过在每个集群节点上运行以下命令来检查，请将镜像标签替换为你想要的 Kubernetes 版本）： + +``` +docker run -v /usr/bin/systemd-run:/usr/bin/systemd-run --entrypoint /usr/bin/systemd-run rancher/hyperkube:v1.16.2-rancher1 --version +``` + +:::caution + +在更新 Kubernetes YAML 以挂载 `systemd-run` 二进制文件之前，请确保在集群节点上安装了 `systemd` 包。如果在绑定挂载创建到你的 Kubernetes YAML _之前_ 未安装此包，Docker 将自动在每个节点上创建目录和文件，并且不允许包安装成功。 + +::: + +``` +services: + kubelet: + extra_binds: + - "/usr/bin/systemd-run:/usr/bin/systemd-run" +``` + +集群完成配置后，你可以通过查找以下日志来检查 `kubelet` 容器日志记录，从而查看该功能是否已激活： + +``` +Detected OS with systemd +``` diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/manage-clusters/create-kubernetes-persistent-storage/manage-persistent-storage/about-persistent-storage.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/manage-clusters/create-kubernetes-persistent-storage/manage-persistent-storage/about-persistent-storage.md new file mode 100644 index 00000000000..6e744c1295f --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/manage-clusters/create-kubernetes-persistent-storage/manage-persistent-storage/about-persistent-storage.md @@ -0,0 +1,72 @@ +--- +title: 持久存储的工作原理 +--- + +持久卷 (PV) 是 Kubernetes 集群中的一块存储，而持久卷声明 (PVC) 是对存储的请求。 + +在 Kubernetes 中使用持久存储有两种方法： + +- 使用现有的持久卷 +- 动态配置新的持久卷 + +要使用现有 PV，你的应用需要使用已绑定到 PV 的 PVC，并且 PV 应包含 PVC 所需的最少资源。 + +对于动态存储配置，你的应用需要使用绑定到存储类的 PVC。存储类包含配置新持久卷的授权。 + +![设置新的和现有的持久存储](/img/rancher-storage.svg) + +有关更多信息，请参阅[关于存储的官方 Kubernetes 文档](https://kubernetes.io/docs/concepts/storage/volumes/)。 + + +## 关于持久卷声明 + +持久卷声明 (PVC) 是从集群请求存储资源的对象，类似于你的 deployment 用于兑换存储访问的凭证。PVC 以卷的形式挂载到工作负载中，以便工作负载可以声明其指定的持久存储份额。 + +要访问持久存储，Pod 必须有挂载为卷的 PVC。此 PVC 让你的 deployment 应用将其数据存储在外部位置，这样，如果 pod 发生故障，就可以用新的 pod 替换它并继续访问其外部存储的数据。 + +每个 Rancher 项目都包含你创建的 PVC 列表，可从**资源 > 工作负载 > 卷**中查看。你可以在将来创建 deployment 时复用这些 PVC。 + +### 新的和现有的持久存储都需要 PVC + +无论工作负载打算使用现有存储，还是需要根据需求动态配置新存储，pod 都需要 PVC 才能使用持久存储。 + +如果你为工作负载设置现有存储，则工作负载会挂载引用一个 PV 的 PVC，该 PV 对应现有的存储基础设施。 + +如果工作负载需要请求新的存储，则工作负载会挂载引用一个存储类的 PVC，该存储类能创建新 PV 及其底层存储基础设施。 + +Rancher 允许你在项目中创建任意数量的 PVC。 + +你可以在创建 deployment 时将 PVC 挂载到 deployment 中，也可以在创建 deployment 后在 deployment 运行的时候将 PVC 挂载到 deployment 中。 + +## 使用 PVC 和 PV 设置现有存储 + +你的 pod 可以将数据存储在[卷](https://kubernetes.io/docs/concepts/storage/volumes/)中，但如果 pod 发生故障，该数据就会丢失。为了解决这个问题，Kubernetes 提供了持久卷 (PV)。PV 是 Kubernetes 资源，这些资源对应于你的 pod 可以访问的外部存储磁盘或文件系统。如果一个 pod 崩溃，它的替代 pod 可以访问持久存储中的数据，而不会丢失任何数据。 + +PV 可以是你本地或托管的云上（Amazon EBS 或 Azure Disk）物理磁盘或文件系统。 + +在 Rancher 中创建持久卷不会创建存储卷。它只创建映射到现有卷的 Kubernetes 资源。因此，在你可以将持久卷创建为 Kubernetes 资源之前，你必须先配置存储。 + +:::note 重要提示： + +PV 是在集群级别创建的，这意味着在多租户集群中，有权访问不同命名空间的团队可以访问同一个 PV。 + +::: + +### 将 PV 绑定到 PVC + +当 pod 设置为使用持久存储时，pod 会挂载持久卷声明 (PVC)，PVC 的挂载方式与其他 Kubernetes 卷相同。在创建每个 PVC 时，Kubernetes master 将 PVC 视为对存储的请求，并将其绑定到与 PVC 的最低资源要求相匹配的 PV。并非每个 PVC 都保证绑定到 PV。详情请参阅 Kubernetes [文档](https://kubernetes.io/docs/concepts/storage/persistent-volumes/)。 + +> 如果没有匹配的卷，则声明将一直保持为未绑定状态。当匹配的卷可用时，声明将会被绑定。例如，配置有许多 50Gi PV 的集群不会匹配请求 100Gi 的 PVC。PVC 可以在 100Gi PV 添加到集群时进行绑定。 + +换句话说，你可以创建无限量的 PVC，但只有在 Kubernetes master 可以找到满足 PVC 所需的磁盘空间量的 PV 时，PVC 才会绑定到 PV。 + +要动态配置新存储，挂载在 pod 中的 PVC 对应的必须是存储类而不是持久卷。 + +## 使用 PVC 和存储类配置新存储 + +存储类允许你动态创建 PV，而无需先在基础设施提供商中创建持久存储。 + +例如，如果工作负载绑定到 PVC 并且 PVC 引用 Amazon EBS 存储类，则存储类可以动态创建 EBS 卷和相应的 PV。 + +然后 Kubernetes master 会将新创建的 PV 绑定到你的工作负载的 PVC，从而允许你的工作负载使用持久存储。 + diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/manage-clusters/create-kubernetes-persistent-storage/manage-persistent-storage/dynamically-provision-new-storage.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/manage-clusters/create-kubernetes-persistent-storage/manage-persistent-storage/dynamically-provision-new-storage.md new file mode 100644 index 00000000000..0d0b638fd10 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/manage-clusters/create-kubernetes-persistent-storage/manage-persistent-storage/dynamically-provision-new-storage.md @@ -0,0 +1,87 @@ +--- +title: 在 Rancher 中动态配置新存储 +--- + +本文介绍如何为 Rancher 中的工作负载配置新的持久存储。 + +本节假设你了解 Kubernetes 的存储类和持久卷声明的概念。如需更多信息，请参阅[存储的工作原理](about-persistent-storage.md)。 + +新存储通常由 Amazon EBS 等云提供商提供。但是，新存储不一定要在云中。 + +如果你有一个块存储池并且不想使用云提供商，你可以使用 Longhorn 为 Kubernetes 集群提供持久存储。详情请参见[本页面](../../../../../integrations-in-rancher/longhorn.md)。 + +要为你的工作负载配置新存储，请执行以下步骤： + +1. [添加一个存储类并将其配置为使用你的存储](#1-添加一个存储类并将其配置为使用你的存储) +2. [为使用 StatefulSet 部署的 Pod 使用存储类](#2-为使用-statefulset-部署的-pod-使用存储类) + +## 先决条件 + +- 设置持久存储需要`管理卷`的[角色](../../../authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/cluster-and-project-roles.md#项目角色参考)。 +- 如果你要为云集群配置存储，则存储和集群主机必须使用相同的云提供商。 +- 必须启用云提供商。有关启用云提供商的详细信息，请参阅[此页面](../../../kubernetes-clusters-in-rancher-setup/set-up-cloud-providers/set-up-cloud-providers.md)。 +- 确保你的存储卷插件可以启用。 + +默认情况下启用以下存储卷插件： + +| 名称 | 插件 | +--------|---------- +| Amazon EBS Disk | `aws-ebs` | +| AzureFile | `azure-file` | +| AzureDisk | `azure-disk` | +| Google Persistent Disk | `gce-pd` | +| Longhorn | `flex-volume-longhorn` | +| VMware vSphere Volume | `vsphere-volume` | +| 本地 | `local` | +| 网络文件系统 | `nfs` | +| hostPath | `host-path` | + +如果你的存储卷插件没有在上述列表中，你需要[使用功能开关来启用不受支持的存储驱动](../../../../advanced-user-guides/enable-experimental-features/unsupported-storage-drivers.md)。 + +## 1. 添加一个存储类并将其配置为使用你的存储 + +这些步骤描述了如何在集群级别设置存储类： + +1. 点击 **☰ > 集群管理**。 +1. 转到要动态配置持久存储卷的集群，然后单击 **Explore**。 +1. 单击**存储 > 存储类**。 +1. 单击**创建**。 +1. 输入存储类的名称。 +1. 从 **Provisioner** 下拉列表中，选择要用于动态配置存储卷的服务。例如，如果你有一个 Amazon EC2 集群并且想要使用云存储，请使用 `Amazon EBS Disk`。 +1. 在**参数**选项卡中，填写服务用于动态配置存储卷所需的信息。每个卷插件都需要不同的信息来动态配置存储卷。有关如何获取此信息的帮助，请参阅服务文档。 +1. 单击**创建**。 + +**结果**：存储类可供 PVC 使用。 + +有关存储类参数的完整信息，请参阅官方 [Kubernetes 文档](https://kubernetes.io/docs/concepts/storage/storage-classes/#parameters)。 + +## 2. 为使用 StatefulSet 部署的 Pod 使用存储类 + +StatefulSet 管理 Pod 的部署和扩展，同时为每个 Pod 维护一个粘性标识。在这个 StatefulSet 中，我们将配置一个 VolumeClaimTemplate。StatefulSet 管理的每个 Pod 都将部署一个基于此 VolumeClaimTemplate 的 PersistentVolumeClaim。PersistentVolumeClaim 将引用我们创建的 StorageClass。因此，在部署 StatefulSet 管理的每个 Pod 时，都会使用 PersistentVolumeClaim 中定义的 StorageClass 来绑定到动态配置的存储。 + +1. 点击 **☰ > 集群管理**。 +1. 转到要将 StorageClass 用于工作负载的集群，然后单击 **Explore**。 +1. 在左侧导航栏中，单击**工作负载**。 +1. 单击**创建**。 +1. 单击 **StatefulSet**。 +1. 在**卷声明模板**选项卡上，单击**添加声明模板**。 +1. 输入持久卷的名称。 +1. 在**存储类**字段中，选择将为此 StatefulSet 管理的 pod 动态配置存储的 StorageClass。 +1. 在**挂载点**字段中，输入工作负载将用于访问卷的路径。 +1. 点击**启动**。 + +**结果**：StatefulSet 管理的每个 Pod 部署完成后，都会向 Kubernetes master 请求指定的磁盘空间。如果在部署工作负载时具有指定资源的 PV 是可用的，则 Kubernetes master 会将 PV 绑定到具有兼容 PVC 的 Pod。 + +要将 PVC 附加到现有工作负载， + +1. 点击 **☰ > 集群管理**。 +1. 转到要将 StorageClass 用于工作负载的集群，然后单击 **Explore**。 +1. 在左侧导航栏中，单击**工作负载**。 +1. 单击 **⋮ > 编辑配置**，转到使用由 StorageClass 配置的存储的工作负载。 +1. 在**卷声明模板**中，单击**添加声明模板**。 +1. 输入持久卷名称。 +1. 在**存储类**字段中，选择将为此 StatefulSet 管理的 pod 动态配置存储的 StorageClass。 +1. 在**挂载点**字段中，输入工作负载将用于访问卷的路径。 +1. 单击**保存**。 + +**结果**：工作负载将向 Kubernetes master 请求指定的磁盘空间。如果在部署工作负载时具有指定资源的 PV 是可用的，则 Kubernetes master 会将 PV 绑定到 PVC。否则，Rancher 将配置新的持久存储。 \ No newline at end of file diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/manage-clusters/create-kubernetes-persistent-storage/manage-persistent-storage/install-iscsi-volumes.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/manage-clusters/create-kubernetes-persistent-storage/manage-persistent-storage/install-iscsi-volumes.md new file mode 100644 index 00000000000..aaa2d24f67f --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/manage-clusters/create-kubernetes-persistent-storage/manage-persistent-storage/install-iscsi-volumes.md @@ -0,0 +1,62 @@ +--- +title: iSCSI 卷 +--- + +在将数据存储在 iSCSI 卷上的 [Rancher 启动的 Kubernetes 集群](../../../launch-kubernetes-with-rancher/launch-kubernetes-with-rancher.md)中，你可能会遇到 kubelet 无法自动连接 iSCSI 卷的问题。成此问题的原因很可能是 iSCSI 启动器工具不兼容。你可以在每个集群节点上安装 iSCSI 启动器工具来解决此问题。 + +将数据存储到 iSCSI 卷的由 Rancher 启动的 Kubernetes 集群使用 [iSCSI 启动器工具](http://www.open-iscsi.com/)，该工具嵌入在 kubelet 的 `rancher/hyperkube` Docker 镜像中。该工具从每个 kubelet（即 _initiator_）发现并发起与 iSCSI 卷（即 _target_）的会话。但是，在某些情况下，initiator 和 target 上安装的 iSCSI 启动器工具的版本可能不匹配，从而导致连接失败。 + +如果你遇到此问题，你可以在集群中的每个节点上安装启动器工具来解决该问题。你可以通过登录到集群节点并输入以下其中一个命令来安装 iSCSI 启动器工具： + +| 平台 | 包名 | 安装命令 | +| ------------- | ----------------------- | -------------------------------------- | +| Ubuntu/Debian | `open-iscsi` | `sudo apt install open-iscsi` | +| RHEL | `iscsi-initiator-utils` | `yum install iscsi-initiator-utils -y` | + + +在节点上安装启动器工具后，编辑集群的 YAML，编辑 kubelet 配置以挂载 iSCSI 二进制文件和配置，如下面的示例所示。 + +:::note 注意事项 + +- 在更新 Kubernetes YAML 以挂载 iSCSI 二进制文件和配置之前，请确保已将 `open-iscsi`（deb）或 `iscsi-initiator-utils`（yum）安装到你的集群节点。如果在绑定挂载创建到你的 Kubernetes YAML _之前_ 未安装此包，Docker 将自动在每个节点上创建目录和文件，并且不允许包安装成功。 + +- 下面的示例 YAML 不适用于 K3s，仅适用于 RKE 集群。由于 K3s kubelet 不在容器中运行，因此不需要添加额外的绑定。但是，所有 iSCSI 工具仍必须安装在你的 K3s 节点上。 + +::: + +``` +services: + kubelet: + extra_binds: + - "/etc/iscsi:/etc/iscsi" + - "/sbin/iscsiadm:/sbin/iscsiadm" +``` + +如果你使用的是 RHEL 7.9，你需要挂载文件 `/usr/lib64/libcrypto.so.10`，如下例所示。 + +``` +services: + kubelet: + extra_binds: + - "/etc/iscsi:/etc/iscsi" + - "/sbin/iscsiadm:/sbin/iscsiadm" + - "/usr/lib64/libcrypto.so.10:/usr/lib/libcrypto.so.10" +``` + +如果你使用的是 RHEL 8.6，你需要挂载文件 `/usr/lib64/libcrypto.so.1.1`，如下例所示。 + +``` +services: + kubelet: + extra_binds: + - "/etc/iscsi:/etc/iscsi" + - "/sbin/iscsiadm:/sbin/iscsiadm" + - "/usr/lib64/libcrypto.so.1.1:/usr/lib/libcrypto.so.1.1" +``` + + +:::tip + +要验证 iscsiadm 是否正常工作，你可以在任何节点上运行命令 `docker exec kubelet iscsiadm --version`。 + +::: diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/manage-clusters/create-kubernetes-persistent-storage/manage-persistent-storage/set-up-existing-storage.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/manage-clusters/create-kubernetes-persistent-storage/manage-persistent-storage/set-up-existing-storage.md new file mode 100644 index 00000000000..2b5575f7794 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/manage-clusters/create-kubernetes-persistent-storage/manage-persistent-storage/set-up-existing-storage.md @@ -0,0 +1,85 @@ +--- +title: 设置现有存储 +--- + +本文介绍如何在 Rancher 中为工作负载设置现有的持久存储。 + +:::note + +本节假设你了解 Kubernetes 的持久卷和持久卷声明的概念。如需更多信息，请参阅[存储的工作原理](about-persistent-storage.md)。 + +::: + +要设置存储，请执行以下步骤： + +1. [设置持久存储](#1-设置持久存储)。 +2. [添加一个引用持久存储的 PersistentVolume](#2-添加一个引用持久存储的-persistentvolume)。 +3. [为使用 StatefulSet 部署的 Pod 使用存储类](#3-为使用-statefulset-部署的-pod-使用存储类) + +## 先决条件 + +- 要将持久卷创建为 Kubernetes 资源，你必须具有`管理卷`的[角色。](../../../authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/cluster-and-project-roles.md#项目角色参考) +- 如果你要为云集群配置存储，则存储和集群主机必须使用相同的云提供商。 + +## 1. 设置持久存储 + +在 Rancher 中创建持久卷不会创建存储卷。它只创建映射到现有卷的 Kubernetes 资源。因此，在你可以将持久卷创建为 Kubernetes 资源之前，你必须先配置存储。 + +设置持久存储设备的步骤会因你的基础设施而异。我们提供了使用 [vSphere](../../provisioning-storage-examples/vsphere-storage.md)、[NFS](../../provisioning-storage-examples/nfs-storage.md) 或 [Amazon EBS ](../../provisioning-storage-examples/persistent-storage-in-amazon-ebs.md)设置存储的示例。 + +如果你有一个块存储池并且不想使用云提供商，你可以使用 Longhorn 为 Kubernetes 集群提供持久存储。详情请参见[本页面](../../../../../integrations-in-rancher/longhorn.md)。 + +## 2. 添加一个引用持久存储的 PersistentVolume + +这些步骤描述了如何在 Kubernetes 的集群级别设置 PersistentVolume。 + +1. 点击 **☰ > 集群管理**。 +1. 转到要添加持久卷的集群，然后单击 **Explore**。 +1. 在左侧导航栏中，单击**存储 > 持久卷**。 +1. 单击**创建**。 +1. 输入持久卷的**名称**。 +1. 为正在使用的磁盘类型或服务选择**卷插件**。将存储添加到由云提供商托管的集群时，请使用云提供商的云存储插件。例如，如果你有一个 Amazon EC2 集群并且想要使用云存储，则必须使用 `Amazon EBS 磁盘`卷插件。 +1. 输入卷的**容量**（单位：GB）。 +1. 填写**插件配置**表单。每个插件类型都需要磁盘类型供应商的信息。有关每个插件的表单和所需信息的帮助，请参阅插件的供应商文档。 +1. 可选：在**自定义**表单中，配置[访问模式](https://kubernetes.io/docs/concepts/storage/persistent-volumes/#access-modes)。此选项设置可以访问卷的节点数量，以及节点的读/写权限。[Kubernetes 文档](https://kubernetes.io/docs/concepts/storage/persistent-volumes/#access-modes)中的表格列出了插件支持的访问模式。 +1. 可选：在**自定义**表单中，配置[挂载选项](https://kubernetes.io/docs/concepts/storage/persistent-volumes/#mount-options)。每个卷插件都允许你在安装过程中指定其他命令行选项。请查阅每个插件的供应商文档以获取可用的挂载选项。 +1. 单击**创建**。 + +**结果**：已创建你的新持久卷。 + + +## 3. 为使用 StatefulSet 部署的 Pod 使用存储类 + +StatefulSet 管理 Pod 的部署和扩展，同时为每个 Pod 维护一个粘性标识。在这个 StatefulSet 中，我们将配置一个 VolumeClaimTemplate。StatefulSet 管理的每个 Pod 都将部署一个基于此 VolumeClaimTemplate 的 PersistentVolumeClaim。PersistentVolumeClaim 将引用我们创建的 PersistentVolume。因此，在部署 StatefulSet 管理的每个 Pod 时，都会绑定一个 PersistentVolumeClaim 中定义的 PersistentVolume。 + +你可以在工作负载创建期间或之后为 StatefulSet 配置存储。 + +以下步骤描述了如何将现有存储分配给新的 StatefulSet： + +1. 点击 **☰ > 集群管理**。 +1. 转到要为 StatefulSet 配置存储的集群，然后单击 **Explore**。 +1. 在左侧导航栏中，单击**工作负载 > StatefulSets**。 +1. 单击**创建**。 +1. 选择要部署工作负载的命名空间。 +1. 输入 StatefulSet 的名称。 +1. 在**卷声明模板**选项卡上，单击**添加声明模板**。 +1. 单击**使用现有的持久卷**。 +1. 在**持久卷**字段中，选择你创建的持久卷。 +1. 在**挂载点**字段中，输入工作负载将用于访问卷的路径。 +1. 点击**启动**。 + +**结果**：当工作负载被部署时，它会向 Kubernetes master 请求指定的磁盘空间。如果在部署工作负载时具有指定资源的 PV 是可用的，则 Kubernetes master 会将 PV 绑定到 PVC。 + +以下步骤描述了如何将持久存储分配给现有工作负载： + +1. 点击 **☰ > 集群管理**。 +1. 转到要为 StatefulSet 配置存储的集群，然后单击 **Explore**。 +1. 在左侧导航栏中，单击**工作负载 > StatefulSets**。 +1. 转到要添加持久存储的工作负载。单击 **⋮ > 编辑**。 +1. 在**卷声明模板**选项卡上，单击**添加声明模板**。 +1. 单击**使用现有的持久卷**。 +1. 在**持久卷**字段中，选择你创建的持久卷。 +1. 在**挂载点**字段中，输入工作负载将用于访问卷的路径。 +1. 点击**启动**。 + +**结果**：工作负载将向 Kubernetes master 请求指定的磁盘空间。如果在部署工作负载时具有指定资源的 PV 是可用的，则 Kubernetes master 会将 PV 绑定到 PVC。 \ No newline at end of file diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/manage-clusters/create-kubernetes-persistent-storage/manage-persistent-storage/use-external-ceph-driver.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/manage-clusters/create-kubernetes-persistent-storage/manage-persistent-storage/use-external-ceph-driver.md new file mode 100644 index 00000000000..31f13278ae2 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/manage-clusters/create-kubernetes-persistent-storage/manage-persistent-storage/use-external-ceph-driver.md @@ -0,0 +1,420 @@ +--- +title: 使用外部 Ceph 驱动 +--- + +本文介绍如何在 RKE2 集群中使用外部 Ceph 驱动。如果你使用的是 RKE，则需要执行其他步骤。详情请参阅[本节](#在-rke-中使用-ceph-驱动)。 + + +## 要求 + +确保 ceph-common 和 xfsprogs 软件包安装在 SLE worker 节点上。 + +## 在 RKE 中使用 Ceph 驱动 + +以下资源与 RKE 集群完全兼容，但需要为 RKE 执行额外的 kubelet 配置。 + +在 RKE 集群上，kubelet 组件在 Docker 容器中运行，默认情况下无法像 rbd 和 libceph 一样访问主机的内核模块。 + +为了解决这个限制，你可以在 worker 节点上运行 `modprobe rbd`，或者配置 kubelet 容器以将主机中的 `/lib/modules` 目录自动挂载到容器中。 + +对于 kubelet 配置，在 RKE 集群配置之前，将以下内容放入 `cluster.yml` 文件中。你稍后还可以在 Rancher UI 中通过单击**编辑集群 > 以 YAML 文件编辑**并重新启动 worker 节点来修改 `cluster.yml`。 + +```yaml +services: + kubelet: + extra_binds: + - '/lib/modules:/lib/modules:ro' +``` + +有关 `extra_binds` 指令的更多信息，请参阅[本节](https://rancher.com/docs/rke/latest/en/config-options/services/services-extras/#extra-binds)。 + +## 在 RKE2 集群上安装 ceph-csi 驱动 + +:::note + +只有动态 RBD 配置需要执行这些步骤。 + +::: + +有关 `ceph-csi-rbd` chart 的更多信息，请参阅[此页面](https://github.com/ceph/ceph-csi/blob/devel/charts/ceph-csi-rbd/README.md)。 + +要获取有关 SES 集群的详细信息，请运行： + +``` +ceph mon dump +``` + +查看输出： + +``` +dumped monmap epoch 3 +epoch 3 +fsid 79179d9d-98d8-4976-ab2e-58635caa7235 +last_changed 2021-02-11T10:56:42.110184+0000 +created 2021-02-11T10:56:22.913321+0000 +min_mon_release 15 (octopus) +0: [v2:10.85.8.118:3300/0,v1:10.85.8.118:6789/0] mon.a +1: [v2:10.85.8.123:3300/0,v1:10.85.8.123:6789/0] mon.b +2: [v2:10.85.8.124:3300/0,v1:10.85.8.124:6789/0] mon.c +``` + +稍后你将需要 fsid 和 mon 地址值。 + +## 使用 Helm 安装 ceph-csi 驱动 + +运行以下命令： + +``` +helm repo add ceph-csi https://ceph.github.io/csi-charts +helm repo update +helm search repo ceph-csi -l +helm inspect values ceph-csi/ceph-csi-rbd > ceph-csi-rbd-values.yaml +``` + +修改 `ceph-csi-rbd-values.yaml` 文件并只保留所需的更改： + +```yaml +# ceph-csi-rbd-values.yaml +csiConfig: + - clusterID: "79179d9d-98d8-4976-ab2e-58635caa7235" + monitors: + - "10.85.8.118:6789" + - "10.85.8.123:6789" + - "10.85.8.124:6789" +provisioner: + name: provisioner + replicaCount: 2 +``` + +确保可以从 RKE2 集群访问 ceph 监视器（例如通过 ping）。 + +``` +kubectl create namespace ceph-csi-rbd +helm install --namespace ceph-csi-rbd ceph-csi-rbd ceph-csi/ceph-csi-rbd --values ceph-csi-rbd-values.yaml +kubectl rollout status deployment ceph-csi-rbd-provisioner -n ceph-csi-rbd +helm status ceph-csi-rbd -n ceph-csi-rbd +``` + +如果你想直接通过 Helm 修改配置，则可以使用 `ceph-csi-rbd-values.yaml` 文件并调用： + +``` +helm upgrade \ + --namespace ceph-csi-rbd ceph-csi-rbd ceph-csi/ceph-csi-rbd --values ceph-csi-rbd-values.yaml +``` + +## 创建 RBD Ceph 资源 + +``` +# 创建一个 ceph 池： +ceph osd pool create myPool 64 64 + +# 创建一个块设备池： +rbd pool init myPool + +# 创建一个块设备镜像： +rbd create -s 2G myPool/image + +# 创建一个块设备用户并记录密钥： +ceph auth get-or-create-key client.myPoolUser mon "allow r" osd "allow class-read object_prefix rbd_children, allow rwx pool=myPool" | tr -d '\n' | base64 +QVFDZ0R5VmdyRk9KREJBQTJ5b2s5R1E2NUdSWExRQndhVVBwWXc9PQ== + +# Base64 加密 ceph 用户 myPoolUser： +echo "myPoolUser" | tr -d '\n' | base64 +bXlQb29sVXNlcg== + +# 创建一个块设备管理员并记录密钥： +ceph auth get-or-create-key client.myPoolAdmin mds 'allow *' mgr 'allow *' mon 'allow *' osd 'allow * pool=myPool' | tr -d '\n' | base64 +QVFCK0hDVmdXSjQ1T0JBQXBrc0VtcVhlZFpjc0JwaStIcmU5M3c9PQ== + +# Base64 加密 ceph 用户 myPoolAdmin： +echo "myPoolAdmin" | tr -d '\n' | base64 +bXlQb29sQWRtaW4= +``` +## 配置 RBD Ceph 访问密钥 + +### 用户账号 + +对于静态 RBD 配置（ceph 池中的镜像必须存在），运行以下命令： + +``` +cat > ceph-user-secret.yaml << EOF +apiVersion: v1 +kind: Secret +metadata: + name: ceph-user + namespace: default +type: kubernetes.io/rbd +data: + userID: bXlQb29sVXNlcg== + userKey: QVFDZ0R5VmdyRk9KREJBQTJ5b2s5R1E2NUdSWExRQndhVVBwWXc9PQ== +EOF + +kubectl apply -f ceph-user-secret.yaml +``` + +### 管理员账号 + +对于动态 RBD 配置（用于在给定 ceph 池中自动创建镜像），请运行以下命令： + +``` +cat > ceph-admin-secret.yaml << EOF +apiVersion: v1 +kind: Secret +metadata: + name: ceph-admin + namespace: default +type: kubernetes.io/rbd +data: + userID: bXlQb29sQWRtaW4= + userKey: QVFCK0hDVmdXSjQ1T0JBQXBrc0VtcVhlZFpjc0JwaStIcmU5M3c9PQ== +EOF + +kubectl apply -f ceph-admin-secret.yaml +``` + +## 创建 RBD 测试资源 + +### 在 Pod 中使用 RBD + +```yaml +# pod +cat > ceph-rbd-pod-inline.yaml << EOF +apiVersion: v1 +kind: Pod +metadata: + name: ceph-rbd-pod-inline +spec: + containers: + - name: ceph-rbd-pod-inline + image: busybox + command: ["sleep", "infinity"] + volumeMounts: + - mountPath: /mnt/ceph_rbd + name: volume + volumes: + - name: volume + rbd: + monitors: + - 10.85.8.118:6789 + - 10.85.8.123:6789 + - 10.85.8.124:6789 + pool: myPool + image: image + user: myPoolUser + secretRef: + name: ceph-user + fsType: ext4 + readOnly: false +EOF + +kubectl apply -f ceph-rbd-pod-inline.yaml +kubectl get pod +kubectl exec pod/ceph-rbd-pod-inline -- df -k | grep rbd +``` + +### 在持久卷中使用 RBD + +```yaml +# pod-pvc-pv +cat > ceph-rbd-pod-pvc-pv-allinone.yaml << EOF +apiVersion: v1 +kind: PersistentVolume +metadata: + name: ceph-rbd-pv +spec: + capacity: + storage: 2Gi + accessModes: + - ReadWriteOnce + rbd: + monitors: + - 10.85.8.118:6789 + - 10.85.8.123:6789 + - 10.85.8.124:6789 + pool: myPool + image: image + user: myPoolUser + secretRef: + name: ceph-user + fsType: ext4 + readOnly: false +--- +kind: PersistentVolumeClaim +apiVersion: v1 +metadata: + name: ceph-rbd-pvc +spec: + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 2Gi +--- +apiVersion: v1 +kind: Pod +metadata: + name: ceph-rbd-pod-pvc-pv +spec: + containers: + - name: ceph-rbd-pod-pvc-pv + image: busybox + command: ["sleep", "infinity"] + volumeMounts: + - mountPath: /mnt/ceph_rbd + name: volume + volumes: + - name: volume + persistentVolumeClaim: + claimName: ceph-rbd-pvc +EOF + +kubectl apply -f ceph-rbd-pod-pvc-pv-allinone.yaml +kubectl get pv,pvc,pod +kubectl exec pod/ceph-rbd-pod-pvc-pv -- df -k | grep rbd +``` + +### 在存储类中使用 RBD + +此示例用于动态配置。需要 ceph-csi 驱动。 + +```yaml +# pod-pvc-sc +cat > ceph-rbd-pod-pvc-sc-allinone.yaml < /root/.bashrc << EOF +export PATH=$PATH:/var/lib/rancher/rke2/bin/ +export KUBECONFIG=/etc/rancher/rke2/rke2.yaml +EOF + +cat /var/lib/rancher/rke2/server/node-token +token: K10ca0c38d4ff90d8b80319ab34092e315a8b732622e6adf97bc9eb0536REDACTED::server:ec0308000b8a6b595da000efREDACTED +``` + +### RKE2 Agent/Worker 配置 + +``` +mkdir -p /etc/rancher/rke2/ + +cat > /etc/rancher/rke2/config.yaml << EOF +server: https://10.100.103.23:9345 +token: K10ca0c38d4ff90d8b80319ab34092e315a8b732622e6adf97bc9eb0536REDACTED::server:ec0308000b8a6b595da000efREDACTED +EOF + +curl -sfL https://get.rke2.io | INSTALL_RKE2_TYPE="agent" sh - +systemctl enable --now rke2-agent.service +``` + +要将集群导入 Rancher，请单击 **☰ > 集群管理**。然后在**集群**页面上，单击**导入已有集群**。然后在 server/master 上运行提供的 kubectl 命令。 + +## 测试版本 + +运行 RKE2 节点的操作系统：安装了 kernel-default-5.3.18-24.49 的 JeOS SLE15-SP2 + +``` +kubectl version +Client Version: version.Info{Major:"1", Minor:"18", GitVersion:"v1.18.4", GitCommit:"c96aede7b5205121079932896c4ad89bb93260af", GitTreeState:"clean", BuildDate:"2020-06-22T12:00:00Z", GoVersion:"go1.13.11", Compiler:"gc", Platform:"linux/amd64"} +Server Version: version.Info{Major:"1", Minor:"19", GitVersion:"v1.19.7+rke2r1", GitCommit:"1dd5338295409edcfff11505e7bb246f0d325d15", GitTreeState:"clean", BuildDate:"2021-01-20T01:50:52Z", GoVersion:"go1.15.5b5", Compiler:"gc", Platform:"linux/amd64"} + +helm version +version.BuildInfo{Version:"3.4.1", GitCommit:"c4e74854886b2efe3321e185578e6db9be0a6e29", GitTreeState:"clean", GoVersion:"go1.14.12"} +``` + +RKE2 集群上的 Kubernetes 版本：v1.19.7+rke2r1 + +## 故障排除 + +如果你使用的是基于 SES7 的 SUSE ceph-rook，你可以通过编辑 `rook-1.4.5/ceph/cluster.yaml` 并设置 `spec.network.hostNetwork=true` 来公开 hostNetwork 上的监视器。 + +如果要操作 ceph-rook 集群，则可以在 Kubernetes 集群上部署一个工具箱，其中 ceph-rook 通过 `kubectl apply -f rook-1.4.5/ceph/toolbox.yaml` 配置。然后所有与 ceph 相关的命令都可以在 toolbox pod 中执行，例如，运行 `kubectl exec -it -n rook-ceph rook-ceph-tools-686d8b8bfb-2nvqp -- bash`。 + +ceph 操作 - 基本命令： + +``` +ceph osd pool stats +ceph osd pool delete myPool myPool --yes-i-really-really-mean-it +rbd list -p myPool +> csi-vol-f5d3766c-7296-11eb-b32a-c2b045952d38 +> image +``` + +删除镜像：`rbd rm csi-vol-f5d3766c-7296-11eb-b32a-c2b045952d38 -p myPool` + +rook 工具箱中的 CephFS 命令： + +``` +ceph -s +ceph fs ls +ceph fs fail cephfs +ceph fs rm cephfs --yes-i-really-mean-it +ceph osd pool delete cephfs_data cephfs_data --yes-i-really-really-mean-it +ceph osd pool delete cephfs_metadata cephfs_metadata --yes-i-really-really-mean-it +``` + +要准备 cephfs 文件系统，你可以在 rook 集群上运行以下命令： + +``` +kubectl apply -f rook-1.4.5/ceph/filesystem.yaml +``` diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/manage-clusters/install-cluster-autoscaler/install-cluster-autoscaler.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/manage-clusters/install-cluster-autoscaler/install-cluster-autoscaler.md new file mode 100644 index 00000000000..9d03258c515 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/manage-clusters/install-cluster-autoscaler/install-cluster-autoscaler.md @@ -0,0 +1,28 @@ +--- +title: Cluster Autoscaler +--- + + + + + +在本文中，你将学习如何使用 AWS EC2 Auto Scaling 组在 Rancher 自定义集群上安装和使用 [Kubernetes cluster-autoscaler](https://github.com/kubernetes/autoscaler/blob/master/cluster-autoscaler/)。 + +Cluster Autoscaler 是一个自动调整 Kubernetes 集群大小的工具。该工具在满足以下条件之一时能自动调整集群大小： + +* 集群中有 Pod 因资源不足而无法运行。 +* 集群中有一些节点长时间未得到充分利用，而且它们的 Pod 可以放到其他现有节点上。 + +为防止你的 pod 被驱逐，请在你的 pod 规范中设置 `priorityClassName: system-cluster-critical` 属性。 + +Cluster Autoscaler 运行在 Kubernetes master 节点上。它可以在 `kube-system` 命名空间中运行。Cluster Autoscaler 不会缩减运行非镜像 `kube-system` pod 的节点。 + +你可以在 worker 节点上运行 Cluster Autoscaler 的自定义 deployment，但需要小心以保证 Cluster Autoscaler 能正常运行。 + +## 云提供商 + +Cluster Autoscaler 为不同的云提供商提供支持。有关详细信息，请参见 [Cluster Autoscaler 支持的云提供商](https://github.com/kubernetes/autoscaler/tree/master/cluster-autoscaler#deployment)。 + +### 在 Amazon 上设置 Cluster Autoscaler + +有关在 Amazon 上运行 Cluster Autoscaler 的详细信息，请参阅[此页面](use-aws-ec2-auto-scaling-groups.md)。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/manage-clusters/install-cluster-autoscaler/use-aws-ec2-auto-scaling-groups.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/manage-clusters/install-cluster-autoscaler/use-aws-ec2-auto-scaling-groups.md new file mode 100644 index 00000000000..4a684b2eabe --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/manage-clusters/install-cluster-autoscaler/use-aws-ec2-auto-scaling-groups.md @@ -0,0 +1,575 @@ +--- +title: 通过 AWS EC2 Auto Scaling 组使用 Cluster Autoscaler +--- + +本指南介绍如何使用 AWS EC2 Auto Scaling 组在 Rancher 自定义集群上安装和使用 [Kubernetes cluster-autoscaler](https://github.com/kubernetes/autoscaler/blob/master/cluster-autoscaler/)。 + +我们将安装一个 Rancher RKE 自定义集群，该集群具有固定数量的具有 etcd 和 controlplane 角色的节点，以及数量可变的具有 worker 角色的节点，它们由 `cluster-autoscaler` 管理。 + + +## 先决条件 + +本指南要求： + +* Rancher Server 正常运行。 +* 你的 AWS EC2 用户具有创建虚拟机、Auto Scaling 组以及 IAM 配置文件和角色的适当权限。 + +### 1. 创建自定义集群 + +在 Rancher Server 上，我们需要创建一个自定义的 K8s 集群。请参阅[此处](https://github.com/kubernetes/autoscaler/blob/master/cluster-autoscaler/)以检查版本兼容性。 + +请确保 cloud_provider 名称设置为 `amazonec2`。创建集群后，我们需要获得： + +* clusterID：`c-xxxxx` 将用于 EC2 `kubernetes.io/cluster/` 实例标签。 +* clusterName：将用于 EC2 `k8s.io/cluster-autoscaler/` 实例标签。 +* nodeCommand：将添加到 EC2 实例 `user_data` 上，以包含集群上的新节点。 + + ```sh + sudo docker run -d --privileged --restart=unless-stopped --net=host -v /etc/kubernetes:/etc/kubernetes -v /var/run:/var/run rancher/rancher-agent: --server https:// --token --ca-checksum + ``` + +### 2. 配置云提供商 + +在 AWS EC2 上，我们需要创建一些对象来配置系统。为了在 AWS 上进行配置，我们定义了三个不同的组和 IAM 配置文件。 + +1. Autoscaling 组：将加入 EC2 Auto Scaling 组 (ASG) 的节点。`cluster-autoscaler` 将使用 ASG 来进行扩缩容。 +* IAM 配置文件：运行 cluster-autoscaler 的 K8s 节点需要该文件。推荐用于 Kubernetes master 节点。此配置文件称为 `K8sAutoscalerProfile`。 + + ```json + { + "Version": "2012-10-17", + "Statement": [ + { + "Effect": "Allow", + "Action": [ + "autoscaling:DescribeAutoScalingGroups", + "autoscaling:DescribeAutoScalingInstances", + "autoscaling:DescribeLaunchConfigurations", + "autoscaling:SetDesiredCapacity", + "autoscaling:TerminateInstanceInAutoScalingGroup", + "autoscaling:DescribeTags", + "autoscaling:DescribeLaunchConfigurations", + "ec2:DescribeLaunchTemplateVersions" + ], + "Resource": [ + "*" + ] + } + ] + } + ``` + +2. Master 组：将成为 Kubernetes etcd 和/或 controlplane 的节点。该组不会在 ASG 中。 +* IAM 配置文件：集成 Kubernetes cloud_provider 需要该文件。或者，你也可以使用 `AWS_ACCESS_KEY` 和 `AWS_SECRET_KEY` 来代替 [using-aws-credentials](https://github.com/kubernetes/autoscaler/blob/master/cluster-autoscaler/cloudprovider/aws/README.md#using-aws-credentials)。此配置文件称为 `K8sMasterProfile`。 + + ```json + { + "Version": "2012-10-17", + "Statement": [ + { + "Effect": "Allow", + "Action": [ + "autoscaling:DescribeAutoScalingGroups", + "autoscaling:DescribeLaunchConfigurations", + "autoscaling:DescribeTags", + "ec2:DescribeInstances", + "ec2:DescribeRegions", + "ec2:DescribeRouteTables", + "ec2:DescribeSecurityGroups", + "ec2:DescribeSubnets", + "ec2:DescribeVolumes", + "ec2:CreateSecurityGroup", + "ec2:CreateTags", + "ec2:CreateVolume", + "ec2:ModifyInstanceAttribute", + "ec2:ModifyVolume", + "ec2:AttachVolume", + "ec2:AuthorizeSecurityGroupIngress", + "ec2:CreateRoute", + "ec2:DeleteRoute", + "ec2:DeleteSecurityGroup", + "ec2:DeleteVolume", + "ec2:DetachVolume", + "ec2:RevokeSecurityGroupIngress", + "ec2:DescribeVpcs", + "elasticloadbalancing:AddTags", + "elasticloadbalancing:AttachLoadBalancerToSubnets", + "elasticloadbalancing:ApplySecurityGroupsToLoadBalancer", + "elasticloadbalancing:CreateLoadBalancer", + "elasticloadbalancing:CreateLoadBalancerPolicy", + "elasticloadbalancing:CreateLoadBalancerListeners", + "elasticloadbalancing:ConfigureHealthCheck", + "elasticloadbalancing:DeleteLoadBalancer", + "elasticloadbalancing:DeleteLoadBalancerListeners", + "elasticloadbalancing:DescribeLoadBalancers", + "elasticloadbalancing:DescribeLoadBalancerAttributes", + "elasticloadbalancing:DetachLoadBalancerFromSubnets", + "elasticloadbalancing:DeregisterInstancesFromLoadBalancer", + "elasticloadbalancing:ModifyLoadBalancerAttributes", + "elasticloadbalancing:RegisterInstancesWithLoadBalancer", + "elasticloadbalancing:SetLoadBalancerPoliciesForBackendServer", + "elasticloadbalancing:AddTags", + "elasticloadbalancing:CreateListener", + "elasticloadbalancing:CreateTargetGroup", + "elasticloadbalancing:DeleteListener", + "elasticloadbalancing:DeleteTargetGroup", + "elasticloadbalancing:DescribeListeners", + "elasticloadbalancing:DescribeLoadBalancerPolicies", + "elasticloadbalancing:DescribeTargetGroups", + "elasticloadbalancing:DescribeTargetHealth", + "elasticloadbalancing:ModifyListener", + "elasticloadbalancing:ModifyTargetGroup", + "elasticloadbalancing:RegisterTargets", + "elasticloadbalancing:SetLoadBalancerPoliciesOfListener", + "iam:CreateServiceLinkedRole", + "ecr:GetAuthorizationToken", + "ecr:BatchCheckLayerAvailability", + "ecr:GetDownloadUrlForLayer", + "ecr:GetRepositoryPolicy", + "ecr:DescribeRepositories", + "ecr:ListImages", + "ecr:BatchGetImage", + "kms:DescribeKey" + ], + "Resource": [ + "*" + ] + } + ] + } + ``` + + * IAM 角色：`K8sMasterRole: [K8sMasterProfile,K8sAutoscalerProfile]` + * 安全组：`K8sMasterSg`。详情请参见 [RKE 端口（自定义节点选项卡）](../../../../getting-started/installation-and-upgrade/installation-requirements/port-requirements.md#下游-kubernetes-集群节点) + * 标签： + `kubernetes.io/cluster/: owned` + * 用户数据：`K8sMasterUserData` Ubuntu 18.04(ami-0e11cbb34015ff725)，安装 Docker 并将 etcd 和 controlplane 节点添加到 K8s 集群。 + + ```sh + #!/bin/bash -x + + cat < /etc/sysctl.d/90-kubelet.conf + vm.overcommit_memory = 1 + vm.panic_on_oom = 0 + kernel.panic = 10 + kernel.panic_on_oops = 1 + kernel.keys.root_maxkeys = 1000000 + kernel.keys.root_maxbytes = 25000000 + EOF + sysctl -p /etc/sysctl.d/90-kubelet.conf + + curl -sL https://releases.rancher.com/install-docker/19.03.sh | sh + sudo usermod -aG docker ubuntu + + TOKEN=$(curl -s -X PUT "http://169.254.169.254/latest/api/token" -H "X-aws-ec2-metadata-token-ttl-seconds: 21600") + PRIVATE_IP=$(curl -H "X-aws-ec2-metadata-token: ${TOKEN}" -s http://169.254.169.254/latest/meta-data/local-ipv4) + PUBLIC_IP=$(curl -H "X-aws-ec2-metadata-token: ${TOKEN}" -s http://169.254.169.254/latest/meta-data/public-ipv4) + K8S_ROLES="--etcd --controlplane" + + sudo docker run -d --privileged --restart=unless-stopped --net=host -v /etc/kubernetes:/etc/kubernetes -v /var/run:/var/run rancher/rancher-agent: --server https:// --token --ca-checksum --address ${PUBLIC_IP} --internal-address ${PRIVATE_IP} ${K8S_ROLES} + ``` + +3. Worker 组：将加入 K8s worker plane 的节点。Worker 节点将由 cluster-autoscaler 使用 ASG 进行扩缩容。 +* IAM 配置文件：提供 cloud_provider worker 集成。 + 此配置文件称为 `K8sWorkerProfile`。 + + ```json + { + "Version": "2012-10-17", + "Statement": [ + { + "Effect": "Allow", + "Action": [ + "ec2:DescribeInstances", + "ec2:DescribeRegions", + "ecr:GetAuthorizationToken", + "ecr:BatchCheckLayerAvailability", + "ecr:GetDownloadUrlForLayer", + "ecr:GetRepositoryPolicy", + "ecr:DescribeRepositories", + "ecr:ListImages", + "ecr:BatchGetImage" + ], + "Resource": "*" + } + ] + } + ``` + +* IAM 角色：`K8sWorkerRole：[K8sWorkerProfile]` +* 安全组：`K8sWorkerSg`。详情请参见 [RKE 端口（自定义节点选项卡）](../../../../getting-started/installation-and-upgrade/installation-requirements/port-requirements.md#下游-kubernetes-集群节点) +* 标签： + * `kubernetes.io/cluster/: owned` + * `k8s.io/cluster-autoscaler/: true` + * `k8s.io/cluster-autoscaler/enabled: true` +* 用户数据：`K8sWorkerUserData` Ubuntu 18.04(ami-0e11cbb34015ff725)，安装 Docker 并将 worker 节点添加到 K8s 集群。 + + ```sh + #!/bin/bash -x + + cat < /etc/sysctl.d/90-kubelet.conf + vm.overcommit_memory = 1 + vm.panic_on_oom = 0 + kernel.panic = 10 + kernel.panic_on_oops = 1 + kernel.keys.root_maxkeys = 1000000 + kernel.keys.root_maxbytes = 25000000 + EOF + sysctl -p /etc/sysctl.d/90-kubelet.conf + + curl -sL https://releases.rancher.com/install-docker/19.03.sh | sh + sudo usermod -aG docker ubuntu + + TOKEN=$(curl -s -X PUT "http://169.254.169.254/latest/api/token" -H "X-aws-ec2-metadata-token-ttl-seconds: 21600") + PRIVATE_IP=$(curl -H "X-aws-ec2-metadata-token: ${TOKEN}" -s http://169.254.169.254/latest/meta-data/local-ipv4) + PUBLIC_IP=$(curl -H "X-aws-ec2-metadata-token: ${TOKEN}" -s http://169.254.169.254/latest/meta-data/public-ipv4) + K8S_ROLES="--worker" + + sudo docker run -d --privileged --restart=unless-stopped --net=host -v /etc/kubernetes:/etc/kubernetes -v /var/run:/var/run rancher/rancher-agent: --server https:// --token --ca-checksum --address ${PUBLIC_IP} --internal-address ${PRIVATE_IP} ${K8S_ROLES} + ``` + +详情请参见 [AWS 上的 RKE 集群](../../../new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-cloud-providers/amazon.md) 和 [AWS 上的 Cluster Autoscaler](https://github.com/kubernetes/autoscaler/blob/master/cluster-autoscaler/cloudprovider/aws/README.md)。 + +### 3. 部署节点 + +我们配置 AWS 后，我们需要创建虚拟机来引导集群： + +* master (etcd+controlplane)：根据需要部署三个适当大小的 master 实例。详情请参见[生产就绪集群的建议](../../kubernetes-clusters-in-rancher-setup/checklist-for-production-ready-clusters/checklist-for-production-ready-clusters.md)。 + * IAM 角色：`K8sMasterRole` + * 安全组：`K8sMasterSg` + * 标签： + * `kubernetes.io/cluster/: owned` + * 用户数据：`K8sMasterUserData` + +* worker：使用以下设置在 EC2 上定义 ASG： + * 名称：`K8sWorkerAsg` + * IAM 角色：`K8sWorkerRole` + * 安全组：`K8sWorkerSg` + * 标签： + * `kubernetes.io/cluster/: owned` + * `k8s.io/cluster-autoscaler/: true` + * `k8s.io/cluster-autoscaler/enabled: true` + * 用户数据：`K8sWorkerUserData` + * 实例： + * 最少：2 + * 理想情况：2 + * 最大：10 + +部署 VM 后，你的 Rancher 自定义集群应该可以正常运行了，其中包含三个 master 节点和两个 worker 节点。 + +### 4. 安装 Cluster-autoscaler + +此时，我们的 Rancher 集群应该已正常运行。我们将根据 cluster-autoscaler 的建议，在 master 节点和 `kube-system` 命名空间上安装 cluster-autoscaler。 + +#### 参数 + +下表显示了用于微调的 cluster-autoscaler 参数： + +| 参数 | 默认 | 描述 | +|---|---|---| +| cluster-name | - | 自动扩缩的集群的名称（如果可用） | +| address | :8085 | 公开 Prometheus 指标的地址 | +| kubernetes | - | Kubernetes master 位置。如需使用默认值，则留空 | +| kubeconfig | - | 带有授权和 master 位置信息的 kubeconfig 文件的路径 | +| cloud-config | - | 云提供商配置文件的路径。如果没有配置文件，则为空字符串 | +| namespace | "kube-system" | 运行 cluster-autoscaler 的命名空间 | +| scale-down-enabled | true | CA 是否应该缩减集群 | +| scale-down-delay-after-add | "10m" | 扩容多久后恢复缩容评估 | +| scale-down-delay-after-delete | 0 | 节点删除多久后恢复缩容评估，默认为 scanInterval 的值 | +| scale-down-delay-after-failure | "3m" | 缩容失败多久后恢复缩容评估 | +| scale-down-unneeded-time | "10m" | 在能进行缩容之前，节点需要不被使用的时间 | +| scale-down-unready-time | "20m" | 在能进行缩容之前，非就绪节点应该需要不被使用的时间 | +| scale-down-utilization-threshold | 0.5 | 节点上运行的所有 pod 的 CPU 或内存之和除以节点对应的可分配资源，低于该值时可以考虑缩减一个节点 | +| scale-down-gpu-utilization-threshold | 0.5 | 节点上运行的所有 pod 的 GPU 请求总和除以节点的可分配资源，低于该值时可以考虑缩减一个节点 | +| scale-down-non-empty-candidates-count | 30 | 在一次迭代中被认为是空节点的最大数量，这些节点会成为使用清空来缩容的候选节点 | +| scale-down-candidates-pool-ratio | 0.1 | 当先前迭代的某些候选节点失效时，被视为要缩容的额外非空候选节点的比率 | +| scale-down-candidates-pool-min-count | 50 | 当先前迭代的某些候选节点失效时，被视为要缩容的额外非空候选节点的最大数量 | +| node-deletion-delay-timeout | "2m" | CA 在删除节点之前，等待删除 delay-deletion.cluster-autoscaler.kubernetes.io/ 注释的最长时间 | +| scan-interval | "10s" | 重新评估集群扩缩容的频率 | +| max-nodes-total | 0 | 所有节点组中的最大节点数。Cluster Autoscaler 不会让集群增长到超过此数量 | +| cores-total | "0:320000" | 集群中的最小和最大的核心数，格式为 `:`。Cluster Autoscaler 会在该范围内扩缩集群。 | +| memory-total | "0:6400000" | 集群中最小和最大内存千兆字节数，格式为 `:`。Cluster Autoscaler 会在该范围内扩缩集群。 | +| cloud-provider | - | 云提供商类型 | +| max-bulk-soft-taint-count | 10 | 可以同时添加/移除 PreferNoSchedule 污点的最大节点数。设置为 0 则关闭此类污点 | +| max-bulk-soft-taint-time | "3s" | 同时添加/移除 PreferNoSchedule 污点的最大持续时间。 | +| max-empty-bulk-delete | 10 | 可以同时删除的最大空节点数 | +| max-graceful-termination-sec | 600 | 尝试缩减节点时，CA 等待 pod 终止的最大秒数 | +| max-total-unready-percentage | 45 | 集群中未就绪节点的最大百分比。超过此值后，CA 将停止操作 | +| ok-total-unready-count | 3 | 允许的未就绪节点数，与 max-total-unready-percentage 无关 | +| scale-up-from-zero | true | 就绪节点数等于 0 时，CA 是否应该扩容 | +| max-node-provision-time | "15m" | CA 等待节点配置的最长时间 | +| nodes | - | 以云提供商接受的格式设置节点组的最小、最大大小和其他配置数据。可以多次使用。格式是 `::`。 | +| node-group-auto-discovery | - | 节点组自动发现的一个或多个定义。定义表示为 `:[[=]]` | +| estimator |"binpacking" | 用于扩容的资源评估器类型。可用值：["binpacking"] | +| expander | "random" | 要在扩容中使用的节点组扩展器的类型。可用值：`["random","most-pods","least-waste","price","priority"]` | +| ignore-daemonsets-utilization | false | CA 为了缩容而计算资源利用率时，是否应忽略 DaemonSet pod | +| ignore-mirror-pods-utilization | false | CA 为了缩容而计算资源利用率时，是否应忽略 Mirror pod | +| write-status-configmap | true | CA 是否应该将状态信息写入 configmap | +| max-inactivity | "10m" | 从上次记录的 autoscaler 活动后，自动重启之前的最长时间 | +| max-failing-time | "15m" | 从上次记录的 autoscaler 成功运行后，自动重启之前的最长时间 | +| balance-similar-node-groups | false | 检测相似的节点组，并均衡它们的节点数量 | +| node-autoprovisioning-enabled | false | CA 是否应在需要时自动配置节点组 | +| max-autoprovisioned-node-group-count | 15 | 集群中自动配置组的最大数量 | +| unremovable-node-recheck-timeout | "5m" | 在再次检查无法删除的节点之前，节点的超时时间 | +| expendable-pods-priority-cutoff | -10 | 优先级低于 cutoff 的 Pod 将是消耗性 pod。这些 pod 可以在缩容期间不加考虑地被终止，并且不会导致扩容。优先级是 null（禁用 PodPriority）的 pod 不是消耗性的 | +| regional | false | 集群是区域性的 | +| new-pod-scale-up-delay | "0s" | 生命短于这个值的 Pod 将不考虑扩容 | +| ignore-taint | - | 在扩缩容节点组时，指定在节点模板中要忽略的污点 | +| balancing-ignore-label | - | 在比较两个节点组是否相似时，指定要忽略的标签（基本标签集和云提供商标签集除外） | +| aws-use-static-instance-list | false | CA 在运行时还是使用静态列表获取实例类型。仅适用于 AWS | +| profiling | false | 是否启用了 debug/pprof 端点 | + +#### 部署 + +基于 [cluster-autoscaler-run-on-control-plane.yaml](https://github.com/kubernetes/autoscaler/blob/master/cluster-autoscaler/cloudprovider/aws/examples/cluster-autoscaler-run-on-control-plane.yaml) 示例，我们已经创建了自己的 `cluster-autoscaler-deployment.yaml` 以使用首选的 [auto-discovery 设置](https://github.com/kubernetes/autoscaler/tree/master/cluster-autoscaler/cloudprovider/aws#auto-discovery-setup)，更新容忍度、nodeSelector、镜像版本和命令配置： + + +```yml +--- +apiVersion: v1 +kind: ServiceAccount +metadata: + labels: + k8s-addon: cluster-autoscaler.addons.k8s.io + k8s-app: cluster-autoscaler + name: cluster-autoscaler + namespace: kube-system +--- +apiVersion: rbac.authorization.k8s.io/v1 +kind: ClusterRole +metadata: + name: cluster-autoscaler + labels: + k8s-addon: cluster-autoscaler.addons.k8s.io + k8s-app: cluster-autoscaler +rules: + - apiGroups: [""] + resources: ["events", "endpoints"] + verbs: ["create", "patch"] + - apiGroups: [""] + resources: ["pods/eviction"] + verbs: ["create"] + - apiGroups: [""] + resources: ["pods/status"] + verbs: ["update"] + - apiGroups: [""] + resources: ["endpoints"] + resourceNames: ["cluster-autoscaler"] + verbs: ["get", "update"] + - apiGroups: [""] + resources: ["nodes"] + verbs: ["watch", "list", "get", "update"] + - apiGroups: [""] + resources: + - "pods" + - "services" + - "replicationcontrollers" + - "persistentvolumeclaims" + - "persistentvolumes" + verbs: ["watch", "list", "get"] + - apiGroups: ["extensions"] + resources: ["replicasets", "daemonsets"] + verbs: ["watch", "list", "get"] + - apiGroups: ["policy"] + resources: ["poddisruptionbudgets"] + verbs: ["watch", "list"] + - apiGroups: ["apps"] + resources: ["statefulsets", "replicasets", "daemonsets"] + verbs: ["watch", "list", "get"] + - apiGroups: ["storage.k8s.io"] + resources: ["storageclasses", "csinodes"] + verbs: ["watch", "list", "get"] + - apiGroups: ["batch", "extensions"] + resources: ["jobs"] + verbs: ["get", "list", "watch", "patch"] + - apiGroups: ["coordination.k8s.io"] + resources: ["leases"] + verbs: ["create"] + - apiGroups: ["coordination.k8s.io"] + resourceNames: ["cluster-autoscaler"] + resources: ["leases"] + verbs: ["get", "update"] +--- +apiVersion: rbac.authorization.k8s.io/v1 +kind: Role +metadata: + name: cluster-autoscaler + namespace: kube-system + labels: + k8s-addon: cluster-autoscaler.addons.k8s.io + k8s-app: cluster-autoscaler +rules: + - apiGroups: [""] + resources: ["configmaps"] + verbs: ["create","list","watch"] + - apiGroups: [""] + resources: ["configmaps"] + resourceNames: ["cluster-autoscaler-status", "cluster-autoscaler-priority-expander"] + verbs: ["delete", "get", "update", "watch"] + +--- +apiVersion: rbac.authorization.k8s.io/v1 +kind: ClusterRoleBinding +metadata: + name: cluster-autoscaler + labels: + k8s-addon: cluster-autoscaler.addons.k8s.io + k8s-app: cluster-autoscaler +roleRef: + apiGroup: rbac.authorization.k8s.io + kind: ClusterRole + name: cluster-autoscaler +subjects: + - kind: ServiceAccount + name: cluster-autoscaler + namespace: kube-system + +--- +apiVersion: rbac.authorization.k8s.io/v1 +kind: RoleBinding +metadata: + name: cluster-autoscaler + namespace: kube-system + labels: + k8s-addon: cluster-autoscaler.addons.k8s.io + k8s-app: cluster-autoscaler +roleRef: + apiGroup: rbac.authorization.k8s.io + kind: Role + name: cluster-autoscaler +subjects: + - kind: ServiceAccount + name: cluster-autoscaler + namespace: kube-system + +--- +apiVersion: apps/v1 +kind: Deployment +metadata: + name: cluster-autoscaler + namespace: kube-system + labels: + app: cluster-autoscaler +spec: + replicas: 1 + selector: + matchLabels: + app: cluster-autoscaler + template: + metadata: + labels: + app: cluster-autoscaler + annotations: + prometheus.io/scrape: 'true' + prometheus.io/port: '8085' + spec: + serviceAccountName: cluster-autoscaler + tolerations: + - effect: NoSchedule + operator: "Equal" + value: "true" + key: node-role.kubernetes.io/controlplane + nodeSelector: + node-role.kubernetes.io/controlplane: "true" + containers: + - image: eu.gcr.io/k8s-artifacts-prod/autoscaling/cluster-autoscaler: + name: cluster-autoscaler + resources: + limits: + cpu: 100m + memory: 300Mi + requests: + cpu: 100m + memory: 300Mi + command: + - ./cluster-autoscaler + - --v=4 + - --stderrthreshold=info + - --cloud-provider=aws + - --skip-nodes-with-local-storage=false + - --expander=least-waste + - --node-group-auto-discovery=asg:tag=k8s.io/cluster-autoscaler/enabled,k8s.io/cluster-autoscaler/ + volumeMounts: + - name: ssl-certs + mountPath: /etc/ssl/certs/ca-certificates.crt + readOnly: true + imagePullPolicy: "Always" + volumes: + - name: ssl-certs + hostPath: + path: "/etc/ssl/certs/ca-certificates.crt" + +``` + +准备好清单文件后，将该文件部署到 Kubernetes 集群中（也可以使用 Rancher UI 进行操作）： + +```sh +kubectl -n kube-system apply -f cluster-autoscaler-deployment.yaml +``` + +:::note + +你也可以通过[手动配置](https://github.com/kubernetes/autoscaler/tree/master/cluster-autoscaler/cloudprovider/aws#manual-configuration)来设置 Cluster-autoscaler deployment。 + +::: + +## 测试 + +此时，cluster-autoscaler 应该已经在 Rancher 自定义集群中启动并运行。当满足以下条件之一时，cluster-autoscaler 需要管理 `K8sWorkerAsg` ASG，以在 2 到 10 个节点之间进行扩缩容： + +* 集群中有 Pod 因资源不足而无法运行。在这种情况下，集群被扩容。 +* 集群中有一些节点长时间未得到充分利用，而且它们的 Pod 可以放到其他现有节点上。在这种情况下，集群被缩容。 + +### 生成负载 + +为了在 Kubernetes 集群上产生负载并查看 cluster-autoscaler 是否正常工作，我们准备了一个 `test-deployment.yaml`。`test-deployment` 通过三个副本请求 1000m CPU 和 1024Mi 内存。通过调整请求的资源和/或副本以确保耗尽 Kubernetes 集群资源： + +```yaml +apiVersion: apps/v1 +kind: Deployment +metadata: + labels: + app: hello-world + name: hello-world +spec: + replicas: 3 + selector: + matchLabels: + app: hello-world + strategy: + rollingUpdate: + maxSurge: 1 + maxUnavailable: 0 + type: RollingUpdate + template: + metadata: + labels: + app: hello-world + spec: + containers: + - image: rancher/hello-world + imagePullPolicy: Always + name: hello-world + ports: + - containerPort: 80 + protocol: TCP + resources: + limits: + cpu: 1000m + memory: 1024Mi + requests: + cpu: 1000m + memory: 1024Mi +``` + +准备好 test deployment 后，将其部署在 Kubernetes 集群的默认命名空间中（可以使用 Rancher UI）： + +``` +kubectl -n default apply -f test-deployment.yaml +``` + +### 检查扩缩容 + +Kubernetes 资源耗尽后，cluster-autoscaler 应该扩容无法调度 pod 的 worker 节点。它应该进行扩容，直到所有 pod 都能被调度。你应该会在 ASG 和 Kubernetes 集群上看到新节点。检查 `kube-system` cluster-autoscaler pod 上的日志。 + +检查完扩容后，我们开始检查缩容。为此，请减少 test deployment 的副本数，直到你能释放足够的 Kubernetes 集群资源以进行缩容。你应该能看到 ASG 和 Kubernetes 集群上的节点消失了。检查 `kube-system` cluster-autoscaler pod 上的日志。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/manage-clusters/manage-cluster-templates.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/manage-clusters/manage-cluster-templates.md new file mode 100644 index 00000000000..9cb5a041693 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/manage-clusters/manage-cluster-templates.md @@ -0,0 +1,130 @@ +--- +title: 集群模板 +--- + +集群模板包含 Kubernetes 配置和节点池配​​置，允许单个模板包含 Rancher 在云提供商中配置新节点并在这些节点上安装 Kubernetes 所需的所有信息。 + +## 概述 + +集群模板以 Helm Chart 的形式提供。要使用集群模板，你需要克隆和复刻模板，根据你的用例更改模板，然后在 Rancher 管理集群上安装 Helm Chart。如果 Helm Chart 安装在 Rancher 管理集群上，会创建一个新的集群资源，Rancher 使用它来配置新集群。 + +使用模板配置集群后，对模板的任何更改都不会影响集群。使用集群模板创建集群后，集群的配置和基础设施可能会发生变化，因为集群模板没有任何执行限制。 + +### Kubernetes 发行版 + +集群模板可以使用任何 Kubernetes 发行版。现在，我们提供一个带有 RKE2 Kubernetes 集群的示例。将来我们可能会提供更多使用其他 Kubernetes 发行版的示例。 + +### 版本控制 + +Rancher 不管理集群模板的版本控制。版本控制在包含模板的 Helm Chart 的仓库中处理。 + +## RKE2 集群模板 + +请参阅 [RKE2 集群模板](https://github.com/rancher/cluster-template-examples)的示例仓库。 + +## 向 Rancher 添加集群模板 + +在本节中，你将学习如何将集群模板添加到 `local` 集群的 Chart 仓库列表中。这样，当用户安装新的 Kubernetes 集群时，Rancher 将提供集群模板的选项。 + +:::note 先决条件： + +- 你需要有在`本地` Kubernetes 集群上安装 Helm Chart 的权限。 +- 为了使 Chart 以创建新集群的形式出现，Chart 必须具有注释 `catalog.cattle.io/type: cluster-template`。 + +::: + +1. 转到集群模板示例仓库。Rancher 的示例位于[此 GitHub 仓库中](https://github.com/rancher/cluster-template-examples)。 +1. 复刻仓库。 +1. 可选：通过编辑 `values.yaml` 文件来编辑集群选项。有关编辑文件的帮助，请参阅集群模板的 Helm Chart 自述文件。 +1. 将 Chart 仓库添加到 Rancher。点击 **☰ > 集群管理**。 +1. 转到 `local` 集群并单击 **Explore**。 +1. 在左侧导航栏中，单击 **Apps > Chart Repositories**。 +1. 点击**创建**。 +1. 输入集群模板仓库的名称。 +1. 点击**包含 Helm Chart 定义的 Git 仓库**。 +1. 在 **Git 仓库 URL**字段，输入仓库的 URL，例如，`https://github.com/rancher/cluster-template-examples.git`。 +1. 在 **Git 分支**字段，输入要用作模板源的分支。Rancher 的示例仓库使用了 `main` 分支。 +1. 点击**创建**。 + +**结果**：集群模板可从 Rancher `local` 集群中的 **Apps** 获得。现在，你可以使用模板来部署集群。 + +:::note 受限管理员访问： + +如果你是受限管理员并且无权访问 `local` 集群，你仍然可以添加新的 RKE2 模板并管理集群仓库。要导航到 Chart 仓库，请在左侧导航栏单击 **☰ > 集群管理 > 高级选项 > 仓库**。你将绕过上述步骤 1 - 6，然后继续按照步骤 7 - 12 创建集群模板。 + +::: + +## 使用集群模板创建集群 + +:::note 先决条件： + +- 你需要获得配置新 Kubernetes 集群的权限。 +- 你将需要云凭证来使用模板配置基础设施。 +- 为了以创建新集群的形式显示，集群模板的 Helm Chart 必须具有 `catalog.cattle.io/type: cluster-template` 注释。 + +::: + +1. 点击 **☰ > 集群管理**。 +1. 在**集群**页面，点击**创建**。 +1. 单击集群模板的名称。 +1. 完成 Helm Chart 的安装。 + +**结果**：在 Rancher 配置新集群后，你可以像管理其他 Rancher 启动的 Kubernetes 集群一样管理该新集群。如果集群模板有可供用户选择的选项，你可以通过 UI 配置这些选项。 + +## 更新使用集群模板创建的集群 + +如果集群所用的模板有了新版本，你可以使用 **Apps > Installed Apps** 页面中的模板更新集群。 + +## 使用 Fleet 从模板部署集群 + +:::note 先决条件： + +- 你需要获得配置新 Kubernetes 集群的权限。 +- 你将需要云凭证来使用模板配置基础设施。 +- 为了以创建新集群的形式显示，集群模板的 Helm Chart 必须具有 `catalog.cattle.io/type:cluster-template` 注释。 +- 为了将模板用作持续交付/GitOps 的一部分，集群模板需要部署在`本地`集群的 `fleet-local` 命名空间中。 +- 所有值都必须在模板的 `values.yaml` 中设置。 +- Fleet 仓库必须遵循此处的[指南](https://fleet.rancher.io/gitrepo-content)。对于 RKE2 集群模板，则必须把 `fleet.yaml` 文件添加到仓库。 + +::: + +1. 点击 **☰ > 集群管理**。 +1. 在**集群**页面，点击**创建**。 +1. 点击**使用模板创建集群**。 + +**结果**：Rancher 配置好新集群后，集群由 Fleet 管理。 + +## 卸载集群模板 + +1. 点击 **☰ > 集群管理**。 +1. 前往 `local` 集群并单击 **Apps > Chart Repositories**。 +1. 转到集群模板的 Chart 仓库，然后单击 **⋮ > 删除。** +1. 确认删除。 + +**结果**：集群模板已卸载。此操作不会影响使用集群模板创建的现有集群。 + +能够访问 `local` 集群的管理员还可以前往 **Apps > Installed Apps** 页面，通过集群模板来移除已部署的集群。 + +## 配置选项 + +集群模板非常灵活，可用于配置以下所有选项： + +- 节点配置 +- 节点池 +- 预先指定的云凭证 +- 启用/配置授权的集群端点，以在不使用 Rancher 作为代理的情况下获得对集群的 kubectl 访问权限 +- 安装 Rancher V2 monitoring +- Kubernetes 版本 +- 分配集群成员 +- 配置基础设施，例如 AWS VPC/子网或 vSphere 数据中心 +- 云提供商选项 +- Pod 安全选项 +- 网络提供商 +- Ingress Controller +- 网络安全配置 +- 网络插件 +- 私有镜像仓库 URL 和凭证 +- 附加组件 +- Kubernetes 选项，包括 kube-api、kube-controller、kubelet 和服务等 Kubernetes 组件的配置 + +有关如何配置模板的详细信息，请参阅集群模板的 Helm Chart README 文件。 \ No newline at end of file diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/manage-clusters/manage-clusters.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/manage-clusters/manage-clusters.md new file mode 100644 index 00000000000..a1c89025444 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/manage-clusters/manage-clusters.md @@ -0,0 +1,36 @@ +--- +title: 集群管理 +--- + + + + + +在 Rancher 中配置集群后，你可以开始使用强大的 Kubernetes 功能在开发、测试或生产环境中部署和扩展容器化应用。 + +:::note + +本节默认你已对 Docker 和 Kubernetes 有一定的了解。如果你需要了解 Kubernetes 组件如何协作，请参见 [Kubernetes 概念](../../../reference-guides/kubernetes-concepts.md)页面。 + +::: + +## 在 Rancher 中管理集群 + +将集群[配置到 Rancher](../kubernetes-clusters-in-rancher-setup/kubernetes-clusters-in-rancher-setup.md) 之后，[集群所有者](../authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/cluster-and-project-roles.md#集群角色)需要管理这些集群。管理集群的选项如下： + +import ClusterCapabilitiesTable from '../../../shared-files/_cluster-capabilities-table.md'; + + + +## 配置工具 + +Rancher 包含 Kubernetes 中未包含的各种工具来协助你进行 DevOps 操作。Rancher 可以与外部服务集成，让你的集群更高效地运行。工具分为以下几类： + +- 告警 +- Notifiers +- Logging +- Monitoring +- Istio 服务网格 +- OPA Gatekeeper + +你可以通过 **Apps** 来安装工具。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/manage-clusters/nodes-and-node-pools.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/manage-clusters/nodes-and-node-pools.md new file mode 100644 index 00000000000..359d10f52cb --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/manage-clusters/nodes-and-node-pools.md @@ -0,0 +1,192 @@ +--- +title: 节点和节点池 +--- + +在 Rancher 中启动 Kubernetes 集群后，你可以从集群的**节点**选项卡管理各个节点。 + +1. 点击左上角的 **☰**。 +1. 选择**集群管理**。 +1. 找到要管理其节点的集群，然后单击行末尾的**浏览**按钮。 +1. 从左侧导航中选择**节点**。 + +不同的集群配置[选项](../kubernetes-clusters-in-rancher-setup/kubernetes-clusters-in-rancher-setup.md)对应不同的可用节点选项。 + +:::note + +如果你想管理 _集群_ 而不是单个节点，请参阅[编辑集群](../../../reference-guides/cluster-configuration/cluster-configuration.md)。 + +::: + + +## 每个集群创建选项的可用节点选项 + +下表列出了 Rancher 中每种集群类型的可用节点选项。单击**选项**列中的链接以获取每个功能的更多信息。 + +| 选项 | [由基础设施提供商托管的节点][1] | [自定义节点][2] | [托管集群][3] | [注册的 EKS 节点][4] | [所有其他注册节点][5] | 描述 | +| ------------------------------------------------ | ------------------------------------------------ | ---------------- | ------------------- | ------------------- | -------------------| ------------------------------------------------------------------ | +| [封锁](#封锁节点) | ✓ | ✓ | ✓ | ✓ | ✓ | 将节点标记为不可调度。 | +| [清空](#清空节点) | ✓ | ✓ | ✓ | ✓ | ✓ | 将节点标记为不可调度 _并且_ 驱逐所有 pod。 | +| [编辑](#管理和编辑单个节点) | ✓ | ✓ | ✓ | ✓ | ✓ | 输入节点的自定义名称、描述、标签或污点。 | +| [查看 API](#在-rancher-api-中查看节点) | ✓ | ✓ | ✓ | ✓ | ✓ | 查看 API 数据。 | +| [删除](#删除节点) | ✓ | ✓ | | * | * | 从集群中删除有缺陷的节点。 | +| [下载密钥](#通过-ssh-连接到由基础设施提供商托管的节点) | ✓ | | | | | 下载 SSH 密钥以通过 SSH 连接到节点。 | +| [节点缩放](#扩缩节点) | ✓ | | | ✓ | | 向上或向下扩展节点池中的节点数。 | + +[1]: ../launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/use-new-nodes-in-an-infra-provider.md +[2]: ../../../reference-guides/cluster-configuration/rancher-server-configuration/use-existing-nodes/use-existing-nodes.md +[3]: ../kubernetes-clusters-in-rancher-setup/set-up-clusters-from-hosted-kubernetes-providers/set-up-clusters-from-hosted-kubernetes-providers.md +[4]: ../kubernetes-clusters-in-rancher-setup/register-existing-clusters.md +[5]: ../kubernetes-clusters-in-rancher-setup/register-existing-clusters.md + +\* 可通过 View API 访问的删除选项 + + +### 由基础设施提供商托管的节点 + +在[托管在基础设施提供商](../launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/use-new-nodes-in-an-infra-provider.md)中的节点上配置由 Rancher 启动的 Kubernetes 集群时，你可以使用节点池。 + +如果节点池被编辑，通过[节点池选项](../launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/use-new-nodes-in-an-infra-provider.md#节点池)配置的集群可以纵向扩容或缩容。 + +如果启用[节点自动替换功能](../launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/use-new-nodes-in-an-infra-provider.md#节点自动替换)，节点池还可以自动维护在初始集群配置期间设置的节点规模。该规模决定了 Rancher 为集群维护的 active 节点的数量。 + +Rancher 使用[节点模板](../launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/use-new-nodes-in-an-infra-provider.md#节点模板)来替换节点池中的节点。每个节点模板都使用云提供商凭证来允许 Rancher 在基础设施提供商中设置节点。 + +### 由托管 Kubernetes 提供商配置的节点 + +用于管理[由 Kubernetes 提供商托管](../kubernetes-clusters-in-rancher-setup/set-up-clusters-from-hosted-kubernetes-providers/set-up-clusters-from-hosted-kubernetes-providers.md)的节点的选项在 Rancher 中有些限制。例如，你不能使用 Rancher UI 向上或向下缩放节点数量，而是需要直接编辑集群。 + +### 注册节点 + +虽然你可以使用 Rancher 将工作负载部署到[已注册集群](../../new-user-guides/kubernetes-clusters-in-rancher-setup/register-existing-clusters.md)，但你无法管理单个集群节点。导入的集群节点的所有管理都必须在 Rancher 之外进行。 + +## 管理和编辑单个节点 + +编辑节点可让你： + +* 更改其名称 +* 更改其描述 +* 添加[标签](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/) +* 添加/删除[污点](https://kubernetes.io/docs/concepts/configuration/taint-and-toleration/) + +要管理单个节点，请浏览到要管理的集群，然后从主菜单中选择**节点**。你可以通过单击节点的 **⋮** (**...**) 图标来打开选项菜单。 + +## 在 Rancher API 中查看节点 + +选择此选项以查看节点的 [API 端点](../../../api/quickstart.md) + +## 删除节点 + +使用 **Delete** 从云提供商中删除有缺陷的节点。 + +当你删除有缺陷的节点时，如果该节点在节点池中并启用了[节点自动替换](../launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/use-new-nodes-in-an-infra-provider.md#节点自动替换)，Rancher 可以自动将其替换为具有相同配置的节点。 + +:::tip + +如果你的集群由基础设施提供商托管，并且你希望缩容集群，而不是删除有缺陷的节点，请进行[缩容](#扩缩节点)而不是删除。 + +::: + +## 扩缩节点 + +对于由基础设施提供商托管的节点，你可以使用缩放控件来缩放每个[节点池](../launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/use-new-nodes-in-an-infra-provider.md#节点池)中的节点数量。此选项不适用于其他集群类型。 + +## 通过 SSH 连接到由基础设施提供商托管的节点 + +对于[由基础设施提供商托管的节点](../launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/use-new-nodes-in-an-infra-provider.md)，你可以选择下载其 SSH 密钥，以便从桌面远程连接到它。 + +1. 在左上角，单击 **☰ > 集群管理**。 +1. 在**集群**页面上，转到要通过 SSH 连接到节点的集群，然后单击集群名称。 +1. 在**主机池**选项卡上，找到要远程访问的节点，然后单击 **⋮ > 下载 SSH 密钥**。这将下载用于 SSH 的文件的 ZIP 包。 +1. 将 ZIP 文件解压缩到任何位置。 +1. 打开终端。转到解压了的 ZIP 文件的位置。 +1. 输入以下命令： + + ``` + ssh -i id_rsa root@ + ``` + +## 封锁节点 + +_封锁_ 节点表示将节点标记为不可调度。此功能适用于在短期维护（如重启，升级或停用）时在节点上执行短期任务。完成后，重新打开电源并通过取消封锁使节点再次可调度。 + +## 清空节点 + +_清空_ 指的是先封锁节点，然后驱逐其所有 pod 的过程。此功能对于执行节点维护（如内核升级或硬件维护）很有用。它可以防止新的 pod 部署到节点，同时能重新分配现有的 pod，从而避免用户遇到服务中断的情况。 + +- 具有副本集的 pod 将被一个新的 pod 替换，该新 pod 将被调度到一个新节点。此外，如果 pod 是服务的一部分，则客户端将自动重定向到新的 pod。 + +- 对于没有副本集的 pod，你需要调出 pod 的新副本。如果该 pod 不是服务的一部分，将客户端重定向到它。 + +你可以清空处于 `cordoned` 或 `active` 状态的节点。清空一个节点时，该节点会被封锁，然后会评估节点是否满足清空的必备要求，如果满足要求，则会驱逐节点的 pod。 + +但是，你可以在启动清空时覆盖清空条件。你还有机会设置宽限期和超时值。 + +### 激进和安全的清空选项 + +为集群配置升级策略时，你将能够启用节点清空。如果启用了节点清空，你将能够配置如何删除和重新调度 pod。 + +- **激进模式** + + 在这种模式下，即使 pod 没有控制器也不会被重新调度到新节点。Kubernetes 会认为你拥有自己的 pod 删除逻辑。 + + Kubernetes 还会认为你有处理使用 emptyDir 的 pod 的实现。如果 Pod 使用 emptyDir 存储本地数据，你可能无法安全地删除该 pod，因为一旦 Pod 从节点中删除，emptyDir 中的数据将被删除。选择激进模式将删除这些 pod。 + +- **安全模式** + + 如果一个节点有独立的 pod 或临时数据，它将被封锁但不会被清空。 +### 宽限期 + +给每个 pod 清理的超时时间，从而让它们优雅地退出。例如，pod 可能需要完成任何未完成的请求、回滚事务或将状态保存到某个外部存储。如果该值为负数，将使用 pod 中指定的默认值。 + +### 超时 + +在清空放弃之前应该继续等待的时间。 + +:::note Kubernetes 已知问题： + +Kubernetes 1.12 之前的版本中，在清空节点时不会强制执行[超时设置](https://github.com/kubernetes/kubernetes/pull/64378)。 + +::: + +### 清空和封锁状态 + +如果有任何与用户输入相关的错误，节点会由于清空失败进入 `cordoned` 状态。你可以更正输入并再次尝试清空节点，也可以通过解封节点来中止。 + +如果清空没有错误，则节点会进入 `draining` 状态。当节点处于此状态时，你可以选择停止清空，这将停止清空过程并将节点的状态更改为 `cordoned`。 + +清空成功完成后，节点将处于 `drained` 状态。然后你可以关闭或删除节点。 + +有关**封锁和清空**的更多信息，请参阅 [Kubernetes 文档](https://kubernetes.io/docs/tasks/administer-cluster/safely-drain-node/)。 + +## 标记 Rancher 忽略的节点 + +某些解决方案（例如 F5 的 BIG-IP 集成）可能需要创建一个不会注册到集群的节点。 + +由于节点永远不会完成注册，因此它在 Rancher UI 中总是显示为不健康。 + +在这种情况下，你可能希望将节点标记为 Rancher 忽略的节点，从而让 Rancher 仅在节点实际发生故障时将节点状态显示为不健康。 + +你可以使用 Rancher UI 或 `kubectl` 标记要忽略的节点。 + +:::note + +已知一个[未解决的问题](https://github.com/rancher/rancher/issues/24172)，即标记为被忽略的节点可能会卡在更新状态。 + +::: + + +### 使用 kubectl 标记要忽略的节点 + +要添加 Rancher 忽略的节点，请使用 `kubectl` 创建具有以下标签的节点： + +``` +cattle.rancher.io/node-status: ignore +``` + +**结果**：如果将节点添加到集群中，Rancher 将不会尝试与该节点同步。该节点仍然可以是集群的一部分，并且可以使用 `kubectl` 列出。 + +如果在将节点添加到集群之前添加了标签，则该节点将不会显示在 Rancher UI 中。 + +如果在将节点添加到 Rancher 集群后添加标签，则不会从 UI 中删除该节点。 + +如果你使用 Rancher UI 或 API 从 Rancher server 中删除节点，假如 `nodeName` 在 Rancher API 下的 `v3/settings/ignore-node-name` 中列出，则不会从集群中删除该节点。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/manage-clusters/projects-and-namespaces.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/manage-clusters/projects-and-namespaces.md new file mode 100644 index 00000000000..7a58bef7089 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/manage-clusters/projects-and-namespaces.md @@ -0,0 +1,194 @@ +--- +title: 使用 Rancher 的项目和 Kubernetes 命名空间 +description: Rancher Projects 减轻了集群的管理负担并支持多租户。学习创建项目并将项目划分为 Kubernetes 命名空间 +--- + +命名空间是 Kubernetes 的概念，它允许你在集群中使用虚拟集群。这对于将集群划分为单独的“虚拟集群”很有用，每个“虚拟集群”都有自己的访问控制和资源配额。 + +项目是一组命名空间，是 Rancher 引入的一个概念。项目允许你将多个命名空间作为一个组进行管理，并在其中执行 Kubernetes 操作。你可以使用项目来支持多租户，以便团队可以在集群内访问项目，而无需访问同一集群中的其他项目。 + +:::note + +UI 上不再强调项目，因为不需要在项目范围内创建 Kubernetes 资源。但是，如果启用了旧版功能开关，则仍可以在项目范围内创建诸如 [Secrets](../../new-user-guides/kubernetes-resources-setup/secrets.md#在项目中创建密文) 之类的资源。 + +::: + +本文介绍项目和命名空间如何与 Rancher 一起使用。 + +## 关于命名空间 + +命名空间是 Kubernetes 引入的一个概念。详情请参见[命名空间的官方 Kubernetes 文档](https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/)。 + +:::note + +Kubernetes 支持由同一个物理集群支持的多个虚拟集群。这些虚拟集群称为命名空间。命名空间适用于多用户分布在多个团队或项目中的环境。如果你的集群只有几个到几十个用户，你不需要创建或考虑使用命名空间。 + +::: + +命名空间提供以下功能： + +- **为名称提供范围**：资源名称在命名空间内必须是唯一的，但跨命名空间时则不需要。命名空间不能相互嵌套，每个 Kubernetes 资源只能位于一个命名空间中。 +- **资源配额**：命名空间提供了在多用户之间划分集群资源的方法。 + +你可以在项目级别分配资源，以便项目中的每个命名空间都可以使用这些资源。你也可以通过将资源显式分配给命名空间来绕过此继承模式。 + +你可以将以下资源直接分配给命名空间： + +- [工作负载](../kubernetes-resources-setup/workloads-and-pods/workloads-and-pods.md) +- [负载均衡器/Ingress](../kubernetes-resources-setup/load-balancer-and-ingress-controller/load-balancer-and-ingress-controller.md) +- [服务发现记录](../kubernetes-resources-setup/create-services.md) +- [持久卷声明](../manage-clusters/create-kubernetes-persistent-storage/create-kubernetes-persistent-storage.md) +- [证书](../kubernetes-resources-setup/encrypt-http-communication.md) +- [ConfigMap](../kubernetes-resources-setup/configmaps.md) +- [镜像仓库](../kubernetes-resources-setup/kubernetes-and-docker-registries.md) +- [密文](../kubernetes-resources-setup/secrets.md) + +为了在 vanilla Kubernetes 集群中管理权限，集群管理员要为每个命名空间配置基于角色的访问策略。Rancher 在项目级别上分配用户权限，项目中的命名空间会自动继承项目的权限。 + +有关创建和移动命名空间的更多信息，请参阅[命名空间](../../new-user-guides/manage-namespaces.md)。 + +### 命名空间和 kubectl 的 RBAC 问题 + +由于项目是 Rancher 引入的概念，因此 kubectl 不能将命名空间的创建限制在创建者可以访问的项目中。 + +这意味着当具有项目范围权限的普通用户使用 `kubectl` 创建命名空间时，由于 `kubectl` 不需要将新命名空间限制在特定项目中，创建的命名空间可能无法使用。 + +如果你的权限仅限于项目级别，则最好[通过 Rancher 创建命名空间](../../new-user-guides/manage-namespaces.md)，以确保你有权访问该命名空间。 + +如果普通用户是项目所有者，则该用户将能够在该项目中创建命名空间。Rancher UI 将阻止该用户在他们有权访问的项目之外创建命名空间。 + +## 关于项目 + +在层次结构方面： + +- 集群包含项目 +- 项目包含命名空间 + +你可以使用项目来支持多租户，以便团队可以在集群内访问项目，而无需访问同一集群中的其他项目。 + +在 Kubernetes 的基础版本中，RBAC 或集群资源等功能被分配给了各个命名空间。项目允许你让个人或团队同时访问多个命名空间来节省时间。 + +你可以使用项目来执行以下操作： + +- 将用户分配到一组命名空间（即[项目成员身份](../authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/cluster-and-project-roles.md)）。 +- 在项目中为用户分配特定角色。角色可以是所有者、成员、只读或[自定义](../authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/custom-roles.md)。 +- 为项目分配资源。 +- 分配 Pod 安全策略。 + +创建集群时，会在其中自动创建两个项目： + +- [Default 项目](#集群的-default-项目) +- [System 项目](#system-项目) + +### 集群的 Default 项目 + +使用 Rancher 配置集群时，Rancher 会自动为集群创建一个 `default` 项目。你可以使用这个项目来开始使用集群。但你始终可以删除该项目，并用具有更多描述性名称的项目替换它。 + +如果你只需要使用 `default` 命名空间，那么你就不需要 Rancher 中 **Default** 之外的其他项目。 + +如果你需要 **Default** 之外的其他项目，你可以在 Rancher 中创建更多项目来隔离命名空间、应用和资源。 + +### System 项目 + +故障排除时，你可以查看 `system` 项目来检查 Kubernetes 系统中重要的命名空间是否正常。这是一个易于访问的项目，能让你避免对系统命名空间容器进行逐个排查。 + +要打开这个项目，请打开集群视图并单击**集群 > 项目/命名空间**。该视图显示了 `system` 项目中的所有命名空间。 + +`system` 项目： + +- 在你配置集群时自动创建。 +- 列出存在于 `v3/settings/system-namespaces` 中的所有命名空间（如果存在）。 +- 允许你添加更多命名空间，或将项目内的命名空间移动到其他项目。 +- 无法删除，因为它是集群操作所必需的。 + +:::note + +在启用了项目网络隔离的 RKE 集群中，`system` 项目会覆盖项目网络隔离选项，以便项目能与其他项目通信、收集日志和检查健康状态。 + +::: + +## 项目授权 + +普通用户仅在两种情况下会被授权访问项目： + +- 管理员、集群所有者或集群成员将普通用户显式添加到项目的**成员**中。 +- 普通用户可以访问他们自己创建的项目。 + +## Pod 安全策略 + +Rancher 在 Kubernetes 之上进行了扩展，除了集群级别之外，还允许在项目级别应用 [Pod 安全策略](https://kubernetes.io/docs/concepts/policy/pod-security-policy/)。但是，最佳实践是在集群级别应用 Pod 安全策略。 + +## 创建项目 + +本节介绍如何创建具有名称以及可选 pod 安全策略、成员和资源配额的新项目。 + +1. [命名新项目](#命名新项目) +1. [推荐：添加项目成员](#推荐添加项目成员) +1. [可选：添加资源配额](#可选添加资源配额) + +### 命名新项目 + +1. 在左上角，单击 **☰ > 集群管理**。 +1. 在**集群**页面上，转到要在其中创建项目的集群，然后单击 **Explore**。 +1. 单击**集群 > 项目/命名空间**。 +1. 单击**创建项目**。 +1. 输入**项目名称**。 + +### 推荐：添加项目成员 + +使用**成员**为其他用户提供项目访问权限和角色。 + +默认情况下，你的用户会被添加为项目的 `Owner`（所有者）。 + +:::note 权限说明： + +- 如果用户分配到了项目的`所有者`或`成员`角色，用户会自动继承`命名空间创建`角色。然而，这个角色是 [Kubernetes ClusterRole](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#role-and-clusterrole)，这表示角色的范围会延展到集群中的所有项目。因此，对于显式分配到了项目`所有者`或`成员`角色的用户来说，即使只有`只读`角色，这些用户也可以在分配给他们的其他项目中创建命名空间。 + +- 默认情况下，Rancher 的`项目成员`角色继承自 `Kubernetes-edit` 角色，而`项目所有者`角色继承自 `Kubernetes-admin` 角色。因此，`项目成员`和`项目所有者`角色都能管理命名空间，包括创建和删除命名空间。 + +- 选择`自定义`来立即创建自定义角色：[自定义项目角色](../authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/cluster-and-project-roles.md#自定义项目角色)。 + +::: + +要添加成员： + +1. 在**成员**选项卡中，单击**添加**。 +1. 在**选择成员**字段中，搜索要分配项目访问权限的用户或组。如果你启用了外部身份验证，则只能搜索组。 + + :::note Notes: + + - At least 2 characters must be typed in the search box for results to appear. + - Users can be searched based on their username or display name. + - Search is prefix-based (e.g., a user named `Stan Dard` will appear when searching for `Sta`, but not when searching for `Dar`) and case-sensitive. + + ::: +1. 在**项目权限**中选择一个角色。如需更多信息，请参阅[项目角色文档](../authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/cluster-and-project-roles.md)。 + +### 可选：添加资源配额 + +资源配额用于限制项目（及其命名空间）可以使用的资源。有关详细信息，请参阅[资源配额](../../advanced-user-guides/manage-projects/manage-project-resource-quotas/manage-project-resource-quotas.md)。 + +要添加资源配额： + +1. 在**资源配额**选项卡中，单击**添加资源**。 +1. 选择一个**资源类型**。有关详细信息，请参阅[资源配额](../../advanced-user-guides/manage-projects/manage-project-resource-quotas/manage-project-resource-quotas.md)。 +1. 输入**项目限制**和**命名空间默认限制**的值。 +1. **可选**：指定**容器默认资源限制**，这将应用于项目中启动的所有容器。如果资源配额设置了 CPU 或内存限制，则建议使用该参数。可以在单个命名空间或容器级别上覆盖它。有关详细信息，请参阅[容器默认资源限制](../../advanced-user-guides/manage-projects/manage-project-resource-quotas/manage-project-resource-quotas.md)。 +1. 单击**创建**。 + +**结果**：项目已创建。你可以从集群的**项目/命名空间**视图中查看它。 + +| 字段 | 描述 | +| ----------------------- | -------------------------------------------------------------------------------------------------------- | +| 项目限制 | 项目的总资源限制。 | +| 命名空间默认限制 | 每个命名空间的默认资源限制。此限制在创建时会沿用到项目中的每个命名空间。项目中所有命名空间的限制之和不应超过项目限制。 | + +## 删除项目 + +1. 在左上角，单击 **☰ > 集群管理**。 +1. 在**集群**页面上，转到项目连接的集群，然后单击 **Explore**。 +1. 单击**集群 > 项目/命名空间**。 +1. 找到要删除的项目，点击 **⋮**。 +1. 选择**删除**。 + +删除项目时，以前与该项目关联的任何命名空间都将保留在集群上。你可以在 Rancher UI **项目/命名空间**页面的**不在项目内**选项卡中找到这些命名空间。你可以通过[移动](../manage-namespaces.md#将命名空间移动到另一个项目)来将它们重新分配给项目。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/manage-clusters/provisioning-storage-examples/nfs-storage.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/manage-clusters/provisioning-storage-examples/nfs-storage.md new file mode 100644 index 00000000000..35b432d9f01 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/manage-clusters/provisioning-storage-examples/nfs-storage.md @@ -0,0 +1,75 @@ +--- +title: NFS 存储 +--- + +在将 NFS 存储卷插件用于 Rancher deployment 之前，你需要配置 NFS 服务器。 + +:::note + +- 如果你已经拥有 NFS 共享，则无需配置新的 NFS 服务器即可在 Rancher 中使用 NFS 卷插件。这样的话，你可以跳过此过程的其余部分并直接[添加存储](../create-kubernetes-persistent-storage/create-kubernetes-persistent-storage.md)。 + +- 此教程演示了如何使用 Ubuntu 设置 NFS 服务器。你也应该能够将这些说明用于其他 Linux 发行版（例如 Debian、RHEL、Arch Linux 等）。有关如何使用另一个 Linux 发行版创建 NFS 服务器的官方说明，请参阅发行版的文档。 + +::: + +:::note 推荐： + +要简化管理防火墙规则的过程，请使用 NFSv4。 + +::: + +1. 使用远程终端连接，登录到你打算用于 NFS 存储的 Ubuntu 服务器。 + +1. 输入以下命令： + + ``` + sudo apt-get install nfs-kernel-server + ``` + +1. 输入以下命令，设置存储目录以及用户访问权限。如果你想使用不同的存储目录，请修改该命令： + + ``` + mkdir -p /nfs && chown nobody:nogroup /nfs + ``` + - `-p /nfs` 参数在根目录下创建一个名为 `nfs` 的目录。 + - `chown nobody:nogroup /nfs` 参数允许对存储目录的所有访问。 + +1. 创建 NFS 导出表。此表设置 NFS 服务器上的目录路径，这些路径会暴露给将使用服务器进行存储的节点。 + + 1. 使用文本编辑器打开 `/etc/exports`。 + 1. 添加你在步骤 3 中创建的 `/nfs` 文件夹的路径以及集群节点的 IP 地址。为集群中的每个 IP 地址添加一个条目。在每个地址及其附带的参数后面加上一个作为分隔符的空格： + + ``` + /nfs (rw,sync,no_subtree_check) (rw,sync,no_subtree_check) (rw,sync,no_subtree_check) + ``` + + :::tip + + 你可以将 IP 地址替换为子网，例如，`10.212.50.12/24`。 + + ::: + + 1. 通过输入以下命令更新 NFS 表： + + ``` + exportfs -ra + ``` + +1. 打开 NFS 使用的端口。 + + 1. 要找出 NFS 正在使用的端口，请运行以下命令： + + ``` + rpcinfo -p | grep nfs + ``` + 2. [打开上一个命令输出的端口](https://help.ubuntu.com/lts/serverguide/firewall.html.en)。例如，以下命令打开端口 2049： + + ``` + sudo ufw allow 2049 + ``` + +**结果**：已将 NFS 服务器配置你的 Rancher 节点的存储。 + +## 后续操作 + +在 Rancher 中，将 NFS 服务器添加为存储卷和/或存储类。添加服务器后，你可以将其用于存储以进行部署。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/manage-clusters/provisioning-storage-examples/persistent-storage-in-amazon-ebs.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/manage-clusters/provisioning-storage-examples/persistent-storage-in-amazon-ebs.md new file mode 100644 index 00000000000..3955afea1f2 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/manage-clusters/provisioning-storage-examples/persistent-storage-in-amazon-ebs.md @@ -0,0 +1,15 @@ +--- +title: 在 Amazon EBS 中创建持久存储 +--- + +本文介绍如何在 EC2 中设置 Amazon 的 Elastic Block Store。 + +1. 在 EC2 控制台中，转到左侧面板中的 **ELASTIC BLOCK STORE** 中，然后单击 **Volumes**。 +1. 单击 **Create Volume**。 +1. 可选：配置卷的大小或其他选项。你需要在卷要挂载到的实例所在的可用区中创建卷。 +1. 单击 **Create Volume**。 +1. 点击 **Close**。 + +**结果**：已创建持久存储。 + +有关如何在 Rancher 中设置新创建的存储的详细信息，请参阅[设置现有存储](../../../new-user-guides/manage-clusters/create-kubernetes-persistent-storage/manage-persistent-storage/set-up-existing-storage.md)。 \ No newline at end of file diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/manage-clusters/provisioning-storage-examples/provisioning-storage-examples.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/manage-clusters/provisioning-storage-examples/provisioning-storage-examples.md new file mode 100644 index 00000000000..3e093ff09e4 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/manage-clusters/provisioning-storage-examples/provisioning-storage-examples.md @@ -0,0 +1,15 @@ +--- +title: 配置存储示例 +--- + + + + + +Rancher 通过各种卷插件来支持持久存储。但是，在使用这些插件将持久存储绑定到工作负载之前，无论是使用云解决方案还是你自己管理的本地解决方案，你都必须先配置存储本身。 + +为了你的方便，Rancher 提供了配置主流存储的参考文档： + +- [NFS](nfs-storage.md) +- [vSphere](vsphere-storage.md) +- [EBS](persistent-storage-in-amazon-ebs.md) diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/manage-clusters/provisioning-storage-examples/vsphere-storage.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/manage-clusters/provisioning-storage-examples/vsphere-storage.md new file mode 100644 index 00000000000..db36152d271 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/manage-clusters/provisioning-storage-examples/vsphere-storage.md @@ -0,0 +1,71 @@ +--- +title: vSphere 存储 +--- + +要为有状态的工作负载提供 vSphere 存储，我们建议创建一个 vSphereVolume StorageClass。当工作负载通过 PersistentVolumeClaim 请求卷时，这种做法会动态调配 vSphere 存储。 + +为了在 vSphere 中动态调配存储，必须启用 vSphere 提供商。有关更多信息，请参阅[树外 vSphere](../../../new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-cloud-providers/configure-out-of-tree-vsphere.md) 和[树内 vSphere](../../../new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-cloud-providers/configure-in-tree-vsphere.md)。 + +## 先决条件 + +为了在 [Rancher Kubernetes Engine (RKE)](../../launch-kubernetes-with-rancher/launch-kubernetes-with-rancher.md) 集群中配置 vSphere 卷，[vSphere cloud provider](https://rancher.com/docs/rke/latest/en/config-options/cloud-providers/vsphere) 必须在[集群选项](../../../../reference-guides/cluster-configuration/rancher-server-configuration/rke1-cluster-configuration.md)中显式启用。 + +## 创建一个 StorageClass + +:::tip + +你也可以使用 `kubectl` 命令行工具来执行以下步骤。有关详细信息，请参阅[关于持久卷的 Kubernetes 文档](https://kubernetes.io/docs/concepts/storage/persistent-volumes/)。 + +::: + +1. 点击 **☰ > 集群管理**。 +1. 选择要使用 vSphere 存储的集群，然后单击**浏览**。 +1. 在左侧导航栏中，选择**存储 > StorageClass**。 +1. 单击**创建**。 +3. 输入存储类的**名称**。 +4. 在 **Provisioner**下，选择 **VMWare vSphere 卷**。 + + ![](/img/vsphere-storage-class.png) + +5. 可选地，你可以在**参数**下指定存储类的其他属性。有关详细信息，请参阅 [vSphere 存储文档](https://github.com/vmware-archive/vsphere-storage-for-kubernetes/blob/master/documentation/storageclass.md)。 +5. 单击**创建**。 + +## 创建使用 vSphere 卷的工作负载 + +1. 在左侧导航栏中，单击**工作负载**。 +1. 单击**创建**。 +1. 单击 **StatefulSet**。 +1. 在**卷声明模板**选项卡上，单击**添加声明模板**。 +1. 输入持久卷名称。 +1. 在**存储类**字段中，选择你创建的 vSphere 存储类。 +6. 输入卷所需的**容量**。然后单击**定义**。 +7. 在**挂载点**字段中指定路径。这是卷将安装在容器文件系统中的完整路径，例如 `/persistent`。 +8. 单击**创建**。 + +## 验证卷的持久性 + +1. 在左侧导航栏中，单击**工作负载 > Pod**。 +1. 转到你刚刚创建的工作负载，然后单击 **⋮ > 执行命令行**。 +2. 请注意卷已挂载到的根目录下的目录（在本例中为 `/persistent`）。 +3. 通过执行命令 `touch //data.txt` 在卷中创建一个文件。 +4. 关闭 shell 窗口。 +5. 单击工作负载的名称以显示详细信息。 +7. 单击 **⋮ > 删除**。 +8. 观察 pod 是否被删除。为了让工作负载维持在所配置的单个有状态 pod 的规模，之后会调度一个新的 Pod 来替换该 Pod。 +9. 替换的 pod 运行后，单击**执行命令行**。 +10. 输入 `ls -l /` 以检查卷所挂载的目录的内容。请注意，你之前创建的文件仍然存在。 + + ![workload-persistent-data](/img/workload-persistent-data.png) + +## 为什么使用 StatefulSet 替代 Deployment + +对于消耗 vSphere 存储的工作负载，你应该始终使用 [StatefulSets](https://kubernetes.io/docs/concepts/workloads/controllers/statefulset/)，因为这种资源类型旨在解决 VMDK 块存储警告。 + +由于 vSphere 卷由 VMDK 块存储支持，因此它们仅支持 `ReadWriteOnce` 的[访问模式](https://kubernetes.io/docs/concepts/storage/persistent-volumes/#persistentvolumeclaims)。此设置限制卷，使其一次只能挂载到一个 pod（除非使用该卷的所有 pod 位于同一节点上）。如果 deployment 资源消耗 vSphere 卷，则 deployment 资源无法用于扩展到超出单个副本。 + +即使使用仅具有单个副本的 deployment 资源也可能在更新 deployment 时出现死锁情况。如果更新的 pod 被调度到不同的节点，由于 VMDK 仍然连接到另一个节点，因此 pod 将无法启动。 + +## 相关链接 + +- [用于 Kubernetes 的 vSphere 存储](https://github.com/vmware-archive/vsphere-storage-for-kubernetes/tree/master/documentation) +- [Kubernetes 持久卷](https://kubernetes.io/docs/concepts/storage/persistent-volumes/) diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/manage-clusters/rotate-certificates.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/manage-clusters/rotate-certificates.md new file mode 100644 index 00000000000..e231727abbd --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/manage-clusters/rotate-certificates.md @@ -0,0 +1,50 @@ +--- +title: 证书轮换 +--- + +:::caution + +轮换 Kubernetes 证书可能会导致集群在组件重启时暂时不可用。对于生产环境，建议在维护时段内执行此操作。 + +::: + +默认情况下，Kubernetes 集群需要证书，Rancher 启动的 Kubernetes 集群会自动为 Kubernetes 组件生成证书。在证书过期之前或被泄露后轮换证书非常重要。证书轮换后，Kubernetes 组件会自动重启。 + +可以为以下服务轮换证书： + +- admin +- api-server +- controller-manager +- scheduler +- rke2-controller +- rke2-server +- cloud-controller +- etcd +- auth-proxy +- kubelet +- kube-proxy + +:::note + +如果你未轮换 webhook 证书，且证书用了一年后已经过期，请参阅此[页面](../../../troubleshooting/other-troubleshooting-tips/expired-webhook-certificate-rotation.md)。 + +::: + +## 证书轮换 + +Rancher 启动的 Kubernetes 集群能够通过 UI 轮换自动生成的证书。 + +1. 在左上角，单击 **☰ > 集群管理**。 +1. 在**集群**页面上，转到要轮换证书的集群，然后单击 **⋮ > 轮换证书**。 +1. 选择要轮换的证书。 + + * 轮换所有服务证书（使用相同的 CA） + * 轮换单个服务，并从下拉菜单中选择其中一项服务。 + +1. 单击**保存**。 + +**结果**：将轮换所选证书，相关服务将重新启动以使用新证书。 + +## 补充说明 + +在 RKE2/K3s 中，etcd 和 controlplane 节点都被视为相同的 `server`。因此，如果你轮换其中一个组件的服务证书，则两者的证书都会被轮换。证书只会针对指定的服务更改，但你会看到两个组件的节点都进入更新状态。你可能还会看到仅 Worker 节点进入更新状态。这是在证书更改后重启 Worker，以确保他们获得最新的客户端证书。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/manage-clusters/rotate-encryption-key.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/manage-clusters/rotate-encryption-key.md new file mode 100644 index 00000000000..f05c3b9d4d9 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/manage-clusters/rotate-encryption-key.md @@ -0,0 +1,19 @@ +--- +title: 加密密钥轮换 +--- + +:::note 重要 + +加密密钥轮换默认启用，不能禁用。 + +::: + +要在 Rancher UI 中轮换密钥： + +1. 点击 **☰ > 集群管理**。 + +1. 在所选集群旁边的屏幕最右侧选择 **⋮ > Rotate Encryption Keys**： + + ![加密密钥轮换](/img/rke2-encryption-key.png) + +> **注意**：有关 RKE2 密文加密配置的更多信息，请参阅 [RKE2 文档](https://docs.rke2.io/security/secrets_encryption)。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/manage-namespaces.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/manage-namespaces.md new file mode 100644 index 00000000000..c91f5830da3 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/manage-namespaces.md @@ -0,0 +1,74 @@ +--- +title: 命名空间 +--- + +在 Rancher 中，你可以将项目进一步划分为多个[命名空间](https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/)，项目是由物理集群支持的，而命名空间是项目中的虚拟集群。当项目和 `default` 命名空间不能满足你的需求时，你可以在项目中创建多个命名空间来隔离应用和资源。 + +你可以在项目层级分配资源，从而使项目中的每个命名空间可以使用这些资源，也可以单独给某个命名空间显式分配资源。 + +可以直接分配给命名空间的资源包括： + +- [工作负载](./kubernetes-resources-setup/workloads-and-pods/workloads-and-pods.md) +- [负载均衡器/Ingress](./kubernetes-resources-setup/load-balancer-and-ingress-controller/load-balancer-and-ingress-controller.md) +- [服务发现记录](./kubernetes-resources-setup/create-services.md) +- [持久卷声明](./manage-clusters/create-kubernetes-persistent-storage/create-kubernetes-persistent-storage.md) +- [证书](./kubernetes-resources-setup/encrypt-http-communication.md) +- [ConfigMap](./kubernetes-resources-setup/configmaps.md) +- [镜像仓库](./kubernetes-resources-setup/kubernetes-and-docker-registries.md) +- [密文](./kubernetes-resources-setup/secrets.md) + +为了在 vanilla Kubernetes 集群中管理权限，集群管理员要为每个命名空间配置基于角色的访问策略。Rancher 在项目级别上分配用户权限，项目中的命名空间会自动继承项目的权限。 + +:::note + +如果你使用 `kubectl`创建命名空间，由于 `kubectl` 不要求将新命名空间限定在你可以访问的项目内，因此你可能无法使用该命名空间。如果你的权限仅限于项目级别，则最好[通过 Rancher 创建命名空间](#创建命名空间)，以确保你有权访问该命名空间。 + +::: + +## 创建命名空间 + +创建一个新的命名空间来隔离项目中的应用和资源。 + +:::tip + +使用可以分配给命名空间的项目资源（例如，[工作负载](kubernetes-resources-setup/workloads-and-pods/deploy-workloads.md)、[证书](kubernetes-resources-setup/encrypt-http-communication.md)、[ConfigMap](kubernetes-resources-setup/configmaps.md) 等）时，你可以动态创建命名空间。 + +::: + +1. 在左上角，单击 **☰ > 集群管理**。 +1. 在**集群**页面上，转到要在其中创建命名空间的集群，然后单击 **Explore**。 +1. 单击**集群 > 项目/命名空间**。 +1. 转到要添加命名空间的项目，并单击**创建命名空间**。或者，你也可以转到**不在项目内**以创建不与项目关联的命名空间。 + +1. **可选**：如果你的项目具有有效的[资源配额](../advanced-user-guides/manage-projects/manage-project-resource-quotas/manage-project-resource-quotas.md)，你可以覆盖默认资源**限制**（限制命名空间可以使用的资源）。 + +1. 输入**名称**，然后单击**创建**。 + +**结果**：已将命名空间添加到项目中。你可以开始将集群资源分配给命名空间。 + +## 将命名空间移动到另一个项目 + +在某些情况下（例如希望其他团队使用该应用时），集群管理员和成员可能需要将命名空间移动到另一个项目： + +1. 在左上角，单击 **☰ > 集群管理**。 +1. 在**集群**页面上，转到需要移动命名空间的集群，然后单击 **Explore**。 +1. 单击**集群 > 项目/命名空间**。 +1. 转到要移动的命名空间，然后单击 **⋮ > 移动**。 + +1. 选择要移动到另一个项目的命名空间。然后单击**移动**。你可以同时移动多个命名空间。 + + :::note 注意事项： + + - 不要移动 `System` 项目中的命名空间。移动命名空间可能会对集群网络产生不利影响。 + - 你不能将命名空间移动到已配置[资源配额](../advanced-user-guides/manage-projects/manage-project-resource-quotas/manage-project-resource-quotas.md)的项目中。 + - 如果你将命名空间从已设置配额的项目移动到未设置配额的项目，则会删除该命名空间的配额。 + +1. 为新命名空间选择一个新项目，然后单击**移动**。你也可以选择**无**，从而将命名空间从所有项目中移除。 + +**结果**：你的命名空间已移至其他项目（或从所有项目中移除）。如果命名空间绑定了项目资源，命名空间会释放这些资源，然后绑定新项目的资源。 + +## 编辑命名空间资源配额 + +你可以覆盖命名空间默认限制，从而为特定命名空间提供对更多（或更少）项目资源的访问权限： + +有关详细信息，请参阅[编辑命名空间资源配额](../advanced-user-guides/manage-projects/manage-project-resource-quotas/override-default-limit-in-namespaces.md)。 \ No newline at end of file diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/new-user-guides.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/new-user-guides.md new file mode 100644 index 00000000000..91cfa77fe1d --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/new-user-guides/new-user-guides.md @@ -0,0 +1,13 @@ +--- +title: 新用户指南 +--- + + + + + +新用户指南，也称为 **教程**，描述了用户在完成一些具体操作时要遵循的实用步骤。这些文档被称为“以学习为导向”的文档，用户通过“实际操作”来学习。 + +新用户指南旨在指导初学者或 Rancher 的日常用户通过一系列步骤来学习如何做某件事。目标是让用户可以通过易于操作、有意义的、可重复的指示来学习如何完成任务。这些指南将帮助用户完成工作，然后立即获得承诺的结果。 + +普通的 Rancher 用户的技术水平高于“初学者”，但是新用户指南旨在同等的帮助新用户、初学者以及经验丰富的 Rancher 客户，这是通过结合使用高级和技术语言来介绍主题并指导用户完成每个 Rancher 用户都必须了解的一般任务来实现的。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/cis-scans/cis-scans.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/cis-scans/cis-scans.md new file mode 100644 index 00000000000..41ca4d923cb --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/cis-scans/cis-scans.md @@ -0,0 +1,121 @@ +--- +title: CIS 扫描 +--- + + + + + +Rancher 可以通过运行安全扫描来检查 Kubernetes 是否按照 CIS Kubernetes Benchmark 中定义的安全最佳实践进行部署。CIS 扫描可以运行在任何 Kubernetes 集群，包括托管的 Kubernetes，例如 EKS、AKS 和 GKE。 + +`rancher-cis-benchmark` 应用使用了 kube-bench, ，这是 Aqua Security 的开源工具，用于检查集群是否符合 CIS Kubernetes Benchmark。此外，为了生成集群级别的报告，此应用使用了 Sonobuoy 来聚合报告。 + +## 关于 CIS Benchmark + +CIS（Center for Internet Security）是一个 501(c\)(3) 非营利组织，成立于 2000 年 10 月，其使命是识别、开发、验证、促进和维持网络防御的最佳实践方案，并建立和指导社区，以在网络空间中营造信任的环境。该组织总部位于纽约东格林布什，其成员包括大公司、政府机构和学术机构。 + +CIS Benchmark 是目标系统安全配置的最佳实践。CIS Benchmark 是由安全专家、技术供应商、公开和私人社区成员，以及 CIS Benchmark 开发团队共同志愿开发的。 + +在 CIS 网站上[注册](https://learn.cisecurity.org/benchmarks)以查看官方 Benchmark 文档。 + +## 关于生成的报告 + +每次扫描都会生成一份报告，你可以在 Rancher UI 中查看该报告，并以 CSV 格式下载它。 + +默认情况下使用 CIS Benchmark v1.6。 + +Benchmark 版本包含在生成的报告中。 + +Benchmark 提供两种类型的建议，分别是自动（Automated）和手动（Manual）。Benchmark 中标记为 Manual 的建议不包含在生成的报告中。 + +一些测试会被标记为“不适用”。由于 Rancher 配置 RKE 集群的方式，这些测试不会在任何 CIS 扫描中运行。有关如何审核测试结果，以及为什么某些测试会被标记为不适用，请参阅 Rancher 的 Kubernetes 对应版本的[自测指南](../../reference-guides/rancher-security/rancher-security.md#CIS-Benchmark-和自我评估)。 + +该报告包含以下信息： + +| 报告中的列 | 描述 | +|-------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `id` | CIS Benchmark 的 ID 号。 | +| `description` | CIS Benchmark 测试的描述。 | +| `remediation` | 为了通过测试需要修复的内容。 | +| `state` | 测试的状态，可以是通过、失败、跳过或不适用。 | +| `node_type` | 节点角色，角色决定了在节点上运行的测试。主测试在 controlplane 节点上运行，etcd 测试在 etcd 节点上运行，节点测试在 Worker 节点上运行。 | +| `audit` | 这是 `kube-bench` 为此测试运行的审计检查。 | +| `audit_config` | 适用于审计脚本的任何配置。 | +| `test_info` | `kube-bench` 报告的测试相关信息（如果存在）。 | +| `commands` | `kube-bench` 报告的测试相关的命令（如果存在）。 | +| `config_commands` | `kube-bench` 报告的测试相关的配置数据（如果存在）。 | +| `actual_value` | 测试的实际值。如果由 `kube-bench` 报告，则会显示。 | +| `expected_result` | 测试的预期值。如果由 `kube-bench` 报告，则会显示。 | + +请参阅[集群加固指南中的表格](../../reference-guides/rancher-security/rancher-security.md)，以了解 Kubernetes、Benchmark、Rancher 以及我们的集群强化指南的版本对应关系。另外，请参阅强化指南，以获取符合 CIS 的集群的配置文件以及修复失败测试的信息。 + +## 测试配置文件 + +以下是可用的配置文件： + +- Generic CIS 1.6 +- Generic CIS 1.20 +- Generic CIS 1.23 +- RKE permissive 1.6 +- RKE hardened 1.6 +- RKE permissive 1.20 +- RKE hardened 1.20 +- RKE permissive 1.23 +- RKE hardened 1.23 +- RKE2 permissive 1.6 +- RKE2 hardened 1.6 +- RKE2 permissive 1.20 +- RKE2 hardened 1.20 +- RKE2 permissive 1.23 +- RKE2 hardened 1.23 +- K3s permissive 1.6 +- K3s hardened 1.6 +- K3s permissive 1.20 +- K3s hardened 1.20 +- K3s permissive 1.23 +- K3s hardened 1.23 +- AKS +- EKS +- GKE + +你还可以通过保存一组要跳过的测试来自定义配置文件。 + +所有配置文件都会有一组不适用的测试，CIS 扫描会跳过这些测试。RKE 集群管理 Kubernetes 的方式导致这些测试被认为不适用。 + +RKE 集群扫描配置文件有两种类型： + +- **Permissive**：此配置文件有一组要跳过的测试，跳过的原因是这些测试会在默认的 RKE Kubernetes 集群上失败。除了跳过的测试列表之外，配置文件也不会运行不适用的测试。 +- **Hardened**：此配置文件不会跳过任何测试（不适用的测试除外）。 + +EKS 和 GKE 集群扫描的配置文件基于这些集群类型特定的 CIS Benchmark 版本。 + +要通过 “Hardened” 配置文件，你需要遵从[强化指南](../../reference-guides/rancher-security/rancher-security.md#Rancher-加固指南)并使用强化指南中定义的 `cluster.yml` 来配置一个强化集群。 + +默认配置文件和支持的 CIS Benchmark 版本取决于扫描的集群类型： + +`rancher-cis-benchmark` 支持 CIS 1.6 Benchmark 版本。 + +- RKE Kubernetes 集群默认使用 RKE Permissive 1.6 配置文件。 +- EKS 和 GKE 有自己的 CIS Benchmark，由 `kube-bench` 发布。这些集群默认使用相应的测试配置文件。 +- RKE2 Kubernetes 集群默认使用 RKE2 Permissive 1.6 配置文件。 +- RKE、RKE2、EKS 和 GKE 以外的集群类型默认使用 Generic CIS 1.5 配置文件。 + +## 跳过和不适用的测试 + +有关要跳过和不适用的测试列表，请参阅[此页面](../../how-to-guides/advanced-user-guides/cis-scan-guides/skip-tests.md)。 + +目前，只有用户定义的跳过测试会在生成报告中标记为跳过。 + +如果某个默认配置文件将某个测试定义为跳过，则该测试也会标记为不适用。 + +## RBAC + +有关权限的详细信息，请参阅[此页面](rbac-for-cis-scans.md)。 + +## 配置 + +有关为扫描、配置文件和 Benchmark 版本配置自定义资源的更多信息，请参阅[此页面](configuration-reference.md)。 + +## 操作指南 + +要了解如何运行 CIS 扫描，请参阅 [CIS 扫描指南](../../how-to-guides/advanced-user-guides/cis-scan-guides/cis-scan-guides.md)。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/cis-scans/configuration-reference.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/cis-scans/configuration-reference.md new file mode 100644 index 00000000000..2b85b101377 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/cis-scans/configuration-reference.md @@ -0,0 +1,105 @@ +--- +title: 配置 +--- + +此配置参考用于帮助你管理由 `rancher-cis-benchmark` 应用创建的自定义资源。这些资源用于在集群上执行 CIS 扫描、跳过测试、设置扫描使用的测试配置文件和其他自定义配置。 + +要配置自定义资源，转到**集群**仪表板。要配置 CIS 扫描： + +1. 在左上角，单击 **☰ > 集群管理**。 +1. 在**集群**页面上，转到要配置 CIS 扫描的集群，然后单击 **Explore**。 +1. 在左侧导航栏中，单击 **CIS Benchmark**。 + +## 扫描 + +扫描是用来根据定义的配置文件，在集群上触发 CIS 扫描的。扫描完成后会创建一份报告。 + +配置扫描时，你需要定义与 `scanProfileName` 参数一起使用的扫描配置文件的名称。 + +下面是一个 ClusterScan 自定义资源示例： + +```yaml +apiVersion: cis.cattle.io/v1 +kind: ClusterScan +metadata: + name: rke-cis +spec: + scanProfileName: rke-profile-hardened +``` + +## 配置文件 + +配置文件包含 CIS 扫描的配置，包括要使用的 Benchmark 测试版本以及要在该 Benchmark 测试中跳过的测试。 + +:::caution + +默认情况下，一些 ClusterScanProfile 会作为 `rancher-cis-benchmark` Chart 的一部分进行安装。如果用户编辑了这些默认 Benchmark 或配置文件，它们会在下一次 Chart 更新时被重置。因此，建议用户不要编辑默认的 ClusterScanProfile。 + +::: + +用户可以通过克隆 ClusterScanProfile 来创建自定义配置文件。 + +跳过的测试会列在 `skipTests` 参数下。 + +创建新配置文件时，你还需要命名配置文件。 + +`ClusterScanProfile` 示例如下： + +```yaml +apiVersion: cis.cattle.io/v1 +kind: ClusterScanProfile +metadata: + annotations: + meta.helm.sh/release-name: clusterscan-operator + meta.helm.sh/release-namespace: cis-operator-system + labels: + app.kubernetes.io/managed-by: Helm + name: "" +spec: + benchmarkVersion: cis-1.5 + skipTests: + - "1.1.20" + - "1.1.21" +``` + +## Benchmark 版本 + +Benchmark 版本是指使用 `kube-bench` 运行的 Benchmark 名称，以及该 Benchmark 的有效配置参数。 + +`ClusterScanBenchmark` 定义了 CIS `BenchmarkVersion` 的名称和测试配置。`BenchmarkVersion` 名称是提供给 `kube-bench` 工具的参数。 + +默认情况下，一些 `BenchmarkVersion` 名称和测试配置会作为 CIS 扫描应用的一部分进行打包。启用此功能后，这些默认 BenchmarkVersion 将自动安装，用户可以使用它们来创建 ClusterScanProfile。 + +:::caution + +如果用户编辑了默认的 BenchmarkVersion，它们会在下一次 Chart 更新时被重置。因此，不建议编辑默认的 ClusterScanBenchmark。 + +::: + +ClusterScanBenchmark 由以下字段组成： + +- `ClusterProvider`：此 Benchmark 适用的集群提供商名称，例如，RKE、EKS、GKE。如果此基准测试可以在任何集群类型上运行，则留空。 +- `MinKubernetesVersion`：集群运行此 Benchmark 测试所需的最低 kubernetes 版本。如果不依赖特定的 Kubernetes 版本，则留空。 +- `MaxKubernetesVersion`：集群运行此 Benchmark 测试所需的最高 Kubernetes 版本。如果不依赖特定的 Kubernetes 版本，则留空。 + +`ClusterScanBenchmark` 示例如下： + +```yaml +apiVersion: cis.cattle.io/v1 +kind: ClusterScanBenchmark +metadata: + annotations: + meta.helm.sh/release-name: clusterscan-operator + meta.helm.sh/release-namespace: cis-operator-system + creationTimestamp: "2020-08-28T18:18:07Z" + generation: 1 + labels: + app.kubernetes.io/managed-by: Helm + name: cis-1.5 + resourceVersion: "203878" + selfLink: /apis/cis.cattle.io/v1/clusterscanbenchmarks/cis-1.5 + uid: 309e543e-9102-4091-be91-08d7af7fb7a7 +spec: + clusterProvider: "" + minKubernetesVersion: 1.15.0 +``` diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/cis-scans/custom-benchmark.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/cis-scans/custom-benchmark.md new file mode 100644 index 00000000000..8cd3c582736 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/cis-scans/custom-benchmark.md @@ -0,0 +1,78 @@ +--- +title: 为集群扫描创建自定义 Benchmark 版本 +--- + +每个 Benchmark 版本都定义了一组测试配置文件，这些文件定义了由 kube-bench 工具运行的 CIS 测试。 +`rancher-cis-benchmark` 应用安装了一些默认的 Benchmark 测试版本，这些版本列在了 CIS Benchmark 测试应用菜单下。 + +但是，某些 Kubernetes 集群可能需要自定义配置 Benchmark 测试。例如，Kubernetes 配置文件或证书的路径可能与上游 CIS Benchmark 的标准位置不同。 + +现在，你可以使用 `rancher-cis-benchmark` 应用来创建自定义 Benchmark 版本，从而运行集群扫描。 + +运行集群扫描时，你需要选择指向特定 Benchmark 版本的配置文件。 + +按照以下所有步骤添加自定义 Benchmark 版本并使用它运行扫描。 + +## 1. 准备自定义 Benchmark 版本 ConfigMap + +要创建自定义 Benchmark 版本，你需要先创建一个包含 Benchmark 版本配置文件的 ConfigMap，并将其上传到要运行扫描的 Kubernetes 集群。 + +假设要添加一个名为 `foo` 的自定义 Benchmark 版本，你可以按照以下步骤准备自定义 Benchmark 版本 ConfigMap： + +1. 创建一个名为 `foo` 的目录，并在该目录中放置所有配置 YAML 文件， kube-bench 工具会搜索这些文件。例如，通用 CIS 1.5 Benchmark 版本的配置 YAML 文件在[此处](https://github.com/aquasecurity/kube-bench/tree/master/cfg/cis-1.5)。 +1. 放置完整的 `config.yaml` 文件，其中包括所有要测试的组件。 +1. 将 Benchmark 版本名称添加到 `config.yaml` 的 `target_mapping` 中： + + ```yaml + target_mapping: + "foo": + - "master" + - "node" + - "controlplane" + - "etcd" + - "policies" + ``` +1. 通过创建 ConfigMap 将此目录上传到 Kubernetes 集群： + + ```yaml + kubectl create configmap -n foo --from-file= + ``` + +## 2. 将自定义 Benchmark 版本添加到集群 + +1. 在左上角，单击 **☰ > 集群管理**。 +1. 在**集群**页面上，转到要添加自定义 Benchmark 的集群，然后单击 **Explore**。 +1. 在左侧导航栏中，单击 **CIS Benchmark > Benchmark 版本**。 +1. 单击**创建**。 +1. 输入自定义 Benchmark 版本的**名称**和描述。 +1. 选择要应用 Benchmark 版本的集群提供商。 +1. 在下拉列表中选择你已上传的 ConfigMap。 +1. 添加最低和最高 Kubernetes 版本限制（如果有）。 +1. 单击**创建**。 + +## 3. 为自定义 Benchmark 版本创建新配置文件 + +要使用你的自定义 Benchmark 版本运行扫描，你需要添加一个指向此 Benchmark 版本的新配置文件： + +1. 在左上角，单击 **☰ > 集群管理**。 +1. 在**集群**页面上，转到要添加自定义 Benchmark 的集群，然后单击 **Explore**。 +1. 在左侧导航栏中，单击 **CIS Benchmark > 配置文件**。 +1. 单击**创建**。 +1. 设置**名称**和描述。在本例中，我们将其命名为 `foo-profile`。 +1. 在下拉列表中选择 Benchmark 版本。 +1. 单击**创建**。 + +## 4. 使用自定义 Benchmark 版本运行扫描 + +指向你的自定义 Benchmark 版本的 `foo` 配置文件创建完成后，你可以创建一个新的扫描，从而在 Benchmark 版本中运行自定义测试。 + +要运行扫描： + +1. 在左上角，单击 **☰ > 集群管理**。 +1. 在**集群**页面上，转到要添加自定义 Benchmark 的集群，然后单击 **Explore**。 +1. 在左侧导航栏中，单击 **CIS Benchmark > 扫描**。 +1. 单击**创建**。 +1. 选择新的集群扫描配置文件。 +1. 单击**创建**。 + +**结果**：已生成带有扫描结果的报告。如需查看结果，请单击显示的扫描名称。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/cis-scans/rbac-for-cis-scans.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/cis-scans/rbac-for-cis-scans.md new file mode 100644 index 00000000000..6398f217c7e --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/cis-scans/rbac-for-cis-scans.md @@ -0,0 +1,46 @@ +--- +title: RBAC +--- + +本文介绍使用 rancher-cis-benchmark 应用所需的权限。 + +默认情况下，rancher-cis-benchmark 是集群管理员独有的功能。 + +但是，`rancher-cis-benchmark` Chart 安装了这两个默认的 `ClusterRole`： + +- cis-admin +- cis-view + +在 Rancher 中，默认情况下只有集群所有者和全局管理员具有 `cis-admin` 访问权限。 + +注意：如果你使用在 Rancher 2.5 中添加的 `cis-edit` 角色，该角色从 2.5.2 开始已被删除，删除的原因是该角色本质上与 `cis-admin` 相同。如果你为 `cis-edit` 创建了任何 clusterrolebinding，请更新这些绑定以使用 `cis-admin` ClusterRole。 + +## Cluster-Admin 访问 + +默认情况下，Rancher CIS 扫描是集群管理员独有的功能。 +换言之，只有 Rancher 全局管理员和集群的集群所有者可以： + +- 安装/卸载 rancher-cis-benchmark 应用。 +- 查看 CIS Benchmark CRD 的导航链接 - ClusterScanBenchmarks、ClusterScanProfiles、ClusterScans。 +- 列出默认的 ClusterScanBenchmarks 和 ClusterScanProfiles。 +- 创建/编辑/删除新的 ClusterScanProfiles。 +- 创建/编辑/删除新的 ClusterScan，从而在集群上运行 CIS 扫描。 +- 在 ClusterScan 完成后查看并下载 ClusterScanReport。 + + +## Kubernetes 默认角色的默认权限摘要 + +rancher-cis-benchmark 创建了三个 `ClusterRole`，并将 CIS Benchmark CRD 访问权限添加到以下默认 K8s `ClusterRole`： + +| Chart 创建的 ClusterRole | 默认 K8s ClusterRole | 角色赋予的权限 | +| ------------------------------| ---------------------------| ---------------------------| +| `cis-admin` | `admin` | 增刪查改（CRUD）clusterscanbenchmarks、clusterscanprofiles、clusterscans、clusterscanreports CR | +| `cis-view` | `view ` | 列出 (R) clusterscanbenchmarks、clusterscanprofiles、clusterscans、clusterscanreports CR | + + +默认情况下，只有 cluster-owner 角色能管理和使用 `rancher-cis-benchmark` 功能。 + +默认情况下，其他 Rancher 角色（cluster-member、project-owner 和 project-member）没有管理和使用 rancher-cis-benchmark 资源的权限。 + +但是，如果 cluster-owner 想将访问权限分配给其他用户，他们可以手动创建目标用户与上述 CIS ClusterRole 之间的 ClusterRoleBinding，从而实现权限分配。 +`rancher-cis-benchmark` ClusterRole 不支持自动角色聚合。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/cis-scans/skipped-and-not-applicable-tests.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/cis-scans/skipped-and-not-applicable-tests.md new file mode 100644 index 00000000000..a7afe788a87 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/cis-scans/skipped-and-not-applicable-tests.md @@ -0,0 +1,53 @@ +--- +title: 跳过和不适用的测试 +--- + +本文列出了在 RKE 的 permissive 测试配置文件中跳过的测试。 + +> 在 v2.5 生成的报告中，此页面上被跳过且不适用的测试将会计为不适用。跳过的测试计数只会涉及用户定义的跳过测试。这样，你可以区分用户要跳过的测试与 RKE permissive 测试配置文件中默认跳过的测试。 + +## CIS Benchmark v1.5 + +### CIS Benchmark v1.5 跳过的测试 + +| 数字 | 描述 | 跳过的原因 | +| ---------- | ------------- | --------- | +| 1.1.12 | 确保 etcd 数据目录所有权设置为 etcd:etcd（自动） | etcd 数据目录所有权需要系统 ServiceAccount。有关如何配置所有权的更多信息，请参阅 Rancher 的强化指南。 | +| 1.2.6 | 确保根据需要设置 --kubelet-certificate-authority 参数（自动） | 在生成服务证书时，功能可能会与某些云提供商所需的主机名覆盖一起中断。 | +| 1.2.16 | 确保设置了准入控制插件 PodSecurityPolicy（自动） | 启用 Pod 安全策略可能会导致应用意外失败。 | +| 1.2.33 | 确保能根据需要设置 --encryption-provider-config 参数（手动） | 启用加密会改变恢复加密数据的方式。 | +| 1.2.34 | 确保正确配置了加密提供程序（手动） | 启用加密会改变恢复加密数据的方式。 | +| 4.2.6 | 确保 --protect-kernel-defaults 参数设置为 true（自动） | 在配置集群之前需要系统级别的配置，才能将此参数设置为 true。 | +| 4.2.10 | 确保根据需要设置 --tls-cert-file 和 --tls-private-key-file 参数（自动） | 在生成服务证书时，功能可能会与某些云提供商所需的主机名覆盖一起中断。 | +| 5.1.5 | 确保未主动使用默认 ServiceAccount。（自动） | Kubernetes 提供了要使用的默认 ServiceAccount。 | +| 5.2.2 | 最小化需要共享主机进程 ID 命名空间的容器准入（自动） | 启用 Pod 安全策略可能会导致应用意外失败。 | +| 5.2.3 | 最小化需要共享主机 IPC 命名空间的容器准入（自动） | 启用 Pod 安全策略可能会导致应用意外失败。 | +| 5.2.4 | 最小化需要共享主机网络命名空间的容器准入（自动） | 启用 Pod 安全策略可能会导致应用意外失败。 | +| 5.2.5 | 使用 allowPrivilegeEscalation（自动）最小化容器的准入 | 启用 Pod 安全策略可能会导致应用意外失败。 | +| 5.3.2 | 确保所有命名空间都定义了网络策略（自动） | 启用网络策略可以防止某些应用进行相互通信。 | +| 5.6.4 | 确保不使用 Default 命名空间（自动） | Kubernetes 提供了一个 Default 命名空间。 | + +### CIS Benchmark v1.5 不适用的测试 + +| 数字 | 描述 | 不适用的原因 | +| ---------- | ------------- | --------- | +| 1.1.1 | 确保 API Server pod 规范文件权限具有 644 或更严格的设置（自动） | RKE 配置的集群不需要或维护 kube-apiserver 的配置文件。所有配置在容器运行时作为参数传入。 | +| 1.1.2 | 确保 API Server pod 规范文件所有权设置为 root:root（自动） | RKE 配置的集群不需要或维护 kube-apiserver 的配置文件。所有配置在容器运行时作为参数传入。 | +| 1.1.3 | 确保 Controller Manager pod 规范文件权限具有 644 或更严格的设置（自动） | RKE 配置的集群不需要或维护 controller-manager 的配置文件。所有配置在容器运行时作为参数传入。 | +| 1.1.4 | 确保 Controller Manager pod 规范文件所有权设置为 root:root（自动） | RKE 配置的集群不需要或维护 controller-manager 的配置文件。所有配置在容器运行时作为参数传入。 | +| 1.1.5 | 确保 Scheduler pod 规范文件权限具有 644 或更严格的设置（自动） | RKE 配置的集群不需要或维护 Scheduler 的配置文件。所有配置在容器运行时作为参数传入。 | +| 1.1.6 | 确保 Scheduler pod 规范文件所有权设置为 root:root（自动） | RKE 配置的集群不需要或维护 Scheduler 的配置文件。所有配置在容器运行时作为参数传入。 | +| 1.1.7 | 确保 etcd pod 规范文件权限具有 644 或更严格的设置（自动） | RKE 配置的集群不需要或维护 etcd 的配置文件。所有配置在容器运行时作为参数传入。 | +| 1.1.8 | 确保 etcd pod 规范文件所有权设置为 root:root（自动） | RKE 配置的集群不需要或维护 etcd 的配置文件。所有配置在容器运行时作为参数传入。 | +| 1.1.13 | 确保 admin.conf 文件权限具有 644 或更严格的设置（自动） | RKE 配置的集群不会在节点上存储 kubernetes 的默认 kubeconfig 凭证文件。 | +| 1.1.14 | 确保 admin.conf 文件所有权设置为 root:root（自动） | RKE 配置的集群不会在节点上存储 kubernetes 的默认 kubeconfig 凭证文件。 | +| 1.1.15 | 确保 scheduler.conf 文件权限具有 644 或更严格的设置（自动） | RKE 配置的集群不需要或维护 Scheduler 的配置文件。所有配置在容器运行时作为参数传入。 | +| 1.1.16 | 确保 scheduler.conf 文件所有权设置为 root:root（自动） | RKE 配置的集群不需要或维护 Scheduler 的配置文件。所有配置在容器运行时作为参数传入。 | +| 1.1.17 | 确保 controller-manager.conf 文件权限具有 644 或更严格的设置（自动） | RKE 配置的集群不需要或维护 controller-manager 的配置文件。所有配置在容器运行时作为参数传入。 | +| 1.1.18 | 确保将 controller-manager.conf 文件所有权设置为 root:root（自动） | RKE 配置的集群不需要或维护 controller-manager 的配置文件。所有配置在容器运行时作为参数传入。 | +| 1.3.6 | 确保 RotateKubeletServerCertificate 参数设置为 true（自动） | RKE 配置的集群直接使用 RKE 处理证书轮换。 | +| 4.1.1 | 确保 kubelet 服务文件权限具有 644 或更严格的设置（自动） | RKE 配置的集群不需要或维护 kubelet 服务的配置文件。所有配置在容器运行时作为参数传入。 | +| 4.1.2 | 确保 kubelet 服务文件所有权设置为 root:root（自动） | RKE 配置的集群不需要或维护 kubelet 服务的配置文件。所有配置在容器运行时作为参数传入。 | +| 4.1.9 | 确保 kubelet 配置文件权限具有 644 或更严格的设置（自动） | RKE 配置的集群不需要或维护 kubelet 的配置文件。所有配置在容器运行时作为参数传入。 | +| 4.1.10 | 确保 kubelet 配置文件所有权设置为 root:root（自动） | RKE 配置的集群不需要或维护 kubelet 的配置文件。所有配置在容器运行时作为参数传入。 | +| 4.2.12 | 确保 RotateKubeletServerCertificate 参数设置为 true（自动） | RKE 配置的集群直接使用 RKE 处理证书轮换。 | \ No newline at end of file diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/cloud-marketplace/aws-cloud-marketplace/adapter-requirements.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/cloud-marketplace/aws-cloud-marketplace/adapter-requirements.md new file mode 100644 index 00000000000..5a6fed5b32a --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/cloud-marketplace/aws-cloud-marketplace/adapter-requirements.md @@ -0,0 +1,96 @@ +--- +title: 先决条件 +--- + +## 1. 设置许可证管理器和购买支持 + +首先，完成许可证管理器设置的[第一步](https://docs.aws.amazon.com/license-manager/latest/userguide/getting-started.html)。 +然后，转到 AWS Marketplace。找到 “Rancher Premium Support Billing Container Starter Pack”。最后，购买至少一项 Entitlement。 + +如果你已使用 “Rancher Setup” AWS Marketplace 产品安装了 Rancher，请跳至[步骤 4](#4-创建-oidc-提供程序)。 + +> **注意**：每项 Entitlement 都对一定数量的节点授予访问支持的权限。你可以后续根据需要购买更多许可证。 + +## 2. 创建 EKS 集群 +按照 [Rancher 文档](../../../getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/rancher-on-amazon-eks.md)创建 EKS 集群。进行到[安装 Rancher Helm Chart](../../../getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/rancher-on-amazon-eks.md#8-安装-rancher-helm-chart)（最后一步）时，**停止并返回此页面**。该集群需要满足以下要求： + +- EKS 1.22 版本。 +- 集群中的每个节点都可以访问包含 Rancher 及其相关镜像的镜像仓库。 +- 集群中的每个节点都可以访问存储 CSP Adapter 的 ECR 仓库。 +- 集群中的每个节点都可以访问许可证管理器服务。 +- 集群中的每个节点都可以访问 STS 服务的全局端点。 + +## 3. 安装 Rancher + +除了在 [Rancher 文档](../../../getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/rancher-on-amazon-eks.md#8-安装-rancher-helm-chart)中指定的 Rancher 安装选项外，你还需要启用其它指标。 +你可以通过 Helm CLI 使用以下选项来完成： + +```bash +--set extraEnv\[0\].name="CATTLE_PROMETHEUS_METRICS" --set-string extraEnv\[0\].value=true +``` + +你还可以使用 values.yaml，如下所示： + +```yaml +extraEnv: + - name: "CATTLE_PROMETHEUS_METRICS" + value: "true" +``` + +你还需要安装 Rancher 2.6.7 或更高版本。 + +## 4. 创建 OIDC 提供程序 + +按照 [AWS 文档](https://docs.aws.amazon.com/eks/latest/userguide/enable-iam-roles-for-service-accounts.html)为上一节中指定的集群创建 OIDC 提供程序。 + +## 5. 创建 IAM 角色 + +CSP Adapter 需要 IAM 角色才能签入/签出 Entitlement。 + +首先，配置如下的信任策略。你需要将 `MY_AWS_ACC` 替换为你的 AWS 帐号，将 `MY_AWS_REGION` 替换为你的 AWS 区域，并将 `MY_OIDC_PROVIDER` 替换为你的 OIDC 提供商 ID： + +```json +{ + "Version": "2012-10-17", + "Statement": [ + { + "Effect": "Allow", + "Principal": { + "Federated": "arn:aws:iam::${MY_AWS_ACC}:oidc-provider/oidc.eks.${MY_AWS_REGION}.amazonaws.com/id/${MY_OIDC_PROVIDER}" + }, + "Action": "sts:AssumeRoleWithWebIdentity", + "Condition": { + "StringEquals": { + "oidc.eks.${MY_AWS_REGION}.amazonaws.com/id/${MY_OIDC_PROVIDER}:sub": "system:serviceaccount:cattle-csp-adapter-system:rancher-csp-adapter", + "oidc.eks.${MY_AWS_REGION}.amazonaws.com/id/${MY_OIDC_PROVIDER}:aud": "sts.amazonaws.com" + } + } + } + ] +} +``` + +接下来，为具有以下权限的角色使用策略： + +```json +{ + "Version": "2012-10-17", + "Statement": [ + { + "Sid": "RancherCSPAdapterPermissions", + "Effect": "Allow", + "Action": [ + "license-manager:ListReceivedLicenses", + "license-manager:CheckoutLicense", + "license-manager:ExtendLicenseConsumption", + "license-manager:CheckInLicense", + "license-manager:GetLicense", + "license-manager:GetLicenseUsage" + ], + "Resource": "*" + } + ] +} +``` + +保存角色的名称。稍后安装 CSP Adapter 时将需要它。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/cloud-marketplace/aws-cloud-marketplace/aws-cloud-marketplace.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/cloud-marketplace/aws-cloud-marketplace/aws-cloud-marketplace.md new file mode 100644 index 00000000000..403531fd27c --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/cloud-marketplace/aws-cloud-marketplace/aws-cloud-marketplace.md @@ -0,0 +1,40 @@ +--- +title: AWS Marketplace 集成 +--- + + + + + +## 概述 + +Rancher 提供与 AWS Marketplace 的集成，允许用户购买 SUSE 的支持合同。当你开始支持更多集群时，这种集成使你可以轻松调整支持需求。 + +## Required Skills + +At a minimum, users are expected to have a working knowledge of EKS and peripheral functions such as IAM Policies and Roles, Route 53 DNS, and the use of awscli and Helm commands. + +## 限制 + +- 你必须运行 Rancher v2.6.7 或更高版本。 +- Rancher 的部署必须启用额外的指标。 +- Rancher 必须安装在 EKS 集群上。 +- 你必须通过 AWS Marketplace 购买至少一项 Rancher 支持的权限。 +- 你可能需要额外的设置来支持代理/离线用例。有关更多信息，请参阅[先决条件](adapter-requirements.md)。 + +## 如何使用 + +1. 完成[先决条件](adapter-requirements.md)。 +2. [安装 CSP Adapter](install-adapter.md)。 + +## 常见问题 + +**我以后可以购买对更多节点的支持吗？** + +可以。只需转到你最初用于购买支持的 AWS Marketplace 条目并增加权限数量即可。 + +**我可以在同一个 AWS 账户中使用多个 Rancher 实例吗？** + +可以。但是，Rancher 安装的每个集群都需要遵守先决条件。 + +此外，一个给定的权限一次只能由一个 Rancher 管理服务器使用。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/cloud-marketplace/aws-cloud-marketplace/common-issues.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/cloud-marketplace/aws-cloud-marketplace/common-issues.md new file mode 100644 index 00000000000..0e9f63f4086 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/cloud-marketplace/aws-cloud-marketplace/common-issues.md @@ -0,0 +1,28 @@ +--- +title: 常见问题 +--- + +**安装 Adapter 后，Rancher 中出现一条横幅消息，上面写着 "AWS Marketplace Adapter: Unable to run the adapter, please check the adapter logs"** + +此错误表示 Adapter 安装到集群中时发生了一个错误，导致它无法正确签入/签出许可证。 + +这通常是因为 IAM 角色设置不正确。请查看[先决条件](./adapter-requirements.md)并确认： + +- 已创建一个 OIDC 提供程序，并且它已关联到运行 Rancher 的集群。 +- IAM 角色已配置为信任此 OIDC 提供程序。 +- IAM 角色至少具有策略中概述的权限。 + +如果上述所有配置均已正确配置，请联系支持寻求帮助。 + +**我看到一条横幅消息，上面写着 "AWS Marketplace Adapter: You have exceeded your licensed node count. At least x more license(s) are required in AWS to become compliant"** + +此消息表明你没有足够的 Entitlement 来满足 Rancher 当前管理的节点数量。 + +请记住以下限制： + +- 每个 Entitlement 仅对一定数量的节点有效。 +- 当前由 Rancher 管理的每个节点都计入你的总使用量（安装了集群 Rancher 的节点除外）。 +- 每个 Entitlement 最多可以被一个 Rancher 实例使用。例如，如果你的账户中有两个正在运行的 Rancher 实例（每个都安装在单独的 EKS 集群上），那么你至少需要两个 Entitlement。 + +你最近可能还卸载/重新安装了 Adapter。如果 Adapter 丢失了它当前管理的许可证的跟踪，则可能需要一个小时来解析许可证的实际状态。 + diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/cloud-marketplace/aws-cloud-marketplace/install-adapter.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/cloud-marketplace/aws-cloud-marketplace/install-adapter.md new file mode 100644 index 00000000000..cac167bf73b --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/cloud-marketplace/aws-cloud-marketplace/install-adapter.md @@ -0,0 +1,152 @@ +--- +title: 安装 Adapter +--- + +> **重要提示**：如果你尝试重新安装 Adapter，你可能会在长达一小时的时间内收到不合规的错误消息。 + +## Rancher 与 Adapter 的兼容性矩阵 + +:::note 重要提示： + +不同版本的 CSP Adapter 依赖于特定 Rancher 版本的功能。 +为了成功部署和运行 Adapter，你需要确保 Adapter 版本与必要的 Rancher 版本对应。 + +::: + +| Rancher 版本 | Adapter 版本 | +|-----------------|------------------| +| v2.13.3 | 108.0.0+up8.0.0 | +| v2.13.2 | 108.0.0+up8.0.0 | +| v2.13.1 | 108.0.0+up8.0.0 | +| v2.13.0 | 108.0.0+up8.0.0 | + +## 1. 获取对 Local 集群的访问权限 + +> **注意**：只有管理员用户才能访问 Local 集群。因为 CSP Adapter 必须安装在 Local 集群中，所以此安装必须由管理员用户执行。 + +首先，单击 Local 集群并下载 kubeconfig 令牌。然后，使用下方的命令配置 CLI 以使用此新令牌，你需要将 `$TOKEN_PATH` 替换为文件系统上令牌的下载路径： + +```bash +export KUBECONFIG=$TOKEN_PATH +``` + +## 2. 创建 Adapter 命名空间 + +创建要安装 Adapter 的命名空间： + +```bash +kubectl create ns cattle-csp-adapter-system +``` + +## 3. 创建证书密文 + +Adapter 需要访问 Rancher 用来与 Rancher Server 通信的根 CA。有关 Rancher 支持的证书选项的更多信息，请参阅 [Chart 选项页面](../../../getting-started/installation-and-upgrade/installation-references/helm-chart-options.md)。 + +如果你的 Rancher 使用由公认的证书颁发机构（例如 Let's Encrypt）签发的证书，你可以跳到[步骤 4](#4-安装-chart)。 + +但是，如果你的 Rancher 使用了自定义证书（例如 Rancher 生成的证书或由私有证书颁发机构签发的证书），你需要为该 CA 提供 PEM 编码格式的证书以便 Adapter 可以与 Rancher 通信。 + +首先，检索 Rancher 正在使用的证书并将其放入名为 `ca-additional.pem` 的文件中。如果你使用 Rancher 生成的证书，你可以使用以下命令完成此操作： + +```bash +kubectl get secret tls-rancher -n cattle-system -o jsonpath="{.data.tls\.crt}" | base64 -d >> ca-additional.pem +``` + +然后，创建一个使用此证书的密文： + +```bash +kubectl -n cattle-csp-adapter-system create secret generic tls-ca-additional --from-file=ca-additional.pem +``` + +> **重要提示**：不要更改文件名或创建的密文的名称，否则可能会导致 Adapter 运行出错。 + +## 4. 安装 Chart + +首先，使用以下命令添加 `rancher/charts` 仓库： + +```bash +helm repo add rancher-charts https://charts.rancher.io +``` + +接下来，安装 CSP Adapter。你必须指定多个值，其中包括账号号码以及在先决条件中创建的角色的名称。 + +确保你的 CSP Adapter 版本与你正在运行的 Rancher 版本匹配，如[上文](#rancher-与-adapter-的兼容性矩阵)所述。 + +在下方的操作中，将 `$MY_ACC_NUM` 替换为你的 AWS 账号，将 `$MY_ROLE_NAME` 替换为先决条件中创建的角色的名称。此外，将 `$CSP_ADAPTER_VERSION` 替换为与[版本矩阵](#rancher-与-adapter-的兼容性矩阵)中的 Rancher 版本匹配的版本。 + +> **注意**：如果你使用 shell 变量，请不要使用引号。例如，MY_ACC_NUM=123456789012 可用，但 MY_ACC_NUM="123456789012" 将失败。 + +> **注意**：使用欧盟和英国的 AWS Marketplace 列表的账号需要额外指定 `--set image.repository=rancher/rancher-csp-adapter-eu` 选项。要查看你的账号在安装 Adapter 时是否需要此选项，请参阅 Marketplace 列表的使用说明。 + + + + +```bash +helm install rancher-csp-adapter rancher-charts/rancher-csp-adapter --namespace cattle-csp-adapter-system --set aws.enabled=true --set aws.roleName=$MY_ROLE_NAME --set-string aws.accountNumber=$MY_ACC_NUM --version $CSP_ADAPTER_VERSION +``` + + +你也可以使用 `values.yaml` 并指定以下选项： + +```yaml +aws: + enabled: true + accountNumber: "$MY_ACC_NUM" + roleName: $MY_ROLE_NAME +``` + +> **注意**：账号需要像上面那样以字符串格式指定，否则安装会失败。 + +然后，使用以下命令安装 Adapter： + +```bash +helm install rancher-csp-adapter rancher-charts/rancher-csp-adapter -f values.yaml --version $CSP_ADAPTER_VERSION +``` + + + + +```bash +helm install rancher-csp-adapter rancher-charts/rancher-csp-adapter --namespace cattle-csp-adapter-system --set aws.enabled=true --set aws.roleName=$MY_ROLE_NAME --set-string aws.accountNumber=$MY_ACC_NUM --set additionalTrustedCAs=true --version $CSP_ADAPTER_VERSION +``` + +你也可以使用 `values.yaml` 并指定以下选项： + +```yaml +aws: + enabled: true + accountNumber: "$MY_ACC_NUM" + roleName: $MY_ROLE_NAME +additionalTrustedCAs: true +``` + +> **注意**：账号需要像上面那样以字符串格式指定，否则安装会失败。 + +然后，使用以下命令安装 Adapter： + +```bash +helm install rancher-csp-adapter rancher-charts/rancher-csp-adapter -f values.yaml --version $CSP_ADAPTER_VERSION +``` + + + + +## 5. 管理证书更新 + +如果你在[步骤 3](#3-创建证书密文) 中创建了一个用于存储自定义证书的密文，则随着证书的轮换，你将需要更新此密文。 + +首先，使用以下命令删除 cattle-csp-adapter-system 命名空间中的原始密文： + +```bash +kubectl delete secret tls-ca-additional -n cattle-csp-adapter-system +``` + +然后，按照[步骤 3](#3-创建证书密文) 中的安装步骤，将密文的内容替换为更新后的值。 + +最后，重新启动 rancher-csp-adapter deployment 来确保更新后的值可供 Adapter 使用： + +```bash +kubectl rollout restart deploy rancher-csp-adapter -n cattle-csp-adapter-system +``` + +> **注意**：有一些方法（例如 cert-manager 的 [trust operator](https://cert-manager.io/docs/projects/trust/)）可以帮助你减少手动轮换任务的数量。这些选项不受官方支持，但可能对想要自动化某些任务的用户有用。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/cloud-marketplace/aws-cloud-marketplace/uninstall-adapter.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/cloud-marketplace/aws-cloud-marketplace/uninstall-adapter.md new file mode 100644 index 00000000000..ddc19f8353e --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/cloud-marketplace/aws-cloud-marketplace/uninstall-adapter.md @@ -0,0 +1,21 @@ +--- +title: 卸载 Adapter +--- + +## 1. 使用 Helm 卸载 Adapter Chart： + +```bash +helm uninstall rancher-csp-adapter -n cattle-csp-adapter-system +``` + +## 2. 删除为 Adapter 创建的命名空间： + +```bash +kubectl delete ns cattle-csp-adapter-system +``` + +## 3. （可选）删除未完成的用户通知： + +```bash +kubectl delete RancherUserNotification csp-compliance +``` diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/cloud-marketplace/cloud-marketplace.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/cloud-marketplace/cloud-marketplace.md new file mode 100644 index 00000000000..44c95be8fe9 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/cloud-marketplace/cloud-marketplace.md @@ -0,0 +1,11 @@ +--- +title: 云市场集成 +--- + + + + + +Rancher 提供与云市场的集成，以便轻松购买对托管在某些云提供商上的安装支持。此外，此集成还提供了生成 Supportconfig Bundle 的功能，该 Bundle 可以给 rancher 提供支持。 + +此集成仅支持 AWS。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/cloud-marketplace/supportconfig.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/cloud-marketplace/supportconfig.md new file mode 100644 index 00000000000..d34958468e7 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/cloud-marketplace/supportconfig.md @@ -0,0 +1,53 @@ +--- +title: Supportconfig Bundle +--- + +安装 CSP Adapter 后，你将能够生成一个 Supportconfig Bundle。此 Bundle 是一个 tar 包，可用于快速提供支持信息。 + +你可以通过 Rancher 或通过直接访问安装 Rancher 的集群来创建这些 Bundle。请注意，建议通过 Rancher 访问。 + +> **注意**：无论采用何种方法，只有管理员可以生成/下载 Supportconfig Bundle。 + +## 通过 Rancher 访问 + +首先，点击汉堡菜单。然后单击 `Get Support` 按钮。 + +![Get Support](/img/support-help.png) + +在下一页中，单击 `Generate Support Config` 按钮。 + +> **注意**：如果未安装 Adapter ，则不会出现生成 Supportconfig Bundle 的选项。你必须安装 CSP Adapter 才能生成 Supportconfig Bundle。 + +![Get Support](/img/generate-support-config.png) + +## 不通过 Rancher 进行访问 + +首先，为安装 Rancher 的集群生成 kubeconfig。 + +> **注意**：如果 Rancher 宕机，你将无法使用 Rancher 生成的 kubeconfig 令牌访问集群。 + +配置你的 shell 环境以使用此 kubeconfig 令牌： + +```bash +export KUBECONFIG=$MY_KUBECONFIG_PATH +``` + +建议在运行此命令时创建一个临时工作目录，如下所示： + +```bash +mkdir temp && cd temp +``` + +然后，检索 Supportconfig Bundle： + +```bash +mkdir rancher && kubectl get configmap csp-config -n cattle-csp-adapter-system -o=jsonpath='{.data.data}' >> rancher/config.json && tar -c -f supportconfig_rancher.tar rancher && rm -rf rancher +``` + +这将在你的当前目录中创建一个 `supportconfig_rancher.tar` 文件。 + +由于 gnu-tar 和 bsd-tar 不兼容，在 Mac 上运行这些命令的用户可能会遇到问题。如果支持部门在读取你制作的 Supportconfig 时出现问题，你可以先尝试在你的路径上将 gnu-tar 作为 `gtar` 进行访问，然后运行以下命令： + +```bash +mkdir rancher && kubectl get configmap csp-config -n cattle-csp-adapter-system -o=jsonpath='{.data.data}' >> rancher/config.json && gtar -c -f supportconfig_rancher.tar rancher && rm -rf rancher +``` diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/cluster-api/cluster-api.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/cluster-api/cluster-api.md new file mode 100644 index 00000000000..fde8aab5d9c --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/cluster-api/cluster-api.md @@ -0,0 +1,14 @@ +--- +title: Cluster API (CAPI) 与 Rancher Turtles +--- + + + + + +[Rancher Turtles](https://turtles.docs.rancher.com/) 是一个 [Rancher 扩展](../rancher-extensions.md)，通过提供 Cluster API (CAPI) 和 Rancher 之间的集成来管理配置的 Kubernetes 集群的生命周期。使用 Rancher Turtles，你可以： + +- 通过在 CAPI 配置的集群中安装 Rancher Cluster Agent，将 CAPI 集群导入 Rancher。 +- 配置 [CAPI Operator](https://turtles.docs.rancher.com/turtles/next/en/reference-guides/rancher-turtles-chart/values.html#cluster-api-operator-values)。 + +[概述](./overview.md)部分介绍了安装选项、Rancher Turtles 架构和简要 Demo。有关详细信息，请参阅 [Rancher Turtles 文档](https://turtles.docs.rancher.com/)。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/cluster-api/overview.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/cluster-api/overview.md new file mode 100644 index 00000000000..003989d5f1a --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/cluster-api/overview.md @@ -0,0 +1,260 @@ +--- +title: 概述 +--- + + + + + +## 架构图 + +下面是 Rancher Turtles 的关键组件及其与 Rancher 和 Rancher Cluster Agent 的关系的架构图，了解这些组件对于深入了解 Rancher 如何利用 CAPI operator 进行集群管理至关重要。 + +![overview](/img/30000ft_view.png) + +## 安全 + +[SLSA](https://slsa.dev/spec/v1.0/about) 是一套由行业共识制定的可逐步采用的供应链安全指南。SLSA 制定的规范对软件生产者和消费者都很有用：生产者可以遵循 SLSA 的指导方针，使他们的软件供应链更加安全，消费者可以使用 SLSA 来决定是否信任软件包。 + +Rancher Turtles 满足 [SLSA Level 3](https://slsa.dev/spec/v1.0/levels#build-l3) 对适当的构建平台、一致的构建过程和来源分布的要求。更多信息请参阅 [Rancher Turtles 安全](https://turtles.docs.rancher.com/turtles/next/en/security/slsa.html)文档。 + +## 先决条件 + +在 Rancher 环境中安装 Rancher Turtles 之前，你必须禁用 Rancher 的 `embedded-cluster-api` 功能。这还包括清理 Rancher 专用的 webhook，否则这些 webhook 将与 CAPI 的 webhook 冲突。 + +为了简化 Rancher 安装 Rancher Turtles 的设置，官方的 Rancher Turtles Helm chart 包含一个删除以下内容的 `pre-install` hook： + +- 禁用 Rancher 中的 `embedded-cluster-api` 功能。 +- 删除不再需要的 `mutating-webhook-configuration` 和 `validating-webhook-configuration` webhook。 + +这些 webhook 也可以通过 Rancher UI 删除： + +1. 点击左上角 **☰ > 集群管理**。 +1. 选择你的 local 集群。 +1. 在左侧导航菜单，选择 **More Resources** > **Admission**。 +1. 在下拉菜单中，选择资源页面的 `MutatingWebhookConfiguration` 和 `ValidatingWebhookConfiguration`。 +1. 在相应的资源页面上，点击 `mutating-webhook-configuration` and `validating-webhook-configuration` 后面的 **⋮** 然后选择 **删除**。 + +还可以通过在 **Resource Search** 字段中输入 webhook 的名称来访问到具体的 webhook。 + +以下的 `kubectl` 命令可以手动删除必要的 webhook： + +```console +kubectl delete mutatingwebhookconfiguration.admissionregistration.k8s.io mutating-webhook-configuration +``` + +```console +kubectl delete validatingwebhookconfigurations.admissionregistration.k8s.io validating-webhook-configuration +``` + +使用以下示例从控制台禁用 `embedded-cluster-api` 功能： + +1. 创建一个 `feature.yaml` 文件，将 `embedded-cluster-api` 设置为 false： + +```yaml title="feature.yaml" +apiVersion: management.cattle.io/v3 +kind: Feature +metadata: + name: embedded-cluster-api +spec: + value: false +``` + +2. 使用 `kubectl` 将 `feature.yaml` 文件应用到集群： + +```bash +kubectl apply -f feature.yaml +``` + +## 安装 Rancher Turtles Operator + +你可以通过 Rancher UI 或使用 Helm 安装 Rancher Turtles operator。对于大多数环境推荐使用第一种方法。 + +:::caution + +如果你的集群中已经安装了 Cluster API (CAPI) Operator，你必须使用[手动 Helm 安装方法](#通过-helm-安装)。 + +::: + +### 通过 Rancher UI 安装 + +通过 Rancher UI 添加 Turtles 仓库，Rancher 可以处理 CAPI 扩展的安装和配置。 + +1. 点击 **☰**。在左侧导航栏**浏览集群**的菜单下，选择 **local**。 +1. 在 **Cluster Dashboard** 的左侧导航菜单中，点击 **Apps > Repositories**。 +1. 点击 **Create** 创建一个新的仓库。 +1. 输入以下信息： + - **Name**: turtles + - **Index URL**: https://rancher.github.io/turtles +1. 等待新的仓库状态更新为 `Active`。 +1. 在左侧导航菜单中，点击 **Apps > Charts**。 +1. 在搜索过滤器中输入 "turtles" 来查找 Turtles chart。 +1. 点击 **Rancher Turtles - the Cluster API Extension**。 +1. 点击 **Install > Next > Install**. + +此过程使用 Helm chart 的默认值，这些值适用于大部分的安装场景。如果你的配置需要覆盖其中一些默认值，你可以在安装期间通过 Rancher UI 指定这些值，也可以通过 [Helm 手动安装 Chart](#通过-helm-安装)。有关可用的 values 设置的详细信息，请参阅 Rancher Turtles 的 [Helm chart 参考指南](https://turtles.docs.rancher.com/turtles/next/en/reference-guides/rancher-turtles-chart/values.html)。 + +安装可能需要几分钟时间，安装完成后，你可以在集群中看到以下新部署： + +- `rancher-turtles-system/rancher-turtles-controller-manager` +- `rancher-turtles-system/rancher-turtles-cluster-api-operator` +- `capi-system/capi-controller-manager` + +#### Demo + +这个 demo 演示了如何使用 Rancher UI 安装 Rancher Turtles、创建/导入一个 CAPI 集群，以及在集群上安装监控： + + + +### 通过 Helm 安装 + +通过 Helm 安装 Rancher Turtles 有两种方法，这取决于你是否将 CAPI operator 作为依赖项包含其中： + +- [使用 CAPI Operator 作为依赖项安装 Rancher Turtles](#使用-cluster-api-capi-operator-作为-helm-依赖项安装-rancher-turtles)。 +- [安装没有 CAPI Operator 的 Rancher Turtles](#不使用-cluster-api-capi-operator-作为-helm-依赖安装-rancher-turtles)。 + +安装 Rancher Turtles 需要 CAPI Operator。你可以选择自己处理此依赖项，还是让 Rancher Turtles Helm chart 替你管理它。[使用 CAPI Operator 作为依赖项安装 Rancher Turtles](#使用-cluster-api-capi-operator-作为-helm-依赖项安装-rancher-turtles) 更简单，但是你的最佳选择取决于你的具体配置。 + +CAPI Operator 允许使用声明式方法处理 CAPI provider 的生命周期，扩展了 `clusterctl` 的能力。如果你想了解更多相关内容，可以参考 [Cluster API Operator book](https://cluster-api-operator.sigs.k8s.io/)。 + +#### 使用 `Cluster API (CAPI) Operator` 作为 Helm 依赖项安装 Rancher Turtles + +1. 添加包含 `rancher-turtles` chart 的 Helm 仓库作为安装的第一步： + +```bash +helm repo add turtles https://rancher.github.io/turtles +helm repo update +``` + +2. 如前面所述，安装 Rancher Turtles 需要 [CAPI Operator](https://github.com/kubernetes-sigs/cluster-api-operator)。Helm chart 可以使用一组最少的参数自动安装： + +```bash +helm install rancher-turtles turtles/rancher-turtles --version \ + -n rancher-turtles-system \ + --dependency-update \ + --create-namespace --wait \ + --timeout 180s +``` + +3. 此操作可能需要几分钟时间，完成后，你可以查看下面列出的已安装的控制器： + +- `rancher-turtles-controller` +- `capi-operator` + +:::note + +- 如果集群中已经有可用的 `cert-manager`，请在安装时通过以下参数将 Rancher Turtles 的此项依赖禁用掉，来阻止冲突： + `--set cluster-api-operator.cert-manager.enabled=false` +- 有关 Rancher Turtles 的版本列表，请参阅 [Turtles 发布页面](https://github.com/rancher/turtles/releases)。 + +::: + +这是最基本的推荐配置，用于管理在核心提供商的命名空间中创建包含所需 CAPI 功能标志（已启用 `CLUSTER_TOPOLOGY`, `EXP_CLUSTER_RESOURCE_SET` 和 `EXP_MACHINE_POOL` ）的 secret。要启用其他 CAPI 功能需要启用上述功能标志。 + +如果你需要覆盖默认的行为并使用现有 secret 或添加自定义环境变量，你可以将 secret 名称通过 Helm 参数传入。在这种情况下，你作为负责管理 secret 创建和内容的用户，需要启用的最少特性包括：`CLUSTER_TOPOLOGY`, `EXP_CLUSTER_RESOURCE_SET` 和 `EXP_MACHINE_POOL`。 + +```bash +helm install ... + # Passing secret name and namespace for additional environment variables + --set cluster-api-operator.cluster-api.configSecret.name= +``` + +以下是一个用户管理 secret `cluster-api-operator.cluster-api.configSecret.name=variables` 的示例，其中设置了 `CLUSTER_TOPOLOGY`, `EXP_CLUSTER_RESOURCE_SET` 和 `EXP_MACHINE_POOL` 功能以及一个额外的自定义变量： + +```yaml title="secret.yaml" +apiVersion: v1 +kind: Secret +metadata: + name: variables + namespace: rancher-turtles-system +type: Opaque +stringData: + CLUSTER_TOPOLOGY: "true" + EXP_CLUSTER_RESOURCE_SET: "true" + EXP_MACHINE_POOL: "true" + CUSTOM_ENV_VAR: "false" +``` + +:::info + +有关 chart 支持的 values 及其用法的详细信息，请参阅 [Helm chart 选项](https://turtles.docs.rancher.com/turtles/next/en/reference-guides/rancher-turtles-chart/values.html) + +::: + +#### 不使用 `Cluster API (CAPI) Operator` 作为 Helm 依赖安装 Rancher Turtles + +:::note + +请记住，如果使用此安装选项，你必须自行管理 CAPI Operator 的安装。你可以参照 Rancher Turtles 文档中的 [CAPI Operator 指南](https://turtles.docs.rancher.com/turtles/next/en/contributing/install_capi_operator.html) + +::: + +1. 添加包含 `rancher-turtles` chart 的 Helm 仓库作为安装的第一步： + +```bash +helm repo add turtles https://rancher.github.io/turtles +helm repo update +``` + +2. 将 chart 安装到 `rancher-turtles-system` 命名空间： + +```bash +helm install rancher-turtles turtles/rancher-turtles --version + -n rancher-turtles-system + --set cluster-api-operator.enabled=false + --set cluster-api-operator.cluster-api.enabled=false + --create-namespace --wait + --dependency-update +``` + +前面的命令告诉 Helm 忽略将 `cluster-api-operator` 作为依赖项安装。 + +3. 此操作可能需要几分钟，完成后你可以查看下面列出的已安装的控制器： + +- `rancher-turtles-controller` + +## 卸载 Rancher Turtles + +:::caution + +在 Rancher 环境中安装 Rancher Turtles 时，Rancher Turtles 默认会启用 CAPI Operator 清理。这包括清理 CAPI Operator 特定的 webhook 和 deployments，否则会导致 Rancher 配置出现问题。 + +为了简化 Rancher Turtles 卸载（通过 Rancher 或 Helm 命令），官方的 Rancher Turtles Helm chart 包含了一个删除以下内容的 `post-delete` hook： + +- 删除不再需要的 `mutating-webhook-configuration` 和 `validating-webhook-configuration` webhook。 +- 删除不再需要的 CAPI `deployments`。 + +::: + +卸载 Rancher Turtles： + +```bash +helm uninstall -n rancher-turtles-system rancher-turtles --cascade foreground --wait +``` + +这可能需要几分钟才能完成。 + +:::note + +请记住，如果你在安装时使用了不同的名称或不同的命名空间，你需要针对你的特定配置自定义卸载命令。 + +::: + +卸载 Rancher Turtles 后， Rancher 的 `embedded-cluster-api` 功能必须重新启用。 + +1. 创建一个 `feature.yaml` 文件，将 `embedded-cluster-api` 设置为 true： + +```yaml title="feature.yaml" +apiVersion: management.cattle.io/v3 +kind: Feature +metadata: + name: embedded-cluster-api +spec: + value: true +``` + +2. 使用 `kubectl` 将 `feature.yaml` 文件应用到集群： + +```bash +kubectl apply -f feature.yaml +``` diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/elemental/elemental.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/elemental/elemental.md new file mode 100644 index 00000000000..6352de02ba1 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/elemental/elemental.md @@ -0,0 +1,30 @@ +--- +title: 使用 Elemental 进行操作系统管理 +--- + + + + + +Elemental 支持云原生主机管理。Elemental 允许你在任何位置装载任何机器，无论是在数据中心还是在边缘，并将它们无缝集成到 Kubernetes 中，同时管理你的工作流程（例如操作系统更新）。 + +## Elemental 和 Rancher + +Rancher 中的 Elemental： + +- 是 Kubernetes 原生的，它允许你通过 Kubernetes 集群中的 Elemental 管理操作系统。 +- 从 Kubernetes 的操作角度来看，不会造成干扰。 +- 是声明性的，并且 GitOps 友好。 +- 允许可信的、确定性的和可预测的 OCI Image-based flows。 +- 大规模运作。它支持 Fleet 规模的操作系统管理。 + +### 我什么时候应该使用 Elemental？ + +- Elemental 通过 Rancher manager 实现云原生操作系统管理。它适用于任何操作系统（例如，SLE Micro vanilla）。 +- Elemental 允许对数据中心和边缘的机器进行云原生管理。 +- Elemental 非常灵活，允许平台团队在其机器群中执行各种工作流。 + +## Elemental 和 Rancher Prime + +- 已作为 GUI 扩展深度集成到 Rancher 中。 +- 将 Rancher 的用例扩展到操作系统，如今 SLE Micro 与 Rancher 可以完美配合。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/fleet-gitops-at-scale/architecture.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/fleet-gitops-at-scale/architecture.md new file mode 100644 index 00000000000..e039b353a31 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/fleet-gitops-at-scale/architecture.md @@ -0,0 +1,8 @@ +--- +title: 架构 +--- + +Fleet 可以管理来自 Git 的原始 Kubernetes YAML、Helm Chart、Kustomize 或三者的任何组合的部署。无论来源如何，所有资源都会动态转化为 Helm Chart，Helm 会用作引擎来将所有资源部署到集群中。这给了你高度的控制、一致性和可审计性。Fleet 不仅关注扩展能力，而且还提供高度的控制和可见性，从而让用户准确了解集群上安装的内容。 + +![架构](/img/fleet-architecture.svg) + diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/fleet-gitops-at-scale/use-fleet-behind-a-proxy.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/fleet-gitops-at-scale/use-fleet-behind-a-proxy.md new file mode 100644 index 00000000000..37ba154ae39 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/fleet-gitops-at-scale/use-fleet-behind-a-proxy.md @@ -0,0 +1,54 @@ +--- +title: 在代理后使用 Fleet +--- + +在本节中，你将学习如何在一个设置中启用 Fleet，该设置有一个具有公共 IP 的 Rancher Server，以及一个没有公共 IP 但配置为使用代理的 Kubernetes 集群。 + +Rancher 不会与已注册的下游集群建立连接。部署在下游集群上的 Rancher agent 必须能够与 Rancher 建立连接。 + +要让 Fleet 在代理后工作，你需要为下游集群设置 **Agent 环境变量**。以下是集群级别的配置选项。 + +你可以通过 Rancher UI 为任何集群类型（包括注册集群和自定义集群）配置这些环境变量。可以在编辑现有集群或配置新集群时添加变量。 + +对于公共下游集群，[在 Rancher UI 中设置必要的环境变量](#在-rancher-ui-中设置环境变量)就足够了。 + +对于私有节点或私有集群，则需要在节点上设置环境变量。然后，在配置自定义集群或注册私有集群时，在 Rancher UI 中配置环境变量。有关如何在 K3s Kubernetes 集群中的 Ubuntu 节点上设置环境变量的示例，请参阅[本节](#在私有节点上设置环境变量)。 + +## 必要的环境变量 + +为代理添加 Fleet agent 环境变量时，将 替换为你的私有代理 IP。 + +| 变量名称 | 值 | +|------------------|--------| +| `HTTP_PROXY` | http://:8888 | +| `HTTPS_PROXY` | http://:8888 | +| `NO_PROXY` | 127.0.0.0/8,10.0.0.0/8,172.16.0.0/12,192.168.0.0/16,.svc,.cluster.local | + +## 在 Rancher UI 中设置环境变量 + +要将环境变量添加到现有集群： + +1. 点击 **☰ > 集群管理**。 +1. 转到要添加环境变量的集群，然后单击 **⋮ > 编辑配置**。 +1. 单击**高级选项**。 +1. 单击**添加环境变量**。 +1. 输入[必要的环境变量](#必要的环境变量) +1. 单击**保存**。 + +**结果**：Fleet agent 会在代理后工作。 + +## 在私有节点上设置环境变量 + +对于私有节点和私有集群，代理环境变量需要在节点本身上设置，以及从 Rancher UI 配置。 + +此示例显示了如何在 K3s Kubernetes 集群中的 Ubuntu 节点上设置环境变量： + +``` +ssh -o ForwardAgent=yes ubuntu@ +ssh +export proxy_private_ip= +export HTTP_PROXY=http://${proxy_private_ip}:8888 +export HTTPS_PROXY=http://${proxy_private_ip}:8888 +export NO_PROXY=127.0.0.0/8,10.0.0.0/8,172.16.0.0/12,192.168.0.0/16,.svc,.cluster.local +export KUBECONFIG=/etc/rancher/k3s/k3s.yaml +``` diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/fleet-gitops-at-scale/windows-support.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/fleet-gitops-at-scale/windows-support.md new file mode 100644 index 00000000000..f322aac9f3a --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/fleet-gitops-at-scale/windows-support.md @@ -0,0 +1,21 @@ +--- +title: Windows 支持 +--- + +在 Rancher 2.5.6 之前，`agent` 在具有 Windows 节点的下游集群上没有原生的 Windows 清单。这将导致集群的 `agent` pod 失败。 + +如果你从旧版本的 Rancher 升级到 2.5.6+，你可以在*下游集群*中部署具有以下工作流的工作 `agent`： + +1. 封锁所有 Windows 节点。 +1. 对 `agent` 工作负载应用以下容忍度。 +1. 取消所有 Windows 节点的封锁。 +1. 删除所有 `agent` pod。使用新的容忍度来创建新 pod。 +1. `agent` pod 运行并为 Fleet 启用了自动更新后，它们会更新到与 Windows 兼容的 `agent` 版本。 + +```yaml +tolerations: +- effect: NoSchedule + key: cattle.io/os + operator: Equal + value: linux +``` diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/fleet/architecture.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/fleet/architecture.md new file mode 100644 index 00000000000..ffdbff3edc2 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/fleet/architecture.md @@ -0,0 +1,11 @@ +--- +title: 架构 +--- + + + + + +Fleet 可以管理来自 Git 的原始 Kubernetes YAML、Helm Chart、Kustomize 或三者的任何组合的部署。无论来源如何，所有资源都会动态转化为 Helm Chart，并使用 Helm 作为引擎来部署到集群中的所有内容。这为你提供了高度的控制力、一致性和可审计性。Fleet 不仅关注扩展能力，而且还提供高度的控制和可见性，从而让用户准确了解集群上安装的内容。 + +![架构](/img/fleet-architecture.svg) diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/fleet/fleet.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/fleet/fleet.md new file mode 100644 index 00000000000..8b1249e41a0 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/fleet/fleet.md @@ -0,0 +1,27 @@ +--- +title: 使用 Fleet 进行持续交付 +--- + + + + + +Fleet 通过集群 Fleet 的供应链协调和管理应用程序的持续交付。Fleet 使用 GitOps 作为一种安全的运营模式，组织供应链，帮助团队及时自信地交付。 + +## Fleet 和 Rancher + +许多用户经常同时管理 10 个以上的集群。鉴于集群的激增，持续交付是 Rancher 的重要组成部分。Fleet 使用 GitOps 确保可靠的持续交付体验，这是一种安全且越来越常见的运营模式。 + +### 我什么时候应该使用 Fleet? + +- 我需要跨地理区域部署我的监控堆栈（例如 Grafana、Prometheus），每个区域都有不同的保留策略。 +- 我是一名平台运营商，希望使用可扩展且安全的操作模型（GitOps）为集群配置所有组件。 +- 我是一名应用程序开发人员，希望我的最新更改自动进入我的开发环境。 + +## Fleet 和 Rancher Prime + +Fleet 已经作为持续交付工具和 GitOps 引擎深度集成到 Rancher 中。 + + diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/fleet/overview.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/fleet/overview.md new file mode 100644 index 00000000000..b26b821dc23 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/fleet/overview.md @@ -0,0 +1,67 @@ +--- +title: 概述 +--- + + + + + +使用 Fleet 进行持续交付是大规模的 GitOps。Fleet 旨在管理多达一百万个集群。它也足够轻量级，对于[单个集群](https://fleet.rancher.io/installation#default-install)也很有效，但当你达到[大规模](https://fleet.rancher.io/installation#configuration-for-multi-cluster)时，它真的会大放异彩。大规模是指单个组织中的大量集群、大量部署或大量团队。 + +Fleet 是 Rancher 的一个独立项目，可以通过 Helm 安装在任何 Kubernetes 集群上。 + +## 架构 + +有关 Fleet 如何运作的信息，请参阅[架构](./architecture.md)页面。 + +## 在 Rancher UI 中访问 Fleet + +Fleet 预安装在 Rancher 中，并由 Rancher UI 中的**持续交付**选项进行管理。有关持续交付和其他 Fleet 故障排除技巧的更多信息，请参阅[此处](https://fleet.rancher.io/troubleshooting)。 + +用户可以按照 **gitops** 实践，利用持续交付将应用程序部署到 git 仓库中的 Kubernetes 集群，而无需任何手动操作。 + +按照以下步骤在 Rancher UI 中访问持续交付： + +1. 单击 **☰ > 持续交付**。 + +1. 在菜单顶部选择命名空间 ，注意以下事项： + + - 默认情况下，选择 **fleet-default**，包括通过 Rancher 注册的所有下游集群。 + + - 你可以切换到 **fleet-local**，它仅包含 **local** 集群，或者你可以创建自己的工作空间，将集群分配和移动到其中。 + + - 然后，你可以通过单击左侧导航栏上的**集群**来管理集群。 + +1. 单击左侧导航栏上的 **Gitrepos**，将 gitrepo 部署到当前工作空间的集群中。 + +1. 选择 [git 仓库](https://fleet.rancher.io/gitrepo-add)和[目标集群/集群组](https://fleet.rancher.io/gitrepo-targets)。你也可以通过单击左侧导航栏中的**集群组**在 UI 中创建集群组。 + +1. 部署 gitrepo 后，你可以通过 Rancher UI 监控应用程序。 + +## Windows 支持 + +有关对具有 Windows 节点的集群的支持的详细信息，请参阅 [Windows 支持](./windows-support.md)页面。 + +## GitHub 仓库 + +Fleet Helm charts 可在[此处](https://github.com/rancher/fleet/releases)获取。 + +## 在代理后使用 Fleet + +有关在代理后面使用 Fleet 的详细信息，请参阅[在代理后使用 Fleet](./use-fleet-behind-a-proxy.md) 页面。 + +## Helm Chart 依赖 + +为了成功部署具有依赖项的 Helm Chart，你必须运行一个手动命令（如下所示），因为用户需要满足依赖列表。如果不执行此操作，继续克隆你的仓库并运行 `helm install`，则会因依赖项丢失而导致安装失败。 + +git 仓库中的 Helm Chart 必须在 Chart 子目录中包含其依赖。 你必须手动运行 `helm dependencies update $chart` 或在本地运行 `helm dependencies build $chart`，然后将完整的 Chart 目录提交到 git 仓库。请注意，你需要使用适当的参数更新你的命令。 + +## 故障排除 + +- **已知问题**：Fleet gitrepos 的 clientSecretName 和 helmSecretName 密文不包含在 [backup-restore-operator](../../how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/back-up-rancher.md#1-安装-rancher-backup-operator) 创建的备份或恢复中。一旦有永久的解决方案，我们将更新社区内容。 + +- **临时解决方法**：默认情况下，用户定义的密文不会在 Fleet 中备份。如果执行灾难恢复或将 Rancher 迁移到新集群，则有必要重新创建密文。要修改 ResourceSet 以包含要备份的额外资源，请参阅文档[此处](https://github.com/rancher/backup-restore-operator#user-flow)。 + +## 文档 + +Fleet 文档位于 https://fleet.rancher.io/ 。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/fleet/use-fleet-behind-a-proxy.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/fleet/use-fleet-behind-a-proxy.md new file mode 100644 index 00000000000..3806cbb2248 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/fleet/use-fleet-behind-a-proxy.md @@ -0,0 +1,58 @@ +--- +title: 在代理后使用 Fleet +--- + + + + + +在本节中，你将学习如何在具有公共 IP 的 Rancher 服务器，以及一个没有公共 IP 但配置为使用代理的 Kubernetes 集群的设置中启用 Fleet。 + +Rancher 不会与已注册的下游集群建立连接。部署在下游集群上的 Rancher agent 必须能够与 Rancher 建立连接。 + +要让 Fleet 在代理后工作，你需要为下游集群设置 **Agent 环境变量**。以下是集群级别的配置选项。 + +你可以通过 Rancher UI 为任何集群类型（包括注册集群和自定义集群）配置这些环境变量。可以在编辑现有集群或配置新集群时添加变量。 + +对于公共下游集群，[在 Rancher UI 中设置必要的环境变量](#在-rancher-ui-中设置环境变量)就足够了。 + +对于私有节点或私有集群，则需要在节点上设置环境变量。然后，在配置自定义集群或注册私有集群时，在 Rancher UI 中配置环境变量。有关如何在 K3s 集群中的 Ubuntu 节点上设置环境变量的示例，请参阅[本节](#在私有节点上设置环境变量)。 + +## 必要的环境变量 + +为代理添加 Fleet agent 环境变量时，将 替换为你的私有代理 IP。 + +| 变量名称 | 值 | +| ------------- | ----------------------------------------------------------------------- | +| `HTTP_PROXY` | http://:8888 | +| `HTTPS_PROXY` | http://:8888 | +| `NO_PROXY` | 127.0.0.0/8,10.0.0.0/8,172.16.0.0/12,192.168.0.0/16,.svc,.cluster.local | + +## 在 Rancher UI 中设置环境变量 + +要将环境变量添加到现有集群： + +1. 单击 **☰ > 集群管理**。 +1. 转到要添加环境变量的集群，然后单击 **⋮ > 编辑配置**。 +1. 单击**高级选项**。 +1. 单击**添加环境变量**。 +1. 输入[必要的环境变量](#必要的环境变量) +1. 单击**保存**。 + +**结果：** Fleet agent 会在代理后工作。 + +## 在私有节点上设置环境变量 + +对于私有节点和私有集群，需要在节点本身上设置代理环境变量，并在 Rancher UI 中进行配置。 + +此示例显示了如何在 K3s 集群中的 Ubuntu 节点上设置环境变量： + +``` +ssh -o ForwardAgent=yes ubuntu@ +ssh +export proxy_private_ip= +export HTTP_PROXY=http://${proxy_private_ip}:8888 +export HTTPS_PROXY=http://${proxy_private_ip}:8888 +export NO_PROXY=127.0.0.0/8,10.0.0.0/8,172.16.0.0/12,192.168.0.0/16,.svc,.cluster.local +export KUBECONFIG=/etc/rancher/k3s/k3s.yaml +``` diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/fleet/windows-support.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/fleet/windows-support.md new file mode 100644 index 00000000000..7102f0fa01d --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/fleet/windows-support.md @@ -0,0 +1,25 @@ +--- +title: Windows 支持 +--- + + + + + +在 Rancher v2.5.6 之前，`agent` 在具有 Windows 节点的下游集群上没有原生的 Windows 清单。这将导致集群的 `agent` pod 运行失败。 + +如果你从旧版本的 Rancher 升级到 v2.5.6+，你可以在 _下游集群_ 中部署具有以下工作流的可运行的 `agent`： + +1. 封锁所有 Windows 节点。 +1. 对 `agent` 工作负载应用以下容忍度。 +1. 取消所有 Windows 节点的封锁。 +1. 删除所有 `agent` pod。使用新的容忍度来创建新 pod。 +1. 一旦 `agent` pod 运行，并且 Fleet 的自动更新已启用，它们会更新到兼容 Windows 的 `agent` 版本。 + +```yaml +tolerations: + - effect: NoSchedule + key: cattle.io/os + operator: Equal + value: linux +``` diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/harvester.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/harvester.md new file mode 100644 index 00000000000..eb6bf4742bb --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/harvester.md @@ -0,0 +1,48 @@ +--- +title: Harvester 集成 +--- + +Harvester 是 Rancher 2.6.1 新增的功能，[Harvester](https://docs.harvesterhci.io/) 是基于 Kubernetes 构建的开源超融合基础架构 (HCI) 软件。Harvester 安装在裸金属服务器上，提供集成的虚拟化和分布式存储功能。虽然 Harvester 使用 Kubernetes 运行，但它不需要用户了解 Kubernetes 概念，因此是一个更加用户友好的应用。 + +## 功能开关 + +你可以使用 Harvester 的功能开关来管理 Harvester 在 Rancher 虚拟化管理页面的访问，用户可以在该页面直接导航到 Harvester 集群并访问 Harvester UI。Harvester 的功能开关是默认启用的。如需了解 Rancher 中功能开关的更多详细信息，请单击[此处](../how-to-guides/advanced-user-guides/enable-experimental-features/enable-experimental-features.md)。 + +要导航到 Harvester 集群，请单击 **☰ > 虚拟化管理**。在 **Harvester 集群**页面中，单击集群以转到该 Harvester 集群的视图。 + +* 如果启用了 Harvester 功能开关，则会从列出 Kubernetes 集群的任何页面或应用（例如 Fleet 和多集群应用）中过滤掉 Harvester 集群。 + +* 如果禁用了 Harvester 功能开关，并且导入了 Harvester 集群，Harvester 集群将显示在**集群管理**页面的 Rancher 集群列表中。仅当功能开关为关闭时，Harvester 集群才会显示在集群列表中。 + +* 集成 Harvester 后，你可以将 Harvester 集群导入 Rancher，对应的集群类型是 `Harvester`。 + +* 用户只能在**虚拟化管理**页面上导入 Harvester 集群。在**集群管理**页面上导入集群是不支持的，而且会出现警告。建议你返回**虚拟化管理**页面执行此操作。 + +## Harvester 主机驱动 + +[Harvester 主机驱动](https://docs.harvesterhci.io/v1.1/rancher/node/node-driver/) 通常可用于 Rancher 中的 RKE 和 RKE2 选项。无论 Harvester 功能开关是否启用，主机驱动都是可用的。请注意，默认情况下主机驱动是关闭的。用户只能通过**集群管理**页面在 Harvester 上创建 RKE 或 RKE2 集群。 + +Harvester 允许通过 Harvester UI 上传和显示 `.ISO` 镜像，但 Rancher UI 不支持。这是因为 `.ISO` 镜像通常需要额外的设置，这会干扰干净的部署（即无需用户干预），并且它们通常不用于云环境。 + +如需了解 Rancher 中主机驱动的更多详细信息，请单击[此处](../how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/about-provisioning-drivers/about-provisioning-drivers.md#主机驱动)。 + +## 端口要求 + +可以在[此处](https://docs.harvesterhci.io/v1.1/install/requirements#networking)找到 Harvester 集群的端口要求。 + +此外，其他网络注意事项如下： + +- 请务必为 VM VLAN 网络启用物理交换机的 VLAN 中继端口。 +- 按照[此处](https://docs.harvesterhci.io/v1.1/networking/clusternetwork)的网络设置指南进行操作。 + +对于其他集群（例如 K3s 和 RKE1）的其他端口要求，请参阅[这些文档](https://docs.harvesterhci.io/v1.1/install/requirements/#guest-clusters)。 + +## 限制 + +--- +**仅适用于 Rancher v2.6.1 和 v2.6.2**： + +- Harvester 0.3.0 不支持离线环境安装。 +- 不支持将 Harvester 0.2.0 升级到 0.3.0，也不支持升级到新的 1.0.0 版本。 + +--- diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/harvester/harvester.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/harvester/harvester.md new file mode 100644 index 00000000000..8f4b2312b56 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/harvester/harvester.md @@ -0,0 +1,15 @@ +--- +title: 使用 Harvester 在 Kubernetes 上进行虚拟化 +--- + + + + + +## Harvester + +Harvester 是 Rancher v2.6.1 新增的功能，是基于 Kubernetes 构建的开源超融合基础架构（HCI）软件。Harvester 安装在裸金属服务器上，提供集成的虚拟化和分布式存储功能。虽然 Harvester 使用 Kubernetes 运行，但它不需要用户了解 Kubernetes 概念，这使得它更加用户友好。 + +## Harvester 与 Rancher + +凭借 Rancher Prime 和 Harvester，IT 运维人员现在可以访问一个企业级的、易于使用的基础设施平台，该平台可以协同管理他们的虚拟机和 Kubernetes 集群。有关产品支持的更多信息，请参阅[支持矩阵](https://www.suse.com/suse-harvester/support-matrix/all-supported-versions/harvester-v1-2-0/)。通过 Rancher 虚拟化管理功能，用户可以导入和管理多个 Harvester 集群。利用 Rancher 的认证功能和 RBAC 控制来支持多租户。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/harvester/overview.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/harvester/overview.md new file mode 100644 index 00000000000..0453eeb700d --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/harvester/overview.md @@ -0,0 +1,42 @@ +--- +title: 概述 +--- + + + + + +[Harvester](https://docs.harvesterhci.io/) 是 Rancher v2.6.1 新增的功能，是基于 Kubernetes 构建的开源超融合基础架构（HCI）软件。Harvester 安装在裸金属服务器上，提供集成的虚拟化和分布式存储功能。虽然 Harvester 使用 Kubernetes 运行，但它不需要用户了解 Kubernetes 概念，这使得它更加用户友好。 + +## 功能开关 + +Harvester 功能开关用于管理对 Rancher 中虚拟化管理（VM）页面的访问，用户可以直接导航到 Harvester 集群并访问 Harvester UI。Harvester 的功能开关默认启用。如需了解 Rancher 中功能开关的更多详细信息，请单击[此处](../../how-to-guides/advanced-user-guides/enable-experimental-features/enable-experimental-features.md)。 + +要导航到 Harvester 集群，请单击 **☰ > 虚拟化管理**。在 Harvester 集群页面中，单击集群以转到该 Harvester 集群的视图。 + +- 如果启用了 Harvester 功能开关，Harvester 集群将会从列出 Kubernetes 集群的任何页面或应用（例如 Fleet 和多集群应用）中过滤掉。 + +- 如果禁用了 Harvester 功能开关，并且导入了 Harvester 集群，Harvester 集群将显示在集群管理页面的 Rancher 集群列表中。仅当功能开关为关闭时，Harvester 集群才会显示在集群列表中。 + +- 集成 Harvester 后，你可以将 Harvester 集群导入 Rancher，对应的集群类型是 `Harvester`。 + +- 用户只能在虚拟化管理页面上导入 Harvester 集群。不支持在集群管理页面上导入集群，并且会出现警告，建议你返回虚拟化管理页面执行此操作。 + +## Harvester 主机驱动 + +[Harvester 主机驱动](https://docs.harvesterhci.io/v1.5/rancher/node/node-driver/)通常可用于 Rancher 中的 K3s 和 RKE2 选项。无论 Harvester 功能开关是否启用，主机驱动都是可用的。请注意，主机驱动默认处于关闭状态。用户只能通过集群管理页面在 Harvester 上创建 K3s 或 RKE2 集群。 + +Harvester 允许通过 Harvester UI 上传和显示 `.ISO` 镜像，但 Rancher UI 是不支持的。这是因为 `.ISO` 镜像通常需要额外的设置，这会干扰干净的部署（即无需用户干预），并且它们通常不用于云环境。 + +如需了解 Rancher 中主机驱动的更多详细信息，请单击[此处](../../how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/about-provisioning-drivers/about-provisioning-drivers.md#主机驱动)。 + +## 端口要求 + +Harvester 集群的端口要求可以在[此处](https://docs.harvesterhci.io/v1.5/install/requirements#networking)找到。 + +此外，其他网络注意事项如下： + +- 请务必为 VM VLAN 网络启用物理交换机的 VLAN 中继端口。 +- 按照[此处](https://docs.harvesterhci.io/v1.5/networking/index)的网络设置指南进行操作。 + +对于其他集群（例如 K3s 和 RKE2）的其他端口要求，请参阅[这些文档](https://docs.harvesterhci.io/v1.5/install/requirements/#guest-clusters)。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/integrations-in-rancher.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/integrations-in-rancher.md new file mode 100644 index 00000000000..24cc0dabca0 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/integrations-in-rancher.md @@ -0,0 +1,18 @@ +--- +title: Rancher 中的集成 +--- + + + + + +Prime 是 Rancher 生态系统的企业级产品，具有更高的安全性、更长的生命周期和对 Prime 专有文档的访问权限。Rancher Prime 安装资产托管在受信任的 SUSE 注册表上，由 Rancher 拥有和管理。受信任的 Prime 注册表仅包括经过社区测试的稳定版本。 + +Prime 还提供生产支持选项，以及根据你的商业需求定制的订阅附加组件。 + +要了解更多信息并开始使用 Rancher Prime，请访问[本页](https://www.rancher.com/quick-start)。 + +import DocCardList from '@theme/DocCardList'; +import { useCurrentSidebarCategory } from '@docusaurus/theme-common/internal'; + + diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/istio/configuration-options/configuration-options.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/istio/configuration-options/configuration-options.md new file mode 100644 index 00000000000..38093e5590c --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/istio/configuration-options/configuration-options.md @@ -0,0 +1,39 @@ +--- +title: 配置选项 +--- + + + + + +## Egress 支持 + +默认情况下，Egress 网关是禁用的，但你可以在安装或升级时使用 values.yaml 或[覆盖文件](#覆盖文件)启用它。 + +## 启用自动 Sidecar 注入 + +默认情况下，自动 sidecar 注入是禁用的。要启用此功能，请在安装或升级时在 values.yaml 中设置 `sidecarInjectorWebhook.enableNamespacesByDefault=true`。这会自动将 Istio sidecar 注入到所有已部署的新命名空间。 + +## 覆盖文件 + +覆盖文件用于为 Istio 进行更广泛的配置。它允许你更改 [IstioOperator API](https://istio.io/latest/docs/reference/config/istio.operator.v1alpha1/) 中可用的任何值。你可以自定义默认安装以满足你的需求。 + +覆盖文件将在 Istio Chart 默认安装的基础上添加配置。换言之，你不需要为安装中已定义的组件进行重新定义。 + +有关覆盖文件的更多信息，请参阅 [Istio 文档](https://istio.io/latest/docs/setup/install/istioctl/#configure-component-settings) + +## 选择器和抓取配置 + +Monitoring 应用设置了 `prometheus.prometheusSpec.ignoreNamespaceSelectors=false`，即在默认情况下跨所有命名空间进行监控。这样，你可以查看部署在具有 `istio-injection=enabled` 标签的命名空间中的资源的流量、指标和图。 + +如果你想将 Prometheus 限制为特定的命名空间，请设置 `prometheus.prometheusSpec.ignoreNamespaceSelectors=true`。完成此操作后，你需要添加其他配置来继续监控你的资源。 + +详情请参阅[本节](selectors-and-scrape-configurations.md)。 + +## 在 RKE2 集群上安装 Istio 的其他步骤 + +详情请参阅[本节](install-istio-on-rke2-cluster.md)。 + +## 项目网络隔离的其他步骤 + +详情请参阅[本节](project-network-isolation.md)。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/istio/configuration-options/install-istio-on-rke2-cluster.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/istio/configuration-options/install-istio-on-rke2-cluster.md new file mode 100644 index 00000000000..811c89b3ea8 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/istio/configuration-options/install-istio-on-rke2-cluster.md @@ -0,0 +1,60 @@ +--- +title: 在 RKE2 和 K3s 集群上安装 Istio 的其他步骤 +--- + +通过 **Apps** 页面安装或升级 Istio Helm Chart 时： + +1. 如果要安装 Chart，请单击**在安装前自定义 Helm 选项**，然后单击**下一步**。 +1. 你将看到配置 Istio Helm Chart 的选项。在**组件**选项卡上，选中**启用 CNI** 旁边的框。 +1. 添加一个自定义覆盖文件，该文件指定 `cniBinDir` 和 `cniConfDir`。有关这些选项的更多信息，请参阅 [Istio 文档](https://istio.io/latest/docs/setup/additional-setup/cni/#helm-chart-parameters)。下方是一个示例： + + + + +```yaml +apiVersion: install.istio.io/v1alpha1 +kind: IstioOperator +spec: + components: + cni: + enabled: true + k8s: + overlays: + - apiVersion: "apps/v1" + kind: "DaemonSet" + name: "istio-cni-node" + patches: + - path: spec.template.spec.containers.[name:install-cni].securityContext.privileged + value: true + values: + cni: + cniBinDir: /opt/cni/bin + cniConfDir: /etc/cni/net.d +``` + + + +```yaml +apiVersion: install.istio.io/v1alpha1 +kind: IstioOperator +spec: + components: + cni: + enabled: true + k8s: + overlays: + - apiVersion: "apps/v1" + kind: "DaemonSet" + name: "istio-cni-node" + patches: + - path: spec.template.spec.containers.[name:install-cni].securityContext.privileged + value: true + values: + cni: + cniBinDir: /var/lib/rancher/k3s/data/current/bin + cniConfDir: /var/lib/rancher/k3s/agent/etc/cni/net.d +``` + + + +**结果**：现在你应该可以根据需要使用 Istio，包括 Sidecar 注入和通过 Kiali 进行监控。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/istio/configuration-options/project-network-isolation.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/istio/configuration-options/project-network-isolation.md new file mode 100644 index 00000000000..00b16856358 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/istio/configuration-options/project-network-isolation.md @@ -0,0 +1,21 @@ +--- +title: 项目网络隔离的其他步骤 +--- + +在集群中： + +- 你同时使用了 Canal 网络插件与 Rancher 2.5.8 之前版本，或者同时使用了 Rancher 2.5.8+ 以及任意支持执行 Kubernetes 网络策略的 RKE 网络插件（例如 Canal 或 Cisco ACI 插件）。 +- 启用了项目网络隔离选项。 +- 安装了 Istio Ingress 模块。 + +默认情况下，Istio Ingress Gateway pod 无法将入口流量重定向到工作负载。这是因为安装了 Istio 的命名空间无法访问所有命名空间。为此你有两个选项。 + +第一个选项是在需要让 Istio 控制入口的每个命名空间中添加一个新的网络策略。你的策略需要包括以下几行： + +``` +- podSelector: + matchLabels: + app: istio-ingressgateway +``` + +第二个选项是将 `istio-system` 命名空间移动到 `system` 项目中，默认情况下该项目被排除在网络隔离之外。 \ No newline at end of file diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/istio/configuration-options/selectors-and-scrape-configurations.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/istio/configuration-options/selectors-and-scrape-configurations.md new file mode 100644 index 00000000000..9828c2b351d --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/istio/configuration-options/selectors-and-scrape-configurations.md @@ -0,0 +1,120 @@ +--- +title: 选择器和抓取配置 +--- + +Monitoring 应用设置了 `prometheus.prometheusSpec.ignoreNamespaceSelectors=false`，即在默认情况下跨所有命名空间进行监控。 + +这样，你可以查看部署在具有 `istio-injection=enabled` 标签的命名空间中的资源的流量、指标和图。 + +如果你想将 Prometheus 限制为特定的命名空间，请设置 `prometheus.prometheusSpec.ignoreNamespaceSelectors=true`。完成此操作后，你需要添加其他配置来继续监控你的资源。 + + +## 通过将 ignoreNamespaceSelectors 设置为 True 来限制对特定命名空间的监控 + +要限制对特定命名空间的监控，你需要编辑 `ignoreNamespaceSelectors` Helm Chart 选项。你可以在安装或升级 Monitoring Helm Chart 时配置此选项： + +1. 安装或升级 Monitoring Helm Chart 时，编辑 values.yml 并设置 `prometheus.prometheusSpec.ignoreNamespaceSelectors=true`。 +1. 完成安装或升级。 + +**结果**：Prometheus 将仅用于特定命名空间。换言之，你需要设置以下配置之一才能继续在各种仪表板中查看数据。 + +## 让 Prometheus 检测其他命名空间中的资源 + +如果设置了 `prometheus.prometheusSpec.ignoreNamespaceSelectors=true`，则有两种方法让 Prometheus 检测其他命名空间中的资源： + +- **监控特定的命名空间**：在命名空间中添加一个 ServiceMonitor 或 PodMonitor 以及要抓取的目标。 +- **跨命名空间监控**：将 `additionalScrapeConfig` 添加到你的 rancher-monitoring 实例，从而抓取所有命名空间中的所有目标。 + +## 监控特定命名空间：创建 ServiceMonitor 或 PodMonitor + +此选项用于定义在特定命名空间中要监控的服务或 pod。 + +可用性权衡指的是，由于你无法跨命名空间进行监控，因此你必须为每个命名空间创建 ServiceMonitor 或 PodMonitor。 + +:::note 先决条件： + +为 `` 定义 ServiceMonitor 或 PodMonitor。下面提供了一个 ServiceMonitor 示例。 + +::: + +1. 点击 **☰ > 集群管理**。 +1. 选择你创建的集群，并点击 **Explore**。 +1. 在顶部导航栏中，打开 kubectl shell。 +1. 如果 ServiceMonitor 或 PodMonitor 文件存储在本地集群中，请运行 `kubectl create -f .yaml`。 +1. 如果 ServiceMonitor 或 PodMonitor 没有存储在本地，请运行 `cat<< EOF | kubectl apply -f -`，将文件内容粘贴到终端，然后运行 ​​`EOF` 来完成命令。 +1. 运行 `kubectl label namespace istio-injection=enabled` 来启用 Envoy sidecar 注入。 + +**结果**：Prometheus 可以抓取 ``。 + +
Istio 代理的 ServiceMonitor 示例
+ +```yaml +apiVersion: monitoring.coreos.com/v1 +kind: ServiceMonitor +metadata: + name: envoy-stats-monitor + namespace: istio-system + labels: + monitoring: istio-proxies +spec: + selector: + matchExpressions: + - {key: istio-prometheus-ignore, operator: DoesNotExist} + namespaceSelector: + any: true + jobLabel: envoy-stats + endpoints: + - path: /stats/prometheus + targetPort: 15090 + interval: 15s + relabelings: + - sourceLabels: [__meta_kubernetes_pod_container_port_name] + action: keep + regex: '.*-envoy-prom' + - action: labeldrop + regex: "__meta_kubernetes_pod_label_(.+)" + - sourceLabels: [__meta_kubernetes_namespace] + action: replace + targetLabel: namespace + - sourceLabels: [__meta_kubernetes_pod_name] + action: replace + targetLabel: pod_name +``` + +## 跨命名空间监控：将 ignoreNamespaceSelectors 设置为 False + +此设置为 Prometheus 提供额外的抓取配置来实现跨命名空间监控。 + +可用性权衡指的是 Prometheus 的所有 `additionalScrapeConfigs` 都维护在一个 Secret 中。如果在安装 Istio 之前已经使用 additionalScrapeConfigs 部署了监控，升级可能会变得困难。 + +1. 安装或升级 Monitoring Helm Chart 时，编辑 values.yml 并将 `prometheus.prometheusSpec.additionalScrapeConfigs` 数组设置为下方的**其它抓取配置**。 +1. 完成安装或升级。 + +**结果**：Promethe 会抓取所有带有 `istio-injection=enabled` 标签的命名空间。 + +
其它抓取配置
+ +```yaml +- job_name: 'istio/envoy-stats' + scrape_interval: 15s + metrics_path: /stats/prometheus + kubernetes_sd_configs: + - role: pod + relabel_configs: + - source_labels: [__meta_kubernetes_pod_container_port_name] + action: keep + regex: '.*-envoy-prom' + - source_labels: [__address__, __meta_kubernetes_pod_annotation_prometheus_io_port] + action: replace + regex: ([^:]+)(?::\d+)?;(\d+) + replacement: $1:15090 + target_label: __address__ + - action: labelmap + regex: __meta_kubernetes_pod_label_(.+) + - source_labels: [__meta_kubernetes_namespace] + action: replace + target_label: namespace + - source_labels: [__meta_kubernetes_pod_name] + action: replace + target_label: pod_name +``` diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/istio/cpu-and-memory-allocations.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/istio/cpu-and-memory-allocations.md new file mode 100644 index 00000000000..c1aad59c6ee --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/istio/cpu-and-memory-allocations.md @@ -0,0 +1,63 @@ +--- +title: CPU 和内存分配 +--- + +本文介绍我们建议在集群中分配给 Istio 组件的最少计算资源。 + +每个组件的 CPU 和内存分配是[可配置](#配置资源分配)的。 + +在启用 Istio 之前，建议你先确认你的 Rancher worker 节点是否有足够的 CPU 和内存来运行 Istio 的所有组件。 + +:::tip + +在规模较大的部署中，我们强烈建议通过为每个 Istio 组件添加节点选择器，来将基础设施放置在集群中的专用节点上。 + +::: + +下表总结了每个核心 Istio 组件推荐配置的 CPU 和内存的最低资源请求和限制。 + +Kubernetes 中的资源请求指的是，除非该节点至少具有指定数量的可用内存和 CPU，否则工作负载不会部署在节点上。如果工作负载超过 CPU 或内存的限制，则可以将其从节点中终止或驱逐。有关管理容器资源限制的更多信息，请参阅 [Kubernetes 文档](https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container/)。 + +| 工作负载 | CPU - 请求 | 内存 - 请求 | CPU - 限制 | 内存 - 限制 | +|----------------------|---------------|------------|-----------------|-------------------| +| 入口网关 | 100m | 128mi | 2000m | 1024mi | +| 出口网关 | 100m | 128mi | 2000m | 1024mi | +| istiod | 500m | 2048mi | 没有限制 | 没有限制 | +| proxy | 10m | 10mi | 2000m | 1024mi | +| **总计：** | **710m** | **2314Mi** | **6000m** | **3072Mi** | + +## 配置资源分配 + +你可以为每种类型的 Istio 组件单独配置资源分配。本节介绍了每个组件默认分配的资源。 + +为了更轻松地将工作负载调度到节点，集群管理员可以降低组件的 CPU 和内存资源请求。默认 CPU 和内存分配是我们推荐的最小值。 + +关于 Istio 配置的更多信息，请参阅 [Istio 官方文档](https://istio.io/)。 + +要配置分配给 Istio 组件的资源： + +1. 点击 **☰ > 集群管理**。 +1. 选择你创建的集群，并点击 **Explore**。 +1. 在左侧导航栏中，点击 **Apps**。 +1. 点击**已安装的应用**。 +1. 转到 `istio-system` 命名空间。在某个 Istio 工作负载中（例如 `rancher-istio`），点击**⋮ > 编辑/升级**。 +1. 点击**升级**，然后通过更改 values.yaml 或添加[覆盖文件](./configuration-options/configuration-options.md#覆盖文件)来编辑基本组件。有关编辑覆盖文件的更多信息，请参阅[本节](#编辑覆盖文件)。 +1. 更改 CPU 或内存分配、调度各个组件的节点，或节点容忍度。 +1. 点击**升级**。然后，更改就能启用。 + +**结果**：已更新 Istio 组件的资源分配。 + +### 编辑覆盖文件 + +覆盖文件可以包含 [Istio Operator 规范](https://istio.io/latest/docs/reference/config/istio.operator.v1alpha1/#IstioOperatorSpec)中的任意值。包含 Istio 应用的覆盖文件只是覆盖文件潜在配置的一个示例。 + +只要文件包含 `kind: IstioOperator` 且 YAML 选项有效，文件就可以用作覆盖。 + +在 Istio 应用提供的示例覆盖文件中，以下部分能让你更改 Kubernetes 资源： + +``` +# k8s: +# resources: +# requests: +# cpu: 200m +``` diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/istio/disable-istio.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/istio/disable-istio.md new file mode 100644 index 00000000000..66e0b1eb9b1 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/istio/disable-istio.md @@ -0,0 +1,42 @@ +--- +title: 禁用 Istio +--- + +本文介绍如何在集群中卸载 Istio，以及如何在命名空间或工作负载中禁用 Istio。 + +## 在集群中卸载 Istio + +要卸载 Istio： + +1. 点击 **☰ > 集群管理**。 +1. 选择你创建的集群，并点击 **Explore**。 +1. 在左侧导航栏中，单击 **Apps > Installed Apps**。 +1. 在 `istio-system` 命名空间中，转到 `rancher-istio` 并单击 **⋮ > 删除**。 +1. 删除 `rancher-istio` 后，选择 `istio-system` 命名空间中所有剩余的应用，然后单击**删除**。 + +**结果**：已删除集群中的 `rancher-istio` 应用。Istio sidecar 不能部署在集群中的任何工作负载上。 + +:::note + +你不能再禁用和重新启用你的 Istio 安装。如果你想保存设置以供将来的安装使用，请查看并保存各个 YAML，以便在之后的安装中参考/重复使用。 + +::: + +**卸载疑难解答**：如果你没有按照卸载步骤操作，则可能会在卸载过程中遇到以下警告： + +`Error: uninstallation completed with 1 error(s): unable to build kubernetes objects for delete: unable to recognize "": no matches for kind "MonitoringDashboard" in version "monitoring.kiali.io/v1alpha1"` + +这可能意味着几种情况。第一种情况是你选择了 `istio-system` 命名空间中的所有应用并同时删除了它们，另一种情况是你在删除 `rancher-istio` Chart 之前删除了`rancher-istio` Chart 依赖项。由于卸载未正确完成，你将需要手动清理 `istio-system` 命名空间中剩余的资源。如果不想进行手动清理，你可以重新安装 `rancher-istio`，然后按照正确的顺序卸载它。 + +## 在命名空间中禁用 Istio + +1. 点击 **☰ > 集群管理**。 +1. 选择你创建的集群，并点击 **Explore**。 +1. 单击**集群 > 项目/命名空间**。 +1. 转到要启用 Istio 的命名空间，然后单击**⋮ > 启用 Istio 自动注入**。或者，你也可以单击命名空间，然后在命名空间详情页面上，单击**⋮ > 启用 Istio 自动注入**。 + +**结果**：如果工作负载部署到此命名空间，它们将没有 Istio sidecar。 + +## 从工作负载中移除 Istio Sidecar + +在命名空间中禁用 Istio，然后重新部署其中的工作负载。这些工作负载将在没有 Istio sidecar 的情况下部署。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/istio/istio.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/istio/istio.md new file mode 100644 index 00000000000..95ac966048f --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/istio/istio.md @@ -0,0 +1,140 @@ +--- +title: Istio +--- + + + + + +[Istio](https://istio.io/) 是一种开源工具，可以让 DevOps 团队更轻松地观察、控制、排查并保护复杂的微服务网络中的流量。 + +随着微服务网络的变化和增长，微服务网络之间的交互变得越来越难以管理和理解。在这种情况下，将服务网格作为单独的基础设施层是非常有用的。Istio 的服务网格可以让你在不直接更改微服务的情况下控制微服务之间的流量。 + +Rancher 与 Istio 集成，使得管理员或集群所有者可以将 Istio 交给开发者团队，然后开发者使用 Istio 执行安全策略，排查问题，或为蓝绿部署，金丝雀部署，和 A/B 测试进行流量管理。 + +此核心服务网格支持但不限于以下功能： + +- **管理流量**：例如入口和出口路由、断路、镜像。 +- **安全**：具有用于验证和授权流量和用户的资源，包括 mTLS。 +- **可观察性**：观察日志、指标和分布式流量。 + +[设置 Istio](../../how-to-guides/advanced-user-guides/istio-setup-guide/istio-setup-guide.md) 后，你可以通过 Rancher UI、`kubectl` 或 ` Istioctl` 来使用 Istio 的 controlplane 功能。 + +Istio 需要由 `cluster-admin` 设置后才能在项目中使用。 + +## Rancher 2.5 的新功能 + +Istio 已简化了整体架构。结合 Pilot、Citadel、Galley 和 sidecar injector 创建了一个单独的组件 Istiod。Node Agent 功能也已合并到 istio-agent 中。 + +以前由 Istio 安装的插件（cert-manager、Grafana、Jaeger、Kiali、Prometheus、Zipkin）现在需要单独安装。Istio 支持安装来自 Istio 项目的集成，并保持与非 Istio 项目的兼容性。 + +你仍然可以通过安装 [Rancher Monitoring](../monitoring-and-alerting/monitoring-and-alerting.md) 或安装你自己的 Prometheus operator 来使用 Prometheus 集成。Rancher 的 Istio chart 还默认安装 Kiali，确保你可以开箱即用地全面了解微服务。 + +Istio 已经脱离了使用 Helm 安装的方式，现在通过 Istioctl 二进制文件或 Istio Operator 进行安装。为了使用最简单的方式与 Istio 交互，Rancher 的 Istio 会维护一个 Helm Chart，该 Chart 使用 Istioctl 二进制文件来管理你的 Istio 安装。 + +此 Helm Chart 将在 UI 的**应用 & 市场**中提供。有权访问 Rancher Chart 应用商店的用户需要先设置 Istio，然后才能在项目中使用它。 + +## Istio 附带的工具 + +我们的 [Istio](https://istio.io/) 安装程序将 istioctl 二进制命令包装在一个 Helm chart 中，其中包括一个覆盖文件的选项，用来支持复杂的自定义配置。 + +它还包括以下内容： + +### Kiali + +Kiali 是一个全面的可视化辅助工具，用于绘制整个服务网格中的流量图。它允许你查看它们的连接方式，包括它们之间的流量速率和延迟。 + +你可以检查服务网格的运行状况，或深入查看单个组件的传入和传出请求。 + +### Jaeger + +Jaeger 是用于跟踪分布式系统的工具。我们的 Istio 安装程序包括能快速启动的一体化 [Jaeger](https://www.jaegertracing.io/) 安装。 + +请注意，这不是符合 Jaeger 生产要求的部署。此部署使用在内存中的存储组件，而 Jaeger 推荐在生产环境中使用持久存储组件。有关你所需的部署策略的更多信息，请参阅 [Jaeger 文档](https://www.jaegertracing.io/docs/1.65/operator/#production-strategy)。 + +## 先决条件 + +在启用 Istio 之前，建议你先确认你的 Rancher worker 节点是否有足够的 [CPU 和内存](cpu-and-memory-allocations.md)来运行 Istio 的所有组件。 + +如果要在 RKE2 集群上安装 Istio，则需要执行一些额外的步骤。有关详细信息，请参阅[本节](#在-rke2-集群上安装-istio-的其他步骤) + +## 设置指南 + +如需了解如何设置 Istio 并在项目中使用它，请参阅[设置指南](../../how-to-guides/advanced-user-guides/istio-setup-guide/istio-setup-guide.md)。 + +## 卸载 Istio + +要从集群、命名空间或工作负载中删除 Istio 组件，请参阅[卸载 Istio](disable-istio.md)。 + +## 访问可视化 + +> 默认情况下，只有 cluster-admin 可以访问 Kiali。有关如何允许具有管理员、编辑或查看权限的角色访问它们的说明，请参阅[本节](rbac-for-istio.md)。 + +在集群中设置 Istio 后，你可以在 Rancher UI 中使用 Grafana、Prometheus 和 Kiali。 + +要访问 Grafana 和 Prometheus 可视化： + +1. 在左上角，单击 **☰ > 集群管理**。 +2. 在**集群**页面上，转到要可视化的集群，然后单击 **Explore**。 +3. 在左侧导航栏中，单击**监控**。 +4. 点击 **Grafana** 或任何其他仪表板。 + +要访问 Kiali 可视化： + +1. 在左上角，单击 **☰ > 集群管理**。 +2. 在**集群**页面上，转到要查看 Kiali 的集群，然后单击 **Explore**。 +3. 在左侧导航栏中，单击 **Istio**。 +4. 单击 **Kiali**。从这里，你可以访问**流量图**或**流量指标**选项卡，从而可视化网络指标。 + +默认情况下，prometheus 会拾取所有命名空间，并将数据用于 Kiali 图。如果你想使用不同的配置进行 prometheus 数据抓取，请参阅[选择器/抓取配置](configuration-options/selectors-and-scrape-configurations.md)。 + +你的角色决定了你对可视化的访问。只有 `cluster-admin` 角色可以使用 Grafana 和 Prometheus。默认情况下，只有 `cluster-admin` 可以使用 Kiali UI，但是 `cluster-admin` 可以通过编辑 Istio values.yaml 来允许其他角色进行访问。 + +## 架构 + +Istio 安装了一个服务网格，它使用 [Envoy](https://www.envoyproxy.io) Sidecar 代理来拦截到每个工作负载的流量。这些 sidecar 拦截并管理服务之间的通信，从而实现精细化观察并控制集群内的流量。 + +只有注入了 Istio sidecar 的工作负载可以通过 Istio 进行跟踪和控制。 + +如果命名空间启用了 Istio，部署到命名空间的新工作负载会自动具有 Istio sidecar。你需要为之前的工作负载手动启用 Istio。 + +有关 Istio sidecar 的更多信息，请参阅 [Istio sidecare-injection 文档](https://istio.io/docs/setup/kubernetes/additional-setup/sidecar-injection/)。有关 Istio 架构的更多信息，请参阅 [Istio 架构文档](https://istio.io/latest/docs/ops/deployment/architecture/)。 + +### 多个 Ingress + +默认情况下，每个 Rancher 配置的集群都有一个 NGINX Ingress Controller 来允许流量进入集群。Istio 还在 `istio-system` 命名空间中默认安装一个 Ingress Gateway。因此，你的集群将有两个 ingress。 + +![启用 Istio 的集群可以有两个 ingress，分别是默认的 Nginx ingress 和默认的 Istio controller](/img/istio-ingress.svg) + +可以通过[覆盖文件](configuration-options/configuration-options.md#覆盖文件)来启用其他 Istio Ingress Gateway。 + +### Egress 支持 + +默认情况下，Egress 网关是禁用的，但你可以在安装或升级时使用 values.yaml 或[覆盖文件](configuration-options/configuration-options.md#覆盖文件)启用它。 + +## 在 RKE2 集群上安装 Istio 的其他步骤 + +要在 RKE2 集群上安装 Istio，请按照[步骤](configuration-options/install-istio-on-rke2-cluster.md)进行操作。 + +## 在离线环境中升级 Istio + +现在，Istio Pod 安全策略默认启用。新值 `installer.releaseMirror.enabled` 已添加到 rancher-istio Chart 中，以启用和禁用支持离线升级的 Server。请注意，`installer.releaseMirror.enabled` 默认设置为 `false`。你可以在安装或升级时根据需要设置该值。按照以下步骤执行： + +1. 在 Rancher UI 中配置离线 Rancher 实例和离线自定义集群。 +2. 在集群中安装 Monitoring：**Cluster Explorer > Apps & Marketplace > Charts > Monitoring**。 +3. 将 Istio 所需的所有镜像拉入在离线环境中使用的私有镜像仓库。 +4. 在集群中安装 Istio：**Cluster Explorer > Apps & Marketplace > Charts > Istio**。 + +:::note + +你可以在新安装的 Istio 上启用 [Jaeger](https://www.jaegertracing.io/) 和 [Kiali](https://kiali.io/)。为确保 Jaeger 和 Kiali 正常工作，请在安装期间将 `values.yaml` 中的 `installer.releaseMirror.enabled` 设置为 `true`。 + +::: + +5. 升级 Istio。 + +:::caution + +如果你还没有执行操作，请设置 `installer.releaseMirror.enabled=true` 以升级 Istio。 + +::: diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/istio/rbac-for-istio.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/istio/rbac-for-istio.md new file mode 100644 index 00000000000..ba56d0ff9b9 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/istio/rbac-for-istio.md @@ -0,0 +1,43 @@ +--- +title: RBAC +--- + +本文介绍访问 Istio 功能所需的权限。 + +Rancher Istio Chart 安装了三个 `ClusterRole`。 + +## Cluster-Admin 访问 + +默认情况下，只有具有 `cluster-admin` `ClusterRole` 的用户可以： + +- 在集群中安装 Istio 应用。 +- 为 Istio 配置资源分配。 + + +## Admin 和 Edit 权限 + +默认情况下，只有 Admin 和 Edit 角色可以： + +- 为命名空间启用和禁用 Istio sidecar 自动注入。 +- 将 Istio sidecar 添加到工作负载。 +- 查看集群的流量指标和流量图。 +- 配置 Istio 的资源（例如网关、目标规则或虚拟服务）。 + +## Kubernetes 默认角色的默认权限摘要 + +Istio 创建了三个 `ClusterRole`，并将 Istio CRD 访问权限添加到以下默认 K8s `ClusterRole`： + +| Chart 创建的 ClusterRole | 默认 K8s ClusterRole | Rancher 角色 | + ------------------------------:| ---------------------------:|---------:| +| `istio-admin` | admin | 项目所有者 | +| `istio-edit` | edit | 项目成员 | +| `istio-view` | view | 只读 | + +Rancher 将继续使用 cluster-owner、cluster-member、project-owner、project-member 等作为角色名称，但会使用默认角色来确定访问权限。每个默认的 K8s `ClusterRole` 都有不同的 Istio CRD 权限以及可以执行的 K8s 操作，包括 Create (C)，Get (G)，List (L)，Watch (W)，Update (U)，Patch (P)，Delete (D) 和 All (*)。 + + +| CRD | Admin | Edit | View | +|----------------------------| ------| -----| ----- +|
  • `config.istio.io`
    • `adapters`
    • `attributemanifests`
    • `handlers`
    • `httpapispecbindings`
    • `httpapispecs`
    • `instances`
    • `quotaspecbindings`
    • `quotaspecs`
    • `rules`
    • `templates`
| GLW | GLW | GLW | +|
  • `networking.istio.io`
    • `destinationrules`
    • `envoyfilters`
    • `gateways`
    • `serviceentries`
    • `sidecars`
    • `virtualservices`
    • `workloadentries`
| * | * | GLW | +|
  • `security.istio.io`
    • `authorizationpolicies`
    • `peerauthentications`
    • `requestauthentications`
| * | * | GLW | \ No newline at end of file diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/kubernetes-distributions/kubernetes-distributions.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/kubernetes-distributions/kubernetes-distributions.md new file mode 100644 index 00000000000..8752645ed96 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/kubernetes-distributions/kubernetes-distributions.md @@ -0,0 +1,34 @@ +--- +title: Kubernetes 发行版 +--- + + + + + +## K3s + +K3s 是一款轻量级、完全兼容的 Kubernetes 发行版，专为一系列用例设计，包括边缘计算、物联网、CI/CD、开发和将 Kubernetes 嵌入到应用程序中。它将系统打包为单个二进制文件，使用 sqlite3 作为默认存储，并提供用户友好的启动器，从而简化了 Kubernetes 的管理。K3s 包括 Local Storage 和负载均衡、Helm Chart 控制器和 Traefik CNI 等基本功能。它最大限度地减少了外部依赖，并提供了精简的 Kubernetes 体验。K3s 于 2020 年 6 月作为沙箱项目捐赠给 CNCF。 + +### K3s 与 Rancher + +- Rancher 允许在一系列平台上轻松配置 K3s，包括 Amazon EC2、DigitalOcean、Azure、vSphere 或现有服务器。 +- Kubernetes 集群的标准 Rancher 管理，包括所有概述[集群管理功能](../../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/kubernetes-clusters-in-rancher-setup.md#不同类型集群的管理功能)。 + +## RKE2 + +RKE2 是 Rancher 开发的一款兼容 Kubernetes 的发行版。它是专门为美国联邦政府部门的安全性和合规性而设计的。 + +RKE2 的主要特性包括: + +1. **安全性和合规性重点**：RKE2 非常重视安全性和合规性，在“默认安全”框架下运行，适用于政府服务以及金融和医疗保健等高度监管的行业。 +1. **CIS Kubernetes Benchmark 一致性**：RKE2 经过预配置，符合 CIS Kubernetes Hardening Benchmark（目前支持 v1.23 和 v1.7），并且只需最少的手动干预。 +1. **FIPS 140-2 合规性**：RKE2 符合 FIPS 140-2 标准，使用经过 FIPS 验证的加密模块作为其组件。 +1. **嵌入式 ETCD**：RKE2 默认使用嵌入式 ETCD 作为其数据存储。这使其与标准的 Kubernetes 实践更加紧密地结合在一起，从而可以更好地与其他 Kubernetes 工具集成并降低错误配置的风险。 +1. **与上游 Kubernetes 保持一致**：RKE2 旨在与上游 Kubernetes 保持密切一致，降低在使用偏离标准 Kubernetes 实践的发行版时可能出现的不一致风险。 +1. **多重 CNI 支持**：RKE2 支持多个容器网络接口（CNI）插件，包括 Cilium、Calico 和 Multus。这对于具有各种生产设施的电信分发中心和工厂等用例至关重要。 + +## RKE2 与 Rancher + +- Rancher 允许在一系列平台上轻松配置 RKE2，包括 Amazon EC2、DigitalOcean、Azure、vSphere 或现有服务器。 +- Kubernetes 集群的标准 Rancher 管理，包括所有概述[集群管理功能](../../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/kubernetes-clusters-in-rancher-setup.md#不同类型集群的管理功能)。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/kubewarden/kubewarden.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/kubewarden/kubewarden.md new file mode 100644 index 00000000000..80c6d16d315 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/kubewarden/kubewarden.md @@ -0,0 +1,31 @@ +--- +title: 使用 Kubewarden 进行高级策略管理 +--- + + + + + +Kubewarden 是一个策略引擎，用于保护和帮助管理集群资源。它允许通过策略验证和更改资源请求，包括上下文感知策略和验证镜像签名。它可以在监视或强制模式下运行策略，并提供集群状态的概述。 + +Kubewarden 旨在通过启用和简化“策略即代码”来成为通用策略引擎。Kubewarden 策略被编译到 WebAssembly 中：它们体积小（400KB~2MB），沙箱式，安全且便携。它旨在通过迎合组织中的每个人来实现通用性： + +- 策略用户：使用 Kubernetes 自定义资源管理和声明策略，重新使用 Rego（OPA 和 Gatekeeper）中编写的现有策略。在 CI/CD 中测试群集外部的策略。 +- 策略开发人员：使用你喜欢的 Wasm 编译语言（Rego、Go、Rust、C#、Swift、Typescript 等）编写策略。重新使用你已经熟悉的工具、库和工作流的生态系统。 +- 策略分发器：策略是 OCI 工件，通过 OCI 仓库为它们提供服务，并在你的基础设施中使用行业标准，如 Software-Bill-Of-Materials 和工件签名。 +- 集群操作员：Kubewarden 是模块化的（OCI 注册表、PolicyServers、Audit Scanner、Controller）。配置你的部署以满足你的需求，隔离不同的租户。使用审核扫描程序和策略报告在集群中获取过去、当前和可能的违规行为的概述。 +- Kubewarden Integrator：将其用作编写新的 Kubewarden 模块和自定义策略的平台。 + +## Kubewarden 和 Rancher + +Kubewarden 的上游 Helm Chart 完全集成为 Rancher 应用程序，为安装选项提供了 UI。这些 Chart 还附带了尊重 Rancher 堆栈的默认设置（例如：不监管 Rancher 系统命名空间）以及默认的 PolicyServer 和策略。用户可以访问所有 Kubewarden 功能，并可以通过与 Kubernetes API 交互（例如：使用 kubectl）手动部署 PolicyServer 和策略。 + +Kubewarden 提供了对已删除的 Kubernetes Pod 安全策略的完全替换。 Kubewarden 还通过增强其安全功能，与最新版本的 Kubernetes 引入的新 Pod Security Admission 功能进行了集成。 + +## Kubewarden 和 Rancher Prime + +Kubewarden 的 Rancher UI 扩展将其集成到 Rancher UI 中。UI 扩展可自动安装和配置 Kubewarden 堆栈，并配置对 SUSE 维护的策略的访问。UI 扩展提供了对现成策略的策划目录的访问。使用 UI 扩展，人们可以浏览、安装和配置这些策略。 + +UI 扩展提供了 Kubewarden 堆栈组件及其行为的概述。这包括对 Kubewarden 指标和跟踪事件的访问。操作员可以了解策略对集群的影响并排查问题。 + +此外，UI 扩展还提供了 Policy Reporter UI，它可以直观地概述 Kubernetes 集群的合规性状态。通过此 UI，操作员可以快速识别所有不合规的 Kubernetes 资源，了解违规原因并采取相应行动。所有这一切都得益于 Rancher Prime 的支持。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/logging/custom-resource-configuration/custom-resource-configuration.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/logging/custom-resource-configuration/custom-resource-configuration.md new file mode 100644 index 00000000000..d719b72fe1d --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/logging/custom-resource-configuration/custom-resource-configuration.md @@ -0,0 +1,12 @@ +--- +title: 自定义资源配置 +--- + + + + + +通过以下自定义资源配置 logging： + +- [Flow 和 ClusterFlow](flows-and-clusterflows.md) +- [Output 和 ClusterOutput](outputs-and-clusteroutputs.md) \ No newline at end of file diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/logging/custom-resource-configuration/flows-and-clusterflows.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/logging/custom-resource-configuration/flows-and-clusterflows.md new file mode 100644 index 00000000000..3f02e5fc4f3 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/logging/custom-resource-configuration/flows-and-clusterflows.md @@ -0,0 +1,75 @@ +--- +title: Flows 和 ClusterFlows +--- + +有关如何配置 `Flow` 和 `ClusterFlow` 的完整详细信息，请参阅 [Logging Operator 文档](https://kube-logging.github.io/docs/configuration/flow/)。 + +有关如何解决 Logging 缓冲区的内存问题，请参阅 [Rancher 与 Logging 服务的集成：故障排除](../logging.md#日志缓冲区导致-pod-过载)。 + +## Flows + +`Flow` 定义要收集和过滤哪些日志，以及将日志发送到哪个 Output。 + +`Flow` 是一个命名空间资源。换言之，只有部署了该 Flow 的命名空间日志才能被 `Flow` 收集。 + +你可以通过在 Rancher UI 中填写表单来配置 `Flow`。 + +有关 `Flow` 自定义资源的更多详细信息，请参阅 [FlowSpec](https://kube-logging.github.io/docs/configuration/crds/v1beta1/flow_types/)。 + +### Matches + +匹配语句用于选择从哪些容器中拉取日志。 + +你可以指定 match 语句，然后根据 Kubernetes 标签、容器和主机名来选择或排除日志。匹配语句会按照定义和处理的顺序进行评估，直到应用了第一个匹配的选择/排除规则。 + +你可以通过填写 Rancher UI 中的 `Flow` 或 `ClusterFlow` 表单来配置匹配。 + +使用 match 语句的详细示例，请参阅[日志路由的官方文档](https://kube-logging.github.io/docs/configuration/log-routing/)。 + +### Filters + +你可以在 `Flow` 中定义一个或多个过滤器。过滤器可以对日志执行各种操作，例如，添加其他数据、转换日志或解析记录中的值。`Flow` 中的过滤器会按定义的顺序应用。 + +有关 Logging Operator 支持的过滤器列表，请参阅 [Fluentd 过滤器的官方文档](https://kube-logging.github.io/docs/configuration/plugins/filters/)。 + +过滤器需要在 YAML 中配置。 + +### Outputs + +此 `Output` 会接收来自 `Flow` 的日志。由于 `Flow` 是一个命名空间资源，因此 `Output` 必须与 `Flow` 位于相同的命名空间中。 + +在 Rancher UI 中填写 `Flow` 或 `ClusterFlow` 表单时，你可以引用`Output`。 + +## ClusterFlows + +为 `ClusterFlow` 配置匹配、过滤器和 `Output` 的方式与 `Flow` 的配置方式相同。主要区别在于 `ClusterFlow` 是集群级别的，并且可以跨所有命名空间配置日志收集。 + +你可以通过在 Rancher UI 中填写表单来配置 `ClusterFlow`。 + +`ClusterFlow` 选择集群中所有命名空间的日志后，集群的日志会被收集并记录到所选的 `ClusterOutput`。 + +## YAML 示例 + +以下示例 `Flow` 转换了默认命名空间的日志消息，并将日志发送到 S3 `Output`： + +```yaml +apiVersion: logging.banzaicloud.io/v1beta1 +kind: Flow +metadata: + name: flow-sample + namespace: default +spec: + filters: + - parser: + remove_key_name_field: true + parse: + type: nginx + - tag_normaliser: + format: ${namespace_name}.${pod_name}.${container_name} + localOutputRefs: + - s3-output + match: + - select: + labels: + app: nginx +``` diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/logging/custom-resource-configuration/outputs-and-clusteroutputs.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/logging/custom-resource-configuration/outputs-and-clusteroutputs.md new file mode 100644 index 00000000000..8e7d608e4a5 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/logging/custom-resource-configuration/outputs-and-clusteroutputs.md @@ -0,0 +1,295 @@ +--- +title: Outputs 和 ClusterOutputs +--- + +有关如何配置 `Flow` 和 `ClusterFlow` 的完整详细信息，请参阅 [Logging Operator 文档](https://kube-logging.github.io/docs/configuration/flow/)。 + +有关如何解决 Logging 缓冲区的内存问题，请参阅 [Rancher 与 Logging 服务的集成：故障排除](../logging.md#日志缓冲区导致-pod-过载)。 + +## Outputs + +`Output` 资源定义了你的 `Flow` 可以发送日志消息的位置。`Output` 是 Logging `Flow` 的最后阶段。 + +`Output` 是命名空间资源，换言之，只有同一命名空间内的 `Flow` 可以访问它。 + +你可以在这些定义中使用密文，但这些密文也必须位于同一命名空间中。 + +你可以通过在 Rancher UI 中填写表单来配置 `Output`。 + +有关 `Output` 自定义资源的更多详细信息，请参阅 [OutputSpec](https://kube-logging.github.io/docs/configuration/crds/v1beta1/output_types/)。 + +Rancher UI 提供了用于配置以下类型 `Output` 的表单： + +- Amazon ElasticSearch +- Azure Storage +- Cloudwatch +- Datadog +- Elasticsearch +- File +- Fluentd +- GCS +- Kafka +- Kinesis Stream +- LogDNA +- LogZ +- Loki +- New Relic +- Splunk +- SumoLogic +- Syslog + +Rancher UI 提供了用于配置 `Output` 类型、目标和访问凭证（如果适用）的表单。 + +有关 Logging Operator 支持的日志插件配置示例，请参阅 [Logging Operator 文档](https://kube-logging.github.io/docs/configuration/plugins/outputs/)。 + +## ClusterOutputs + +`ClusterOutput` 定义了一个没有命名空间限制的 `Output`。只有在与 Logging Operator 部署在同一命名空间中时，它才能生效。 + +你可以通过在 Rancher UI 中填写表单来配置 `ClusterOutput`。 + +有关 `ClusterOutput` 自定义资源的更多详细信息，请参阅 [ClusterOutput](https://kube-logging.github.io/docs/configuration/crds/v1beta1/clusteroutput_types/)。 + +## YAML 示例 + +安装 Logging 后，你可以参考以下示例来构建你自己的 Logging 流水线： + +- [ClusterOutput 设为 ElasticSearch](#clusteroutput-设为-elasticsearch) +- [Output 设为 Splunk](#output-设为-splunk) +- [Output 设为 Syslog](#output-设为-syslog) +- [不支持的 Output](#不支持的-output) + +### ClusterOutput 设为 ElasticSearch + +假设你想将集群中的所有日志发送到 `elasticsearch` 集群。首先，创建一个集群 `Output`： + +```yaml +apiVersion: logging.banzaicloud.io/v1beta1 +kind: ClusterOutput +metadata: + name: "example-es" + namespace: "cattle-logging-system" +spec: + elasticsearch: + host: elasticsearch.example.com + port: 9200 + scheme: http +``` + +在与 Operator 相同的命名空间（`cattle-logging-system`）中，我们创建了这个 `ClusterOutput`（没有 elasticsearch 配置）。每次创建 `ClusterFlow` 或 `ClusterOutput` 时，我们都必须将其放在 `cattle-logging-system` 命名空间中。 + +配置日志的目的位置后，我们可以尝试将所有日志都配置到该 `ClusterOutput`： + +```yaml +apiVersion: logging.banzaicloud.io/v1beta1 +kind: ClusterFlow +metadata: + name: "all-logs" + namespace: "cattle-logging-system" +spec: + globalOutputRefs: + - "example-es" +``` + +现在，我们应该能看到配置的包含日志的索引。 + + +### Output 设为 Splunk + +有时候，你的应用程序团队可能只想将某个命名空间的日志发送到 `splunk` 服务器。对于这种情况，你可以使用命名空间范围的 `Output` 和 `Flow`。 + +在开始之前，先设置该团队的应用程序 `coolapp`。 + +```yaml +apiVersion: v1 +kind: Namespace +metadata: + name: devteam +--- +apiVersion: apps/v1 +kind: Deployment +metadata: + name: coolapp + namespace: devteam + labels: + app: coolapp +spec: + replicas: 2 + selector: + matchLabels: + app: coolapp + template: + metadata: + labels: + app: coolapp + spec: + containers: + - name: generator + image: paynejacob/loggenerator:latest +``` + +`coolapp` 运行时，我们将使用与创建 `ClusterOutput` 时类似的路径。但是，我们不使用 `ClusterOutput`，而是在应用程序的命名空间中创建 `Output`。 + +```yaml +apiVersion: logging.banzaicloud.io/v1beta1 +kind: Output +metadata: + name: "devteam-splunk" + namespace: "devteam" +spec: + splunkHec: + hec_host: splunk.example.com + hec_port: 8088 + protocol: http +``` + +然后，再次为 `Output` 提供一些日志： + +```yaml +apiVersion: logging.banzaicloud.io/v1beta1 +kind: Flow +metadata: + name: "devteam-logs" + namespace: "devteam" +spec: + localOutputRefs: + - "devteam-splunk" +``` + + +### Output 设为 Syslog + +假设你想将集群中的所有日志发送到 `syslog` 服务器。首先，我们创建一个 `ClusterOutput`： + +```yaml +apiVersion: logging.banzaicloud.io/v1beta1 +kind: ClusterOutput +metadata: + name: "example-syslog" + namespace: "cattle-logging-system" +spec: + syslog: + buffer: + timekey: 30s + timekey_use_utc: true + timekey_wait: 10s + flush_interval: 5s + format: + type: json + app_name_field: test + host: syslog.example.com + insecure: true + port: 514 + transport: tcp +``` + +配置日志的目的位置后，我们可以尝试将所有日志都配置到该 `Output`： + +```yaml +apiVersion: logging.banzaicloud.io/v1beta1 +kind: ClusterFlow +metadata: + name: "all-logs" + namespace: cattle-logging-system +spec: + globalOutputRefs: + - "example-syslog" +``` + +### 不支持的 Output + +对于最后一个示例，我们创建一个 `Output` 来将日志写入到不是开箱即用的目标位置： + +:::note Syslog 注意事项： + +`Syslog` 是受支持的 `Output`。但是，此示例仍提供了不受支持的插件概述。 + +::: + +```yaml +apiVersion: v1 +kind: Secret +metadata: + name: syslog-config + namespace: cattle-logging-system +type: Opaque +stringData: + fluent-bit.conf: | + [INPUT] + Name forward + Port 24224 + + [OUTPUT] + Name syslog + InstanceName syslog-output + Match * + Addr syslog.example.com + Port 514 + Cluster ranchers + +--- +apiVersion: apps/v1 +kind: Deployment +metadata: + name: fluentbit-syslog-forwarder + namespace: cattle-logging-system + labels: + output: syslog +spec: + selector: + matchLabels: + output: syslog + template: + metadata: + labels: + output: syslog + spec: + containers: + - name: fluentbit + image: paynejacob/fluent-bit-out-syslog:latest + ports: + - containerPort: 24224 + volumeMounts: + - mountPath: "/fluent-bit/etc/" + name: configuration + volumes: + - name: configuration + secret: + secretName: syslog-config +--- +apiVersion: v1 +kind: Service +metadata: + name: syslog-forwarder + namespace: cattle-logging-system +spec: + selector: + output: syslog + ports: + - protocol: TCP + port: 24224 + targetPort: 24224 +--- +apiVersion: logging.banzaicloud.io/v1beta1 +kind: ClusterFlow +metadata: + name: all-logs + namespace: cattle-logging-system +spec: + globalOutputRefs: + - syslog +--- +apiVersion: logging.banzaicloud.io/v1beta1 +kind: ClusterOutput +metadata: + name: syslog + namespace: cattle-logging-system +spec: + forward: + servers: + - host: "syslog-forwarder.cattle-logging-system" + require_ack_response: false + ignore_network_errors_at_startup: false +``` + +现在，我们分解这里的内容。首先，我们创建一个容器 Deployment，该容器具有额外的 `syslog` 插件并支持转发自另一个 `fluentd` 的日志。接下来，我们创建一个配置为 Deployment 转发器的 `Output`。然后，Deployment `fluentd` 会将所有日志转发到配置的 `syslog` 目标。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/logging/logging-architecture.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/logging/logging-architecture.md new file mode 100644 index 00000000000..cbaeda896e3 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/logging/logging-architecture.md @@ -0,0 +1,28 @@ +--- +title: 架构 +--- + +本节介绍了 Rancher Logging 应用程序的架构。 + +有关 Logging Operator 工作原理的更多详细信息，请参阅[官方文档](https://kube-logging.github.io/docs/#architecture)。 + +## Logging Operator 工作原理 + +Logging Operator 自动部署和配置 Kubernetes 日志流水线。它会在每个节点上部署和配置一个 Fluent Bit DaemonSet，从而收集节点文件系统中的容器和应用程序日志。 + +Fluent Bit 查询 Kubernetes API 并使用 pod 的元数据来丰富日志，然后将日志和元数据都传输到 Fluentd。Fluentd 会接收和过滤日志并将日志传输到多个`Output`。 + +以下自定义资源用于定义了如何过滤日志并将日志发送到 `Output`： + +- `Flow` 是一个命名空间自定义资源，它使用过滤器和选择器将日志消息路由到对应的 `Output`。 +- `ClusterFlow` 用于路由集群级别的日志消息。 +- `Output` 是一个命名空间资源，用于定义发送日志消息的位置。 +- `ClusterOutput` 定义了一个所有 `Flow` 和 `ClusterFlow` 都可用的 `Output`。 + +每个 `Flow` 都必须引用一个 `Output`，而每个 `ClusterFlow` 都必须引用一个 `ClusterOutput`。 + +[Logging Operator 文档](https://kube-logging.github.io/docs/#architecture)中的下图显示了新的 Logging 架构： + +
Logging Operator 如何与 Fluentd 和 Fluent Bit 一起使用
+ +![Logging Operator 如何与 Fluentd 一起使用](/img/banzai-cloud-logging-operator.png) diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/logging/logging-helm-chart-options.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/logging/logging-helm-chart-options.md new file mode 100644 index 00000000000..a6b72b66af6 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/logging/logging-helm-chart-options.md @@ -0,0 +1,93 @@ +--- +title: rancher-logging Helm Chart 选项 +--- + +## 启用/禁用 Windows 节点 Logging + +要启用或禁用 Windows 节点 Logging，你可以在 `values.yaml` 中将 `global.cattle.windows.enabled` 设置为 `true` 或 `false`。 + +默认情况下，如果使用 Cluster Dashboard UI 在 Windows 集群上安装了 Logging 应用程序，Windows 节点的 Logging 就会启用。 + +在这种情况下，将 `global.cattle.windows.enabled` 设置为 `false` 会禁用集群上的 Windows 节点 Logging。 +禁用后，仍会从 Windows 集群中的 Linux 节点收集日志。 + +:::note + +目前存在一个[问题](https://github.com/rancher/rancher/issues/32325)，在 Windows 集群中禁用 Windows Logging 后执行 `helm upgrade` 时不会删除 Windows nodeAgent。在这种情况下，如果已安装 Windows nodeAgents，用户可能需要手动卸载它们。 + +::: + +## 使用自定义 Docker 根目录 + +如果使用了自定义 Docker 根目录，你可以在 `values.yaml` 中设置 `global.dockerRootDirectory`。 + +这将确保创建的 Logging CR 使用你指定的路径，而不是使用默认的 Docker `data-root` 位置。 + +请注意，这只影响 Linux 节点。 + +如果集群中有任何 Windows 节点，则更改将不适用于这些节点。 + +## 为自定义污点添加 NodeSelector 设置和容忍度 + +你可以添加 `nodeSelector` 设置，并通过编辑 Logging Helm Chart 值来添加其他`容忍度`。有关详细信息，请参阅[此页面](taints-and-tolerations.md)。 + +## 启用 Logging 应用程序以使用 SELinux + +:::note 要求： + +Logging v2 已在 RHEL/CentOS 7 和 8 上使用 SELinux 进行了测试。 + +::: + +[安全增强型 Linux (SELinux)](https://en.wikipedia.org/wiki/Security-Enhanced_Linux) 是对 Linux 的安全增强。被政府机构使用之后，SELinux 已成为行业标准，并在 CentOS 7 和 8 上默认启用。 + +要配合使用 Logging V2 与 SELinux，我们建议你根据[此说明](../../reference-guides/rancher-security/selinux-rpm/selinux-rpm.md)安装 `rancher-selinux` RPM。 + +然后，在安装 Logging 应用程序时，在 `values.yaml` 中将 `global.seLinux.enabled` 更改为 `true`，使 Chart 支持 SELinux。 + +## 其他日志来源 + +默认情况下，Rancher 会收集所有类型集群的 [controlplane 组件](https://kubernetes.io/docs/concepts/overview/components/#control-plane-components)和[节点组件](https://kubernetes.io/docs/concepts/overview/components/#node-components)的日志。 + +在某些情况下，Rancher 也能收集其他的日志。 + +下表总结了每种节点类型可以收集的其他日志来源： + +| 日志来源 | Linux 节点（包括在 Windows 集群中） | Windows 节点 | +| --- | --- | ---| +| RKE2 | ✓ | | +| K3s | ✓ | | +| AKS | ✓ | | +| EKS | ✓ | | +| GKE | ✓ | | + +要将托管 Kubernetes 的提供商作为额外的日志来源，在安装或升级 Logging Helm Chart 时，请启用 **Enable enhanced cloud provider logging** 选项。 + +启用后，Rancher 会收集提供商开放可用的所有其他节点和 controlplane 日志，不同提供商可能有所不同。 + +如果你已经使用了云提供商的日志解决方案，例如 AWS CloudWatch 或 Google Cloud Operations Suite（以前称为 Stackdriver），由于原生解决方案可以不受限制地访问所有日志，因此你无需启用此选项。 + +## Systemd 配置 + +在 Rancher Logging 中，你必须为 K3s 和 RKE2 Kubernetes 发行版配置 `SystemdLogPath`。 + +K3s 和 RKE2 Kubernetes 发行版将日志写入到 journald，它是 systemd 的子系统，用于日志记录。要收集这些日志，你需要定义 `systemdLogPath`。默认路径是 `run/log/journal`，但某些 Linux 发行版不默认使用该路径。例如，Ubuntu 默认使用 `var/log/journal`。要确定你的 `systemdLogPath` 配置，请参阅以下步骤。 + +**Systemd 配置步骤：** + +* 在其中一个节点上运行 `cat /etc/systemd/journald.conf | grep -E ^\#?Storage | cut -d"=" -f2`。 +* 如果返回 `persistent`，则你的 `systemdLogPath` 是 `/var/log/journal`。 +* 如果返回 `volatile`，则你的 `systemdLogPath` 是 `/run/log/journal`。 +* 如果返回 `auto`，则检查 `/var/log/journal` 是否存在。 + * 如果 `/var/log/journal` 存在，则使用 `/var/log/journal`。 + * 如果 `/var/log/journal` 不存在，则使用 `/run/log/journal`。 + +:::note 注意事项： + +如果返回的值不包括在上述描述中，Rancher Logging 将无法收集 controlplane 日志。要解决此问题，你需要在每个 controlplane 节点上执行以下操作。 + +* 在 journald.conf 中设置 `Storage=volatile`。 +* 重启主机。 +* 将 `systemdLogPath` 设置为 `/run/log/journal`。 + +::: \ No newline at end of file diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/logging/logging.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/logging/logging.md new file mode 100644 index 00000000000..dcc65014fbd --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/logging/logging.md @@ -0,0 +1,115 @@ +--- +title: Rancher Logging 集成 +description: Rancher 集成了主流的日志服务。了解集成日志服务的要求和优势，并在你的集群上启用 Logging。 +--- + + + + + +现在，Rancher 的日志管理由 [Logging operator](https://kube-logging.github.io/docs/) 提供支持，它取代了以前的内部解决方案。 + +## 启用 Logging + +你可以转到**应用**页面并安装 Logging 应用程序，从而为 Rancher 管理的集群启用 Logging： + +1. 转到要安装 Logging 的集群，然后单击 **Apps**。 +1. 点击 **Logging** 应用。 +1. 滚动到 Helm Chart README 的底部，然后单击**安装**。 + +**结果**：Logging 应用已部署到 `cattle-logging-system` 命名空间中。 + +## 卸载 Logging + +1. 转到要安装 Logging 的集群，然后单击 **Apps**。 +1. 点击**已安装的应用**。 +1. 转到 `cattle-logging-system` 命名空间并选中 `rancher-logging` 和 `rancher-logging-crd` 框。 +1. 单击**删除**。 +1. 确认**删除**。 + +**结果**：已卸载 `rancher-logging`。 + +## 架构 + +有关 Logging 应用程序工作原理的更多信息，请参阅[本节](logging-architecture.md)。 + +## RBAC + +Rancher Logging 有两个角色，分别是 `logging-admin` 和 `logging-view`。有关如何以及何时使用这些角色的更多信息，请参阅[此页面](rbac-for-logging.md)。 + +## 配置 Logging 自定义资源 + +要管理 `Flows`、`ClusterFlows`、`Outputs` 和 `ClusterOutputs`： + +1. 在左上角，单击 **☰ > 集群管理**。 +2. 在**集群**页面上，转到要配置 Logging 自定义资源的集群，然后单击 **Explore**。 +3. 在左侧导航栏中，单击 **Logging**。 + +### Flows 和 ClusterFlows + +有关配置 `Flows` 和 `ClusterFlows` 的帮助，请参阅[此页面](custom-resource-configuration/flows-and-clusterflows.md)。 + +### Outputs 和 ClusterOutputs + +有关配置 `Outputs` 和 `ClusterOutputs` 的帮助，请参阅[此页面](custom-resource-configuration/outputs-and-clusteroutputs.md)。 + +## 配置 Logging Helm Chart + +有关在安装或升级 Logging 应用程序时可配置的选项，请参阅[此页面](logging-helm-chart-options.md)。 + +### Windows 支持 + +你可以从 Windows 节点[启用 Logging](logging-helm-chart-options.md#启用禁用-windows-节点-logging)。 + +### 使用自定义 Docker 根目录 + +有关使用自定义 Docker 根目录的详细信息，请参阅[本节](logging-helm-chart-options.md#使用自定义-docker-根目录)。 + +### 处理污点和容忍度 + +有关如何在 Logging 应用程序中使用污点和容忍度的信息，请参阅[此页面](taints-and-tolerations.md)。 + +### 在 SELinux 上使用 Logging V2 + +有关在启用了 SELinux 的节点上使用 Logging 应用程序的信息，请参阅[本节](logging-helm-chart-options.md#启用-logging-应用程序以使用-selinux)。 + +### 其他日志来源 + +默认情况下，Rancher 会收集所有类型集群的 controlplane 组件和节点组件的日志。在某些情况下，也会收集其他日志。有关详细信息，请参阅[本节](logging-helm-chart-options.md#其他日志来源)。 + +## 故障排除 + +### 日志缓冲区导致 Pod 过载 + +根据你的配置，默认缓冲区大小可能太大并导致 Pod 故障。减少负载的一种方法是降低记录器的刷新间隔。这可以防止日志溢出缓冲区。你还可以添加更多刷新线程来处理大量日志试图同时填充缓冲区的情况。 + +有关如何配置日志缓冲区来满足企业需求的更完整说明，请参阅[缓冲区](https://kube-logging.github.io/docs/configuration/plugins/outputs/buffer/)和 [Fluentd 配置](https://kube-logging.github.io/docs/logging-infrastructure/fluentd/)的官方 Logging Operator 文档。 + +### `cattle-logging` 命名空间正在重新创建 + +如果你的集群之前在旧版 Rancher UI 的全局视图中部署了 Logging，`cattle-logging` 命名空间可能会不断被重新创建。 + +要解决这个问题，你可以将所有 `clusterloggings.management.cattle.io` 和 `projectloggings.management.cattle.io` 自定义资源从管理集群中针对该集群的命名空间中删除。 +这些自定义资源会导致 Rancher 在下游集群中创建 `cattle-logging` 命名空间（如果不存在）。 + +集群命名空间与集群 ID 匹配，因此我们需要找到每个集群的集群 ID。 + +1. 在左上角，单击 **☰ > 集群管理**。 +1. 在**集群**页面上，转到要获取 ID 的集群，然后单击 **Explore**。 +2. 从以下其中一个 URL 中复制 `` 的内容。`` 是集群命名空间名称。 + +```bash +# Cluster Management UI +https:///c// + +# Cluster Dashboard +https:///dashboard/c// +``` + +现在我们有了 `` 命名空间，我们可以删除导致 `cattle-logging` 不断重新创建的自定义资源。 +*警告*：请确保当前未使用 Logging （从旧版 Rancher UI 全局视图中安装的版本）。 + +```bash +kubectl delete crd clusterloggings.management.cattle.io -n +kubectl delete crd projectloggings.management.cattle.io -n +``` diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/logging/rbac-for-logging.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/logging/rbac-for-logging.md new file mode 100644 index 00000000000..2959a9f7946 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/logging/rbac-for-logging.md @@ -0,0 +1,23 @@ +--- +title: Logging 的 RBAC +--- + +Rancher Logging 有两个角色，分别是 `logging-admin` 和 `logging-view`。 + +- `logging-admin` 允许用户完全访问命名空间的 `Flow` 和 `Output`。 +- `logging-view` 允许用户*查看*命名空间的 `Flow` 和 `Output`，以及 `ClusterFlow` 和 `ClusterOutput`。 + +:::note 为什么选择一个角色而不是另一个角色？ + +`ClusterFlow` 和 `ClusterOutput` 资源的编辑权限非常强大。任何拥有该权限的用户都能编辑集群中的所有日志。 + +::: + +在 Rancher 中，集群管理员角色是唯一可以完全访问所有 `rancher-logging` 资源的角色。集群成员无法编辑或读取任何 Logging 资源。项目所有者和成员具有以下权限： + +| 项目所有者 | 项目成员 | +--- | --- +| 能够在其项目命名空间中创建命名空间级别的 `Flow` 和 `Output` | 只能查看项目命名空间中的 `Flow` 和 `Output` | +| 可以从项目命名空间中收集任何日志 | 无法在其项目命名空间中收集任何日志 | + +如果项目所有者和项目成员需要使用 Logging，他们需要在项目中至少有*一个*命名空间。如果没有，他们可能看不到顶部导航下拉列表中的 Logging 按钮。 \ No newline at end of file diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/logging/taints-and-tolerations.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/logging/taints-and-tolerations.md new file mode 100644 index 00000000000..d109b29f8ea --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/logging/taints-and-tolerations.md @@ -0,0 +1,64 @@ +--- +title: 处理污点和容忍度 +--- + +在 Kubernetes 节点上添加污点会导致 pod 排斥在该节点上运行。 + +除非 pod 对该节点的污点具有`容忍度`（toleration），否则 Pod 将在集群中的其他节点上运行。 + +[污点和容忍度](https://kubernetes.io/docs/concepts/scheduling-eviction/taint-and-toleration/)可以与 `PodSpec` 中的 `nodeSelector` [字段](https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node/#nodeselector)一起使用，从而实现*相反的*污点效果。 + +`nodeSelector` 可以使 pod 被吸引到某类节点。 + +两者都能让 pod 选择在哪个节点上运行。 + +- [Rancher 日志堆栈中的默认实现](#rancher-日志堆栈中的默认实现) +- [为自定义污点添加 NodeSelector 设置和容忍度](#为自定义污点添加-nodeselector-设置和容忍度) + +## Rancher 日志堆栈中的默认实现 + +默认情况下，Rancher 使用 `cattle.io/os=linux` 来将污点应用到所有 Linux 节点，而不影响 Windows 节点。 +日志堆栈 pod 具有针对此污点的`容忍度`，因此它们能够运行在 Linux 节点上。 +此外，大多数日志堆栈 pod 仅在 Linux 上运行，并添加了 `nodeSelector` 以确保它们在 Linux 节点上运行。 + +此示例 Pod YAML 文件显示了与容忍度一起使用的 nodeSelector： + +```yaml +apiVersion: v1 +kind: Pod +# metadata... +spec: + # containers... + tolerations: + - key: cattle.io/os + operator: "Equal" + value: "linux" + effect: NoSchedule + nodeSelector: + kubernetes.io/os: linux +``` + +在上面的示例中，我们确保了的 pod 仅在 Linux 节点上运行，并且为所有 Linux 节点上的污点添加了`容忍度`。 + +你可以对 Rancher 现有的污点或你自己的自定义污点执行相同的操作。 + +## 为自定义污点添加 NodeSelector 设置和容忍度 + +如果要添加你自己的 `nodeSelector` 设置，或者要为其他污点添加 `容忍度`，你可以将以下内容传递给 Chart 的值： + +```yaml +tolerations: + # insert tolerations... +nodeSelector: + # insert nodeSelector... +``` + +这些值会将这两个设置添加到 `fluentd`、`fluentbit`和 `logging-operator` 容器中。 +本质上，这些是日志堆栈中所有 pod 的全局设置。 + +但是，如果你想*仅*为 `fluentbit` 容器添加容忍度，你可以将以下内容添加到 Chart 的值中： + +```yaml +fluentbit_tolerations: + # insert tolerations list for fluentbit containers only... +``` diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/longhorn.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/longhorn.md new file mode 100644 index 00000000000..53ffddc28d2 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/longhorn.md @@ -0,0 +1,70 @@ +--- +title: Longhorn - Kubernetes 的云原生分布式块存储 +--- + +[Longhorn](https://longhorn.io/) 是一个轻量级、可靠、易用的 Kubernetes 分布式块存储系统。 + +Longhorn 是免费的开源软件。Longhorn 最初由 Rancher Labs 开发，现在正在作为云原生计算基金会的沙盒项目进行开发。它可以通过 Helm、kubectl 或 Rancher UI 安装在任何 Kubernetes 集群上。有关其架构的更多信息，请参阅[此处](https://longhorn.io/docs/latest/concepts/)。 + +使用 Longhorn，你可以： + +- 将 Longhorn 卷用作 Kubernetes 集群中分布式有状态应用程序的持久存储 +- 将你的块存储分区为 Longhorn 卷，以便在有或没有云提供商的情况下使用 Kubernetes 卷 +- 跨多个节点和数据中心复制块存储以提高可用性 +- 将备份数据存储在 NFS 或 AWS S3 等外部存储中 +- 创建跨集群灾难恢复卷，以便使用另一个 Kubernetes 集群中的备份快速恢复主 Kubernetes 集群中的数据 +- 计划卷的定期快照，并将定期备份调度到 NFS 或兼容 S3 的辅助存储 +- 使用备份来恢复卷 +- 在不中断持久卷的情况下升级 Longhorn + +
Longhorn 仪表板
+ +![Longhorn 仪表板](/img/longhorn-screenshot.png) + +## 使用 Rancher 安装 Longhorn + +1. 满足所有[安装要求](https://longhorn.io/docs/latest/deploy/install/#installation-requirements)。 +1. 转到要安装 Longhorn 的集群。 +1. 单击 **Apps**。 +1. 单击 **Chart**。 +1. 点击 **Longhorn**。 +1. 可选：要自定义初始设置，请单击 **Longhorn 默认设置**并编辑配置。如需自定义设置的帮助，请参阅 [Longhorn 文档](https://longhorn.io/docs/latest/references/settings/)。 +1. 单击**安装**。 + +**结果**：Longhorn 已部署到 Kubernetes 集群中。 + +## 从 Rancher UI 访问 Longhorn + +1. 转到安装了 Longhorn 的集群。在左侧导航菜单中，单击 **Longhorn**。 +1. 在此页面上，你可以编辑 Longhorn 管理的 Kubernetes 资源。要查看 Longhorn UI，请单击**概述**中的 **Longhorn** 按钮。 + +**结果**：你将转到 Longhorn UI，你可以在那里管理 Longhorn 卷及其在 Kubernetes 集群中的副本，还可以查看位于另一个 Kubernetes 集群或 S3 中的 Longhorn 存储辅助备份。 + +## 从 Rancher UI 卸载 Longhorn + +1. 转到安装了 Longhorn 的集群，然后单击 **Apps**。 +1. 点击**已安装的应用**。 +1. 转到 `longhorn-system` 命名空间并选中 `longhorn` 和 `longhorn-crd` 应用程序旁边的框。 +1. 单击**删除**并确认**删除**。 + +**结果**：Longhorn 已被卸载。 + +## GitHub 仓库 + +Longhorn 项目在[此处](https://github.com/longhorn/longhorn)。 + +## 文档 + +Longhorn 文档在[此处](https://longhorn.io/docs/)。 + +## 架构 + +Longhorn 为每个卷创建专用的存储控制器，并在存储在多个节点上的多个副本之间同步复制该卷。 + +存储控制器和副本本身是使用 Kubernetes 编排的。 + +有关其架构的更多信息，请参阅[此处](https://longhorn.io/docs/latest/concepts/)。 + +
Longhorn 架构
+ +![Longhorn 架构](/img/longhorn-architecture.svg) diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/longhorn/longhorn.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/longhorn/longhorn.md new file mode 100644 index 00000000000..c3727f30ff8 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/longhorn/longhorn.md @@ -0,0 +1,15 @@ +--- +title: 使用 Longhorn 进行云原生存储 +--- + + + + + +## Longhorn + +Longhorn 是官方的[云原生计算基金会（CNCF）](https://cncf.io/)项目，它为 Kubernetes 提供了一个可以在任何地方运行的强大的云原生分布式存储平台。当与 Rancher 相结合使用时，Longhorn 使你可以在 Kubernetes 环境中轻松、快速且可靠地部署高可用的持久块存储。 + +## Longhorn 与 Rancher + +凭借 Rancher Prime 和 Longhorn，用户可以通过 Rancher 应用商店一键轻松部署，并对托管集群进行生命周期管理；允许用户能够安装和升级，同时进行清空操作以实现优雅的操作。Longhorn 和 Rancher Prime 还提供了 Windows 的混合集群支持，Rancher 托管的镜像，通过 Rancher 的 UI 代理访问，以及使用 Longhorn 指标进行 Rancher 监控。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/longhorn/overview.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/longhorn/overview.md new file mode 100644 index 00000000000..dd02b06d713 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/longhorn/overview.md @@ -0,0 +1,74 @@ +--- +title: 概述 +--- + + + + + +[Longhorn](https://longhorn.io/) 是一个轻量级、可靠且易于使用的 Kubernetes 分布式块存储系统。 + +Longhorn 是免费的开源软件。它最初由 Rancher Labs 开发，现在被开发为云原生计算基金会的沙箱项目。它可以通过 Helm、kubectl 或 Rancher UI 安装在任何 Kubernetes 集群上。有关其架构的更多信息，请参阅[此处](https://longhorn.io/docs/latest/concepts/)。 + +使用 Longhorn，你可以： + +- 使用 Longhorn 卷作为 Kubernetes 集群中分布式有状态应用程序的持久存储 +- 将块存储分区为 Longhorn 卷，以便你可以在有或没有云提供商的情况下使用 Kubernetes 卷 +- 跨多个节点和数据中心复制块存储以提高可用性 +- 将备份数据存储在 NFS 或 AWS S3 等外部存储中 +- 创建跨集群灾难恢复卷，以便使用另一个 Kubernetes 集群中的备份快速恢复主 Kubernetes 集群中的数据 +- 计划卷的定期快照，并将定期备份调度到 NFS 或兼容 S3 的辅助存储 +- 使用备份来恢复卷 +- 在不中断持久卷的情况下升级 Longhorn + +
Longhorn 仪表板
+ +![Longhorn 仪表板](/img/longhorn-screenshot.png) + +## 使用 Rancher 安装 Longhorn + +1. 满足所有[安装要求](https://longhorn.io/docs/latest/deploy/install/#installation-requirements)。 +1. 转到要安装 Longhorn 的集群。 +1. 单击 **Apps**。 +1. 单击 **Charts**。 +1. 单击 **Longhorn**。 +1. 可选：要自定义初始设置，请单击 **Longhorn 默认设置**并编辑配置。如需自定义设置的帮助，请参阅 [Longhorn 文档](https://longhorn.io/docs/latest/references/settings/)。 +1. 单击**安装**。 + +**结果**：Longhorn 已部署到 Kubernetes 集群中。 + +## 从 Rancher UI 访问 Longhorn + +1. 转到安装了 Longhorn 的集群。在左侧导航菜单中，单击 **Longhorn**。 +1. 在此页面上，你可以编辑 Longhorn 管理的 Kubernetes 资源。要查看 Longhorn UI，请单击**概述**中的 **Longhorn** 按钮。 + +**结果**：你将转到 Longhorn UI，在这里你可以管理 Kubernetes 集群中的 Longhorn 卷及其副本，以及可能存在于另一个 Kubernetes 集群或 S3 中的 Longhorn 存储辅助备份。 + +## 从 Rancher UI 卸载 Longhorn + +1. 转到安装了 Longhorn 的集群，然后单击 **Apps**。 +1. 点击**已安装的应用**。 +1. 转到 `longhorn-system` 命名空间并选中 `longhorn` 和 `longhorn-crd` 应用程序旁边的框。 +1. 单击**删除**并确认**删除**。 + +**结果**：Longhorn 已被卸载。 + +## GitHub 仓库 + +Longhorn 项目可在[此处](https://github.com/longhorn/longhorn)获取。 + +## 文档 + +Longhorn 文档在[此处](https://longhorn.io/docs/)。 + +## 架构 + +Longhorn 为每个卷创建专用的存储控制器，并在多个节点上存储的多个副本之间同步复制该卷。 + +存储控制器和副本本身是使用 Kubernetes 编排的。 + +有关其架构的更多信息，请参阅[此处](https://longhorn.io/docs/latest/concepts/)。 + +
Longhorn 架构
+ +![Longhorn 架构](/img/longhorn-architecture.svg) diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/monitoring-and-alerting/built-in-dashboards.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/monitoring-and-alerting/built-in-dashboards.md new file mode 100644 index 00000000000..101ae2b2cd4 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/monitoring-and-alerting/built-in-dashboards.md @@ -0,0 +1,117 @@ +--- +title: 内置仪表板 +--- + +## Grafana UI + +你可以使用 [Grafana](https://grafana.com/grafana/) 对存储在各个地方的指标进行查询、可视化、告警和了解。你能与你的团队创建、探索和共享仪表板，并培养数据驱动的文化。 + +要查看时间序列数据可视化的默认仪表板，请转到 Grafana UI。 + +### 自定义 Grafana + +要查看和自定义用于支持 Grafana 仪表板的 PromQL 查询，请参阅[此页面](../../how-to-guides/advanced-user-guides/monitoring-alerting-guides/customize-grafana-dashboard.md)。 + +### 持久化 Grafana 仪表板 + +要创建持久化 Grafana 仪表板，请参阅[此页面](../../how-to-guides/advanced-user-guides/monitoring-alerting-guides/create-persistent-grafana-dashboard.md)。 + +### 访问 Grafana + +有关 Grafana 的 RBAC，请参阅[本节](rbac-for-monitoring.md#grafana-的-rbac)。 + + +## Alertmanager UI + +安装 `rancher-monitoring` 后，会部署 Prometheus Alertmanager UI，从而让你查看告警以及当前的 Alertmanager 配置。 + +:::note + +本节参考假设你已经熟悉 Monitoring 组件的协同工作方式。有关 Alertmanager 的详细信息，请参阅 [Alertmanager 工作原理](how-monitoring-works.md#3-alertmanager-的工作原理)。 + +::: + +### 访问 Alertmanager UI + +Alertmanager UI 可让你查看最近触发的告警。 + +:::note 先决条件： + +必须安装 `rancher-monitoring` 应用。 + +::: + +要查看 Alertmanager UI： + +1. 在左上角，单击 **☰ > 集群管理**。 +1. 在**集群**页面上，转到要查看 Alertmanager UI 的集群，然后单击 **Explore**。 +1. 在左侧导航栏中，单击**监控**。 +1. 单击 **Alertmanager**。 + +**结果**：在新选项卡中打开 Alertmanager UI。如需配置帮助，请参阅[官方 Alertmanager 文档](https://prometheus.io/docs/alerting/latest/alertmanager/)。 + +有关在 Rancher 中配置 Alertmanager 的更多信息，请参阅[此页面](../../how-to-guides/advanced-user-guides/monitoring-v2-configuration-guides/advanced-configuration/alertmanager.md)。 + +
Alertmanager UI
+ +![Alertmanager UI](/img/alertmanager-ui.png) + + +### 查看默认告警 + +要查看默认触发的告警，请转到 Alertmanager UI 并单击**展开所有组**。 + + +## Prometheus UI + +默认情况下，[kube-state-metrics service](https://github.com/kubernetes/kube-state-metrics) 向 monitoring 应用提供 CPU 和内存利用率的大量信息。这些指标涵盖了跨命名空间的 Kubernetes 资源。换言之，如果你要查看服务的资源指标，你无需为其创建新的 ServiceMonitor。由于数据已经在时间序列数据库中，你可以转到 Prometheus UI 并运行 PromQL 查询来获取信息。你可以使用相同的查询来配置 Grafana 仪表板，从而显示这些指标随时间变化的图表。 + +要查看 Prometheus UI，请安装 `rancher-monitoring`。然后： + +1. 在左上角，单击 **☰ > 集群管理**。 +1. 在**集群**页面上，转到要查看 Prometheus UI 的集群，然后单击 **Explore**。 +1. 在左侧导航栏中，单击**监控**。 +1. 单击 **Prometheus Graph**。 + +
Prometheus Graph UI
+ +![Prometheus Graph UI](/img/prometheus-graph-ui.png) + +### 查看 Prometheus 目标 + +要查看你正在监控的服务，你需要查看你的目标。目标是由 ServiceMonitor 和 PodMonitor 设置的，指的是指标抓取的的源。你无需直接编辑目标，但 Prometheus UI 可为你提供抓取的所有指标来源的概览。 + +要查看 Prometheus 目标，请安装 `rancher-monitoring`。然后： + + +1. 在左上角，单击 **☰ > 集群管理**。 +1. 在**集群**页面上，转到要查看 Prometheus 目标的集群，然后单击 **Explore**。 +1. 在左侧导航栏中，单击**监控**。 +1. 单击 **Prometheus 目标**。 + +
Prometheus UI 中的目标
+ +![Prometheus 目标 UI](/img/prometheus-targets-ui.png) + +### 查看 PrometheusRules + +当你定义规则时（在 PrometheusRule 资源的 RuleGroup 中声明），[规则本身的规范](https://github.com/prometheus-operator/prometheus-operator/blob/main/Documentation/api-reference/api.md#rule)会包含标签，然后 Alertmanager 会使用这些标签来确定接收对应告警的路由。 + +要查看 PrometheusRule，请安装 `rancher-monitoring`。然后： + +1. 在左上角，单击 **☰ > 集群管理**。 +1. 在**集群**页面上，转到要可视化的集群，然后单击 **Explore**。 +1. 在左侧导航栏中，单击**监控**。 +1. 点击 **Prometheus 规则**。 + +你还可以在 Prometheus UI 中查看规则： + +
Prometheus UI 中的规则
+ +![PrometheusRules UI](/img/prometheus-rules-ui.png) + +有关在 Rancher 中配置 PrometheusRule 的更多信息，请参阅[此页面](../../how-to-guides/advanced-user-guides/monitoring-v2-configuration-guides/advanced-configuration/prometheusrules.md)。 + +## 旧版 UI + +有关在引入 `rancher-monitoring` 应用程序之前 Rancher v2.2 到 v2.4 中可用仪表板的信息，请参阅 [Rancher v2.0—v2.4 文档](https://github.com/rancher/rancher-docs/tree/main/archived_docs/en/version-2.0-2.4/explanations/integrations-in-rancher/cluster-monitoring/viewing-metrics.md)。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/monitoring-and-alerting/how-monitoring-works.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/monitoring-and-alerting/how-monitoring-works.md new file mode 100644 index 00000000000..fb4a5c764c4 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/monitoring-and-alerting/how-monitoring-works.md @@ -0,0 +1,245 @@ +--- +title: Monitoring 的工作原理 +--- + +## 1. 架构概述 + +_**下文描述了数据如何流经 Monitoring V2 应用程序：**_ + +### Prometheus Operator + +Prometheus Operator 观察正在创建的 ServiceMonitors、PodMonitors 和 PrometheusRules。在创建 Prometheus 配置资源时，Prometheus Operator 会调用 Prometheus API 来同步新配置。如本节末尾的图所示，Prometheus Operator 充当 Prometheus 和 Kubernetes 之间的中介，调用 Prometheus API 来同步 Prometheus 与 Kubernetes 中的监控相关资源。 + +### ServiceMonitor 和 PodMonitor + +ServiceMonitor 和 PodMonitor 以声明方式指定需要监控的目标，例如 Service 和 Pod。 + +- 目标是根据配置的 Prometheus 抓取间隔定期抓取的，而抓取的指标存储在 Prometheus 时间序列数据库（Time Series Database，TSDB）中。 + +- 为了执行抓取，你需要使用标签选择器来定义 ServiceMonitor 和 PodMonitor，这些标签选择器用于确定要抓取的 Service 或 Pod，并能确定端点（端点能确定抓取如何在给定目标上进行，例如在 TCP 10252 中抓取指标，通过 IP 地址 x.x.x.x 进行代理）。 + +- 开箱即用地，Monitoring V2 附带了一些预配置的 Exporter，这些 Exporter 根据其所在的 Kubernetes 集群的类型进行部署。有关详细信息，请参阅[抓取和公开指标](#5-抓取和公开指标)。 + +### PushProx 的工作原理 + +- 某些内部 Kubernetes 组件是通过部署在 Monitoring V2 中名为 **PushProx** 的代理来抓取的。通过 PushProx 向 Prometheus 公开指标的 Kubernetes 组件分别是 `kube-controller-manager`、`kube-scheduler`, `etcd` 和 `kube-proxy`。 + +- 对于每个 PushProx Exporter，我们在所有目标节点上都部署一个 PushProx 客户端。例如，将 PushProx 客户端部署到 kube-controller-manager 的所有 controlplane 节点、kube-etcd 的所有 etcd 节点上，和 kubelet 的所有节点上。 + +- 我们为每个 Exporter 部署了一个 PushProx 代理。导出指标的流程如下： + +1. PushProx 客户端与 PushProx 代理建立出站连接。 +1. 然后，客户端会轮询代理以获取进入代理的抓取请求。 +1. 当代理收到来自 Prometheus 的抓取请求时，客户端会将其视为轮询的结果。 +1. 客户端抓取内部组件。 +1. 内部组件通过将指标推回代理来响应。 + + +

使用 PushProx 导出指标的过程：
+ +![使用 PushProx 导出指标的过程](/img/pushprox-process.svg) + +### PrometheusRules + +PrometheusRule 用于定义指标或时间序列数据库查询触发告警的规则。规则是按时间间隔评估的。 + +- **记录规则**根据已收集的现有序列创建一个新的时间序列。它们常用于预先计算的复杂查询。 +- **告警规则**运行特定查询，如果查询评估为非零值，则从 Prometheus 触发告警。 + +### 告警路由 + +一旦 Prometheus 确定需要触发告警，就会将告警转发到 **Alertmanager**。 + +- 告警包含来自 PromQL 查询本身的标签，以及指定初始 PrometheusRule 时设置的其他标签和注释。 + +- 在接收任何告警之前，Alertmanager 会用配置中指定的**路由 (Route)** 和**接收器 (Receiver)** 来形成一个路由树，所有传入的告警都会在该路由树上进行评估。路由树的每个节点都可以根据附加到 Prometheus 告警的标签来指定要进行的其他分组、标签和过滤。路由树上的节点（通常是叶节点）还可以指定到达的告警需要发送到什么接收器，例如 Slack、PagerDuty、SMS 等。请注意，Alertmanager 首先向 **alertingDriver** 发送告警，然后 alertingDriver 再将告警发送或转发到正确的目标位置。 + +- 路由和接收器也通过 Alertmanager Secret 存储在 Kubernetes API 中。当 Secret 更新时，Alertmanager 也会自动更新。请注意，路由仅通过标签发生（而不是通过注释等）。 + +## 2. Prometheus 的工作原理 + +### 存储时间序列数据 + +收集 Exporter 的指标后，Prometheus 将时间序列存储在本地磁盘时间序列数据库中。Prometheus 可以选择与远程系统集成，但 `rancher-monitoring` 使用本地存储来存储时间序列数据库。 + +存储后，用户可以使用 PromQL（Prometheus 的查询语言）查询此 TSDB。 + +PromQL 查询可以通过以下两种方式进行可视化： + +1. 通过在 Prometheus 的 Graph UI 中提供查询，UI 会显示数据的简单图形视图。 +1. 通过创建包含 PromQL 查询和其他格式化指令的 Grafana 仪表板，这些指令用于标记轴、添加单位、更改颜色、使用替代可视化等。 + +### 为 Prometheus 定义规则 + +规则定义了 Prometheus 需要在常规 `evaluationInterval` 上执行的查询，从而执行某些操作，例如触发告警（告警规则）或根据 TSDB 中存在的其他查询（记录规则）预先计算查询。这些规则编码在 PrometheusRules 自定义资源中。创建或更新 PrometheusRule 自定义资源后，Prometheus Operator 会观察变化，并调用 Prometheus API 来定期同步 Prometheus 当前正在评估的规则集。 + +PrometheusRule 支持定义一个或多个 RuleGroup。每个 RuleGroup 由一组 Rule 对象组成，每个 Rule 对象均能表示告警或记录规则，并具有以下字段： + +- 新告警或记录的名称 +- 新告警或记录的 PromQL 表达式 +- 用于标记告警或记录的标签（例如集群名称或严重性） +- 对需要在告警通知上显示的其他重要信息进行编码的注释（例如摘要、描述、消息、Runbook URL 等）。记录规则不需要此字段。 + +在评估[规则](https://github.com/prometheus-operator/prometheus-operator/blob/main/Documentation/api-reference/api.md#rule)时，Prometheus 将执行配置的 PromQL 查询，添加其他标签（或注释 - 仅用于告警规则），并为规则执行所需的操作。例如，如果某个告警规则将 `team:front-end` 作为标签添加到配置的 PromQL 查询，该标签会尾附到触发的告警，这将允许 Alertmanager 将告警转发到正确的接收器。 + +### 告警和记录规则 + +Prometheus 不会维护告警是否处于 active 状态。它在每个评估间隔内重复触发告警，并根据 Alertmanager 对告警进行分组和过滤成有意义的通知。 + +`evaluation_interval` 常量定义了 Prometheus 根据时间序列数据库评估告警规则的频率。与 `scrape_interval` 类似，`evaluation_interval` 的默认值也是一分钟。 + +规则包含在一组规则文件中。规则文件包括告警规则和记录规则，但只有告警规则才会在评估后触发告警。 + +对于记录规则，Prometheus 会运行查询，然后将其存储为时间序列。如果需要存储非常昂贵或耗时的查询的结果，这种合成的时间序列则非常有用，因此你可以在后续更快地进行查询它们。 + +告警规则是更常用的。每当告警规则评估为正数时，Prometheus 都会触发告警。 + +在触发告警之前，Rule 文件会根据实际用例将标签和注释添加到告警中： + +- 标签用于标识告警的信息，并可能影响告警的路由。例如，如果在发送有关某个容器的告警时，你可以使用容器 ID 作为标签。 + +- 注释用于表示不影响告警路由位置的信息，例如 Runbook 或错误消息。 + +## 3. Alertmanager 的工作原理 + +Alertmanager 处理由 Prometheus server 等客户端应用发送的告警。它负责以下任务： + +- 删除重复数据，分组，并将告警路由到正确的接收器集成（例如电子邮件、PagerDuty 或 OpsGenie） + +- 静音和抑制告警 + +- 跟踪随时间触发的告警 + +- 发送告警的状态，即告警是否正在触发，或者是否已经解决 + +### 由 alertingDrivers 转发的告警 + +安装 alertingDriver 后会根据 alertingDriver 的配置创建一个 `Service`，可用作 Teams 或 SMS 的接收器 URL。接收器中的 URL 会指向 alertingDrivers。因此 Alertmanager 首先向 alertingDriver 发送告警，然后 alertingDriver 将告警转发或发送到正确的目的位置。 + +### 将告警路由到接收器 + +Alertmanager 负责协调告警的发送位置。它允许你根据标签对告警进行分组，并根据标签匹配情况来触发告警。一个最顶层路由会接受所有告警。然后，Alertmanager 会根据告警是否匹配下一个路由的条件，继续将告警路由到接收器。 + +虽然 Rancher UI 表单只允许编辑两层深的路由树，但你可以通过编辑 Alertmanager Secret 来配置更深的嵌套路由结构。 + +### 配置多个接收器 + +你可以编辑 Rancher UI 中的表单来设置一个接收器资源，其中包含 Alertmanager 将告警发送到你的通知系统所需的所有信息。 + +通过在 Alertmanager 或接收器配置中编辑自定义 YAML，你还可以将告警发送到多个通知系统。有关详细信息，请参阅[接收器配置](../../reference-guides/monitoring-v2-configuration/receivers.md#配置多个接收器)。 + +## 4. Monitoring V2 特定组件 + +Prometheus Operator 引入了一组[自定义资源定义](https://github.com/prometheus-operator/prometheus-operator#customresourcedefinitions)，允许用户通过在集群上创建和修改这些自定义资源来部署和管理 Prometheus 和 Alertmanager 实例。 + +Prometheus Operator 会根据 Rancher UI 中编辑的资源和配置选项的实时状态来自动更新 Prometheus 配置。 + +### 默认部署的资源 + +默认情况下，由 [kube-prometheus](https://github.com/prometheus-operator/kube-prometheus) 项目策划的一组资源会作为 Rancher Monitoring 安装的一部分部署到你的集群上，用来设置基本的 Monitoring/Alerting 堆栈。 + +你可以在 [`rancher-monitoring`](https://github.com/rancher/charts/tree/main/charts/rancher-monitoring) Helm Chart 中找到部署到你的集群以支持此解决方案的资源，该 chart 密切跟踪由 Prometheus 社区维护的上游 [kube-prometheus-stack](https://github.com/prometheus-community/helm-charts/tree/main/charts/kube-prometheus-stack) Helm Chart，并在 [CHANGELOG.md](https://github.com/rancher/charts/blob/main/charts/rancher-monitoring/CHANGELOG.md) 中跟踪变更。 + +### 默认 Exporter + +Monitoring V2 部署了三个默认 Exporter，它们为 Prometheus 提供额外的指标来存储： + +1. `node-exporter`：公开 Linux 主机的硬件和操作系统指标。有关 `node-exporter` 的更多信息，请参阅[上游文档](https://prometheus.io/docs/guides/node-exporter/)。 + +1. `windows-exporter`：公开 Windows 主机的硬件和操作系统指标（仅部署在 Windows 集群上）。有关 `windows-exporter` 的更多信息，请参阅[上游文档](https://github.com/prometheus-community/windows_exporter)。 + +1. `kube-state-metrics`：公开跟踪 Kubernetes API 中包含的资源状态的其他指标（例如，pod、工作负载等）。有关 `kube-state-metrics` 的更多信息，请参阅[上游文档](https://github.com/kubernetes/kube-state-metrics/tree/master/docs)。 + +ServiceMonitor 和 PodMonitor 将按照[此定义](#定义要抓取的指标)来抓取这些 Exporter。Prometheus 会存储这些指标，你可以通过 Prometheus 的 UI 或 Grafana 查询结果。 + +有关记录规则、告警规则和 Alertmanager 的更多信息，请参阅[架构](#1-架构概述)。 + +### Rancher UI 中公开的组件 + +安装 monitoring 应用后，你将能够在 Rancher UI 中编辑以下组件： + +| 组件 | 组件类型 | 编辑的目的和常见用例 | +|--------------|------------------------|---------------------------| +| ServiceMonitor | 自定义资源 | 设置 Kubernetes Service 来获取其自定义指标。自动更新 Prometheus 自定义资源中的抓取配置。 | +| PodMonitor | 自定义资源 | 设置 Kubernetes Pod 来获取其自定义指标。自动更新 Prometheus 自定义资源中的抓取配置。 | +| 接收器 | 配置块（Alertmanager 的一部分） | 修改将告警发送到什么位置的信息（例如，Slack、PagerDuty 等）以及发送告警的其他必要信息（例如，TL​​S 证书、代理 URL 等）。自动更新 Alertmanager 自定义资源。 | +| Route | 配置块（Alertmanager 的一部分） | 修改用于根据标签过滤、标记和分组告警的路由树，并将告警发送到所需的接收器。自动更新 Alertmanager 自定义资源。 | +| PrometheusRule | 自定义资源 | 定义其他查询，这些查询能触发告警或定义 Prometheus TSDB 中现有的物化视图。自动更新 Prometheus 自定义资源。 | + +### PushProx + +PushProx 允许 Prometheus 跨网络边界抓取指标，这样，用户就不用必须为 Kubernetes 集群中每个节点上的内部 Kubernetes 组件公开指标端口。 + +由于 Kubernetes 组件的指标通常暴露在集群中节点的主机网络上，PushProx 部署了一个客户端 DaemonSet，这些客户端位于每个节点的主机网络上，并与位于 Kubernetes API 上的单个代理建立出站连接。然后，你可以让 Prometheus 通过代理将抓取请求发送到每个客户端，这样，Prometheus 能从内部 Kubernetes 组件抓取指标，而不需要打开任何入站节点端口。 + +有关更多信息，请参阅[使用 PushProx 抓取指标](#使用-pushprox-抓取指标)。 + +## 5. 抓取和公开指标 + +### 定义要抓取的指标 + +ServiceMonitor 和 PodMonitor 定义了 Prometheus 要抓取的目标。[Prometheus 自定义资源](https://github.com/prometheus-operator/prometheus-operator/blob/main/Documentation/getting-started/design.md#prometheus)告诉 Prometheus 应该使用哪个 ServiceMonitor 或 PodMonitor 来确定从哪里抓取指标。 + +Prometheus Operator 观察 ServiceMonitor 和 PodMonitor。当它观察到二者被创建或更新时，它会调用 Prometheus API 来更新 Prometheus 自定义资源中的抓取配置，并使该配置与 ServiceMonitor 或 PodMonitor 中的抓取配置保持同步。此抓取配置告诉 Prometheus 从哪些端点抓取指标，以及如何标记这些端点的指标。 + +Prometheus 会根据 `scrape_interval`（默认为一分钟）来抓取定义在抓取配置中的所有指标。 + +抓取配置可以作为 Prometheus 自定义资源的一部分被查看，该资源在 Rancher UI 中公开。 + +### Prometheus Operator 如何设置指标抓取 + +Prometheus Deployment 或 StatefulSet 能抓取指标，而 Prometheus 的配置由 Prometheus 自定义资源控制。Prometheus Operator 会观察 Prometheus 和 Alertmanager 资源，当它们被创建时，Prometheus Operator 使用用户定义的配置，为 Prometheus 或 Alertmanager 创建一个 Deployment 或 StatefulSet。 + +如果 Prometheus Operator 观察到正在创建的 ServiceMonitor、PodMonitor 和 PrometheusRule，它就知道需要在 Prometheus 中更新抓取配置。首先，会通过更新 Prometheus 的 Deployment 或 StatefulSet 卷中的配置和规则文件来更新 Prometheus。然后，再调用 Prometheus API 来同步新配置，从而将 Prometheus Deployment 或 StatefulSet 修改到位。 + +### 如何公开 Kubernetes 组件指标 + +Prometheus 从称为 [exporter](https://prometheus.io/docs/instrumenting/exporters/) 的 deployment 中抓取指标，exporter 以 Prometheus 可以抓取的格式导出时间序列数据。在 Prometheus 中，时间序列由属于相同指标和相同标记维度集的时间戳值流组成。 + +### 使用 PushProx 抓取指标 + +某些内部 Kubernetes 组件是通过部署在 Monitoring V2 中名为 PushProx 的代理来抓取的。有关 PushProx 的详细信息，请参阅[此处](#pushprox-的工作原理)和上面的[架构](#1-架构概述)部分。 + +### 抓取指标 + +Prometheus 直接抓取以下 Kubernetes 组件： + +- kubelet\* +- ingress-nginx\*\* +- coreDns/kubeDns +- kube-api-server + +\* 你可以选择通过 `hardenedKubelet.enabled` 来使用 PushProx，但这不是默认设置。 + +\*\* RKE2 集群默认部署 ingress-nginx，并将其视为内部 Kubernetes 组件。 + + +### 基于 Kubernetes 发行版抓取指标 + +指标的抓取方式根据 Kubernetes 发行版而有所不同。有关术语的帮助，请参阅[此处](#名词解释)。详情见下表： + +
指标如何暴露给 Prometheus
+ +| Kubernetes 组件 | RKE2 | KubeADM | K3s | +|-----|-----|-----|-----|-----| +| kube-controller-manager | rke2ControllerManager.enabled | kubeAdmControllerManager.enabled | k3sServer.enabled | +| kube-scheduler | rke2Scheduler.enabled | kubeAdmScheduler.enabled | k3sServer.enabled | +| etcd | rke2Etcd.enabled | kubeAdmEtcd.enabled | 不可用 | +| kube-proxy | rke2Proxy.enabled | kubeAdmProxy.enabled | k3sServer.enabled | +| kubelet | 收集 kubelet 直接公开的指标 | 收集 kubelet 直接公开的指标 | 收集 kubelet 直接公开的指标 | +| ingress-nginx* | 收集 kubelet 直接公开的指标，由 rke2IngressNginx.enabled 公开 | 不可用 | 不可用 | +| coreDns/kubeDns | 收集 coreDns/kubeDns 直接公开的指标 | 收集 coreDns/kubeDns 直接公开的指标 | 收集 coreDns/kubeDns 直接公开的指标 | +| kube-api-server | 收集 kube-api-server 直接公开的指标 | 收集 kube-appi-server 直接公开的指标 | 收集 kube-api-server 直接公开的指标 | + +\* RKE2 集群默认部署 ingress-nginx，并将其视为内部 Kubernetes 组件。 + +### 名词解释 + +- **kube-scheduler**：内部 Kubernetes 组件，该组件使用 pod 规范中的信息来决定在哪个节点上运行 pod。 +- **kube-controller-manager**：负责节点管理（检测节点是否失败）、pod 复制，以及端点创建的内部 Kubernetes 组件。 +- **etcd**：Kubernetes 内部组件，它是 Kubernetes 用于持久存储所有集群信息的分布式键/值存储。 +- **kube-proxy**：内部 Kubernetes 组件，用于监控 API server 的 pod/service 更改以保持网络最新状态。 +- **kubelet**：内部 Kubernetes 组件，用于为 pod 监视节点上的 API server 并确保这些 pod 能运行。 +- **ingress-nginx**：用于 Kubernetes 的 Ingress controller，使用 NGINX 作为反向代理和负载均衡器。 +- **coreDns/kubeDns**：负责 DNS 的内部 Kubernetes 组件。 +- **kube-api-server**：负责为其他 master 组件公开 API 的主要内部 Kubernetes 组件。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/monitoring-and-alerting/monitoring-and-alerting.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/monitoring-and-alerting/monitoring-and-alerting.md new file mode 100644 index 00000000000..2881aa36090 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/monitoring-and-alerting/monitoring-and-alerting.md @@ -0,0 +1,104 @@ +--- +title: 监控和告警 +description: Prometheus 允许你查看来自不同 Rancher 和 Kubernetes 对象的指标。了解监控范围以及如何启用集群监控 +--- + + + + + +你可以使用 `rancher-monitoring` 应用，将业界领先的开源监控和告警解决方案快速部署到你的集群中。 + +在 Rancher v2.5 中引入的 `rancher-monitoring` operator 由 [Prometheus](https://prometheus.io/)、[Grafana](https://grafana.com/grafana/)、[Alertmanager](https://prometheus.io/docs/alerting/latest/alertmanager/)， [Prometheus Operator](https://github.com/prometheus-operator/prometheus-operator) 和 [Prometheus adapter](https://github.com/DirectXMan12/k8s-prometheus-adapter) 提供支持。 + +有关在 Rancher v2.2 到 v2.4 中可用的 V1 监控和告警的信息，请参阅 Rancher v2.0 到 v2.4 文档中的[集群监控](https://github.com/rancher/rancher-docs/tree/main/archived_docs/en/version-2.0-2.4/explanations/integrations-in-rancher/cluster-monitoring/cluster-monitoring.md)，[告警](https://github.com/rancher/rancher-docs/tree/main/archived_docs/en/version-2.0-2.4/explanations/integrations-in-rancher/cluster-alerts/cluster-alerts.md)，[通知](https://github.com/rancher/rancher-docs/tree/main/archived_docs/en/version-2.0-2.4/explanations/integrations-in-rancher/notifiers.md)和[工具](https://github.com/rancher/rancher-docs/tree/main/archived_docs/en/version-2.0-2.4/reference-guides/rancher-project-tools/rancher-project-tools.md)。 + +使用 `rancher-monitoring` 应用程序，你可以快速部署领先的开源监控和告警解决方案到你的集群上。 + +## 功能 + +Prometheus 支持查看 Rancher 和 Kubernetes 对象的指标。通过使用时间戳，Prometheus 能让你通过 Rancher UI 或 Grafana（与 Prometheus 一起部署的分析查看平台）以更容易阅读的图表和视觉形式来查询和查看这些指标。 + +通过查看 Prometheus 从集群的 controlplane、节点和 deployment 中抓取的数据，你可以随时了解集群中发生的所有事件。然后，你可以使用这些分析来更好地运行你的环境，例如在系统紧急情况发生之前阻止它们、制定维护策略，或恢复崩溃的服务器。 + +Monitoring 应用： + +- 监控集群节点、Kubernetes 组件和软件部署的状态和进程。 +- 根据 Prometheus 收集的指标定义告警。 +- 创建自定义 Grafana 仪表板。 +- 使用 Prometheus Alertmanager 通过电子邮件、Slack、PagerDuty 等配置告警通知。 +- 根据 Prometheus 收集的指标，将预先计算的、经常需要的，或计算成本高的表达式定义为新的时间序列。 +- 通过 Prometheus Adapter，将从 Prometheus 收集的指标公开给 Kubernetes Custom Metrics API，以便在 HPA 中使用。 + +有关监控组件如何协同工作的说明，请参阅 [Monitoring 工作原理](how-monitoring-works.md)。 + +## 默认组件和部署 + +### 内置仪表板 + +默认情况下，监控应用将 Grafana 仪表板（由 [kube-prometheus](https://github.com/prometheus-operator/kube-prometheus) 项目策划）部署到集群上。 + +它还部署一个 Alertmanager UI 和一个 Prometheus UI。有关这些工具的更多信息，请参见[内置仪表板](built-in-dashboards.md)。 + +### 默认指标 Exporter + +默认情况下，Rancher Monitoring 会部署 Exporter（例如 [node-exporter](https://github.com/prometheus/node_exporter) 和 [kube-state-metrics](https://github.com/kubernetes/kube-state-metrics)）。 + +这些默认 Exporter 会自动从 Kubernetes 集群的所有组件（包括工作负载）中抓取 CPU 和内存的指标。 + +### 默认告警 + +Monitoring 应用会默认部署一些告警。要查看默认告警，请转到 [Alertmanager UI](built-in-dashboards.md#alertmanager-ui) 并单击**展开所有组**。 + +### Rancher UI 中公开的组件 + +有关 Rancher UI 中公开的监控组件列表，以及编辑它们的常见用例，请参阅[本节](how-monitoring-works.md#rancher-ui-中公开的组件)。 + +## RBAC + +有关配置 monitoring 访问权限的信息，请参阅[此页面](rbac-for-monitoring.md)。 + +:::note + +Rancher 和 Project 的读取权限并不一定适用于监控相关资源. 查看 [monitoring-ui-view](rbac-for-monitoring.md#其他监控角色) 获取更多详细信息. + +::: + +## 指南 + +- [启用 monitoring](../../how-to-guides/advanced-user-guides/monitoring-alerting-guides/enable-monitoring.md) +- [卸载 monitoring](../../how-to-guides/advanced-user-guides/monitoring-alerting-guides/uninstall-monitoring.md) +- [Monitoring 工作负载](../../how-to-guides/advanced-user-guides/monitoring-alerting-guides/set-up-monitoring-for-workloads.md) +- [自定义 Grafana 仪表板](../../how-to-guides/advanced-user-guides/monitoring-alerting-guides/customize-grafana-dashboard.md) +- [持久化 Grafana 仪表板](../../how-to-guides/advanced-user-guides/monitoring-alerting-guides/create-persistent-grafana-dashboard.md) +- [调试高内存使用率](../../how-to-guides/advanced-user-guides/monitoring-alerting-guides/debug-high-memory-usage.md) + +## 配置 + +### 在 Rancher 中配置 Monitoring 资源 + +此处的配置参考假设你已经熟悉 monitoring 组件的协同工作方式。如需更多信息，请参阅 [monitoring 的工作原理](how-monitoring-works.md)。 + +- [ServiceMonitor 和 PodMonitor](../../reference-guides/monitoring-v2-configuration/servicemonitors-and-podmonitors.md) +- [接收器](../../reference-guides/monitoring-v2-configuration/receivers.md) +- [路由](../../reference-guides/monitoring-v2-configuration/routes.md) +- [PrometheusRule](../../how-to-guides/advanced-user-guides/monitoring-v2-configuration-guides/advanced-configuration/prometheusrules.md) +- [Prometheus](../../how-to-guides/advanced-user-guides/monitoring-v2-configuration-guides/advanced-configuration/prometheus.md) +- [Alertmanager](../../how-to-guides/advanced-user-guides/monitoring-v2-configuration-guides/advanced-configuration/alertmanager.md) + +### 配置 Helm Chart 选项 + +有关 `rancher-monitoring` Chart 选项的更多信息，包括设置资源限制和请求的选项，请参阅 [Helm Chart 选项](../../reference-guides/monitoring-v2-configuration/helm-chart-options.md)。 + +## Windows 集群支持 + +为了能够为 Windows 完全部署 Monitoring V2，你的所有 Windows 主机都必须至少具有 v0.1.0 的 [wins](https://github.com/rancher/wins) 版本。 + +有关如何在现有 Windows 主机上升级 wins 版本的更多信息，请参阅 [Windows 集群对 Monitoring V2 的支持](windows-support.md)。 + + +## 已知问题 + +有一个[已知问题](https://github.com/rancher/rancher/issues/28787#issuecomment-693611821)，即 K3s 集群需要的内存超过分配的默认内存。如果你在 K3s 集群上启用 Monitoring，将 `prometheus.prometheusSpec.resources.memory.limit` 设置为 2500 Mi，并将 `prometheus.prometheusSpec.resources.memory.request` 设置为 1750 Mi。 + +如需获取意见和建议，请参阅[调试高内存使用情况](../../how-to-guides/advanced-user-guides/monitoring-alerting-guides/debug-high-memory-usage.md)。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/monitoring-and-alerting/promql-expressions.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/monitoring-and-alerting/promql-expressions.md new file mode 100644 index 00000000000..006df34697c --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/monitoring-and-alerting/promql-expressions.md @@ -0,0 +1,365 @@ +--- +title: PromQL 表达式参考 +--- + +本文档中的 PromQL 表达式可用于配置告警。 + +关于查询 Prometheus 时间序列数据库的更多信息，请参阅 [Prometheus 官方文档](https://prometheus.io/docs/prometheus/latest/querying/basics/)。 + + +## 集群指标 + +### 集群 CPU 利用率 + +| Catalog | 表达式 | +| --- | --- | +| 详情 | `1 - (avg(irate(node_cpu_seconds_total{mode="idle"}[5m])) by (instance))` | +| 摘要 | `1 - (avg(irate(node_cpu_seconds_total{mode="idle"}[5m])))` | + +### 集群平均负载 + +| Catalog | 表达式 | +| --- | --- | +| 详情 |
load1`sum(node_load1) by (instance) / count(node_cpu_seconds_total{mode="system"}) by (instance)`
load5`sum(node_load5) by (instance) / count(node_cpu_seconds_total{mode="system"}) by (instance)`
load15`sum(node_load15) by (instance) / count(node_cpu_seconds_total{mode="system"}) by (instance)`
| +| 摘要 |
load1`sum(node_load1) by (instance) / count(node_cpu_seconds_total{mode="system"})`
load5`sum(node_load5) by (instance) / count(node_cpu_seconds_total{mode="system"})`
load15`sum(node_load15) by (instance) / count(node_cpu_seconds_total{mode="system"})`
| + +### 集群内存利用率 + +| Catalog | 表达式 | +| --- | --- | +| 详情 | `1 - sum(node_memory_MemAvailable_bytes) by (instance) / sum(node_memory_MemTotal_bytes) by (instance)` | +| 摘要 | `1 - sum(node_memory_MemAvailable_bytes) / sum(node_memory_MemTotal_bytes)` | + +### 集群磁盘利用率 + +| Catalog | 表达式 | +| --- | --- | +| 详情 | `(sum(node_filesystem_size_bytes{device!="rootfs"}) by (instance) - sum(node_filesystem_free_bytes{device!="rootfs"}) by (instance)) / sum(node_filesystem_size_bytes{device!="rootfs"}) by (instance)` | +| 摘要 | `(sum(node_filesystem_size_bytes{device!="rootfs"}) - sum(node_filesystem_free_bytes{device!="rootfs"})) / sum(node_filesystem_size_bytes{device!="rootfs"})` | + +### 集群磁盘 I/O + +| Catalog | 表达式 | +| --- | --- | +| 详情 |
read`sum(rate(node_disk_read_bytes_total[5m])) by (instance)`
written`sum(rate(node_disk_written_bytes_total[5m])) by (instance)`
| +| 摘要 |
read`sum(rate(node_disk_read_bytes_total[5m]))`
written`sum(rate(node_disk_written_bytes_total[5m]))`
| + +### 集群网络数据包 + +| Catalog | 表达式 | +| --- | --- | +| 详情 |
receive-droppedsum(rate(node_network_receive_drop_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*"}[5m])) by (instance)
receive-errssum(rate(node_network_receive_errs_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*"}[5m])) by (instance)
receive-packetssum(rate(node_network_receive_packets_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*"}[5m])) by (instance)
transmit-droppedsum(rate(node_network_transmit_drop_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*"}[5m])) by (instance)
transmit-errssum(rate(node_network_transmit_errs_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*"}[5m])) by (instance)
transmit-packetssum(rate(node_network_transmit_packets_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*"}[5m])) by (instance)
| +| 摘要 |
receive-droppedsum(rate(node_network_receive_drop_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*"}[5m]))
receive-errssum(rate(node_network_receive_errs_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*"}[5m]))
receive-packetssum(rate(node_network_receive_packets_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*"}[5m]))
transmit-droppedsum(rate(node_network_transmit_drop_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*"}[5m]))
transmit-errssum(rate(node_network_transmit_errs_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*"}[5m]))
transmit-packetssum(rate(node_network_transmit_packets_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*"}[5m]))
| + +### 集群网络 I/O + +| Catalog | 表达式 | +| --- | --- | +| 详情 |
receivesum(rate(node_network_receive_bytes_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*"}[5m])) by (instance)
transmitsum(rate(node_network_transmit_bytes_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*"}[5m])) by (instance)
| +| 摘要 |
receivesum(rate(node_network_receive_bytes_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*"}[5m]))
transmitsum(rate(node_network_transmit_bytes_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*"}[5m]))
| + +## 节点指标 + +### 节点 CPU 利用率 + +| Catalog | 表达式 | +| --- | --- | +| 详情 | `avg(irate(node_cpu_seconds_total{mode!="idle", instance=~"$instance"}[5m])) by (mode)` | +| 摘要 | `1 - (avg(irate(node_cpu_seconds_total{mode="idle", instance=~"$instance"}[5m])))` | + +### 节点平均负载 + +| Catalog | 表达式 | +| --- | --- | +| 详情 |
load1`sum(node_load1{instance=~"$instance"}) / count(node_cpu_seconds_total{mode="system",instance=~"$instance"})`
load5`sum(node_load5{instance=~"$instance"}) / count(node_cpu_seconds_total{mode="system",instance=~"$instance"})`
load15`sum(node_load15{instance=~"$instance"}) / count(node_cpu_seconds_total{mode="system",instance=~"$instance"})`
| +| 摘要 |
load1`sum(node_load1{instance=~"$instance"}) / count(node_cpu_seconds_total{mode="system",instance=~"$instance"})`
load5`sum(node_load5{instance=~"$instance"}) / count(node_cpu_seconds_total{mode="system",instance=~"$instance"})`
load15`sum(node_load15{instance=~"$instance"}) / count(node_cpu_seconds_total{mode="system",instance=~"$instance"})`
| + +### 节点内存利用率 + +| Catalog | 表达式 | +| --- | --- | +| 详情 | `1 - sum(node_memory_MemAvailable_bytes{instance=~"$instance"}) / sum(node_memory_MemTotal_bytes{instance=~"$instance"})` | +| 摘要 | `1 - sum(node_memory_MemAvailable_bytes{instance=~"$instance"}) / sum(node_memory_MemTotal_bytes{instance=~"$instance"}) ` | + +### 节点磁盘利用率 + +| Catalog | 表达式 | +| --- | --- | +| 详情 | `(sum(node_filesystem_size_bytes{device!="rootfs",instance=~"$instance"}) by (device) - sum(node_filesystem_free_bytes{device!="rootfs",instance=~"$instance"}) by (device)) / sum(node_filesystem_size_bytes{device!="rootfs",instance=~"$instance"}) by (device)` | +| 摘要 | `(sum(node_filesystem_size_bytes{device!="rootfs",instance=~"$instance"}) - sum(node_filesystem_free_bytes{device!="rootfs",instance=~"$instance"})) / sum(node_filesystem_size_bytes{device!="rootfs",instance=~"$instance"})` | + +### 节点磁盘 I/O + +| Catalog | 表达式 | +| --- | --- | +| 详情 |
read`sum(rate(node_disk_read_bytes_total{instance=~"$instance"}[5m]))`
written`sum(rate(node_disk_written_bytes_total{instance=~"$instance"}[5m]))`
| +| 摘要 |
read`sum(rate(node_disk_read_bytes_total{instance=~"$instance"}[5m]))`
written`sum(rate(node_disk_written_bytes_total{instance=~"$instance"}[5m]))`
| + +### 节点网络数据包 + +| Catalog | 表达式 | +| --- | --- | +| 详情 |
receive-droppedsum(rate(node_network_receive_drop_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*",instance=~"$instance"}[5m])) by (device)
receive-errssum(rate(node_network_receive_errs_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*",instance=~"$instance"}[5m])) by (device)
receive-packetssum(rate(node_network_receive_packets_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*",instance=~"$instance"}[5m])) by (device)
transmit-droppedsum(rate(node_network_transmit_drop_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*",instance=~"$instance"}[5m])) by (device)
transmit-errssum(rate(node_network_transmit_errs_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*",instance=~"$instance"}[5m])) by (device)
transmit-packetssum(rate(node_network_transmit_packets_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*",instance=~"$instance"}[5m])) by (device)
| +| 摘要 |
receive-droppedsum(rate(node_network_receive_drop_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*",instance=~"$instance"}[5m]))
receive-errssum(rate(node_network_receive_errs_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*",instance=~"$instance"}[5m]))
receive-packetssum(rate(node_network_receive_packets_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*",instance=~"$instance"}[5m]))
transmit-droppedsum(rate(node_network_transmit_drop_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*",instance=~"$instance"}[5m]))
transmit-errssum(rate(node_network_transmit_errs_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*",instance=~"$instance"}[5m]))
transmit-packetssum(rate(node_network_transmit_packets_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*",instance=~"$instance"}[5m]))
| + +### 节点网络 I/O + +| Catalog | 表达式 | +| --- | --- | +| 详情 |
receivesum(rate(node_network_receive_bytes_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*",instance=~"$instance"}[5m])) by (device)
transmitsum(rate(node_network_transmit_bytes_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*",instance=~"$instance"}[5m])) by (device)
| +| 摘要 |
receivesum(rate(node_network_receive_bytes_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*",instance=~"$instance"}[5m]))
transmitsum(rate(node_network_transmit_bytes_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*",instance=~"$instance"}[5m]))
| + +## ETCD 指标 + +### ETCD 有一个 Leader + +`max(etcd_server_has_leader)` + +### Leader 更换次数 + +`max(etcd_server_leader_changes_seen_total)` + +### 失败的 Proposal 数量 + +`sum(etcd_server_proposals_failed_total)` + +### GRPC 客户端流量 + +| Catalog | 表达式 | +| --- | --- | +| 详情 |
in`sum(rate(etcd_network_client_grpc_received_bytes_total[5m])) by (instance)`
out`sum(rate(etcd_network_client_grpc_sent_bytes_total[5m])) by (instance)`
| +| 摘要 |
in`sum(rate(etcd_network_client_grpc_received_bytes_total[5m]))`
out`sum(rate(etcd_network_client_grpc_sent_bytes_total[5m]))`
| + +### 对等流量 + +| Catalog | 表达式 | +| --- | --- | +| 详情 |
in`sum(rate(etcd_network_peer_received_bytes_total[5m])) by (instance)`
out`sum(rate(etcd_network_peer_sent_bytes_total[5m])) by (instance)`
| +| 摘要 |
in`sum(rate(etcd_network_peer_received_bytes_total[5m]))`
out`sum(rate(etcd_network_peer_sent_bytes_total[5m]))`
| + +### 数据库大小 + +| Catalog | 表达式 | +| --- | --- | +| 详情 | `sum(etcd_debugging_mvcc_db_total_size_in_bytes) by (instance)` | +| 摘要 | `sum(etcd_debugging_mvcc_db_total_size_in_bytes)` | + +### 活动流 + +| Catalog | 表达式 | +| --- | --- | +| 详情 |
lease-watch`sum(grpc_server_started_total{grpc_service="etcdserverpb.Lease",grpc_type="bidi_stream"}) by (instance) - sum(grpc_server_handled_total{grpc_service="etcdserverpb.Lease",grpc_type="bidi_stream"}) by (instance)`
watch`sum(grpc_server_started_total{grpc_service="etcdserverpb.Watch",grpc_type="bidi_stream"}) by (instance) - sum(grpc_server_handled_total{grpc_service="etcdserverpb.Watch",grpc_type="bidi_stream"}) by (instance)`
| +| 摘要 |
lease-watch`sum(grpc_server_started_total{grpc_service="etcdserverpb.Lease",grpc_type="bidi_stream"}) - sum(grpc_server_handled_total{grpc_service="etcdserverpb.Lease",grpc_type="bidi_stream"})`
watch`sum(grpc_server_started_total{grpc_service="etcdserverpb.Watch",grpc_type="bidi_stream"}) - sum(grpc_server_handled_total{grpc_service="etcdserverpb.Watch",grpc_type="bidi_stream"})`
| + +### Raft 方案 + +| Catalog | 表达式 | +| --- | --- | +| 详情 |
applied`sum(increase(etcd_server_proposals_applied_total[5m])) by (instance)`
committed`sum(increase(etcd_server_proposals_committed_total[5m])) by (instance)`
pending`sum(increase(etcd_server_proposals_pending[5m])) by (instance)`
failed`sum(increase(etcd_server_proposals_failed_total[5m])) by (instance)`
| +| 摘要 |
applied`sum(increase(etcd_server_proposals_applied_total[5m]))`
committed`sum(increase(etcd_server_proposals_committed_total[5m]))`
pending`sum(increase(etcd_server_proposals_pending[5m]))`
failed`sum(increase(etcd_server_proposals_failed_total[5m]))`
| + +### RPC 速率 + +| Catalog | 表达式 | +| --- | --- | +| 详情 |
total`sum(rate(grpc_server_started_total{grpc_type="unary"}[5m])) by (instance)`
fail`sum(rate(grpc_server_handled_total{grpc_type="unary",grpc_code!="OK"}[5m])) by (instance)`
| +| 摘要 |
total`sum(rate(grpc_server_started_total{grpc_type="unary"}[5m]))`
fail`sum(rate(grpc_server_handled_total{grpc_type="unary",grpc_code!="OK"}[5m]))`
| + +### 磁盘操作 + +| Catalog | 表达式 | +| --- | --- | +| 详情 |
commit-called-by-backend`sum(rate(etcd_disk_backend_commit_duration_seconds_sum[1m])) by (instance)`
fsync-called-by-wal`sum(rate(etcd_disk_wal_fsync_duration_seconds_sum[1m])) by (instance)`
| +| 摘要 |
commit-called-by-backend`sum(rate(etcd_disk_backend_commit_duration_seconds_sum[1m]))`
fsync-called-by-wal`sum(rate(etcd_disk_wal_fsync_duration_seconds_sum[1m]))`
| + +### 磁盘同步持续时间 + +| Catalog | 表达式 | +| --- | --- | +| 详情 |
wal`histogram_quantile(0.99, sum(rate(etcd_disk_wal_fsync_duration_seconds_bucket[5m])) by (instance, le))`
db`histogram_quantile(0.99, sum(rate(etcd_disk_backend_commit_duration_seconds_bucket[5m])) by (instance, le))`
| +| 摘要 |
wal`sum(histogram_quantile(0.99, sum(rate(etcd_disk_wal_fsync_duration_seconds_bucket[5m])) by (instance, le)))`
db`sum(histogram_quantile(0.99, sum(rate(etcd_disk_backend_commit_duration_seconds_bucket[5m])) by (instance, le)))`
| + +## Kubernetes 组件指标 + +### API Server 请求延迟 + +| Catalog | 表达式 | +| --- | --- | +| 详情 | `avg(apiserver_request_latencies_sum / apiserver_request_latencies_count) by (instance, verb) /1e+06` | +| 摘要 | `avg(apiserver_request_latencies_sum / apiserver_request_latencies_count) by (instance) /1e+06` | + +### API Server 请求速率 + +| Catalog | 表达式 | +| --- | --- | +| 详情 | `sum(rate(apiserver_request_count[5m])) by (instance, code)` | +| 摘要 | `sum(rate(apiserver_request_count[5m])) by (instance)` | + +### 调度失败的 Pod + +| Catalog | 表达式 | +| --- | --- | +| 详情 | `sum(kube_pod_status_scheduled{condition="false"})` | +| 摘要 | `sum(kube_pod_status_scheduled{condition="false"})` | + +### Controller Manager 队列深度 + +| Catalog | 表达式 | +| --- | --- | +| 详情 |
volumes`sum(volumes_depth) by instance`
deployment`sum(deployment_depth) by instance`
replicaset`sum(replicaset_depth) by instance`
service`sum(service_depth) by instance`
serviceaccount`sum(serviceaccount_depth) by instance`
endpoint`sum(endpoint_depth) by instance`
daemonset`sum(daemonset_depth) by instance`
statefulset`sum(statefulset_depth) by instance`
replicationmanager`sum(replicationmanager_depth) by instance`
| +| 摘要 |
volumes`sum(volumes_depth)`
deployment`sum(deployment_depth)`
replicaset`sum(replicaset_depth)`
service`sum(service_depth)`
serviceaccount`sum(serviceaccount_depth)`
endpoint`sum(endpoint_depth)`
daemonset`sum(daemonset_depth)`
statefulset`sum(statefulset_depth)`
replicationmanager`sum(replicationmanager_depth)`
| + +### 调度器 E2E 调度延迟 + +| Catalog | 表达式 | +| --- | --- | +| 详情 | `histogram_quantile(0.99, sum(scheduler_e2e_scheduling_latency_microseconds_bucket) by (le, instance)) / 1e+06` | +| 摘要 | `sum(histogram_quantile(0.99, sum(scheduler_e2e_scheduling_latency_microseconds_bucket) by (le, instance)) / 1e+06)` | + +### 调度器抢占尝试 + +| Catalog | 表达式 | +| --- | --- | +| 详情 | `sum(rate(scheduler_total_preemption_attempts[5m])) by (instance)` | +| 摘要 | `sum(rate(scheduler_total_preemption_attempts[5m]))` | + +### Ingress Controller 连接数 + +| Catalog | 表达式 | +| --- | --- | +| 详情 |
reading`sum(nginx_ingress_controller_nginx_process_connections{state="reading"}) by (instance)`
waiting`sum(nginx_ingress_controller_nginx_process_connections{state="waiting"}) by (instance)`
writing`sum(nginx_ingress_controller_nginx_process_connections{state="writing"}) by (instance)`
accepted`sum(ceil(increase(nginx_ingress_controller_nginx_process_connections_total{state="accepted"}[5m]))) by (instance)`
active`sum(ceil(increase(nginx_ingress_controller_nginx_process_connections_total{state="active"}[5m]))) by (instance)`
handled`sum(ceil(increase(nginx_ingress_controller_nginx_process_connections_total{state="handled"}[5m]))) by (instance)`
| +| 摘要 |
reading`sum(nginx_ingress_controller_nginx_process_connections{state="reading"})`
waiting`sum(nginx_ingress_controller_nginx_process_connections{state="waiting"})`
writing`sum(nginx_ingress_controller_nginx_process_connections{state="writing"})`
accepted`sum(ceil(increase(nginx_ingress_controller_nginx_process_connections_total{state="accepted"}[5m])))`
active`sum(ceil(increase(nginx_ingress_controller_nginx_process_connections_total{state="active"}[5m])))`
handled`sum(ceil(increase(nginx_ingress_controller_nginx_process_connections_total{state="handled"}[5m])))`
| + +### Ingress Controller 请求处理时间 + +| Catalog | 表达式 | +| --- | --- | +| 详情 | `topk(10, histogram_quantile(0.95,sum by (le, host, path)(rate(nginx_ingress_controller_request_duration_seconds_bucket{host!="_"}[5m]))))` | +| 摘要 | `topk(10, histogram_quantile(0.95,sum by (le, host)(rate(nginx_ingress_controller_request_duration_seconds_bucket{host!="_"}[5m]))))` | + +## Rancher Logging 指标 + + +### Fluentd 缓冲区队列速率 + +| Catalog | 表达式 | +| --- | --- | +| 详情 | `sum(rate(fluentd_output_status_buffer_queue_length[5m])) by (instance)` | +| 摘要 | `sum(rate(fluentd_output_status_buffer_queue_length[5m]))` | + +### Fluentd 输入速率 + +| Catalog | 表达式 | +| --- | --- | +| 详情 | `sum(rate(fluentd_input_status_num_records_total[5m])) by (instance)` | +| 摘要 | `sum(rate(fluentd_input_status_num_records_total[5m]))` | + +### Fluentd 输出错误率 + +| Catalog | 表达式 | +| --- | --- | +| 详情 | `sum(rate(fluentd_output_status_num_errors[5m])) by (type)` | +| 摘要 | `sum(rate(fluentd_output_status_num_errors[5m]))` | + +### Fluentd 输出速率 + +| Catalog | 表达式 | +| --- | --- | +| 详情 | `sum(rate(fluentd_output_status_num_records_total[5m])) by (instance)` | +| 摘要 | `sum(rate(fluentd_output_status_num_records_total[5m]))` | + +## 工作负载指标 + +### 工作负载 CPU 利用率 + +| Catalog | 表达式 | +| --- | --- | +| 详情 |
cfs throttled seconds`sum(rate(container_cpu_cfs_throttled_seconds_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m])) by (pod_name)`
user seconds`sum(rate(container_cpu_user_seconds_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m])) by (pod_name)`
system seconds`sum(rate(container_cpu_system_seconds_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m])) by (pod_name)`
usage seconds`sum(rate(container_cpu_usage_seconds_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m])) by (pod_name)`
| +| 摘要 |
cfs throttled seconds`sum(rate(container_cpu_cfs_throttled_seconds_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m]))`
user seconds`sum(rate(container_cpu_user_seconds_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m]))`
system seconds`sum(rate(container_cpu_system_seconds_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m]))`
usage seconds`sum(rate(container_cpu_usage_seconds_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m]))`
| + +### 工作负载内存利用率 + +| Catalog | 表达式 | +| --- | --- | +| 详情 | `sum(container_memory_working_set_bytes{namespace="$namespace",pod_name=~"$podName", container_name!=""}) by (pod_name)` | +| 摘要 | `sum(container_memory_working_set_bytes{namespace="$namespace",pod_name=~"$podName", container_name!=""})` | + +### 工作负载网络数据包 + +| Catalog | 表达式 | +| --- | --- | +| 详情 |
receive-packets`sum(rate(container_network_receive_packets_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m])) by (pod_name)`
receive-dropped`sum(rate(container_network_receive_packets_dropped_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m])) by (pod_name)`
receive-errors`sum(rate(container_network_receive_errors_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m])) by (pod_name)`
transmit-packets`sum(rate(container_network_transmit_packets_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m])) by (pod_name)`
transmit-dropped`sum(rate(container_network_transmit_packets_dropped_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m])) by (pod_name)`
transmit-errors`sum(rate(container_network_transmit_errors_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m])) by (pod_name)`
| +| 摘要 |
receive-packets`sum(rate(container_network_receive_packets_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m]))`
receive-dropped`sum(rate(container_network_receive_packets_dropped_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m]))`
receive-errors`sum(rate(container_network_receive_errors_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m]))`
transmit-packets`sum(rate(container_network_transmit_packets_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m]))`
transmit-dropped`sum(rate(container_network_transmit_packets_dropped_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m]))`
transmit-errors`sum(rate(container_network_transmit_errors_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m]))`
| + +### 工作负载网络 I/O + +| Catalog | 表达式 | +| --- | --- | +| 详情 |
receive`sum(rate(container_network_receive_bytes_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m])) by (pod_name)`
transmit`sum(rate(container_network_transmit_bytes_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m])) by (pod_name)`
| +| 摘要 |
receive`sum(rate(container_network_receive_bytes_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m]))`
transmit`sum(rate(container_network_transmit_bytes_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m]))`
| + +### 工作负载磁盘 I/O + +| Catalog | 表达式 | +| --- | --- | +| 详情 |
read`sum(rate(container_fs_reads_bytes_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m])) by (pod_name)`
write`sum(rate(container_fs_writes_bytes_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m])) by (pod_name)`
| +| 摘要 |
read`sum(rate(container_fs_reads_bytes_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m]))`
write`sum(rate(container_fs_writes_bytes_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m]))`
| + +## Pod 指标 + +### Pod CPU 利用率 + +| Catalog | 表达式 | +| --- | --- | +| 详情 |
cfs throttled seconds`sum(rate(container_cpu_cfs_throttled_seconds_total{container_name!="POD",namespace="$namespace",pod_name="$podName", container_name!=""}[5m])) by (container_name)`
usage seconds`sum(rate(container_cpu_usage_seconds_total{container_name!="POD",namespace="$namespace",pod_name="$podName", container_name!=""}[5m])) by (container_name)`
system seconds`sum(rate(container_cpu_system_seconds_total{container_name!="POD",namespace="$namespace",pod_name="$podName", container_name!=""}[5m])) by (container_name)`
user seconds`sum(rate(container_cpu_user_seconds_total{container_name!="POD",namespace="$namespace",pod_name="$podName", container_name!=""}[5m])) by (container_name)`
| +| 摘要 |
cfs throttled seconds`sum(rate(container_cpu_cfs_throttled_seconds_total{container_name!="POD",namespace="$namespace",pod_name="$podName", container_name!=""}[5m]))`
usage seconds`sum(rate(container_cpu_usage_seconds_total{container_name!="POD",namespace="$namespace",pod_name="$podName", container_name!=""}[5m]))`
system seconds`sum(rate(container_cpu_system_seconds_total{container_name!="POD",namespace="$namespace",pod_name="$podName", container_name!=""}[5m]))`
user seconds`sum(rate(container_cpu_user_seconds_total{container_name!="POD",namespace="$namespace",pod_name="$podName", container_name!=""}[5m]))`
| + +### Pod 内存利用率 + +| Catalog | 表达式 | +| --- | --- | +| 详情 | `sum(container_memory_working_set_bytes{container_name!="POD",namespace="$namespace",pod_name="$podName",container_name!=""}) by (container_name)` | +| 摘要 | `sum(container_memory_working_set_bytes{container_name!="POD",namespace="$namespace",pod_name="$podName",container_name!=""})` | + +### Pod 网络数据包 + +| Catalog | 表达式 | +| --- | --- | +| 详情 |
receive-packets`sum(rate(container_network_receive_packets_total{namespace="$namespace",pod_name="$podName",container_name!=""}[5m]))`
receive-dropped`sum(rate(container_network_receive_packets_dropped_total{namespace="$namespace",pod_name="$podName",container_name!=""}[5m]))`
receive-errors`sum(rate(container_network_receive_errors_total{namespace="$namespace",pod_name="$podName",container_name!=""}[5m]))`
transmit-packets`sum(rate(container_network_transmit_packets_total{namespace="$namespace",pod_name="$podName",container_name!=""}[5m]))`
transmit-dropped`sum(rate(container_network_transmit_packets_dropped_total{namespace="$namespace",pod_name="$podName",container_name!=""}[5m]))`
transmit-errors`sum(rate(container_network_transmit_errors_total{namespace="$namespace",pod_name="$podName",container_name!=""}[5m]))`
| +| 摘要 |
receive-packets`sum(rate(container_network_receive_packets_total{namespace="$namespace",pod_name="$podName",container_name!=""}[5m]))`
receive-dropped`sum(rate(container_network_receive_packets_dropped_total{namespace="$namespace",pod_name="$podName",container_name!=""}[5m]))`
receive-errors`sum(rate(container_network_receive_errors_total{namespace="$namespace",pod_name="$podName",container_name!=""}[5m]))`
transmit-packets`sum(rate(container_network_transmit_packets_total{namespace="$namespace",pod_name="$podName",container_name!=""}[5m]))`
transmit-dropped`sum(rate(container_network_transmit_packets_dropped_total{namespace="$namespace",pod_name="$podName",container_name!=""}[5m]))`
transmit-errors`sum(rate(container_network_transmit_errors_total{namespace="$namespace",pod_name="$podName",container_name!=""}[5m]))`
| + +### Pod 网络 I/O + +| Catalog | 表达式 | +| --- | --- | +| 详情 |
receive`sum(rate(container_network_receive_bytes_total{namespace="$namespace",pod_name="$podName",container_name!=""}[5m]))`
transmit`sum(rate(container_network_transmit_bytes_total{namespace="$namespace",pod_name="$podName",container_name!=""}[5m]))`
| +| 摘要 |
receive`sum(rate(container_network_receive_bytes_total{namespace="$namespace",pod_name="$podName",container_name!=""}[5m]))`
transmit`sum(rate(container_network_transmit_bytes_total{namespace="$namespace",pod_name="$podName",container_name!=""}[5m]))`
| + +### Pod 磁盘 I/O + +| Catalog | 表达式 | +| --- | --- | +| 详情 |
read`sum(rate(container_fs_reads_bytes_total{namespace="$namespace",pod_name="$podName",container_name!=""}[5m])) by (container_name)`
write`sum(rate(container_fs_writes_bytes_total{namespace="$namespace",pod_name="$podName",container_name!=""}[5m])) by (container_name)`
| +| 摘要 |
read`sum(rate(container_fs_reads_bytes_total{namespace="$namespace",pod_name="$podName",container_name!=""}[5m]))`
write`sum(rate(container_fs_writes_bytes_total{namespace="$namespace",pod_name="$podName",container_name!=""}[5m]))`
| + +## 容器指标 + +### 容器 CPU 利用率 + +| Catalog | 表达式 | +| --- | --- | +| cfs throttled seconds | `sum(rate(container_cpu_cfs_throttled_seconds_total{namespace="$namespace",pod_name="$podName",container_name="$containerName"}[5m]))` | +| usage seconds | `sum(rate(container_cpu_usage_seconds_total{namespace="$namespace",pod_name="$podName",container_name="$containerName"}[5m]))` | +| system seconds | `sum(rate(container_cpu_system_seconds_total{namespace="$namespace",pod_name="$podName",container_name="$containerName"}[5m]))` | +| user seconds | `sum(rate(container_cpu_user_seconds_total{namespace="$namespace",pod_name="$podName",container_name="$containerName"}[5m]))` | + +### 容器内存利用率 + +`sum(container_memory_working_set_bytes{namespace="$namespace",pod_name="$podName",container_name="$containerName"})` + +### 容器磁盘 I/O + +| Catalog | 表达式 | +| --- | --- | +| read | `sum(rate(container_fs_reads_bytes_total{namespace="$namespace",pod_name="$podName",container_name="$containerName"}[5m]))` | +| write | `sum(rate(container_fs_writes_bytes_total{namespace="$namespace",pod_name="$podName",container_name="$containerName"}[5m]))` | diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/monitoring-and-alerting/rbac-for-monitoring.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/monitoring-and-alerting/rbac-for-monitoring.md new file mode 100644 index 00000000000..978ff27d4f3 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/monitoring-and-alerting/rbac-for-monitoring.md @@ -0,0 +1,251 @@ +--- +title: RBAC +--- +本节描述了 RBAC 在 Rancher Monitoring 中的作用。 + + +## 集群管理员 + +默认情况下，只有具有 cluster-admin `ClusterRole` 的用户才能： + +- 将 `rancher-monitoring` 应用安装到集群上，并在 Chart 部署上执行所有其他相关配置。 + - 例如，是否创建了默认仪表板，要将哪些 Exporter 部署到集群上以收集指标等。 +- 通过 Prometheus CR 在集群中创建/修改/删除 Prometheus deployment。 +- 通过 Alertmanager CR 在集群中创建/修改/删除 Alertmanager deployment。 +- 通过在命名空间中创建 ConfigMap 来保留新的 Grafana 仪表板或数据源。 +- 通过 `cattle-monitoring-system` 命名空间中的 Secret 将某些 Prometheus 指标暴露给 HPA 的 K8s Custom Metrics API。 + +## 具有基于 Kubernetes ClusterRole 权限的用户 + +`rancher-monitoring` Chart 安装了以下三个 `ClusterRole`。默认情况下，它们会聚合到相应的 K8s `ClusterRole` 中： + +| ClusterRole | 聚合到默认的 K8s ClusterRole | +| ------------------------------| ---------------------------| +| `monitoring-admin` | `admin` | +| `monitoring-edit` | `edit` | +| `monitoring-view` | `view ` | + +这些 `ClusterRole` 根据可执行的操作提供对 Monitoring CRD 的不同访问级别： + +| CRD (monitoring.coreos.com) | Admin | Edit | View | +| ------------------------------| ---------------------------| ---------------------------| ---------------------------| +|
  • `prometheuses`
  • `alertmanagers`
| Get, List, Watch | Get, List, Watch | Get, List, Watch | +|
  • `servicemonitors`
  • `podmonitors`
  • `prometheusrules`
| * | * | Get, List, Watch | + +在较高级别上，默认情况下会分配以下权限。 + +### 具有 Kubernetes 管理员/编辑权限的用户 + +只有具有 cluster-admin、admin 或 edit 的 `ClusterRole` 可以： + +- 通过 ServiceMonitor 和 PodMonitor CR 修改 Prometheus deployment 的抓取配置。 +- 通过 PrometheusRules CR 修改 Prometheus deployment 的告警/记录规则。 + +### 具有 Kubernetes 查看权限的用户 + +只有具有 Kubernetes `ClusterRole` 的用户可以： + +- 查看集群内部署的 Prometheuses 的配置。 +- 查看集群内部署的 Alertmanagers 的配置。 +- 通过 ServiceMonitor 和 PodMonitor CR 查看 Prometheus deployment 的抓取配置。 +- 通过 PrometheusRules CR 查看 Prometheus deployment 的告警/记录规则。 + +### 其他监控角色 + +Monitoring 还会创建其他 `Role`，这些角色默认情况下不会分配给用户，而是在集群中创建。你可以部署引用角色的 `RoleBinding` 来将角色绑定到命名空间。要使用 `kubectl` 而不是通过 Rancher 来定义 `RoleBinding`，请单击[此处](#使用-kubectl-分配-role-和-clusterrole)。 + +管理员应使用这些角色为用户提供更细粒度的访问权限： + +| 角色 | 用途 | +| ------------------------------| ---------------------------| +| monitoring-config-admin | 允许管理员为用户分配角色，以便查看/编辑 cattle-monitoring-system 命名空间中的 Secret 和 ConfigMap。修改此命名空间中的 Secret/ConfigMap 可以允许用户更改集群的 Alertmanager 配置、Prometheus Adapter 配置、其他 Grafana 数据源、TLS 密钥等。 | +| monitoring-config-edit | 允许管理员为用户分配角色，以便查看/编辑 cattle-monitoring-system 命名空间中的 Secret 和 ConfigMap。修改此命名空间中的 Secret/ConfigMap 可以允许用户更改集群的 Alertmanager 配置、Prometheus Adapter 配置、其他 Grafana 数据源、TLS 密钥等。 | +| monitoring-config-view | 允许管理员为用户分配角色，以便查看 cattle-monitoring-system 命名空间中的 Secret 和 ConfigMap。查看此命名空间中的 Secret/ConfigMap 可以允许用户观察集群的 Alertmanager 配置、Prometheus Adapter 配置、其他 Grafana 数据源、TLS 密钥等。 | +| monitoring-dashboard-admin | 允许管理员为用户分配角色，以便查看/编辑 cattle-dashboards 命名空间中的 ConfigMap。此命名空间中的 ConfigMap 将对应于持久化到集群上的 Grafana 仪表板。 | +| monitoring-dashboard-edit | 允许管理员为用户分配角色，以便查看/编辑 cattle-dashboards 命名空间中的 ConfigMap。此命名空间中的 ConfigMap 将对应于持久化到集群上的 Grafana 仪表板。 | +| monitoring-dashboard-view | 允许管理员为用户分配角色，以便查看 cattle-dashboards 命名空间中的 ConfigMap。此命名空间中的 ConfigMap 将对应于持久化到集群上的 Grafana 仪表板。 | + + +### 通过自定义角色分配监控角色 + +管理员可以在 Rancher UI 中分配自定义角色以管理、编辑和查看监控。这些“角色”是在安装 Monitoring 应用程序时默认创建的。此外，这些角色也会被部署到相应的 Kubernetes 角色：admin、edit 和 view `ClusterRoles`。 + +:::note 重要提示： + +将用户添加到集群时，UI 不会提供 `monitoring-admin`、`monitoring-edit` 和 `monitoring-view` 选项。这些监控角色只能通过手动创建自定义角色来分配，该自定义角色继承 Project Owner 和 Project Monitoring View 角色。 + +::: + +1. 创建自定义角色： + + 1.1 单击 **☰ > Users & Authentication > Roles**。 + + 1.2 选择适当的选项卡，例如 **Cluster** 角色。然后单击 **Create Cluster Role**。 + + 1.3 在 **Name** 字段中，创建自定义角色，例如 `View Monitoring`、`Edit Monitoring` 或 `Admin Monitoring`。 + + 1.4 单击 **Inherit From > Add Resource**，然后从下拉列表中选择所需的 Kubernetes 角色。 + + 1.5 单击 **Create**。 + + +2. 将自定义角色分配给新用户： + + 2.1 单击 **☰ > Cluster Management > Cluster Explore > Cluster > Cluster Members > Add**。 + + 2.2 从显示的 **Select Member** 中搜索你的新用户名。 + + 2.3 将 **Cluster Permissions** 中的新自定义角色分配给新用户。 + + 2.4 单击 **Create**。 + +**结果**：新用户现在应该能够看到 monitoring 工具。 + +### 其他监控集群角色 + +Monitoring 还会创建其他 `ClusterRole`，这些角色默认情况下不会分配给用户，而是在集群中创建。默认情况下，这些角色不会聚合，但你可以部署引用角色的 `RoleBinding` 或 `ClusterRoleBinding` 来将角色绑定到命名空间。要使用 `kubectl` 而不是通过 Rancher 来定义 `RoleBinding`，请单击[此处](#使用-kubectl-分配-role-和-clusterrole)。 + +| 角色 | 用途 | +| ------------------------------| ---------------------------| +| monitoring-ui-view | _自 Monitoring v2 14.5.100+ 起可用_ 此 ClusterRole 允许用户在 Rancher UI 中查看指定集群的指标图。这是通过授予对外部监控 UI 的只读访问权限来实现的。具有此角色的用户有权限列出 Prometheus、Alertmanager 和 Grafana 端点，并通过 Rancher 代理向 Prometheus、Grafana 和 Alertmanager UI 发出 GET 请求。 | + +### 使用 kubectl 分配 Role 和 ClusterRole + +#### 使用 `kubectl create` + +一种方法是使用 `kubectl create clusterrolebinding` 或 `kubectl create rolebinding` 来分配一个 `Role` 或 `ClusterRole`。如以下示例所示： + +- 分配给特定用户： + + + + ```plain + kubectl create clusterrolebinding my-binding --clusterrole=monitoring-ui-view --user=u-l4npx + ``` + + + + + ```plain + kubectl create rolebinding my-binding --clusterrole=monitoring-ui-view --user=u-l4npx --namespace=my-namespace + ``` + + + +- 分配给所有经过身份认证的用户： + + + + ```plain + kubectl create clusterrolebinding my-binding --clusterrole=monitoring-ui-view --group=system:authenticated + ``` + + + + + ```plain + kubectl create rolebinding my-binding --clusterrole=monitoring-ui-view --group=system:authenticated --namespace=my-namespace + ``` + + + + +#### 使用 YAML 文件 + +另一种方法是在你创建的 YAML 文件中定义绑定。你必须先使用 YAML 文件配置 `RoleBinding` 或 `ClusterRoleBinding`。然后，通过运行 `kubectl apply` 命令来应用配置更改。 + +- **Role**：以下 YAML 文件示例可帮助你在 Kubernetes 中配置 `RoleBinding`。你需要在下面填写名称。 + +:::note + +名称区分大小写。 + +::: + +```yaml +# monitoring-config-view-role-binding.yaml +apiVersion: rbac.authorization.k8s.io/v1 +kind: RoleBinding +metadata: + name: monitoring-config-view + namespace: cattle-monitoring-system +roleRef: + kind: Role + name: monitoring-config-view + apiGroup: rbac.authorization.k8s.io +subjects: +- kind: User + name: u-b4qkhsnliz # this can be found via `kubectl get users -A` + apiGroup: rbac.authorization.k8s.io +``` + +- **kubectl**：以下 `kubectl` 示例命令用于应用 YAML 文件中创建的绑定。请记住相应填写你的 YAML 文件名。 + ```plain + kubectl apply -f monitoring-config-view-role-binding.yaml + ``` + +## 具有 Rancher 权限的用户 + +Rancher 部署的默认角色（即 cluster-owner、cluster-member、project-owner、project-member）、Kubernetes 默认角色，以及 rancher-monitoring Chart 部署的角色之间的关系如下： + +
默认 Rancher 权限和对应的 Kubernetes ClusterRole
+ +| Rancher 角色 | Kubernetes 角色 | Monitoring ClusterRole/Role | ClusterRoleBinding/RoleBinding | +| --------- | --------- | --------- | --------- | +| cluster-owner | cluster-admin | N/A | ClusterRoleBinding | +| cluster-member | admin | monitoring-admin | ClusterRoleBinding | +| project-owner | admin | monitoring-admin | 项目命名空间中的 RoleBinding | +| project-member | edit | monitoring-edit | 项目命名空间中的 RoleBinding | + +除这些默认角色之外，你还可以将以下的其他 Rancher 项目角色应用于集群成员，以提供对 Monitoring 的其他访问。这些 Rancher 角色将与 Monitoring Chart 部署的 ClusterRole 相关联： + +
非默认的 Rancher 权限和对应的 Kubernetes ClusterRole
+ +| Rancher 角色 | Kubernetes ClusterRole | 可用 Rancher 版本 | 可用 Monitoring V2 版本 | +|--------------------------|-------------------------------|-------|------| +| 查看 Monitoring\* | [monitoring-ui-view](#具有-rancher-权限的用户) | 2.4.8+ | 9.4.204+ | + +\* 如果某个用户绑定了 Rancher 的 **View Monitoring** 角色，该用户只有在有 UI 链接时才有权访问外部 Monitoring UI。要访问 Monitoring Pane 以获取这些链接，用户必须是至少一个项目的项目成员。 + +### 2.5.x 中的差异 + +在 Rancher 2.5.x 中，分配了 project-member 或 project-owner 角色的用户将无法访问 Prometheus 或 Grafana，因为我们仅在集群级别创建 Grafana 或 Prometheus。 + +此外，虽然 project-owner 仍然只能添加默认在项目命名空间内抓取资源的 ServiceMonitor/PodMonitor，但 PrometheusRule 并不局限于单个命名空间/项目。因此，即使 project-owner 无法查看/编辑/删除在项目命名空间之外创建的任何规则，project-owner 在其项目命名空间内创建的任何告警规则或记录规则都将应用于整个集群。 + +### 分配其他访问权限 + +如果 cluster-admin 想要为不具有 rancher-monitoring chart 角色的用户提供 admin/edit 访问权限，则存在下表的潜在影响： + +| CRD (monitoring.coreos.com) | 是否会在命名空间/项目之外造成影响 | 影响 | +|----------------------------| ------| ----------------------------| +| `prometheuses` | 是。该资源可以从整个集群中的任何目标中抓取指标（除非 Operator 本身进行了额外的配置）。 | 用户将能够定义应在集群中创建的新集群级 Prometheus deployment 的配置。 | +| `alertmanagers` | 否 | 用户将能够定义应在集群中创建的新集群级 Alertmanager deployment 的配置。注意：如果你只想允许用户配置路由和接收器等设置，你应该只提供对 Alertmanager Config Secret 的访问权限。 | +|
  • `servicemonitors`
  • `podmonitors`
| 否（默认）。可以通过 Prometheus CR 上的 `ignoreNamespaceSelectors` 进行配置。 | 用户将能够通过 Prometheus，在他们被授予此权限的命名空间内的 Service/Pod 暴露的端点上设置抓取。 | +| `prometheusrules` | 是。PrometheusRules 是集群范围的。 | 用户将能够根据在整个集群中收集的任何系列，在 Prometheus 上定义告警或记录规则。 | + +| K8s 资源 | 命名空间 | 是否会在命名空间/项目之外造成影响 | 影响 | +|----------------------------| ------| ------| ----------------------------| +|
  • `secrets`
  • `configmaps`
| `cattle-monitoring-system` | 是。此命名空间中的 Config 和 Secret 会影响整个监控/告警流水线。 | 用户将能够创建或编辑 Secret/ ConfigMap，例如 Alertmanager Config、Prometheus Adapter 配置、TLS 密文、其他 Grafana 数据源等。这会对所有集群监控/告警产生广泛影响。 | +|
  • `secrets`
  • `configmaps`
| `cattle-dashboards` | 是。此命名空间中的 Config 和 Secret 可以创建仪表板，对在集群级别收集的所有指标进行查询。 | 用户将能够创建仅保留新 Grafana 仪表板的 Secret/ConfigMap。 | + +## Grafana 的 RBAC + +对于经过 Kubernetes 认证并可以访问 Rancher Monitoring Chart 部署的 Grafana 服务的任何用户，Rancher 允许他们通过 Rancher Dashboard UI 访问 Grafana。默认情况下，所有能够访问 Grafana 的用户都被赋予 [Viewer](https://grafana.com/docs/grafana/latest/permissions/organization_roles/#viewer-role) 角色，能查看 Rancher 部署的任何默认仪表板。 + +但是，如果有需要的话，用户可以选择以 [Admin](https://grafana.com/docs/grafana/latest/permissions/organization_roles/#admin-role) 身份登录 Grafana。Grafana 实例的默认 Admin 用户名和密码是 `admin`/`prom-operator`，但你也可以在部署或升级 Chart 时替换凭证。 + +要查看 Grafana UI，请安装 `rancher-monitoring`。然后： + +1. 在左上角，单击 **☰ > 集群管理**。 +1. 在**集群**页面上，转到要可视化的集群，然后单击 **Explore**。 +1. 在左侧导航栏中，单击**监控**。 +1. 点击 **Grafana**。 + +
Grafana 中的集群计算资源仪表板
+ +![Grafana 中的集群计算资源仪表板](/img/cluster-compute-resources-dashboard.png) + +
Grafana 中的默认仪表板
+ +![Grafana 中的默认仪表板](/img/grafana-default-dashboard.png) \ No newline at end of file diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/monitoring-and-alerting/windows-support.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/monitoring-and-alerting/windows-support.md new file mode 100644 index 00000000000..c46c0cc8f76 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/monitoring-and-alerting/windows-support.md @@ -0,0 +1,41 @@ +--- +title: Monitoring V2 的 Windows 集群支持 +--- + +_从 v2.5.8 起可用_ + +从 Monitoring V2 14.5.100（Rancher 2.5.8 的默认版本）开始，Monitoring V2 可以部署在 Windows 集群上，并将使用 [prometheus-community/windows_exporter](https://github.com/prometheus-community/windows_exporter)（旧名是 `wmi_exporter`）来抓取 Windows 节点的指标。 + +## 集群要求 + +Monitoring V2 for Windows 只能从最低是 `wins` v0.1.0 的 Windows 主机中抓取指标。要完全部署 Monitoring V2 for Windows，你的所有主机都必须满足此要求。 + +### 将现有集群升级到 wins v0.1.0 + +如果集群是在 Rancher 2.5.8 之前配置的（即使当前 Rancher 版本是 2.5.8），你将无法成功部署 Monitoring V2 for Windows，除非你将每台主机的 wins 版本升级到 v0.1.0 或以上版本。 + +为了方便此次升级，Rancher 2.5.8 发布了一个全新的 Helm Chart，名为 `rancher-wins-upgrader`。 + +1. 使用以下覆盖部署 `rancher-wins-upgrader`： + + ```yaml + # 通过先前已列入白名单的进程路径 + # 来引导 win-upgrader 安装，这是因为正常安装路径 + # c:\etc\rancher\wins\wins-upgrade.exe 通常不会被列入白名单。 + # 因此，我们使用 Monitoring V1 之前所用的 + # 已列入白名单的进程路径。 + masquerade: + enabled: true + as: c:\\etc\wmi-exporter\wmi-exporter.exe + ``` + +2. 成功升级所有主机后，请再次使用默认值部署 Helm Chart，以避免与以下设置发生冲突： + + ```yaml + masquerade: + enabled: false + ``` + +**结果**：主机已准备好安装 Monitoring V2。你可以选择卸载 `rancher-wins-upgrader` Chart，或将其保留在集群中以方便将来升级。 + +有关如何使用它的更多信息，请参阅 Chart 的 [README.md](https://github.com/rancher/wins/blob/master/charts/rancher-wins-upgrader/README.md)。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/neuvector.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/neuvector.md new file mode 100644 index 00000000000..f14ae63cbb8 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/neuvector.md @@ -0,0 +1,199 @@ +--- +title: NeuVector 集成 +--- + +## Rancher 中的 NeuVector 集成 + +[NeuVector 5.x](https://open-docs.neuvector.com/) 是一个开源的，以容器为中心的安全应用程序，Rancher 已集成 NeuVector。NeuVector 在运行时为关键应用程序和数据提供实时的合规、可见和保护功能。NeuVector 提供具有 CIS Benchmark 和漏洞扫描的防火墙、容器进程/文件系统监控和安全审计。有关 Rancher 安全性的更多信息，请参阅[安全文档](../reference-guides/rancher-security/rancher-security.md)。 + +NeuVector 可以通过 Helm Chart 启用。你可以在 **Apps** 或 Rancher UI 中的 **Cluster Tools** 中安装该 Chart。安装 Helm Chart 后，用户可以轻松地[在 Rancher 中部署和管理 NeuVector 集群](https://open-docs.neuvector.com/deploying/rancher#deploy-and-manage-neuvector-through-rancher-apps-marketplace)。 + +## 使用 Rancher 安装 NeuVector + +Harvester Helm Chart 用于管理 Rancher 中 NeuVector UI 的访问，用户可以在 Rancher 中直接跳转，然后部署和管理 NeuVector 集群。 + +**通过 "Apps" 导航并安装 NeuVector Chart**： + +1. 点击 **☰ > 集群管理**。 +1. 在 Clusters 页面上，转到要部署 NeuVector 的集群，然后单击 **Explore**。 +1. 转到 **Apps > Charts**，然后从 Chart 仓库中安装 **NeuVector**。 +1. 不同的集群类型需要不同的容器运行时。配置 Helm Chart 值时，转到**容器运行时**，然后根据集群类型选择运行时。最后，再次单击**安装**。 + +以下是一些例子： + +- RKE1：`docker` +- K3s 和 RKE2：`k3scontainerd` +- AKS：`containerd` 适用于 v1.19 及更高版本 +- EKS：`docker` 适用于 v1.22 及以下版本；`containerd` 适用于 v1.23 及更高版本 +- GKE：`containerd`（请参阅 [Google 文档](https://cloud.google.com/kubernetes-engine/docs/concepts/using-containerd)了解更多信息） + + :::note + + 在安装过程中一次只能选择一个容器运行时引擎。 + + ::: + +**通过集群工具导航并安装 NeuVector Chart**： + +1. 点击 **☰ > 集群管理**。 +1. 在 Clusters 页面上，转到要部署 NeuVector 的集群，然后单击 **Explore**。 +1. 点击左侧导航栏底部的**集群工具**。 +1. 按照上面的步骤 4 相应地选择你的容器运行时，然后再次单击**安装**。 + +## 从 Rancher UI 访问 NeuVector + +1. 导航到安装了 NeuVector 的集群的 Cluster Explorer。在左侧导航栏中，单击 **NeuVector**。 +1. 单击外部链接以转到 NeuVector UI。选择链接后，用户必须接受`最终用户许可协议`才能访问 NeuVector UI。 + +## 从 Rancher UI 卸载 NeuVector + +**通过 "Apps" 卸载**： + +1. 点击 **☰ > 集群管理**。 +1. 在 **Apps** 下，点击 **Installed Apps**。 +1. 在 `cattle-neuvector-system` 下，选择 NeuVector 应用程序（如果需要，还可以选择相关的 CRD），然后单击**删除**。 + +**通过集群工具卸载**： + +1. 点击 **☰ > 集群管理**。 +1. 单击屏幕左下角的**集群工具**，然后单击 NeuVector Chart 下方的垃圾桶图标。如果需要，选择`删除与此应用关联的 CRD`，然后单击**删除**。 + +## GitHub 仓库 + +NeuVector 项目在[这里](https://github.com/neuvector/neuvector)。 + +## 文档 + +NeuVector 文档在[这里](https://open-docs.neuvector.com/)。 + +## 架构 + +NeuVector 安全解决方案包含四种类型的安全容器，分别是 Controller、Enforcer、Manager 和 Scanner。它还提供了一个称为 All-in-One 的特殊容器（主要用于 Docker 原生部署），能将 Controller、Enforcer 和 Manager 功能组合在一个容器中。此外，还有一个 Updater，运行该程序时会更新 CVE 数据库。 + +- **Controller**：管理 NeuVector Enforcer 容器；为管理控制台提供 REST API。 +- **Enforcer**：执行安全策略。 +- **Manager**：提供一个 web-UI 和 CLI 控制台来管理 NeuVector 平台。 +- **All-in-One**：包括 Controller、Enforcer 和 Manager。 +- **Scanner**：对镜像、容器和节点执行漏洞和合规性扫描。 +- **Updater**：更新 Neuvector 的 CVE 数据库（运行的时候）；重新部署 scanner pod。 + +
**NeuVector 安全容器：**
+ +![NeuVector 安全容器](/img/neuvector-security-containers.png) + +
**NeuVector 架构：**
+ +![NeuVector 架构](/img/neuvector-architecture.png) + +要了解有关 NeuVector 架构的更多信息，请参阅[此处](https://open-docs.neuvector.com/basics/overview#architecture)。 + +## CPU 和内存分配 + +以下是默认 NeuVector Chart 安装部署的最低计算资源推荐。请注意，未设置资源限制。 + +| 容器 | CPU - 请求 | 内存 - 请求 | +|------------|--------|---------| +| Controller | 3（每个控制器需要 1GB 1vCPU） | * | +| Enforcer | 所有节点上 (500MB .5vCPU) | 1GB | +| Manager | 1 (500MB .5vCPU) | * | +| Scanner | 3 (100MB .5vCPU) | * | + +\* Controller、Manager 和 Scanner 容器合计至少需要 1GB 内存。 + + +## 强化集群支持 - Calico 和 Canal + + + + +- 如果 PSP 设置为 true，则所有 NeuVector 组件都是可部署的。 + +你需要为强化集群环境进行额外的配置，如下所示： + +1. 点击 **☰ > 集群管理**。 +1. 选择你创建的集群，并点击 **Explore**。 +1. 在左侧导航栏中，点击 **Apps**。 +1. 安装（或升级到）NeuVector 版本 `100.0.1+up2.2.2`。 + +- 在 **编辑选项** > **其它配置**下，选中复选框来启用 **Pod 安全策略**（无需其他配置）： + + ![为 RKE1 强化集群启用 PSP](/img/psp-nv-rke.png) + +1. 点击右下角的**安装**。 + + + + + +- 如果 PSP 设置为 true，则可以部署 NeuVector 组件 Controller 和 Enforcer。 + + +**仅适用于 NeuVector Chart 版本 100.0.0+up2.2.0**： + +- 对于 Manager、Scanner 和 Updater 组件，需要进行额外的配置，如下所示： + +``` +kubectl patch deploy neuvector-manager-pod -n cattle-neuvector-system --patch '{"spec":{"template":{"spec":{"securityContext":{"runAsUser": 5400}}}}}' +kubectl patch deploy neuvector-scanner-pod -n cattle-neuvector-system --patch '{"spec":{"template":{"spec":{"securityContext":{"runAsUser": 5400}}}}}' +kubectl patch cronjob neuvector-updater-pod -n cattle-neuvector-system --patch '{"spec":{"jobTemplate":{"spec":{"template":{"spec":{"securityContext":{"runAsUser": 5400}}}}}}}' +``` +
+ +你需要为强化集群环境进行额外的配置。 + +> **注意**：你必须更新 RKE2 和 K3s 强化集群中的配置，如下所示。 + +1. 点击 **☰ > 集群管理**。 +1. 选择你创建的集群，并点击 **Explore**。 +1. 在左侧导航栏中，点击 **Apps**。 +1. 安装（或升级到）NeuVector 版本 `100.0.1+up2.2.2`。 + +- 在 **编辑选项** > **其它配置**下，选中复选框来启用 **Pod 安全策略**。请注意，对于 `Manager runAsUser ID`、`Scanner runAsUser ID` 和 `Updater runAsUser ID`，你还必须输入大于 `0` 的值: + + ![为 RKE2 和 K3s 强化集群启用 PSP](/img/psp-nv-rke2.png) + +1. 点击右下角的**安装**。 + + + + + +## 启用 SELinux 的集群支持 - Calico 和 Canal + +要在 RKE2 集群上启用 SELinux，请执行以下步骤： + +- 如果 PSP 设置为 true，则可以部署 NeuVector 组件 Controller 和 Enforcer。 + + +**仅适用于 NeuVector Chart 版本 100.0.0+up2.2.0**： + +- 对于 Manager、Scanner 和 Updater 组件，需要进行额外的配置，如下所示： + +``` +kubectl patch deploy neuvector-manager-pod -n cattle-neuvector-system --patch '{"spec":{"template":{"spec":{"securityContext":{"runAsUser": 5400}}}}}' +kubectl patch deploy neuvector-scanner-pod -n cattle-neuvector-system --patch '{"spec":{"template":{"spec":{"securityContext":{"runAsUser": 5400}}}}}' +kubectl patch cronjob neuvector-updater-pod -n cattle-neuvector-system --patch '{"spec":{"jobTemplate":{"spec":{"template":{"spec":{"securityContext":{"runAsUser": 5400}}}}}}}' +``` + +## 离线环境中的集群支持 + +- 所有 NeuVector 组件都可部署在离线环境中的集群上，无需任何额外配置。 + + +## 支持限制 + +* 目前仅支持管理员和集群所有者。 + +* 不支持 Fleet 多集群部署。 + +* Windows 集群不支持 NeuVector。 + + +## 其他限制 + +* 目前，如果 NeuVector partner Chart 已存在，则 NeuVector 功能 Chart 的安装会失败。要解决此问题，请卸载 NeuVector partner Chart 并重新安装 NeuVector 功能 Chart。 + +* Controller 未准备好时，有可能无法从 Rancher UI 访问 NeuVector UI。在此期间，Controller 将尝试重新启动，并且需要几分钟才能进入 active 状态。 + +* 安装 NeuVector Chart 时，不会针对不同的集群类型自动检测容器运行时。要解决此问题，你可以手动指定运行时。 + diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/neuvector/neuvector.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/neuvector/neuvector.md new file mode 100644 index 00000000000..d2f1257309f --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/neuvector/neuvector.md @@ -0,0 +1,27 @@ +--- +title: 使用 NeuVector 实现容器安全 +--- + + + + + +NeuVector 是唯一一个100%开源、零信任的容器安全平台。在整个容器生命周期中持续扫描。清除安全路障。从一开始就制定安全策略，以最大限度地提高开发人员的灵活性。NeuVector 提供从构建到生产的漏洞和合规性扫描与管理。独特的 NeuVector 运行时保护通过七层容器防火墙保护集群内的网络连接以及集群的入口/出口。此外，NeuVector 还监视容器和主机上的进程和文件活动，以阻止未经授权的活动。 + +## NeuVector 和 Rancher + +所有 NeuVector 功能均可通过 Rancher 进行集成部署并单点登录 NeuVector 控制台。Rancher 集群管理员能够在其集群上部署和管理 NeuVector 部署，Helm 值、configMaps、自定义资源定义（CRD）和 NeuVector 控制台轻松配置 NeuVector。 + +使用 NeuVector 和 Rancher： + +- 部署、管理和保护多个集群。 +- 管理和报告 Rancher 工作负载和节点的漏洞和合规性结果。 + +## NeuVector Prime 和 Rancher Prime + +Rancher Manager 的 NeuVector UI 扩展可用于并支持 Rancher Prime 和 NeuVector Prime 客户。此扩展提供： + +- NeuVector 自动化部署，包括 Rancher Prime NeuVector 扩展仪表板。 +- 访问每个集群的重要安全信息，如关键安全事件、漏洞扫描结果和入口/出口暴露。 +- 直接对 Rancher 资源（例如节点和容器/ Pod）进行集成漏洞 (CVE) 和合规扫描。 +- 集成操作，如手动触发 Rancher 资源的扫描。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/neuvector/overview.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/neuvector/overview.md new file mode 100644 index 00000000000..f28cd25e3bd --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/neuvector/overview.md @@ -0,0 +1,195 @@ +--- +title: 概述 +--- + + + + + +## Rancher 中的 NeuVector 集成 + +[NeuVector 5.x](https://open-docs.neuvector.com/) 是一个开源的，以容器为中心的安全应用程序，Rancher 已集成 NeuVector。NeuVector 在运行时为关键应用程序和数据提供实时的合规、可见和保护功能。NeuVector 提供具有 CIS Benchmark 和漏洞扫描的防火墙、容器进程/文件系统监控和安全审计。有关 Rancher 安全性的更多信息，请参阅[安全文档](../../reference-guides/rancher-security)。 + +NeuVector 可以通过 Helm Chart 启用。你可以在 **Apps** 或 Rancher UI 中的 **Cluster Tools** 中安装该 Chart。安装 Helm Chart 后，用户可以轻松地[在 Rancher 中部署和管理 NeuVector 集群](https://open-docs.neuvector.com/deploying/rancher#deploy-and-manage-neuvector-through-rancher-apps-marketplace)。 + +## 使用 Rancher 安装 NeuVector + +Harvester Helm Chart 用于管理 Rancher 中 NeuVector UI 的访问，用户可以在 Rancher 中直接跳转，然后部署和管理 NeuVector 集群。 + +**通过 Apps 导航并安装 NeuVector Chart：** + +1. 单击 **☰ > 集群管理**。 +1. 在 Clusters 页面上，转到要部署 NeuVector 的集群，然后单击 **Explore**。 +1. 转到 **Apps > Charts**，然后从 Chart 仓库中安装 **NeuVector**。 +1. 不同的集群类型需要不同的容器运行时。配置 Helm Chart 值时，转到**容器运行时**，然后根据集群类型选择运行时。最后，再次单击**安装**。 + +以下是一些例子： + +- K3s 和 RKE2：`k3scontainerd` +- AKS：`containerd` 适用于 v1.19 及更高版本 +- EKS：`docker` 适用于 v1.22 及以下版本；`containerd` 适用于 v1.23 及更高版本 +- GKE：`containerd` (请参阅 [Google 文档](https://cloud.google.com/kubernetes-engine/docs/concepts/using-containerd)了解更多信息) + + :::note + + 在安装过程中一次只能选择一个容器运行时引擎。 + + ::: + +**通过集群工具导航并安装 NeuVector Chart：** + +1. 单击 **☰ > 集群管理**。 +1. 在 Clusters 页面上，转到要部署 NeuVector 的集群，然后单击 **Explore**。 +1. 点击左侧导航栏底部的**集群工具**。 +1. 按照上面的步骤 4 相应地选择你的容器运行时，然后再次单击**安装**。 + +## 从 Rancher UI 访问 NeuVector + +1. 导航到安装了 NeuVector 的集群的 Cluster Explorer。在左侧导航栏中，单击 **NeuVector**。 +1. 单击外部链接以转到 NeuVector UI。选择链接后，用户必须接受`最终用户许可协议`才能访问 NeuVector UI。 + +## 从 Rancher UI 卸载 NeuVector + +**通过 Apps 卸载：** + +1. 单击 **☰ > 集群管理**。 +1. 在 **Apps** 下，点击 **Installed Apps**。 +1. 在 `cattle-neuvector-system` 下，选择 NeuVector 应用程序（如果需要，还可以选择相关的 CRD），然后单击**删除**。 + +**通过集群工具卸载：** + +1. 单击 **☰ > 集群管理**。 +1. 单击屏幕左下角的**集群工具**，然后单击 NeuVector Chart 下方的垃圾桶图标。如果需要，选择`删除与此应用关联的 CRD`，然后单击**删除**。 + +## GitHub 仓库 + +NeuVector 项目在[这里](https://github.com/neuvector/neuvector)。 + +## 文档 + +NeuVector 文档在[这里](https://open-docs.neuvector.com/)。 + +## 架构 + +NeuVector 安全解决方案包含四种类型的安全容器，分别是 Controller、Enforcer、Manager 和 Scanner。它还提供了一个称为 All-in-One 的特殊容器（主要用于 Docker 原生部署），能将 Controller、Enforcer 和 Manager 功能组合在一个容器中。此外，还有一个 Updater，运行该程序时会更新 CVE 数据库。 + +- **Controller：** 管理 NeuVector Enforcer 容器；为管理控制台提供 REST API。 +- **Enforcer：** 执行安全策略。 +- **Manager：** 提供一个 web-UI 和 CLI 控制台来管理 NeuVector 平台。 +- **All-in-One：** 包括 Controller、Enforcer 和 Manager。 +- **Scanner：** 对镜像、容器和节点执行漏洞和合规性扫描。 +- **Updater：** 更新 Neuvector 的 CVE 数据库（运行的时候）；重新部署 scanner pod。 + +
**NeuVector 安全容器：**
+ +![NeuVector 安全容器](/img/neuvector-security-containers.png) + +
**NeuVector 架构：**
+ +![NeuVector 架构](/img/neuvector-architecture.png) + +要了解有关 NeuVector 架构的更多信息，请参阅[此处](https://open-docs.neuvector.com/basics/overview#architecture)。 + +## CPU 和内存分配 + +以下是默认 NeuVector Chart 安装部署的最低计算资源推荐。请注意，未设置资源限制。 + +| 容器 | CPU - 请求 | 内存 - 请求 | +| ---------- | ----------------------------- | ----------- | +| Controller | 3（每个控制器需要 1GB 1vCPU） | \* | +| Enforcer | 所有节点上 (500MB .5vCPU) | 1GB | +| Manager | 1 (500MB .5vCPU) | \* | +| Scanner | 3 (100MB .5vCPU) | \* | + +\* Controller、Manager 和 Scanner 容器合计至少需要 1GB 内存。 + +## 强化集群支持 - Calico 和 Canal + + + + +- 如果 PSP 设置为 true，则所有 NeuVector 组件都是可部署的。 + +你需要为强化集群环境进行额外的配置，如下所示： + +1. 单击 **☰ > 集群管理**。 +1. 选择你创建的集群，并点击 **Explore**。 +1. 在左侧导航栏中，点击 **Apps**。 +1. 安装（或升级到）NeuVector 版本 `100.0.1+up2.2.2`。 + +- 在**编辑选项** > **其它配置**下，选中复选框来启用 **Pod 安全策略**（无需其他配置）： + + ![为 RKE1 强化集群启用 PSP](/img/psp-nv-rke.png) + +1. 点击右下角的**安装**。 + + + + +- 如果 PSP 设置为 true，则可以部署 NeuVector 组件 Controller 和 Enforcer。 + +**仅适用于 NeuVector Chart 版本 100.0.0+up2.2.0：** + +- 对于 Manager、Scanner 和 Updater 组件，需要进行额外的配置，如下所示： + +``` +kubectl patch deploy neuvector-manager-pod -n cattle-neuvector-system --patch '{"spec":{"template":{"spec":{"securityContext":{"runAsUser": 5400}}}}}' +kubectl patch deploy neuvector-scanner-pod -n cattle-neuvector-system --patch '{"spec":{"template":{"spec":{"securityContext":{"runAsUser": 5400}}}}}' +kubectl patch cronjob neuvector-updater-pod -n cattle-neuvector-system --patch '{"spec":{"jobTemplate":{"spec":{"template":{"spec":{"securityContext":{"runAsUser": 5400}}}}}}}' +``` + +
+ +你需要为强化集群环境进行额外的配置。 + +> **注意：**你必须更新 RKE2 和 K3s 强化集群中的配置，如下所示。 + +1. 单击 **☰ > 集群管理**。 +1. 选择你创建的集群，并点击 **Explore**。 +1. 在左侧导航栏中，点击 **Apps**。 +1. 安装（或升级到）NeuVector 版本 `100.0.1+up2.2.2`。 + +- 在**编辑选项** > **其它配置**下，选中复选框来启用 **Pod 安全策略**。请注意，对于 `Manager runAsUser ID`，`Scanner runAsUser ID` 和 `Updater runAsUser ID`，你还必须输入大于 `0` 的值： + + ![为 RKE2 和 K3s 强化集群启用 PSP](/img/psp-nv-rke2.png) + +1. 点击右下角的**安装**。 + + + + +## 启用 SELinux 的集群支持 - Calico 和 Canal + +要在 RKE2 集群上启用 SELinux，请执行以下步骤： + +- 如果 PSP 设置为 true，则可以部署 NeuVector 组件 Controller 和 Enforcer。 + +**仅适用于 NeuVector Chart 版本 100.0.0+up2.2.0：** + +- 对于 Manager、Scanner 和 Updater 组件，需要进行额外的配置，如下所示： + +``` +kubectl patch deploy neuvector-manager-pod -n cattle-neuvector-system --patch '{"spec":{"template":{"spec":{"securityContext":{"runAsUser": 5400}}}}}' +kubectl patch deploy neuvector-scanner-pod -n cattle-neuvector-system --patch '{"spec":{"template":{"spec":{"securityContext":{"runAsUser": 5400}}}}}' +kubectl patch cronjob neuvector-updater-pod -n cattle-neuvector-system --patch '{"spec":{"jobTemplate":{"spec":{"template":{"spec":{"securityContext":{"runAsUser": 5400}}}}}}}' +``` + +## 离线环境中的集群支持 + +- 所有 NeuVector 组件都可部署在离线环境中的集群上，无需任何额外配置。 + +## 支持限制 + +- 目前仅支持管理员和集群所有者。 + +- 不支持 Fleet 多集群部署。 + +- Windows 集群不支持 NeuVector。 + +## 其他限制 + +- 目前，如果 NeuVector partner Chart 已存在，则 NeuVector 功能 Chart 的安装会失败。要解决此问题，请卸载 NeuVector partner Chart 并重新安装 NeuVector 功能 Chart。 + +- Controller 未准备好时，有可能无法从 Rancher UI 访问 NeuVector UI。在此期间，Controller 将尝试重新启动，并且需要几分钟才能进入 active 状态。 + +- 安装 NeuVector Chart 时，不会针对不同的集群类型自动检测容器运行时。要解决此问题，你可以手动指定运行时。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/opa-gatekeeper.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/opa-gatekeeper.md new file mode 100644 index 00000000000..41c91274c66 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/opa-gatekeeper.md @@ -0,0 +1,111 @@ +--- +title: OPA Gatekeeper +--- + +为了确保一致性和合规性，每个组织都需要能够以自动化的方式在环境中定义和执行策略。[OPA（Open Policy Agent）](https://www.openpolicyagent.org/) 是一个策略引擎，用于基于策略控制云原生环境。Rancher 支持在 Kubernetes 集群中启用 OPA Gatekeeper，并且还安装了一些内置的策略定义（也称为约束模板）。 + +OPA 提供了一种高级声明性语言，可以让你将策略指定为代码，还能扩展简单的 API，从而减轻策略决策的负担。 + +[OPA Gatekeeper](https://github.com/open-policy-agent/gatekeeper) 是一个提供 OPA 和 Kubernetes 集成的项目。OPA Gatekeeper 提供： + +- 一个可扩展的参数化策略库。 +- 用于实例化策略库的原生 Kubernetes CRD，也称为“约束”。 +- 用于扩展策略库的原生 Kubernetes CRD，也称为“约束模板”。 +- 审计功能。 + +要了解更多关于 OPA 的信息，请参阅[官方文档](https://www.openpolicyagent.org/docs/latest/)。 + +## OPA Gatekeeper 集成的工作原理 + +Kubernetes 支持通过准入控制器（准入控制器）webhook 来扩展 API Server 的功能，创建、更新或删除资源时都会调用这些 webhook。Gatekeeper 作为验证 webhook 安装，并执行由 Kubernetes CRD（Custom Resource Definition）定义的策略。除了使用准入控制之外，Gatekeeper 还能审计 Kubernetes 集群中的现有资源，并对违反当前策略的情况进行标记。 + +OPA Gatekeeper 由 Rancher 的 Helm system Chart 提供，它安装在名为 `gatekeeper-system` 的命名空间中。 + +## 在集群中启用 OPA Gatekeeper + +:::note + +Rancher 2.5 改进了 OPA Gatekeeper 应用。无法从 Rancher 2.4 升级到 Rancher 2.5 中的新版本。如果你在 Rancher 2.4 中安装了 OPA Gatekeeper，则需要在旧 UI 中卸载 OPA Gatekeeper 及其 CRD，然后在 Rancher 2.5 中重新安装它。如需卸载 CRD，请在 kubectl 控制台中运行 `kubectl delete crd configs.config.gatekeeper.sh constrainttemplates.templates.gatekeeper.sh` 命令。 + +::: + +:::note 先决条件： + +只有管理员和集群所有者才能启用 OPA Gatekeeper。 + +::: + +你可以在 **Apps** 页面安装 OPA Gatekeeper Helm Chart。 + +### 启用 OPA Gatekeeper + +1. 在左上角，单击 **☰ > 集群管理**。 +1. 在**集群**页面中，转到要启用 OPA Gatekeeper 的集群，然后单击 **Explore**。 +1. 在左侧导航栏中，点击 **Apps**。 +1. 点击 **Charts** 并点击 **OPA Gatekeeper**。 +1. 单击**安装**。 + +**结果**：已将 OPA Gatekeeper 部署到你的 Kubernetes 集群。 + +## 约束模板 + +[约束模板](https://github.com/open-policy-agent/gatekeeper#constraint-templates)是 Kubernetes 自定义资源，用于定义要由 Gatekeeper 应用的 OPA 策略的架构和 Rego 逻辑。有关 Rego 策略语言的更多信息，请参阅[官方文档](https://www.openpolicyagent.org/docs/latest/policy-language/)。 + +启用 OPA Gatekeeper 后，Rancher 默认会安装一些模板。 + +要列出集群中安装的约束模板，请转到 OPA Gatekeeper 下的左侧菜单，然后单击**模板**。 + +Rancher 还支持通过导入 YAML 定义来创建你自己的约束模板。 + +## 创建和配置约束 + +[约束](https://github.com/open-policy-agent/gatekeeper#constraints)是 Kubernetes 自定义资源，用于定义要应用约束模板的对象范围。约束模板和约束共同定义一个完整的策略。 + +:::note 先决条件： + +集群中已启用 OPA Gatekeeper。 + +::: + +要列出已安装的约束，请转到 OPA Gatekeeper 下的左侧菜单，然后单击**约束**。 + +可以从约束模板创建新的约束。 + +Rancher 支持通过使用方便的表单来创建约束，你可以在该表单中输入各种约束字段。 + +**以 YAML 文件编辑**选项也可以用于配置约束的 YAML 定义。 + +### 使 Rancher 的 System 命名空间不受约束 + +创建约束时，请确保该约束不应用于任何 Rancher 或 Kubernetes System 命名空间。如果不排除 System 命名空间，则可能会出现 system 命名空间下的许多资源被标记为违反约束。 + +要让约束仅限制用户命名空间，请在约束的**匹配**字段下指定这些命名空间。 + +此外，该约束可能会干扰其他 Rancher 功能并拒绝部署系统工作负载。为避免这种情况，请从你的约束中排除所有 Rancher 特定的命名空间。 + +## 在集群中实施约束 + +如果**执行动作**为 **Deny**，约束会立即启用，并拒绝任何违反策略的请求。默认情况下，执行的值为 **Deny**。 + +如果**执行动作** 为 **Dryrun**，违反策略的资源仅会记录在约束的状态字段中。 + +要强制执行约束，请使用表单创建约束。在**执行动作**字段中，选择 **Deny**。 + +## 集群中的审计和违规 + +OPA Gatekeeper 运行定期审计，以检查现有资源是否违反强制执行的约束。你可以在安装 Gatekeeper 时配置审计间隔（默认 300 秒）。 + +Gatekeeper 页面上列出了违反已定义的约束的情况。 + +此外，你也可以在**约束**页面中找到违反约束的数量。 + +每个约束的详细信息视图列出了违反约束的资源的信息。 + +## 禁用 Gatekeeper + +1. 导航到集群的仪表板视图。 +1. 在左侧菜单中，展开集群菜单并单击 **OPA Gatekeeper**。 +1. 单击 **⋮ > 禁用**。 + +**结果**：禁用 OPA Gatekeeper 后，所有约束模板和约束也将被删除。 + diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/rancher-desktop.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/rancher-desktop.md new file mode 100644 index 00000000000..5e418069595 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/rancher-desktop.md @@ -0,0 +1,33 @@ +--- +title: 桌面上的 Kubernetes 与 Rancher Desktop +--- + + + + + +Rancher Desktop 将用于桌面开发和测试云原生应用程序的基本工具捆绑在一起。 + +如果你在本地计算机上运行适用于云环境的应用程序，则通常需要进行大量准备工作。你需要选择一个容器运行时,安装 Kubernetes 和流行的实用程序，并且可能还需要设置虚拟机。单独安装组件并使它们协同工作可能是一个耗时的过程。 + +为了降低复杂性，Rancher Desktop 为团队提供了以下主要功能： + +- 在 macOS、Linux 和 Windows 操作系统上进行简单易用的安装。 +- K3s，一个易于使用的轻量级 Kubernetes 发行版。 +- 能够在 Kubernetes 版本之间轻松切换。 +- 由 Rancher 支持的基于 GUI 的集群仪表板，用于浏览本地集群。 +- 自由选择容器引擎：dockerd（moby）或 containerd。 +- 用于配置应用程序以满足你的需求的首选项设置。 +- 容器、基于 Kubernetes 的开发和操作工作流程所需的捆绑工具。 +- 定期更新，使捆绑工具保持最新。 +- 与流行的工具/IDE 集成，包括 VS Code 和 Skaffold。 +- 镜像和注册表访问控制。 +- 支持 Docker 扩展。 + +访问 [Rancher Desktop](https://rancherdesktop.io) 网站并阅读[文档](https://docs.rancherdesktop.io/)以了解更多信息。 + +要在你的机器上安装 Rancher Desktop，请参阅[安装指南](https://docs.rancherdesktop.io/getting-started/installation)。 + +## 在 Rancher Desktop 上尝试 Rancher + +Rancher Desktop 提供了轻松试用容器化、基于 Helm 的应用程序所需的设置和工具。你可以按照此[操作指南](https://docs.rancherdesktop.io/how-to-guides/rancher-on-rancher-desktop)，使用 Rancher Desktop 开始使用 Rancher Kubernetes 管理平台。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/rancher-extensions.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/rancher-extensions.md new file mode 100644 index 00000000000..0f6de8e5900 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/rancher-extensions.md @@ -0,0 +1,84 @@ +--- +title: Rancher 扩展 +--- + +Rancher v2.7.0 引入了**扩展（Extension）**的新功能。扩展允许用户、开发人员、合作伙伴和客户扩展和增强 Rancher UI。此外，用户可以独立于 Rancher 版本对其 UI 功能进行更改和增强。有了扩展，用户能够在 Rancher 之上进行构建，从而更好地根据环境进行定制。用户还可以更新到新版本以及回滚到以前的版本。 + +扩展是只能在集群中安装一次的 Helm Chart。因此，这些 Chart 已经过简化，并与 **Apps** 下列出的常规 Helm Chart 分开。 + +内置的 Rancher 扩展示例包括 Fleet、Explorer 和 Harvester。使用可手动添加的 Extensions API 的其他扩展示例包括 Kubewarden 和 Elemental。 + +## 先决条件 + +> 你必须以管理员身份登录才能查看扩展管理页面并与之交互。 + +## 安装扩展 + +1. 点击 **Configuration** 下的 **☰ > Extensions**。 + +2. 如果它尚未安装到 **Apps** 中，则你必须通过单击 **Enable** 按钮启用扩展 operator。 + + - 如果不是离线安装环境，请单击 **OK** 添加 Rancher 扩展仓库。否则，取消选中复选框并单击 **OK**。 + + ![Rancher extension repository](/img/add-rancher-extension-repo.png) + +3. 在 **Extensions** 页面上，单击 **Available** 选项卡选择要安装的扩展。 + +:::info + +在 v2.7.0 中，**Available** 选项卡下不会显示内置扩展。因此，你需要手动添加所需的仓库以安装扩展。一旦这些扩展可用了，我们将同步社区。 + +::: +
+ +4. 如果没有显示可用的扩展，你可以手动添加仓库，如下所示： + + 4.1. 在屏幕右上角，点击 **⋮ > Manage Repositories > Create**。 + + 4.2. 添加所需的仓库名称，确保指定了 Git 仓库 URL 和 Git 分支。 + + 4.3. 再次点击右下方的 **Create**。 + + ![Manage repositories](/img/manage-repos.png) + +5. 在 **Available** 选项卡下，单击所需扩展和版本上的 **Install** 按钮，如下例所示。请注意，如果扩展程序可用，**Update** 按钮将出现在该扩展上，因此你可以轻松更新扩展。 + + ![Install Kubewarden](/img/install-kubewarden.png) + +6. 点击 **Reload** 按钮，该按钮将在你的扩展成功安装后出现。请注意，对于刚刚安装扩展的登录用户而言，**除非**他们重新加载页面，否则他们不会看到 UI 的变化。 + + ![Reload button](/img/reload-button.png) + +## 卸载扩展 + +你可以通过两种方式卸载或禁用扩展： + +1. 在 **Installed** 选项卡下，单击要删除的扩展上的 **Uninstall** 按钮。 + + ![Uninstall extensions](/img/uninstall-extension.png) + +1. 在扩展管理页面，点击 **⋮ > Disable Extension Support**。这将禁用所有已安装的扩展。 + + ![Disable extensions](/img/disable-extension-support.png) + +:::caution + +你必须在禁用扩展后重新加载页面，否则可能会出现显示问题。 + +::: + +## 回滚扩展 + +在 **Installed** 选项卡下，单击要回滚的扩展上的 **Rollback** 按钮。 + +![Roll back extensions](/img/roll-back-extension.png) + +:::caution + +回滚扩展后必须重新加载页面，否则可能会出现显示问题。 + +::: + +## 开发扩展 + +要了解如何开发你自己的扩展，请参阅官方[入门指南](https://rancher.github.io/dashboard/extensions/extensions-getting-started)。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/rancher-manager.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/rancher-manager.md new file mode 100644 index 00000000000..7df74298395 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/rancher-manager.md @@ -0,0 +1,15 @@ +--- +slug: / +title: "什么是 Rancher？" +sidebar_label: 什么是 Rancher？ +description: "Rancher 在 Kubernetes 之上添加了新的功能，让你一站式管理上百个集群，统一 RBAC，开启监控和告警。了解更多。" +--- +Rancher 是一个 Kubernetes 管理工具，让你能在任何地方和任何提供商上部署和运行集群。 + +Rancher 可以创建来自 Kubernetes 托管服务提供商的集群，创建节点并安装 Kubernetes，或者导入在任何地方运行的现有 Kubernetes 集群。 + +Rancher 基于 Kubernetes 添加了新的功能，包括统一所有集群的身份验证和 RBAC，让系统管理员从一个位置控制全部集群的访问。 + +此外，Rancher 可以为集群和资源提供更精细的监控和告警，将日志发送到外部提供商，并通过应用商店（Application Catalog）直接集成 Helm。如果你拥有外部 CI/CD 系统，你可以将其与 Rancher 对接。没有的话，你也可以使用 Rancher 提供的 Fleet 自动部署和升级工作负载。 + +Rancher 是一个 _全栈式_ 的 Kubernetes 容器管理平台，为你提供在任何地方都能成功运行 Kubernetes 的工具。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/backup-restore-configuration/backup-configuration.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/backup-restore-configuration/backup-configuration.md new file mode 100644 index 00000000000..005e93110aa --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/backup-restore-configuration/backup-configuration.md @@ -0,0 +1,188 @@ +--- +title: 备份配置 +--- + +你可以在备份创建页面配置调度，启用加密，并指定备份的存储位置。 + + +## 调度 + +选择第一个选项来执行一次性备份，或选择第二个选项来安排定期备份。选择**定期备份**后，你可以配置以下两个字段： + +- **调度**：该字段支持 + - 标准 [cron 表达式](https://en.wikipedia.org/wiki/Cron)，例如 `"0 * * * *"` + - 描述符，例如 `"@midnight"` 或 `"@every 1h30m"` +- **保留数量**：指定必须保留的备份文件数量。如果文件数量超过 `retentionCount` 设置的值，最旧的文件将被删除。默认值为 10。 + +| YAML 指令名称 | 描述 | +| ---------------- | ---------------- | +| `schedule` | 提供用于调度定期备份的 cron 字符串。 | +| `retentionCount` | 提供要保留的备份文件数量。 | + +## 加密 + +rancher-backup 通过调用 kube-apiserver 来收集资源。apiserver 返回的对象会被解密，所以即使启用了[静态加密](https://kubernetes.io/docs/tasks/administer-cluster/encrypt-data/)，备份收集的加密对象也会是明文。 + +为避免以明文形式存储资源，你可以使用与静态加密相同的 `EncryptionConfiguration` 文件来加密备份中的特定资源。 + +:::note 重要提示： + +rancher-backup Operator 不会保存 `EncryptionConfiguration`，因此在备份中加密对象时，你必须自行保存该文件。 + +例如，[将 Rancher 迁移到新集群](../../how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/migrate-rancher-to-new-cluster.md)时，该文件可用于在新集群​​中重新创建 secret。 + +::: + +Operator 将 `EncryptionConfiguration` 用作 `cattle-resources-system` 命名空间中的 Kubernetes Secret，在 Secret 数据中，它位于名为 `encryption-provider-config.yaml` 的 key 下面。 + +对于 `EncryptionConfiguration`，你可以使用 [Kubernetes 文档中提供的示例](https://kubernetes.io/docs/tasks/administer-cluster/encrypt-data/#understanding-the-encryption-at-rest-configuration)。 + +为确保在 secret 中使用正确的密钥，加密配置文件必须命名为 `encryption-provider-config.yaml`。下面的命令使用 `--from-file` 标志来创建具有正确密钥名称的 Secret。 + +将 `EncryptionConfiguration` 保存到名为 `encryption-provider-config.yaml` 的文件中，并运行以下命令： + +```bash +kubectl create secret generic encryptionconfig \ + --from-file=./encryption-provider-config.yaml \ + -n cattle-resources-system +``` + +这将确保密文包含一个名为 `encryption-provider-config.yaml` 的 key，而且 operator 会使用该 key 来获取加密配置。 + +`Encryption Config Secret` 下拉菜单将过滤并仅列出拥有这个 key 的密文。 + +![](/img/backup_restore/backup/encryption.png) + +在上面的示例命令中，`encryptionconfig` 这个名称可以任意修改。 + + +| YAML 指令名称 | 描述 | +| ---------------- | ---------------- | +| `encryptionConfigSecretName` | 提供 `cattle-resources-system` 命名空间中包含加密配置文件的密文的名称。 | + +## 存储位置 + +如果在备份中指定了 `StorageLocation`，operator 将从该特定的 S3 存储桶中检索备份位置。如果没有指定，operator 将尝试在默认 operator 级别的 S3 存储和 operator 级别的 PVC 存储中查找这个文件。默认存储位置是在部署 `rancher-backup` operator 时配置的。 + +如果你选择第一个选项，备份将存储在安装 rancher-backup Chart 时配置的存储位置中。如果你选择第二个选项，你可以配置不同的兼容 S3 的对象存储作为备份存储位置。 + +### S3 + +:::caution + +如果你使用 S3 备份目标，请确保每个集群都有自己的存储桶或文件夹。Rancher 将使用集群配置的 S3 存储桶或文件夹中的可用快照来填充快照信息。 + +::: + +S3 存储位置包含以下配置字段： + +1. **凭证密文**（可选）：如果你需要使用 AWS 访问密钥（access key）和密文密钥（secret key）来访问 S3 存储桶，请使用带有密钥和指令 `accessKey` 和 `secretKey` 的凭证来创建密文。它可以是任意一个命名空间。你可以点击[此处](#credentialsecret-示例)查看示例密文。如果运行 operator 的节点在 EC2 中，并且设置了允许它们访问 S3 的 IAM 权限，则此指令是不必要的（如[本节](#ec2-节点访问-s3-的-iam-权限)所述）。凭证密文下拉菜单列出了所有命名空间的密文。 +1. **存储桶名称**：存储备份文件的 S3 存储桶的名称。 +1. **区域**（可选）：S3 存储桶所在的 AWS [区域](https://aws.amazon.com/about-aws/global-infrastructure/regions_az/)。配置 MinIO 时不需要该字段。 +1. **文件夹**（可选）：S3 存储桶中存储备份文件的文件夹名称。不支持嵌套文件夹（例如， `rancher/cluster1`）。如果此字段留空，则默认将备份文件存储在 S3 存储桶的根文件夹中。 +1. **端点**：用于访问存储桶区域中的 S3 的[端点](https://docs.aws.amazon.com/general/latest/gr/s3.html)。 +1. **端点 CA**（可选）：Base64 编码的 CA 证书。如需获取示例，请参见 [S3 兼容配置示例](#s3-存储配置示例)。 +1. **跳过 TLS 验证**（可选）：如果你不使用 TLS，则设置为 `true`。 + + +| YAML 指令名称 | 描述 | 必填 | +| ---------------- | ---------------- | ------------ | +| `credentialSecretName` | 如果你需要使用 AWS 访问密钥（access key）和密文密钥（secret key）来访问 S3 存储桶，请使用带有密钥和指令 `accessKey` 和 `secretKey` 的凭证来创建密文。它可以在任何命名空间中，只要你在 `credentialSecretNamespace` 中提供该命名空间。点击[这里](#credentialsecret-示例)查看示例密文。如果运行 operator 的节点在 EC2 中，并且设置了允许它们访问 S3 的 IAM 权限，则此指令是不必要的（如[本节](#ec2-节点访问-s3-的-iam-权限)所述）。 | | +| `credentialSecretNamespace` | 包含访问 S3 的凭证的密文的命名空间。如果运行 operator 的节点在 EC2 中，并且设置了允许它们访问 S3 的 IAM 权限，则此指令是不必要的（如[本节](#ec2-节点访问-s3-的-iam-权限)所述）。 | | +| `bucketName` | 存储备份文件的 S3 存储桶的名称。 | ✓ | +| `folder` | S3 存储桶中存储备份文件的文件夹名称。不支持嵌套文件夹（例如， `rancher/cluster1`）。如果此字段留空，则默认将备份文件存储在 S3 存储桶的根文件夹中。 | | +| `region` | S3 存储桶所在的 AWS [区域](https://aws.amazon.com/about-aws/global-infrastructure/regions_az/)。 | ✓ | +| `endpoint` | 用于访问存储桶区域中的 S3 的[端点](https://docs.aws.amazon.com/general/latest/gr/s3.html)。 | ✓ | +| `endpointCA` | Base64 编码的 CA 证书。如需获取示例，请参见 [S3 兼容配置示例](#s3-存储配置示例)。 | | +| `insecureTLSSkipVerify` | 如果你不使用 TLS，则设置为 `true`。 | | + +### S3 存储配置示例 + +```yaml +s3: + credentialSecretName: s3-creds + credentialSecretNamespace: default + bucketName: rancher-backups + folder: rancher + region: us-west-2 + endpoint: s3.us-west-2.amazonaws.com +``` + +### MinIO 配置示例 + +```yaml +s3: + credentialSecretName: minio-creds + bucketName: rancherbackups + endpoint: minio.35.202.130.254.xip.io + endpointCA: LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSURHakNDQWdLZ0F3SUJBZ0lKQUtpWFZpNEpBb0J5TUEwR0NTcUdTSWIzRFFFQkN3VUFNQkl4RURBT0JnTlYKQkFNTUIzUmxjM1F0WTJFd0hoY05NakF3T0RNd01UZ3lOVFE1V2hjTk1qQXhNREk1TVRneU5UUTVXakFTTVJBdwpEZ1lEVlFRRERBZDBaWE4wTFdOaE1JSUJJakFOQmdrcWhraUc5dzBCQVFFRkFBT0NBUThBTUlJQkNnS0NBUUVBCjA4dnV3Q2Y0SEhtR2Q2azVNTmozRW5NOG00T2RpS3czSGszd1NlOUlXQkwyVzY5WDZxenBhN2I2M3U2L05mMnkKSnZWNDVqeXplRFB6bFJycjlpbEpWaVZ1NFNqWlFjdG9jWmFCaVNsL0xDbEFDdkFaUlYvKzN0TFVTZSs1ZDY0QQpWcUhDQlZObU5xM3E3aVY0TE1aSVpRc3N6K0FxaU1Sd0pOMVVKQTZ6V0tUc2Yzc3ByQ0J2dWxJWmZsVXVETVAyCnRCTCt6cXZEc0pDdWlhNEEvU2JNT29tVmM2WnNtTGkwMjdub3dGRld3MnRpSkM5d0xMRE14NnJoVHQ4a3VvVHYKQXJpUjB4WktiRU45L1Uzb011eUVKbHZyck9YS2ZuUDUwbk8ycGNaQnZCb3pUTStYZnRvQ1d5UnhKUmI5cFNTRApKQjlmUEFtLzNZcFpMMGRKY2sxR1h3SURBUUFCbzNNd2NUQWRCZ05WSFE0RUZnUVU5NHU4WXlMdmE2MTJnT1pyCm44QnlFQ2NucVFjd1FnWURWUjBqQkRzd09ZQVU5NHU4WXlMdmE2MTJnT1pybjhCeUVDY25xUWVoRnFRVU1CSXgKRURBT0JnTlZCQU1NQjNSbGMzUXRZMkdDQ1FDb2wxWXVDUUtBY2pBTUJnTlZIUk1FQlRBREFRSC9NQTBHQ1NxRwpTSWIzRFFFQkN3VUFBNElCQVFER1JRZ1RtdzdVNXRQRHA5Q2psOXlLRW9Vd2pYWWM2UlAwdm1GSHpubXJ3dUVLCjFrTkVJNzhBTUw1MEpuS29CY0ljVDNEeGQ3TGdIbTNCRE5mVVh2anArNnZqaXhJYXR2UWhsSFNVaWIyZjJsSTkKVEMxNzVyNCtROFkzelc1RlFXSDdLK08vY3pJTGh5ei93aHRDUlFkQ29lS1dXZkFiby8wd0VSejZzNkhkVFJzNwpHcWlGNWZtWGp6S0lOcTBjMHRyZ0xtalNKd1hwSnU0ZnNGOEcyZUh4b2pOKzdJQ1FuSkg5cGRIRVpUQUtOL2ppCnIvem04RlZtd1kvdTBndEZneWVQY1ZWbXBqRm03Y0ZOSkc4Y2ZYd0QzcEFwVjhVOGNocTZGeFBHTkVvWFZnclMKY1VRMklaU0RJd1FFY3FvSzFKSGdCUWw2RXBaUVpWMW1DRklrdFBwSQotLS0tLUVORCBDRVJUSUZJQ0FURS0tLS0t +``` +### credentialSecret 示例 + +```yaml +apiVersion: v1 +kind: Secret +metadata: + name: creds +type: Opaque +data: + accessKey: + secretKey: +``` + +:::note + +为避免编码问题，你可以使用以下命令创建 `credentialSecret`，更新 `accessKey` 和 `secretKey` 的值。 + +```bash +kubectl create secret generic s3-creds \ + --from-literal=accessKey= \ + --from-literal=secretKey= +``` + +::: + +### EC2 节点访问 S3 的 IAM 权限 + +有两种方法可以设置 `rancher-backup` operator 来使用 S3 作为备份存储位置。 + +一种方法是在 Backup 自定义资源中配置 `credentialSecretName`（即可以访问 S3 的 AWS 凭证）。 + +如果集群节点在 Amazon EC2 中，你也可以给 EC2 节点分配 IAM 权限，使其可以访问 S3。 + +要允许节点访问 S3，请按照 [AWS 文档](https://aws.amazon.com/premiumsupport/knowledge-center/ec2-instance-access-s3-bucket/)中的说明，为 EC2 创建一个 IAM 角色。在向角色添加自定义策略时，添加以下权限，并将 `Resource` 替换为你的存储桶名称： + +```json +{ + "Version": "2012-10-17", + "Statement": [ + { + "Effect": "Allow", + "Action": [ + "s3:ListBucket" + ], + "Resource": [ + "arn:aws:s3:::rancher-backups" + ] + }, + { + "Effect": "Allow", + "Action": [ + "s3:PutObject", + "s3:GetObject", + "s3:DeleteObject", + "s3:PutObjectAcl" + ], + "Resource": [ + "arn:aws:s3:::rancher-backups/*" + ] + } + ] +} +``` + +在创建角色并将相应的实例配置文件附加 EC2 实例后，Backup 自定义资源中的 `credentialSecretName` 指令可以留空。 + +## 示例 + +如需获取 Backup 自定义资源的示例，请参见[本页](examples.md#备份)。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/backup-restore-configuration/backup-restore-configuration.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/backup-restore-configuration/backup-restore-configuration.md new file mode 100644 index 00000000000..6fbc1f202af --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/backup-restore-configuration/backup-restore-configuration.md @@ -0,0 +1,12 @@ +--- +title: Rancher 备份配置参考 +--- + + + + + +- [备份配置](backup-configuration.md) +- [还原配置](restore-configuration.md) +- [存储位置配置](storage-configuration.md) +- [Backup 和 Restore 自定义资源示例](examples.md) diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/backup-restore-configuration/examples.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/backup-restore-configuration/examples.md new file mode 100644 index 00000000000..ca1ce934d84 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/backup-restore-configuration/examples.md @@ -0,0 +1,293 @@ +--- +title: 示例 +--- + +本节包含 Backup 和 Restore 自定义资源的示例。 + +默认的备份存储位置是在安装或升级 `rancher-backup` operator 时配置的。 + +只有 Restore 自定义资源使用创建备份时使用的加密配置密文时，才能还原加密的备份。 + +## 备份 + +本节包含 Backup 自定义资源的示例。 + +> **注意**：有关配置以下选项的更多信息，请参阅[备份配置参考页面](./backup-configuration.md)。 + +### 在默认位置进行加密备份 + +```yaml +apiVersion: resources.cattle.io/v1 +kind: Backup +metadata: + name: default-location-encrypted-backup +spec: + resourceSetName: rancher-resource-set + encryptionConfigSecretName: encryptionconfig +``` + +### 在默认位置进行定期备份 + +```yaml +apiVersion: resources.cattle.io/v1 +kind: Backup +metadata: + name: default-location-recurring-backup +spec: + resourceSetName: rancher-resource-set + schedule: "@every 1h" + retentionCount: 10 +``` + +### 在默认位置进行加密的定期备份 + +```yaml +apiVersion: resources.cattle.io/v1 +kind: Backup +metadata: + name: default-enc-recurring-backup +spec: + resourceSetName: rancher-resource-set + encryptionConfigSecretName: encryptionconfig + schedule: "@every 1h" + retentionCount: 3 +``` + +### Minio 中的加密备份 + +```yaml +apiVersion: resources.cattle.io/v1 +kind: Backup +metadata: + name: minio-backup +spec: + storageLocation: + s3: + credentialSecretName: minio-creds + credentialSecretNamespace: default + bucketName: rancherbackups + endpoint: minio.xip.io + endpointCA: + resourceSetName: rancher-resource-set + encryptionConfigSecretName: encryptionconfig +``` + +### 使用 AWS 凭证密文在 S3 中备份 + +```yaml +apiVersion: resources.cattle.io/v1 +kind: Backup +metadata: + name: s3-backup +spec: + storageLocation: + s3: + credentialSecretName: s3-creds + credentialSecretNamespace: default + bucketName: rancher-backups + folder: ecm1 + region: us-west-2 + endpoint: s3.us-west-2.amazonaws.com + resourceSetName: rancher-resource-set + encryptionConfigSecretName: encryptionconfig +``` + +### 使用 AWS 凭证密文在 S3 中进行定期备份 + +```yaml +apiVersion: resources.cattle.io/v1 +kind: Backup +metadata: + name: s3-recurring-backup +spec: + storageLocation: + s3: + credentialSecretName: s3-creds + credentialSecretNamespace: default + bucketName: rancher-backups + folder: ecm1 + region: us-west-2 + endpoint: s3.us-west-2.amazonaws.com + resourceSetName: rancher-resource-set + encryptionConfigSecretName: encryptionconfig + schedule: "@every 1h" + retentionCount: 10 +``` + +### 从具有访问 S3 的 IAM 权限的 EC2 节点进行备份 + +这个例子表明，如果运行 `rancher-backup` 的节点拥有这些[访问 S3 的权限](backup-configuration.md#ec2-节点访问-s3-的-iam-权限)，就不必提供 AWS 的凭证密文来创建备份。 + +```yaml +apiVersion: resources.cattle.io/v1 +kind: Backup +metadata: + name: s3-iam-backup +spec: + storageLocation: + s3: + bucketName: rancher-backups + folder: ecm1 + region: us-west-2 + endpoint: s3.us-west-2.amazonaws.com + resourceSetName: rancher-resource-set + encryptionConfigSecretName: encryptionconfig +``` + +## 还原 + +本节包含 Restore 自定义资源的示例。 + +> **注意**：有关配置以下选项的更多信息，请参阅[恢复配置参考页面](./restore-configuration.md)。 + +### 使用默认备份文件位置还原 + +```yaml +apiVersion: resources.cattle.io/v1 +kind: Restore +metadata: + name: restore-default +spec: + backupFilename: default-location-recurring-backup-752ecd87-d958-4d20-8350-072f8d090045-2020-09-26T12-29-54-07-00.tar.gz +# encryptionConfigSecretName: test-encryptionconfig +``` + +### 为 Rancher 迁移进行还原 +```yaml +apiVersion: resources.cattle.io/v1 +kind: Restore +metadata: + name: restore-migration +spec: + backupFilename: backup-b0450532-cee1-4aa1-a881-f5f48a007b1c-2020-09-15T07-27-09Z.tar.gz + prune: false + storageLocation: + s3: + credentialSecretName: s3-creds + credentialSecretNamespace: default + bucketName: rancher-backups + folder: ecm1 + region: us-west-2 + endpoint: s3.us-west-2.amazonaws.com +``` + +### 使用加密的备份还原 + +```yaml +apiVersion: resources.cattle.io/v1 +kind: Restore +metadata: + name: restore-encrypted +spec: + backupFilename: default-test-s3-def-backup-c583d8f2-6daf-4648-8ead-ed826c591471-2020-08-24T20-47-05Z.tar.gz + encryptionConfigSecretName: encryptionconfig +``` + +### 从 Minio 还原加密的备份 + +```yaml +apiVersion: resources.cattle.io/v1 +kind: Restore +metadata: + name: restore-minio +spec: + backupFilename: default-minio-backup-demo-aa5c04b7-4dba-4c48-9ac4-ab7916812eaa-2020-08-30T13-18-17-07-00.tar.gz + storageLocation: + s3: + credentialSecretName: minio-creds + credentialSecretNamespace: default + bucketName: rancherbackups + endpoint: minio.xip.io + endpointCA: + encryptionConfigSecretName: test-encryptionconfig +``` + +### 使用 AWS 凭证密文访问 S3 从备份中还原 + +```yaml +apiVersion: resources.cattle.io/v1 +kind: Restore +metadata: + name: restore-s3-demo +spec: + backupFilename: test-s3-recurring-backup-752ecd87-d958-4d20-8350-072f8d090045-2020-09-26T12-49-34-07-00.tar.gz.enc + storageLocation: + s3: + credentialSecretName: s3-creds + credentialSecretNamespace: default + bucketName: rancher-backups + folder: ecm1 + region: us-west-2 + endpoint: s3.us-west-2.amazonaws.com + encryptionConfigSecretName: test-encryptionconfig +``` + +### 从具有访问 S3 的 IAM 权限的 EC2 节点进行还原 + +这个例子表明，如果运行 `rancher-backup` 的节点拥有这些[访问 S3 的权限](backup-configuration.md#ec2-节点访问-s3-的-iam-权限)，就不必提供 AWS 的凭证密文来从备份中还原。 + +```yaml +apiVersion: resources.cattle.io/v1 +kind: Restore +metadata: + name: restore-s3-demo +spec: + backupFilename: default-test-s3-recurring-backup-84bf8dd8-0ef3-4240-8ad1-fc7ec308e216-2020-08-24T10#52#44-07#00.tar.gz + storageLocation: + s3: + bucketName: rajashree-backup-test + folder: ecm1 + region: us-west-2 + endpoint: s3.us-west-2.amazonaws.com + encryptionConfigSecretName: test-encryptionconfig +``` + +## 在 S3 中存储备份的凭证密文示例 + +```yaml +apiVersion: v1 +kind: Secret +metadata: + name: creds +type: Opaque +data: + accessKey: + secretKey: +``` + +## EncryptionConfiguration 示例 + +以下代码片段演示了两种不同类型的密文及其与自定义资源的备份和还原的相关性。 + +第一个示例是用于加密备份文件的密钥。在这种情况下，Backup operator 将无法读取密文加密文件。它只使用密文的内容。 + +第二个示例是 Kubernetes 密文加密配置文件，用于加密存储在 etcd 中的密文。**备份 etcd 数据存储时，请务必同时备份 EncryptionConfiguration**。如果你没有这样做，而且备份数据时正在使用密文加密，你将无法使用恢复的数据。 + + +```yaml +apiVersion: apiserver.config.k8s.io/v1 +kind: EncryptionConfiguration +resources: + - resources: + - secrets + providers: + - aesgcm: + keys: + - name: key1 + secret: c2VjcmV0IGlzIHNlY3VyZQ== + - name: key2 + secret: dGhpcyBpcyBwYXNzd29yZA== + - aescbc: + keys: + - name: key1 + secret: c2VjcmV0IGlzIHNlY3VyZQ== + - name: key2 + secret: dGhpcyBpcyBwYXNzd29yZA== + - secretbox: + keys: + - name: key1 + secret: YWJjZGVmZ2hpamtsbW5vcHFyc3R1dnd4eXoxMjM0NTY= +``` + + + diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/backup-restore-configuration/restore-configuration.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/backup-restore-configuration/restore-configuration.md new file mode 100644 index 00000000000..5931f1f82d8 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/backup-restore-configuration/restore-configuration.md @@ -0,0 +1,81 @@ +--- +title: 还原配置 +--- + +你可以在还原创建页面提供还原备份的详细信息。 + +![](/img/backup_restore/restore/restore.png) + + +## 备份源 +你需要提供备份文件和备份文件存储位置的详细信息，operator 会使用这些信息执行还原。选择以下其中一个选项来提供这些详细信息。 + + + + +### 使用已有的备份配置恢复 + +如果你选择这个选项，**目标备份**下拉菜单中会出现集群中可用的备份。从下拉菜单中选择 Backup，选择后**备份文件名**字段会自动填写，而且所选 Backup 的信息会传递给 operator + +![](/img/backup_restore/restore/existing.png) + +如果 Backup 自定义资源在集群中不存在，你需要获取准确的文件名，并使用默认存储目标或与 S3 兼容的对象存储来提供备份源的详细信息。 + + +### 使用默认存储目标恢复 + +如果你要从 operator 级别配置的默认存储位置中的备份文件进行恢复，请选择此选项。operator 级别的配置是指安装或升级 `rancher-backup` operator 时配置的存储位置。在**备份文件名**字段中提供准确的文件名。 + +![](/img/backup_restore/restore/default.png) + +### 使用与 S3 兼容的对象存储恢复 + +如果在 operator 级别没有配置默认存储位置，或者备份文件所在的存储桶与配置的默认存储位置不一样时，请选择此选项。在**备份文件名**字段中提供准确的文件名。请参见[本节](#从-s3-获取备份文件名)了解从 S3 获取备份文件名的具体步骤。填写 S3 兼容对象存储的所有详细信息。它的字段与 [Backup 自定义资源](backup-configuration.md#存储位置)中 `backup.StorageLocation` 配置的字段一样。 + +![](/img/backup_restore/restore/s3store.png) + +## 加密 + +如果备份是在启用加密的情况下创建的，备份文件的后缀为 `.enc`。如果你选择这类的 Backup，或者提供后缀为 `.enc` 的备份文件名，则会显示另一个名为 **Encryption Config Secret** 的下拉菜单。 + +![](/img/backup_restore/restore/encryption.png) + +从该下拉菜单中选择的密文必须与执行备份时用于 Backup 自定义资源的密文内容相同。如果加密配置不匹配，还原将会失败。 + +`Encryption Config Secret` 下拉菜单将过滤并仅列出拥有这个 key 的密文。 + +| YAML 指令名称 | 描述 | +| ---------------- | ---------------- | +| `encryptionConfigSecretName` | 提供 `cattle-resources-system` 命名空间中包含加密配置文件的密文的名称。 | + +:::note 重要提示： + +此字段仅在备份创建的过程中启用了加密功能时才需要设置。提供错误的加密配置将导致还原失败。 + +::: + +## 还原过程中修剪 + +* **Prune**：为了从备份中完全恢复 Rancher，并回到备份时的确切状态，我们需要删除 Rancher 在备份后创建的所有额外资源。如果 **Prune** 标志被启用，operator 就会删除这些资源。Prune 是默认启用的，建议保持启用状态。 +* **删除超时**：在删除资源的时候，operator 编辑资源以删除 Finalizers，并试图再次删除前将等待的时间。 + +| YAML 指令名称 | 描述 | +| ---------------- | ---------------- | +| `prune` | 删除备份中不存在的由 Rancher 管理的资源（推荐）。 | +| `deleteTimeoutSeconds` | 在删除资源的时候，operator 编辑资源以删除 Finalizers，并试图再次删除前将等待的时间。 | + +## 从 S3 获取备份文件名 + +这是 `rancher-backup` operator 用来执行还原的备份文件的名称。 + +要从 S3 获取这个文件名，请进入你的 S3 存储桶（或在执行备份时指定的文件夹）。 + +复制文件名并将其存储在你的 Restore 自定义资源中。假设你的备份文件的名字是 `backupfile`： + +- 如果你的存储桶名称是 `s3bucket`，而且你没有指定文件夹，那么要使用的 `backupFilename` 会是 `backupfile`。 +- 如果你的存储桶名称是 `s3bucket`，而且基础文件夹是 `s3folder`，那么要使用的 `backupFilename` 会是 `backupfile`。 +- 如果 `s3Folder` 中有一个名为 `s3sub` 的子文件夹，而且你的备份文件存放在该文件夹中，那么要使用的`backupFilename` 会是 `s3sub/backupfile`。 + +| YAML 指令名称 | 描述 | +| ---------------- | ---------------- | +| `backupFilename` | 这是 `rancher-backup` operator 用来执行还原的备份文件的名称。 | diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/backup-restore-configuration/storage-configuration.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/backup-restore-configuration/storage-configuration.md new file mode 100644 index 00000000000..2db4ed74ef5 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/backup-restore-configuration/storage-configuration.md @@ -0,0 +1,56 @@ +--- +title: 备份存储位置配置 +--- + +配置一个用于保存所有备份的默认存储位置。你可以选择对每个备份进行覆盖，但仅限于使用 S3 对象存储。 + +在 operator 级别只能配置一个存储位置。 + + +## 存储位置配置 + +### 无默认存储位置 + +你可以选择不配置 operator 级别的存储位置。如果选择此选项，你必须配置一个与 S3 兼容的对象存储作为每个备份的存储位置。 + +### S3 兼容的对象存储 + +| 参数 | 描述 | +| -------------- | -------------- | +| 凭证密文 | 从 Rancher 的密文中选择 S3 的凭证。[示例](examples.md#在-s3-中存储备份的凭证密文示例)。 | +| 存储桶名称 | 存储备份的 [S3 存储桶](https://docs.aws.amazon.com/AmazonS3/latest/dev/UsingBucket.html)的名称。默认值：`rancherbackups`。 | +| 区域 | S3 存储桶所在的 [AWS 区域](https://aws.amazon.com/about-aws/global-infrastructure/regions_az/)。 | +| 文件夹 | 存储备份的 [S3 存储桶中的文件夹](https://docs.aws.amazon.com/AmazonS3/latest/user-guide/using-folders.html)。如果此字段留空，则默认将备份文件存储在 S3 存储桶的根文件夹中。 | +| 端点 | [S3 端点](https://docs.aws.amazon.com/general/latest/gr/s3.html)，例如 `s3.us-west-2.amazonaws.com`。 | +| Endpoint CA | 用于 S3 端点的 CA 证书。默认值：base64 编码的 CA 证书。 | +| insecureTLSSkipVerify | 如果你不使用 TLS，则设置为 `true`。 | + +### 使用现有的 StorageClass + +如果你通过选择 StorageClass 选项来安装 `rancher-backup` Chart，将会创建一个持久卷说明（Persistent Volume Claim，PVC），而且 Kubernetes 会动态配置一个持久卷（Persistent Volume，PV），所有备份都会默认保存到该持久卷中。 + +关于创建存储类的信息，请参见[本章节](../../how-to-guides/new-user-guides/manage-clusters/create-kubernetes-persistent-storage/manage-persistent-storage/dynamically-provision-new-storage.md)。 + +:::note 重要提示： + +强烈建议使用回收策略为 "Retain" 的 StorageClass。否则，如果 `rancher-backup` Chart 创建的 PVC 在应用升级期间或意外被删除后，PV 也会被删除，也就是说所有保存在其中的备份都会被删除。 +如果没有这样的 StorageClass 可用，在配置 PV 后，请确保先将其回收策略设置为 "Retain"，然后再存储备份。 + +::: + +### 使用现有的持久卷 + +选择一个用于存储备份的现有持久卷。有关在 Rancher 中创建 PersistentVolumes 的更多信息，请参见[本节](../../how-to-guides/new-user-guides/manage-clusters/create-kubernetes-persistent-storage/manage-persistent-storage/set-up-existing-storage.md#2-添加一个引用持久存储的-persistentvolume)。 + +:::note 重要提示： + +强烈建议使用回收策略为 "Retain" 的 Persistent Volume。否则，如果 `rancher-backup` Chart 创建的 PVC 在应用升级期间或意外被删除后，PV 也会被删除，也就是说所有保存在其中的备份都会被删除。 + +::: + +## rancher-backup Helm Chart 的示例 values.yaml + +使用 Helm CLI 时，可用于配置 `rancher-backup` operator 的 `values.yaml` 可以在 [backup-restore-operator](https://github.com/rancher/backup-restore-operator/blob/master/charts/rancher-backup/values.yaml) 仓库中找到。 + +有关 `values.yaml` 文件和在安装时配置 Helm Charts 的更多信息，请参见 [Helm 文档](https://helm.sh/docs/intro/using_helm/#customizing-the-chart-before-installing)。 + diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/best-practices/best-practices.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/best-practices/best-practices.md new file mode 100644 index 00000000000..11f4ee82e41 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/best-practices/best-practices.md @@ -0,0 +1,21 @@ +--- +title: 最佳实践 +--- + + + + + +本节介绍 Rancher 实现的最佳实践，其中包括对 Kubernetes、Docker、容器等技术的使用建议。最佳实践旨在利用 Rancher 及其客户的运营经验，助你更好地实现 Rancher。 + +如果你对用例的实际应用有任何疑问，请联系客户成功经理或支持中心。 + +你可以在左侧导航栏快速找到管理和部署 Rancher Server 的最佳实践。 + +如需查看更多最佳实践指南，请参见： + +- [安全类文档](../rancher-security/rancher-security.md) +- [Rancher 博客](https://www.suse.com/c/rancherblog/) +- [Rancher 论坛](https://forums.rancher.com/) +- [Rancher 用户的 Slack 群组](https://slack.rancher.io/) +- [B 站](https://space.bilibili.com/430496045/) diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/best-practices/rancher-managed-clusters/disconnected-clusters.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/best-practices/rancher-managed-clusters/disconnected-clusters.md new file mode 100644 index 00000000000..e0b9eb6757f --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/best-practices/rancher-managed-clusters/disconnected-clusters.md @@ -0,0 +1,19 @@ +--- +title: Best Practices for Disconnected Clusters +--- + + + + + +Rancher supports managing clusters that may not always be online due to network disruptions, control plane availability, or because all cluster nodes are down. At the moment there are no known issues with disconnected clusters in the latest released Rancher version. + +While a managed cluster is disconnected from Rancher, management operations will be unavailable, and the Rancher UI will not allow navigation to the cluster. However, once the connection is reestablished, functionality is fully restored. + +### Best Practices for Managing Disconnected Clusters + +- **Cluster Availability During Rancher Upgrades**: It is recommended to have all, or at least most, managed clusters online during a Rancher upgrade. The reason is that upgrading Rancher automatically upgrades the Rancher agent software running on managed clusters. Keeping the agent and Rancher versions aligned ensures consistent functionality. Any clusters that are disconnected during the upgrade will have their agents updated as soon as they reconnect. + +- **Cleaning Up Disconnected Clusters**: Regularly remove clusters that will no longer reconnect to Rancher (e.g., clusters that have been decommissioned or destroyed). Keeping such clusters in the Rancher management system consumes unnecessary resources, which could impact Rancher's performance over time. + +- **Certificate Rotation Considerations**: When designing processes that involve regularly shutting down clusters, whether connected to Rancher or not, take into account certificate rotation policies. For example, RKE2/K3s clusters may rotate certificates on startup if they exceeded their lifetime. diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/best-practices/rancher-managed-clusters/logging-best-practices.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/best-practices/rancher-managed-clusters/logging-best-practices.md new file mode 100644 index 00000000000..64d58392251 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/best-practices/rancher-managed-clusters/logging-best-practices.md @@ -0,0 +1,86 @@ +--- +title: Logging 最佳实践 +--- + +本指南介绍了集群级别日志和应用日志的最佳实践。 + +- [集群级别日志](#集群级别日志) +- [应用日志](#应用日志) +- [通用最佳实践](#通用最佳实践) + +在 Rancher 2.5 之前，Rancher 的 Logging 是一个静态集成。可供选择的聚合器是固定的（包括 ElasticSearch、Splunk、Kafka、Fluentd 和 Syslog），而且只有两个配置级别可供选择（集群级别和项目级别）。 + +现在，Rancher 的日志聚合更加灵活。通过新的 Logging 的功能，管理员和用户都可以部署符合细粒度收集标准的日志记录，同时提供更多的目标和配置选项。 + +Rancher Logging 使用的是 [Logging Operator](https://github.com/kube-logging/logging-operator)。我们让你可以管理这个 operator 及其资源，并将它的管理功能和 Rancher 集群管理联系起来。 + +## 集群级别日志 + +### 抓取集群内日志 + +某些用户可能想从集群中运行的每个容器中抓取日志。但是你的安全团队可能要求你从所有执行点收集所有日志。 + +在这种情况下，我们建议你至少创建两个 _ClusterOutput_ 对象 - 一个用于安全团队（如果需要），另一个用于你自己，即集群管理员。创建这些对象时，请选择一个可以处理整个集群的大量日志的输出端点。此外，你还需要选择合适的索引来接收这些日志。 + +创建这些 _ClusterOutput_ 对象后，创建一个 _ClusterFlow_ 来收集所有日志。不要在此 flow 上定义任何 _Include_ 或 _Exclude_ 规则。这可以确保你能收集整个集群的所有日志。如果你有两个 _ClusterOutputs_，请确保它们都能收到日志。 + +### Kubernetes 组件 + +_ClusterFlows_ 能够收集 Kubernetes 集群中所有主机上所有容器的日志。如果这些容器包含在 Kubernetes Pod 中，这个方法是适用的。 + +Rancher 的未来版本将包含源容器名称，来支持过滤这些组件的日志。该功能实现之后，你将能够自定义 _ClusterFlow_ 来**仅**检索 Kubernetes 组件日志，并将日志发送到适当的输出位置。 + +## 应用日志 + +对于 Kubernetes 和所有基于容器的应用而言，最佳实践是将应用日志引导到 `stdout`/`stderr`。容器运行时将捕获这些日志并用它们进行**某些操作** - 通常是将它们写入文件。根据容器运行时（及其配置），这些日志可以放置在任意数量的位置。 + +在将日志写入文件的情况下，Kubernetes 通过在每个主机上创建一个 `/var/log/containers` 目录来提供帮助。这个目录将日志文件符号链接到它们的实际目的地（可能因为配置或容器运行时而有所不同）。 + +Rancher 的 Logging 将读取 `/var/log/containers` 中的所有日志条目，确保所有容器的所有日志条目（假设使用默认配置）均能被收集和处理。 + +### 特定日志文件 + +日志收集仅从 Kubernetes 中的 Pod 中检索 `stdout`/`stderr` 日志。但是，我们也可能想从应用生成的其他文件中收集日志。在这种情况下，你可以使用一个（或两个）日志流 Sidecar。 + +设置日志流 Sidecar 的目的是获取写入磁盘的日志文件，并将其内容传输到 `stdout`。这样一来，Logging Operator 就可以接收这些日志，并把日志发送到目标输出位置。 + +要进行设置，编辑你的工作负载资源（例如 Deployment）并添加以下 Sidecar 定义： + +```yaml +... +containers: +- args: + - -F + - /path/to/your/log/file.log + command: + - tail + image: busybox + name: stream-log-file-[name] + volumeMounts: + - mountPath: /path/to/your/log + name: mounted-log +... +``` + +这将添加一个容器到你的工作负载定义中，用于将 `/path/to/your/log/file.log` 的内容（在本示例中）传输到 `stdout`。 + +然后将根据你设置的 _Flows_ 或 _ClusterFlows_ 自动收集该日志流。你还可以通过使用容器的名称，专门为该日志文件创建一个 _Flow_。示例如下： + +```yaml +... +spec: + match: + - select: + container_names: + - stream-log-file-name +... +``` + + +## 通用最佳实践 + +- 尽量输出结构化日志条目（例如 `syslog`、JSON）。这些格式已经有了解析器，因此你可以更轻松地处理日志条目。 +- 尽量在日志条目内提供创建该日志条目的应用的名称。这可以使故障排除更容易。这是因为 Kubernetes 并不总是将应用的名称作为对象名称。例如，某个 Pod ID 可能是 `myapp-098kjhsdf098sdf98`，从这个 ID 中我们不能获取运行在容器内的应用的太多信息。 +- 除了在集群范围内收集所有日志的情况外，尽量严格限定 _Flow_ 和 _ClusterFlow_ 对象的范围。这使得在出现问题时更容易进行故障排除，并且还有助于确保不相关的日志条目不会出现在你的聚合器中。严格限定范围的一个例子是将 _Flow_ 限制在命名空间中的单个 _Deployment_，甚至是 _Pod_ 中的单个容器。 +- 除非要进行故障排除，否则不要让日志太详细。太详细的日志会带来许多问题，其中最主要的是**带来干扰**，即重要事件可能会淹没在海量 `DEBUG` 信息中。你可以通过使用自动告警和脚本来缓解这种问题，但太详细的日志仍然给日志管理基础设施带来过大的压力。 +- 如果可能，尽量在日志条目中提供事务或请求 ID。这可以使跨日志源追踪应用活动变得更容易，尤其是在处理分布式应用时。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/best-practices/rancher-managed-clusters/monitoring-best-practices.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/best-practices/rancher-managed-clusters/monitoring-best-practices.md new file mode 100644 index 00000000000..31e3448f835 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/best-practices/rancher-managed-clusters/monitoring-best-practices.md @@ -0,0 +1,111 @@ +--- +title: 监控最佳实践 +--- + +配置合理的监控和告警规则对于安全、可靠地运行生产环境中的工作负载至关重要。在使用 Kubernetes 和 Rancher 时也是如此。幸运的是，你可以使用集成的监控和告警功能来简化整个过程。 + +[Rancher 监控文档](../../../integrations-in-rancher/monitoring-and-alerting/monitoring-and-alerting.md)描述了如何设置完整的 Prometheus 和 Grafana。这是开箱即用的功能，它将从集群中的所有系统和 Kubernetes 组件中抓取监控数据，并提供合理的仪表板和告警。但为了实现可靠的设置，你还需要监控你的工作负载并使 Prometheus 和 Grafana 适应你的特定用例和集群规模。本文档将为你提供这方面的最佳实践。 + +## 监控内容 + +Kubernetes 本身以及运行在其内部的应用构成了一个分布式系统，不同的组件之间能够进行交互。对于整个系统和每个单独的组件，你必须确保其性能、可用性、可靠性和可扩展性。详情请参见 Google 免费的 [Site Reliability Engineering Book](https://sre.google/sre-book/table-of-contents/)，尤其是关于 [Monitoring distributed systems](https://sre.google/sre-book/monitoring-distributed-systems/) 的章节。 + +## 配置 Prometheus 资源使用 + +在安装集成监控时，Rancher 允许进行一些配置，这些配置取决于你的集群规模和其中运行的工作负载。本章将更详细地介绍这些内容。 + +### 存储和数据保留 + +Prometheus 所需的存储空间取决于你存储的时间序列和标签的数量，以及你配置的数据保留量。需要注意的是，Prometheus 并不是用来长期存储指标的。数据通常只保留几天，而不是几周或几个月。这是因为 Prometheus 不会对存储的指标进行任何聚合。不聚合的好处是避免稀释数据，但这也意味着不设置保留时长的话，所需的存储空间随着时间的推移线性增长。 + +以下是计算所需存储空间的一种方法。首先，通过以下查询来查看 Prometheus 中存储块的平均大小： + +``` +rate(prometheus_tsdb_compaction_chunk_size_bytes_sum[1h]) / rate(prometheus_tsdb_compaction_chunk_samples_sum[1h]) +``` + +接下来，找出每秒的数据引入速率： + +``` +rate(prometheus_tsdb_head_samples_appended_total[1h]) +``` + +然后与保留时间相乘，并添加几个百分点作为缓冲区： + +``` +平均块大小（以字节为单位）x 每秒的数据引入速率 x 保留时间（以秒为单位）x 1.1 = 必需的存储空间（以字节为单位） +``` + +你可以访问[这篇博客](https://www.robustperception.io/how-much-disk-space-do-prometheus-blocks-use)了解关于如何计算必须的存储空间的更多信息。 + +你可以参见 [Prometheus 官方文档](https://prometheus.io/docs/prometheus/latest/storage)来进一步了解 Prometheus 的存储概念。 + +### CPU 和内存的请求和限制 + +在较大的 Kubernetes 集群中，Prometheus 会消耗大量内存。Prometheus 需要的内存与它存储的时间序列和标签的数量以及抓取间隔有关。 + +你可以访问[这篇博客](https://www.robustperception.io/how-much-ram-does-prometheus-2-x-need-for-cardinality-and-ingestion)了解关于如何计算必须的内存的更多信息。 + +所需的 CPU 数量与你正在执行的查询数量相关。 + +### 长期储存 + +Prometheus 不是用于长期存储指标的，它只用于短期存储。 + +如果想要长时间存储部分或全部指标，你可以利用 Prometheus 的[远程读/写](https://prometheus.io/docs/prometheus/latest/storage/#remote-storage-integrations)功能将其连接到 [Thanos](https://thanos.io/)，[InfluxDB](https://www.influxdata.com/) 或 [M3DB](https://www.m3db.io/) 等存储系统。你可以访问[这篇博客](https://rancher.com/blog/2020/prometheus-metric-federation)找到设置示例。 + +## 抓取自定义工作负载 + +虽然集成的 Rancher Monitoring 已经可以从集群的节点和系统组件中抓取系统指标，但你也需要为部署在 Kubernetes 上的自定义工作负载抓取数据。为此，你可以配置 Prometheus，让它在一定的时间间隔内对你应用的端点进行 HTTP 请求。然后，这些端点会以 Prometheus 格式返回指标。 + +一般来说，你会从集群中运行的所有工作负载中抓取数据，然后将数据用于告警或调试问题。一般情况下，你只有在具体事件发生后才需要某些指标数据。如果数据已经被抓取并存储了，那就好办了。由于 Prometheus 只是短期存储指标，因此抓取和存储大量数据的成本并不是那么高。如果你使用的是 Prometheus 的长期存储方案，那么你也可以决定持久存储哪些数据。 + +### 关于 Prometheus Exporters + +许多第三方工作负载（如数据库、队列或 Web 服务器）要么已经支持以 Prometheus 格式公开指标，要么有所谓的 exporter，来对工具的指标格式和 Prometheus 理解的指标格式进行转换。通常，你可以将这些 exporter 作为额外的 Sidecar 容器添加到工作负载的 Pod 中。很多 Helm Chart 已经包含了部署 exporter 的选项。此外，你还可以在 [ExporterHub](https://exporterhub.io/) 上找到一个策划的 exporter 列表。 + +### Prometheus 的编程语言和框架支持 + +要想把你的自定义应用指标放到 Prometheus 中，你必须直接从你的应用代码中收集和暴露这些指标。幸运的是，对于大多数流行的编程语言和框架来说，已经有一些库和集成来帮助解决这个问题。其中一个例子是 [Spring 框架](https://docs.spring.io/spring-metrics/docs/current/public/prometheus)中的 Prometheus 支持。 + +### ServiceMonitor 和 PodMonitor + +一旦所有工作负载都以 Prometheus 格式公开了指标后，你必须配置 Prometheus 来抓取数据。Rancher 使用 [prometheus-operator](https://github.com/prometheus-operator/prometheus-operator)，这使得使用 ServiceMonitors 和 PodMonitors 来添加其他抓取目标变得容易。很多 Helm Chart 已经包含直接创建这些监控器的选项。你也可以在 Rancher 文档中找到更多信息。 + +### Prometheus 推送网关（Pushgateway） + +有些工作负载的指标很难被 Prometheus 抓取，就像 Jobs 和 CronJobs 这样的短期工作负载，或者是不允许在单个处理的传入请求之间共享数据的应用，如 PHP 应用。 + +要想获得这些用例的指标，你可以设置 [prometheus-pushgateways](https://github.com/prometheus/pushgateway)。CronJob 或 PHP 应用将把指标更新推送到 pushgateway。pushgateway 汇总并通过 HTTP 端点暴露它们，然后可以由 Prometheus 抓取。 + +### Prometheus Blackbox 监控 + +有时，你可能需要从外部监控工作负载。为此，你可以使用 [Prometheus blackbox-exporter](https://github.com/prometheus/blackbox_exporter)，它允许通过 HTTP、HTTPS、DNS、TCP 和 ICMP 探测任何类型的端点。 + +## 在（微）服务架构中进行监控 + +如果你有一个（微）服务架构，在该架构中集群的多个单独的工作负载相互通信，那么拥有这些流量的详细指标和跟踪是非常重要的，因为这可以帮助你了解所有这些工作负载之间的通信方式，以及问题或瓶颈可能出现的地方。 + +当然，你可以监控所有工作负载中的所有内部流量，并将这些指标暴露给 Prometheus，但这相当耗费精力。像 Istio 这样的服务网格（可以通过[单击](../../../integrations-in-rancher/istio/istio.md)在 Rancher 中安装）可以自动完成这项工作，并提供所有 Service 之间流量的丰富的遥测数据。 + +## 真实用户监控 + +监控所有内部工作负载的可用性和性能对于稳定、可靠和快速地运行应用至关重要。但这些指标只能向你展示部分情况。要想获得一个完整的视图，还必须知道你的最终用户是如何实际感知的。为此，你可以研究各种[真实用户监控解决方案](https://en.wikipedia.org/wiki/Real_user_monitoring)。 + +## 安全监控 + +除了通过监控工作负载来检测性能、可用性或可扩展性之外，你还应该监控集群和运行在集群中的工作负载，来发现潜在的安全问题。一个好的做法是经常运行 [CIS 扫描](../../../how-to-guides/advanced-user-guides/cis-scan-guides/cis-scan-guides.md)并发出告警，来检查集群是否按照安全最佳实践进行配置。 + +对于工作负载，你可以查看 Kubernetes 和 Container 安全解决方案，例如 [NeuVector](https://www.suse.com/products/neuvector/)、[Falco](https://falco.org/)、[Aqua Kubernetes Security](https://www.aquasec.com/products/kubernetes-security/) 和 [SysDig](https://sysdig.com/)。 + +## 设置告警 + +将所有的指标纳入监控系统并在仪表板中可视化是很好的做法，但你也希望在出现问题时能主动收到提醒。 + +集成的 Rancher 监控已经配置了一套合理的告警，这些告警在任何 Kubernetes 集群中都是可用的。你可以扩展告警，来覆盖特定的工作负载和用例。 + +在设置告警时，你需要为对你应用非常关键的工作负载配置告警，但同时也要确保告警不会太频繁。理想情况下，你收到的每一个告警都应该是一个你需要关注并解决的问题。如果你一直收到不太关键的告警，你就有可能开始完全忽略告警信息，然后错过真正重要的告警。因此，少量的告警可能会更好。首先，你可以关注真正重要的指标，例如应用离线等。之后，解决出现的所有问题，然后再创建更详细的告警。 + +如果告警开始发送，但你暂时无法处理，你也可以将告警静默一定时间，以便以后查看。 + +如果需要了解更多关于如何设置告警和通知通道的信息，请访问 [Rancher 文档中心](../../../integrations-in-rancher/monitoring-and-alerting/monitoring-and-alerting.md)。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/best-practices/rancher-managed-clusters/rancher-managed-clusters-in-vsphere.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/best-practices/rancher-managed-clusters/rancher-managed-clusters-in-vsphere.md new file mode 100644 index 00000000000..de11f24cedd --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/best-practices/rancher-managed-clusters/rancher-managed-clusters-in-vsphere.md @@ -0,0 +1,58 @@ +--- +title: Rancher 管理 vSphere 集群的最佳实践 +--- + +本指南概述了在 vSphere 环境中配置下游 Rancher 集群的参考架构，以及 VMware 记录的标准 vSphere 最佳实践。 + +- [1. 虚拟机注意事项](#1-虚拟机注意事项) +- [2. 网络注意事项](#2-网络注意事项) +- [3. 存储注意事项](#3-存储注意事项) +- [4. 备份和灾难恢复](#4-备份和灾难恢复) + +
解决方案概述
+ +![解决方案概述](/img/solution_overview.drawio.svg) + +## 1. 虚拟机注意事项 + +### 利用虚拟机模板来构建环境 + +为了保证跨环境部署的虚拟机的一致性，你可以考虑使用虚拟机模板形式的黄金镜像（golden image）。你可以使用 Packer 来实现，从而增加更多自定义选项。 + +### 利用 DRS 反亲和规则（可能的话）在 ESXi 主机上分离下游集群节点 + +这样可以确保节点虚拟机分布在多台 ESXi 主机上，从而防止主机级别的单点故障。 + +### 利用 DRS 反亲和规则（可能的话）在 Datastore 上分离下游集群节点 + +这样可以确保节点虚拟机分布在多个 Datastore 上，从而防止 Datastore 级别的单点故障。 + +### 为 Kubernetes 配置合适的虚拟机 + +在部署节点时，请遵循 K8s 和 etcd 的最佳实践，其中包括禁用 swap，检查集群中的所有主机之间是否有良好的网络连接，为每个节点使用唯一的主机名、MAC 地址和 `product_uuids`。 + +## 2. 网络注意事项 + +### 利用 ETCD 节点之间的低延迟和高带宽连接 + +尽可能在单个数据中心内部署 etcd 成员，来避免延迟开销并减少网络分区的可能性。大多数情况下，1Gb 的连接就足够了。对于大型集群，10Gb 的连接可以缩短恢复备份所需的时间。 + +### 为虚拟机提供固定的 IP 地址 + +你可以为使用的所有节点都配置一个静态 IP。如果使用 DHCP，则每个节点都应该有一个 DHCP 预留，以确保节点分配到相同的 IP 地址。 + +## 3. 存储注意事项 + +### 在 ETCD 节点上使用 SSD 磁盘 + +ETCD 对写入延迟非常敏感。因此，你可以尽量使用 SSD 磁盘来提高写入性能。 + +## 4. 备份和灾难恢复 + +### 定期备份下游集群 + +Kubernetes 使用 etcd 来存储其所有数据，包括配置、状态和元数据。在灾难恢复的情况下，备份这些数据是至关重要的。 + +### 备份下游节点虚拟机 + +将 Rancher 下游节点的虚拟机纳入标准的虚拟机备份策略中。 \ No newline at end of file diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/best-practices/rancher-managed-clusters/rancher-managed-clusters.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/best-practices/rancher-managed-clusters/rancher-managed-clusters.md new file mode 100644 index 00000000000..eb6009f41f7 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/best-practices/rancher-managed-clusters/rancher-managed-clusters.md @@ -0,0 +1,27 @@ +--- +title: Rancher 管理集群的最佳实践 +--- + + + + + +## Logging + +有关集群级别日志和应用日志的建议，请参见 [Logging 最佳实践](logging-best-practices.md)。 + +## Monitoring + +配置合理的监控和告警规则对于安全、可靠地运行生产环境中的工作负载至关重要。有关更多建议，请参阅[最佳实践](monitoring-best-practices.md)。 + +### Disconnected clusters + +Rancher supports managing clusters that may not always be online due to network disruptions, control plane availability, or because all cluster nodes are down. Refer to this [guide](disconnected-clusters.md) for our recommendations. + +## 设置容器的技巧 + +配置良好的容器可以极大地提高环境的整体性能和安全性。有关容器设置的建议，请参见[设置容器的技巧](tips-to-set-up-containers.md)。 + +## Rancher 管理 vSphere 集群的最佳实践 + +[Rancher 管理 vSphere 集群的最佳实践](rancher-managed-clusters-in-vsphere.md)概述了在 vSphere 环境中配置下游 Rancher 集群的参考架构，以及 VMware 记录的标准 vSphere 最佳实践。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/best-practices/rancher-managed-clusters/tips-to-set-up-containers.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/best-practices/rancher-managed-clusters/tips-to-set-up-containers.md new file mode 100644 index 00000000000..d368853d2e5 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/best-practices/rancher-managed-clusters/tips-to-set-up-containers.md @@ -0,0 +1,57 @@ +--- +title: 设置容器的技巧 +--- + +配置良好的容器可以极大地提高环境的整体性能和安全性。 + +本文介绍一些设置容器的技巧。 + +如果你需要了解容器安全的详细信息，也可以参见 Rancher 的[容器安全指南](https://rancher.com/complete-guide-container-security)。 + +## 使用通用容器操作系统 + +在可能的情况下，你应该尽量在通用的容器基础操作系统上进行标准化。 + +Alpine 和 BusyBox 等较小的发行版减少了容器镜像的大小，并且通常具有较小的漏洞。 + +流行的发行版如 Ubuntu、Fedora 和 CentOS 等都经过了大量的测试，并提供了更多的功能。 + +## 使用 From scratch 容器 + +如果你的微服务是一个独立的静态二进制，你应该使用 `From scratch` 容器。 + +`FROM scratch` 容器是一个[官方 Docker 镜像](https://hub.docker.com/_/scratch)，它是空的，这样你就可以用它来设计最小的镜像。 + +这个镜像这将具有最小的攻击层和最小的镜像大小。 + +## 以非特权方式运行容器进程 + +在可能的情况下，在容器内运行进程时使用非特权用户。虽然容器运行时提供了隔离，但仍然可能存在漏洞和攻击。如果容器以 root 身份运行，无意中或意外的主机挂载也会受到影响。有关为 Pod 或容器配置安全上下文的详细信息，请参见 [Kubernetes 文档](https://kubernetes.io/docs/tasks/configure-pod-container/security-context/)。 + +## 定义资源限制 + +你应该将 CPU 和内存限制应用到你的 Pod 上。这可以帮助管理 worker 节点上的资源，并避免发生故障的微服务影响其他微服务。 + +在标准 Kubernetes 中，你可以设置命名空间级别的资源限制。在 Rancher 中，你可以设置项目级别的资源限制，项目内的所有命名空间都会继承这些限制。详情请参见 Rancher 官方文档。 + +在设置资源配额时，如果你在项目或命名空间上设置了任何与 CPU 或内存相关的内容（即限制或预留），所有容器都需要在创建期间设置各自的 CPU 或内存字段。为了避免在创建工作负载期间对每个容器设置这些限制，可以在命名空间上指定一个默认的容器资源限制。 + +有关如何在[容器级别](https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container/#resource-requests-and-limits-of-pod-and-container)和命名空间级别设置资源限制的更多信息，请参见 Kubernetes 文档。 + +## 定义资源需求 + +你应该将 CPU 和内存要求应用到你的 Pod 上。这对于通知调度器需要将你的 pod 放置在哪种类型的计算节点上，并确保它不会过度配置该节点资源至关重要。在 Kubernetes 中，你可以通过在 pod 的容器规范的资源请求字段中定义 `resources.requests` 来设置资源需求。详情请参见 [Kubernetes 文档](https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container/#resource-requests-and-limits-of-pod-and-container)。 + +:::note + +如果你为 pod 所部署的命名空间设置了资源限制，而容器没有特定的资源请求，则不允许启动 pod。为了避免在创建工作负载期间对每个容器设置这些字段，可以在命名空间上指定一个默认的容器资源限制。 + +::: + +建议在容器级别上定义资源需求，否则，调度器会认为集群加载对你的应用没有帮助。 + +## 配置存活和就绪探测器 + +你可以为你的容器配置存活探测器和就绪探测器。如果你的容器不是完全崩溃，Kubernetes 是不会知道它是不健康的，除非你创建一个可以报告容器状态的端点或机制。或者，确保你的容器在不健康的情况下停止并崩溃。 + +Kubernetes 文档展示了如何[为容器配置存活和就绪探测器](https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-probes/)。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/best-practices/rancher-server/on-premises-rancher-in-vsphere.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/best-practices/rancher-server/on-premises-rancher-in-vsphere.md new file mode 100644 index 00000000000..efdfde73d91 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/best-practices/rancher-server/on-premises-rancher-in-vsphere.md @@ -0,0 +1,84 @@ +--- +title: 在 vSphere 环境中安装 Rancher +--- + +本指南概述了在 vSphere 环境中在 RKE Kubernetes 集群上安装 Rancher 的参考架构，以及 VMware 记录的标准 vSphere 最佳实践。 + + +
解决方案概述
+ +![解决方案概述](/img/rancher-on-prem-vsphere.svg) + +## 1. 负载均衡器注意事项 + +你需要使用一个负载均衡器将流量转发到 RKE 节点上的 Rancher 工作负载。 + +### 利用容错和高可用性 + +请充分利用具有继承高可用功能的外部（硬件或软件）负载均衡器（如：F5、NSX-T、Keepalived 等）。 + +### 备份负载均衡器配置 + +在灾难恢复时，可用的负载均衡器配置可以加快恢复过程。 + +### 配置健康检查 + +让负载均衡器在健康检查失败时自动将节点标记为不可用。例如，NGINX 可以通过以下配置来实现这一功能： + +`max_fails=3 fail_timeout=5s` + +### 利用外部负载均衡器 + +避免在管理集群内使用软件负载均衡器。 + +### 安全访问 Rancher + +将防火墙/ACL 规则配置为只允许 Rancher 访问。 + +## 2. 虚拟机注意事项 + +### 根据 Rancher 文档确定虚拟机的大小 + +请参阅[安装要求](../../../getting-started/installation-and-upgrade/installation-requirements/installation-requirements.md)。 + +### 利用虚拟机模板来构建环境 + +为了保证跨环境部署的虚拟机的一致性，你可以考虑使用虚拟机模板形式的黄金镜像（golden image）。你可以使用 Packer 来实现，从而增加更多自定义选项。 + +### 利用 DRS 反亲和规则（可能的话）在 ESXi 主机上分离 Rancher 集群节点 + +这样可以确保节点虚拟机分布在多台 ESXi 主机上，从而防止主机级别的单点故障。 + +### 利用 DRS 反亲和规则（可能的话）在 Datastore 上分离 Rancher 集群节点 + +这样可以确保节点虚拟机分布在多个 Datastore 上，从而防止 Datastore 级别的单点故障。 + +### 为 Kubernetes 配置合适的虚拟机 + +在部署节点时，请遵循 K8s 和 etcd 的最佳实践，其中包括禁用 swap，检查集群中的所有主机之间是否有良好的网络连接，为每个节点使用唯一的主机名、MAC 地址和 `product_uuids`。 + +## 3. 网络注意事项 + +### 利用 ETCD 节点之间的低延迟和高带宽连接 + +尽可能在单个数据中心内部署 etcd 成员，来避免延迟开销并减少网络分区的可能性。大多数情况下，1Gb 的连接就足够了。对于大型集群，10Gb 的连接可以缩短恢复备份所需的时间。 + +### 为虚拟机提供固定的 IP 地址 + +你可以为使用的所有节点都配置一个静态 IP。如果使用 DHCP，则每个节点都应该有一个 DHCP 预留，以确保节点分配到相同的 IP 地址。 + +## 4. 存储注意事项 + +### 在 ETCD 节点上使用 SSD 磁盘 + +ETCD 对写入延迟非常敏感。因此，你可以尽量使用 SSD 磁盘来提高写入性能。 + +## 5. 备份和灾难恢复 + +### 定期备份管理集群 + +Rancher 将数据存储在它所在的 Kubernetes 集群的 ETCD datastore 中。与其它 Kubernetes 集群一样，你需要对该集群进行频繁且经过测试的备份。 + +### 备份 Rancher 集群节点虚拟机 + +将 Rancher 管理节点的虚拟机纳入标准的虚拟机备份策略中。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/best-practices/rancher-server/rancher-deployment-strategy.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/best-practices/rancher-server/rancher-deployment-strategy.md new file mode 100644 index 00000000000..8c4d1541296 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/best-practices/rancher-server/rancher-deployment-strategy.md @@ -0,0 +1,36 @@ +--- +title: Rancher 部署策略 +--- + +本文提供 Rancher 实例的两种部署策略，用于管理下游 Kubernetes 集群。每种策略都有优缺点。请按照你的实际情况选择最适合的部署策略。 + +## 中心辐射型策略 +--- + +在中心辐射型部署中，一个 Rancher 实例就可以管理遍布全球的 Kubernetes 集群。Rancher 实例运行在高可用 Kubernetes 集群上，并且会受延迟影响。 + +### 优点 + +* 可以通过一个 controlplane 界面查看所有区域和环境。 +* Kubernetes 不需要 Rancher 进行操作，并且可以容忍与 Rancher 实例断开连接。 + +### 缺点 + +* 受限于网络延迟。 +* 如果 Rancher 出现故障，在恢复之前不可以在全球范围内创建新服务。但是每个 Kubernetes 集群都可以继续单独管理。 + +## 区域型策略 +--- +在区域型部署模型中，Rancher 实例部署在靠近下游 Kubernetes 集群的位置。 + +### 优点 + +* 如果某个区域的 Rancher 实例出现故障，其他区域内的 Rancher 功能仍然可以保持正常。 +* Rancher 和下游集群之间的网络延迟大大降低，提高了 Rancher 的性能。 +* 你可以在每个区域内独立升级 Rancher。 + +### 缺点 + +* 管理多个 Rancher 安装的开销较大。 +* 需要在多个界面中查看不同区域的 Kubernetes 集群。 +* 在 Rancher 中部署多集群应用时，需要在每个 Rancher Server 中重复部署步骤。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/best-practices/rancher-server/rancher-server.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/best-practices/rancher-server/rancher-server.md new file mode 100644 index 00000000000..00202488669 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/best-practices/rancher-server/rancher-server.md @@ -0,0 +1,21 @@ +--- +title: Rancher Server 的最佳实践 +--- + + + + + +本指南介绍了让 Rancher 管理下游 Kubernetes 集群的 Rancher Server 运行建议。 + +## 推荐的架构和基础设施 + +有关在高可用 Kubernetes 集群上设置 Rancher Server 的通用建议，请参见[本指南](tips-for-running-rancher.md)。 + +## 部署策略 + +[本指南](rancher-deployment-strategy.md)旨在帮助你选择部署策略（区域部署/中心辐射型部署），来让 Rancher Server 更好地管理下游 Kubernetes 集群。 + +## 在 vSphere 环境中安装 Rancher + +[本指南](on-premises-rancher-in-vsphere.md)介绍了在 vSphere 环境中安装 Rancher 的参考架构，以及 VMware 记录的标准 vSphere 最佳实践。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/best-practices/rancher-server/tips-for-running-rancher.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/best-practices/rancher-server/tips-for-running-rancher.md new file mode 100644 index 00000000000..3e7a33d3e88 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/best-practices/rancher-server/tips-for-running-rancher.md @@ -0,0 +1,37 @@ +--- +title: Rancher 运行技巧 +--- + +本指南适用于使用 Rancher 管理下游 Kubernetes 集群的用例。高可用设置可以防止 Rancher Server 不可用时无法访问下游集群。 + +高可用 Rancher 安装指将 Rancher 安装到至少有三个节点的 Kubernetes 集群上，适用于所有生产环境以及重要的安装场景。在多个节点上运行多个 Rancher 实例能够实现单节点安装无法提供的高可用性。 + +如果你在 vSphere 环境中安装 Rancher，请参见[最佳实践文档](on-premises-rancher-in-vsphere.md)。 + +在设置高可用 Rancher 安装时，请考虑以下事项。 + +## 在单独的集群上运行 Rancher + +不要在安装了 Rancher 的 Kubernetes 集群上运行其他工作负载或微服务。 + +## 确保 Kubernetes 节点配置正确 + +在部署节点时，请遵循 K8s 和 etcd 的最佳实践，其中包括禁用 swap，检查集群中的所有主机之间是否有良好的网络连接，为每个节点使用唯一的主机名、MAC 地址和 `product_uuids`，检查所需端口是否已经打开，并使用配置 SSD 的 etcd 进行部署。详情请参见 [kubernetes 官方文档](https://kubernetes.io/docs/setup/production-environment/tools/kubeadm/install-kubeadm/#before-you-begin)和 [etcd 性能操作指南](https://etcd.io/docs/v3.5/op-guide/performance/)。 + +## 在同一个数据中心运行集群中的所有节点 + +为达到最佳性能，请在同一地理数据中心运行所有三个节点。如果你在云（如 AWS）上运行节点，请在不同的可用区（AZ）中运行这三个节点。例如，在 us-west-2a 中运行节点 1，在 us-west-2b 中运行节点 2，在 us-west-2c 中运行节点 3。 + +## 保证开发和生产环境的相似性 + +强烈建议为运行 Rancher 的 Kubernetes 集群配备 “staging” 或 “pre-production” 环境。这个环境的软件和硬件配置应该尽可能接近你的生产环境。 + +## 监控集群以规划容量 + +Rancher Server 的 Kubernetes 集群应该尽可能满足[系统和硬件要求](../../../getting-started/installation-and-upgrade/installation-requirements/installation-requirements.md)。越偏离系统和硬件要求，你可能面临的风险就越大。 + +但是，已发布的要求已经考虑了各种工作负载类型，因此，基于指标来规划容量应该是扩展 Rancher 的最佳实践。 + +你可以将 Rancher 集成业界领先的开源监控解决方案 Prometheus 以及能可视化 Prometheus 指标的 Grafana，来监控集群节点、Kubernetes 组件和软件部署的状态和过程。 + +在集群中[启用监控](../../../integrations-in-rancher/monitoring-and-alerting/monitoring-and-alerting.md)后，你可以通过设置告警通知，来了解集群容量的使用情况。你还可以使用 Prometheus 和 Grafana 监控框架，在你扩容时建立关键指标的基线。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/best-practices/rancher-server/tips-for-scaling-rancher.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/best-practices/rancher-server/tips-for-scaling-rancher.md new file mode 100644 index 00000000000..8e98f63729f --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/best-practices/rancher-server/tips-for-scaling-rancher.md @@ -0,0 +1,61 @@ +--- +title: Rancher 扩展技巧 +--- + +本指南介绍了扩展 Rancher 时应该考虑的方法，以及这样做的难度。随着系统的增长，性能自然会降低，但我们可以采取一些措施来最大限度地减少 Rancher 的负载，并优化 Rancher 处理这些大型设置的能力。 + +## 优化 Rancher 性能的技巧 +* 建议及时更新 Rancher 的补丁版本。在次要版本的整个生命周期中，我们都会进行性能改进和错误修复。你可以查看发行说明决定是否需要升级，但在大多数情况下，我们建议你使用最新版本。 + +* 性能会受 Rancher 的基础设施和下游集群的基础设施之间的延迟影响（例如，地理距离）。如果用户需要遍布全球或分布在许多地区的集群/节点，最好使用多个 Rancher。 + +* 请始终尝试逐渐扩大规模，同时监控和观察变化。通常情况下，性能问题越早解决越好，而且在其他问题出现之前更容易解决。 + +## 最小化本地集群的负载 +扩展 Rancher 最大的瓶颈是本地 Kubernetes 集群中的资源增长。local 集群包含所有下游集群的信息。下游集群的许多操作将在 local 集群中创建新对象，并需要使用 local 集群中运行的处理程序进行计算。 + +### 管理对象数量 +ETCD 最终会遇到存储的 Kubernetes 资源数量超过限制的问题。暂时没有这些数字的确切记录。根据内部观察，一旦单个资源类型的对象数量超过 60k（通常是 Rolebindings），就很有可能遇到性能问题。 + +Rolebindings 是在 local 集群中创建的，是许多操作的结果。 + +尝试减少 local 集群中的 rolebindings 时需要注意： +* 仅在必要时将用户添加到集群和项目中 +* 删除不需要的集群和项目 +* 仅在必要时使用自定义角色 +* 在自定义角色中使用尽可能少的规则 +* 考虑给用户添加角色是否多余 +* 使用更少但更强大的集群可能更高效 +* 检查是否能通过创建新项目或新集群为你的用例减少 rolebindings。 + +### 使用新版应用程序而不是旧版应用程序 +Rancher 使用了两个应用程序 kubernetes 资源，分别是 apps.projects.cattle.io 和 apps.cattle.cattle.io。旧版应用程序 apps.projects.cattle.io 最初是在 Cluster Manager 中引入的，现在已经过时。新版应用程序 apps.catalog.cattle.io 可在其各自集群的 Cluster Explorer 中找到。新版应用程序更受欢迎，因为它们位于下游集群中，而旧版应用程序位于 local 集群中。 + +我们建议删除 Cluster Manager 中出现的应用程序，如有必要，可以为目标集群替换为 Cluster Explorer 中的应用程序，并仅在集群的 Cluster Explorer 中创建后续的应用程序。 + +### 使用授权集群端点（ACE） +Rancher 配置的 RKE1、RKE2 和 K3s 集群有一个 _授权集群端点_ 选项。启用后，会在为集群生成的 kubeconfigs 中添加一个上下文，该上下文使用一个直接到集群的端点，并绕过 Rancher。但是，仅启用此选项是不够的。Kubeconfig 的用户需要使用 `kubectl use-context ` 才能开始使用它。 + +如果不使用 ACE，所有 kubeconfig 请求都会先通过 Rancher 进行路由。 + +### 实验功能：减少事件处理程序执行的选项 +Rancher 的大部分逻辑都发生在事件处理程序上。每当更新对象以及启动 Rancher 时，这些事件处理程序都会在对象上运行。此外，当缓存同步时，它们每 15 小时会运行一次。在缩放设置中，由于每个处理程序都会在每个适用对象上运行，因此运行这些计划会消耗巨大的性能。但是，你可以使用 `CATTLE_SYNC_ONLY_CHANGED_OBJECTS` 环境变量来禁用处理程序的这些计划执行。如果在大约 15 小时的间隔内看到资源分配峰值，则此设置可能有帮助。 + +环境变量的值可以是以下选项的逗号分隔列表。这些值指的是控制器的类型（包含和运行处理程序的 struct）及其处理程序。如果将控制器类型添加到变量中，那么该组控制器将无法在重新同步缓存时运行其处理程序。 + +* `mgmt` 指的是只运行在一个 Rancher 节点上的管理控制器。 +* `user` 指的是为每个集群运行的用户控制器。其中一些运行在与管理控制器相同的节点上，而其他则运行在下游集群中。该选项针对前者。 +* `scaled` 指的是在每个 Rancher 节点上运行的缩放控制器。由于缩放处理程序负责的关键功能，因此不建议设置。 + +简而言之，如果你发现 CPU 使用率每 15 小时出现一次峰值，请将 `CATTLE_SYNC_ONLY_CHANGED_OBJECTS` 环境变量添加到你的 Rancher 部署中，其值为 `mgmt,user`。 + +## Rancher 之外的优化 +影响性能的一个重要因素是 local 集群及其配置方式。该集群可能会在 Rancher 运行之前引入瓶颈。当 Rancher 节点出现资源占用过高的情况时，你可以使用 top 命令来判断是 Rancher 还是 Kubernetes 组件在超额消耗资源。 + +### 保持使用最新版本的 Kubernetes +与 Rancher 版本类似，我们建议让你的 kubernetes 集群保持使用最新版本。这将确保你的集群能包含可用的性能增强或错误修复。 + +### 优化 ETCD +[ETCD 性能](https://etcd.io/docs/v3.5/op-guide/performance/)的两个主要瓶颈是磁盘速度和网络速度。对任何一个进行优化都应该能提高性能。有关 ETCD 性能的信息，请参阅 [etcd 性能慢（性能测试和优化）](https://www.suse.com/support/kb/doc/?id=000020100)和[为大型安装调优 etcd](https://docs.ranchermanager.rancher.io/how-to-guides/advanced-user-guides/tune-etcd-for-large-installs)。有关磁盘的信息，你也可以参阅[我们的文档](https://docs.Ranchermanager.Rancher.io/v2.5/pages-for-subheaders/installation-requirements#disks)。 + +理论上，ETCD 集群中的节点越多，由于复制要求 [source](https://etcd.io/docs/v3.3/faq)，它就会越慢。这可能与常见的缩放方法相悖。我们还可以推断，ETCD 的性能将受到节点间距离的反面影响，因为这将减慢网络通信。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/best-practices/rancher-server/tuning-and-best-practices-for-rancher-at-scale.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/best-practices/rancher-server/tuning-and-best-practices-for-rancher-at-scale.md new file mode 100644 index 00000000000..68ae57eae46 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/best-practices/rancher-server/tuning-and-best-practices-for-rancher-at-scale.md @@ -0,0 +1,117 @@ +--- +title: Rancher 大规模部署的调优和最佳实践 +--- + + + + + +本指南介绍了扩容 Rancher 相关场景的最佳实践和调优方法。随着系统规模的不断增长，性能自然会降低，但是可以采取一些步骤将 Rancher 的负载最小化，以优化 Rancher 管理较大基础设施的能力。 + +## 优化 Rancher 性能 + +* 及时升级 Rancher 的 Patch 更新。我们会不断的对 Rancher 进行性能增强和错误修复，最新的 Rancher 版本包含了基于开发人员和用户反馈的所有性能和稳定性的优化改进。 +* 逐渐的执行扩容操作，在操作的过程中观察并监控任何变化，在性能刚出现异常时发现问题并修复，避免其他干扰因素。 +* 尽可能地减少上游 Rancher 集群和下游集群之间的网络延时。需要注意的是，排除掉其他因素，延时与地理距离成正比，如果你的集群或节点分布在全球各地，请考虑改为安装多个 Rancher。 + +## 最小化上游集群的负载 + +在 Rancher 扩容时，一个典型的性能瓶颈是上游（local）Kubernetes 集群的资源增长。上游集群包含所有下游集群的数据信息，许多对下游集群的操作会在上游集群中创建新的对象，并需要在上游集群中进行计算处理。 + +### 最大限度地减少上游集群上的第三方软件 + +大规模运行 Rancher 可能会给内部 Kubernetes 组件（例如 `etcd` 或 `kubeapiserver`）带来大量负载。如果第三方软件干扰了这些组件或 Rancher 的性能，则可能会出现性能问题。 + +每个第三方软件都存在干扰性能的风险。为了防止上游集群出现性能问题，你应该避免运行除 Kubernetes 系统组件和 Rancher 本身之外的任何应用程序或组件。 + +以下类别的软件通常不会干扰 Rancher 或 Kubernetes 系统性能： + * Rancher 内部组件，例如 Fleet + * Rancher 扩展 + * 集群 API 组件 + * CNI 网络插件 + * 云控制器管理器 + * 观察和监控工具（`prometheus-rancher-exporter` 除外） + +除此之外，已发现以下软件会在 Rancher 扩容时影响性能： + * [CrossPlane](https://www.crossplane.io/) + * [Argo CD](https://argoproj.github.io/cd/) + * [Flux](https://fluxcd.io/) + * [prometheus-rancher-exporter](https://github.com/David-VTUK/prometheus-rancher-exporter)（请参阅 [issue 33](https://github.com/David-VTUK/prometheus-rancher-exporter/issues/33)） + +### 管理你的 Object 计数 + +Etcd 是 Kubernetes 和 Rancher 的后端数据库，该数据库可能会遇到单个 Kubernetes 资源类型数量的限制，确切的限制因素各不相同，取决于诸多因素。经验表明，一旦单个资源类型的对象数量超过 60000，通常会出现性能问题，通常该资源类型是 RoleBinding 对象。 + +这在 Rancher 中很常见，因为许多操作会在上游集群中创建新的 RoleBinding 对象。 + +你可以通过以下方法减少上游集群的 `RoleBinding` 数量： +* 减少使用 [Restricted Admin（受限管理员）](../../../how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/global-permissions.md#受限管理员) 角色，改为使用其他角色。 +* 如果你使用了 [外部认证](../../../how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/authentication-config/authentication-config.md)，配置其按组分配角色。 +* 仅在必要情况下将用户添加到集群和项目中。 +* 移除不需要的集群和项目。 +* 仅在必要情况下使用自定义角色。 +* 在自定义角色中，尽可能的减少规则数量。 +* 避免为用户添加多余的角色。 +* 考虑使用数量更少，但性能更强大的集群。 +* Kubernetes 权限始终是 “附加”（允许列表）而不是“减去”（拒绝列表）。尽量减少允许访问集群、项目或命名空间等方面的配置，因为这将导致创建大量的 RoleBinding 对象。 +* 实验一下，创建新项目或集群后，在你的特定用例场景是否表现出更少的 RoleBinding 的效果。 + +### RoleBinding 计数估计 + +预测给定的配置将创建多少个 RoleBinding 对象很复杂，但是以下注意事项可以提供粗略的估算： +* 对于最小的数量估计，请使用公式 `32C + U + 2UaC + 8P + 5Pa`。 + * `C` 是集群数量。 + * `U` 是用户数量。 + * `Ua` 是集群中具有成员资格的用户的平均数量。 + * `P` 是项目总数。 + * `Pa` 是项目中具有成员资格的平均用户数。 +* 受限管理员角色（Restricted Admin）遵循不同的公式，因为具有此角色的每个用户都会额外产生至少 `7C + 2P + 2` 个 `RoleBinding` 对象。 +* * `RoleBinding` 的数量会随着集群、项目和用户的数量线性增加。 + +### 使用新的应用代替旧版应用 + +Rancher 使用两个 Kubernetes 应用程序资源：`apps.projects.cattle.io` 和 `apps.cattle.cattle.io`。以`apps.projects.cattle.io` 为代表的旧版应用程序在低版本的 Cluster Manager UI 中引入，现已弃用。新的应用程序（由 `apps.catalog.cattle.io` 表示）可以在 Cluster Explorer UI 中安装部署。新的 `apps.cattle.cattle.io` 应用程序数据保存在下游集群中，这可以减少上游集群中的资源数量。 + +你应当删除 Cluster Manager UI 中遗留的所有旧版应用程序，并将其替换为 Cluster Explorer UI 中的应用程序。只在 Cluster Explorer UI 中创建任何新应用程序。 + +### 使用授权集群端点 (ACE) + +[授权集群端点](../../../reference-guides/rancher-manager-architecture/communicating-with-downstream-user-clusters.md#4-授权集群端点) (ACE) 提供了 Rancher 部署的 RKE2 和 K3s 集群的 Kubernetes API 访问。启用后，ACE 会为生成的 `kubeconfig` 文件配置直接访问下游集群 Endpoint，从而绕过 Rancher 代理。在可以直接访问下游集群 Kubernetes API 的场景下，可以减少 Rancher 负载。有关更多信息，请参阅[授权集群端点](../../../reference-guides/rancher-manager-architecture/communicating-with-downstream-user-clusters.md#4-授权集群端点)配置说明。 + +### 减少 Event Handler 执行 + +Rancher 的大部分逻辑发生在 Event Handler 上。每当资源对象产生更新或 Rancher 启动时，这些资源对应的 Event Handler 都会执行。除此之外，它们会每隔 15 小时在 Rancher 计划的同步缓存时再运行一次，这可能会导致 Rancher 运行过程中出现大量性能消耗。可使用 `CATTLE_SYNC_ONLY_CHANGED_OBJECTS` 环境变量禁用计划的 Handler 处理程序执行。如果每 15 小时出现一次性能资源高峰，此设置会有所帮助。 + +`CATTLE_SYNC_ONLY_CHANGED_OBJECTS` 的值可被设置为以下内容，以逗号分隔。这些值代表了处理程序的种类，将处理程序添加到该变量会禁止其在定期的缓存重新同步过程中运行。 + +* `mgmt`：在 Rancher 节点上运行的 Management 管理控制器。 +* `user`：所有集群运行的用户控制器。其中一部分与 Management 管理控制器运行在同一节点上，而另一部分运行在下游集群中，该选项针对的是前者。 +* `scaled`：每个 Rancher 节点上运行的规模控制器。因规模控制器负责关键功能，应当避免设置此值。如果设置可能会破坏集群稳定。 + +简而言之，如果你发现 CPU 使用率每 15 小时出现一次峰值，请将 `CATTLE_SYNC_ONLY_CHANGED_OBJECTS` 环境变量添加到 Rancher Deployment 中（添加至 `spec.containers.env` 列表），其值为 `mgmt,user`。 + +## Rancher 之外的优化 + +集群底层自身的配置也是影响性能的重要因素。如果上游集群存在错误配置，会带来 Rancher 软件所无法解决的性能瓶颈。 + +### 使用 RKE2 直接管理上游集群节点 + +由于 Rancher 对上游集群的要求非常高，尤其是在大规模部署场景，你需要拥有上游集群和节点的所有管理员权限，要找出资源消耗过高的根本原因，请使用标准的 Linux 故障排除工具，这有助于区分是 Rancher、Kubernetes 还是操作系统组件出现的问题。 + +尽管托管 Kubernetes 服务使部署和运行 Kubernetes 集群变得更加容易，但在大规模场景中，不鼓励将其用于上游集群。 托管 Kubernetes 服务通常会限制对单个节点和服务配置的访问。 + +建议在大规模用例场景中使用 RKE2 集群。 + +### 及时更新 Kubernetes 版本 + +你应当及时更新上游集群的 Kubernetes 版本，以确保你的集群具备最新的性能增强和问题修复。 + +### 优化 Etcd + +Etcd 是 Kubernetes 和 Rancher 的后端数据库，在 Rancher 性能中扮演重要的角色。 + +[Etcd 性能](https://etcd.io/docs/v3.5/op-guide/performance/)的两个主要瓶颈是磁盘和网络速度。Etcd 应当在具有高速网络和高读写速度 (IOPS) SSD 硬盘的专用节点上运行。有关 etcd 性能的更多信息，请参阅 [etcd 性能缓慢（性能测试和优化）](https://www.suse.com/support/kb/doc/?id=000020100)和[为大型安装进行 etcd 调优](../../../how-to-guides/advanced-user-guides/tune-etcd-for-large-installs.md)。有关磁盘的信息可以在[安装要求](../../../getting-started/installation-and-upgrade/installation-requirements/installation-requirements.md#磁盘)中找到。 + +根据 etcd 的[复制机制](https://etcd.io/docs/v3.5/faq/#what-is-maximum-cluster-size)，建议在三个节点上运行 etcd，运行在更多的节点上反而会降低速度。 + +Etcd 性能也会受节点之间的网络延迟影响，因此 etcd 节点应与 Rancher 节点部署在一起。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/cli-with-rancher/cli-with-rancher.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/cli-with-rancher/cli-with-rancher.md new file mode 100644 index 00000000000..51f50ec2dca --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/cli-with-rancher/cli-with-rancher.md @@ -0,0 +1,9 @@ +--- +title: Rancher CLI +--- + + + + + +Rancher CLI 是一个命令行工具，用于在工作站中与 Rancher 进行交互。以下文档将描述 [Rancher CLI](rancher-cli.md) 和 [kubectl实用程序](kubectl-utility.md)。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/cli-with-rancher/kubectl-utility.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/cli-with-rancher/kubectl-utility.md new file mode 100644 index 00000000000..28315bf813d --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/cli-with-rancher/kubectl-utility.md @@ -0,0 +1,32 @@ +--- +title: kubectl 实用程序 +--- + +## kubectl + +kubectl 用于与 Rancher 进行交互。 + +### kubectl 实用程序 + +安装 `kubectl`。详情请参见[安装 kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/)。 + +要配置 kubectl，通过 Rancher Web UI 访问你的集群，单击 `Kubeconfig`，然后复制内容并将其粘贴到你的 `~/.kube/config` 文件中。 + +检查是否可以成功运行 `kubectl cluster-info` 或 `kubectl get pods` 命令。 + +### 使用 kubectl 和 kubeconfig 令牌进行 TTL 认证 + +_要求_ + +如果管理员[关闭了 kubeconfig 令牌生成](../../api/api-tokens.md#在生成的-kubeconfig-中禁用令牌)，当你运行 `kubectl` 时，kubeconfig 文件需要 [Rancher CLI](./rancher-cli.md) 存在于你的 PATH 中。否则，你会看到这样的错误信息： +`Unable to connect to the server: getting credentials: exec: exec: "rancher": executable file not found in $PATH`。 + +该功能可以让 kubectl 与 Rancher Server 进行身份验证，并在需要时获得新的 kubeconfig token。目前支持以下验证提供程序： + +1. 本地 +2. Active Directory (仅限 LDAP) +3. FreeIPA +4. OpenLDAP +5. SAML 身份提供商：Ping，Okta，ADFS，Keycloak 和 Shibboleth + +如果你是第一次运行 kubectl（例如，`kubectl get pods`），它会要求你选择一个验证提供程序并使用 Rancher Server 登录。kubeconfig token 会被缓存到 `./.cache/token` 下你运行 kubectl 的路径中。该 Token 在[过期](../../api/api-tokens.md#在生成的-kubeconfig-中禁用令牌)或[从 Rancher Server 删除](../../api/api-tokens.md#删除令牌)之前都是有效的。过期后，下一个 `kubectl get pods` 命令会要求你再次使用 Rancher Server 登录。 \ No newline at end of file diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/cli-with-rancher/rancher-cli.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/cli-with-rancher/rancher-cli.md new file mode 100644 index 00000000000..01a9552e4bc --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/cli-with-rancher/rancher-cli.md @@ -0,0 +1,91 @@ +--- +title: Rancher CLI +description: Rancher CLI 是一个命令行工具，用于在工作站中与 Rancher 进行交互。 +--- + + + + + +Rancher CLI（命令行界面）是一个命令行工具，可用于与 Rancher 进行交互。使用此工具，你可以使用命令行而不用通过 GUI 来操作 Rancher。 + +## 下载 Rancher CLI + +你可以直接 UI 下载二进制文件。 + +1. 点击左上角的 **☰**。 +1. 在导航侧边栏菜单底部，单击Rancher的版本号。 +1. 在 **CLI 下载**中，有 Windows、Mac 和 Linux 的二进制文件下载链接。你还可以访问我们的 CLI [发布页面](https://github.com/rancher/cli/releases)直接下载二进制文件。 + +## 要求 + +下载 Rancher CLI 后，你需要进行一些配置。Rancher CLI 需要： + +- 你的 Rancher Server URL，用于连接到 Rancher Server。 +- API 持有者令牌（Bearer Token），用于向 Rancher 进行身份验证。有关获取持有者令牌的更多信息，请参阅[创建 API 密钥](../user-settings/api-keys.md)。 + +## CLI 身份验证 + +在使用 Rancher CLI 控制你的 Rancher Server 之前，你必须使用 API 持有者令牌进行身份验证。运行以下命令进行登录（将 `` 和 `` 替换为你的实际信息）： + +```bash +$ ./rancher login https:// --token +``` + +如果 Rancher Server 使用自签名证书，Rancher CLI 会提示你继续连接。 + +## 项目选择 + +在执行命令之前，你必须先选择一个 Rancher 项目来执行这些命令。要选择[项目](../../how-to-guides/new-user-guides/manage-clusters/projects-and-namespaces.md)，请运行 `./rancher context switch` 命令。输入此命令后，会显示可用项目的列表。输入一个数字以选择项目。 + +**示例：`./rancher context switch` 输出** +``` +User:rancher-cli-directory user$ ./rancher context switch +NUMBER CLUSTER NAME PROJECT ID PROJECT NAME +1 cluster-2 c-7q96s:p-h4tmb project-2 +2 cluster-2 c-7q96s:project-j6z6d Default +3 cluster-1 c-lchzv:p-xbpdt project-1 +4 cluster-1 c-lchzv:project-s2mch Default +Select a Project: +``` + +输入数字后，控制台会显示你所选项目的消息。 + +``` +INFO[0005] Setting new context to project project-1 +INFO[0005] Saving config to /Users/markbishop/.ranchcli2.json +``` + +请确保你可以成功运行 `rancher kubectl get pods`。 + +## 命令 + +以下命令可用于 Rancher CLI： + +| 命令 | 结果 | +|---|---| +| `apps, [app]` | 对商店应用（即单个 [Helm Chart](https://docs.helm.sh/developing_charts/)）或 Rancher Chart 执行操作。 | +| `catalog` | 对[应用商店](../../how-to-guides/new-user-guides/helm-charts-in-rancher/helm-charts-in-rancher.md)执行操作。 | +| `clusters, [cluster]` | 对[集群](../../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/kubernetes-clusters-in-rancher-setup.md)执行操作。 | +| `context` | 在 Rancher [项目](../../how-to-guides/new-user-guides/manage-clusters/projects-and-namespaces.md)之间切换。有关示例，请参阅[项目选择](#项目选择)。 | +| `inspect [OPTIONS] [RESOURCEID RESOURCENAME]` | 显示 [Kubernetes 资源](https://kubernetes.io/docs/reference/kubectl/cheatsheet/#resource-types)或 Rancher 资源（即[项目](../../how-to-guides/new-user-guides/manage-clusters/projects-and-namespaces.md)和[工作负载](../../how-to-guides/new-user-guides/kubernetes-resources-setup/workloads-and-pods/workloads-and-pods.md)）的详细信息。按名称或 ID 指定资源。 | +| `kubectl` | 运行 [kubectl 命令](https://kubernetes.io/docs/reference/kubectl/overview/#operations)。 | +| `login, [l]` | 登录 Rancher Server。有关示例，请参阅 [CLI 身份验证](#cli-身份验证)。 | +| `namespaces, [namespace]` | 执行命名空间操作。 | +| `nodes, [node]` | 执行节点空间操作。 | +| `projects, [project]` | 执行[项目](../../how-to-guides/new-user-guides/manage-clusters/projects-and-namespaces.md)操作。 | +| `ps` | 显示项目中的[工作负载](../../how-to-guides/new-user-guides/kubernetes-resources-setup/workloads-and-pods/workloads-and-pods.md)。 | +| `settings, [setting]` | 显示 Rancher Server 的当前设置。 | +| `ssh` | 使用 SSH 协议连接到你的某个集群节点。 | +| `help, [h]` | 显示命令列表或某个命令的帮助。 | + + +## Rancher CLI 帮助 + +使用 CLI 登录 Rancher Server 后，输入 `./rancher --help` 以获取命令列表。 + +所有命令都支持 `--help` 标志，该标志解释了每个命令的用法。 + +## 限制 + +Rancher CLI **不能**用于安装[仪表板应用程序或 Rancher 功能 Chart](../../how-to-guides/new-user-guides/helm-charts-in-rancher/helm-charts-in-rancher.md)。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/cluster-configuration/cluster-configuration.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/cluster-configuration/cluster-configuration.md new file mode 100644 index 00000000000..8add5f0520a --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/cluster-configuration/cluster-configuration.md @@ -0,0 +1,31 @@ +--- +title: 集群配置 +--- + + + + + +使用 Rancher 配置 Kubernetes 集群后，你仍然可以编辑集群的选项和设置。 + +有关编辑集群成员资格的信息，请转至[此页面](../../how-to-guides/new-user-guides/manage-clusters/access-clusters/add-users-to-clusters.md)。 + +## 集群配置参考 + +集群配置选项取决于 Kubernetes 集群的类型： + +- [RKE2 集群配置](rancher-server-configuration/rke2-cluster-configuration.md) +- [K3s 集群配置](rancher-server-configuration/k3s-cluster-configuration.md) +- [EKS 集群配置](rancher-server-configuration/eks-cluster-configuration.md) +- [GKE 集群配置](rancher-server-configuration/gke-cluster-configuration/gke-cluster-configuration.md) +- [AKS 集群配置](rancher-server-configuration/aks-cluster-configuration.md) + +## 不同类型集群的管理功能 + +对于已有集群而言，可提供的选项和设置取决于你配置集群的方法。 + +下表总结了每一种类型的集群和对应的可编辑的选项和设置： + +import ClusterCapabilitiesTable from '../../shared-files/_cluster-capabilities-table.md'; + + diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/cluster-configuration/downstream-cluster-configuration/downstream-cluster-configuration.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/cluster-configuration/downstream-cluster-configuration/downstream-cluster-configuration.md new file mode 100644 index 00000000000..684f10d8157 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/cluster-configuration/downstream-cluster-configuration/downstream-cluster-configuration.md @@ -0,0 +1,9 @@ +--- +title: 下游集群配置 +--- + + + + + +以下文档将讨论[主机配置](machine-configuration/machine-configuration.md)。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/cluster-configuration/downstream-cluster-configuration/machine-configuration/amazon-ec2.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/cluster-configuration/downstream-cluster-configuration/machine-configuration/amazon-ec2.md new file mode 100644 index 00000000000..656430783c5 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/cluster-configuration/downstream-cluster-configuration/machine-configuration/amazon-ec2.md @@ -0,0 +1,80 @@ +--- +title: EC2 主机配置参考 +--- + +有关 EC2 和节点的更多详细信息，请参阅 [EC2 管理控制台](https://aws.amazon.com/ec2)的官方文档。 + +## Machine Pools + +### 区域 + +构建集群的地理[区域](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-regions-availability-zones.html)。 + +### 地区 + +[地区](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-regions-availability-zones.html#concepts-availability-zones)，一个区域内用于构建集群的隔离位置。 + +### 实例类型 + +[实例类型](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/instance-types.html)用于配置集群，能确定硬件特性。 + +### 根磁盘大小 + +配置[根设备](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/RootDeviceStorage.html)的大小（以 GB 为单位）。 + +### VPC/子网 + +[VPC](https://docs.aws.amazon.com/vpc/latest/userguide/configure-your-vpc.html) 或特定的[子网](https://docs.aws.amazon.com/vpc/latest/userguide/configure-subnets.html)（VPC 中的一个 IP 范围），用于添加你的资源。 + +### IAM 实例配置文件名称 + +示例配置文件的名称，用于将 IAM 角色传递给 EC2 实例。 + +## 高级选项 + +### AMI ID + +用于集群中节点的 [Amazon Machine Image（AMI）](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/AMIs.html)。 + +### 用于 AMI 的 SSH 用户名 + +用于连接到你启动的实例的用户名。有关选定 AMI 的默认用户名，请参阅[此处](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/connection-prereqs.html)。对于未列出的 AMI，请咨询 AMI 提供商。 + +### 安全组 + +选择默认安全组或配置安全组。 + +请参考[使用主机驱动时的 Amazon EC2 安全组](../../../../getting-started/installation-and-upgrade/installation-requirements/port-requirements.md#rancher-aws-ec2-安全组)，了解 `rancher-nodes` 安全组中创建的规则。 + +### EBS 根卷类型 + +用于根设备的 [EBS 卷类型](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ebs-volume-types.html)。 + +### 加密 EBS 卷 + +启用 [Amazon EBS 加密](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/EBSEncryption.html)。 + +### 请求 Spot 实例 + +开启[请求 Spot 实例](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/spot-requests.html)选项，并指定你愿意支付的最高实例价格（每小时）。 + +### 仅使用私有地址 + +启用仅使用[私人地址](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-instance-addressing.html)的选项。 + +### EBS 优化实例 + +使用 [EBS 优化实例](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ebs-optimized.html)。 + +### 允许访问 EC2 元数据 + +启用对 [EC2 元数据](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-instance-metadata.html)的访问。 + +### 为元数据使用 Token + +使用 [Instance Metadata Service Version 2 (IMDSv2)](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/configuring-instance-metadata-service.html)，即基于令牌访问元数据的方法。 + +### 添加标签 + +使用[标签](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/Using_Tags.html)添加元数据，从而对资源进行分类。 + diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/cluster-configuration/downstream-cluster-configuration/machine-configuration/azure.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/cluster-configuration/downstream-cluster-configuration/machine-configuration/azure.md new file mode 100644 index 00000000000..6abf01e5e2e --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/cluster-configuration/downstream-cluster-configuration/machine-configuration/azure.md @@ -0,0 +1,122 @@ +--- +title: Azure 主机配置 +--- + +有关 Azure 的更多信息，请参阅官方 [Azure 文档](https://docs.microsoft.com/en-us/azure/?product=featured)。 + +## Machine Pools + +### 环境 + +Microsoft 提供了多个[云](https://docs.microsoft.com/en-us/cli/azure/cloud?view=azure-cli-latest)来满足地区法律的要求： + +- AzurePublicCloud +- AzureGermanCloud +- AzureChinaCloud +- AzureUSGovernmentCloud + +### 位置 + +配置集群和节点的[位置](https://docs.microsoft.com/en-us/azure/virtual-machines/regions)。 + +### 资源组 + +资源组是一个容器，其中包含 Azure 解决方案的相关资源。资源组可以包括解决方案的所有资源，或者仅包括你希望作为一个组来管理的资源。你可以根据组织的需求来决定如何将资源分配给资源组。通常情况下，你可以将生命周期相同的资源添加到同一个资源组，以便轻松地按组进行部署、更新和删除。 + +你可以使用现有资源组，也可以输入资源组的名称，然后系统将为你创建一个资源组。 + +有关管理资源组的信息，请参阅 [Azure 文档](https://docs.microsoft.com/en-us/azure/azure-resource-manager/management/manage-resource-groups-portal)。 + +### 可用性集（非托管） + +要添加 VM 的现有[可用性集](https://docs.microsoft.com/en-us/azure/virtual-machines/availability-set-overview)的名称或 ID。 + +### 镜像 + +作为 ARM 资源标识符提供的操作系统镜像的名称。需要使用托管磁盘。 + +### 虚拟机大小 + +为节点池中的每个 VM 选择一个大小。有关每个 VM 大小的详细信息，请参阅[此页面](https://azure.microsoft.com/en-us/pricing/details/virtual-machines/linux/)。 + +## 高级选项 + +### 容错域数量 + +容错域定义了共享公共电源和网络交换机的虚拟机组。如果可用性集已创建，将忽略容错域数量。 + +有关容错域的更多信息，请参阅[此处](https://docs.microsoft.com/en-us/azure/virtual-machines/availability-set-overview#how-do-availability-sets-work)。 + +### 更新域数量 + +更新域表示可以同时重新启动的虚拟机组和底层物理硬件。如果可用性集已创建，将忽略更新域数量。 + +有关更新域的更多信息，请参阅[此处](https://docs.microsoft.com/en-us/azure/virtual-machines/availability-set-overview#how-do-availability-sets-work)。 + +### 购买计划 + +Azure 市场中的某些 VM 镜像需要购买计划。如果适用，请为你选择的镜像选择格式为 `publisher:product:plan` 的购买计划。 + +### 子网 + +创建新 VNet 或引用现有 VNet 时的子网名称。 + +默认值：`docker-machine` + +### 子网前缀 + +创建 CIDR 格式的新 VNet 时要使用的子网 IP 地址前缀。 + +默认值：`192.168.0.0/16` + +### 虚拟网络 + +要使用或创建的[虚拟网络](https://docs.microsoft.com/en-us/azure/virtual-network/virtual-networks-overview)（如果不存在）。格式为 `[resourcegroup:]name`。 + +### 公共 IP 选项 + +#### 没有公共 IP + +不要分配公共 IP 地址。 + +#### 静态公共 IP + +分配静态公共 IP 地址。 + +### 使用私有 IP + +使用静态私有 IP 地址。 + +### 私有 IP 地址 + +配置要使用的静态私有 IP 地址。 + +### 网络安全组 + +要使用的[网络安全组（NSG）](https://docs.microsoft.com/en-us/azure/virtual-network/network-security-groups-overview)。使用此模板的所有节点都将使用配置的网络安全组。如果没有配置网络安全组，则为每个节点创建一个新的网络安全组。 + +### DNS 标签 + +公共 IP 地址的唯一 DNS 名称标签。 + +### 储存类型 + +用于 VM 的[存储账号](https://docs.microsoft.com/en-us/azure/storage/common/storage-account-overview)类型。可选项包括 Standard LRS、Standard ZRS、Standard GRS、Standard RAGRS 和 Premium LRS。 + +### 使用托管磁盘 + +[Azure 托管磁盘](https://docs.microsoft.com/en-us/azure/virtual-machines/managed-disks-overview)是由 Azure 管理并与 Azure Virtual Machines 一起使用的块级存储卷。托管磁盘旨在实现 99.999% 的高可用性。托管磁盘通过提供三个数据副本来实现高可用性和高持续性。 + +### 托管磁盘大小 + +每个节点的磁盘大小（以 GB 为单位）。 + +### SSH 用户名 + +用于 SSH 连接到节点的用户名。 + +### 开放端口 + +打开指定端口上的入站流量。如果你使用现有的网络安全组，将忽略开放端口。 + +默认值：`2379/tcp, 2380/tcp, 6443/tcp, 9796/tcp, 10250/tcp, 10251/tcp, 10252/tcp, 10256/tcp` 和 `8472/udp, 4789/udp` \ No newline at end of file diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/cluster-configuration/downstream-cluster-configuration/machine-configuration/digitalocean.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/cluster-configuration/downstream-cluster-configuration/machine-configuration/digitalocean.md new file mode 100644 index 00000000000..16cb5d9f12f --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/cluster-configuration/downstream-cluster-configuration/machine-configuration/digitalocean.md @@ -0,0 +1,35 @@ +--- +title: DigitalOcean 主机配置 +--- + +有关 DigitalOcean、Droplet 的更多详细信息，请参阅[官方文档](https://docs.digitalocean.com/products/compute/)。 + +## Machine Pools + +### 区域 + +配置创建 Droplet 的[区域](https://docs.digitalocean.com/glossary/region/)。 + +### 大小 + +配置 Droplet 的[大小](https://docs.digitalocean.com/products/droplets/resources/choose-plan/)。 + +### 操作系统镜像 + +配置用于创建 Droplet 的操作系统[镜像](https://docs.digitalocean.com/products/images/)。 + +### Monitoring + +启用 DigitalOcean 代理以进行额外的[监控](https://docs.digitalocean.com/products/monitoring/)。 + +### IPv6 + +为 Droplet 启用 IPv6。 + +### 私有网络 + +为 Droplet 启用私有网络。 + +### Droplet 标签 + +将标签（tag, label）应用于 Droplet。标签只能包含字母、数字、冒号、破折号和下划线。例如，`my_server`。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/cluster-configuration/downstream-cluster-configuration/machine-configuration/machine-configuration.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/cluster-configuration/downstream-cluster-configuration/machine-configuration/machine-configuration.md new file mode 100644 index 00000000000..7669ec23377 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/cluster-configuration/downstream-cluster-configuration/machine-configuration/machine-configuration.md @@ -0,0 +1,9 @@ +--- +title: 主机配置 +--- + + + + + +主机配置指的是如何将资源分配给虚拟机。请参阅 [Amazon EC2](amazon-ec2.md)、[DigitalOcean](digitalocean.md) 和 [Azure](azure.md) 的文档以了解更多信息。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/cluster-configuration/downstream-cluster-configuration/node-template-configuration/amazon-ec2.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/cluster-configuration/downstream-cluster-configuration/node-template-configuration/amazon-ec2.md new file mode 100644 index 00000000000..903a5550f63 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/cluster-configuration/downstream-cluster-configuration/node-template-configuration/amazon-ec2.md @@ -0,0 +1,47 @@ +--- +title: EC2 节点模板配置 +--- + +有关 EC2 和节点的更多详细信息，请参阅 [EC2 管理控制台](https://aws.amazon.com/ec2)的官方文档。 + +## 区域 + +在**区域**字段中，选择创建云凭证时使用的同一区域。 + +## 云凭证 + +你的 AWS 账户访问信息，存储在[云凭证](../../../user-settings/manage-cloud-credentials.md)中。 + +请参阅 [Amazon 文档：创建访问密钥](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html#Using_CreateAccessKey)来创建访问密钥和密文密钥。 + +请参阅 [Amazon 文档：创建 IAM 策略（控制台）](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_create.html#access_policies_create-start)来创建 IAM 策略。 + +请参阅 [Amazon 文档：为用户添加权限（控制台）](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users_change-permissions.html#users_change_permissions-add-console)了解如何绑定 IAM。 + +参阅下面的三个示例 JSON 策略： + +- [IAM 策略示例](../../../../how-to-guides/new-user-guides/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/create-an-amazon-ec2-cluster.md#iam-策略示例) +- [带有 PassRole 的 IAM 策略示例](../../../../how-to-guides/new-user-guides/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/create-an-amazon-ec2-cluster.md#带有-passrole-的-iam-策略示例)（如果要使用 [Kubernetes 云提供商](../../../../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-cloud-providers/set-up-cloud-providers.md)，或将 IAM 配置文件传递给实例，则需要） +- [允许用户加密 EBS 卷的 IAM 策略示例](../../../../how-to-guides/new-user-guides/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/create-an-amazon-ec2-cluster.md#允许加密-ebs-卷的-iam-策略示例) + +## 验证和配置节点 + +为集群选择可用区和网络设置。 + +## 安全组 + +选择默认安全组或配置安全组。 + +请参考[使用主机驱动时的 Amazon EC2 安全组](../../../../getting-started/installation-and-upgrade/installation-requirements/port-requirements.md#rancher-aws-ec2-安全组)，了解 `rancher-nodes` 安全组中创建的规则。 + +如果你自行为 EC2 实例提供安全组，Rancher 不会对其进行修改。因此，你需要让你的安全组允许 [Rancher 配置实例所需的端口](../../../../getting-started/installation-and-upgrade/installation-requirements/port-requirements.md#rke2-上-rancher-server-节点的端口)。有关使用安全组控制 EC2 实例的入站和出站流量的更多信息，请参阅[这里](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_SecurityGroups.html#WorkingWithSecurityGroups)。 + +## 实例选项 + +配置要创建的实例。确保为 AMI 配置正确的 **SSH 用户**。所选的区域可能不支持默认实例类型。在这种情况下，你必须选择一个确实存在的实例类型。否则将出现错误，表示请求的配置不受支持。 + +如果需要传递 **IAM 示例配置名称**（不是 ARN），例如要使用 [Kubernetes 云提供商](../../../../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-cloud-providers/set-up-cloud-providers.md)时，策略则需要其他权限。有关示例策略，请参阅[带有 PassRole 的 IAM 策略示例](../../../../how-to-guides/new-user-guides/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/create-an-amazon-ec2-cluster.md#带有-passrole-的-iam-策略示例)。 + +## 引擎选项 + +在节点模板的**引擎选项**中，你可以配置容器 daemon。你可能需要指定容器版本或容器镜像仓库 Mirror。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/cluster-configuration/downstream-cluster-configuration/node-template-configuration/azure.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/cluster-configuration/downstream-cluster-configuration/node-template-configuration/azure.md new file mode 100644 index 00000000000..25531ce9a1c --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/cluster-configuration/downstream-cluster-configuration/node-template-configuration/azure.md @@ -0,0 +1,33 @@ +--- +title: Azure 节点模板配置 +--- + +有关 Azure 的更多信息，请参阅官方 [Azure 文档](https://docs.microsoft.com/en-us/azure/?product=featured)。 + +账户访问信息存储在云凭证中。云凭证存储在 Kubernetes 密文中。多个节点模板可以使用相同的云凭证。你可以使用现有的云凭证或创建新的凭证。 + +- **Placement** 设置托管集群的地理区域以及其他位置元数据。 +- **Network** 配置集群中使用的网络。 +- **Instance** 自定义你的 VM 配置。 + + :::note + + 如果在与 VM 不同的资源组中使用 VNet，则 VNet 名称需要以资源组名称作为前缀。例如，`:`。 + + ::: + +如果你使用 Docker，[Docker daemon](https://docs.docker.com/engine/docker-overview/#the-docker-daemon) 配置选项包括： + +- **标签**：有关标签的信息，请参阅 [Docker 对象标签文档](https://docs.docker.com/config/labels-custom-metadata/)。 +- **Docker 引擎安装 URL**：确定要在实例上安装的 Docker 版本。 + + :::note + + 如果要配置 Red Hat Enterprise Linux (RHEL) 或 CentOS 节点，请将 **Docker Install URL** 字段保留为默认值，或选择 **none**。由于 Docker 已经安装在这些节点上，因此将绕过 Docker 安装检查。 + + 如果没有将 **Docker Install URL** 设置为默认值或 **none**，你可能会看到错误消息：`Error creating machine: RHEL ssh command error: command: sudo -E yum install -y curl err: exit status 1 output: Updating Subscription Management repositories`。 + + ::: + +- **镜像仓库 mirror**：Docker daemon 使用的 Docker 镜像仓库镜像。 +- **其他高级选项**：参见 [Docker daemon 选项参考](https://docs.docker.com/engine/reference/commandline/dockerd/)。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/cluster-configuration/downstream-cluster-configuration/node-template-configuration/digitalocean.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/cluster-configuration/downstream-cluster-configuration/node-template-configuration/digitalocean.md new file mode 100644 index 00000000000..141c2973e0f --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/cluster-configuration/downstream-cluster-configuration/node-template-configuration/digitalocean.md @@ -0,0 +1,18 @@ +--- +title: DigitalOcean 节点模板配置 +--- + +账户访问信息存储在云凭证中。云凭证存储在 Kubernetes 密文中。多个节点模板可以使用相同的云凭证。你可以使用现有的云凭证或创建新的凭证。 + +## Droplet 选项 + +**Droplet 选项**用于配置集群的地理区域和规范。 + +## Docker Daemon + +如果你使用 Docker，[Docker daemon](https://docs.docker.com/engine/docker-overview/#the-docker-daemon) 配置选项包括： + +- **标签**：有关标签的信息，请参阅 [Docker 对象标签文档](https://docs.docker.com/config/labels-custom-metadata/)。 +- **Docker 引擎安装 URL**：确定要在实例上安装的 Docker 版本。 +- **镜像仓库 mirror**：Docker daemon 使用的 Docker 镜像仓库镜像。 +- **其他高级选项**：参见 [Docker daemon 选项参考](https://docs.docker.com/engine/reference/commandline/dockerd/)。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/cluster-configuration/downstream-cluster-configuration/node-template-configuration/node-template-configuration.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/cluster-configuration/downstream-cluster-configuration/node-template-configuration/node-template-configuration.md new file mode 100644 index 00000000000..35779a5d3ae --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/cluster-configuration/downstream-cluster-configuration/node-template-configuration/node-template-configuration.md @@ -0,0 +1,9 @@ +--- +title: 节点模板配置 +--- + + + + + +要了解节点模板配置，请参阅[EC2 节点模板配置](amazon-ec2.md)、[DigitalOcean 节点模板配置](digitalocean.md)、[Azure 节点模板配置](azure.md)、[vSphere 节点模板配置](vsphere.md)和 [Nutanix 节点模板配置](nutanix.md)。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/cluster-configuration/downstream-cluster-configuration/node-template-configuration/nutanix.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/cluster-configuration/downstream-cluster-configuration/node-template-configuration/nutanix.md new file mode 100644 index 00000000000..21f03714a21 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/cluster-configuration/downstream-cluster-configuration/node-template-configuration/nutanix.md @@ -0,0 +1,66 @@ +--- +title: Nutanix 节点模板配置 +--- + +## 账号访问 + +| 参数 | 必填 | 描述 | 默认 | +|:-----------------------------|:--------:|:-----------------------------------------------------------------|:----- +| 管理端点 | ✓ | Prism Central 的主机名/IP 地址 | +| 用户名 | ✓ | Prism Central 用户的用户名 | +| 密码 | ✓ | Prism Central 用户的密码 | +| 允许不安全的通信 | | 设置为 true 以允许与 Prism Central 进行不安全的 SSL 通信 | False | + +## 调度 + +选择虚拟机要调度到哪个 Nutanix 集群。 + +| 参数 | 必填 | 描述 | +|:----------|:--------:|:---------------------------------------------------------------------------- +| 集群 | ✓ | 部署虚拟机的 Nutanix 集群的名称（区分大小写） | + +## 实例选项 + +在**实例参数**中，配置此模板创建的 VM 的 vCPU 数量、内存和磁盘大小。 + +| 参数 | 必填 | 描述 | 默认 | +|:---------------------|:--------:|:--------------------------------------------------------------------------------------------|:------- +| CPU | | 分配给 VM 的 vCPU 数量（核心） | 2 | +| 内存 | | 分配给 VM 的 RAM 量 (MB) | 2 GB | +| Template Image | ✓ | 要作为虚拟机主磁盘进行克隆的磁盘镜像模板的名称（必须支持 cloud-init） | +| 虚拟机磁盘大小 | | 虚拟机主磁盘的新大小（以 GiB 为单位） | +| 其他磁盘大小 | | 要添加到虚拟机的其他磁盘的大小（以 GiB 为单位） | +| 储存容器 | | 要配置其他磁盘的存储容器 _UUID_ | +| Cloud Config YAML | | 要提供给虚拟机的 cloud-init（将使用 Rancher root 用户修补） | +| 网络 | ✓ | 要附加到虚拟机的网络的名称 | +| 虚拟机类别 | | 要应用于虚拟机的类别名称 | + +虚拟机支持通过 [Config Drive v2 datasource](https://cloudinit.readthedocs.io/en/latest/reference/datasources/configdrive.html) 来支持 [cloud-init](https://cloudinit.readthedocs.io/en/latest/) 的任何现代 Linux 操作系统。 + +## 网络 + +节点模板允许你为虚拟机配置多个网络。在**网络**字段中，你可以单击**添加**，然后在 AOS 中添加任何可用的网络。 + +## 虚拟机类别 + +类别用于将实体分组成键值对。通常会根据某些标准为虚拟机分配一个类别。然后，你可以将策略绑定到分配（分组）了特定类别值的实体。 + +## cloud-init + +[Cloud-init](https://cloudinit.readthedocs.io/en/latest/) 允许你在首次启动时应用配置，从而初始化节点。这可能涉及创建用户或授权 SSH 密钥之类的操作。 + +要使用 cloud-init 初始化，请将使用有效 YAML 语法的 cloud config 粘贴到 **Cloud Config YAML** 字段中。要获取支持的 cloud config 指令的注释示例集，请参阅 [cloud-init 文档](https://cloudinit.readthedocs.io/en/latest/topics/examples.html)。 + +不建议使用基于 cloud-init 的网络配置，仅支持使用用户数据 `runcmd`，不支持 NoCloud 或其他网络配置数据源。 + +建议使用 Nutanix IP Address Management（IPAM) 或其他 DHCP 服务。 + +## 引擎选项 + +在节点模板的**引擎选项**中，你可以配置容器 daemon。你可能需要指定容器版本或容器镜像仓库 Mirror。 + +:::note +如果要配置 Red Hat Enterprise Linux (RHEL) 或 CentOS 节点，请将 **Docker Install URL** 字段保留为默认值，或选择 **none**。由于 Docker 已经安装在这些节点上，因此将绕过 Docker 安装检查。 + +如果没有将 **Docker Install URL** 设置为默认值或 **none**，你可能会看到错误消息：`Error creating machine: RHEL ssh command error: command: sudo -E yum install -y curl err: exit status 1 output: Updating Subscription Management repositories`。 +::: \ No newline at end of file diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/cluster-configuration/downstream-cluster-configuration/node-template-configuration/vsphere.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/cluster-configuration/downstream-cluster-configuration/node-template-configuration/vsphere.md new file mode 100644 index 00000000000..a8956d548d5 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/cluster-configuration/downstream-cluster-configuration/node-template-configuration/vsphere.md @@ -0,0 +1,95 @@ +--- +title: vSphere 节点模板配置 +--- + +## 账号访问 + +| 参数 | 必填 | 描述 | +|:----------------------|:--------:|:-----| +| 云凭证 | * | 你的 vSphere 账号访问信息，存储在[云凭证](../../../user-settings/manage-cloud-credentials.md)中。 | + +你的云凭证具有以下字段： + +| 凭证字段 | 描述 | +|-----------------|--------------| +| vCenter 或 ESXi Server | 输入 vCenter 或 ESXi 主机名/IP。ESXi 是你创建和运行虚拟机和虚拟设备的虚拟化平台。你可以通过 vCenter Server 服务来管理网络中连接的多个主机并池化主机资源。 | +| 端口 | 可选：配置 vCenter 或 ESXi Server 的端口。 | +| 用户名和密码 | 你的 vSphere 登录用户名和密码。 | + +## 调度 + +选择虚拟机要调度到哪个虚拟机监控程序。 + +**调度**中的字段应使用 vSphere 中可用的数据中心和其他计划选项自动填充。 + +| 字段 | 必填 | 解释 | +|---------|---------------|-----------| +| 数据中心 | * | 选择要调度 VM 的数据中心的名称/路径。 | +| 资源池 | | 要在其中调度 VM 的资源池名称。资源池可对独立主机或集群的可用 CPU 和内存资源进行分区，也可以嵌套使用。如果是独立 ESXi，请留空。如果未指定，则使用默认资源池。 | +| 数据存储 | * | 如果你有数据存储集群，则可以打开**数据存储**字段。此字段允许你选择要将 VM 调度到哪个数据存储集群。如果该字段未打开，你可以选择单个磁盘。 | +| 文件夹 | | 数据中心中用于创建 VM 的文件夹的名称。必须已经存在。此下拉菜单中的 VM 文件夹直接对应于 vSphere 中的 VM 文件夹。在 vSphere 配置文件中，文件夹名称应以 `vm/` 开头。 | +| 主机 | | 用于调度 VM 的主机系统的 IP。如果是独立 ESXi 或具有 DRS（分布式资源调度器）的集群，将此字段留空。如果指定，将使用主机系统的池，而忽略**资源池**参数。 | + +## 实例选项 + +在**实例参数**中，配置此模板创建的 VM 的 vCPU 数量、内存和磁盘大小。 + +| 参数 | 必填 | 描述 | +|:----------------|:--------:|:-----------| +| CPU | * | 要分配给 VM 的 vCPU 数量。 | +| 内存 | * | 要分配给 VM 的内存量。 | +| 磁盘 | * | 要挂载到 VM 的磁盘大小（以 MB 为单位）。 | +| 创建方法 | * | 在节点上设置操作系统的方法。可以使用 ISO 或 VM 模板安装操作系统。根据创建方法，你还必须指定 VM 模板、内容库、现有 VM 或 ISO。有关创建方法的详细信息，请参阅 [VM 创建方法](#vm-创建方法)。 | +| Cloud Init | | `cloud-config.yml` 文件的 URL 或用于配置 VM 的 URL。此文件允许进一步定制操作系统，例如网络配置、DNS 服务器或系统守护程序。操作系统必须支持 `cloud-init`。 | +| 网络 | | 要挂载 VM 的网络的名称。 | +| guestinfo 配置参数 | | VM 的其他配置参数。这些参数对应 vSphere 控制台中的[高级设置](https://kb.vmware.com/s/article/1016098)。示例用例包括提供 RancherOS [guestinfo](https://rancher.com/docs/os/v1.x/en/installation/cloud/vmware-esxi/#vmware-guestinfo) 参数，或为 VM 启用磁盘 UUID (`disk.EnableUUID=TRUE`)。 | + + +### VM 创建方法 + +在**创建方法**字段中，配置用于在 vSphere 中配置 VM 的方法。可用的选项包括创建从 RancherOS ISO 启动的 VM，或通过从现有虚拟机或 [VM 模板](https://docs.vmware.com/en/VMware-vSphere/6.5/com.vmware.vsphere.vm_admin.doc/GUID-F7BF0E6B-7C4F-4E46-8BBF-76229AEA7220.html)克隆来创建 VM。 + +现有 VM 或模板可以使用任何现代 Linux 操作系统，该操作系统配置为使用 [NoCloud 数据源](https://canonical-cloud-init.readthedocs-hosted.com/en/latest/reference/datasources/nocloud.html)来支持 [cloud-init](https://cloudinit.readthedocs.io/en/latest/)。 + +选择创建 VM 的方式： + +- **使用模板部署：数据中心**：选择存在于所选数据中心的 VM 模板。 +- **使用模板部署：内容库**：首先选择包含你的模板的[内容库](https://docs.vmware.com/en/VMware-vSphere/6.5/com.vmware.vsphere.vm_admin.doc/GUID-254B2CE8-20A8-43F0-90E8-3F6776C2C896.html)，然后从填充列表**库模板**中选择模板。 +- **克隆现有的虚拟机**：在**虚拟机**字段中选择一个现有虚拟机，新虚拟机将克隆自该虚拟机。 +- **使用 boot2docker ISO 安装**：确保 **OS ISO URL** 字段包含 RancherOS 的 VMware ISO 版本的 URL (`rancheros-vmware.iso`)。请注意，运行 Rancher Server 节点必须能访问该 URL。 + +## 网络 + +节点模板允许你为虚拟机配置多个网络。在**网络**字段中，你可以单击**添加网络**来添加 vSphere 中可用的任何网络。 + +## 节点标签和自定义属性 + +标签用于向 vSphere 对象清单中的对象添加元数据，以便对对象进行排序和搜索。 + +你的所有 vSphere 标签都将显示为节点模板中可供选择的选项。 + +在自定义属性中，Rancher 会让你选择你已经在 vSphere 中设置的所有自定义属性。自定义属性是键，你可以为每个属性输入值。 + +:::note + +自定义属性是一项旧版功能，最终将从 vSphere 中删除。 + +::: + +## cloud-init + +[Cloud-init](https://cloudinit.readthedocs.io/en/latest/) 允许你在首次启动时应用配置，从而初始化节点。这可能涉及创建用户、授权 SSH 密钥或设置网络之类的操作。 + +要使用 cloud-init 初始化，请使用有效的 YAML 语法创建一个 cloud config 文件，并将文件内容粘贴到 **Cloud Init** 字段中。要获取支持的 cloud config 指令的注释示例集，请参阅 [cloud-init 文档](https://cloudinit.readthedocs.io/en/latest/topics/examples.html)。 + +请注意，使用 ISO 创建方法时不支持 cloud-init。 + +## 引擎选项 + +在节点模板的**引擎选项**中，你可以配置容器 daemon。你可能需要指定容器版本或容器镜像仓库 Mirror。 + +:::note +如果要配置 Red Hat Enterprise Linux (RHEL) 或 CentOS 节点，请将 **Docker Install URL** 字段保留为默认值，或选择 **none**。由于 Docker 已经安装在这些节点上，因此将绕过 Docker 安装检查。 + +如果没有将 **Docker Install URL** 设置为默认值或 **none**，你可能会看到错误消息：`Error creating machine: RHEL ssh command error: command: sudo -E yum install -y curl err: exit status 1 output: Updating Subscription Management repositories`。 +::: \ No newline at end of file diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/cluster-configuration/rancher-server-configuration/aks-cluster-configuration.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/cluster-configuration/rancher-server-configuration/aks-cluster-configuration.md new file mode 100644 index 00000000000..d617a0d6497 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/cluster-configuration/rancher-server-configuration/aks-cluster-configuration.md @@ -0,0 +1,224 @@ +--- +title: AKS 集群配置参考 +--- + +## Rancher 2.6 变更 + +- 支持添加多个节点池 +- 支持私有集群 +- 启用自动缩放节点池 +- 在云凭证中配置 AKS 权限 + +## RBAC + +在 Rancher UI 中配置 AKS 集群时，无法禁用 RBAC。如果在 AKS 中为集群禁用了 RBAC，则无法在 Rancher 中注册或导入集群。 + +Rancher 可以使用与其他集群一样的方式为 AKS 集群配置成员角色。有关详细信息，请参阅 [RBAC](../../../how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/manage-role-based-access-control-rbac.md)。 + +## 云凭证 + +:::note + +本节中的配置信息假设你已经为 Rancher 设置了服务主体。有关如何设置服务主体的分步说明，请参阅[本节](../../../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-clusters-from-hosted-kubernetes-providers/aks.md#microsoft-azure-中的先决条件)。 + +::: + +### 订阅 ID + +要获取订阅 ID，请单击左侧导航栏中的 **All Services**。然后单击 **Subscriptions**。转到要与 Kubernetes 集群关联的订阅的名称，然后复制 **Subscription ID**。 + +### 客户端 ID + +要获取客户端 ID，请转到 Azure 门户，然后单击 **Azure Active Directory**，单击 **App registrations**，然后单击服务主体的名称。客户端 ID 在 app registration 详细信息页面上列为 **Application (client) ID**。 + +### 客户端密码 + +在创建客户端密码值后，你无法再获取它的值。因此如果你还没有客户端密码值，则需要创建一个新的客户端密码。 + +要获取新的客户端密码，请转到 Azure 门户，然后单击 **Azure Active Directory**，单击 **App registrations**，然后单击服务主体的名称。 + +然后点击 **Certificates & secrets** 并点击 **New client secret**。单击 **Add**。然后复制新客户端密码的 **Value**。 + +### 环境 + +Microsoft 提供了多个[云](https://docs.microsoft.com/en-us/cli/azure/cloud?view=azure-cli-latest)来满足地区法律的要求： + +- AzurePublicCloud +- AzureGermanCloud +- AzureChinaCloud +- AzureUSGovernmentCloud + +## 账号访问 + +在本部分中，你需要选择现有的 Azure 云凭证或创建一个新凭证。 + +有关配置 Azure 云凭证的帮助，请参阅[本部分](#云凭证)。 + +## 集群位置 + +配置集群和节点位置。有关 AKS 可用区的详细信息，请参阅 [AKS 文档](https://docs.microsoft.com/en-us/azure/aks/availability-zones)。 + +高可用性位置包括多个可用区。 + +## 集群选项 + +### Kubernetes 版本 + +可用的 Kubernetes 版本是从 Azure API 动态获取的。 + +### 集群资源组 + +资源组是一个容器，其中包含 Azure 解决方案的相关资源。资源组可以包括解决方案的所有资源，或者仅包括你希望作为一个组来管理的资源。你可以根据组织的需求来决定如何将资源分配给资源组。通常情况下，你可以将生命周期相同的资源添加到同一个资源组，以便轻松地按组进行部署、更新和删除。 + +你可以使用现有资源组，也可以输入资源组的名称，然后系统将为你创建一个资源组。 + +使用包含现有 AKS 集群的资源组将会创建一个新资源组。Azure AKS 仅允许每个资源组对应一个 AKS 集群。 + +有关管理资源组的信息，请参阅 [Azure 文档](https://docs.microsoft.com/en-us/azure/azure-resource-manager/management/manage-resource-groups-portal)。 + +### Linux 管理员用户名 + +用于创建到 Linux 节点的 SSH 连接的用户名。 + +AKS 节点的默认用户名是 `azureuser`。 + +### SSH 公钥 + +用于创建到 Linux 节点的 SSH 连接的密钥。 + +### Tags + +如果你的组织使用标签（Tag）来管理多个 Azure 服务的资源，那么集群标签则非常有用。这些标签不适用于集群内的资源。 + +## 网络选项 + +### 负载均衡器 SKU + +Azure 负载均衡器支持 standard 和 basic SKU（stock keeping units）。 + +有关 standard 负载均衡器和 basic 负载均衡器的对比，请参阅官方 [Azure 文档](https://docs.microsoft.com/en-us/azure/load-balancer/skus#skus)。Microsoft 建议使用 standard 负载均衡器。 + +如果你选择了一个或多个可用区，或者你有多个节点池，则需要 Standard 负载均衡器。 + +### 网络策略 + +默认情况下，AKS 集群中的所有 Pod 都可以无限制地发送和接收流量。为了提高安全性，你可以定义控制流量的规则。Kubernetes 中的网络策略功能允许你定义集群中 pod 之间的入口和出口流量规则。 + +Azure 提供了两种实现网络策略的方法。创建 AKS 集群时会选择网络策略选项。创建集群后无法更改策略选项： + +- Azure 自己的实现，称为 Azure 网络策略。Azure 网络策略需要 Azure CNI。 +- Calico Network Policies，一个由 [Tigera](https://www.tigera.io/) 创立的开源网络和网络安全解决方案。 + +你也可以选择不使用网络策略。 + +有关 Azure 和 Calico 网络策略及其功能之间的差异，请参阅 [AKS 文档](https://docs.microsoft.com/en-us/azure/aks/use-network-policies#differences-between-azure-and-calico-policies-and-their-capabilities)。 + +### DNS 前缀 +为集群的 Kubernetes API server FQDN 输入唯一的 DNS 前缀。 + +### 网络插件 +有两个网络插件，分别是 kubenet 和 Azure CNI。 + +[kubenet](https://kubernetes.io/docs/concepts/cluster-administration/network-plugins/#kubenet) Kubernetes 插件是 AKS 创建的集群的默认配置。使用 kubenet 时，集群中的每个节点都会收到一个可路由的 IP 地址。Pod 使用 NAT 与 AKS 集群外部的其他资源进行通信。这种方法减少了需要在网络空间中保留以供 Pod 使用的 IP 地址数量。 + +如果使用 Azure CNI（高级）网络插件，Pod 可以使用完整的虚拟网络连接，并且可以从连接的网络中通过 pod 的私有 IP 地址直接访问。这个插件需要更多的 IP 地址空间。 + +有关 kubenet 和 Azure CNI 之间差异的详细信息，请参阅 [AKS 文档](https://docs.microsoft.com/en-us/azure/aks/concepts-network#compare-network-models)。 + +### HTTP 应用路由 + +启用后，HTTP 应用路由附加组件可以更轻松地访问部署到 AKS 集群的应用。它部署了两个组件，分别是 [Kubernetes Ingress controller](https://kubernetes.io/docs/concepts/services-networking/ingress/) 和 [External-DNS](https://github.com/kubernetes-incubator/external-dns) controller。 + +有关详细信息，请参阅 [AKS 文档](https://docs.microsoft.com/en-us/azure/aks/http-application-routing)。 + +### 设置授权 IP 范围 + +你可以使用[授权的 IP 地址范围](https://docs.microsoft.com/en-us/azure/aks/api-server-authorized-ip-ranges#overview-of-api-server-authorized-ip-ranges)来保护对 Kubernetes API server 的访问。 + +Kubernetes API server 公开 Kubernetes API。该组件提供管理工具（例如 kubectl）的交互。AKS 提供带有专用 API server 的单租户集群 controlplane。默认情况下，API server 分配了一个公共 IP 地址，你应该使用基于 Kubernetes 或 Azure 的 RBAC 来控制对 API server 的访问。 + +要保护对其他可公开的 AKS controlplane 和 API server 的访问，你可以启用并使用授权的 IP 范围。这些授权的 IP 范围只允许定义的 IP 地址范围与 API server 通信。 + +但是，即使你使用了授权的 IP 地址范围，你仍应使用 Kubernetes RBAC 或 Azure RBAC 来授权用户及其请求的操作。 + +### 容器监控 + +容器监控使用 Metrics API 从 Kubernetes 中可用的控制器、节点和容器中收集内存和处理器指标，从而为你可视化性能数据。容器日志也能被收集。启用监控后，系统会通过 Linux 的 Log Analytics 代理的容器化版本自动为你收集指标和日志。指标会被写入指标存储，而日志数据会被写入与你的 [Log Analytics](https://docs.microsoft.com/en-us/azure/azure-monitor/logs/log-query-overview) 工作区关联的日志存储。 + +### Log Analytics 工作区资源组 + +[资源组](https://docs.microsoft.com/en-us/azure/azure-resource-manager/management/overview#resource-groups)包含 Log Analytics 工作区。你必须至少创建一个工作区才能使用 Azure Monitor Logs。 + +### Log Analytics 工作区名称 + +Azure Monitor Logs 收集的数据存储在一个或多个 [Log Analytics 工作区中](https://docs.microsoft.com/en-us/azure/azure-monitor/logs/design-logs-deployment)。工作区定义了数据的地理位置、访问权限（定义了哪些用户可以访问数据）以及配置设置（定价层和数据保留等）。 + +你必须至少创建一个工作区才能使用 Azure Monitor Logs。一个工作区可能就足以满足你的所有监控数据。你也可以根据需求创建多个工作区。例如，你可能有一个工作区用于生产数据，另一个工作区用于测试。 + +有关 Azure Monitor Logs 的详细信息，请参阅 [Azure 文档](https://docs.microsoft.com/en-us/azure/azure-monitor/logs/data-platform-logs)。 + +### 支持私有 Kubernetes 服务 + +通常情况下，无论集群是否为私有，AKS worker 节点都不会获得公共 IP。在私有集群中，controlplane 没有公共端点。 + +Rancher 可以通过以下两种方式之一连接到私有 AKS 集群。 + +第一种方法是确保 Rancher 运行在与 AKS 节点相同的 [NAT](https://docs.microsoft.com/en-us/azure/virtual-network/nat-overview) 上。 + +第二种方法是运行命令向 Rancher 注册集群。配置集群后，你可以在任何能连接到集群的 Kubernetes API 的地方运行显示的命令。配置启用了私有 API 端点的 AKS 集群时，此命令将显示在弹出窗口中。 + +:::note + +注册现有 AKS 集群时，集群可能需要一些时间（可能是数小时）才会出现在 `Cluster To register` 下拉列表中。不同区域的结果可能不同。 + +::: + +有关连接到 AKS 专用集群的详细信息，请参阅 [AKS 文档](https://docs.microsoft.com/en-us/azure/aks/private-clusters#options-for-connecting-to-the-private-cluster)。 + +## 节点池 + +### 模式 + +在 Azure 界面中，用户能够指定主要节点池（Primary Node Pool）依赖于 `system`（通常用于 controlplane）还是 `user`（Rancher 最常用的）。 + +你可以指定主要节点池（Primary Node Pool）的模式、操作系统、数量和大小。 + +`system` 节点池总是需要运行节点，因此它们不能缩容到一个节点以下。至少需要一个 `system` 节点池。 + +对于后续的节点池，Rancher UI 强制使用默认的 `user`。`user` 节点池允许缩容到零节点。`user` 节点池不运行 Kubernetes controlplane 的任何部分。 + +AKS 不会公开运行 Kubernetes controlplane 组件的节点。 + +### 可用区 + +[可用区](https://docs.microsoft.com/en-us/azure/availability-zones/az-overview)是区域内的唯一物理位置。每个可用区由一个或多个配备独立电源、冷却系统和网络的数据中心组成。 + +并非所有区域都支持可用区。有关具有可用区的 Azure 区域列表，请参阅 [Azure 文档](https://docs.microsoft.com/en-us/azure/availability-zones/az-region#azure-regions-with-availability-zones)。 + +### 虚拟机大小 + +为节点池中的每个 VM 选择一个大小。有关每个 VM 大小的详细信息，请参阅[此页面](https://azure.microsoft.com/en-us/pricing/details/virtual-machines/linux/)。 + +### 操作系统磁盘类型 + +节点池中的节点可以使用托管磁盘或临时磁盘。 + +[临时 OS 磁盘](https://docs.microsoft.com/en-us/azure/virtual-machines/ephemeral-os-disks)在本地虚拟机存储上创建，并不会保存到远程 Azure 存储。临时 OS 磁盘适用于无状态工作负载，其中的应用可以容忍单个 VM 故障，但更容易受 VM 部署时间或重置单个虚拟机实例镜像的影响。使用临时 OS 磁盘，你可以体验更低的 OS 磁盘读/写延迟和更快的 VM 重置镜像过程。 + +[Azure 托管磁盘](https://docs.microsoft.com/en-us/azure/virtual-machines/managed-disks-overview)是由 Azure 管理并与 Azure Virtual Machines 一起使用的块级存储卷。托管磁盘旨在实现 99.999% 的高可用性。托管磁盘通过提供三个数据副本来实现高可用性和高持续性。 + +### 操作系统磁盘大小 + +每个节点的磁盘大小（以 GB 为单位）。 + +### 节点数 +节点池中的节点数。[Azure 订阅](https://docs.microsoft.com/en-us/azure/azure-resource-manager/management/azure-subscription-service-limits)可能会限制最大节点数。 + +### 每个节点的最大 Pod 数量 +每个节点的最大 Pod 数量默认为 110，最大为 250。 + +### 启用自动扩缩容 + +启用自动扩缩容后，你需要输入最小和最大节点数。 + +启用 Auto Scaling 后，你将无法手动对节点池进行扩缩容。扩缩容由 AKS autoscaler 控制。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/cluster-configuration/rancher-server-configuration/eks-cluster-configuration.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/cluster-configuration/rancher-server-configuration/eks-cluster-configuration.md new file mode 100644 index 00000000000..be8365d0724 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/cluster-configuration/rancher-server-configuration/eks-cluster-configuration.md @@ -0,0 +1,149 @@ +--- +title: EKS 集群配置参考 +--- + +## 账号访问 + +使用获取的信息为 IAM 策略填写每个下拉列表和字段： + +| 设置 | 描述 | +| ---------- | -------------------------------------------------------------------------------------------------------------------- | +| 区域 | 从下拉列表中选择构建集群的地理区域。 | +| 云凭证 | 选择为 IAM 策略创建的云凭证。有关在 Rancher 中创建云凭证的更多信息，请参阅[此页面](../../user-settings/manage-cloud-credentials.md)。 | + +## 服务角色 + +选择一个[服务角色](https://docs.aws.amazon.com/IAM/latest/UserGuide/using-service-linked-roles.html)。 + +| 服务角色 | 描述 | +-------------|--------------------------- +| Standard：Rancher 生成的服务角色 | 如果选择此角色，Rancher 会自动添加一个服务角色以供集群使用。 | +| 自定义：从现有的服务角色中选择 | 如果选择此角色，Rancher 将允许你从已在 AWS 中创建的服务角色中进行选择。有关在 AWS 中创建自定义服务角色的更多信息，请参阅 [Amazon 文档](https://docs.aws.amazon.com/IAM/latest/UserGuide/using-service-linked-roles.html#create-service-linked-role)。 | + +## 密文加密 + +可选：要加密密文，请选择或输入在 [AWS 密钥管理服务 (KMS)](https://docs.aws.amazon.com/kms/latest/developerguide/overview.html) 中创建的密钥。 + +## API Server 端点访问 + +配置公共/私有 API 访问是一个高级用例。有关详细信息，请参阅 [EKS 集群端点访问控制文档](https://docs.aws.amazon.com/eks/latest/userguide/cluster-endpoint.html)。 + +## 专用 API 端点 + +如果你在创建集群时启用了私有 API 端点访问，并禁用了公共 API 端点访问，那么你必须进行额外的步骤才能使 Rancher 成功连接到集群。在这种情况下，一个弹窗将会显示，其中包含需要在要注册到 Rancher 的集群上运行的命令。配置集群后，你可以在任何能连接到集群的 Kubernetes API 的地方运行显示的命令。 + +以下两种方法能避免这个额外的手动步骤： +- 在创建集群时，创建具有私有和公共 API 端点访问权限的集群。在集群创建并处于 active 状态后，你可以禁用公共访问，Rancher 将能继续与 EKS 集群通信。 +- 确保 Rancher 与 EKS 集群共享同一个子网。然后，你可以使用安全组使 Rancher 能够与集群的 API 端点进行通信。在这种情况下，你不需要运行注册集群的命令，Rancher 就能够与你的集群通信。有关配置安全组的更多信息，请参阅[安全组文档](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_SecurityGroups.html)。 + +## 公共访问端点 + +你也可以选择通过显式 CIDR 块来限制对公共端点的访问。 + +如果你限制对特定 CIDR 块的访问，那么建议你也启用私有访问，以避免丢失与集群的网络通信。 + +启用私有访问需要满足以下条件之一： +- Rancher 的 IP 必须是允许的 CIDR 块的一部分。 +- 应该启用了私有访问。此外，Rancher 必须和集群共享同一个子网，并对集群有网络访问权限。你可以通过安全组来进行配置。 + +有关对集群端点的公共和私有访问的更多信息，请参阅 [Amazon EKS 文档](https://docs.aws.amazon.com/eks/latest/userguide/cluster-endpoint.html)。 + +## 子网 + +| 选项 | 描述 | +| ------- | ------------ | +| Standard：Rancher 生成的 VPC 和子网 | 在配置集群时，Rancher 会生成一个具有 3 个公有子网的新 VPC。 | +| 自定义：从现有的 VPC 和子网中选择 | 在配置集群时，Rancher 将你的 controlplane 和节点配置为使用你已经[在 AWS 中创建](https://docs.aws.amazon.com/vpc/latest/userguide/what-is-amazon-vpc.html)的 VPC 和子网。 | + +有关更多信息，请参阅 AWS 文档以了解[集群 VPC 注意事项](https://docs.aws.amazon.com/eks/latest/userguide/network_reqs.html)。根据你在上一步中的选择，按照以下说明进行操作。 + +- [什么是 Amazon VPC？](https://docs.aws.amazon.com/vpc/latest/userguide/what-is-amazon-vpc.html) +- [VPC 和子网](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_Subnets.html) + +## 安全组 + +Amazon 文档： + +- [集群安全组注意事项](https://docs.aws.amazon.com/eks/latest/userguide/sec-group-reqs.html) +- [VPC 的安全组](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_SecurityGroups.html) +- [创建安全组](https://docs.aws.amazon.com/vpc/latest/userguide/getting-started-ipv4.html#getting-started-create-security-group) + +## Logging + +将 controlplane 日志配置为发送到 Amazon CloudWatch。如果你将集群日志发送到 CloudWatch Logs，你需要按照 standard CloudWatch Logs 支付数据引入和存储费用。 + +每个日志类型均对应一个 Kubernetes controlplane 组件。有关这些组件的更多信息，请参阅 Kubernetes 文档中的 [Kubernetes 组件](https://kubernetes.io/docs/concepts/overview/components/)。 + +有关 EKS controlplane 日志管理的更多信息，请参阅[官方文档](https://docs.aws.amazon.com/eks/latest/userguide/control-plane-logs.html)。 + +## 托管节点组 + +Amazon EKS 托管的节点组自动为 Amazon EKS Kubernetes 集群的节点（Amazon EC2 实例）进行预置和生命周期管理。 + +有关节点组如何工作以及如何配置的更多信息，请参阅 [EKS 文档](https://docs.aws.amazon.com/eks/latest/userguide/managed-node-groups.html)。 + +### 使用你自己的启动模板 + +你可以提供启动模板 ID 和版本，以便轻松配置节点组中的 EC2 实例。如果你提供了启动模板，则以下设置都无法在 Rancher 中进行配置。因此，如果你使用启动模板，则需要在启动模板中指定以下列表中的所有必须和所需的设置。另请注意，如果提供了启动模板 ID 和版本，则只能更新模板版本。如果要使用新模板 ID，则需要创建新的托管节点组。 + +| 选项 | 描述 | 必填/选填 | +| ------ | ----------- | ----------------- | +| 实例类型 | 为要配置的实例选择[硬件规格](https://aws.amazon.com/ec2/instance-types/)。 | 必填 | +| 镜像 ID | 为节点指定自定义 AMI。与 EKS 一起使用的自定义 AMI 必须[正确配置](https://aws.amazon.com/premiumsupport/knowledge-center/eks-custom-linux-ami/)。 | 选填 | +| 节点卷大小 | 启动模板必须指定具有所需大小的 EBS 卷。 | 必填 | +| SSH 密钥 | 要添加到实例以对节点进行 SSH 访问的密钥。 | 选填 | +| 用户数据 | [MIME 多部分格式](https://docs.aws.amazon.com/eks/latest/userguide/launch-templates.html#launch-template-user-data)的 Cloud init 脚本。 | 选填 | +| 实例资源标签 | 标记节点组中的每个 EC2 实例。 | 选填 | + +### Rancher 管理的启动模板 + +如果你不指定启动模板，你将能够在 Rancher UI 中配置上述选项，并且可以在创建后更新所有这些选项。为了利用所有这些选项，Rancher 将为你创建和管理启动模板。Rancher 中的所有集群都将有一个 Rancher 管理的启动模板。此外，每个没有指定启动模板的托管节点组都将具有一个管理的启动模板版本。此启动模板的名称将具有 “rancher-managed-lt-” 前缀，后面是集群的显示名称。此外，Rancher 管理的启动模板将使用 “rancher-managed-template” 键和 “do-not-modify-or-delete” 值来进行标记，以将其识别为 Rancher 管理的启动模板。请注意，不要修改或删除此启动模板，或将此启动模板与其他集群或托管节点组一起使用。因为这可能会使你的节点组“降级”并需要销毁和重新创建。 + +### 自定义 AMI + +如果你在启动模板或 Rancher 中指定了自定义 AMI，则必须[正确配置](https://aws.amazon.com/premiumsupport/knowledge-center/eks-custom-linux-ami/)镜像，并且必须提供用户数据以[引导节点](https://docs.aws.amazon.com/eks/latest/userguide/launch-templates.html#launch-template-custom-ami)。这是一个高级用例，因此你必须要了解其要求。 + +如果你指定了不包含自定义 AMI 的启动模板，则 Amazon 将为 Kubernetes 版本和所选区域使用 [EKS 优化的 AMI](https://docs.aws.amazon.com/eks/latest/userguide/eks-optimized-ami.html)。你还可以为能从中受益的工作负载选择[启用 GPU 的实例](https://docs.aws.amazon.com/eks/latest/userguide/eks-optimized-ami.html#gpu-ami)。 + +:::note + +如果你在下拉菜单或启动模板中提供了自定义 AMI，则会忽略 Rancher 中设置的启用 GPU 的实例。 + +::: + +### Spot 实例 + +Spot 实例现在[受 EKS 支持](https://docs.aws.amazon.com/eks/latest/userguide/managed-node-groups.html#managed-node-group-capacity-types-spot)。如果你指定了启动模板，Amazon 建议不要在模板中提供实例类型。相反，Amazon 建议提供多种实例类型。如果你为节点组启用了“请求 Spot 实例”复选框，那么你将有机会提供多种实例类型。 + +:::note + +在这种情况下，你在实例类型下拉列表中所选的选项都将被忽略，你必须在“Spot 实例类型”中至少指定一种实例类型。此外，与 EKS 一起使用的启动模板无法请求 Spot 实例。请求 Spot 实例必须是 EKS 配置的一部分。 + +::: + +### 节点组设置 + +以下设置也是可配置的。在创建节点组后，除“节点组名称”外的所有选项都是可编辑的。 + +| 选项 | 描述 | +| ------- | ------------ | +| 节点组名称 | 节点组的名称。 | +| 期望 ASG 大小 | 期望的实例数量。 | +| 最大 ASG 大小 | 最大的实例数量。在安装 [Cluster Autoscaler](https://docs.aws.amazon.com/eks/latest/userguide/cluster-autoscaler.html) 之前，此设置不会生效。 | +| 最小 ASG 大小 | 最小的实例数量。在安装 [Cluster Autoscaler](https://docs.aws.amazon.com/eks/latest/userguide/cluster-autoscaler.html) 之前，此设置不会生效。 | +| Labels | 应用于管理的节点组中节点的 Kubernetes 标签。 | +| Tags | 管理的节点组的标签，这些标签不会传播到任何相关资源。 | + + +## 配置刷新间隔 + +`eks-refresh-cron` 设置已弃用。它已迁移到 `eks-refresh` 设置，这是一个表示秒的整数。 + +默认值为 300 秒。 + +你可以通过运行 `kubectl edit setting eks-refresh` 来更改同步间隔。 + +如果之前设置了 `eks-refresh-cron` 设置，迁移将自动进行。 + +刷新窗口越短，争用条件发生的可能性就越小。但这确实增加了遇到 AWS API 可能存在的请求限制的可能性。 + diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/cluster-configuration/rancher-server-configuration/gke-cluster-configuration/gke-cluster-configuration.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/cluster-configuration/rancher-server-configuration/gke-cluster-configuration/gke-cluster-configuration.md new file mode 100644 index 00000000000..469c2363893 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/cluster-configuration/rancher-server-configuration/gke-cluster-configuration/gke-cluster-configuration.md @@ -0,0 +1,324 @@ +--- +title: GKE 集群配置参考 +--- + + + + + +## Rancher 2.6 变更 + +- 支持额外的配置选项： + - 项目网络隔离 + - 网络标签 + +## 集群位置 + +| 值 | 描述 | +|--------|--------------| +| 位置类型 | 地区 (zone) 或区域 (region)。借助 GKE，你可以根据工作负载的可用性要求和预算创建一个量身定制的集群。默认情况下，集群的节点在单个计算区域中运行。选择多个区域时，集群的节点将跨越多个计算区域，而 controlplane 则只位于单个区域中。区域集群也增加了 controlplane 的可用性。有关选择集群可用性类型的帮助，请参阅[这些文档](https://cloud.google.com/kubernetes-engine/docs/best-practices/scalability#choosing_a_regional_or_zonal_control_plane)。 | +| 地区 | 计算引擎中的每个区域都包含多地区。有关可用区域和可用区的更多信息，请参阅[这些文档](https://cloud.google.com/compute/docs/regions-zones#available)。 | +| 其他地区 | 对于地区性集群，你可以选择其他地区来创建[多地区集群](https://cloud.google.com/kubernetes-engine/docs/concepts/types-of-clusters#multi-zonal_clusters)。 | +| 区域 | 对于[区域性集群](https://cloud.google.com/kubernetes-engine/docs/concepts/types-of-clusters#regional_clusters)，你可以选择一个区域。有关可用区域和可用区的更多信息，请参阅[本节](https://cloud.google.com/compute/docs/regions-zones#available)。地区名称的前面部分是区域的名称。 | + +## 集群选项 + +### Kubernetes 版本 + +_可变：是_ + +有关 GKE Kubernetes 版本的更多信息，请参阅[这些文档](https://cloud.google.com/kubernetes-engine/versioning)。 + +### 容器地址范围 + +_可变：否_ + +集群中 Pod 的 IP 地址范围。必须是有效的 CIDR 范围，例如 10.42.0.0/16。如果未指定，则会自动从 10.0.0.0/8 中选择一个随机范围，并排除已分配给 VM、其他集群或路由的范围。自动选择的范围可能与预留的 IP 地址、动态路由或与集群对等的 VPC 中的路由发生冲突。 + +### 网络 + +_可变：否_ + +集群连接的 Compute Engine 网络。将使用此网络创建路由和防火墙。如果使用[共享 VPC](https://cloud.google.com/vpc/docs/shared-vpc)，与你的项目共享的 VPC 网络将显示在此处。你将可以在此字段中进行选择。有关详细信息，请参阅[此页面](https://cloud.google.com/vpc/docs/vpc#vpc_networks_and_subnets)。 + +### 节点子网/子网 + +_可变：否_ + +集群连接到的 Compute Engine 子网。该子网必须属于**网络**字段中指定的网络。选择一个现有的子网，或选择“自动创建子网”来自动创建一个子网。如果不使用现有网络，则需要使用**子网名称**来生成一个。如果使用[共享 VPC](https://cloud.google.com/vpc/docs/shared-vpc)，与你的项目共享的 VPC 子网将显示在此处。如果使用共享 VPC 网络，则无法选择“自动创建子网”。如需更多信息，请参阅[此页面](https://cloud.google.com/vpc/docs/vpc#vpc_networks_and_subnets)。 + +### 子网名称 + +_可变：否_ + +使用提供的名称自动创建子网。如果为**节点子网**或**子网**选择了“自动创建子网”，则为必填。有关子网的更多信息，请参阅[此页面](https://cloud.google.com/vpc/docs/vpc#vpc_networks_and_subnets)。 + +### IP 别名 + +_可变：否_ + +启用[别名 IP](https://cloud.google.com/vpc/docs/alias-ip)。这将启用 VPC 原生流量路由。如果使用[共享 VPC](https://cloud.google.com/vpc/docs/shared-vpc)，则为必填。 + +### 网络策略 + +_可变：是_ + +在集群上启用的网络策略。网络策略定义了集群中 pod 和 service 之间可以发生的通信级别。有关详细信息，请参阅[此页面](https://cloud.google.com/kubernetes-engine/docs/how-to/network-policy)。 + +### 项目网络隔离 + +_可变：是_ + +选择启用或禁用项目间通信。请注意，如果启用**项目网络隔离**，则将自动启用**网络策略**和**网络策略配置**，反之则不然。 + +### 节点 IPv4 CIDR 块 + +_可变：否_ + +此集群中实例 IP 的 IP 地址范围。如果为**节点子网**或**子网**选择了“自动创建子网”，则可以进行设置。必须是有效的 CIDR 范围，例如 10.96.0.0/14。有关如何确定 IP 地址范围的详细信息，请参阅[此页面](https://cloud.google.com/kubernetes-engine/docs/concepts/alias-ips#cluster_sizing)。 + +### 集群次要范围名称 + +_可变：否_ + +Pod IP 地址的现有次要范围的名称。如果选中，将自动填充**集群 Pod 地址范围**。如果使用共享 VPC 网络，则为必填。 + +### 集群 Pod 地址范围 + +_可变：否_ + +分配给集群中 pod 的 IP 地址范围。必须是有效的 CIDR 范围，例如 10.96.0.0/11。如果未提供，将自动创建。如果使用共享 VPC 网络，则必须提供。有关如何确定 pod 的 IP 地址范围的更多信息，请参阅[本节](https://cloud.google.com/kubernetes-engine/docs/concepts/alias-ips#cluster_sizing_secondary_range_pods)。 + +### Service 次要范围名称 + +_可变：否_ + +Service IP 地址的现有次要范围的名称。如果选中，将自动填充 **Service 地址范围**。如果使用共享 VPC 网络，则为必填。 + +### Service 地址范围 + +_可变：否_ + +分配给集群中 Service 的地址范围。必须是有效的 CIDR 范围，例如 10.94.0.0/18。如果未提供，将自动创建。如果使用共享 VPC 网络，则必须提供。有关如何确定 Service 的 IP 地址范围的详细信息，请参阅[本节](https://cloud.google.com/kubernetes-engine/docs/concepts/alias-ips#cluster_sizing_secondary_range_svcs)。 + +### 私有集群 + +_可变：否_ + +:::caution + +私有集群需要在 Rancher 之外进行额外的规划和配置。请参阅[私有集群指南](gke-private-clusters.md)。 + +::: + +仅分配节点内部 IP 地址。除非在 GCP 中执行了额外的联网步骤，否则私有集群节点无法访问公共互联网。 + +### 启用私有端点 + +:::caution + +私有集群需要在 Rancher 之外进行额外的规划和配置。请参阅[私有集群指南](gke-private-clusters.md)。 + +::: + +_可变：否_ + +锁定对 controlplane 端点的外部访问。仅当**私有集群**也被选中时可用。如果选中，并且 Rancher 无法直接访问集群所在的虚拟私有云网络，Rancher 将提供在集群上运行的注册命令，以使 Rancher 能够连接到集群。 + +### 主 IPV4 CIDR 块 + +_可变：否_ + +controlplane VPC 的 IP 范围。 + +### 主授权网络 + +_可变：是_ + +启用 controlplane 授权网络，以阻止不受信任的非 GCP 源 IP 通过 HTTPS 访问 Kubernetes master。如果选择，则可以添加额外的授权网络。如果集群是使用公共端点创建的，则此选项可用于将公共端点的访问锁定到特定网络（例如运行 Rancher 服务的网络）。如果集群只有一个私有端点，则需要此设置。 + +## 其他选项 + +### 集群插件 + +其他 Kubernetes 集群组件。有关详细信息，请参阅[此页面](https://cloud.google.com/kubernetes-engine/docs/reference/rest/v1/projects.locations.clusters#Cluster.AddonsConfig)。 + +#### 水平 Pod 自动缩放 + +_可变：是_ + +Horizo​​ntal Pod Autoscaler 通过自动增加或减少 Pod 的数量来调整 Kubernetes 工作负载，从而响应工作负载的 CPU 或内存消耗，以及 Kubernetes 内部报告的自定义指标或集群外部设置的指标。详情请参见[本页面](https://cloud.google.com/kubernetes-engine/docs/concepts/horizontalpodautoscaler)。 + +#### HTTP (L7) 负载均衡 + +_可变：是_ + +HTTP (L7) 负载均衡将 HTTP 和 HTTPS 流量分配到托管在 GKE 上的后端。有关详细信息，请参阅[此页面](https://cloud.google.com/kubernetes-engine/docs/tutorials/http-balancer)。 + +#### 网络策略配置（仅限 master） + +_可变：是_ + +NetworkPolicy 的配置。仅跟踪 master 节点上是否启用了插件，不跟踪是否为节点启用了网络策略。 + +### 集群特征（Alpha 功能） + +_可变：否_ + +打开集群的所有 Kubernetes alpha API 组和功能。启用后，集群无法升级，并且会在 30 天后自动删除。由于 GKE SLA 未支持 alpha 集群，因此不建议将 Alpha 集群用于生产环境。有关详细信息，请参阅[此页面](https://cloud.google.com/kubernetes-engine/docs/concepts/alpha-clusters)。 + +### Logging 服务 + +_可变：是_ + +集群用于写入日志的日志管理服务。要么使用 [Cloud Logging](https://cloud.google.com/logging)，要么不使用日志管理服务（不会从集群中导出日志）。 + +### 监控服务 + +_可变：是_ + +集群用于写入指标的监控服务。要么使用 [Cloud Monitoring](https://cloud.google.com/monitoring)，要么不使用集群监控服务（不会从集群中导出指标）。 + + +### 维护窗口 + +_可变：是_ + +设置时长 4 小时的维护窗口的开始时间。使用 HH:MM 格式在 UTC 时区中指定时间。有关详细信息，请参阅[此页面](https://cloud.google.com/kubernetes-engine/docs/concepts/maintenance-windows-and-exclusions)。 + +## 节点池 + +在此部分中，输入描述节点池中每个节点的配置的详细信息。 + +### Kubernetes 版本 + +_可变：是_ + +节点池中每个节点的 Kubernetes 版本。有关 GKE Kubernetes 版本的更多信息，请参阅[这些文档](https://cloud.google.com/kubernetes-engine/versioning)。 + +### 镜像类型 + +_可变：是_ + +节点操作系统镜像。有关 GKE 为每个操作系统提供的节点镜像选项，请参阅[此页面](https://cloud.google.com/kubernetes-engine/docs/concepts/node-images#available_node_images)。 + +:::note + +默认选项是 “Container-Optimized OS with Docker”。GCP Container-Optimized OS 上的只读文件系统与 Rancher 中的 [legacy logging](https://github.com/rancher/rancher-docs/tree/main/archived_docs/en/version-2.0-2.4/pages-for-subheaders/cluster-logging.md) 实现不兼容。如果你需要使用旧版日志管理功能，请选择 “Ubuntu with Docker” 或 “Ubuntu with Containerd”。[current logging feature](../../../../integrations-in-rancher/logging/logging.md) 与 Container-Optimized OS 镜像兼容。 + +::: + +:::note + +如果节点池镜像类型选择 “Windows Long Term Service Channel” 或 “Windows Semi-Annual Channel”，还必须至少添加一个 Container-Optimized OS 或 Ubuntu 节点池。 + +::: + +### 主机类型 + +_可变：否_ + +节点实例可用的虚拟化硬件资源。有关 Google Cloud 主机类型的详细信息，请参阅[此页面](https://cloud.google.com/compute/docs/machine-types#machine_types)。 + +### 根磁盘类型 + +_可变：否_ + +标准永久性磁盘由标准磁盘驱动器 (HDD) 支持，而 SSD 永久性磁盘由固态硬盘 (SSD) 支持。有关详细信息，请参阅[本节](https://cloud.google.com/compute/docs/disks)。 + +### 本地 SSD 磁盘 + +_可变：否_ + +配置每个节点的本地 SSD 磁盘存储（以 GB 为单位）。本地 SSD 物理连接到托管你的 VM 实例的服务器。与标准永久性磁盘或 SSD 永久性磁盘相比，本地 SSD 具有更高的吞吐量和更低的延迟。存储在本地 SSD 上的数据只会保留到实例停止或删除。有关详细信息，请参阅[本节](https://cloud.google.com/compute/docs/disks#localssds)。 + +### 抢占式节点（beta） + +_可变：否_ + +抢占式节点也称为抢占式虚拟机。通常是最长持续 24 小时的 Compute Engine 虚拟机实例，不提供可用性保证。详情请参见[本页面](https://cloud.google.com/kubernetes-engine/docs/how-to/preemptible-vms)。 + +### 污点 + +_可变：否_ + +将污点应用于节点时，仅允许容忍该污点的 Pod 在该节点上运行。在 GKE 集群中，你可以将污点应用到节点池，这会将污点应用到池中的所有节点。 + +### 节点标签 + +_可变：否_ + +你可以将标签应用到节点池，这会将标签应用到池中的所有节点。 + +无效标签会阻止升级，或阻止 Rancher 启动。有关标签语法的详细信息，请参阅 [Kubernetes 文档](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/#syntax-and-character-set)。 + +### 网络标签 + +_可变：否_ + +你可以将网络标签添加到节点池以制定防火墙规则和子网之间的路由。标签将应用于池中的所有节点。 + +有关标签语法和要求的详细信息，请参阅 [Kubernetes 文档](https://cloud.google.com/vpc/docs/add-remove-network-tags)。 + +## 组详细信息 + +在此部分中，输入描述节点池的详细信息。 + +### 名称 + +_可变：否_ + +输入节点池的名称。 + +### 初始节点数 + +_可变：是_ + +节点池中初始节点数的整数。 + +### 每个节点的最大 Pod 数量 + +_可变：否_ + +GKE 的硬性限制是每个节点 110 个 Pod。有关 Kubernetes 限制的更多信息，请参阅[本节](https://cloud.google.com/kubernetes-engine/docs/best-practices/scalability#dimension_limits)。 + +### 自动缩放 + +_可变：是_ + +节点池自动缩放会根据工作负载的需求动态创建或删除节点。详情请参见[本页面](https://cloud.google.com/kubernetes-engine/docs/concepts/cluster-autoscaler)。 + +### 自动修复 + +_可变：是_ + +GKE 的节点自动修复功能可帮助你将集群中的节点保持在健康的运行状态。启用后，GKE 会定期检查集群中每个节点的运行状况。如果某个节点在较长时间段内连续未通过健康检查，GKE 会为该节点启动修复过程。有关详细信息，请参阅[自动修复节点](https://cloud.google.com/kubernetes-engine/docs/how-to/node-auto-repair)。 + +### 自动升级 + +_可变：是_ + +启用后，当你的 controlplane [按照你的需求更新](https://cloud.google.com/kubernetes-engine/upgrades#automatic_cp_upgrades)时，自动升级功能会使集群中的节点与集群 controlplane（master）版本保持同步。有关自动升级节点的更多信息，参见[此页面。](https://cloud.google.com/kubernetes-engine/docs/how-to/node-auto-upgrades) + +### 访问范围 + +_可变：否_ + +设置访问范围是为你的节点指定权限的旧版方法。 + +- **允许默认访问**：新集群的默认访问是 [Compute Engine 默认 ServiceAccount](https://cloud.google.com/compute/docs/access/service-accounts?hl=en_US#default_service_account)。 +- **允许完全访问所有 Cloud API**：通常，你只需设置云平台访问范围来允许完全访问所有 Cloud API，然后仅授予 ServiceAccount 相关的 IAM 角色。授予虚拟机实例的访问范围和授予 ServiceAccount 的 IAM 角色的组合决定了 ServiceAccount 对该实例的访问量。 +- **为每个 API 设置访问权限**：或者，你可以设置服务将调用的特定 API 方法的访问范围。 + +有关详细信息，请参阅[为 VM 启用 ServiceAccount](https://cloud.google.com/compute/docs/access/create-enable-service-accounts-for-instances)。 + + +### 配置刷新间隔 + +刷新间隔可以通过 “gke-refresh” 来配置，它是一个代表秒的整数。 + +默认值为 300 秒。 + +你可以通过运行 `kubectl edit setting gke-refresh` 来更改同步间隔。 + +刷新窗口越短，争用条件发生的可能性就越小。但这确实增加了遇到 GCP API 可能存在的请求限制的可能性。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/cluster-configuration/rancher-server-configuration/gke-cluster-configuration/gke-private-clusters.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/cluster-configuration/rancher-server-configuration/gke-cluster-configuration/gke-private-clusters.md new file mode 100644 index 00000000000..6cb63287e57 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/cluster-configuration/rancher-server-configuration/gke-cluster-configuration/gke-private-clusters.md @@ -0,0 +1,49 @@ +--- +title: 私有集群 +--- + +在 GKE 中，[私有集群](https://cloud.google.com/kubernetes-engine/docs/concepts/private-cluster-concept)是一种集群，其节点仅通过分配内部 IP 地址与入站和出站流量相隔离。GKE 中的私有集群可以选择将 controlplane 端点作为公开访问的地址或作为私有地址。这与其他 Kubernetes 提供商不同，后者可能将具有私有 controlplane 端点的集群称为“私有集群”，但仍允许进出节点的流量。基于你的组织的网络和安全要求，你可能想创建一个有私有节点的集群，其中有或没有公共 controlplane 端点。从 Rancher 配置的 GKE 集群可以通过在**集群选项**中选择**私有集群**（在**显示高级选项**下）来使用隔离的节点。通过选择**启用私有端点**，可以选择将 controlplane 端点设为私有。 + +## 私有节点 + +由于私有集群中的节点只有内部 IP 地址，它们将无法安装 cluster agent，Rancher 将无法完全管理集群。这可以通过几种方式来处理。 + +### Cloud NAT + +:::caution + +Cloud NAT 将[产生费用](https://cloud.google.com/nat/pricing)。 + +::: + +如果限制外出的互联网访问对你的组织来说不是一个问题，可以使用 Google 的 [Cloud NAT](https://cloud.google.com/nat/docs/using-nat) 服务来允许私有网络中的节点访问互联网，使它们能够从 Dockerhub 下载所需的镜像并与 Rancher management server 通信。这是最简单的解决方案。 + +### 私有镜像仓库 + +:::caution + +此方案不受官方支持。如果 Cloud NAT 服务不足以满足你的需求，则可以参考此方案。 + +::: + +如果要求限制节点的传入和传出流量，请按照离线安装说明，在集群所在的 VPC 上设置一个私有容器[镜像仓库](../../../../getting-started/installation-and-upgrade/other-installation-methods/air-gapped-helm-cli-install/air-gapped-helm-cli-install.md)，从而允许集群节点访问和下载运行 cluster agent 所需的镜像。如果 controlplane 端点也是私有的，Rancher 将需要[直接访问](#直接访问)它。 + +## 私有 controlplane 端点 + +如果集群暴露了公共端点，Rancher 将能够访问集群，且无需执行额外的步骤。但是，如果集群没有公共端点，则必须确保 Rancher 可以访问集群。 + +### Cloud NAT + +:::caution + +Cloud NAT 将[产生费用](https://cloud.google.com/nat/pricing)。 + +::: + +如上所述，如果不考虑限制对节点的传出互联网访问，则可以使用 Google 的 [Cloud NAT](https://cloud.google.com/nat/docs/using-nat) 服务来允许节点访问互联网。当集群进行配置时，Rancher 将提供一个在集群上运行的注册命令。下载新集群的 [kubeconfig](https://cloud.google.com/kubernetes-engine/docs/how-to/cluster-access-for-kubectl) 并在集群上运行提供的 kubectl 命令。如果要通过获取集群访问权来运行此命令，你可以创建临时节点或使用 VPC 中的现有节点，或者登录到某个集群节点或使用某个集群节点创建 SSH 隧道。 + +### 直接访问 + +如果 Rancher server 与集群的 controlplane 运行在同一 VPC 上，它将直接访问 controlplane 的私有端点。集群节点将需要访问[私有镜像仓库](#私有镜像仓库)以下载上述的镜像。 + +你还可以使用 Google 的服务（例如 [Cloud VPN](https://cloud.google.com/network-connectivity/docs/vpn/concepts/overview) 或 [Cloud Interconnect VLAN](https://cloud.google.com/network-connectivity/docs/interconnect)）来促进组织网络与 Google VPC 之间的连接。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/cluster-configuration/rancher-server-configuration/k3s-cluster-configuration.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/cluster-configuration/rancher-server-configuration/k3s-cluster-configuration.md new file mode 100644 index 00000000000..6b6c2a7cf63 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/cluster-configuration/rancher-server-configuration/k3s-cluster-configuration.md @@ -0,0 +1,151 @@ +--- +title: K3s 集群配置参考 +--- + +本文介绍 Rancher 中可用于新的或现有的 K3s Kubernetes 集群的配置选项。 + +## 概述 + +你可以通过以下两种方式之一来配置 Kubernetes 选项： + +- [Rancher UI](#rancher-ui-中的配置选项)：使用 Rancher UI 来选择设置 Kubernetes 集群时常用的自定义选项。 +- [集群配置文件](#集群配置文件)：高级用户可以创建一个 K3s 配置文件，而不是使用 Rancher UI 来为集群选择 Kubernetes 选项。配置文件允许你设置 K3s 安装中可用的任何[选项](https://rancher.com/docs/k3s/latest/en/installation/install-options/)。 + +## Rancher UI 中的配置选项 + +:::tip + +一些高级配置选项没有在 Rancher UI 表单中开放，但你可以通过在 YAML 中编辑 K3s 集群配置文件来启用这些选项。有关 YAML 中 K3s 集群的可配置选项的完整参考，请参阅 [K3s 文档](https://rancher.com/docs/k3s/latest/en/installation/install-options/)。 + +::: + +### 基本信息 +#### Kubernetes 版本 + +这指的是集群节点上安装的 Kubernetes 版本。Rancher 基于 [hyperkube](https://github.com/rancher/hyperkube) 打包了自己的 Kubernetes 版本。 + +有关更多详细信息，请参阅[升级 Kubernetes](../../../getting-started/installation-and-upgrade/upgrade-and-roll-back-kubernetes.md)。 + +#### 加密密文 + +启用或禁用密文加密的选项。启用后，密文将使用 AES-CBC 密钥进行加密。如果禁用，则在再次启用加密之前无法读取任何以前的密文。有关详细信息，请参阅 [K3s 文档](https://rancher.com/docs/k3s/latest/en/advanced/#secrets-encryption-config-experimental)。 + +#### 项目网络隔离 + +如果你的网络提供商允许项目网络隔离，你可以选择启用或禁用项目间的通信。 + +#### SELinux + +启用或禁用 [SELinux](https://rancher.com/docs/k3s/latest/en/advanced/#selinux-support) 支持的选项。 + +#### CoreDNS + +默认情况下，[CoreDNS](https://coredns.io/) 会安装为默认 DNS 提供程序。如果未安装 CoreDNS，则必须自己安装备用 DNS 提供程序。有关详细信息，请参阅 [K3s 文档](https://rancher.com/docs/k3s/latest/en/networking/#coredns)。 + +#### Klipper Service LB + +启用或禁用 [Klipper](https://github.com/rancher/klipper-lb) 服务负载均衡器的选项。有关详细信息，请参阅 [K3s 文档](https://rancher.com/docs/k3s/latest/en/networking/#service-load-balancer)。 + +#### Traefik Ingress + +启用或禁用 [Traefik](https://traefik.io/) HTTP 反向代理和负载均衡器的选项。有关更多详细信息和配置选项，请参阅 [K3s 文档](https://rancher.com/docs/k3s/latest/en/networking/#traefik-ingress-controller)。 + +#### Local Storage + +在节点上启用或禁用 [Local Storage](https://rancher.com/docs/k3s/latest/en/storage/) 的选项。 + +#### Metrics Server + +启用或禁用 [metrics server](https://github.com/kubernetes-incubator/metrics-server) 的选项。如果启用，请确保为入站 TCP 流量打开 10250 端口。 + +### 附加配置 + +集群启动时将应用的其他 Kubernetes 清单，会作为[附加组件](https://kubernetes.io/docs/concepts/cluster-administration/addons/)来管理。有关详细信息，请参阅 [K3s 文档](https://rancher.com/docs/k3s/latest/en/helm/#automatically-deploying-manifests-and-helm-charts)。 + +### Agent 环境变量 + +为 [K3s agent](https://rancher.com/docs/k3s/latest/en/architecture/) 设置环境变量的选项。你可以使用键值对设置环境变量。有关详细信息，请参阅 [K3s 文档](https://rancher.com/docs/k3s/latest/en/installation/install-options/agent-config/)。 + +### etcd + +#### 自动快照 + +启用或禁用定期 etcd 快照的选项。如果启用，用户可以配置快照的频率。有关详细信息，请参阅 [K3s 文档](https://docs.k3s.io/cli/etcd-snapshot#creating-snapshots)。 + +#### 指标 + +选择向公众公开或仅在集群内公开 etcd 指标的选项。 + +### 网络 + +#### 集群 CIDR + +用于 pod IP 的 IPv4/IPv6 网络 CIDR（默认：10.42.0.0/16）。 + +#### Service CIDR + +用于 Service IP 的 IPv4/IPv6 网络 CIDR（默认：10.43.0.0/16）。 + +#### 集群 DNS + +用于 coredns 服务的 IPv4 集群 IP。应该在你的 service-cidr 范围内（默认：10.43.0.10）。 + +#### 集群域名 + +选择集群的域。默认值为 `cluster.local`。 + +#### NodePort 服务端口范围 + +更改可用于 [NodePort 服务](https://kubernetes.io/docs/concepts/services-networking/service/#nodeport)的端口范围的选项。默认值为 `30000-32767`。 + +#### 截断主机名 + +将主机名截断为 15 个或更少字符。该字段只能在集群初始创建时设置。创建集群后，你无法再启用或禁用 15 个字符的限制。 + +此设置仅影响配置了机器的集群。由于自定义集群在创建节点时设置主机名（发生在 Rancher 之外），因此该字段不限制自定义集群的主机名长度。 + +截断集群中的主机名可提高与基于 Windows 的系统的兼容性。虽然 Kubernetes 允许最长的主机名长度为 63 个字符，但使用 NetBIOS 的系统将主机名限制为 15 个字符之内。 + +#### TLS 可选名称 + +在服务器 TLS 证书上添加其他主机名或 IPv4/IPv6 地址作为 Subject Alternative Name。 + +#### 授权集群端点 + +授权集群端点（ACE）可用于直接访问 Kubernetes API server，而无需通过 Rancher 进行通信。 + +有关授权集群端点的工作原理以及使用的原因，请参阅[架构介绍](../../../reference-guides/rancher-manager-architecture/communicating-with-downstream-user-clusters.md#4-授权集群端点)。 + +我们建议使用具有授权集群端点的负载均衡器。有关详细信息，请参阅[推荐的架构](../../rancher-manager-architecture/architecture-recommendations.md#授权集群端点架构)。 + +### 镜像仓库 + +选择要从中拉取 Rancher 镜像的镜像仓库。有关更多详细信息和配置选项，请参阅 [K3s 文档](https://rancher.com/docs/k3s/latest/en/installation/private-registry/)。 + +### 升级策略 + +#### controlplane 并发 + +选择可以同时升级多少个节点。可以是固定数字或百分比。 + +#### Worker 并发 + +选择可以同时升级多少个节点。可以是固定数字或百分比。 + +#### 清空节点（controlplane） + +在升级之前从节点中删除所有 pod 的选项。 + +#### 清空节点（worker 节点） + +在升级之前从节点中删除所有 pod 的选项。 + +### 高级配置 + +为不同节点设置 kubelet 选项。有关可用选项，请参阅 [Kubernetes 文档](https://kubernetes.io/docs/reference/command-line-tools-reference/kubelet/)。 + +## 集群配置文件 + +高级用户可以创建一个 K3s 配置文件，而不是使用 Rancher UI 表单来为集群选择 Kubernetes 选项。配置文件允许你设置 K3s 安装中可用的任何[选项](https://rancher.com/docs/k3s/latest/en/installation/install-options/)。 + +要直接从 Rancher UI 编辑 K3s 配置文件，单击**以 YAML 文件编辑**。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/cluster-configuration/rancher-server-configuration/rancher-server-configuration.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/cluster-configuration/rancher-server-configuration/rancher-server-configuration.md new file mode 100644 index 00000000000..9d42590068e --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/cluster-configuration/rancher-server-configuration/rancher-server-configuration.md @@ -0,0 +1,15 @@ +--- +title: Rancher Server 配置 +--- + + + + + +- [RKE2 集群配置](rke2-cluster-configuration.md) +- [K3s 集群配置](k3s-cluster-configuration.md) +- [EKS 集群配置](eks-cluster-configuration.md) +- [AKS 集群配置](aks-cluster-configuration.md) +- [GKE 集群配置](gke-cluster-configuration/gke-cluster-configuration.md) +- [使用现有节点](use-existing-nodes/use-existing-nodes.md) +- [同步集群](sync-clusters.md) diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/cluster-configuration/rancher-server-configuration/rke1-cluster-configuration.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/cluster-configuration/rancher-server-configuration/rke1-cluster-configuration.md new file mode 100644 index 00000000000..043a6b43cc9 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/cluster-configuration/rancher-server-configuration/rke1-cluster-configuration.md @@ -0,0 +1,357 @@ +--- +title: RKE 集群配置参考 +--- + + + +Rancher 安装 Kubernetes 时，它使用 [RKE](../../../how-to-guides/new-user-guides/launch-kubernetes-with-rancher/launch-kubernetes-with-rancher.md) 或 [RKE2](https://docs.rke2.io/) 作为 Kubernetes 发行版。 + +本文介绍 Rancher 中可用于新的或现有的 RKE Kubernetes 集群的配置选项。 + + +## 概述 + +你可以通过以下两种方式之一来配置 Kubernetes 选项： + +- [Rancher UI](#rancher-ui-中的配置选项)：使用 Rancher UI 来选择设置 Kubernetes 集群时常用的自定义选项。 +- [集群配置文件](#rke-集群配置文件参考)：高级用户可以创建一个 RKE 配置文件，而不是使用 Rancher UI 来为集群选择 Kubernetes 选项。配置文件可以让你使用 YAML 来指定 RKE 安装中可用的任何选项（除了 system_images 配置）。 + +RKE 集群配置选项嵌套在 `rancher_kubernetes_engine_config` 参数下。有关详细信息，请参阅[集群配置文件](#rke-集群配置文件参考)。 + +在 [RKE 启动的集群](../../../how-to-guides/new-user-guides/launch-kubernetes-with-rancher/launch-kubernetes-with-rancher.md)中，你可以编辑任何后续剩余的选项。 + +有关 RKE 配置文件语法的示例，请参阅 [RKE 文档](https://rancher.com/docs/rke/latest/en/example-yamls/)。 + +Rancher UI 中的表单不包括配置 RKE 的所有高级选项。有关 YAML 中 RKE Kubernetes 集群的可配置选项的完整参考，请参阅 [RKE 文档](https://rancher.com/docs/rke/latest/en/config-options/)。 + +## 在 Rancher UI 中使用表单编辑集群 + +要编辑你的集群： + +1. 在左上角，单击 **☰ > 集群管理**。 +1. 转到要配置的集群，然后单击 **⋮ > 编辑配置**。 + + +## 使用 YAML 编辑集群 + +高级用户可以创建一个 RKE 配置文件，而不是使用 Rancher UI 来为集群选择 Kubernetes 选项。配置文件可以让你使用 YAML 来指定 RKE 安装中可用的任何选项（除了 system_images 配置）。 + +RKE 集群（也称为 RKE1 集群）的编辑方式与 RKE2 和 K3s 集群不同。 + +要直接从 Rancher UI 编辑 RKE 配置文件： + +1. 点击 **☰ > 集群管理**。 +1. 转到要配置的 RKE 集群。单击并单击 **⋮ > 编辑配置**。你将会转到 RKE 配置表单。请注意，由于集群配置在 Rancher 2.6 中发生了变更，**⋮ > 以 YAML 文件编辑**可用于配置 RKE2 集群，但不能用于编辑 RKE1 配置。 +1. 在配置表单中，向下滚动并单击**以 YAML 文件编辑**。 +1. 编辑 `rancher_kubernetes_engine_config` 参数下的 RKE 选项。 + +## Rancher UI 中的配置选项 + +:::tip + +一些高级配置选项没有在 Rancher UI 表单中开放，但你可以通过在 YAML 中编辑 RKE 集群配置文件来启用这些选项。有关 YAML 中 RKE Kubernetes 集群的可配置选项的完整参考，请参阅 [RKE 文档](https://rancher.com/docs/rke/latest/en/config-options/)。 + +::: + +### Kubernetes 版本 + +这指的是集群节点上安装的 Kubernetes 版本。Rancher 基于 [hyperkube](https://github.com/rancher/hyperkube) 打包了自己的 Kubernetes 版本。 + +有关更多详细信息，请参阅[升级 Kubernetes](../../../getting-started/installation-and-upgrade/upgrade-and-roll-back-kubernetes.md)。 + +### 网络提供商 + +这指的是集群使用的[网络提供商](https://kubernetes.io/docs/concepts/cluster-administration/networking/)。有关不同网络提供商的更多详细信息，请查看我们的[网络常见问题解答](../../../faq/container-network-interface-providers.md)。 + +:::caution + +启动集群后，你无法更改网络提供商。由于 Kubernetes 不允许在网络提供商之间切换，因此，请谨慎选择要使用的网络提供商。使用网络提供商创建集群后，如果你需要更改网络提供商，你将需要拆除整个集群以及其中的所有应用。 + +::: + +Rancher 与以下开箱即用的网络提供商兼容： + +- [Canal](https://github.com/projectcalico/canal) +- [Flannel](https://github.com/coreos/flannel#flannel) +- [Calico](https://docs.projectcalico.org/v3.11/introduction/) +- [Weave](https://github.com/weaveworks/weave) + +:::note Weave 注意事项： + +选择 Weave 作为网络提供商时，Rancher 将通过生成随机密码来自动启用加密。如果你想手动指定密码，请参阅使用[配置文件](#rke-集群配置文件参考)和 [Weave 网络插件选项](https://rancher.com/docs/rke/latest/en/config-options/add-ons/network-plugins/#weave-network-plug-in-options)来配置集群。 + +::: + +### 项目网络隔离 + +如果你的网络提供商允许项目网络隔离，你可以选择启用或禁用项目间的通信。 + +如果你使用支持执行 Kubernetes 网络策略的 RKE 网络插件（例如 Canal 或 Cisco ACI 插件），则可以使用项目网络隔离。 + +### Kubernetes 云提供商 + +你可以配置 [Kubernetes 云提供商](../../../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-cloud-providers/set-up-cloud-providers.md)。如果你想在 Kubernetes 中使用动态配置的[卷和存储](../../../how-to-guides/new-user-guides/manage-clusters/create-kubernetes-persistent-storage/create-kubernetes-persistent-storage.md)，你通常需要选择特定的云提供商。例如，如果你想使用 Amazon EBS，则需要选择 `aws` 云提供商。 + +:::note + +如果你要使用的云提供商未作为选项列出，你需要使用[配置文件选项](#rke-集群配置文件参考)来配置云提供商。请参考 [RKE 云提供商文档](https://rancher.com/docs/rke/latest/en/config-options/cloud-providers/)来了解如何配置云提供商。 + +::: + +### 私有镜像仓库 + +集群级别的私有镜像仓库配置仅能用于配置集群。 + +在 Rancher 中设置私有镜像仓库的主要方法有两种：通过[全局默认镜像仓库](../../../how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/global-default-private-registry.md)中的**设置**选项卡设置全局默认镜像仓库，以及在集群级别设置的高级选项中设置私有镜像仓库。全局默认镜像仓库可以用于离线设置，不需要凭证的镜像仓库。而集群级私有镜像仓库用于所有需要凭证的私有镜像仓库。 + +如果你的私有镜像仓库需要凭证，为了将凭证传递给 Rancher，你需要编辑每个需要从仓库中拉取镜像的集群的集群选项。 + +私有镜像仓库的配置选项能让 Rancher 知道要从哪里拉取用于集群的[系统镜像](https://rancher.com/docs/rke/latest/en/config-options/system-images/)或[附加组件镜像](https://rancher.com/docs/rke/latest/en/config-options/add-ons/)。 + +- **系统镜像**是维护 Kubernetes 集群所需的组件。 +- **附加组件**用于部署多个集群组件，包括网络插件、ingress controller、DNS 提供商或 metrics server。 + +有关为集群配置期间应用的组件设置私有镜像仓库的更多信息，请参阅[私有镜像仓库的 RKE 文档](https://rancher.com/docs/rke/latest/en/config-options/private-registries/)。 + +Rancher v2.6 引入了[为 RKE 集群配置 ECR 镜像仓库](https://rancher.com/docs/rke/latest/en/config-options/private-registries/#amazon-elastic-container-registry-ecr-private-registry-setup)的功能。 + +### 授权集群端点 + +授权集群端点（ACE）可用于直接访问 Kubernetes API server，而无需通过 Rancher 进行通信。 + +:::note + +授权集群端点仅适用于 Rancher 启动的 Kubernetes 集群，即只适用于 Rancher [使用 RKE](../../../reference-guides/rancher-manager-architecture/communicating-with-downstream-user-clusters.md#配置-kubernetes-集群的工具) 来配置的集群。它不适用于托管在 Kubernetes 提供商中的集群，例如 Amazon 的 EKS。 + +::: + +在 Rancher 启动的 Kubernetes 集群中，它默认启用，使用具有 `controlplane` 角色的节点的 IP 和默认的 Kubernetes 自签名证书。 + +有关授权集群端点的工作原理以及使用的原因，请参阅[架构介绍](../../../reference-guides/rancher-manager-architecture/communicating-with-downstream-user-clusters.md#4-授权集群端点)。 + +我们建议使用具有授权集群端点的负载均衡器。有关详细信息，请参阅[推荐的架构](../../rancher-manager-architecture/architecture-recommendations.md#授权集群端点架构)。 + +### 节点池 + +有关使用 Rancher UI 在 RKE 集群中设置节点池的信息，请参阅[此页面](../../../how-to-guides/new-user-guides/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/use-new-nodes-in-an-infra-provider.md)。 + +### NGINX Ingress + +如果你想使用高可用性配置来发布应用，并且你使用没有原生负载均衡功能的云提供商来托管主机，请启用此选项以在集群中使用 NGINX Ingress。 + +### Metrics Server 监控 + +这是启用或禁用 [Metrics Server](https://rancher.com/docs/rke/latest/en/config-options/add-ons/metrics-server/) 的选项。 + +每个能够使用 RKE 启动集群的云提供商都可以收集指标并监控你的集群节点。如果启用此选项，你可以从你的云提供商门户查看你的节点指标。 + +### 节点上的 Docker 版本 + +表示是否允许节点运行 Rancher 不正式支持的 Docker 版本。 + +如果你选择使用支持的 Docker 版本，Rancher 会禁止 pod 运行在安装了不支持的 Docker 版本的节点上。 + +如需了解各个 Rancher 版本通过了哪些 Docker 版本测试，请参见[支持和维护条款](https://rancher.com/support-maintenance-terms/)。 + +### Docker 根目录 + +如果要添加到集群的节点为 Docker 配置了非默认 Docker 根目录（默认为 `/var/lib/docker`），请在此选项中指定正确的 Docker 根目录。 + +### 默认 Pod 安全策略 + +如果你启用了 **Pod 安全策略支持**，请使用此下拉菜单选择应用于集群的 pod 安全策略。 + +### 节点端口范围 + +更改可用于 [NodePort 服务](https://kubernetes.io/docs/concepts/services-networking/service/#nodeport)的端口范围的选项。默认为 `30000-32767`。 + +### 定期 etcd 快照 + +启用或禁用[定期 etcd 快照](https://rancher.com/docs/rke/latest/en/etcd-snapshots/#etcd-recurring-snapshots)的选项。 + +### Agent 环境变量 + +为 [rancher agent](../../../how-to-guides/new-user-guides/launch-kubernetes-with-rancher/about-rancher-agents.md) 设置环境变量的选项。你可以使用键值对设置环境变量。如果 Rancher Agent 需要使用代理与 Rancher Server 通信，则可以使用 Agent 环境变量设置 `HTTP_PROXY`，`HTTPS_PROXY` 和 `NO_PROXY` 环境变量。 + +### 更新 ingress-nginx + +使用 Kubernetes 1.16 之前版本创建的集群将具有 `OnDelete`的 `ingress-nginx` `updateStrategy`。使用 Kubernetes 1.16 或更高版本创建的集群将具有 `RollingUpdate`。 + +如果 `ingress-nginx` 的 `updateStrategy` 是 `OnDelete`，则需要删除这些 pod 以获得 deployment 正确的版本。 + +### Cluster Agent 配置和 Fleet Agent 配置 + +你可以为 Cluster Agent 和集群的 Fleet Agent 配置调度字段和资源限制。你可以使用这些字段来自定义容忍度、亲和性规则和资源要求。其他容忍度会被尾附到默认容忍度和 Control Plane 节点污点的列表中。如果你定义了自定义亲和性规则，它们将覆盖全局默认亲和性设置。定义资源要求会在以前没有的地方设置请求或限制。 + +:::note + +有了这个选项，你可以覆盖或删除运行集群所需的规则。我们强烈建议你不要删除或覆盖这些规则和其他亲和性规则，因为这可能会导致不必要的影响： + +- `affinity.nodeAffinity.requiredDuringSchedulingIgnoredDuringExecution` 用于 `cattle-cluster-agent` +- `cluster-agent-default-affinity` 用于 `cattle-cluster-agent` +- `fleet-agent-default-affinity` 用于 `fleet-agent` + +::: + +如果将 Rancher 降级到 v2.7.4 或更低版本，你的更改将丢失，而且 Agent 将在没有你的自定义设置的情况下重新部署。重新部署时，Fleet Agent 将回退到使用内置默认值。如果降级期间 Fleet 版本没有更改，则不会立即重新部署。 + + +## RKE 集群配置文件参考 + +高级用户可以创建一个 RKE 配置文件，而不是使用 Rancher UI 来为集群选择 Kubernetes 选项。配置文件可以让你在 RKE 安装中设置任何[可用选项](https://rancher.com/docs/rke/latest/en/config-options/)（`system_images` 配置除外）。使用 Rancher UI 或 API 创建集群时，不支持 `system_images` 选项。 + +有关 YAML 中 RKE Kubernetes 集群的可配置选项的完整参考，请参阅 [RKE 文档](https://rancher.com/docs/rke/latest/en/config-options/)。 + +### Rancher 中的配置文件结构 + +RKE（Rancher Kubernetes Engine）是 Rancher 用来配置 Kubernetes 集群的工具。过去，Rancher 的集群配置文件与 [RKE 配置文件](https://rancher.com/docs/rke/latest/en/example-yamls/)的结构是一致的。但由于 Rancher 文件结构发生了变化，因此在 Rancher 中，RKE 集群配置项与非 RKE 配置项是分开的。所以，你的集群配置需要嵌套在集群配置文件中的 `rancher_kubernetes_engine_config` 参数下。使用早期版本的 Rancher 创建的集群配置文件需要针对这种格式进行更新。以下是一个集群配置文件示例： + +
+ 集群配置文件示例 + +```yaml +# +# Cluster Config +# +docker_root_dir: /var/lib/docker +enable_cluster_alerting: false +enable_cluster_monitoring: false +enable_network_policy: false +local_cluster_auth_endpoint: + enabled: true +# +# Rancher Config +# +rancher_kubernetes_engine_config: # Your RKE template config goes here. + addon_job_timeout: 30 + authentication: + strategy: x509 + ignore_docker_version: true +# +# # 目前仅支持 Nginx ingress provider +# # 要禁用 Ingress controller，设置 `provider: none` +# # 要在指定节点上禁用 Ingress，使用 node_selector，例如： +# provider: nginx +# node_selector: +# app: ingress +# + ingress: + provider: nginx + kubernetes_version: v1.15.3-rancher3-1 + monitoring: + provider: metrics-server +# +# If you are using calico on AWS +# +# network: +# plugin: calico +# calico_network_provider: +# cloud_provider: aws +# +# # To specify flannel interface +# +# network: +# plugin: flannel +# flannel_network_provider: +# iface: eth1 +# +# # To specify flannel interface for canal plugin +# +# network: +# plugin: canal +# canal_network_provider: +# iface: eth1 +# + network: + options: + flannel_backend_type: vxlan + plugin: canal +# +# services: +# kube-api: +# service_cluster_ip_range: 10.43.0.0/16 +# kube-controller: +# cluster_cidr: 10.42.0.0/16 +# service_cluster_ip_range: 10.43.0.0/16 +# kubelet: +# cluster_domain: cluster.local +# cluster_dns_server: 10.43.0.10 +# + services: + etcd: + backup_config: + enabled: true + interval_hours: 12 + retention: 6 + safe_timestamp: false + creation: 12h + extra_args: + election-timeout: 5000 + heartbeat-interval: 500 + gid: 0 + retention: 72h + snapshot: false + uid: 0 + kube_api: + always_pull_images: false + pod_security_policy: false + service_node_port_range: 30000-32767 + ssh_agent_auth: false +windows_prefered_cluster: false +``` +
+ +### 默认 DNS 提供商 + +下表显示了默认部署的 DNS 提供商。有关如何配置不同 DNS 提供商的更多信息，请参阅 [DNS 提供商相关的 RKE 文档](https://rancher.com/docs/rke/latest/en/config-options/add-ons/dns/)。CoreDNS 只能在 Kubernetes v1.12.0 及更高版本上使用。 + +| Rancher 版本 | Kubernetes 版本 | 默认 DNS 提供商 | +|-------------|--------------------|----------------------| +| v2.2.5 及更高版本 | v1.14.0 及更高版本 | CoreDNS | +| v2.2.5 及更高版本 | v1.13.x 及更低版本 | kube-dns | +| v2.2.4 及更低版本 | 任意 | kube-dns | + +## YAML 中的 Rancher 特定参数 + +除了 RKE 配置文件选项外，还有可以在配置文件 (YAML) 中配置的 Rancher 特定设置如下。 + +### docker_root_dir + +请参阅 [Docker 根目录](#docker-根目录)。 + +### enable_cluster_monitoring + +启用或禁用[集群监控](../../../integrations-in-rancher/monitoring-and-alerting/monitoring-and-alerting.md)的选项。 + +### enable_network_policy + +启用或禁用项目网络隔离的选项。 + +如果你使用支持执行 Kubernetes 网络策略的 RKE 网络插件（例如 Canal 或 Cisco ACI 插件），则可以使用项目网络隔离。 + +### local_cluster_auth_endpoint + +请参阅[授权集群端点](#授权集群端点)。 + +示例： + +```yaml +local_cluster_auth_endpoint: + enabled: true + fqdn: "FQDN" + ca_certs: |- + -----BEGIN CERTIFICATE----- + ... + -----END CERTIFICATE----- +``` + +### 自定义网络插件 + +你可以使用 RKE 的[用户定义的附加组件功能](https://rancher.com/docs/rke/latest/en/config-options/add-ons/user-defined-add-ons/)来添加自定义网络插件。部署 Kubernetes 集群之后，你可以定义要部署的任何附加组件。 + +有两种方法可以指定附加组件： + +- [内嵌附加组件](https://rancher.com/docs/rke/latest/en/config-options/add-ons/user-defined-add-ons/#in-line-add-ons) +- [为附加组件引用 YAML 文件](https://rancher.com/docs/rke/latest/en/config-options/add-ons/user-defined-add-ons/#referencing-yaml-files-for-add-ons) + +有关如何通过编辑 `cluster.yml` 来配置自定义网络插件的示例，请参阅 [RKE 文档](https://rancher.com/docs/rke/latest/en/config-options/add-ons/network-plugins/custom-network-plugin-example)。 \ No newline at end of file diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/cluster-configuration/rancher-server-configuration/rke2-cluster-configuration.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/cluster-configuration/rancher-server-configuration/rke2-cluster-configuration.md new file mode 100644 index 00000000000..c88096c7b68 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/cluster-configuration/rancher-server-configuration/rke2-cluster-configuration.md @@ -0,0 +1,356 @@ +--- +title: RKE2 集群配置参考 +--- + +本文介绍 Rancher 中可用于新的或现有的 RKE2 Kubernetes 集群的配置选项。 + +## 概述 + +你可以通过以下两种方式之一来配置 Kubernetes 选项： + +- [Rancher UI](#rancher-ui-中的配置选项)：使用 Rancher UI 来选择设置 Kubernetes 集群时常用的自定义选项。 +- [集群配置文件](#集群配置文件参考)：高级用户可以创建一个 RKE2 配置文件，而不是使用 Rancher UI 来为集群选择 Kubernetes 选项。配置文件让你能设置更多可用于 RKE2 的其他[安装选项](https://docs.rke2.io/install/configuration)。 + +## 在 Rancher UI 中使用表单编辑集群 + +要编辑你的集群： + +1. 在左上角，单击 **☰ > 集群管理**。 +1. 转到要配置的集群，然后单击 **⋮ > 编辑配置**。 + +## 使用 YAML 编辑集群 + +高级用户可以创建一个 RKE2 配置文件，而不是使用 Rancher UI 来为集群选择 Kubernetes 选项。配置文件可以让你使用 YAML 来指定 RKE2 安装中可用的任何选项。 + +要直接从 Rancher UI 中编辑 RKE2 配置文件： + +1. 点击 **☰ > 集群管理**。 +1. 转到你要配置的集群，然后单击 **⋮ > 以 YAML 文件编辑**。 +1. 编辑 `rkeConfig` 参数下的 RKE 选项。 + +## Rancher UI 中的配置选项 + +:::tip + +一些高级配置选项没有在 Rancher UI 表单中开放，但你可以通过在 YAML 中编辑 RKE2 集群配置文件来启用这些选项。有关 YAML 中 RKE2 Kubernetes 集群的可配置选项的完整参考，请参阅 [RKE2 文档](https://docs.rke2.io/install/configuration)。 + +::: + +## 主机池 + +本小节介绍了通用的主机池配置。对于针对特定基础设施提供商的配置，请参阅以下页面： + +- [Azure](../downstream-cluster-configuration/machine-configuration/azure.md) +- [DigitalOcean](../downstream-cluster-configuration/machine-configuration/digitalocean.md) +- [EC2](../downstream-cluster-configuration/machine-configuration/amazon-ec2.md) + +### 池名称 + +主机池的名称。 + +### 主机数量 + +池中的主机数。 + +### 角色 + +将 etcd、controlplane 和 worker 角色分配给节点的选项。 + +### 高级配置 + +#### 自动替换 + +如果节点无法访问的持续时间达到该值，则会被自动删除和替换。 + +#### 删除前清空 + +通过在删除节点之前驱逐所有 pod 来清空节点。 + +#### Kubernetes 节点标签 + +将[标签](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/)（label）添加到节点，让对象选择更加简便。 + +有关标签语法的详细信息，请参阅 [Kubernetes 文档](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/#syntax-and-character-set)。 + +#### 污点 + +将[污点](https://kubernetes.io/docs/concepts/configuration/taint-and-toleration/)（taint）添加到节点，防止 pod 被调度或在节点上执行（除非 pod 具有匹配的容忍度）。 + +## 集群配置 + +### 基本信息 +#### Kubernetes 版本 + +这指的是集群节点上安装的 Kubernetes 版本。Rancher 基于 [hyperkube](https://github.com/rancher/hyperkube) 打包了自己的 Kubernetes 版本。 + +有关更多详细信息，请参阅[升级 Kubernetes](../../../getting-started/installation-and-upgrade/upgrade-and-roll-back-kubernetes.md)。 + +#### 容器网络提供商 + +这指的是集群使用的[网络提供商](https://kubernetes.io/docs/concepts/cluster-administration/networking/)。 + +:::caution + +启动集群后，你无法更改网络提供商。由于 Kubernetes 不允许在网络提供商之间切换，因此，请谨慎选择要使用的网络提供商。使用网络提供商创建集群后，如果你需要更改网络提供商，你将需要拆除整个集群以及其中的所有应用。 + +::: + +Rancher 与以下开箱即用的网络提供商兼容： + +- [Canal](https://github.com/projectcalico/canal) +- [Cilium](https://cilium.io/)\* +- [Calico](https://docs.projectcalico.org/v3.11/introduction/) +- [Multus](https://github.com/k8snetworkplumbingwg/multus-cni) + +\* 在 [Cilium CNI](../../../faq/container-network-interface-providers.md#cilium) 中使用[项目网络隔离](#项目网络隔离)时，你可以开启跨节点入口路由。详情请参见 [CNI 提供商文档](../../../faq/container-network-interface-providers.md#cilium-中跨节点的-ingress-路由)。 + +有关不同网络提供商以及如何配置它们的更多详细信息，请查阅 [RKE2 文档](https://docs.rke2.io/install/network_options)。 + +##### 双栈网络 + +所有 CNI 网络插件都支持[双栈](https://docs.rke2.io/install/network_options#dual-stack-configuration)网络。要在双栈模式下配置 RKE2，请为你的[集群 CIDR](#集群-cidr) 和/或 [Service CIDR](#service-cidr) 设置有效的 IPv4/IPv6 CIDR。 + +###### 额外配置 + +使用 `cilium` 或 `multus,cilium` 作为容器网络接口提供商时，请确保**启用 IPv6 支持**选项。 + +#### 云提供商 + +你可以配置 [Kubernetes 云提供商](../../../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-cloud-providers/set-up-cloud-providers.md)。如果你想在 Kubernetes 中使用动态配置的[卷和存储](../../../how-to-guides/new-user-guides/manage-clusters/create-kubernetes-persistent-storage/create-kubernetes-persistent-storage.md)，你通常需要选择特定的云提供商。例如，如果你想使用 Amazon EBS，则需要选择 `aws` 云提供商。 + +:::note + +如果你要使用的云提供商未作为选项列出，你需要使用[配置文件选项](#集群配置文件参考)来配置云提供商。请参考[本文档](https://rancher.com/docs/rke/latest/en/config-options/cloud-providers/)来了解如何配置云提供商。 + +::: + +#### Worker CIS 配置文件 + +选择一个 [CIS benchmark](../../../how-to-guides/advanced-user-guides/cis-scan-guides/cis-scan-guides.md) 来验证系统配置。 + +#### 项目网络隔离 + +如果你的网络提供商允许项目网络隔离，你可以选择启用或禁用项目间的通信。 + +如果你使用支持执行 Kubernetes 网络策略的 RKE2 网络插件（例如 Canal），则可以使用项目网络隔离。 + +#### CoreDNS + +默认情况下，[CoreDNS](https://coredns.io/) 会安装为默认 DNS 提供程序。如果未安装 CoreDNS，则必须自己安装备用 DNS 提供程序。有关其他 CoreDNS 配置，请参阅 [RKE2 文档](https://docs.rke2.io/networking/networking_services#coredns)。 + +#### NGINX Ingress + +如果你想使用高可用性配置来发布应用，并且你使用没有原生负载均衡功能的云提供商来托管主机，请启用此选项以在集群中使用 NGINX Ingress。有关其他配置选项，请参阅 [RKE2 文档](https://docs.rke2.io/networking/networking_services#nginx-ingress-controller)。 + +有关其他配置选项，请参阅 [RKE2 文档](https://docs.rke2.io/networking/networking_services#nginx-ingress-controller)。 + +#### Metrics Server + +这是启用或禁用 [Metrics Server](https://rancher.com/docs/rke/latest/en/config-options/add-ons/metrics-server/) 的选项。 + +每个能够使用 RKE2 启动集群的云提供商都可以收集指标并监控你的集群节点。如果启用此选项，你可以从你的云提供商门户查看你的节点指标。 + +### 附加配置 + +集群启动时将应用的其他 Kubernetes 清单，会作为[附加组件](https://kubernetes.io/docs/concepts/cluster-administration/addons/)来管理。有关详细信息，请参阅 [RKE2 文档](https://docs.rke2.io/helm#automatically-deploying-manifests-and-helm-charts)。 + +### Agent 环境变量 + +为 [Rancher agent](../../../how-to-guides/new-user-guides/launch-kubernetes-with-rancher/about-rancher-agents.md) 设置环境变量的选项。你可以使用键值对设置环境变量。有关详细信息，请参阅 [RKE2 文档](https://docs.rke2.io/reference/linux_agent_config)。 + +### etcd + +#### 自动快照 + +启用或禁用定期 etcd 快照的选项。如果启用，用户可以配置快照的频率。有关详细信息，请参阅 [RKE2 文档](https://docs.rke2.io/datastore/backup_restore#creating-snapshots)。请注意，如果使用 RKE2，快照会存储在每个 etcd 节点上，这与 RKE1 不同（RKE1 每个集群只存储一个快照）。 + +#### 指标 + +选择向公众公开或仅在集群内公开 etcd 指标的选项。 + +### 网络 + +#### 集群 CIDR + +用于 pod IP 的 IPv4 和/或 IPv6 网络 CIDR（默认：10.42.0.0/16）。 + +##### 双栈网络 + +要配置[双栈](https://docs.rke2.io/install/network_options#dual-stack-configuration)模式，请输入有效的 IPv4/IPv6 CIDR。例如 `10.42.0.0/16,2001:cafe:42:0::/56`。 + +使用 `cilium` 或 `multus,cilium` 作为[容器网络](#容器网络提供商)接口提供商时，你需要进行[附加配置](#额外配置)。 + +#### Service CIDR + +用于 Service IP 的 IPv4/IPv6 网络 CIDR（默认：10.43.0.0/16）。 + +##### 双栈网络 + +要配置[双栈](https://docs.rke2.io/install/network_options#dual-stack-configuration)模式，请输入有效的 IPv4/IPv6 CIDR。例如 `10.42.0.0/16,2001:cafe:42:0::/56`。 + +使用 `cilium` 或 `multus,cilium` 作为[容器网络](#容器网络提供商)接口提供商时，你需要进行[附加配置](#额外配置)。 + +#### 集群 DNS + +用于 coredns 服务的 IPv4 集群 IP。应该在你的 service-cidr 范围内（默认：10.43.0.10）。 + +#### 集群域名 + +选择集群的域。默认值为 `cluster.local`。 + +#### NodePort 服务端口范围 + +更改可用于 [NodePort 服务](https://kubernetes.io/docs/concepts/services-networking/service/#nodeport)的端口范围的选项。默认值为 `30000-32767`。 + +#### 截断主机名 + +将主机名截断为 15 个或更少字符。该字段只能在集群初始创建时设置。创建集群后，你无法再启用或禁用 15 个字符的限制。 + +此设置仅影响配置了机器的集群。由于自定义集群在创建节点时设置主机名（发生在 Rancher 之外），因此该字段不限制自定义集群的主机名长度。 + +截断集群中的主机名可提高与基于 Windows 的系统的兼容性。虽然 Kubernetes 允许最长的主机名长度为 63 个字符，但使用 NetBIOS 的系统将主机名限制为 15 个字符之内。 + +#### TLS 可选名称 + +在服务器 TLS 证书上添加其他主机名或 IPv4/IPv6 地址作为 Subject Alternative Name。 + +#### 授权集群端点 + +授权集群端点（ACE）可用于直接访问 Kubernetes API server，而无需通过 Rancher 进行通信。 + +在 Rancher 启动的 Kubernetes 集群中，它默认启用，使用具有 `controlplane` 角色的节点的 IP 和默认的 Kubernetes 自签名证书。 + +有关授权集群端点的工作原理以及使用的原因，请参阅[架构介绍](../../../reference-guides/rancher-manager-architecture/communicating-with-downstream-user-clusters.md#4-授权集群端点)。 + +我们建议使用具有授权集群端点的负载均衡器。有关详细信息，请参阅[推荐的架构](../../rancher-manager-architecture/architecture-recommendations.md#授权集群端点架构)。 + +### 镜像仓库 + +选择要从中拉取 Rancher 镜像的镜像仓库。有关更多详细信息和配置选项，请参阅 [RKE2 文档](https://docs.rke2.io/install/private_registry)。 + +### 升级策略 + +#### controlplane 并发 + +选择可以同时升级多少个节点。可以是固定数字或百分比。 + +#### Worker 并发 + +选择可以同时升级多少个节点。可以是固定数字或百分比。 + +#### 清空节点（controlplane） + +在升级之前从节点中删除所有 pod 的选项。 + +#### 清空节点（worker 节点） + +在升级之前从节点中删除所有 pod 的选项。 + +### 高级配置 + +为不同节点设置 kubelet 选项。有关可用选项，请参阅 [Kubernetes 文档](https://kubernetes.io/docs/reference/command-line-tools-reference/kubelet/)。 + +## 集群配置文件参考 + +高级用户可以创建一个配置文件，而不是使用 Rancher UI 来为集群选择 Kubernetes 选项。配置文件允许你为 RKE2 设置[可用的选项](https://docs.rke2.io/install/configuration)，其中包括已经在 [Rancher UI 配置选项](#rancher-ui-中的配置选项)中列出的选项以及 Rancher 特定的参数。 + +
+ + 集群配置文件片段示例 + + +```yaml +spec: + cloudCredentialSecretName: cattle-global-data:cc-s879v + kubernetesVersion: v1.23.6+rke2r2 + localClusterAuthEndpoint: {} + rkeConfig: + chartValues: + rke2-calico: {} + etcd: + snapshotRetention: 5 + snapshotScheduleCron: 0 */5 * * * + machineGlobalConfig: + cni: calico + disable-kube-proxy: false + etcd-expose-metrics: false + profile: null + machinePools: + - controlPlaneRole: true + etcdRole: true + machineConfigRef: + kind: Amazonec2Config + name: nc-test-pool1-pwl5h + name: pool1 + quantity: 1 + unhealthyNodeTimeout: 0s + workerRole: true + machineSelectorConfig: + - config: + protect-kernel-defaults: false + registries: {} + upgradeStrategy: + controlPlaneConcurrency: "1" + controlPlaneDrainOptions: + deleteEmptyDirData: true + enabled: true + gracePeriod: -1 + ignoreDaemonSets: true + timeout: 120 + workerConcurrency: "1" + workerDrainOptions: + deleteEmptyDirData: true + enabled: true + gracePeriod: -1 + ignoreDaemonSets: true + timeout: 120 +``` +
+ +### chartValues + +此选项用于为 RKE2/K3s 安装的 System Chart 指定值。 + +示例： + +```yaml +chartValues: + chart-name: + key: value +``` +### machineGlobalConfig + +RKE2/K3s 配置嵌套在 `machineGlobalConfig` 参数下。在这里所做的任何配置更改都将应用到每个节点。你可以在此处应用[RKE2 的独立版本](https://docs.rke2.io/reference/server_config)中可用的配置选项。 + +示例： + +```yaml +machineGlobalConfig: + etcd-arg: + - key1=value1 + - key2=value2 +``` + +### machineSelectorConfig + +此参数与 [`machineGlobalConfig`](#machineglobalconfig) 相同，只是可以在配置中指定 [label](#kubernetes-节点标签) 选择器。该配置仅应用于与标签选择器匹配的节点。 + +允许多个 `config` 条目，可以为每个条目指定各自的 `machineLabelSelector`。用户可以指定 `matchExpressions`、`matchLabels`、指定二者或都不指定。如果你省略了 `machineLabelSelector`，则与将 config 放入 `machineGlobalConfig` 的效果相同。 + +示例： + +```yaml +machineSelectorConfig + - config: + config-key: config-value + machineLabelSelector: + matchExpressions: + - key: example-key + operator: string # 有效的运算符：In、NotIn、Exists 和 DoesNotExist + values: + - example-value1 + - example-value2 + matchLabels: + key1: value1 + key2: value2 +``` diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/cluster-configuration/rancher-server-configuration/sync-clusters.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/cluster-configuration/rancher-server-configuration/sync-clusters.md new file mode 100644 index 00000000000..af2782a81b3 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/cluster-configuration/rancher-server-configuration/sync-clusters.md @@ -0,0 +1,41 @@ +--- +title: 同步 +--- + +同步允许 Rancher 更新集群值，以便与托管在 AKS、EKS 或 GKE 中的集群对象保持同步。这使得 Rancher 以外的来源能够获取托管集群的状态。这是 UI 中显示的内容。 + +:::caution +如果你同时处理来自另一个来源的更新，你可能会不小心覆盖一个来源的状态。如果你在完成一个来源的更新后 5 分钟内处理另一个来源的更新，也可能会发生这种情况。 +::: + +## 工作原理 + +要理解同步是如何工作的，则必须理解 Rancher Cluster 对象上的两个字段： + +1. 集群的 config 对象，位于集群的规范上： + + * 对于 AKS，该字段称为 AKSConfig + * 对于 EKS，该字段称为 EKSConfig + * 对于 GKE，该字段称为 GKEConfig + +2. UpstreamSpec 对象 + + * 对于 AKS，它位于群集状态的 AKSStatus 字段中。 + * 对于 EKS，它位于集群状态的 EKSStatus 字段中。 + * 对于 GKE，它位于集群状态的 GKEStatus 字段中。 + +定义这些对象的结构类型可以在它们对应的 operator 项目中找到： + +* [aks-operator](https://github.com/rancher/aks-operator/blob/master/pkg/apis/aks.cattle.io/v1/types.go) +* [eks-operator](https://github.com/rancher/eks-operator/blob/master/pkg/apis/eks.cattle.io/v1/types.go) +* [gke-operator](https://github.com/rancher/gke-operator/blob/master/pkg/apis/gke.cattle.io/v1/types.go) + +除集群名称、位置（区域或地区）、导入和云凭证引用外，所有字段均可为空。 + +AKSConfig、EKSConfig 或 GKEConfig 表示所需的状态。零值会被忽略。配置对象中非零的字段可以被认为是“管理的”。在 Rancher 中创建集群时，所有字段都是非零的，因此都是“管理”的。在把一个已存在的集群注册到 Rancher 时，所有可为空字段都是 nil 并且不是“管理”的。一旦 Rancher 更改了这些字段的值，这些字段就会被管理。 + +UpstreamSpec 代表集群在托管的 Kubernetes 提供商中的情况。它每 5 分钟刷新一次。刷新 UpstreamSpec 后，Rancher 会检查集群是否正在进行更新。如果它正在更新，则不做任何进一步处理。如果它目前没有更新，AKSConfig、EKSConfig 或 GKEConfig 上的任何 "管理" 字段都会被最近更新的 UpstreamSpec 上的相应值覆盖。 + +有效的期望状态可以被认为是 UpstreamSpec，加上 AKSConfig、EKSConfig 或 GKEConfig 中的所有非零字段。这是 UI 中显示的内容。 + +如果 Rancher 和另一个来源试图在同一时间或在更新完成后的 5 分钟尝试更新集群，任何管理字段都可能陷入竞争状态。以 EKS 为例，集群可能将 PrivateAccess 作为管理字段。如果 PrivateAccess 为 false，在 11:01 在 EKS 控制台中启用，然后 Rancher 在 11:05 之前更新标签，那么该值很可能被覆盖。如果在集群处理更新时更新了标签，也会发生这种情况。如果集群已注册并且 PrivateAccess 字段为 nil，则不应发生此示例中描述的问题。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/cluster-configuration/rancher-server-configuration/use-existing-nodes/rancher-agent-options.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/cluster-configuration/rancher-server-configuration/use-existing-nodes/rancher-agent-options.md new file mode 100644 index 00000000000..895c75d5c0e --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/cluster-configuration/rancher-server-configuration/use-existing-nodes/rancher-agent-options.md @@ -0,0 +1,53 @@ +--- +title: Rancher Agent 选项 +--- + +Rancher 在每个节点上部署一个 Agent 来与节点通信。本文描述了可以传递给 Agent 的选项。要使用这些选项，你需要[使用自定义节点创建集群](./use-existing-nodes.md)，并在添加节点时将选项添加到生成的 `docker run` 命令。 + +有关 Rancher 如何使用 Node Agent 与下游集群通信的概述，请参阅[产品架构](../../../rancher-manager-architecture/communicating-with-downstream-user-clusters.md#3-node-agents)。 + +## 通用选项 + +| 参数 | 环境变量 | 描述 | +| ---------- | -------------------- | ----------- | +| `--server` | `CATTLE_SERVER` | 已配置的 Rancher `server-url`，Agent 将通过这个地址连接 Server。 | +| `--token` | `CATTLE_TOKEN` | 在 Rancher 中注册节点所需的 Token。 | +| `--ca-checksum` | `CATTLE_CA_CHECKSUM` | 使用已配置的 Rancher `cacerts` 进行 SHA256 校验和验证。 | +| `--node-name` | `CATTLE_NODE_NAME` | 覆盖用于注册节点的主机名（默认为 `hostname -s`）。 | +| `--label` | `CATTLE_NODE_LABEL` | 向节点添加节点标签。对于多个标签，请传递额外的 `--label` 选项。(`--label key=value`) | +| `--taints` | `CATTLE_NODE_TAINTS` | 将节点污点添加到节点。对于多个污点，请传递额外的 `--taints` 选项。(`--taints key=value:effect`) | + +## 角色选项 + +| 参数 | 环境变量 | 描述 | +| ---------- | -------------------- | ----------- | +| `--all-roles` | `ALL=true` | 将所有角色（`etcd`、`controlplane`、`worker`）应用到节点。 | +| `--etcd` | `ETCD=true` | 将角色 `etcd` 应用到节点。 | +| `--controlplane` | `CONTROL=true` | 将角色 `controlplane` 应用到节点。 | +| `--worker` | `WORKER=true` | 将角色 `worker` 应用到节点。 | + +## IP 地址选项 + +| 参数 | 环境变量 | 描述 | +| ---------- | -------------------- | ----------- | +| `--address` | `CATTLE_ADDRESS` | 节点将注册的 IP 地址（默认为用于连接 `8.8.8.8`的 IP）。 | +| `--internal-address` | `CATTLE_INTERNAL_ADDRESS` | 私有网络上用于主机间通信的 IP 地址。 | + +### 动态 IP 地址选项 + +出于自动化目的，你不能在命令中使用特定的 IP 地址，因为它必须是通用的才能用于每个节点。为此，我们提供了动态 IP 地址的选项。它们用作现有 IP 地址选项的值。支持 `--address` 和 `--internal-address`。 + +| 值 | 示例 | 描述 | +| ---------- | -------------------- | ----------- | +| 接口名称 | `--address eth0` | 将从给定的接口中检索第一个配置的 IP 地址。 | +| `ipify` | `--address ipify` | 将使用从 `https://api.ipify.org` 检索到的值。 | +| `awslocal` | `--address awslocal` | 将使用从 `http://169.254.169.254/latest/meta-data/local-ipv4` 检索到的值。 | +| `awspublic` | `--address awspublic` | 将使用从 `http://169.254.169.254/latest/meta-data/public-ipv4` 检索到的值。 | +| `doprivate` | `--address doprivate` | 将使用从 `http://169.254.169.254/metadata/v1/interfaces/private/0/ipv4/address` 检索到的值。 | +| `dopublic` | `--address dopublic` | 将使用从 `http://169.254.169.254/metadata/v1/interfaces/public/0/ipv4/address` 检索到的值。 | +| `azprivate` | `--address azprivate` | 将使用从 `http://169.254.169.254/metadata/instance/network/interface/0/ipv4/ipAddress/0/privateIpAddress?api-version=2017-08-01&format=text` 检索到的值。 | +| `azpublic` | `--address azpublic` | 将使用从 `http://169.254.169.254/metadata/instance/network/interface/0/ipv4/ipAddress/0/publicIpAddress?api-version=2017-08-01&format=text` 检索到的值。 | +| `gceinternal` | `--address gceinternal` | 将使用从 `http://metadata.google.internal/computeMetadata/v1/instance/network-interfaces/0/ip` 检索到的值。 | +| `gceexternal` | `--address gceexternal` | 将使用从 `http://metadata.google.internal/computeMetadata/v1/instance/network-interfaces/0/access-configs/0/external-ip` 检索到的值。 | +| `packetlocal` | `--address packetlocal` | 将使用从 `https://metadata.packet.net/2009-04-04/meta-data/local-ipv4` 检索到的值。 | +| `packetpublic` | `--address packetlocal` | 将使用从 `https://metadata.packet.net/2009-04-04/meta-data/public-ipv4` 检索到的值。 | diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/cluster-configuration/rancher-server-configuration/use-existing-nodes/use-existing-nodes.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/cluster-configuration/rancher-server-configuration/use-existing-nodes/use-existing-nodes.md new file mode 100644 index 00000000000..aaa9b78100e --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/cluster-configuration/rancher-server-configuration/use-existing-nodes/use-existing-nodes.md @@ -0,0 +1,141 @@ +--- +title: 在现有自定义节点上启动 Kubernetes +description: 要创建具有自定义节点的集群，你需要访问集群中的服务器，并根据 Rancher 的要求配置服务器。 +--- + + + + + +创建自定义集群时，Rancher 使用 RKE（Rancher Kubernetes Engine）在本地裸机服务器、本地虚拟机或云服务器节点中创建 Kubernetes 集群。 + +要使用此选项，你需要访问要在 Kubernetes 集群中使用的服务器。请根据[要求](../../../../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/node-requirements-for-rancher-managed-clusters.md)配置每台服务器，其中包括硬件要求和 Docker 要求。在每台服务器上安装 Docker 后，你还需要在每台服务器上运行 Rancher UI 中提供的命令，从而将每台服务器转换为 Kubernetes 节点。 + +本节介绍如何设置自定义集群。 + +## 使用自定义节点创建集群 + +:::note 使用 Windows 主机作为 Kubernetes Worker 节点？ + +在开始之前，请参阅[配置 Windows 自定义集群](../../../../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/use-windows-clusters/use-windows-clusters.md)。 + +::: + +### 1. 配置 Linux 主机 + +你可以通过配置 Linux 主机，来创建自定义集群。你的主机可以是： + +- 云虚拟机 +- 本地虚拟机 +- 裸机服务器 + +如果要重复使用之前的自定义集群中的节点，请在复用之前[清理节点](../../../../how-to-guides/new-user-guides/manage-clusters/clean-cluster-nodes.md)。如果你重复使用尚未清理的节点，则集群配置可能会失败。 + +根据[安装要求](../../../../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/node-requirements-for-rancher-managed-clusters.md)和[生产就绪集群的检查清单](../../../../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/checklist-for-production-ready-clusters/checklist-for-production-ready-clusters.md)配置主机。 + +如果你使用 Amazon EC2 作为主机，并希望使用[双栈 (dual-stack)](https://kubernetes.io/docs/concepts/services-networking/dual-stack/) 功能，则需要满足配置主机的其他[要求](https://rancher.com/docs/rke//latest/en/config-options/dual-stack#requirements)。 + +### 2. 创建自定义集群 + +1. 点击 **☰ > 集群管理**。 +1. 在**集群**页面上，单击**创建**。 +1. 单击**自定义**。 +1. 输入**集群名称**。 +1. 在**集群配置**中，选择 Kubernetes 版本、要使用的网络提供商，以及是否启用项目网络隔离。要查看更多集群选项，请单击**显示高级选项**。 + + :::note 使用 Windows 主机作为 Kubernetes Worker 节点？ + + - 请参阅[启用 Windows 支持选项](../../../../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/use-windows-clusters/use-windows-clusters.md)。 + - 支持 Windows 集群的唯一网络插件是 Flannel。 + + ::: + + :::note Amazon EC2 上的双栈： + + 如果你使用 Amazon EC2 作为主机，并希望使用[双栈 (dual-stack)](https://kubernetes.io/docs/concepts/services-networking/dual-stack/) 功能，则需要满足配置 RKE 的其他[要求](https://rancher.com/docs/rke//latest/en/config-options/dual-stack#requirements)。 + + ::: + +6. 点击**下一步**。 + +4. 使用**成员角色**为集群配置用户授权。点击**添加成员**添加可以访问集群的用户。使用**角色**下拉菜单为每个用户设置权限。 + +7. 从**节点角色**中，选择要由集群节点充当的角色。你必须为 `etcd`、`worker` 和 `controlplane` 角色配置至少一个节点。自定义集群需要所有三个角色才能完成配置。有关角色的详细信息，请参阅[本节](../../../kubernetes-concepts.md#kubernetes-集群中节点的角色)。 + +:::note + +- 使用 Windows 主机作为 Kubernetes Worker 节点？请参阅[本节](../../../../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/use-windows-clusters/use-windows-clusters.md)。 +- 裸机服务器提醒：如果你想将裸机服务器专用于每个角色，则必须为每个角色配置一个裸机服务器（即配置多个裸机服务器）。 + +::: + +8. **可选**：点击**[显示高级选项](../../../../how-to-guides/new-user-guides/launch-kubernetes-with-rancher/about-rancher-agents.md)**来指定注册节点时使用的 IP 地址，覆盖节点的主机名，或将[标签](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/)或[污点](https://kubernetes.io/docs/concepts/configuration/taint-and-toleration/)添加到节点。 + +9. 将屏幕上显示的命令复制到剪贴板。 + +10. 使用你惯用的 shell（例如 PuTTy 或远程终端）登录到你的 Linux 主机。粘贴剪贴板的命令并运行。 + +:::note + +如果要将特定主机专用于特定节点角色，请重复步骤 7-10。根据需要多次重复这些步骤。 + +::: + +11. 在 Linux 主机上运行完命令后，单击**完成**。 + +**结果：** + +集群已被创建，集群的状态是**配置中**。Rancher 已在启动你的集群。 + +当集群状态变为 **Active** 后，你可访问集群。 + +**Active** 状态的集群会分配到两个项目： + +- `Default`：包含 `default` 命名空间 +- `System`：包含 `cattle-system`，`ingress-nginx`，`kube-public` 和 `kube-system` 命名空间。 + + +### 3. 仅限亚马逊：标签资源 + +如果你已将集群配置为使用 Amazon 作为**云提供商**，请使用集群 ID 标记你的 AWS 资源。 + +[Amazon 文档：标记你的 Amazon EC2 资源](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/Using_Tags.html) + +:::note + +你可以使用 Amazon EC2 实例，而无需在 Kubernetes 中配置云提供商。如果你想使用特定的 Kubernetes 云提供商功能，配置云提供商即可。如需更多信息，请参阅 [Kubernetes 云提供商](https://github.com/kubernetes/website/blob/release-1.18/content/en/docs/concepts/cluster-administration/cloud-providers.md)。 + +::: + +以下资源需要使用 `ClusterID` 进行标记： + +- **Nodes**：Rancher 中添加的所有主机。 +- **Subnet**：集群使用的子网。 +- **Security Group**：用于你的集群的安全组。 + +:::note + +不要标记多个安全组。创建 Elastic Load Balancer 时，标记多个组会导致错误。 + +::: + +应该使用的标签是： + +``` +Key=kubernetes.io/cluster/, Value=owned +``` + +`` 可以是你选择的任何字符串。但是，必须在你标记的每个资源上使用相同的字符串。将值设置为 `owned` 会通知集群所有带有 `` 标记的资源都由该集群拥有和管理。 + +如果你在集群之间共享资源，你可以将标签更改为： + +``` +Key=kubernetes.io/cluster/CLUSTERID, Value=shared +``` + +## 可选的后续步骤 + +创建集群后，你可以通过 Rancher UI 访问集群。最佳实践建议你设置以下访问集群的备用方式： + +- **通过 kubectl CLI 访问你的集群**：按照[这些步骤](../../../../how-to-guides/new-user-guides/manage-clusters/access-clusters/use-kubectl-and-kubeconfig.md#在工作站使用-kubectl-访问集群)在你的工作站上使用 kubectl 访问集群。在这种情况下，你将通过 Rancher Server 的认证代理进行认证，然后 Rancher 会让你连接到下游集群。此方法允许你在没有 Rancher UI 的情况下管理集群。 +- **通过 kubectl CLI 使用授权的集群端点访问你的集群**：按照[这些步骤](../../../../how-to-guides/new-user-guides/manage-clusters/access-clusters/use-kubectl-and-kubeconfig.md#直接使用下游集群进行身份验证)直接使用 kubectl 访问集群，而无需通过 Rancher 进行认证。我们建议设置此替代方法来访问集群，以便在无法连接到 Rancher 时访问集群。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/kubernetes-concepts.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/kubernetes-concepts.md new file mode 100644 index 00000000000..6df41049db4 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/kubernetes-concepts.md @@ -0,0 +1,58 @@ +--- +title: Kubernetes 概念 +--- + +本文解释了 Kubernetes 的相关概念，以便让你更好地了解 Rancher 的运行机制。本文仅对 Kubernetes 组件进行了简单的描述。如需了解更多详情，请参见 [Kubernetes 组件的官方文档](https://kubernetes.io/docs/concepts/overview/components/)。 + +## 关于 Docker + +Docker 是一个容器打包和运行时标准。开发者可以使用 Dockerfile 构建容器镜像，并从 Docker 镜像仓库分发容器镜像。[Docker Hub](https://hub.docker.com) 是一个流行的公共镜像仓库。许多组织也建立了私有 Docker 镜像仓库。Docker 主要用于管理单个节点上的容器。 + +## 关于 Kubernetes + +Kubernetes 是容器和集群管理的标准。YAML 文件规定了组成一个应用所需的容器和其他资源。Kubernetes 提供了调度、伸缩、服务发现、健康检查、密文管理和配置管理等功能。 + +## Kubernetes 集群是什么 + +集群是可作为一个系统协同工作的一组计算机。 + +_Kubernetes 集群_ 是使用 [Kubernetes 容器编排系统](https://kubernetes.io/)来部署、运维和伸缩 容器的集群，让你的组织实现应用自动化运维。 + +## Kubernetes 集群中节点的角色 + +Kubernetes 集群中的每个计算资源称为一个 _节点_ 。节点可以是裸金属服务器或虚拟机。Kubernetes 将节点分为 _etcd_ 节点、_controlplane_ 节点和 _worker_ 节点。 + +一个 Kubernetes 集群至少包含一个 etcd 节点，一个 controlplane 节点和一个 worker 节点。 + +### etcd 节点 + +Rancher 在单节点和高可用安装中均使用 etcd 作为数据存储。在 Kubernetes 中，etcd 也是存储集群状态的节点的角色。 + +Kubernetes 集群的状态保存在 [etcd](https://kubernetes.io/docs/concepts/overview/components/#etcd) 中。etcd 节点运行 etcd 数据库。 + +etcd 数据库组件是一个分布式的键值对存储系统，用于存储所有 Kubernetes 的集群数据，例如集群协作和状态管理相关的数据。建议在多个节点上运行 etcd，以保证在发生故障时有可用的备份数据。 + +即使你可以仅在一个节点上运行 etcd，但 etcd 需要大多数节点（即 quorum）的同意才能更新集群状态。集群需要包含足够数量的健康 etcd 节点，以形成 quorum。假设集群中有 n 个节点，quorum 的数量则需要是 (n/2)+1。如果集群节点数量是奇数，每新增一个节点，都会增加 quorum 所需节点数。 + +一般情况下，集群中只要配置三个 etcd 节点就能满足小型集群的需求，五个 etcd 节点能满足大型集群的需求。 + +### controlplane 节点 + +controlplane 节点上运行 Kubernetes API server、scheduler 和 Controller Manager。这些节点执行日常任务，以确保集群状态和你的配置一致。因为 etcd 节点保存了集群的全部数据，所以 controlplane 节点是无状态的。虽然你可以在单个节点上运行 controlplane，但是我们建议在两个或以上的节点上运行 controlplane，以保证冗余性。另外，一个节点可以既是 controlplane 节点，又是 etcd 节点。 + +### Worker 节点 + +每个 [worker 节点](https://kubernetes.io/docs/concepts/architecture/nodes/)都能运行： + +- **Kubelets**：监控节点状态的 Agent，确保你的容器处于健康状态。 +- **工作负载**：承载应用和其他 deployment 的容器和 Pod。 + +Worker 节点也运行存储和网络驱动，有必要时也会运行 Ingress Controller。你可以根据需要，创建尽可能多的 worker 节点来运行你的[工作负载](../how-to-guides/new-user-guides/kubernetes-resources-setup/workloads-and-pods/workloads-and-pods.md)。 + +## 关于 Helm + +在 Rancher 高可用安装的场景下，你可以使用 Helm 工具，把 Rancher 安装到 Kubernetes 集群上。 + +Helm 是 Kubernetes 的包管理工具。Helm Chart 为 Kubernetes YAML 清单文件提供了模板语法。通过 Helm，用户可以创建可配置的 deployment，而不仅仅只能使用静态文件。如果你需要创建自己的 deployment 商店应用，请参见 [https://helm.sh/](https://helm.sh) 上的文档。 + +有关 ServiceAccount 和 Cluster Role Binding 的更多信息，请参见 [Kubernetes 官方文档](https://kubernetes.io/docs/reference/access-authn-authz/rbac/)。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/monitoring-v2-configuration/examples.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/monitoring-v2-configuration/examples.md new file mode 100644 index 00000000000..4d80a2d4b6a --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/monitoring-v2-configuration/examples.md @@ -0,0 +1,23 @@ +--- +title: 示例 +--- + +## ServiceMonitor + +你可以在[此处](https://github.com/prometheus-operator/prometheus-operator/blob/main/example/prometheus-operator-crd/monitoring.coreos.com_servicemonitors.yaml)找到 ServiceMonitor 自定义资源的示例。 + +## PodMonitor + +你可以在[此处](https://prometheus-operator.dev/docs/developer/getting-started/#using-podmonitors)找到 PodMonitor 示例和引用它的 Prometheus 资源示例。 + +## PrometheusRule + +PrometheusRule 包含你通常放置在 [Prometheus 规则文件](https://prometheus.io/docs/prometheus/latest/configuration/recording_rules/)中的告警和记录规则。 + +要在集群中更细粒度地应用 PrometheusRules，你可以使用 Prometheus 资源的 ruleSelector 字段，从而根据添加到 PrometheusRules 资源的标签来选择要加载到 Prometheus 上的 PrometheusRule。 + +你可以在[此页面](https://prometheus-operator.dev/docs/developer/alerting/)找到 PrometheusRule 示例。 + +## Alertmanager 配置 + +有关示例配置，请参阅[本节](./receivers.md#alertmanager-配置示例)。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/monitoring-v2-configuration/helm-chart-options.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/monitoring-v2-configuration/helm-chart-options.md new file mode 100644 index 00000000000..476af17585c --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/monitoring-v2-configuration/helm-chart-options.md @@ -0,0 +1,68 @@ +--- +title: Helm Chart 选项 +--- + +## 配置资源限制和请求 + +安装 `rancher-monitoring` 时可以配置资源请求和限制。 + +默认值在 `rancher-monitoring` Helm Chart 的 [values.yaml](https://github.com/rancher/charts/blob/main/charts/rancher-monitoring/values.yaml) 中。 + +下表中的默认值是所需的最低资源限制和请求： + +| 资源名称 | 内存限制 | CPU 限制 | 内存请求 | CPU 请求 | +| ------------- | ------------ | ----------- | ---------------- | ------------------ | +| alertmanager | 500Mi | 1000m | 100Mi | 100m | +| grafana | 200Mi | 200m | 100Mi | 100m | +| kube-state-metrics subchart | 200Mi | 100m | 130Mi | 100m | +| prometheus-node-exporter subchart | 50Mi | 200m | 30Mi | 100m | +| prometheusOperator | 500Mi | 200m | 100Mi | 100m | +| prometheus | 2500Mi | 1000m | 1750Mi | 750m | +| **总计** | **3950Mi** | **2700m** | **2210Mi** | **1250m** | + +建议至少配 50Gi 存储。 + + +## Notifiers 的可信 CA + +如果你需要将受信任的 CA 添加到 Notifiers，请执行以下步骤： + +1. 创建 `cattle-monitoring-system` 命名空间。 +1. 将你信任的 CA 密文添加到 `cattle-monitoring-system` 命名空间。 +1. 部署或升级 `rancher-monitoring` Helm Chart。在 Chart 选项中，引用**告警 > 补充密文**中的密钥。 + +**结果**：默认的 Alertmanager 自定义资源将有权访问你信任的 CA。 + + +## 其它抓取配置 + +如果无法通过 ServiceMonitor 或 PodMonitor 指定你想要的抓取配置，你可以在部署或升级 `rancher-monitoring` 时提供 `additionalScrapeConfigSecret`。 + +[scrape_config](https://prometheus.io/docs/prometheus/latest/configuration/configuration/#scrape_config) 指定一组目标以及抓取这些目标的参数。在一般情况下，一个抓取配置指定一个 job。 + +Istio 就是一个可能用到这个配置的例子。有关详细信息，请参阅[本节](../../integrations-in-rancher/istio/configuration-options/selectors-and-scrape-configurations.md)。 + + +## 配置打包在 Monitoring V2 中的应用 + +我们使用 Monitoring V2 来部署 kube-state-metrics 和 node-exporter。node-exporter 部署为 DaemonSet。对于 Monitoring V2 helm Chart，values.yaml 中的所有东西都部署为子 Chart。 + +我们还部署了不由 prometheus 管理的 Grafana。 + +如果你查看 Helm Chart 在 kube-state-metrics 中的功能，则还有很多可以设置的值没有在顶层 Chart 中显示。 + +但是，你可以在顶层 Chart 中添加覆盖子 Chart 的值。 + +### 增加 Alertmanager 的副本 + +作为 Chart 部署选项的一部分，你可以选择增加部署到集群上的 Alertmanager 副本的数量。这些副本使用相同的底层 Alertmanager Config Secret 进行管理。有关 Alertmanager Config Secret 的更多信息，请参阅[本节](../../how-to-guides/advanced-user-guides/monitoring-v2-configuration-guides/advanced-configuration/alertmanager.md#多个-alertmanager-副本)。 + +### 为持久化 Grafana 仪表板配置命名空间 + +要让 Grafana 监控所有命名空间中的 ConfigMap，请在 `rancher-monitoring` Helm chart 中指定以下值： + +``` +grafana.sidecar.dashboards.searchNamespace=ALL +``` + +请注意，Monitoring Chart 用于添加 Grafana 仪表板的 RBAC 角色仅能让用户将仪表板添加到定义在 `grafana.dashboards.namespace` 中的命名空间，默认为 `cattle-dashboards`。 \ No newline at end of file diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/monitoring-v2-configuration/monitoring-v2-configuration.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/monitoring-v2-configuration/monitoring-v2-configuration.md new file mode 100644 index 00000000000..1110b88e03a --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/monitoring-v2-configuration/monitoring-v2-configuration.md @@ -0,0 +1,15 @@ +--- +title: Monitoring V2 配置 +--- + + + + + +以下将说明在 Rancher 中如何配置 Monitoring V2 的基本重要选项： + +- [接收器配置](receivers.md) +- [路由配置](routes.md) +- [ServiceMonitor 和 PodMonitor 配置](servicemonitors-and-podmonitors.md) +- [Helm Chart 选项](helm-chart-options.md) +- [示例](examples.md) \ No newline at end of file diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/monitoring-v2-configuration/receivers.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/monitoring-v2-configuration/receivers.md new file mode 100644 index 00000000000..e961ec75d77 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/monitoring-v2-configuration/receivers.md @@ -0,0 +1,299 @@ +--- +title: 接收器配置 +--- + +[Alertmanager Config](https://prometheus.io/docs/alerting/latest/configuration/#configuration-file) Secret 包含 Alertmanager 实例的配置，该实例根据 Prometheus 发出的告警发送通知。 + +:::note + +本节参考假设你已经熟悉 Monitoring 组件的协同工作方式。有关 Alertmanager 的详细信息，请参阅[本节](../../integrations-in-rancher/monitoring-and-alerting/how-monitoring-works.md#3-alertmanager-的工作原理)。 + +::: + + +## 在 Rancher UI 中创建接收器 + +:::note 先决条件： + +- 已安装 Monitoring 应用。 +- 如果你使用现有的 Alertmanager Secret 配置 Monitoring，则它必须具有 Rancher 的 UI 支持的格式。否则，你将只能直接修改 Alertmanager Secret 来进行更改。请注意，对于通过使用路由和接收器 UI 支持的 Alertmanager 配置类型，我们会继续进行强化。因此如果你有增强功能的请求，请[提交 issue](https://github.com/rancher/rancher/issues/new)。 + +::: + +要在 Rancher UI 中创建通知接收器： + + + + +1. 转到要创建接收器的集群。单击 **监控 -> 告警 -> AlertManagerConfigs**。 +1. 单击**创建**。 +1. 点击**添加接收器**。 +1. 输入接收器的**名称**。 +1. 为接收器配置一个或多个提供程序。如需获取填写表单的帮助，请参阅下方的配置选项。 +1. 单击**创建**。 + + + + +1. 转到要创建接收器的集群。单击**监控**，然后单击**接收器**。 +2. 输入接收器的名称。 +3. 为接收器配置一个或多个提供程序。如需获取填写表单的帮助，请参阅下方的配置选项。 +4. 单击**创建**。 + + + + +**结果**：告警可以向接收器发送通知。 + +## 接收器配置 + +通知集成是通过 `receiver` 配置的，[Prometheus](https://prometheus.io/docs/alerting/latest/configuration/#receiver) 文档对此进行了说明。 + +### 原生和非原生接收器 + +默认情况下，AlertManager 提供与一些接收器的原生集成，这些接收器在[本节](https://prometheus.io/docs/alerting/latest/configuration/#receiver)中列出。所有原生支持的接收器都可以通过 Rancher UI 进行配置。 + +对于 AlertManager 不提供原生支持的通知机制，可使用 [webhook 接收器](https://prometheus.io/docs/alerting/latest/configuration/#webhook_config)实现集成。你可以在[此处](https://prometheus.io/docs/operating/integrations/#alertmanager-webhook-receiver)找到提供此类集成的第三方驱动程序列表。Alerting Drivers 应用能让你访问这些驱动程序，以及它们相关的集成。启用后，你将可以在 Rancher UI 中配置非原生的接收器。 + +目前 Rancher Alerting Drivers 应用支持访问以下集成： +- Microsoft Teams，基于 [prom2teams](https://github.com/idealista/prom2teams) 驱动程序 +- SMS，基于 [Sachet](https://github.com/messagebird/sachet) 驱动程序 + +你可以在 Rancher UI 中可以配置以下类型的接收器： + +- Slack +- 电子邮件 +- PagerDuty +- Opsgenie +- Webhook +- 自定义 +- Teams +- SMS + +你可以在 YAML 中使用自定义接收器选项，从而配置无法通过 Rancher UI 表单配置的接收器。 + +## Slack + +| 字段 | 类型 | 描述 | +|------|--------------|------| +| URL | String | 输入你的 Slack webhook URL。有关创建 Slack webhook 的说明，请参阅 [Slack 文档](https://get.slack.help/hc/en-us/articles/115005265063-Incoming-WebHooks-for-Slack)。 | +| 默认频道 | String | 输入要发送告警通知的频道名称。格式：`#`。 | +| 代理 URL | String | webhook 通知的代理。 | +| 发送已解决告警 | Bool | 如果告警已解决（例如 [已解决] CPU 使用率过高问题），是否发送后续通知。 | + +## 电子邮件 + +| 字段 | 类型 | 描述 | +|------|--------------|------| +| 默认收件人地址 | String | 接收通知的电子邮件地址。 | +| 发送已解决告警 | Bool | 如果告警已解决（例如 [已解决] CPU 使用率过高问题），是否发送后续通知。 | + +SMTP 选项： + +| 字段 | 类型 | 描述 | +|------|--------------|------| +| 发件人 | String | 你的 SMTP 邮件服务器上可用的电子邮件地址，用于发送通知。 | +| 主机 | String | SMTP 服务器的 IP 地址或主机名。示例：`smtp.email.com`。 | +| 使用 TLS | Bool | 使用 TLS 进行加密。 | +| 用户名 | String | 用户名，用于通过 SMTP 服务器进行身份验证。 | +| 密码 | String | 密码，用于通过 SMTP 服务器进行身份验证。 | + +## PagerDuty + +| 字段 | 类型 | 描述 | +|------|------|-------| +| 集成类型 | String | `Events API v2` 或 `Prometheus`。 | +| 默认集成密钥 | String | 有关获取集成密钥的说明，请参阅 [PagerDuty 文档](https://www.pagerduty.com/docs/guides/prometheus-integration-guide/)。 | +| 代理 URL | String | PagerDuty 通知的代理。 | +| 发送已解决告警 | Bool | 如果告警已解决（例如 [已解决] CPU 使用率过高问题），是否发送后续通知。 | + +## Opsgenie + +| 字段 | 描述 | +|------|-------------| +| API 密钥 | 有关获取 API 密钥的说明，请参阅 [Opsgenie 文档](https://docs.opsgenie.com/docs/api-key-management)。 | +| 代理 URL | Opsgenie 通知的代理。 | +| 发送已解决告警 | 如果告警已解决（例如 [已解决] CPU 使用率过高问题），是否发送后续通知。 | + +Opsgenie 响应者： + +| 字段 | 类型 | 描述 | +|-------|------|--------| +| 类型 | String | 计划程序、团队、用户或升级。有关告警响应者的更多信息，请参阅 [Opsgenie 文档](https://docs.opsgenie.com/docs/alert-recipients-and-teams)。 | +| 发送至 | String | Opsgenie 收件人的 ID、名称或用户名。 | + +## Webhook + +| 字段 | 描述 | +|-------|--------------| +| URL | 你所选的应用的 Webhook URL。 | +| 代理 URL | webhook 通知的代理。 | +| 发送已解决告警 | 如果告警已解决（例如 [已解决] CPU 使用率过高问题），是否发送后续通知。 | + + + +## 自定义 + +此处提供的 YAML 将直接附加到 Alertmanager Config Secret 的接收器中。 + +## Teams + +### 为 Rancher 管理的集群启用 Teams 接收器 + +Teams 接收器不是原生接收器，因此需要启用后才能使用。你可以通过转到应用页面，安装 rancher-alerting-drivers 应用，然后选择 Teams 选项，从而为 Rancher 管理的集群启用 Teams 接收器。 + +1. 在 Rancher UI 中，转到要安装 rancher-alerting-drivers 的集群，然后单击 **Apps**。 +1. 点击 **Alerting Drivers** 应用。 +1. 单击 **Helm 部署选项**选项卡。 +1. 选择 **Teams** 并单击**安装**。 +1. 记下使用的命名空间，后续步骤中将需要该命名空间。 + +### 配置 Teams 接收器 + +可以通过更新 ConfigMap 来配置 Teams 接收器。例如，以下是最小的 Teams 接收器配置： + +```yaml +[Microsoft Teams] +teams-instance-1: https://your-teams-webhook-url +``` + +配置完成后，按照[本节](#在-rancher-ui-中创建接收器)中的步骤添加接收器。 + +使用以下示例作为 URL，其中： + +- 将 `ns-1` 替换为安装 `rancher-alerting-drivers` 应用的命名空间。 + +```yaml +url: http://rancher-alerting-drivers-prom2teams.ns-1.svc:8089/v2/teams-instance-1 +``` + + + +## SMS + +### 为 Rancher 管理的集群启用 SMS 接收器 + +SMS 接收器不是原生接收器，因此需要启用后才能使用。你可以通过转到应用页面，安装 rancher-alerting-drivers 应用，然后选择 SMS 选项，从而为 Rancher 管理的集群启用 SMS 接收器。 + +1. 在左上角，单击 **☰ > 集群管理**。 +1. 在**集群**页面上，转到要安装 `rancher-alerting-drivers` 的集群，然后单击 **Explore**。 +1. 在左侧导航栏中，单击**应用 & 应用市场**。 +1. 点击 **Alerting Drivers** 应用。 +1. 单击 **Helm 部署选项**选项卡。 +1. 选择 **SMS** 并单击**安装**。 +1. 记下使用的命名空间，后续步骤中将需要该命名空间。 + +### 配置 SMS 接收器 + +可以通过更新 ConfigMap 来配置 SMS 接收器。例如，以下是最小的 SMS 接收器配置： + +```yaml +providers: + telegram: + token: 'your-token-from-telegram' + +receivers: +- name: 'telegram-receiver-1' + provider: 'telegram' + to: + - '123456789' +``` + +配置完成后，按照[本节](#在-rancher-ui-中创建接收器)中的步骤添加接收器。 + +使用以下示例作为名称和 URL，其中： + +- 分配给接收器的名称（例如 `telegram-receiver-1`）必须与 ConfigMap 中 `receivers.name` 字段中的名称（例如 `telegram-receiver-1`）匹配。 +- 将 URL 中的 `ns-1` 替换为安装 `rancher-alerting-drivers` 应用的命名空间。 + +```yaml +name: telegram-receiver-1 +url http://rancher-alerting-drivers-sachet.ns-1.svc:9876/alert +``` + + + + +## 配置多个接收器 + +你可以编辑 Rancher UI 中的表单来设置一个接收器资源，其中包含 Alertmanager 将告警发送到你的通知系统所需的所有信息。 + +也可以向多个通知系统发送告警。一种方法是使用自定义 YAML 来配置接收器。如果你需要让两个系统接收相同的消息，则可以为多个通知系统添加配置。 + +你还可以通过使用路由的 `continue` 选项来设置多个接收器。这样，发送到接收器的告警会在路由树（可能包含另一个接收器）的下一级进行评估。 + + +## Alertmanager 配置示例 + +### Slack +要通过 Slack 设置通知，你可以将以下 Alertmanager Config YAML 放入 Alertmanager Config Secret 的 `alertmanager.yaml` 键中，你需要更新 `api_url` 来使用来自 Slack 的 Webhook URL： + +```yaml +route: + group_by: ['job'] + group_wait: 30s + group_interval: 5m + repeat_interval: 3h + receiver: 'slack-notifications' +receivers: +- name: 'slack-notifications' + slack_configs: + - send_resolved: true + text: '{{ template "slack.rancher.text" . }}' + api_url: +templates: +- /etc/alertmanager/config/*.tmpl +``` + +### PagerDuty +要通过 PagerDuty 设置通知，请使用 [PagerDuty 文档](https://www.pagerduty.com/docs/guides/prometheus-integration-guide/) 中的以下示例作为指导。此示例设置了一个路由，该路由捕获数据库服务的告警，并将告警发送到链接到服务的接收器，该服务将直接通知 PagerDuty 中的 DBA，而其他告警将被定向到具有不同 PagerDuty 集成密钥的默认接收器。 + +你可以将以下 Alertmanager Config YAML 放入 Alertmanager Config Secret 的 `alertmanager.yaml` 键中。你需要将 `service_key` 更新为使用你的 PagerDuty 集成密钥，可以根据 PagerDuty 文档的 "Integrating with Global Event Routing" 找到该密钥。有关配置选项的完整列表，请参阅 [Prometheus 文档](https://prometheus.io/docs/alerting/latest/configuration/#pagerduty_config)。 + +```yaml +route: + group_by: [cluster] + receiver: 'pagerduty-notifications' + group_interval: 5m + routes: + - match: + service: database + receiver: 'database-notifcations' + +receivers: +- name: 'pagerduty-notifications' + pagerduty_configs: + - service_key: 'primary-integration-key' + +- name: 'database-notifcations' + pagerduty_configs: + - service_key: 'database-integration-key' +``` + +## CIS 扫描告警的示例路由配置 + +在为 `rancher-cis-benchmark` 告警配置路由时，你可以使用键值对 `job:rancher-cis-scan` 来指定匹配。 + +例如，以下路由配置示例可以与名为 `test-cis` 的 Slack 接收器一起使用： + +```yaml +spec: + receiver: test-cis + group_by: +# - string + group_wait: 30s + group_interval: 30s + repeat_interval: 30s + match: + job: rancher-cis-scan +# key: string + match_re: + {} +# key: string +``` + +有关为 `rancher-cis-benchmark` 启用告警的更多信息，请参阅[本节](../../how-to-guides/advanced-user-guides/cis-scan-guides/enable-alerting-for-rancher-cis-benchmark.md)。 + +## Notifiers 的可信 CA + +如果你需要将受信任的 CA 添加到 Notifiers，请按照[本节](helm-chart-options.md#notifiers-的可信-ca)中的步骤操作。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/monitoring-v2-configuration/routes.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/monitoring-v2-configuration/routes.md new file mode 100644 index 00000000000..fbbfe7e6445 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/monitoring-v2-configuration/routes.md @@ -0,0 +1,64 @@ +--- +title: 路由配置 +--- + +路由（Route）配置是 Alertmanager 自定义资源的一部分，用于控制 Prometheus 触发的告警在到达接收器之前的分组和过滤方式。 + +当路由更改时，Prometheus Operator 会重新生成 Alertmanager 自定义资源以反映更改。 + +有关配置路由的更多信息，请参阅[官方 Alertmanager 文档](https://www.prometheus.io/docs/alerting/latest/configuration/#route)。 + +:::note + +本节参考假设你已经熟悉 Monitoring 组件的协同工作方式。有关详细信息，请参阅[本节](../../integrations-in-rancher/monitoring-and-alerting/how-monitoring-works.md)。 + +::: + + + +## 路由限制 + +Alertmanager 根据接收器和路由树来代理 Prometheus 的告警，该路由树根据标签将告警过滤到指定接收器。 + +Alerting Drivers 为 Alertmanager 将告警代理到非原生接收器，例如 Microsoft Teams 和 SMS。 + +在配置路由和接收器的 Rancher UI 中，你可以配置有一个根的路由树，然后再配置一个深度，这样的树就有两个深度。但是如果在直接配置 Alertmanager 时使用 `continue` 路由，你可以让树更深。 + +每个接收器用于一个或多个通知提供商。因此，如果你需要将发送到 Slack 的每个告警也发送到 PagerDuty，你可以在同一个接收器中配置两者。 + +## 路由配置 + +### 标签和注释的注意事项 + +标签用于识别可能影响通知路由的信息。告警的标识信息可能包括容器名称，或应接收通知的团队的名称。 + +注释用于标识不影响告警接收者的信息，例如 Runbook URL 或错误消息。 + + +### 接收器 +路由需要引用一个已经配置好的[接收器](./receivers.md)。 + +### 分组 + +| 字段 | 默认 | 描述 | +|-------|--------------|---------| +| 分组依据 | N/A | 用于分组的标签列表。所有标签都必须是唯一的。如果提供了特殊标签“...”（由所有可能的标签聚合），标签必须在列表中是唯一的元素。接受字符串列表。有关详细信息，请参阅[上游文档](https://github.com/prometheus-operator/prometheus-operator/blob/main/Documentation/api-reference/api.md#route)。 | +| 组等待时长 | 30s | 在发送之前，缓冲同一组告警的等待时间。 | +| 组间隔 | 5m | 等待多长时间才发送已添加到告警组的告警，其中该告警组的初次通知已被发送。 | +| 重复间隔 | 4h | 等待多长时间后，才重新发送已发送的告警。 | + +### 匹配 + +**Match** 字段指一组相等匹配器，用于根据告警上定义的标签来识别要发送到指定路由的告警。在 Rancher UI 中添加键值对时，它们对应于以下格式的 YAML： + +```yaml +match: + [ : , ... ] +``` + +**Match Regex** 字段指一组正则表达式匹配器，用于根据在该告警上定义的标签来识别要发送到指定路由的告警。在 Rancher UI 中添加键值对时，它们对应于以下格式的 YAML： + +```yaml +match_re: + [ : , ... ] +``` diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/monitoring-v2-configuration/servicemonitors-and-podmonitors.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/monitoring-v2-configuration/servicemonitors-and-podmonitors.md new file mode 100644 index 00000000000..371fdd845a2 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/monitoring-v2-configuration/servicemonitors-and-podmonitors.md @@ -0,0 +1,33 @@ +--- +title: ServiceMonitor 和 PodMonitor 配置 +--- + +ServiceMonitor 和 PodMonitor 都是伪 CRD，它们映射 Prometheus 自定义资源的抓取配置。 + +这些配置对象以声明方式指定 Prometheus 抓取指标的端点。 + +ServiceMonitor 比 PodMonitor 更常用，推荐用于大多数用例。 + +:::note + +本节参考假设你已经熟悉 Monitoring 组件的协同工作方式。有关 Alertmanager 的详细信息，请参阅[本节](../../integrations-in-rancher/monitoring-and-alerting/how-monitoring-works.md)。 + +::: + +## ServiceMonitor + +这个伪 CRD 映射到 Prometheus 自定义资源配置的一部分。它以声明方式指定应如何监控 Kubernetes 服务组。 + +创建 ServiceMonitor 时，Prometheus Operator 会更新 Prometheus 抓取配置，从而包含 ServiceMonitor 配置。然后 Prometheus 开始从 ServiceMonitor 中定义的端点抓取指标。 + +如果集群中的任何 Service 与 ServiceMonitor `selector` 字段中的标签匹配，则会根据 ServiceMonitor 指定的 `endpoints` 进行监控。有关可以指定的字段的更多信息，请查看 Prometheus Operator 的[规范](https://github.com/prometheus-operator/prometheus-operator/blob/main/Documentation/api-reference/api.md#servicemonitor)。 + +有关 ServiceMonitor 工作原理的更多信息，请参阅 [Prometheus Operator 文档](https://github.com/prometheus-operator/prometheus-operator/blob/main/Documentation/user-guides/running-exporters.md)。 + +## PodMonitor + +这个伪 CRD 映射到 Prometheus 自定义资源配置的一部分。它以声明方式指定应如何监控 Pod 组。 + +创建 PodMonitor 时，Prometheus Operator 会更新 Prometheus 抓取配置，从而包含 PodMonitor 配置。然后 Prometheus 开始从 PodMonitor 中定义的端点抓取指标。 + +如果集群中的任何 Pod 与 PodMonitor `selector` 字段中的标签匹配，则会根据 PodMonitor 指定的 `podMetricsEndpoints` 进行监控。有关可以指定的字段的更多信息，请查看 Prometheus Operator 的[规范](https://github.com/prometheus-operator/prometheus-operator/blob/main/Documentation/api-reference/api.md#podmonitor)。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/prometheus-federator/prometheus-federator.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/prometheus-federator/prometheus-federator.md new file mode 100644 index 00000000000..e7d9990f5fb --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/prometheus-federator/prometheus-federator.md @@ -0,0 +1,109 @@ +--- +title: Prometheus Federator +--- + + + + + +Prometheus Federator（也称为 Project Monitoring V2）基于 [rancher/helm-project-operator](https://github.com/rancher/helm-project-operator) 部署一个 Helm Project Operator。该 Operator 管理 Helm Chart 的部署，每个 Operator 都包含一个 Project Monitoring Stack，而每个堆栈都包含： + +- [Prometheus](https://prometheus.io/)（由 [Prometheus Operator](https://github.com/prometheus-operator/prometheus-operator) 在外部管理） +- [Alertmanager](https://prometheus.io/docs/alerting/latest/alertmanager/)（由 [Prometheus Operator](https://github.com/prometheus-operator/prometheus-operator) 在外部管理） +- [Grafana](https://github.com/helm/charts/tree/master/stable/grafana)（通过嵌入式 Helm Chart 部署） +- 基于 [kube-prometheus](https://github.com/prometheus-operator/kube-prometheus/) 社区策划资源集合的默认 PrometheusRules 和 Grafana 仪表板 +- 监视已部署资源的默认 ServiceMonitor + +:::note 重要提示： + +Prometheus Federator 适合在已安装 Prometheus Operator CRD 的集群中与现有的 Prometheus Operator Deployment 一起部署。 + +::: + +## Operator 工作原理 + +1. 在部署此 Chart 时，用户可以创建 ProjectHelmCharts CR，并在**项目 Registration 命名空间 (`cattle-project-`)** 中将 `spec.helmApiVersion` 设置为 `monitoring.cattle.io/v1alpha1`（在 Rancher UI 中也称为“项目监控”）。 +2. 在看到每个 ProjectHelmChartCR 时，Operator 会代表项目所有者在**项目 Release 命名空间 (`cattle-project--monitoring`)** 中自动部署一个 Project Prometheus 堆栈（基于 ProjectHelmChart 控制器在 **Operator / System Namespace** 中创建的 HelmChart CR 和 HelmRelease CR）。 +3. RBAC 将自动分配到项目 Release 命名空间中，从而允许用户查看 Prometheus、Alertmanager 以及已部署的 Project Monitoring Stack 的 Grafana UI（基于在项目 Registration 命名空间上针对[面向用户的默认 Kubernetes 角色](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#user-facing-roles)定义的 RBAC）。有关详细信息，请参阅[配置 RBAC](rbac.md)。 + +### 什么是项目？ + +在 Prometheus Federator 中，项目是一组可以由 `metav1.LabelSelector` 标识的命名空间。默认情况下，用于标识项目的标签是 `field.cattle.io/projectId`，该标签用于标识给定 Rancher 项目中包含的命名空间。 + +### 配置由 ProjectHelmChart 创建的 Helm 版本 + +此 ProjectHelmChart 资源的 `spec.values` 对应于为底层 Helm Chart 配置的 `values.yaml` 覆盖，该 Helm Chart 是 Operator 代表用户部署的。要查看底层 Chart 的 `values.yaml` 规范，你可以选择以下其中一种方式： + +- 查看位于 [`charts/rancher-project-monitoring` 中的 `rancher/prometheus-federator`](https://github.com/rancher/prometheus-federator/blob/main/charts/rancher-project-monitoring) 的 Chart 定义（Chart 版本会绑定到 Operator 版本）。 +- 查找在每个项目 Registration 命名空间中自动创建的名为 `monitoring.cattle.io.v1alpha1` 的 ConfigMap，其中包含用于配置 Chart（直接嵌入到 `prometheus-federator` 二进制文件中）的`values.yaml` 和 `questions.yaml`。 + +### 命名空间 + +Prometheus Federator 是基于 [rancher/helm-project-operator](https://github.com/rancher/helm-project-operator) 的 Project Operator，Prometheus Federator 提供了三类命名空间供 Operator 查找： + +1. **Operator / System 命名空间**：部署 Operator 的命名空间（例如 `cattle-monitoring-system`）。此命名空间将包含该 Operator 监视的所有 ProjectHelmChart 的所有 HelmChart 和 HelmRelease。**只有集群管理员才能访问此命名空间**。 + +2. **项目 Registration 命名空间 (`cattle-project-`)**：Operator 在这些命名空间中监视 ProjectHelmChart。对于在项目发布命名空​​间中创建的自动分配的 RBAC，应用于此命名空间的 RoleBinding 和 ClusterRoleBinding 也会作为 RBAC 的真实来源。有关详细信息，请参阅 [RBAC 页面](rbac.md)。**项目所有者（admin）、项目成员（edit）和只读成员（view）应该有权访问此命名空间。** + + :::note 注意事项： + + - 如果提供了 `.Values.global.cattle.projectLabel`（默认设置为 `field.cattle.io/projectId`），则 Operator 会自动生成项目注册命名空间，并将它导入到命名空间绑定的项目中。换言之，如果观察到至少一个带有该标签的命名空间，则 Operator 会创建一个项目 Registration 命名空间。除非出现以下两种情况，否则 Operator 不会让这些命名空间被删除。第一种情况是带有该标签的所有命名空间都消失了（例如，这是该项目中的最后一个命名空间，在这种情况下，命名空间将标有标签 `"helm.cattle.io/helm-project-operator-orphaned": "true"`，表示可以删除）。第二种情况是由于项目 ID 是在 `.Values.helmProjectOperator.otherSystemProjectLabelValues` 下提供的（用作项目的拒绝名单），导致 Operator 不再监视该项目。这些命名空间不会被自动删除，这样能避免破坏用户数据。如果需要，建议用户在创建或删除项目时手动清理这些命名空间。 + + - 如果未提供 `.Values.global.cattle.projectLabel`，则 Operator / System 命名空间也是项目注册命名空间。 + + ::: + +3. **项目发布命名空​​间（`cattle-project--monitoring`）**：Operator 代表 ProjectHelmChart 在其中部署项目监控堆栈的命名空间集。Operator 还将根据在项目 Registration 命名空间中找到的绑定，自动为项目监控堆栈在此命名空间中创建的角色分配 RBAC。**只有集群管理员才能访问这个命名空间。部署的 Helm Chart 和 Prometheus Federator 将为项目所有者（admin）、项目成员（edit）和只读成员（view）分配该命名空间的有限访问权限。** + + :::note 注意事项： + + - 项目发布命名空间会自动部署并导入到 ID 在 `.Values.helmProjectOperator.projectReleaseNamespaces.labelValue` 下指定的项目中，如果未指定，且项目注册命名空间中指定了 ProjectHelmChart，则默认为 `.Values.global.cattle.systemProjectId` 的值。 + + - 项目发布命名空​​间的孤立约定与项目注册命名空间的相同（参见上面的注释）。 + + - 如果 `.Values.projectReleaseNamespaces.enabled` 为 false，则项目发布命名空​​间与项目注册命名空间是相同的。 + + ::: + +### Helm 资源（HelmChart、HelmRelease） + +在部署 ProjectHelmChart 时，Prometheus Federator 将自动创建和管理两个子自定义资源，它们依次管理以下底层 Helm 资源： + +- HelmChart CR（通过 Operator 中的嵌入式 [k3s-io​​/helm-contoller](https://github.com/k3s-io/helm-controller) 管理）：此自定义资源会根据应用到 HelmChart CR 的变更，在触发 `helm install`、`helm upgrade` 或 `helm uninstall` 的同一命名空间中自动创建一个 Job。此 CR 会根据 ProjectHelmChart 的更改（例如，修改 `values.yaml`）或底层项目定义的更改（例如，从项目中添加或删除命名空间）自动更新。 + +:::note 重要提示： + +如果 ProjectHelmChart 没有部署或更新底层项目监控堆栈，你可以先使用此资源在 Operator / System 命名空间中创建的 Job 来检查 Helm 操作是否有问题。通常只能由**集群管理员访问**。 + +::: + +- HelmRelease CR（通过 Operator 中的嵌入式 [rancher/helm-locker](https://github.com/rancher/helm-locker) 管理）：此自定义资源会自动锁定已部署的 Helm 版本并自动覆盖对底层资源的更新，除非更改是 Helm 操作导致的（`helm install`、`helm upgrade` 或 `helm uninstall` 由 HelmChart CR 执行）。 + +:::note + +HelmRelease CR 会发出 Kubernetes 事件，用于检测底层 Helm 版本修改并将其锁定回原位。要查看这些事件，你可以使用 `kubectl describe helmrelease -n `。你还可以查看此 Operator 的日志，了解检测到更改的时间以及哪些资源被尝试更改。 + +::: + +这两种资源都是为 Operator / System 命名空间中的所有 Helm Chart 创建的，用于避免低权限用户的权限升级。 + +### 高级 Helm Project Operator 配置 + +有关高级配置的更多信息，请参阅[此页面](https://github.com/rancher/prometheus-federator/blob/main/charts/prometheus-federator/README.md#advanced-helm-project-operator-configuration)。 + + + +### Local 集群上的 Prometheus Federator + +Prometheus Federator 是一个资源密集型应用程序。你可以将其安装到 Local 集群（**不推荐**）。 + diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/prometheus-federator/rbac.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/prometheus-federator/rbac.md new file mode 100644 index 00000000000..c7aea4be4be --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/prometheus-federator/rbac.md @@ -0,0 +1,31 @@ +--- +title: RBAC +--- + +本文介绍 Prometheus Federator RBAC。 + +如[命名空间](./prometheus-federator.md#命名空间)部分所述，Prometheus Federator 期望集群中具有项目级别权限（例如，具有由单个标签选择器确定的命名空间组的权限）的项目所有者、项目成员和其他用户，除了项目 Registration 命名空间（默认导入到项目中）和那些已经包含其项目的命名空间之外，在任何其他命名空间中都只有最低权限。因此，为了让项目所有者将特定 Chart 权限分配给其项目命名空间中的其他用户，Helm Project Operator 将自动监视以下绑定： + +- ClusterRoleBindings +- 项目发布命名空​​间中的 RoleBindings + +如果 Helm Project Operator 观察到其中一种绑定的更改，Helm Project Operator 会检查绑定指向的 `roleRef` 是否与具有以下名称的 ClusterRole 匹配： + +- `helmProjectOperator.releaseRoleBindings.clusterRoleRefs.admin` +- `helmProjectOperator.releaseRoleBindings.clusterRoleRefs.edit` +- `helmProjectOperator.releaseRoleBindings.clusterRoleRefs.view` + +默认情况下，这些 roleRef 分别对应 `admin`、`edit` 和 `view`，它们都是 [Kubernetes 面向用户的默认角色](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#user-facing-roles)。 + +:::note + +对于 Rancher RBAC 用户，这些 [Kubernetes 面向用户的默认角色](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#user-facing-roles)与`项目所有者`、`项目成员`和`只读`默认项目角色模板直接对应。 + +::: + +如果 `roleRef` 匹配，Helm Project Operator 将为所有用户和组过滤绑定的 `subjects`，并使用它为项目 Release 命名空间中的每个角色自动构造一个 RoleBinding，该 RoleBinding 的名称与角色相同并带有以下标签： + +- `helm.cattle.io/project-helm-chart-role: {{ .Release.Name }}` +- `helm.cattle.io/project-helm-chart-role-aggregate-from: ` + +默认情况下，Prometheus Federator 部署的底层 Chart `rancher-project-monitoring` 会为每个项目发布命名空​​间创建三个默认角色，这些角色能授权 `admin`、`edit` 和 `view` 用户查看项目监控堆栈的 Prometheus、Alertmanager 和 Grafana UI，从而提供最低权限。如果集群管理员想要为某些用户分配额外的权限，一种做法是直接将项目 Release 命名空间中的 RoleBinding 分配给某些用户。另一种做法是创建带有上述两个标签的角色，然后，项目所有者可以控制在项目 Registration 命名空间中分配这些 RBAC 角色的用户。 \ No newline at end of file diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/rancher-cluster-tools.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/rancher-cluster-tools.md new file mode 100644 index 00000000000..e454be93e76 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/rancher-cluster-tools.md @@ -0,0 +1,48 @@ +--- +title: 集群工具：Logging，Monitoring 和可视化 +--- + +Rancher 包含 Kubernetes 中未包含的各种工具来协助你进行 DevOps 操作。Rancher 可以与外部服务集成，让你的集群更高效地运行。工具分为以下几类： + + +## Logging + +Logging 支持： + +- 获取和分析集群的状态 +- 在你的环境中发现趋势 +- 将日志保存到集群外部的安全位置 +- 随时了解容器崩溃、pod 驱逐或节点死亡等事件 +- 更轻松地调试和解决问题 + +Rancher 可以与 Elasticsearch、splunk、kafka、syslog 和 fluentd 集成。 + +有关详细信息，请参阅 [Logging 文档](../integrations-in-rancher/logging/logging.md)。 +## 监控和告警 + +你可以使用 Rancher，通过业界领先并开源的 [Prometheus](https://prometheus.io/) 来监控集群节点、Kubernetes 组件和软件部署的状态和进程。 + +启用监控后，你可以通过设置告警和通知器来配置接收告警的机制。 + +通知器是通知你告警事件的服务。你可以通过配置通知器来向最适合采取纠正措施的员工发送告警通知。支持使用 Slack、电子邮件、PagerDuty、微信和 webhook 发送通知。 + +告警是触发这些通知的规则。在接收告警之前，你必须在 Rancher 中配置一个或多个通知器。你可以在集群或项目级别设置告警范围。 + +如需更多信息，请参阅[监控文档](../integrations-in-rancher/monitoring-and-alerting/monitoring-and-alerting.md)。 + +## Istio + +[Istio](https://istio.io/) 是一种开源工具，可以让 DevOps 团队更轻松地观察、控制、排查并保护复杂的微服务网络中的流量。 + +Rancher v2.5 改进了与 Istio 的集成。 + +如需更多信息，请参阅 [Istio 文档](..//integrations-in-rancher/istio/istio.md)。 +## OPA Gatekeeper + +[OPA Gatekeeper](https://github.com/open-policy-agent/gatekeeper) 是一个开源项目，它对 OPA 和 Kubernetes 进行了集成，以通过许可控制器 Webhook 提供策略控制。有关如何在 Rancher 中启用 Gatekeeper 的详细信息，请参阅 [OPA Gatekeeper](../integrations-in-rancher/opa-gatekeeper.md)。 + +## CIS 扫描 + +Rancher 可以通过运行安全扫描来检查 Kubernetes 是否按照 CIS Kubernetes Benchmark 中定义的安全最佳实践进行部署。 + +如需更多信息，请参阅 [CIS 扫描文档](../how-to-guides/advanced-user-guides/cis-scan-guides/cis-scan-guides.md)。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/rancher-manager-architecture/architecture-recommendations.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/rancher-manager-architecture/architecture-recommendations.md new file mode 100644 index 00000000000..2b518f95407 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/rancher-manager-architecture/architecture-recommendations.md @@ -0,0 +1,66 @@ +--- +title: 架构推荐 +--- + +如果你准备在单个节点上安装 Rancher，我们推荐你[分开部署 Rancher 与下游集群](#分开部署-rancher-与下游集群)。 + +## 分开部署 Rancher 与下游集群 + +下游集群，是运行你自己的应用和服务的下游 Kubernetes 集群。 + +如果你通过 Docker 安装了 Rancher，运行 Rancher Server 的节点应该与你的下游集群分开。 + +如果你需要使用 Rancher 管理下游 Kubernetes 集群，那么运行 Rancher Server 的 Kubernetes 集群也应该与下游集群分开。 + +![分开部署 Rancher Server 与下游集群](/img/rancher-architecture-separation-of-rancher-server.svg) + +## 为什么高可用（HA）更适合生产环境中的 Rancher + +我们建议在高可用 Kubernetes 集群上安装 Rancher Server，以保护 Rancher Server 的数据。在高可用安装中，负载均衡器充当客户端的单点入口，并在集群中的多台服务器之间分配网络流量，这有助于防止任何一台服务器成为单点故障。 + +我们不建议在单个 Docker 容器中安装 Rancher，因为如果该节点发生故障，则其他节点上将没有可用的集群数据副本，并且你可能会丢失 Rancher Server 上的数据。 + +### K3s Kubernetes 集群安装 + +底层 Kubernetes 集群的一种选择是使用 K3s Kubernetes。K3s 是 Rancher CNCF 认证的 Kubernetes 发行版。K3s 易于安装，仅需要 Kubernetes 内存的一半，所有组件都在一个小于 100 MB 的二进制文件中。K3s 的另一个优点是允许外部 Datastore 保存集群数据，因此可以把 K3s 服务器节点视为无状态。 + +
运行 Rancher Management Server 的 K3s Kubernetes 集群的架构
+ +![运行 Rancher Management Server 的 K3s Kubernetes 集群的架构](/img/k3s-server-storage.svg) + +## Kubernetes 安装的负载均衡器推荐配置 + +我们建议你为负载均衡器和 Ingress Controller 使用以下配置： + +* 把 Rancher 的 DNS 解析到四层负载均衡器上。 +* 负载均衡器应该把 TCP/80 端口和 TCP/443 端口的流量转发到 Kubernetes 集群的全部 3 个节点上。 +* Ingress Controller 会把 HTTP 重定向到 HTTPS，在 TCP/443 端口终结 SSL/TLS。 +* Ingress Controller 会把流量转发到 Rancher deployment 的 Pod 上的 TCP/80 端口。 + +
在 Kubernetes 集群中安装 Rancher，并使用四层负载均衡器，SSL 终止在 Ingress Controller 中
+ +![Rancher HA](/img/ha/rancher2ha.svg) + +## Kubernetes 安装环境 + +我们强烈建议你把 Rancher 安装到托管在云提供商（如 AWS EC2 和 Google Compute Engine（GCE）等）上的 Kubernetes 集群上。 + +为了达到最佳性能和安全性，我们建议你为 Rancher Management Server 创建一个专用的 Kubernetes 集群。不建议在此集群上运行用户工作负载。部署 Rancher 后，你可以[创建或导入集群](../../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/kubernetes-clusters-in-rancher-setup.md)来运行你的工作负载。 + +## Kubernetes 安装的推荐节点角色 + +如果 Rancher 安装在 K3s Kubernetes 上，则适用以下建议。 + +### K3s 集群角色 + +在 K3s 集群中有两种类型的节点，分别是 Server 节点和 Agent 节点。你可以把工作负载调度到 Server 节点和 Agent 节点上。Server 节点运行 Kubernetes master。 + +对于运行 Rancher Management Server 的集群，我们建议使用两个 server 节点。不需要 Agent 节点。 + +## 授权集群端点架构 + +如果你使用[授权集群端点（ACE）](../../reference-guides/rancher-manager-architecture/communicating-with-downstream-user-clusters.md#4-授权集群端点)，我们建议你创建一个指向负载均衡器的 FQDN，这个负载均衡器把流量转到所有角色为 `controlplane` 的节点。 + +如果你在负载均衡器上使用了私有 CA 签发的证书，你需要提供 CA 证书，这个证书会包含在生成的 kubeconfig 文件中，以校验证书链。详情请参见 [kubeconfig 文件](../../how-to-guides/new-user-guides/manage-clusters/access-clusters/use-kubectl-and-kubeconfig.md)和 [API 密钥](../user-settings/api-keys.md#创建-api-密钥)的相关文档。 + +注册的 RKE2 和 K3s 集群可以使用 ACE 支持。点击[这里](../../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/register-existing-clusters.md#对-rke2-和-k3s-集群的授权集群端点支持)了解在下游集群中开启 ACE 的步骤。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/rancher-manager-architecture/communicating-with-downstream-user-clusters.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/rancher-manager-architecture/communicating-with-downstream-user-clusters.md new file mode 100644 index 00000000000..36f32cb1b49 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/rancher-manager-architecture/communicating-with-downstream-user-clusters.md @@ -0,0 +1,131 @@ +--- +title: 与下游集群通信 +--- + +本节介绍 Rancher 如何配置和管理运行应用和服务的下游集群。 + +下图显示了 Cluster Controller、Cluster Agent 和 Node Agent 让 Rancher 控制下游集群的。 + +
与下游集群通信
+ +![Rancher 组件](/img/rancher-architecture-cluster-controller.svg) + +以下描述对应于上图中的数字： + +1. [认证代理](#1-认证代理) +2. [Cluster Controller 和 Cluster Agent](#2-cluster-controller-和-cluster-agent) +3. [Node Agents](#3-node-agents) +4. [授权集群端点](#4-授权集群端点) + +## Components + +### 1. 认证代理 + +在此图中，名为 Bob 的用户希望查看在名为 User Cluster 1 的下游集群上运行的所有 Pod。在 Rancher 中，他可以运行 `kubectl` 命令来查看 +Pod。Bob 通过 Rancher 的认证代理进行身份验证。 + +认证代理将所有 Kubernetes API 调用转发到下游集群。它集成了本地身份验证、Active Directory 和 GitHub 等身份验证方式。在每个 Kubernetes API 调用请求时，认证代理会验证请求方的身份，并在转发给 Kubernetes master 节点之前，设置正确的 Kubernetes 消息头。 + +Rancher 使用 [ServiceAccount](https://kubernetes.io/docs/tasks/configure-pod-container/configure-service-account/) 与 Kubernetes 集群通信，该 ServiceAccount 为在 Pod 中运行的进程提供身份。 + +默认情况下，Rancher 生成一个 [kubeconfig 文件](../../how-to-guides/new-user-guides/manage-clusters/access-clusters/use-kubectl-and-kubeconfig.md)，文件包含凭证信息，用于为 Rancher Server 连接下游集群的 Kubernetes API Server 的代理。kubeconfig 文件 (`kube_config_rancher-cluster.yml`) 包含对集群的完全访问权限。 + +### 2. Cluster Controller 和 Cluster Agent + +每个下游集群都有一个 Cluster Agent，用于打开与 Rancher Server 中对应的 Cluster Controller 之间的通道。 + +每个下游集群有一个 Cluster Controller 和一个 Cluster Agent。每个 Cluster Controller 都能： + +- 检测下游集群中的资源变化 +- 将下游集群的当前状态变更到目标状态 +- 配置集群和项目的访问控制策略 +- 通过调用所需的 Docker Machine 驱动和 Kubernetes 引擎（例如，GKE）来配置集群 + +默认情况下，Cluster Controller 连接到 Cluster Agent，Rancher 才能与下游集群通信。如果 Cluster Agent 不可用，Cluster Controller 可以连接到 [Node Agent](#3-node-agents)。 + +Cluster Agent，也叫做 `cattle-cluster-agent`，是运行在下游集群中的组件。它具有以下功能： + +- 连接 Rancher 启动的 Kubernetes 集群中的 Kubernetes API。 +- 管理集群内的工作负载，pod 创建和部署。 +- 根据每个集群的全局策略，应用定义的角色和绑定。 +- 通过与 Cluster Controller 之间的通道，实现集群和 Rancher Server 之间的通信，包括事件，统计数据，节点信息和健康状况。 + +### 3. Node Agents + +如果 Cluster Agent（也称为 `cattle-cluster-agent`）不可用，其中一个 Node Agent 会创建一个连接到 Cluster Controller 的通道与 Rancher 通信。 + +`cattle-node-agent` 使用 [DaemonSet](https://kubernetes.io/docs/concepts/workloads/controllers/daemonset/) 资源进行部署，以确保它能在 Rancher 启动的 Kubernetes 集群中的每个节点上运行，用于在执行集群操作时与节点交互。集群操作的包括升级 Kubernetes 版本，创建或恢复 etcd 快照等。 + +### 4. 授权集群端点 + +授权集群端点（ACE）可连接到下游集群的 Kubernetes API Server，而不用通过 Rancher 认证代理调度请求。 + +> 授权集群端点仅适用于 Rancher 启动的 Kubernetes 集群，即 [Rancher 配置的集群](../../how-to-guides/new-user-guides/launch-kubernetes-with-rancher/launch-kubernetes-with-rancher.md) 它不适用于导入的集群，也不适用于托管在 Kubernetes 提供商中的集群（例如 Amazon 的 EKS）。 + +授权集群端点的主要用途： + +- 在 Rancher 不可用时访问下游集群 +- 在 Rancher Server 和与下游集群之间相距甚远时降低延迟 + +`kube-api-auth` 微服务为授权集群端点提供用户验证功能。当使用 `kubectl`访问下游集群时，集群的 Kubernetes API Server 使用 `kube-api-auth` 服务作为 webhook 对用户进行身份验证。 + +与授权集群端点一样，`kube-api-auth` 的身份验证功能也仅适用于 Rancher 启动的 Kubernetes 集群。 + +> **示例场景：** 假设 Rancher Server 位于美国，User Cluster 1 与用户 Alice 均位于澳大利亚。Alice 可以使用 Rancher UI 操作 User Cluster 1 中的资源，但她的请求必须从澳大利亚发送到美国的 Rancher Server，然后通过代理返回澳大利亚，即下游集群所在的位置。地理距离可能导致明显延迟，因此，Alice 可以使用授权集群端点来降低延迟。 + +为下游集群启用授权集群端点后，Rancher 会在 kubeconfig 文件中额外生成一段 Kubernetes 上下文，用于直连到集群。该文件具有 `kubectl` 和 `helm`的凭证。 + +如果 Rancher 出现问题，你需要使用此 kubeconfig 文件中定义的上下文来访问集群。因此，我们建议你导出 kubeconfig 文件，以便在 Rancher 出现问题时，仍能使用文件中的凭证访问集群。详情请参见使用 [kubectl 和 kubeconfig 文件](../../how-to-guides/new-user-guides/manage-clusters/access-clusters/use-kubectl-and-kubeconfig.md)访问集群的章节。 + +## 重要文件 + +维护、排除问题和升级集群需要用到以下文件，请妥善保管这些文件： + +- `config.yaml`: The RKE2 and K3s cluster configuration file. +- `rke2.yaml` or `k3s.yaml`: The Kubeconfig file for your RKE2 or K3s cluster. This file contains credentials for full access to the cluster. You can use this file to authenticate with a Rancher-launched Kubernetes cluster if Rancher goes down. + +有关在没有 Rancher 认证代理和其他配置选项的情况下连接到集群的更多信息，请参见 [kubeconfig 文件](../../how-to-guides/new-user-guides/manage-clusters/access-clusters/use-kubectl-and-kubeconfig.md)。 + +## 配置 Kubernetes 集群的工具 + +Rancher 使用什么工具配置下游集群，取决于集群的类型。 + +### Rancher 为托管在云提供商中的节点启动 Kubernetes + +Rancher 可以动态启动云上（如 Amazon EC2、DigitalOcean、Azure 或 vSphere 等）的节点，然后在节点上安装 Kubernetes。 + +Rancher 使用 [docker-machine](https://github.com/rancher/machine) 来配置这类型的集群。 + +### Rancher Launched Kubernetes for Custom Nodes + +When setting up this type of cluster, Rancher installs Kubernetes on existing nodes, which creates a custom cluster. + +Rancher provisions this type of cluster using [RKE2](https://github.com/rancher/rke2) or [K3s](https://github.com/rancher/k3s). + +### 托管的 Kubernetes 提供商 + +配置此类集群时，Kubernetes 由云提供商安装，如 GKE、ECS 或 AKS 等。 + +Rancher 使用 [kontainer-engine](https://github.com/rancher/kontainer-engine) 配置此类型的集群。 + +### 导入的 Kubernetes 集群 + +这种情况下，Rancher 需要连接到一个设置好的 Kubernetes 集群。因此，Rancher 不提供 Kubernetes，只设置 Rancher Agent 实现与集群通信。 + +## Rancher Server 组件和源码 + +下图展示了 Rancher Server 的组件： + +![Rancher 组件](/img/rancher-architecture-rancher-components.svg) + +Rancher 的 GitHub 代码仓库如下： + +- [Rancher Server 主代码库](https://github.com/rancher/rancher) +- [Rancher UI](https://github.com/rancher/ui) +- [Rancher API UI](https://github.com/rancher/api-ui) +- [Norman](https://github.com/rancher/norman)（Rancher 的 API 框架） +- [类型](https://github.com/rancher/types) +- [Rancher CLI](https://github.com/rancher/cli) +- [应用商店](https://github.com/rancher/helm) + +以上仅列出部分 Rancher 最重要的仓库。详情请参见[参与 Rancher 开源贡献](../../contribute-to-rancher.md#rancher-仓库)。如需获取 Rancher 使用的所有库和项目，请参见 `rancher/rancher` 仓库中的 [`go.mod` 文件](https://github.com/rancher/rancher/blob/master/go.mod)。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/rancher-manager-architecture/rancher-manager-architecture.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/rancher-manager-architecture/rancher-manager-architecture.md new file mode 100644 index 00000000000..edc2686bb64 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/rancher-manager-architecture/rancher-manager-architecture.md @@ -0,0 +1,20 @@ +--- +title: 架构 +--- + + + + + +本章节重点介绍 [Rancher Server 及其组件](rancher-server-and-components.md) 以及 [Rancher 如何与下游 Kubernetes 集群通信](communicating-with-downstream-user-clusters.md) +有关安装 Rancher 的不同方式的信息，请参见[安装选项概述](../../getting-started/installation-and-upgrade/installation-and-upgrade.md#安装方式概述)。 + +有关 Rancher API Server 的主要功能，请参见[概述](../../getting-started/overview.md#rancher-api-server-的功能)。 + +有关如何为 Rancher Server 设置底层基础架构，请参见[架构推荐](architecture-recommendations.md)。 + +:::note + +本节默认你已对 Docker 和 Kubernetes 有一定的了解。如果你需要了解 Kubernetes 组件如何协作，请参见 [Kubernetes 概念](../kubernetes-concepts.md)。 + +::: diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/rancher-manager-architecture/rancher-server-and-components.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/rancher-manager-architecture/rancher-server-and-components.md new file mode 100644 index 00000000000..ef25d5ea4c1 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/rancher-manager-architecture/rancher-server-and-components.md @@ -0,0 +1,35 @@ +--- +title: Rancher Server 和 Components +--- + +大多数 Rancher 2.x 软件均运行在 Rancher Server 上。Rancher Server 包括用于管理整个 Rancher 部署的所有软件组件。 + +下图展示了 Rancher 2.x 的上层架构。下图中，Rancher Server 管理两个下游 Kubernetes 集群，其中一个由 RKE 创建，另一个由 Amazon EKS 创建。 + +为了达到最佳性能和安全性，我们建议你为 Rancher Management Server 创建一个专用的 Kubernetes 集群。不建议在此集群上运行用户工作负载。部署 Rancher 后，你可以[创建或导入集群](../../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/kubernetes-clusters-in-rancher-setup.md)来运行你的工作负载。 + +下图介绍了用户如何通过 Rancher 的认证代理管理 [Rancher 启动的 Kubernetes](../../how-to-guides/new-user-guides/launch-kubernetes-with-rancher/launch-kubernetes-with-rancher.md) 集群和[托管的 Kubernetes](../../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-clusters-from-hosted-kubernetes-providers/set-up-clusters-from-hosted-kubernetes-providers.md) 集群： + +
通过 Rancher 的认证代理管理 Kubernetes 集群
+ +![架构](/img/rancher-architecture-rancher-api-server.svg) + +你可以把 Rancher 安装到单个节点或高可用 Kubernetes 集群上。 + +在生产环境中，建议安装到高可用 Kubernetes 集群。 + +Rancher 的 Docker 安装仅推荐用于开发和测试环境中。Rancher 版本决定了能否将 Rancher 迁移到高可用集群。 + +要查看已部署的资源，运行以下命令： + +```bash +kubectl get all -n +``` +如果你具有管理员权限，你还可以在 Rancher UI 中看到列出的资源： + +1. 单击 **☰** 并选择一个集群。 +1. 从侧面导航菜单中选择**更多资源**，从而按类型查看已部署的资源。 +1. 从侧面导航菜单中选择**集群** > **项目/命名空间**，然后选择一个命名空间，从而按命名空间查看已部署的资源。 + Rancher backup operator 可将 Rancher 从单个 Docker 容器迁移到高可用 Kubernetes 集群上。有关详细信息，请参阅[将 Rancher 迁移到新集群](../../how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/migrate-rancher-to-new-cluster.md)。 + +不管 Rancher Server 是如何安装的，它都应该运行在与其管理的下游集群不同节点上。如果 Rancher 安装在高可用的 Kubernetes 集群上，它需要运行在与其管理的集群不同的集群上。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/rancher-project-tools.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/rancher-project-tools.md new file mode 100644 index 00000000000..fd99a83952e --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/rancher-project-tools.md @@ -0,0 +1,32 @@ +--- +title: 项目工具：Logging，Monitoring 和可视化 +--- + +Rancher 包含 Kubernetes 中未包含的各种工具来协助你进行 DevOps 操作。Rancher 可以与外部服务集成，让你的集群更高效地运行。 + + +## Notifiers 和告警 + +通知器和告警是两个协同工作的功能，它们可以将 Rancher 系统中的事件告知你。在启用它们之前，你必须先安装监控应用。 + +通知器是通知你告警事件的服务。你可以通过配置通知器来向最适合采取纠正措施的员工发送告警通知。支持使用 Slack、电子邮件、PagerDuty、微信和 webhook 发送通知。 + +告警是触发这些通知的规则。在接收告警之前，你必须在 Rancher 中配置一个或多个通知器。你可以在集群或项目级别设置告警范围。 + +## Logging + +Logging 支持： + +- 获取和分析集群的状态 +- 在你的环境中发现趋势 +- 将日志保存到集群外部的安全位置 +- 随时了解容器崩溃、pod 驱逐或节点死亡等事件 +- 更轻松地调试和解决问题 + +Rancher 可以与 Elasticsearch、splunk、kafka、syslog 和 fluentd 集成。 + +有关详细信息，请参阅 [Logging](../integrations-in-rancher/logging/logging.md)。 + +## Monitoring + +你可以使用 Rancher，通过业界领先并开源的 [Prometheus](https://prometheus.io/) 来监控集群节点、Kubernetes 组件和软件部署的状态和进程。有关详细信息，请参阅 [Monitoring](../integrations-in-rancher/monitoring-and-alerting/monitoring-and-alerting.md)。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/rancher-security/hardening-guides/hardening-guides.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/rancher-security/hardening-guides/hardening-guides.md new file mode 100644 index 00000000000..799268cdd1e --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/rancher-security/hardening-guides/hardening-guides.md @@ -0,0 +1,42 @@ +--- +title: Rancher 自我评估和加固指南 +--- + + + + + +Rancher 为每个受支持的 Rancher 版本的 Kubernetes 发行版提供了特定的安全强化指南。 + +## Rancher Kubernetes 发行版 + +Rancher 使用以下 Kubernetes 发行版： + +- [**RKE2**](https://docs.rke2.io/) 是一个完全合规的 Kubernetes 发行版，专注于安全和合规性。 +- [**K3s**](https://docs.k3s.io/) 是一个完全合规的，轻量级 Kubernetes 发行版。它易于安装，内存需求只有上游 Kubernetes 的一半，所有组件都在一个小于 100 MB 的二进制文件中。 + +要加固运行未列出的发行版的 Kubernetes 集群，请参阅 Kubernetes 提供商文档。 + +## 加固指南和 Benchmark 版本 + +每个自我评估指南都附有强化指南。这些指南与列出的 Rancher 版本一起进行了测试。每个自我评估指南都在特定的 Kubernetes 版本和 CIS Benchmark 版本上进行了测试。如果 CIS Benchmark 尚未针对你的 Kubernetes 版本进行验证，你可以使用现有指南，直到添加适合你的版本的指南。 + +### RKE2 指南 + +| 类型 | Kubernetes 版本 | CIS Benchmark 版本 | 自我评估指南 | 加固指南 | +|------|--------------------|-----------------------|-----------------------|------------------| +| Rancher provisioned RKE2 | Kubernetes v1.25/v1.26/v1.27 | CIS v1.7 | [链接](rke2-hardening-guide/rke2-self-assessment-guide-with-cis-v1.7-k8s-v1.25-v1.26-v1.27.md) | [链接](rke2-hardening-guide/rke2-hardening-guide.md) | +| Standalone RKE2 | Kubernetes v1.27-v1.32 | CIS v1.9 | [链接](https://docs.rke2.io/security/cis_self_assessment19) | [链接](https://docs.rke2.io/security/hardening_guide) | + +### K3s 指南 + +| 类型 | Kubernetes 版本 | CIS Benchmark 版本 | 自我评估指南 | 加固指南 | +|------|--------------------|-----------------------|-----------------------|------------------| +| Rancher provisioned K3s cluster | Kubernetes v1.25/v1.26/v1.27 | CIS v1.7 | [链接](k3s-hardening-guide/k3s-self-assessment-guide-with-cis-v1.7-k8s-v1.25-v1.26-v1.27.md) | [链接](k3s-hardening-guide/k3s-hardening-guide.md) | +| Standalone K3s | Kubernetes v1.26 up to v1.29 | CIS v1.8 | [链接](https://docs.k3s.io/security/self-assessment-1.8) | [链接](https://docs.k3s.io/security/hardening-guide) | + +## 在 SELinux 上使用 Rancher + +[Security-Enhanced Linux (SELinux)](https://en.wikipedia.org/wiki/Security-Enhanced_Linux) 是一个内核模块，为 Linux 添加了额外的访问控制和安全工具。SELinux 过去曾被政府机构使用，现在已成为行业标准。SELinux 在 RHEL 和 CentOS 上默认启用。 + +要将 Rancher 与 SELinux 结合使用，我们建议[安装](../selinux-rpm/about-rancher-selinux.md) `rancher-selinux`。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/rancher-security/hardening-guides/k3s-hardening-guide/k3s-hardening-guide.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/rancher-security/hardening-guides/k3s-hardening-guide/k3s-hardening-guide.md new file mode 100644 index 00000000000..bb9639fc118 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/rancher-security/hardening-guides/k3s-hardening-guide/k3s-hardening-guide.md @@ -0,0 +1,744 @@ +--- +title: K3s 加固指南 +--- + + + + + +本文档提供了针对生产环境的 K3s 集群进行加固的具体指导，以便在使用 Rancher 部署之前进行配置。它概述了满足信息安全中心（Center for Information Security, CIS）Kubernetes benchmark controls 所需的配置和控制。 + +:::note +这份加固指南描述了如何确保你集群中的节点安全。我们建议你在安装 Kubernetes 之前遵循本指南。 +::: + +此加固指南适用于 K3s 集群，并与以下版本的 CIS Kubernetes Benchmark、Kubernetes 和 Rancher 相关联： + +| Rancher 版本 | CIS Benchmark 版本 | Kubernetes 版本 | +|-----------------|-----------------------|------------------------------| +| Rancher v2.7 | Benchmark v1.23 | Kubernetes v1.23 | +| Rancher v2.7 | Benchmark v1.24 | Kubernetes v1.24 | +| Rancher v2.7 | Benchmark v1.7 | Kubernetes v1.25 至 v1.26 | + +:::note +在 Benchmark v1.7 中，不再需要 `--protect-kernel-defaults` (4.2.6) 参数，并已被 CIS 删除。 +::: + +有关如何评估加固的 K3s 集群与官方 CIS benchmark 的更多细节，请参考特定 Kubernetes 和 CIS benchmark 版本的 K3s 自我评估指南。 + +K3s 在不需要修改的情况下通过了许多 Kubernetes CIS controls，因为它默认应用了几个安全缓解措施。然而，有一些值得注意的例外情况，需要手动干预才能完全符合 CIS Benchmark 要求： + +1. K3s 不修改主机操作系统。任何主机级别的修改都需要手动完成。 +2. 某些 CIS policy controls，例如 `NetworkPolicies` 和 `PodSecurityStandards`（在 v1.24 及更早版本中为 `PodSecurityPolicies`），会限制集群功能。 + 你必须选择让 K3s 配置这些策略。在你的命令行标志或配置文件中添加相应的选项（启用准入插件），并手动应用适当的策略。 + 请参阅以下详细信息。 + +CIS Benchmark 的第一部分（1.1）主要关注于 Pod manifest 的权限和所有权。由于发行版中的所有内容都打包在一个二进制文件中，因此这一部分不适用于 K3s 的核心组件。 + +## 主机级别要求 + +### 确保 `protect-kernel-defaults`已经设置 + + + + +自 CIS benchmark 1.7 开始，不再需要`protect-kernel-defaults`。 + + + + +这是一个 kubelet 标志，如果所需的内核参数未设置或设置为与 kubelet 的默认值不同的值，将导致 kubelet 退出。 + +可以在 Rancher 的集群配置中设置 `protect-kernel-defaults` 标志。 + +```yaml +spec: + rkeConfig: + machineSelectorConfig: + - config: + protect-kernel-defaults: true +``` + + + + +### 设置内核参数 + +建议为集群中的所有节点类型设置以下 `sysctl` 配置。在 `/etc/sysctl.d/90-kubelet.conf` 中设置以下参数： + +```ini +vm.panic_on_oom=0 +vm.overcommit_memory=1 +kernel.panic=10 +kernel.panic_on_oops=1 +``` + +运行 `sudo sysctl -p /etc/sysctl.d/90-kubelet.conf` 以启用设置。 + +此配置需要在设置 kubelet 标志之前完成，否则 K3s 将无法启动。 + +## Kubernetes 运行时要求 + +CIS Benchmark 的运行时要求主要围绕 Pod 安全（通过 PSA）、网络策略和 API 服务器审计日志展开。 + +默认情况下，K3s 不包含任何 Pod 安全或网络策略。然而，K3s 附带一个控制器，可以强制执行你创建的任何网络策略。默认情况下，K3s 启用了 `PodSecurity` 和 `NodeRestriction` 等多个准入控制器。 + +### Pod 安全 + + + + +K3s v1.25 及更新版本支持 [Pod 安全准入(PSA)](https://kubernetes.io/docs/concepts/security/pod-security-admission/)，用于控制 Pod 安全性。 + +你可以在 Rancher 中通过集群配置，设置 `defaultPodSecurityAdmissionConfigurationTemplateName` 字段来指定 PSA 配置： + +```yaml +spec: + defaultPodSecurityAdmissionConfigurationTemplateName: rancher-restricted +``` + +Rancher 提供了 `rancher-restricted` 模板，用于强制执行高度限制性的 Kubernetes 上游 [`Restricted`](https://kubernetes.io/docs/concepts/security/pod-security-standards/#restricted) 配置文件，其中包含了 Pod 加固的最佳实践。 + + + + +K3s v1.24 及更早版本支持 [Pod 安全策略 (PSP)](https://github.com/kubernetes/website/blob/release-1.24/content/en/docs/concepts/security/pod-security-policy.md) 以控制 Pod 安全性。 + +你可以在 Rancher 中通过集群配置，传递以下标志来启用 PSPs： + +```yaml +spec: + rkeConfig: + machineGlobalConfig: + kube-apiserver-arg: + - enable-admission-plugins=NodeRestriction,PodSecurityPolicy,ServiceAccount +``` + +这会保留 `NodeRestriction` 插件并启用 `PodSecurityPolicy`。 + +启用 PSPs 后，你可以应用策略来满足 CIS Benchmark 第 5.2 节中描述的必要控制。 + +:::note +这些是 CIS Benchmark 中的手动检查。CIS 扫描结果将标记为 `warning`，因为需要集群操作员进行手动检查。 +::: + +以下是合规的 PSP 示例： + +```yaml +--- +apiVersion: policy/v1beta1 +kind: PodSecurityPolicy +metadata: + name: restricted-psp +spec: + privileged: false # CIS - 5.2.1 + allowPrivilegeEscalation: false # CIS - 5.2.5 + requiredDropCapabilities: # CIS - 5.2.7/8/9 + - ALL + volumes: + - 'configMap' + - 'emptyDir' + - 'projected' + - 'secret' + - 'downwardAPI' + - 'csi' + - 'persistentVolumeClaim' + - 'ephemeral' + hostNetwork: false # CIS - 5.2.4 + hostIPC: false # CIS - 5.2.3 + hostPID: false # CIS - 5.2.2 + runAsUser: + rule: 'MustRunAsNonRoot' # CIS - 5.2.6 + seLinux: + rule: 'RunAsAny' + supplementalGroups: + rule: 'MustRunAs' + ranges: + - min: 1 + max: 65535 + fsGroup: + rule: 'MustRunAs' + ranges: + - min: 1 + max: 65535 + readOnlyRootFilesystem: false +``` + +要使示例 PSP 生效，我们需要创建一个 `ClusterRole` 和 一个`ClusterRoleBinding`。我们还需要为需要额外权限的系统级 Pod 提供“系统无限制策略”，以及允许必要的 sysctls 来实现 ServiceLB 完整功能的额外策略。 + +```yaml +--- +apiVersion: policy/v1beta1 +kind: PodSecurityPolicy +metadata: + name: restricted-psp +spec: + privileged: false + allowPrivilegeEscalation: false + requiredDropCapabilities: + - ALL + volumes: + - 'configMap' + - 'emptyDir' + - 'projected' + - 'secret' + - 'downwardAPI' + - 'csi' + - 'persistentVolumeClaim' + - 'ephemeral' + hostNetwork: false + hostIPC: false + hostPID: false + runAsUser: + rule: 'MustRunAsNonRoot' + seLinux: + rule: 'RunAsAny' + supplementalGroups: + rule: 'MustRunAs' + ranges: + - min: 1 + max: 65535 + fsGroup: + rule: 'MustRunAs' + ranges: + - min: 1 + max: 65535 + readOnlyRootFilesystem: false +--- +apiVersion: policy/v1beta1 +kind: PodSecurityPolicy +metadata: + name: system-unrestricted-psp + annotations: + seccomp.security.alpha.kubernetes.io/allowedProfileNames: '*' +spec: + allowPrivilegeEscalation: true + allowedCapabilities: + - '*' + fsGroup: + rule: RunAsAny + hostIPC: true + hostNetwork: true + hostPID: true + hostPorts: + - max: 65535 + min: 0 + privileged: true + runAsUser: + rule: RunAsAny + seLinux: + rule: RunAsAny + supplementalGroups: + rule: RunAsAny + volumes: + - '*' +--- +apiVersion: policy/v1beta1 +kind: PodSecurityPolicy +metadata: + name: svclb-psp + annotations: + seccomp.security.alpha.kubernetes.io/allowedProfileNames: '*' +spec: + allowPrivilegeEscalation: false + allowedCapabilities: + - NET_ADMIN + allowedUnsafeSysctls: + - net.ipv4.ip_forward + - net.ipv6.conf.all.forwarding + fsGroup: + rule: RunAsAny + hostPorts: + - max: 65535 + min: 0 + runAsUser: + rule: RunAsAny + seLinux: + rule: RunAsAny + supplementalGroups: + rule: RunAsAny +--- +apiVersion: rbac.authorization.k8s.io/v1 +kind: ClusterRole +metadata: + name: psp:restricted-psp +rules: +- apiGroups: + - policy + resources: + - podsecuritypolicies + verbs: + - use + resourceNames: + - restricted-psp +--- +apiVersion: rbac.authorization.k8s.io/v1 +kind: ClusterRole +metadata: + name: psp:system-unrestricted-psp +rules: +- apiGroups: + - policy + resources: + - podsecuritypolicies + resourceNames: + - system-unrestricted-psp + verbs: + - use +--- +apiVersion: rbac.authorization.k8s.io/v1 +kind: ClusterRole +metadata: + name: psp:svclb-psp +rules: +- apiGroups: + - policy + resources: + - podsecuritypolicies + resourceNames: + - svclb-psp + verbs: + - use +--- +apiVersion: rbac.authorization.k8s.io/v1 +kind: ClusterRole +metadata: + name: psp:svc-local-path-provisioner-psp +rules: +- apiGroups: + - policy + resources: + - podsecuritypolicies + resourceNames: + - system-unrestricted-psp + verbs: + - use +--- +apiVersion: rbac.authorization.k8s.io/v1 +kind: ClusterRole +metadata: + name: psp:svc-coredns-psp +rules: +- apiGroups: + - policy + resources: + - podsecuritypolicies + resourceNames: + - system-unrestricted-psp + verbs: + - use +--- +apiVersion: rbac.authorization.k8s.io/v1 +kind: ClusterRole +metadata: + name: psp:svc-cis-operator-psp +rules: +- apiGroups: + - policy + resources: + - podsecuritypolicies + resourceNames: + - system-unrestricted-psp + verbs: + - use +--- +apiVersion: rbac.authorization.k8s.io/v1 +kind: ClusterRoleBinding +metadata: + name: default:restricted-psp +roleRef: + apiGroup: rbac.authorization.k8s.io + kind: ClusterRole + name: psp:restricted-psp +subjects: +- kind: Group + name: system:authenticated + apiGroup: rbac.authorization.k8s.io +--- +apiVersion: rbac.authorization.k8s.io/v1 +kind: ClusterRoleBinding +metadata: + name: system-unrestricted-node-psp-rolebinding +roleRef: + apiGroup: rbac.authorization.k8s.io + kind: ClusterRole + name: psp:system-unrestricted-psp +subjects: +- apiGroup: rbac.authorization.k8s.io + kind: Group + name: system:nodes +--- +apiVersion: rbac.authorization.k8s.io/v1 +kind: RoleBinding +metadata: + name: system-unrestricted-svc-acct-psp-rolebinding + namespace: kube-system +roleRef: + apiGroup: rbac.authorization.k8s.io + kind: ClusterRole + name: psp:system-unrestricted-psp +subjects: +- apiGroup: rbac.authorization.k8s.io + kind: Group + name: system:serviceaccounts +--- +apiVersion: rbac.authorization.k8s.io/v1 +kind: RoleBinding +metadata: + name: svclb-psp-rolebinding + namespace: kube-system +roleRef: + apiGroup: rbac.authorization.k8s.io + kind: ClusterRole + name: psp:svclb-psp +subjects: +- kind: ServiceAccount + name: svclb +--- +apiVersion: rbac.authorization.k8s.io/v1 +kind: RoleBinding +metadata: + name: svc-local-path-provisioner-psp-rolebinding + namespace: kube-system +roleRef: + apiGroup: rbac.authorization.k8s.io + kind: ClusterRole + name: psp:svc-local-path-provisioner-psp +subjects: +- kind: ServiceAccount + name: local-path-provisioner-service-account +--- +apiVersion: rbac.authorization.k8s.io/v1 +kind: RoleBinding +metadata: + name: svc-coredns-psp-rolebinding + namespace: kube-system +roleRef: + apiGroup: rbac.authorization.k8s.io + kind: ClusterRole + name: psp:svc-coredns-psp +subjects: +- kind: ServiceAccount + name: coredns +--- +apiVersion: rbac.authorization.k8s.io/v1 +kind: RoleBinding +metadata: + name: svc-cis-operator-psp-rolebinding + namespace: cis-operator-system +roleRef: + apiGroup: rbac.authorization.k8s.io + kind: ClusterRole + name: psp:svc-cis-operator-psp +subjects: +- kind: ServiceAccount + name: cis-operator-serviceaccount +``` + +上述策略可以放置在 `/var/lib/rancher/k3s/server/manifests` 目录下名为 `policy.yaml` 的文件中。在启动 K3s 之前，必须创建策略文件和其目录结构。建议限制访问权限以避免泄露潜在的敏感信息。 + +```shell +sudo mkdir -p -m 700 /var/lib/rancher/k3s/server/manifests +``` + +:::note +CNI、DNS 和 Ingress 等关键 Kubernetes 组件在 `kube-system` 命名空间中作为 Pod 运行。因此，这个命名空间的限制政策较少，从而使这些组件能够正常运行。 +::: + + + + +### 网络策略 + +CIS 要求所有命名空间应用网络策略，合理限制进入命名空间和 Pod 的流量。 + +:::note +这些是 CIS Benchmark 中的手动检查。CIS 扫描结果将标记为 `warning`，因为需要集群操作员进行手动检查。 +::: + +网络策略可以放置在 `/var/lib/rancher/k3s/server/manifests` 目录下的 `policy.yaml` 文件中。如果该目录不是作为 PSP（如上所述）的一部分创建的，则必须首先创建该目录。 + +```shell +sudo mkdir -p -m 700 /var/lib/rancher/k3s/server/manifests +``` + +以下是合规的网络策略示例： + +```yaml +--- +kind: NetworkPolicy +apiVersion: networking.k8s.io/v1 +metadata: + name: intra-namespace + namespace: kube-system +spec: + podSelector: {} + ingress: + - from: + - namespaceSelector: + matchLabels: + name: kube-system +--- +kind: NetworkPolicy +apiVersion: networking.k8s.io/v1 +metadata: + name: intra-namespace + namespace: default +spec: + podSelector: {} + ingress: + - from: + - namespaceSelector: + matchLabels: + name: default +--- +kind: NetworkPolicy +apiVersion: networking.k8s.io/v1 +metadata: + name: intra-namespace + namespace: kube-public +spec: + podSelector: {} + ingress: + - from: + - namespaceSelector: + matchLabels: + name: kube-public +``` + +除非特意允许，否则活动限制会阻止 DNS。以下是允许 DNS 相关流量的网络策略示例： + +```yaml +--- +apiVersion: networking.k8s.io/v1 +kind: NetworkPolicy +metadata: + name: default-network-dns-policy + namespace: +spec: + ingress: + - ports: + - port: 53 + protocol: TCP + - port: 53 + protocol: UDP + podSelector: + matchLabels: + k8s-app: kube-dns + policyTypes: + - Ingress +``` + +如果没有创建网络策略来允许访问，则默认情况下会阻止 metrics-server 和 Traefik Ingress 控制器。 + +```yaml +--- +apiVersion: networking.k8s.io/v1 +kind: NetworkPolicy +metadata: + name: allow-all-metrics-server + namespace: kube-system +spec: + podSelector: + matchLabels: + k8s-app: metrics-server + ingress: + - {} + policyTypes: + - Ingress +--- +apiVersion: networking.k8s.io/v1 +kind: NetworkPolicy +metadata: + name: allow-all-svclbtraefik-ingress + namespace: kube-system +spec: + podSelector: + matchLabels: + svccontroller.k3s.cattle.io/svcname: traefik + ingress: + - {} + policyTypes: + - Ingress +--- +apiVersion: networking.k8s.io/v1 +kind: NetworkPolicy +metadata: + name: allow-all-traefik-v121-ingress + namespace: kube-system +spec: + podSelector: + matchLabels: + app.kubernetes.io/name: traefik + ingress: + - {} + policyTypes: + - Ingress +``` + +:::note +你必须像平常一样管理你创建的任何其他命名空间的网络策略。 +::: + +### API server 审计配置 + +CIS 要求 1.2.19 至 1.2.22 与配置 API server 审核日志相关。默认情况下，K3s 不会创建日志目录和审计策略，因为每个用户的审计策略要求和环境都是特定的。 + +如果你需要日志目录，则必须在启动 K3s 之前创建它。我们建议限制访问权限以避免泄露敏感信息。 + +```bash +sudo mkdir -p -m 700 /var/lib/rancher/k3s/server/logs +``` + +以下是用于记录请求元数据的初始审计策略。应将策略写入到 `/var/lib/rancher/k3s/server` 目录下名为 `audit.yaml` 的文件中。有关 API server 的策略配置的详细信息，请参阅 [官方 Kubernetes 文档](https://kubernetes.io/docs/tasks/debug/debug-cluster/audit/)。 + +```yaml +--- +apiVersion: audit.k8s.io/v1 +kind: Policy +rules: +- level: Metadata +``` + +还需要进一步配置才能通过 CIS 检查。这些在 K3s 中默认不配置，因为它们根据你的环境和需求而有所不同： + +- 确保 `--audit-log-path` 参数已经设置。 +- 确保 `--audit-log-maxage` 参数设置为 30 或适当的值。 +- 确保 `--audit-log-maxbackup` 参数设置为 10 或适当的值。 +- 确保 `--audit-log-maxsize` 参数设置为 100 或适当的值。 + +综合起来，要启用和配置审计日志，请将以下行添加到 Rancher 的 K3s 集群配置文件中： + +```yaml +spec: + rkeConfig: + machineGlobalConfig: + kube-apiserver-arg: + - audit-policy-file=/var/lib/rancher/k3s/server/audit.yaml # CIS 3.2.1 + - audit-log-path=/var/lib/rancher/k3s/server/logs/audit.log # CIS 1.2.18 + - audit-log-maxage=30 # CIS 1.2.19 + - audit-log-maxbackup=10 # CIS 1.2.20 + - audit-log-maxsize=100 # CIS 1.2.21 +``` + +### Controller Manager 要求 + +CIS 要求 1.3.1 检查 Controller Manager 中的垃圾收集设置。垃圾收集对于确保资源充足可用性并避免性能和可用性下降非常重要。根据你的系统资源和测试结果，选择一个适当的阈值来激活垃圾收集。 + +你可以在 Rancher 的 K3s 集群文件中设置以下配置来解决此问题。下面的值仅是一个示例，请根据当前环境设置适当的阈值。 + +```yaml +spec: + rkeConfig: + machineGlobalConfig: + kube-controller-manager-arg: + - terminated-pod-gc-threshold=10 # CIS 1.3.1 +``` + +### 配置 `default` Service Account + +Kubernetes 提供了一个名为 `default` 的 service account，供集群工作负载使用，其中没有为 Pod 分配特定的 service account。当 Pod 需要从 Kubernetes API 获取访问权限时，应为该 Pod 创建一个特定的 service account，并为该 service account 授予权限。 + +对于 CIS 5.1.5，`default` service account 应配置为不提供 service account 令牌，并且不具有任何明确的权限分配。 + +可以通过在每个命名空间中将 `default` service account 的 `automountServiceAccountToken` 字段更新为 `false` 来解决此问题。 + +对于内置命名空间（`kube-system`、`kube-public`、`kube-node-lease` 和 `default`）中的 `default` service accounts，K3s 不会自动执行此操作。 + +将以下配置保存到名为 `account_update.yaml` 的文件中。 + +```yaml +--- +apiVersion: v1 +kind: ServiceAccount +metadata: + name: default +automountServiceAccountToken: false +``` + +创建一个名为 `account_update.sh` 的 Bash 脚本文件。确保使用 `chmod +x account_update.sh` 给脚本添加可执行权限。 + +```shell +#!/bin/bash -e + +for namespace in $(kubectl get namespaces -A -o=jsonpath="{.items[*]['metadata.name']}"); do + kubectl patch serviceaccount default -n ${namespace} -p "$(cat account_update.yaml)" +done +``` + +每次向你的集群添加新的 service account 时，运行该脚本。 + +## 加固版 K3s 模板配置参考 + +Rancher 使用以下参考模板配置，基于本指南中的每个 CIS 控件创建加固过的自定义 K3s 集群。此参考内容不包括其他必需的**集群配置**指令，这些指令因你的环境而异。 + + + + +```yaml +apiVersion: provisioning.cattle.io/v1 +kind: Cluster +metadata: + name: # 定义集群名称 +spec: + defaultPodSecurityAdmissionConfigurationTemplateName: rancher-restricted + enableNetworkPolicy: true + kubernetesVersion: # 定义 K3s 版本 + rkeConfig: + machineGlobalConfig: + kube-apiserver-arg: + - enable-admission-plugins=NodeRestriction,ServiceAccount # CIS 1.2.15, 1.2.13 + - audit-policy-file=/var/lib/rancher/k3s/server/audit.yaml # CIS 3.2.1 + - audit-log-path=/var/lib/rancher/k3s/server/logs/audit.log # CIS 1.2.18 + - audit-log-maxage=30 # CIS 1.2.19 + - audit-log-maxbackup=10 # CIS 1.2.20 + - audit-log-maxsize=100 # CIS 1.2.21 + - request-timeout=300s # CIS 1.2.22 + - service-account-lookup=true # CIS 1.2.24 + kube-controller-manager-arg: + - terminated-pod-gc-threshold=10 # CIS 1.3.1 + secrets-encryption: true + machineSelectorConfig: + - config: + kubelet-arg: + - make-iptables-util-chains=true # CIS 4.2.7 +``` + + + + +```yaml +apiVersion: provisioning.cattle.io/v1 +kind: Cluster +metadata: + name: # 定义集群名称 +spec: + enableNetworkPolicy: true + kubernetesVersion: # 定义 K3s 版本 + rkeConfig: + machineGlobalConfig: + kube-apiserver-arg: + - enable-admission-plugins=NodeRestriction,PodSecurityPolicy,ServiceAccount # CIS 1.2.15, 5.2, 1.2.13 + - audit-policy-file=/var/lib/rancher/k3s/server/audit.yaml # CIS 3.2.1 + - audit-log-path=/var/lib/rancher/k3s/server/logs/audit.log # CIS 1.2.18 + - audit-log-maxage=30 # CIS 1.2.19 + - audit-log-maxbackup=10 # CIS 1.2.20 + - audit-log-maxsize=100 # CIS 1.2.21 + - request-timeout=300s # CIS 1.2.22 + - service-account-lookup=true # CIS 1.2.24 + kube-controller-manager-arg: + - terminated-pod-gc-threshold=10 # CIS 1.3.1 + secrets-encryption: true + machineSelectorConfig: + - config: + kubelet-arg: + - make-iptables-util-chains=true # CIS 4.2.7 + protect-kernel-defaults: true # CIS 4.2.6 +``` + + + + +## 结论 + +如果你按照本指南操作，由 Rancher 提供的 K3s 自定义集群将配置为通过 CIS Kubernetes Benchmark 测试。你可以查看我们的 K3s 自我评估指南，了解我们是如何验证每个 benchmarks 的，并且你可以在你的集群上执行相同的操作。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/rancher-security/hardening-guides/k3s-hardening-guide/k3s-self-assessment-guide-with-cis-v1.7-k8s-v1.25-v1.26-v1.27.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/rancher-security/hardening-guides/k3s-hardening-guide/k3s-self-assessment-guide-with-cis-v1.7-k8s-v1.25-v1.26-v1.27.md new file mode 100644 index 00000000000..8443a80b530 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/rancher-security/hardening-guides/k3s-hardening-guide/k3s-self-assessment-guide-with-cis-v1.7-k8s-v1.25-v1.26-v1.27.md @@ -0,0 +1,3215 @@ +--- +title: K3s 自我评估指南 - CIS Benchmark v1.7 - K8s v1.25/v1.26/v1.27 +--- + + + + + +本文档是 [K3s 加固指南](k3s-hardening-guide.md)的配套文档，该指南提供了关于如何加固正在生产环境中运行并由 Rancher 管理的 K3s 集群的指导方针。本 benchmark 指南可帮助你根据 CIS Kubernetes Benchmark 中的每个 control 来评估加固集群的安全性。 + +本指南对应以下版本的 Rancher、CIS Benchmarks 和 Kubernetes： + +| Rancher 版本 | CIS Benchmark 版本 | Kubernetes 版本 | +|-----------------|-----------------------|--------------------| +| Rancher v2.7 | Benchmark v1.7 | Kubernetes v1.25/v1.26/v1.27 | + +本文档适用于 Rancher 运维人员、安全团队、审计员和决策者。 + +有关每个 control 的更多信息，包括详细描述和未通过测试的补救措施，请参考 CIS Kubernetes Benchmark v1.7 的相应部分。你可以在[互联网安全中心 (CIS)](https://www.cisecurity.org/benchmark/kubernetes/)创建免费账户后下载 benchmark。 + +## 测试方法 + +每个 CIS Kubernetes Benchmark 中的 control 都根据附带的加固指南评估了针对 K3s 集群的配置。 + +当 control 审计与原始的 CIS benchmark 不同的时候，提供了针对 K3s 的特定审计命令，以供测试使用。 + +以下是每个 control 可能的结果： + +- **Pass（通过）** - K3s 集群通过了 benchmark 中概述的审计。 +- **Not Applicable（不适用）** - 由于 K3s 的设计方式，该 control 不适用于 K3s。在补救措施部分解释了原因。 +- **Warn（警告）** - 在 CIS benchmark 中，该 control 是手动的，它取决于集群的使用情况或其他必须由集群操作员确定的因素。这些 control 措施已经过评估，以确保 K3s 不会阻止其实施，但尚未对集群进行进一步的配置或审计。 + +本指南假设 K3s 作为 Systemd 单元运行。你的安装可能会有所不同。调整"审计"命令以适合你的场景。 + +:::note + +本指南仅涵盖 `automated`（之前称为 `scored`）测试。 + +::: + +### Controls + + +## 1.1 Control Plane Node Configuration Files +### 1.1.1 Ensure that the API server pod specification file permissions are set to 600 or more restrictive (Automated) + + +**Result:** Not Applicable + +**Remediation:** +Run the below command (based on the file location on your system) on the +control plane node. +For example, chmod 600 /etc/kubernetes/manifests/kube-apiserver.yaml +Not Applicable. + +### 1.1.2 Ensure that the API server pod specification file ownership is set to root:root (Automated) + + +**Result:** Not Applicable + +**Remediation:** +Run the below command (based on the file location on your system) on the control plane node. +For example, chown root:root /etc/kubernetes/manifests/kube-apiserver.yaml +Not Applicable. + +### 1.1.3 Ensure that the controller manager pod specification file permissions are set to 600 or more restrictive (Automated) + + +**Result:** Not Applicable + +**Remediation:** +Run the below command (based on the file location on your system) on the control plane node. +For example, chmod 600 /etc/kubernetes/manifests/kube-controller-manager.yaml +Not Applicable. + +### 1.1.4 Ensure that the controller manager pod specification file ownership is set to root:root (Automated) + + +**Result:** Not Applicable + +**Remediation:** +Run the below command (based on the file location on your system) on the control plane node. +For example, chown root:root /etc/kubernetes/manifests/kube-controller-manager.yaml +Not Applicable. + +### 1.1.5 Ensure that the scheduler pod specification file permissions are set to 600 or more restrictive (Automated) + + +**Result:** Not Applicable + +**Remediation:** +Run the below command (based on the file location on your system) on the control plane node. +For example, chmod 600 /etc/kubernetes/manifests/kube-scheduler.yaml +Not Applicable. + +### 1.1.6 Ensure that the scheduler pod specification file ownership is set to root:root (Automated) + + +**Result:** Not Applicable + +**Remediation:** +Run the below command (based on the file location on your system) on the control plane node. +For example, chown root:root /etc/kubernetes/manifests/kube-scheduler.yaml +Not Applicable. + +### 1.1.7 Ensure that the etcd pod specification file permissions are set to 600 or more restrictive (Automated) + + +**Result:** Not Applicable + +**Remediation:** +Run the below command (based on the file location on your system) on the control plane node. +For example, +chmod 600 /etc/kubernetes/manifests/etcd.yaml +Not Applicable. + +### 1.1.8 Ensure that the etcd pod specification file ownership is set to root:root (Automated) + + +**Result:** Not Applicable + +**Remediation:** +Run the below command (based on the file location on your system) on the control plane node. +For example, +chown root:root /etc/kubernetes/manifests/etcd.yaml +Not Applicable. + +### 1.1.9 Ensure that the Container Network Interface file permissions are set to 600 or more restrictive (Automated) + + +**Result:** Not Applicable + +**Remediation:** +Run the below command (based on the file location on your system) on the control plane node. +For example, chmod 600 +Not Applicable. + +### 1.1.10 Ensure that the Container Network Interface file ownership is set to root:root (Manual) + + +**Result:** Not Applicable + +**Remediation:** +Run the below command (based on the file location on your system) on the control plane node. +For example, +chown root:root +Not Applicable. + +### 1.1.11 Ensure that the etcd data directory permissions are set to 700 or more restrictive (Automated) + + +**Result:** pass + +**Remediation:** +On the etcd server node, get the etcd data directory, passed as an argument --data-dir, +from the command 'ps -ef | grep etcd'. +Run the below command (based on the etcd data directory found above). For example, +chmod 700 /var/lib/etcd + +**Audit Script:** `check_for_k3s_etcd.sh` + +```bash +#!/bin/bash + +# This script is used to ensure that k3s is actually running etcd (and not other databases like sqlite3) +# before it checks the requirement +set -eE + +handle_error() { + echo "false" +} + +trap 'handle_error' ERR + + +if [[ "$(journalctl -D /var/log/journal -u k3s | grep 'Managed etcd cluster initializing' | grep -v grep | wc -l)" -gt 0 ]]; then + case $1 in + "1.1.11") + echo $(stat -c %a /var/lib/rancher/k3s/server/db/etcd);; + "1.2.29") + echo $(journalctl -D /var/log/journal -u k3s | grep 'Running kube-apiserver' | tail -n1 | grep 'etcd-');; + "2.1") + echo $(grep -A 5 'client-transport-security' /var/lib/rancher/k3s/server/db/etcd/config | grep -E 'cert-file|key-file');; + "2.2") + echo $(grep -A 5 'client-transport-security' /var/lib/rancher/k3s/server/db/etcd/config | grep 'client-cert-auth');; + "2.3") + echo $(grep 'auto-tls' /var/lib/rancher/k3s/server/db/etcd/config);; + "2.4") + echo $(grep -A 5 'peer-transport-security' /var/lib/rancher/k3s/server/db/etcd/config | grep -E 'cert-file|key-file');; + "2.5") + echo $(grep -A 5 'peer-transport-security' /var/lib/rancher/k3s/server/db/etcd/config | grep 'client-cert-auth');; + "2.6") + echo $(grep 'peer-auto-tls' /var/lib/rancher/k3s/server/db/etcd/config);; + "2.7") + echo $(grep 'trusted-ca-file' /var/lib/rancher/k3s/server/db/etcd/config);; + esac +else +# If another database is running, return whatever is required to pass the scan + case $1 in + "1.1.11") + echo "700";; + "1.2.29") + echo "--etcd-certfile AND --etcd-keyfile";; + "2.1") + echo "cert-file AND key-file";; + "2.2") + echo "--client-cert-auth=true";; + "2.3") + echo "false";; + "2.4") + echo "peer-cert-file AND peer-key-file";; + "2.5") + echo "--client-cert-auth=true";; + "2.6") + echo "--peer-auto-tls=false";; + "2.7") + echo "--trusted-ca-file";; + esac +fi + +``` + +**Audit Execution:** + +```bash +./check_for_k3s_etcd.sh 1.1.11 +``` + +**Expected Result**: + +```console +'700' is equal to '700' +``` + +**Returned Value**: + +```console +700 +``` + +### 1.1.12 Ensure that the etcd data directory ownership is set to etcd:etcd (Automated) + + +**Result:** Not Applicable + +**Remediation:** +On the etcd server node, get the etcd data directory, passed as an argument --data-dir, +from the command 'ps -ef | grep etcd'. +Run the below command (based on the etcd data directory found above). +For example, chown etcd:etcd /var/lib/etcd +Not Applicable. + +### 1.1.13 Ensure that the admin.conf file permissions are set to 600 or more restrictive (Automated) + + +**Result:** Not Applicable + +**Remediation:** +Run the below command (based on the file location on your system) on the control plane node. +For example, chmod 600 /var/lib/rancher/k3s/server/cred/admin.kubeconfig + +### 1.1.14 Ensure that the admin.conf file ownership is set to root:root (Automated) + + +**Result:** pass + +**Remediation:** +Run the below command (based on the file location on your system) on the control plane node. +For example, chown root:root /etc/kubernetes/admin.conf + +**Audit:** + +```bash +/bin/sh -c 'if test -e /var/lib/rancher/k3s/server/cred/admin.kubeconfig; then stat -c %U:%G /var/lib/rancher/k3s/server/cred/admin.kubeconfig; fi' +``` + +**Expected Result**: + +```console +'root:root' is equal to 'root:root' +``` + +**Returned Value**: + +```console +root:root +``` + +### 1.1.15 Ensure that the scheduler.conf file permissions are set to 600 or more restrictive (Automated) + + +**Result:** pass + +**Remediation:** +Run the below command (based on the file location on your system) on the control plane node. +For example, +chmod 600 scheduler + +**Audit:** + +```bash +/bin/sh -c 'if test -e /var/lib/rancher/k3s/server/cred/scheduler.kubeconfig; then stat -c permissions=%a /var/lib/rancher/k3s/server/cred/scheduler.kubeconfig; fi' +``` + +**Expected Result**: + +```console +permissions has permissions 600, expected 600 or more restrictive +``` + +**Returned Value**: + +```console +permissions=600 +``` + +### 1.1.16 Ensure that the scheduler.conf file ownership is set to root:root (Automated) + + +**Result:** pass + +**Remediation:** +Run the below command (based on the file location on your system) on the control plane node. +For example, +chown root:root scheduler + +**Audit:** + +```bash +/bin/sh -c 'if test -e /var/lib/rancher/k3s/server/cred/scheduler.kubeconfig; then stat -c %U:%G /var/lib/rancher/k3s/server/cred/scheduler.kubeconfig; fi' +``` + +**Expected Result**: + +```console +'root:root' is present +``` + +**Returned Value**: + +```console +root:root +``` + +### 1.1.17 Ensure that the controller-manager.conf file permissions are set to 600 or more restrictive (Automated) + + +**Result:** pass + +**Remediation:** +Run the below command (based on the file location on your system) on the control plane node. +For example, +chmod 600 controllermanager + +**Audit:** + +```bash +/bin/sh -c 'if test -e /var/lib/rancher/k3s/server/cred/controller.kubeconfig; then stat -c permissions=%a /var/lib/rancher/k3s/server/cred/controller.kubeconfig; fi' +``` + +**Expected Result**: + +```console +permissions has permissions 600, expected 600 or more restrictive +``` + +**Returned Value**: + +```console +permissions=600 +``` + +### 1.1.18 Ensure that the controller-manager.conf file ownership is set to root:root (Automated) + + +**Result:** pass + +**Remediation:** +Run the below command (based on the file location on your system) on the control plane node. +For example, +chown root:root controllermanager + +**Audit:** + +```bash +stat -c %U:%G /var/lib/rancher/k3s/server/cred/controller.kubeconfig +``` + +**Expected Result**: + +```console +'root:root' is equal to 'root:root' +``` + +**Returned Value**: + +```console +root:root +``` + +### 1.1.19 Ensure that the Kubernetes PKI directory and file ownership is set to root:root (Automated) + + +**Result:** pass + +**Remediation:** +Run the below command (based on the file location on your system) on the control plane node. +For example, +chown -R root:root /var/lib/rancher/k3s/server/tls + +**Audit:** + +```bash +stat -c %U:%G /var/lib/rancher/k3s/server/tls +``` + +**Expected Result**: + +```console +'root:root' is present +``` + +**Returned Value**: + +```console +root:root +``` + +### 1.1.20 Ensure that the Kubernetes PKI certificate file permissions are set to 600 or more restrictive (Manual) + + +**Result:** warn + +**Remediation:** +Run the below command (based on the file location on your system) on the control plane node. +For example, +chmod -R 600 /etc/kubernetes/pki/*.crt + +**Audit:** + +```bash +stat -c %n %a /var/lib/rancher/k3s/server/tls/*.crt +``` + +### 1.1.21 Ensure that the Kubernetes PKI key file permissions are set to 600 (Manual) + + +**Result:** warn + +**Remediation:** +Run the below command (based on the file location on your system) on the control plane node. +For example, +chmod -R 600 /etc/kubernetes/pki/*.key + +**Audit:** + +```bash +stat -c %n %a /var/lib/rancher/k3s/server/tls/*.key +``` + +## 1.2 API Server +### 1.2.1 Ensure that the --anonymous-auth argument is set to false (Manual) + + +**Result:** pass + +**Remediation:** +Edit the API server pod specification file /etc/kubernetes/manifests/kube-apiserver.yaml +on the control plane node and set the below parameter. +--anonymous-auth=false + +**Audit:** + +```bash +journalctl -D /var/log/journal -u k3s | grep 'Running kube-apiserver' | tail -n1 | grep 'anonymous-auth' +``` + +**Expected Result**: + +```console +'--anonymous-auth' is equal to 'false' +``` + +**Returned Value**: + +```console +Sep 11 20:52:00 ip-172-31-12-34 k3s[2340]: time="2023-09-11T20:52:00Z" level=info msg="Running kube-apiserver --admission-control-config-file=/etc/rancher/k3s/config/rancher-psact.yaml --advertise-port=6443 --allow-privileged=true --anonymous-auth=false --api-audiences=https://kubernetes.default.svc.cluster.local,k3s --audit-log-maxage=30 --audit-log-maxbackup=10 --audit-log-maxsize=100 --audit-log-path=/var/lib/rancher/k3s/server/logs/audit.log --audit-policy-file=/var/lib/rancher/k3s/server/audit.yaml --authorization-mode=Node,RBAC --bind-address=127.0.0.1 --cert-dir=/var/lib/rancher/k3s/server/tls/temporary-certs --client-ca-file=/var/lib/rancher/k3s/server/tls/client-ca.crt --egress-selector-config-file=/var/lib/rancher/k3s/server/etc/egress-selector-config.yaml --enable-admission-plugins=NodeRestriction,ServiceAccount --enable-aggregator-routing=true --enable-bootstrap-token-auth=true --encryption-provider-config=/var/lib/rancher/k3s/server/cred/encryption-config.json --etcd-cafile=/var/lib/rancher/k3s/server/tls/etcd/server-ca.crt --etcd-certfile=/var/lib/rancher/k3s/server/tls/etcd/client.crt --etcd-keyfile=/var/lib/rancher/k3s/server/tls/etcd/client.key --etcd-servers=https://127.0.0.1:2379 --feature-gates=JobTrackingWithFinalizers=true --kubelet-certificate-authority=/var/lib/rancher/k3s/server/tls/server-ca.crt --kubelet-client-certificate=/var/lib/rancher/k3s/server/tls/client-kube-apiserver.crt --kubelet-client-key=/var/lib/rancher/k3s/server/tls/client-kube-apiserver.key --kubelet-preferred-address-types=InternalIP,ExternalIP,Hostname --profiling=false --proxy-client-cert-file=/var/lib/rancher/k3s/server/tls/client-auth-proxy.crt --proxy-client-key-file=/var/lib/rancher/k3s/server/tls/client-auth-proxy.key --request-timeout=300s --requestheader-allowed-names=system:auth-proxy --requestheader-client-ca-file=/var/lib/rancher/k3s/server/tls/request-header-ca.crt --requestheader-extra-headers-prefix=X-Remote-Extra- --requestheader-group-headers=X-Remote-Group --requestheader-username-headers=X-Remote-User --secure-port=6444 --service-account-issuer=https://kubernetes.default.svc.cluster.local --service-account-key-file=/var/lib/rancher/k3s/server/tls/service.key --service-account-lookup=true --service-account-signing-key-file=/var/lib/rancher/k3s/server/tls/service.current.key --service-cluster-ip-range=10.43.0.0/16 --service-node-port-range=30000-32767 --storage-backend=etcd3 --tls-cert-file=/var/lib/rancher/k3s/server/tls/serving-kube-apiserver.crt --tls-cipher-suites=TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305,TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305 --tls-private-key-file=/var/lib/rancher/k3s/server/tls/serving-kube-apiserver.key" +``` + +### 1.2.2 Ensure that the --token-auth-file parameter is not set (Automated) + + +**Result:** pass + +**Remediation:** +Follow the documentation and configure alternate mechanisms for authentication. Then, +edit the API server pod specification file /etc/kubernetes/manifests/kube-apiserver.yaml +on the control plane node and remove the --token-auth-file= parameter. + +**Audit:** + +```bash +/bin/ps -ef | grep containerd | grep -v grep +``` + +**Expected Result**: + +```console +'--token-auth-file' is not present +``` + +**Returned Value**: + +```console +root 527 1 0 Sep11 ? 00:01:28 /usr/bin/containerd root 663 1 0 Sep11 ? 00:00:08 /usr/bin/dockerd -H fd:// --containerd=/run/containerd/containerd.sock root 2361 2340 3 Sep11 ? 00:40:19 containerd -c /var/lib/rancher/k3s/agent/etc/containerd/config.toml -a /run/k3s/containerd/containerd.sock --state /run/k3s/containerd --root /var/lib/rancher/k3s/agent/containerd root 3021 1 0 Sep11 ? 00:00:29 /var/lib/rancher/k3s/data/3cdacaf539fc388d8e542a8d643948e3c7bfa4a7e91b7521102325e0ce8581b6/bin/containerd-shim-runc-v2 -namespace k8s.io -id 4790d392966915d995e666002c56ed4cce6dd86f305ce2ee390547a1fcbf6c82 -address /run/k3s/containerd/containerd.sock root 3035 1 0 Sep11 ? 00:00:28 /var/lib/rancher/k3s/data/3cdacaf539fc388d8e542a8d643948e3c7bfa4a7e91b7521102325e0ce8581b6/bin/containerd-shim-runc-v2 -namespace k8s.io -id 9d73e6a160ccde6c7c7d4ba0df3b9f696e3de2ebfc0f19a1dcbdf13aea496427 -address /run/k3s/containerd/containerd.sock root 3235 1 0 Sep11 ? 00:00:31 /var/lib/rancher/k3s/data/3cdacaf539fc388d8e542a8d643948e3c7bfa4a7e91b7521102325e0ce8581b6/bin/containerd-shim-runc-v2 -namespace k8s.io -id 587f6221ee9f36c877231ada8d816a799dfda186332c33378d1eb16c72cdc87d -address /run/k3s/containerd/containerd.sock root 4435 1 0 Sep11 ? 00:00:28 /var/lib/rancher/k3s/data/3cdacaf539fc388d8e542a8d643948e3c7bfa4a7e91b7521102325e0ce8581b6/bin/containerd-shim-runc-v2 -namespace k8s.io -id a74c9ec7d99785c2f2d4e6826aa80c22eb8b38249e8f99679ece00a818e9b7b3 -address /run/k3s/containerd/containerd.sock root 4985 1 0 Sep11 ? 00:00:53 /var/lib/rancher/k3s/data/3cdacaf539fc388d8e542a8d643948e3c7bfa4a7e91b7521102325e0ce8581b6/bin/containerd-shim-runc-v2 -namespace k8s.io -id 5b0c9784dbe0fcbe8be10c857976e70ec84a208cb814e87b5ca085a02d434f8c -address /run/k3s/containerd/containerd.sock root 5056 1 0 Sep11 ? 00:00:28 /var/lib/rancher/k3s/data/3cdacaf539fc388d8e542a8d643948e3c7bfa4a7e91b7521102325e0ce8581b6/bin/containerd-shim-runc-v2 -namespace k8s.io -id f3231ff35f18056e74eda14907f296be15f7ea1c6ae5ab7904e27d4d18183301 -address /run/k3s/containerd/containerd.sock root 5868 1 0 Sep11 ? 00:00:27 /var/lib/rancher/k3s/data/3cdacaf539fc388d8e542a8d643948e3c7bfa4a7e91b7521102325e0ce8581b6/bin/containerd-shim-runc-v2 -namespace k8s.io -id 3e908c4d0b10df275bdef6f72fbcfa09517d11cf749236ad020364e14d77bc93 -address /run/k3s/containerd/containerd.sock root 6158 1 0 Sep11 ? 00:00:28 /var/lib/rancher/k3s/data/3cdacaf539fc388d8e542a8d643948e3c7bfa4a7e91b7521102325e0ce8581b6/bin/containerd-shim-runc-v2 -namespace k8s.io -id bec5780a5c73fa3154aa3b5ee26cdf23202db821205893e7e66ae17e6103e97b -address /run/k3s/containerd/containerd.sock root 7366 1 0 Sep11 ? 00:00:28 /var/lib/rancher/k3s/data/3cdacaf539fc388d8e542a8d643948e3c7bfa4a7e91b7521102325e0ce8581b6/bin/containerd-shim-runc-v2 -namespace k8s.io -id a81b78845bdcaef710314c93e5ea0d0617f37a8929472f7b570ab90c6667f57f -address /run/k3s/containerd/containerd.sock root 97274 1 0 16:13 ? 00:00:00 /var/lib/rancher/k3s/data/3cdacaf539fc388d8e542a8d643948e3c7bfa4a7e91b7521102325e0ce8581b6/bin/containerd-shim-runc-v2 -namespace k8s.io -id c90652c935d9e79af45b9a9ac2b4fe315e2a761a0525737fdb95c680123a164c -address /run/k3s/containerd/containerd.sock root 98309 1 0 16:16 ? 00:00:00 /var/lib/rancher/k3s/data/3cdacaf539fc388d8e542a8d643948e3c7bfa4a7e91b7521102325e0ce8581b6/bin/containerd-shim-runc-v2 -namespace k8s.io -id 431a2763636488efd7d104c228d41f4f2ecd8c06a7fc375d8977ab0d238936a8 -address /run/k3s/containerd/containerd.sock root 98493 1 0 16:16 ? 00:00:00 /var/lib/rancher/k3s/data/3cdacaf539fc388d8e542a8d643948e3c7bfa4a7e91b7521102325e0ce8581b6/bin/containerd-shim-runc-v2 -namespace k8s.io -id 5b480d2fa55c8cc0105ec1902887040c017f03d5b1eb6c73c24bb9d523ad9b37 -address /run/k3s/containerd/containerd.sock +``` + +### 1.2.3 Ensure that the --DenyServiceExternalIPs is not set (Automated) + + +**Result:** pass + +**Remediation:** +Edit the API server pod specification file /etc/kubernetes/manifests/kube-apiserver.yaml +on the control plane node and remove the `DenyServiceExternalIPs` +from enabled admission plugins. + +**Audit:** + +```bash +/bin/ps -ef | grep containerd | grep -v grep +``` + +**Expected Result**: + +```console +'--enable-admission-plugins' is present OR '--enable-admission-plugins' is not present +``` + +**Returned Value**: + +```console +root 527 1 0 Sep11 ? 00:01:28 /usr/bin/containerd root 663 1 0 Sep11 ? 00:00:08 /usr/bin/dockerd -H fd:// --containerd=/run/containerd/containerd.sock root 2361 2340 3 Sep11 ? 00:40:19 containerd -c /var/lib/rancher/k3s/agent/etc/containerd/config.toml -a /run/k3s/containerd/containerd.sock --state /run/k3s/containerd --root /var/lib/rancher/k3s/agent/containerd root 3021 1 0 Sep11 ? 00:00:29 /var/lib/rancher/k3s/data/3cdacaf539fc388d8e542a8d643948e3c7bfa4a7e91b7521102325e0ce8581b6/bin/containerd-shim-runc-v2 -namespace k8s.io -id 4790d392966915d995e666002c56ed4cce6dd86f305ce2ee390547a1fcbf6c82 -address /run/k3s/containerd/containerd.sock root 3035 1 0 Sep11 ? 00:00:28 /var/lib/rancher/k3s/data/3cdacaf539fc388d8e542a8d643948e3c7bfa4a7e91b7521102325e0ce8581b6/bin/containerd-shim-runc-v2 -namespace k8s.io -id 9d73e6a160ccde6c7c7d4ba0df3b9f696e3de2ebfc0f19a1dcbdf13aea496427 -address /run/k3s/containerd/containerd.sock root 3235 1 0 Sep11 ? 00:00:31 /var/lib/rancher/k3s/data/3cdacaf539fc388d8e542a8d643948e3c7bfa4a7e91b7521102325e0ce8581b6/bin/containerd-shim-runc-v2 -namespace k8s.io -id 587f6221ee9f36c877231ada8d816a799dfda186332c33378d1eb16c72cdc87d -address /run/k3s/containerd/containerd.sock root 4435 1 0 Sep11 ? 00:00:28 /var/lib/rancher/k3s/data/3cdacaf539fc388d8e542a8d643948e3c7bfa4a7e91b7521102325e0ce8581b6/bin/containerd-shim-runc-v2 -namespace k8s.io -id a74c9ec7d99785c2f2d4e6826aa80c22eb8b38249e8f99679ece00a818e9b7b3 -address /run/k3s/containerd/containerd.sock root 4985 1 0 Sep11 ? 00:00:53 /var/lib/rancher/k3s/data/3cdacaf539fc388d8e542a8d643948e3c7bfa4a7e91b7521102325e0ce8581b6/bin/containerd-shim-runc-v2 -namespace k8s.io -id 5b0c9784dbe0fcbe8be10c857976e70ec84a208cb814e87b5ca085a02d434f8c -address /run/k3s/containerd/containerd.sock root 5056 1 0 Sep11 ? 00:00:28 /var/lib/rancher/k3s/data/3cdacaf539fc388d8e542a8d643948e3c7bfa4a7e91b7521102325e0ce8581b6/bin/containerd-shim-runc-v2 -namespace k8s.io -id f3231ff35f18056e74eda14907f296be15f7ea1c6ae5ab7904e27d4d18183301 -address /run/k3s/containerd/containerd.sock root 5868 1 0 Sep11 ? 00:00:27 /var/lib/rancher/k3s/data/3cdacaf539fc388d8e542a8d643948e3c7bfa4a7e91b7521102325e0ce8581b6/bin/containerd-shim-runc-v2 -namespace k8s.io -id 3e908c4d0b10df275bdef6f72fbcfa09517d11cf749236ad020364e14d77bc93 -address /run/k3s/containerd/containerd.sock root 6158 1 0 Sep11 ? 00:00:28 /var/lib/rancher/k3s/data/3cdacaf539fc388d8e542a8d643948e3c7bfa4a7e91b7521102325e0ce8581b6/bin/containerd-shim-runc-v2 -namespace k8s.io -id bec5780a5c73fa3154aa3b5ee26cdf23202db821205893e7e66ae17e6103e97b -address /run/k3s/containerd/containerd.sock root 7366 1 0 Sep11 ? 00:00:28 /var/lib/rancher/k3s/data/3cdacaf539fc388d8e542a8d643948e3c7bfa4a7e91b7521102325e0ce8581b6/bin/containerd-shim-runc-v2 -namespace k8s.io -id a81b78845bdcaef710314c93e5ea0d0617f37a8929472f7b570ab90c6667f57f -address /run/k3s/containerd/containerd.sock root 97274 1 0 16:13 ? 00:00:00 /var/lib/rancher/k3s/data/3cdacaf539fc388d8e542a8d643948e3c7bfa4a7e91b7521102325e0ce8581b6/bin/containerd-shim-runc-v2 -namespace k8s.io -id c90652c935d9e79af45b9a9ac2b4fe315e2a761a0525737fdb95c680123a164c -address /run/k3s/containerd/containerd.sock root 98309 1 0 16:16 ? 00:00:00 /var/lib/rancher/k3s/data/3cdacaf539fc388d8e542a8d643948e3c7bfa4a7e91b7521102325e0ce8581b6/bin/containerd-shim-runc-v2 -namespace k8s.io -id 431a2763636488efd7d104c228d41f4f2ecd8c06a7fc375d8977ab0d238936a8 -address /run/k3s/containerd/containerd.sock root 98493 1 0 16:16 ? 00:00:00 /var/lib/rancher/k3s/data/3cdacaf539fc388d8e542a8d643948e3c7bfa4a7e91b7521102325e0ce8581b6/bin/containerd-shim-runc-v2 -namespace k8s.io -id 5b480d2fa55c8cc0105ec1902887040c017f03d5b1eb6c73c24bb9d523ad9b37 -address /run/k3s/containerd/containerd.sock +``` + +### 1.2.4 Ensure that the --kubelet-client-certificate and --kubelet-client-key arguments are set as appropriate (Automated) + + +**Result:** pass + +**Remediation:** +Follow the Kubernetes documentation and set up the TLS connection between the +apiserver and kubelets. Then, edit API server pod specification file +/etc/kubernetes/manifests/kube-apiserver.yaml on the control plane node and set the +kubelet client certificate and key parameters as below. +--kubelet-client-certificate= +--kubelet-client-key= + +**Audit:** + +```bash +journalctl -D /var/log/journal -u k3s | grep 'Running kube-apiserver' | tail -n1 | grep 'kubelet-certificate-authority' +``` + +**Expected Result**: + +```console +'--kubelet-client-certificate' is present AND '--kubelet-client-key' is present +``` + +**Returned Value**: + +```console +Sep 11 20:52:00 ip-172-31-12-34 k3s[2340]: time="2023-09-11T20:52:00Z" level=info msg="Running kube-apiserver --admission-control-config-file=/etc/rancher/k3s/config/rancher-psact.yaml --advertise-port=6443 --allow-privileged=true --anonymous-auth=false --api-audiences=https://kubernetes.default.svc.cluster.local,k3s --audit-log-maxage=30 --audit-log-maxbackup=10 --audit-log-maxsize=100 --audit-log-path=/var/lib/rancher/k3s/server/logs/audit.log --audit-policy-file=/var/lib/rancher/k3s/server/audit.yaml --authorization-mode=Node,RBAC --bind-address=127.0.0.1 --cert-dir=/var/lib/rancher/k3s/server/tls/temporary-certs --client-ca-file=/var/lib/rancher/k3s/server/tls/client-ca.crt --egress-selector-config-file=/var/lib/rancher/k3s/server/etc/egress-selector-config.yaml --enable-admission-plugins=NodeRestriction,ServiceAccount --enable-aggregator-routing=true --enable-bootstrap-token-auth=true --encryption-provider-config=/var/lib/rancher/k3s/server/cred/encryption-config.json --etcd-cafile=/var/lib/rancher/k3s/server/tls/etcd/server-ca.crt --etcd-certfile=/var/lib/rancher/k3s/server/tls/etcd/client.crt --etcd-keyfile=/var/lib/rancher/k3s/server/tls/etcd/client.key --etcd-servers=https://127.0.0.1:2379 --feature-gates=JobTrackingWithFinalizers=true --kubelet-certificate-authority=/var/lib/rancher/k3s/server/tls/server-ca.crt --kubelet-client-certificate=/var/lib/rancher/k3s/server/tls/client-kube-apiserver.crt --kubelet-client-key=/var/lib/rancher/k3s/server/tls/client-kube-apiserver.key --kubelet-preferred-address-types=InternalIP,ExternalIP,Hostname --profiling=false --proxy-client-cert-file=/var/lib/rancher/k3s/server/tls/client-auth-proxy.crt --proxy-client-key-file=/var/lib/rancher/k3s/server/tls/client-auth-proxy.key --request-timeout=300s --requestheader-allowed-names=system:auth-proxy --requestheader-client-ca-file=/var/lib/rancher/k3s/server/tls/request-header-ca.crt --requestheader-extra-headers-prefix=X-Remote-Extra- --requestheader-group-headers=X-Remote-Group --requestheader-username-headers=X-Remote-User --secure-port=6444 --service-account-issuer=https://kubernetes.default.svc.cluster.local --service-account-key-file=/var/lib/rancher/k3s/server/tls/service.key --service-account-lookup=true --service-account-signing-key-file=/var/lib/rancher/k3s/server/tls/service.current.key --service-cluster-ip-range=10.43.0.0/16 --service-node-port-range=30000-32767 --storage-backend=etcd3 --tls-cert-file=/var/lib/rancher/k3s/server/tls/serving-kube-apiserver.crt --tls-cipher-suites=TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305,TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305 --tls-private-key-file=/var/lib/rancher/k3s/server/tls/serving-kube-apiserver.key" +``` + +### 1.2.5 Ensure that the --kubelet-certificate-authority argument is set as appropriate (Automated) + + +**Result:** Not Applicable + +**Remediation:** +Follow the Kubernetes documentation and setup the TLS connection between +the apiserver and kubelets. Then, edit the API server pod specification file +/etc/kubernetes/manifests/kube-apiserver.yaml on the control plane node and set the +--kubelet-certificate-authority parameter to the path to the cert file for the certificate authority. +--kubelet-certificate-authority= +Permissive - When generating serving certificates, functionality could break in conjunction with hostname overrides which are required for certain cloud providers. + +### 1.2.6 Ensure that the --authorization-mode argument is not set to AlwaysAllow (Automated) + + +**Result:** pass + +**Remediation:** +Edit the API server pod specification file /etc/kubernetes/manifests/kube-apiserver.yaml +on the control plane node and set the --authorization-mode parameter to values other than AlwaysAllow. +One such example could be as below. +--authorization-mode=RBAC + +**Audit:** + +```bash +journalctl -D /var/log/journal -u k3s | grep 'Running kube-apiserver' | tail -n1 | grep 'authorization-mode' +``` + +**Expected Result**: + +```console +'--authorization-mode' does not have 'AlwaysAllow' +``` + +**Returned Value**: + +```console +Sep 11 20:52:00 ip-172-31-12-34 k3s[2340]: time="2023-09-11T20:52:00Z" level=info msg="Running kube-apiserver --admission-control-config-file=/etc/rancher/k3s/config/rancher-psact.yaml --advertise-port=6443 --allow-privileged=true --anonymous-auth=false --api-audiences=https://kubernetes.default.svc.cluster.local,k3s --audit-log-maxage=30 --audit-log-maxbackup=10 --audit-log-maxsize=100 --audit-log-path=/var/lib/rancher/k3s/server/logs/audit.log --audit-policy-file=/var/lib/rancher/k3s/server/audit.yaml --authorization-mode=Node,RBAC --bind-address=127.0.0.1 --cert-dir=/var/lib/rancher/k3s/server/tls/temporary-certs --client-ca-file=/var/lib/rancher/k3s/server/tls/client-ca.crt --egress-selector-config-file=/var/lib/rancher/k3s/server/etc/egress-selector-config.yaml --enable-admission-plugins=NodeRestriction,ServiceAccount --enable-aggregator-routing=true --enable-bootstrap-token-auth=true --encryption-provider-config=/var/lib/rancher/k3s/server/cred/encryption-config.json --etcd-cafile=/var/lib/rancher/k3s/server/tls/etcd/server-ca.crt --etcd-certfile=/var/lib/rancher/k3s/server/tls/etcd/client.crt --etcd-keyfile=/var/lib/rancher/k3s/server/tls/etcd/client.key --etcd-servers=https://127.0.0.1:2379 --feature-gates=JobTrackingWithFinalizers=true --kubelet-certificate-authority=/var/lib/rancher/k3s/server/tls/server-ca.crt --kubelet-client-certificate=/var/lib/rancher/k3s/server/tls/client-kube-apiserver.crt --kubelet-client-key=/var/lib/rancher/k3s/server/tls/client-kube-apiserver.key --kubelet-preferred-address-types=InternalIP,ExternalIP,Hostname --profiling=false --proxy-client-cert-file=/var/lib/rancher/k3s/server/tls/client-auth-proxy.crt --proxy-client-key-file=/var/lib/rancher/k3s/server/tls/client-auth-proxy.key --request-timeout=300s --requestheader-allowed-names=system:auth-proxy --requestheader-client-ca-file=/var/lib/rancher/k3s/server/tls/request-header-ca.crt --requestheader-extra-headers-prefix=X-Remote-Extra- --requestheader-group-headers=X-Remote-Group --requestheader-username-headers=X-Remote-User --secure-port=6444 --service-account-issuer=https://kubernetes.default.svc.cluster.local --service-account-key-file=/var/lib/rancher/k3s/server/tls/service.key --service-account-lookup=true --service-account-signing-key-file=/var/lib/rancher/k3s/server/tls/service.current.key --service-cluster-ip-range=10.43.0.0/16 --service-node-port-range=30000-32767 --storage-backend=etcd3 --tls-cert-file=/var/lib/rancher/k3s/server/tls/serving-kube-apiserver.crt --tls-cipher-suites=TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305,TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305 --tls-private-key-file=/var/lib/rancher/k3s/server/tls/serving-kube-apiserver.key" +``` + +### 1.2.7 Ensure that the --authorization-mode argument includes Node (Automated) + + +**Result:** pass + +**Remediation:** +Edit the API server pod specification file /etc/kubernetes/manifests/kube-apiserver.yaml +on the control plane node and set the --authorization-mode parameter to a value that includes Node. +--authorization-mode=Node,RBAC + +**Audit:** + +```bash +journalctl -D /var/log/journal -u k3s | grep 'Running kube-apiserver' | tail -n1 | grep 'authorization-mode' +``` + +**Expected Result**: + +```console +'--authorization-mode' has 'Node' +``` + +**Returned Value**: + +```console +Sep 11 20:52:00 ip-172-31-12-34 k3s[2340]: time="2023-09-11T20:52:00Z" level=info msg="Running kube-apiserver --admission-control-config-file=/etc/rancher/k3s/config/rancher-psact.yaml --advertise-port=6443 --allow-privileged=true --anonymous-auth=false --api-audiences=https://kubernetes.default.svc.cluster.local,k3s --audit-log-maxage=30 --audit-log-maxbackup=10 --audit-log-maxsize=100 --audit-log-path=/var/lib/rancher/k3s/server/logs/audit.log --audit-policy-file=/var/lib/rancher/k3s/server/audit.yaml --authorization-mode=Node,RBAC --bind-address=127.0.0.1 --cert-dir=/var/lib/rancher/k3s/server/tls/temporary-certs --client-ca-file=/var/lib/rancher/k3s/server/tls/client-ca.crt --egress-selector-config-file=/var/lib/rancher/k3s/server/etc/egress-selector-config.yaml --enable-admission-plugins=NodeRestriction,ServiceAccount --enable-aggregator-routing=true --enable-bootstrap-token-auth=true --encryption-provider-config=/var/lib/rancher/k3s/server/cred/encryption-config.json --etcd-cafile=/var/lib/rancher/k3s/server/tls/etcd/server-ca.crt --etcd-certfile=/var/lib/rancher/k3s/server/tls/etcd/client.crt --etcd-keyfile=/var/lib/rancher/k3s/server/tls/etcd/client.key --etcd-servers=https://127.0.0.1:2379 --feature-gates=JobTrackingWithFinalizers=true --kubelet-certificate-authority=/var/lib/rancher/k3s/server/tls/server-ca.crt --kubelet-client-certificate=/var/lib/rancher/k3s/server/tls/client-kube-apiserver.crt --kubelet-client-key=/var/lib/rancher/k3s/server/tls/client-kube-apiserver.key --kubelet-preferred-address-types=InternalIP,ExternalIP,Hostname --profiling=false --proxy-client-cert-file=/var/lib/rancher/k3s/server/tls/client-auth-proxy.crt --proxy-client-key-file=/var/lib/rancher/k3s/server/tls/client-auth-proxy.key --request-timeout=300s --requestheader-allowed-names=system:auth-proxy --requestheader-client-ca-file=/var/lib/rancher/k3s/server/tls/request-header-ca.crt --requestheader-extra-headers-prefix=X-Remote-Extra- --requestheader-group-headers=X-Remote-Group --requestheader-username-headers=X-Remote-User --secure-port=6444 --service-account-issuer=https://kubernetes.default.svc.cluster.local --service-account-key-file=/var/lib/rancher/k3s/server/tls/service.key --service-account-lookup=true --service-account-signing-key-file=/var/lib/rancher/k3s/server/tls/service.current.key --service-cluster-ip-range=10.43.0.0/16 --service-node-port-range=30000-32767 --storage-backend=etcd3 --tls-cert-file=/var/lib/rancher/k3s/server/tls/serving-kube-apiserver.crt --tls-cipher-suites=TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305,TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305 --tls-private-key-file=/var/lib/rancher/k3s/server/tls/serving-kube-apiserver.key" +``` + +### 1.2.8 Ensure that the --authorization-mode argument includes RBAC (Automated) + + +**Result:** pass + +**Remediation:** +Edit the API server pod specification file /etc/kubernetes/manifests/kube-apiserver.yaml +on the control plane node and set the --authorization-mode parameter to a value that includes RBAC, +for example `--authorization-mode=Node,RBAC`. + +**Audit:** + +```bash +journalctl -D /var/log/journal -u k3s | grep 'Running kube-apiserver' | tail -n1 | grep 'authorization-mode' +``` + +**Expected Result**: + +```console +'--authorization-mode' has 'RBAC' +``` + +**Returned Value**: + +```console +Sep 11 20:52:00 ip-172-31-12-34 k3s[2340]: time="2023-09-11T20:52:00Z" level=info msg="Running kube-apiserver --admission-control-config-file=/etc/rancher/k3s/config/rancher-psact.yaml --advertise-port=6443 --allow-privileged=true --anonymous-auth=false --api-audiences=https://kubernetes.default.svc.cluster.local,k3s --audit-log-maxage=30 --audit-log-maxbackup=10 --audit-log-maxsize=100 --audit-log-path=/var/lib/rancher/k3s/server/logs/audit.log --audit-policy-file=/var/lib/rancher/k3s/server/audit.yaml --authorization-mode=Node,RBAC --bind-address=127.0.0.1 --cert-dir=/var/lib/rancher/k3s/server/tls/temporary-certs --client-ca-file=/var/lib/rancher/k3s/server/tls/client-ca.crt --egress-selector-config-file=/var/lib/rancher/k3s/server/etc/egress-selector-config.yaml --enable-admission-plugins=NodeRestriction,ServiceAccount --enable-aggregator-routing=true --enable-bootstrap-token-auth=true --encryption-provider-config=/var/lib/rancher/k3s/server/cred/encryption-config.json --etcd-cafile=/var/lib/rancher/k3s/server/tls/etcd/server-ca.crt --etcd-certfile=/var/lib/rancher/k3s/server/tls/etcd/client.crt --etcd-keyfile=/var/lib/rancher/k3s/server/tls/etcd/client.key --etcd-servers=https://127.0.0.1:2379 --feature-gates=JobTrackingWithFinalizers=true --kubelet-certificate-authority=/var/lib/rancher/k3s/server/tls/server-ca.crt --kubelet-client-certificate=/var/lib/rancher/k3s/server/tls/client-kube-apiserver.crt --kubelet-client-key=/var/lib/rancher/k3s/server/tls/client-kube-apiserver.key --kubelet-preferred-address-types=InternalIP,ExternalIP,Hostname --profiling=false --proxy-client-cert-file=/var/lib/rancher/k3s/server/tls/client-auth-proxy.crt --proxy-client-key-file=/var/lib/rancher/k3s/server/tls/client-auth-proxy.key --request-timeout=300s --requestheader-allowed-names=system:auth-proxy --requestheader-client-ca-file=/var/lib/rancher/k3s/server/tls/request-header-ca.crt --requestheader-extra-headers-prefix=X-Remote-Extra- --requestheader-group-headers=X-Remote-Group --requestheader-username-headers=X-Remote-User --secure-port=6444 --service-account-issuer=https://kubernetes.default.svc.cluster.local --service-account-key-file=/var/lib/rancher/k3s/server/tls/service.key --service-account-lookup=true --service-account-signing-key-file=/var/lib/rancher/k3s/server/tls/service.current.key --service-cluster-ip-range=10.43.0.0/16 --service-node-port-range=30000-32767 --storage-backend=etcd3 --tls-cert-file=/var/lib/rancher/k3s/server/tls/serving-kube-apiserver.crt --tls-cipher-suites=TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305,TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305 --tls-private-key-file=/var/lib/rancher/k3s/server/tls/serving-kube-apiserver.key" +``` + +### 1.2.9 Ensure that the admission control plugin EventRateLimit is set (Manual) + + +**Result:** warn + +**Remediation:** +Follow the Kubernetes documentation and set the desired limits in a configuration file. +Then, edit the API server pod specification file /etc/kubernetes/manifests/kube-apiserver.yaml +and set the below parameters. +--enable-admission-plugins=...,EventRateLimit,... +--admission-control-config-file= + +**Audit:** + +```bash +journalctl -D /var/log/journal -u k3s | grep 'Running kube-apiserver' | tail -n1 | grep 'enable-admission-plugins' +``` + +**Expected Result**: + +```console +'--enable-admission-plugins' has 'EventRateLimit' +``` + +**Returned Value**: + +```console +Sep 11 20:52:00 ip-172-31-12-34 k3s[2340]: time="2023-09-11T20:52:00Z" level=info msg="Running kube-apiserver --admission-control-config-file=/etc/rancher/k3s/config/rancher-psact.yaml --advertise-port=6443 --allow-privileged=true --anonymous-auth=false --api-audiences=https://kubernetes.default.svc.cluster.local,k3s --audit-log-maxage=30 --audit-log-maxbackup=10 --audit-log-maxsize=100 --audit-log-path=/var/lib/rancher/k3s/server/logs/audit.log --audit-policy-file=/var/lib/rancher/k3s/server/audit.yaml --authorization-mode=Node,RBAC --bind-address=127.0.0.1 --cert-dir=/var/lib/rancher/k3s/server/tls/temporary-certs --client-ca-file=/var/lib/rancher/k3s/server/tls/client-ca.crt --egress-selector-config-file=/var/lib/rancher/k3s/server/etc/egress-selector-config.yaml --enable-admission-plugins=NodeRestriction,ServiceAccount --enable-aggregator-routing=true --enable-bootstrap-token-auth=true --encryption-provider-config=/var/lib/rancher/k3s/server/cred/encryption-config.json --etcd-cafile=/var/lib/rancher/k3s/server/tls/etcd/server-ca.crt --etcd-certfile=/var/lib/rancher/k3s/server/tls/etcd/client.crt --etcd-keyfile=/var/lib/rancher/k3s/server/tls/etcd/client.key --etcd-servers=https://127.0.0.1:2379 --feature-gates=JobTrackingWithFinalizers=true --kubelet-certificate-authority=/var/lib/rancher/k3s/server/tls/server-ca.crt --kubelet-client-certificate=/var/lib/rancher/k3s/server/tls/client-kube-apiserver.crt --kubelet-client-key=/var/lib/rancher/k3s/server/tls/client-kube-apiserver.key --kubelet-preferred-address-types=InternalIP,ExternalIP,Hostname --profiling=false --proxy-client-cert-file=/var/lib/rancher/k3s/server/tls/client-auth-proxy.crt --proxy-client-key-file=/var/lib/rancher/k3s/server/tls/client-auth-proxy.key --request-timeout=300s --requestheader-allowed-names=system:auth-proxy --requestheader-client-ca-file=/var/lib/rancher/k3s/server/tls/request-header-ca.crt --requestheader-extra-headers-prefix=X-Remote-Extra- --requestheader-group-headers=X-Remote-Group --requestheader-username-headers=X-Remote-User --secure-port=6444 --service-account-issuer=https://kubernetes.default.svc.cluster.local --service-account-key-file=/var/lib/rancher/k3s/server/tls/service.key --service-account-lookup=true --service-account-signing-key-file=/var/lib/rancher/k3s/server/tls/service.current.key --service-cluster-ip-range=10.43.0.0/16 --service-node-port-range=30000-32767 --storage-backend=etcd3 --tls-cert-file=/var/lib/rancher/k3s/server/tls/serving-kube-apiserver.crt --tls-cipher-suites=TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305,TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305 --tls-private-key-file=/var/lib/rancher/k3s/server/tls/serving-kube-apiserver.key" +``` + +### 1.2.10 Ensure that the admission control plugin AlwaysAdmit is not set (Automated) + + +**Result:** pass + +**Remediation:** +Edit the API server pod specification file /etc/kubernetes/manifests/kube-apiserver.yaml +on the control plane node and either remove the --enable-admission-plugins parameter, or set it to a +value that does not include AlwaysAdmit. + +**Audit:** + +```bash +journalctl -D /var/log/journal -u k3s | grep 'Running kube-apiserver' | tail -n1 | grep 'enable-admission-plugins' +``` + +**Expected Result**: + +```console +'--enable-admission-plugins' does not have 'AlwaysAdmit' OR '--enable-admission-plugins' is not present +``` + +**Returned Value**: + +```console +Sep 11 20:52:00 ip-172-31-12-34 k3s[2340]: time="2023-09-11T20:52:00Z" level=info msg="Running kube-apiserver --admission-control-config-file=/etc/rancher/k3s/config/rancher-psact.yaml --advertise-port=6443 --allow-privileged=true --anonymous-auth=false --api-audiences=https://kubernetes.default.svc.cluster.local,k3s --audit-log-maxage=30 --audit-log-maxbackup=10 --audit-log-maxsize=100 --audit-log-path=/var/lib/rancher/k3s/server/logs/audit.log --audit-policy-file=/var/lib/rancher/k3s/server/audit.yaml --authorization-mode=Node,RBAC --bind-address=127.0.0.1 --cert-dir=/var/lib/rancher/k3s/server/tls/temporary-certs --client-ca-file=/var/lib/rancher/k3s/server/tls/client-ca.crt --egress-selector-config-file=/var/lib/rancher/k3s/server/etc/egress-selector-config.yaml --enable-admission-plugins=NodeRestriction,ServiceAccount --enable-aggregator-routing=true --enable-bootstrap-token-auth=true --encryption-provider-config=/var/lib/rancher/k3s/server/cred/encryption-config.json --etcd-cafile=/var/lib/rancher/k3s/server/tls/etcd/server-ca.crt --etcd-certfile=/var/lib/rancher/k3s/server/tls/etcd/client.crt --etcd-keyfile=/var/lib/rancher/k3s/server/tls/etcd/client.key --etcd-servers=https://127.0.0.1:2379 --feature-gates=JobTrackingWithFinalizers=true --kubelet-certificate-authority=/var/lib/rancher/k3s/server/tls/server-ca.crt --kubelet-client-certificate=/var/lib/rancher/k3s/server/tls/client-kube-apiserver.crt --kubelet-client-key=/var/lib/rancher/k3s/server/tls/client-kube-apiserver.key --kubelet-preferred-address-types=InternalIP,ExternalIP,Hostname --profiling=false --proxy-client-cert-file=/var/lib/rancher/k3s/server/tls/client-auth-proxy.crt --proxy-client-key-file=/var/lib/rancher/k3s/server/tls/client-auth-proxy.key --request-timeout=300s --requestheader-allowed-names=system:auth-proxy --requestheader-client-ca-file=/var/lib/rancher/k3s/server/tls/request-header-ca.crt --requestheader-extra-headers-prefix=X-Remote-Extra- --requestheader-group-headers=X-Remote-Group --requestheader-username-headers=X-Remote-User --secure-port=6444 --service-account-issuer=https://kubernetes.default.svc.cluster.local --service-account-key-file=/var/lib/rancher/k3s/server/tls/service.key --service-account-lookup=true --service-account-signing-key-file=/var/lib/rancher/k3s/server/tls/service.current.key --service-cluster-ip-range=10.43.0.0/16 --service-node-port-range=30000-32767 --storage-backend=etcd3 --tls-cert-file=/var/lib/rancher/k3s/server/tls/serving-kube-apiserver.crt --tls-cipher-suites=TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305,TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305 --tls-private-key-file=/var/lib/rancher/k3s/server/tls/serving-kube-apiserver.key" +``` + +### 1.2.11 Ensure that the admission control plugin AlwaysPullImages is set (Manual) + + +**Result:** warn + +**Remediation:** +Edit the API server pod specification file /etc/kubernetes/manifests/kube-apiserver.yaml +on the control plane node and set the --enable-admission-plugins parameter to include +AlwaysPullImages. +--enable-admission-plugins=...,AlwaysPullImages,... + +**Audit:** + +```bash +/bin/ps -ef | grep containerd | grep -v grep +``` + +**Expected Result**: + +```console +'--enable-admission-plugins' is present +``` + +**Returned Value**: + +```console +root 527 1 0 Sep11 ? 00:01:28 /usr/bin/containerd root 663 1 0 Sep11 ? 00:00:08 /usr/bin/dockerd -H fd:// --containerd=/run/containerd/containerd.sock root 2361 2340 3 Sep11 ? 00:40:19 containerd -c /var/lib/rancher/k3s/agent/etc/containerd/config.toml -a /run/k3s/containerd/containerd.sock --state /run/k3s/containerd --root /var/lib/rancher/k3s/agent/containerd root 3021 1 0 Sep11 ? 00:00:29 /var/lib/rancher/k3s/data/3cdacaf539fc388d8e542a8d643948e3c7bfa4a7e91b7521102325e0ce8581b6/bin/containerd-shim-runc-v2 -namespace k8s.io -id 4790d392966915d995e666002c56ed4cce6dd86f305ce2ee390547a1fcbf6c82 -address /run/k3s/containerd/containerd.sock root 3035 1 0 Sep11 ? 00:00:28 /var/lib/rancher/k3s/data/3cdacaf539fc388d8e542a8d643948e3c7bfa4a7e91b7521102325e0ce8581b6/bin/containerd-shim-runc-v2 -namespace k8s.io -id 9d73e6a160ccde6c7c7d4ba0df3b9f696e3de2ebfc0f19a1dcbdf13aea496427 -address /run/k3s/containerd/containerd.sock root 3235 1 0 Sep11 ? 00:00:31 /var/lib/rancher/k3s/data/3cdacaf539fc388d8e542a8d643948e3c7bfa4a7e91b7521102325e0ce8581b6/bin/containerd-shim-runc-v2 -namespace k8s.io -id 587f6221ee9f36c877231ada8d816a799dfda186332c33378d1eb16c72cdc87d -address /run/k3s/containerd/containerd.sock root 4435 1 0 Sep11 ? 00:00:28 /var/lib/rancher/k3s/data/3cdacaf539fc388d8e542a8d643948e3c7bfa4a7e91b7521102325e0ce8581b6/bin/containerd-shim-runc-v2 -namespace k8s.io -id a74c9ec7d99785c2f2d4e6826aa80c22eb8b38249e8f99679ece00a818e9b7b3 -address /run/k3s/containerd/containerd.sock root 4985 1 0 Sep11 ? 00:00:53 /var/lib/rancher/k3s/data/3cdacaf539fc388d8e542a8d643948e3c7bfa4a7e91b7521102325e0ce8581b6/bin/containerd-shim-runc-v2 -namespace k8s.io -id 5b0c9784dbe0fcbe8be10c857976e70ec84a208cb814e87b5ca085a02d434f8c -address /run/k3s/containerd/containerd.sock root 5056 1 0 Sep11 ? 00:00:28 /var/lib/rancher/k3s/data/3cdacaf539fc388d8e542a8d643948e3c7bfa4a7e91b7521102325e0ce8581b6/bin/containerd-shim-runc-v2 -namespace k8s.io -id f3231ff35f18056e74eda14907f296be15f7ea1c6ae5ab7904e27d4d18183301 -address /run/k3s/containerd/containerd.sock root 5868 1 0 Sep11 ? 00:00:27 /var/lib/rancher/k3s/data/3cdacaf539fc388d8e542a8d643948e3c7bfa4a7e91b7521102325e0ce8581b6/bin/containerd-shim-runc-v2 -namespace k8s.io -id 3e908c4d0b10df275bdef6f72fbcfa09517d11cf749236ad020364e14d77bc93 -address /run/k3s/containerd/containerd.sock root 6158 1 0 Sep11 ? 00:00:28 /var/lib/rancher/k3s/data/3cdacaf539fc388d8e542a8d643948e3c7bfa4a7e91b7521102325e0ce8581b6/bin/containerd-shim-runc-v2 -namespace k8s.io -id bec5780a5c73fa3154aa3b5ee26cdf23202db821205893e7e66ae17e6103e97b -address /run/k3s/containerd/containerd.sock root 7366 1 0 Sep11 ? 00:00:28 /var/lib/rancher/k3s/data/3cdacaf539fc388d8e542a8d643948e3c7bfa4a7e91b7521102325e0ce8581b6/bin/containerd-shim-runc-v2 -namespace k8s.io -id a81b78845bdcaef710314c93e5ea0d0617f37a8929472f7b570ab90c6667f57f -address /run/k3s/containerd/containerd.sock root 97274 1 0 16:13 ? 00:00:00 /var/lib/rancher/k3s/data/3cdacaf539fc388d8e542a8d643948e3c7bfa4a7e91b7521102325e0ce8581b6/bin/containerd-shim-runc-v2 -namespace k8s.io -id c90652c935d9e79af45b9a9ac2b4fe315e2a761a0525737fdb95c680123a164c -address /run/k3s/containerd/containerd.sock root 98309 1 0 16:16 ? 00:00:00 /var/lib/rancher/k3s/data/3cdacaf539fc388d8e542a8d643948e3c7bfa4a7e91b7521102325e0ce8581b6/bin/containerd-shim-runc-v2 -namespace k8s.io -id 431a2763636488efd7d104c228d41f4f2ecd8c06a7fc375d8977ab0d238936a8 -address /run/k3s/containerd/containerd.sock root 98493 1 0 16:16 ? 00:00:00 /var/lib/rancher/k3s/data/3cdacaf539fc388d8e542a8d643948e3c7bfa4a7e91b7521102325e0ce8581b6/bin/containerd-shim-runc-v2 -namespace k8s.io -id 5b480d2fa55c8cc0105ec1902887040c017f03d5b1eb6c73c24bb9d523ad9b37 -address /run/k3s/containerd/containerd.sock +``` + +### 1.2.12 Ensure that the admission control plugin SecurityContextDeny is set if PodSecurityPolicy is not used (Manual) + + +**Result:** Not Applicable + +**Remediation:** +Edit the API server pod specification file /etc/kubernetes/manifests/kube-apiserver.yaml +on the control plane node and set the --enable-admission-plugins parameter to include +SecurityContextDeny, unless PodSecurityPolicy is already in place. +--enable-admission-plugins=...,SecurityContextDeny,... +Permissive - Enabling Pod Security Policy can cause applications to unexpectedly fail. + +### 1.2.13 Ensure that the admission control plugin ServiceAccount is set (Automated) + + +**Result:** pass + +**Remediation:** +Follow the documentation and create ServiceAccount objects as per your environment. +Then, edit the API server pod specification file /etc/kubernetes/manifests/kube-apiserver.yaml +on the control plane node and ensure that the --disable-admission-plugins parameter is set to a +value that does not include ServiceAccount. + +**Audit:** + +```bash +journalctl -D /var/log/journal -u k3s | grep 'Running kube-apiserver' | tail -n1 | grep -v grep +``` + +**Expected Result**: + +```console +'--disable-admission-plugins' is present OR '--disable-admission-plugins' is not present +``` + +**Returned Value**: + +```console +Sep 11 20:52:00 ip-172-31-12-34 k3s[2340]: time="2023-09-11T20:52:00Z" level=info msg="Running kube-apiserver --admission-control-config-file=/etc/rancher/k3s/config/rancher-psact.yaml --advertise-port=6443 --allow-privileged=true --anonymous-auth=false --api-audiences=https://kubernetes.default.svc.cluster.local,k3s --audit-log-maxage=30 --audit-log-maxbackup=10 --audit-log-maxsize=100 --audit-log-path=/var/lib/rancher/k3s/server/logs/audit.log --audit-policy-file=/var/lib/rancher/k3s/server/audit.yaml --authorization-mode=Node,RBAC --bind-address=127.0.0.1 --cert-dir=/var/lib/rancher/k3s/server/tls/temporary-certs --client-ca-file=/var/lib/rancher/k3s/server/tls/client-ca.crt --egress-selector-config-file=/var/lib/rancher/k3s/server/etc/egress-selector-config.yaml --enable-admission-plugins=NodeRestriction,ServiceAccount --enable-aggregator-routing=true --enable-bootstrap-token-auth=true --encryption-provider-config=/var/lib/rancher/k3s/server/cred/encryption-config.json --etcd-cafile=/var/lib/rancher/k3s/server/tls/etcd/server-ca.crt --etcd-certfile=/var/lib/rancher/k3s/server/tls/etcd/client.crt --etcd-keyfile=/var/lib/rancher/k3s/server/tls/etcd/client.key --etcd-servers=https://127.0.0.1:2379 --feature-gates=JobTrackingWithFinalizers=true --kubelet-certificate-authority=/var/lib/rancher/k3s/server/tls/server-ca.crt --kubelet-client-certificate=/var/lib/rancher/k3s/server/tls/client-kube-apiserver.crt --kubelet-client-key=/var/lib/rancher/k3s/server/tls/client-kube-apiserver.key --kubelet-preferred-address-types=InternalIP,ExternalIP,Hostname --profiling=false --proxy-client-cert-file=/var/lib/rancher/k3s/server/tls/client-auth-proxy.crt --proxy-client-key-file=/var/lib/rancher/k3s/server/tls/client-auth-proxy.key --request-timeout=300s --requestheader-allowed-names=system:auth-proxy --requestheader-client-ca-file=/var/lib/rancher/k3s/server/tls/request-header-ca.crt --requestheader-extra-headers-prefix=X-Remote-Extra- --requestheader-group-headers=X-Remote-Group --requestheader-username-headers=X-Remote-User --secure-port=6444 --service-account-issuer=https://kubernetes.default.svc.cluster.local --service-account-key-file=/var/lib/rancher/k3s/server/tls/service.key --service-account-lookup=true --service-account-signing-key-file=/var/lib/rancher/k3s/server/tls/service.current.key --service-cluster-ip-range=10.43.0.0/16 --service-node-port-range=30000-32767 --storage-backend=etcd3 --tls-cert-file=/var/lib/rancher/k3s/server/tls/serving-kube-apiserver.crt --tls-cipher-suites=TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305,TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305 --tls-private-key-file=/var/lib/rancher/k3s/server/tls/serving-kube-apiserver.key" +``` + +### 1.2.14 Ensure that the admission control plugin NamespaceLifecycle is set (Automated) + + +**Result:** pass + +**Remediation:** +Edit the API server pod specification file /etc/kubernetes/manifests/kube-apiserver.yaml +on the control plane node and set the --disable-admission-plugins parameter to +ensure it does not include NamespaceLifecycle. + +**Audit:** + +```bash +journalctl -D /var/log/journal -u k3s | grep 'Running kube-apiserver' | tail -n1 | grep -v grep +``` + +**Expected Result**: + +```console +'--disable-admission-plugins' is present OR '--disable-admission-plugins' is not present +``` + +**Returned Value**: + +```console +Sep 11 20:52:00 ip-172-31-12-34 k3s[2340]: time="2023-09-11T20:52:00Z" level=info msg="Running kube-apiserver --admission-control-config-file=/etc/rancher/k3s/config/rancher-psact.yaml --advertise-port=6443 --allow-privileged=true --anonymous-auth=false --api-audiences=https://kubernetes.default.svc.cluster.local,k3s --audit-log-maxage=30 --audit-log-maxbackup=10 --audit-log-maxsize=100 --audit-log-path=/var/lib/rancher/k3s/server/logs/audit.log --audit-policy-file=/var/lib/rancher/k3s/server/audit.yaml --authorization-mode=Node,RBAC --bind-address=127.0.0.1 --cert-dir=/var/lib/rancher/k3s/server/tls/temporary-certs --client-ca-file=/var/lib/rancher/k3s/server/tls/client-ca.crt --egress-selector-config-file=/var/lib/rancher/k3s/server/etc/egress-selector-config.yaml --enable-admission-plugins=NodeRestriction,ServiceAccount --enable-aggregator-routing=true --enable-bootstrap-token-auth=true --encryption-provider-config=/var/lib/rancher/k3s/server/cred/encryption-config.json --etcd-cafile=/var/lib/rancher/k3s/server/tls/etcd/server-ca.crt --etcd-certfile=/var/lib/rancher/k3s/server/tls/etcd/client.crt --etcd-keyfile=/var/lib/rancher/k3s/server/tls/etcd/client.key --etcd-servers=https://127.0.0.1:2379 --feature-gates=JobTrackingWithFinalizers=true --kubelet-certificate-authority=/var/lib/rancher/k3s/server/tls/server-ca.crt --kubelet-client-certificate=/var/lib/rancher/k3s/server/tls/client-kube-apiserver.crt --kubelet-client-key=/var/lib/rancher/k3s/server/tls/client-kube-apiserver.key --kubelet-preferred-address-types=InternalIP,ExternalIP,Hostname --profiling=false --proxy-client-cert-file=/var/lib/rancher/k3s/server/tls/client-auth-proxy.crt --proxy-client-key-file=/var/lib/rancher/k3s/server/tls/client-auth-proxy.key --request-timeout=300s --requestheader-allowed-names=system:auth-proxy --requestheader-client-ca-file=/var/lib/rancher/k3s/server/tls/request-header-ca.crt --requestheader-extra-headers-prefix=X-Remote-Extra- --requestheader-group-headers=X-Remote-Group --requestheader-username-headers=X-Remote-User --secure-port=6444 --service-account-issuer=https://kubernetes.default.svc.cluster.local --service-account-key-file=/var/lib/rancher/k3s/server/tls/service.key --service-account-lookup=true --service-account-signing-key-file=/var/lib/rancher/k3s/server/tls/service.current.key --service-cluster-ip-range=10.43.0.0/16 --service-node-port-range=30000-32767 --storage-backend=etcd3 --tls-cert-file=/var/lib/rancher/k3s/server/tls/serving-kube-apiserver.crt --tls-cipher-suites=TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305,TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305 --tls-private-key-file=/var/lib/rancher/k3s/server/tls/serving-kube-apiserver.key" +``` + +### 1.2.15 Ensure that the admission control plugin NodeRestriction is set (Automated) + + +**Result:** pass + +**Remediation:** +Follow the Kubernetes documentation and configure NodeRestriction plug-in on kubelets. +Then, edit the API server pod specification file /etc/kubernetes/manifests/kube-apiserver.yaml +on the control plane node and set the --enable-admission-plugins parameter to a +value that includes NodeRestriction. +--enable-admission-plugins=...,NodeRestriction,... + +**Audit:** + +```bash +journalctl -D /var/log/journal -u k3s | grep 'Running kube-apiserver' | tail -n1 | grep 'enable-admission-plugins' +``` + +**Expected Result**: + +```console +'--enable-admission-plugins' has 'NodeRestriction' +``` + +**Returned Value**: + +```console +Sep 11 20:52:00 ip-172-31-12-34 k3s[2340]: time="2023-09-11T20:52:00Z" level=info msg="Running kube-apiserver --admission-control-config-file=/etc/rancher/k3s/config/rancher-psact.yaml --advertise-port=6443 --allow-privileged=true --anonymous-auth=false --api-audiences=https://kubernetes.default.svc.cluster.local,k3s --audit-log-maxage=30 --audit-log-maxbackup=10 --audit-log-maxsize=100 --audit-log-path=/var/lib/rancher/k3s/server/logs/audit.log --audit-policy-file=/var/lib/rancher/k3s/server/audit.yaml --authorization-mode=Node,RBAC --bind-address=127.0.0.1 --cert-dir=/var/lib/rancher/k3s/server/tls/temporary-certs --client-ca-file=/var/lib/rancher/k3s/server/tls/client-ca.crt --egress-selector-config-file=/var/lib/rancher/k3s/server/etc/egress-selector-config.yaml --enable-admission-plugins=NodeRestriction,ServiceAccount --enable-aggregator-routing=true --enable-bootstrap-token-auth=true --encryption-provider-config=/var/lib/rancher/k3s/server/cred/encryption-config.json --etcd-cafile=/var/lib/rancher/k3s/server/tls/etcd/server-ca.crt --etcd-certfile=/var/lib/rancher/k3s/server/tls/etcd/client.crt --etcd-keyfile=/var/lib/rancher/k3s/server/tls/etcd/client.key --etcd-servers=https://127.0.0.1:2379 --feature-gates=JobTrackingWithFinalizers=true --kubelet-certificate-authority=/var/lib/rancher/k3s/server/tls/server-ca.crt --kubelet-client-certificate=/var/lib/rancher/k3s/server/tls/client-kube-apiserver.crt --kubelet-client-key=/var/lib/rancher/k3s/server/tls/client-kube-apiserver.key --kubelet-preferred-address-types=InternalIP,ExternalIP,Hostname --profiling=false --proxy-client-cert-file=/var/lib/rancher/k3s/server/tls/client-auth-proxy.crt --proxy-client-key-file=/var/lib/rancher/k3s/server/tls/client-auth-proxy.key --request-timeout=300s --requestheader-allowed-names=system:auth-proxy --requestheader-client-ca-file=/var/lib/rancher/k3s/server/tls/request-header-ca.crt --requestheader-extra-headers-prefix=X-Remote-Extra- --requestheader-group-headers=X-Remote-Group --requestheader-username-headers=X-Remote-User --secure-port=6444 --service-account-issuer=https://kubernetes.default.svc.cluster.local --service-account-key-file=/var/lib/rancher/k3s/server/tls/service.key --service-account-lookup=true --service-account-signing-key-file=/var/lib/rancher/k3s/server/tls/service.current.key --service-cluster-ip-range=10.43.0.0/16 --service-node-port-range=30000-32767 --storage-backend=etcd3 --tls-cert-file=/var/lib/rancher/k3s/server/tls/serving-kube-apiserver.crt --tls-cipher-suites=TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305,TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305 --tls-private-key-file=/var/lib/rancher/k3s/server/tls/serving-kube-apiserver.key" +``` + +### 1.2.16 Ensure that the --secure-port argument is not set to 0 - NoteThis recommendation is obsolete and will be deleted per the consensus process (Automated) + + +**Result:** pass + +**Remediation:** +Edit the API server pod specification file /etc/kubernetes/manifests/kube-apiserver.yaml +on the control plane node and either remove the --secure-port parameter or +set it to a different (non-zero) desired port. + +**Audit:** + +```bash +journalctl -D /var/log/journal -u k3s | grep 'Running kube-apiserver' | tail -n1 | grep 'secure-port' +``` + +**Expected Result**: + +```console +'--secure-port' is greater than 0 OR '--secure-port' is not present +``` + +**Returned Value**: + +```console +Sep 11 20:52:00 ip-172-31-12-34 k3s[2340]: time="2023-09-11T20:52:00Z" level=info msg="Running kube-apiserver --admission-control-config-file=/etc/rancher/k3s/config/rancher-psact.yaml --advertise-port=6443 --allow-privileged=true --anonymous-auth=false --api-audiences=https://kubernetes.default.svc.cluster.local,k3s --audit-log-maxage=30 --audit-log-maxbackup=10 --audit-log-maxsize=100 --audit-log-path=/var/lib/rancher/k3s/server/logs/audit.log --audit-policy-file=/var/lib/rancher/k3s/server/audit.yaml --authorization-mode=Node,RBAC --bind-address=127.0.0.1 --cert-dir=/var/lib/rancher/k3s/server/tls/temporary-certs --client-ca-file=/var/lib/rancher/k3s/server/tls/client-ca.crt --egress-selector-config-file=/var/lib/rancher/k3s/server/etc/egress-selector-config.yaml --enable-admission-plugins=NodeRestriction,ServiceAccount --enable-aggregator-routing=true --enable-bootstrap-token-auth=true --encryption-provider-config=/var/lib/rancher/k3s/server/cred/encryption-config.json --etcd-cafile=/var/lib/rancher/k3s/server/tls/etcd/server-ca.crt --etcd-certfile=/var/lib/rancher/k3s/server/tls/etcd/client.crt --etcd-keyfile=/var/lib/rancher/k3s/server/tls/etcd/client.key --etcd-servers=https://127.0.0.1:2379 --feature-gates=JobTrackingWithFinalizers=true --kubelet-certificate-authority=/var/lib/rancher/k3s/server/tls/server-ca.crt --kubelet-client-certificate=/var/lib/rancher/k3s/server/tls/client-kube-apiserver.crt --kubelet-client-key=/var/lib/rancher/k3s/server/tls/client-kube-apiserver.key --kubelet-preferred-address-types=InternalIP,ExternalIP,Hostname --profiling=false --proxy-client-cert-file=/var/lib/rancher/k3s/server/tls/client-auth-proxy.crt --proxy-client-key-file=/var/lib/rancher/k3s/server/tls/client-auth-proxy.key --request-timeout=300s --requestheader-allowed-names=system:auth-proxy --requestheader-client-ca-file=/var/lib/rancher/k3s/server/tls/request-header-ca.crt --requestheader-extra-headers-prefix=X-Remote-Extra- --requestheader-group-headers=X-Remote-Group --requestheader-username-headers=X-Remote-User --secure-port=6444 --service-account-issuer=https://kubernetes.default.svc.cluster.local --service-account-key-file=/var/lib/rancher/k3s/server/tls/service.key --service-account-lookup=true --service-account-signing-key-file=/var/lib/rancher/k3s/server/tls/service.current.key --service-cluster-ip-range=10.43.0.0/16 --service-node-port-range=30000-32767 --storage-backend=etcd3 --tls-cert-file=/var/lib/rancher/k3s/server/tls/serving-kube-apiserver.crt --tls-cipher-suites=TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305,TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305 --tls-private-key-file=/var/lib/rancher/k3s/server/tls/serving-kube-apiserver.key" +``` + +### 1.2.17 Ensure that the --profiling argument is set to false (Automated) + + +**Result:** pass + +**Remediation:** +Edit the API server pod specification file /etc/kubernetes/manifests/kube-apiserver.yaml +on the control plane node and set the below parameter. +--profiling=false + +**Audit:** + +```bash +journalctl -D /var/log/journal -u k3s | grep 'Running kube-apiserver' | tail -n1 | grep 'profiling' +``` + +**Expected Result**: + +```console +'--profiling' is equal to 'false' +``` + +**Returned Value**: + +```console +Sep 11 20:52:00 ip-172-31-12-34 k3s[2340]: time="2023-09-11T20:52:00Z" level=info msg="Running kube-apiserver --admission-control-config-file=/etc/rancher/k3s/config/rancher-psact.yaml --advertise-port=6443 --allow-privileged=true --anonymous-auth=false --api-audiences=https://kubernetes.default.svc.cluster.local,k3s --audit-log-maxage=30 --audit-log-maxbackup=10 --audit-log-maxsize=100 --audit-log-path=/var/lib/rancher/k3s/server/logs/audit.log --audit-policy-file=/var/lib/rancher/k3s/server/audit.yaml --authorization-mode=Node,RBAC --bind-address=127.0.0.1 --cert-dir=/var/lib/rancher/k3s/server/tls/temporary-certs --client-ca-file=/var/lib/rancher/k3s/server/tls/client-ca.crt --egress-selector-config-file=/var/lib/rancher/k3s/server/etc/egress-selector-config.yaml --enable-admission-plugins=NodeRestriction,ServiceAccount --enable-aggregator-routing=true --enable-bootstrap-token-auth=true --encryption-provider-config=/var/lib/rancher/k3s/server/cred/encryption-config.json --etcd-cafile=/var/lib/rancher/k3s/server/tls/etcd/server-ca.crt --etcd-certfile=/var/lib/rancher/k3s/server/tls/etcd/client.crt --etcd-keyfile=/var/lib/rancher/k3s/server/tls/etcd/client.key --etcd-servers=https://127.0.0.1:2379 --feature-gates=JobTrackingWithFinalizers=true --kubelet-certificate-authority=/var/lib/rancher/k3s/server/tls/server-ca.crt --kubelet-client-certificate=/var/lib/rancher/k3s/server/tls/client-kube-apiserver.crt --kubelet-client-key=/var/lib/rancher/k3s/server/tls/client-kube-apiserver.key --kubelet-preferred-address-types=InternalIP,ExternalIP,Hostname --profiling=false --proxy-client-cert-file=/var/lib/rancher/k3s/server/tls/client-auth-proxy.crt --proxy-client-key-file=/var/lib/rancher/k3s/server/tls/client-auth-proxy.key --request-timeout=300s --requestheader-allowed-names=system:auth-proxy --requestheader-client-ca-file=/var/lib/rancher/k3s/server/tls/request-header-ca.crt --requestheader-extra-headers-prefix=X-Remote-Extra- --requestheader-group-headers=X-Remote-Group --requestheader-username-headers=X-Remote-User --secure-port=6444 --service-account-issuer=https://kubernetes.default.svc.cluster.local --service-account-key-file=/var/lib/rancher/k3s/server/tls/service.key --service-account-lookup=true --service-account-signing-key-file=/var/lib/rancher/k3s/server/tls/service.current.key --service-cluster-ip-range=10.43.0.0/16 --service-node-port-range=30000-32767 --storage-backend=etcd3 --tls-cert-file=/var/lib/rancher/k3s/server/tls/serving-kube-apiserver.crt --tls-cipher-suites=TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305,TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305 --tls-private-key-file=/var/lib/rancher/k3s/server/tls/serving-kube-apiserver.key" +``` + +### 1.2.18 Ensure that the --audit-log-path argument is set (Automated) + + +**Result:** Not Applicable + +**Remediation:** +Edit the API server pod specification file /etc/kubernetes/manifests/kube-apiserver.yaml +on the control plane node and set the --audit-log-path parameter to a suitable path and +file where you would like audit logs to be written, for example, +--audit-log-path=/var/log/apiserver/audit.log +Permissive. + +### 1.2.19 Ensure that the --audit-log-maxage argument is set to 30 or as appropriate (Automated) + + +**Result:** Not Applicable + +**Remediation:** +Edit the API server pod specification file /etc/kubernetes/manifests/kube-apiserver.yaml +on the control plane node and set the --audit-log-maxage parameter to 30 +or as an appropriate number of days, for example, +--audit-log-maxage=30 +Permissive. + +### 1.2.20 Ensure that the --audit-log-maxbackup argument is set to 10 or as appropriate (Automated) + + +**Result:** Not Applicable + +**Remediation:** +Edit the API server pod specification file /etc/kubernetes/manifests/kube-apiserver.yaml +on the control plane node and set the --audit-log-maxbackup parameter to 10 or to an appropriate +value. For example, +--audit-log-maxbackup=10 +Permissive. + +### 1.2.21 Ensure that the --audit-log-maxsize argument is set to 100 or as appropriate (Automated) + + +**Result:** Not Applicable + +**Remediation:** +Edit the API server pod specification file /etc/kubernetes/manifests/kube-apiserver.yaml +on the control plane node and set the --audit-log-maxsize parameter to an appropriate size in MB. +For example, to set it as 100 MB, --audit-log-maxsize=100 +Permissive. + +### 1.2.22 Ensure that the --request-timeout argument is set as appropriate (Manual) + + +**Result:** Not Applicable + +**Remediation:** +Edit the API server pod specification file /etc/kubernetes/manifests/kube-apiserver.yaml +and set the below parameter as appropriate and if needed. +For example, --request-timeout=300s +Permissive. + +### 1.2.23 Ensure that the --service-account-lookup argument is set to true (Automated) + + +**Result:** pass + +**Remediation:** +Edit the API server pod specification file /etc/kubernetes/manifests/kube-apiserver.yaml +on the control plane node and set the below parameter. +--service-account-lookup=true +Alternatively, you can delete the --service-account-lookup parameter from this file so +that the default takes effect. + +**Audit:** + +```bash +journalctl -D /var/log/journal -u k3s | grep 'Running kube-apiserver' | tail -n1 | grep -v grep +``` + +**Expected Result**: + +```console +'--service-account-lookup' is not present OR '--service-account-lookup' is equal to 'true' +``` + +**Returned Value**: + +```console +Sep 11 20:52:00 ip-172-31-12-34 k3s[2340]: time="2023-09-11T20:52:00Z" level=info msg="Running kube-apiserver --admission-control-config-file=/etc/rancher/k3s/config/rancher-psact.yaml --advertise-port=6443 --allow-privileged=true --anonymous-auth=false --api-audiences=https://kubernetes.default.svc.cluster.local,k3s --audit-log-maxage=30 --audit-log-maxbackup=10 --audit-log-maxsize=100 --audit-log-path=/var/lib/rancher/k3s/server/logs/audit.log --audit-policy-file=/var/lib/rancher/k3s/server/audit.yaml --authorization-mode=Node,RBAC --bind-address=127.0.0.1 --cert-dir=/var/lib/rancher/k3s/server/tls/temporary-certs --client-ca-file=/var/lib/rancher/k3s/server/tls/client-ca.crt --egress-selector-config-file=/var/lib/rancher/k3s/server/etc/egress-selector-config.yaml --enable-admission-plugins=NodeRestriction,ServiceAccount --enable-aggregator-routing=true --enable-bootstrap-token-auth=true --encryption-provider-config=/var/lib/rancher/k3s/server/cred/encryption-config.json --etcd-cafile=/var/lib/rancher/k3s/server/tls/etcd/server-ca.crt --etcd-certfile=/var/lib/rancher/k3s/server/tls/etcd/client.crt --etcd-keyfile=/var/lib/rancher/k3s/server/tls/etcd/client.key --etcd-servers=https://127.0.0.1:2379 --feature-gates=JobTrackingWithFinalizers=true --kubelet-certificate-authority=/var/lib/rancher/k3s/server/tls/server-ca.crt --kubelet-client-certificate=/var/lib/rancher/k3s/server/tls/client-kube-apiserver.crt --kubelet-client-key=/var/lib/rancher/k3s/server/tls/client-kube-apiserver.key --kubelet-preferred-address-types=InternalIP,ExternalIP,Hostname --profiling=false --proxy-client-cert-file=/var/lib/rancher/k3s/server/tls/client-auth-proxy.crt --proxy-client-key-file=/var/lib/rancher/k3s/server/tls/client-auth-proxy.key --request-timeout=300s --requestheader-allowed-names=system:auth-proxy --requestheader-client-ca-file=/var/lib/rancher/k3s/server/tls/request-header-ca.crt --requestheader-extra-headers-prefix=X-Remote-Extra- --requestheader-group-headers=X-Remote-Group --requestheader-username-headers=X-Remote-User --secure-port=6444 --service-account-issuer=https://kubernetes.default.svc.cluster.local --service-account-key-file=/var/lib/rancher/k3s/server/tls/service.key --service-account-lookup=true --service-account-signing-key-file=/var/lib/rancher/k3s/server/tls/service.current.key --service-cluster-ip-range=10.43.0.0/16 --service-node-port-range=30000-32767 --storage-backend=etcd3 --tls-cert-file=/var/lib/rancher/k3s/server/tls/serving-kube-apiserver.crt --tls-cipher-suites=TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305,TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305 --tls-private-key-file=/var/lib/rancher/k3s/server/tls/serving-kube-apiserver.key" +``` + +### 1.2.24 Ensure that the --service-account-key-file argument is set as appropriate (Automated) + + +**Result:** Not Applicable + +**Remediation:** +Edit the API server pod specification file /etc/kubernetes/manifests/kube-apiserver.yaml +on the control plane node and set the --service-account-key-file parameter +to the public key file for service accounts. For example, +--service-account-key-file= + +### 1.2.25 Ensure that the --etcd-certfile and --etcd-keyfile arguments are set as appropriate (Automated) + + +**Result:** pass + +**Remediation:** +Follow the Kubernetes documentation and set up the TLS connection between the apiserver and etcd. +Then, edit the API server pod specification file /etc/kubernetes/manifests/kube-apiserver.yaml +on the control plane node and set the etcd certificate and key file parameters. +--etcd-certfile= +--etcd-keyfile= + +**Audit Script:** `check_for_k3s_etcd.sh` + +```bash +#!/bin/bash + +# This script is used to ensure that k3s is actually running etcd (and not other databases like sqlite3) +# before it checks the requirement +set -eE + +handle_error() { + echo "false" +} + +trap 'handle_error' ERR + + +if [[ "$(journalctl -D /var/log/journal -u k3s | grep 'Managed etcd cluster initializing' | grep -v grep | wc -l)" -gt 0 ]]; then + case $1 in + "1.1.11") + echo $(stat -c %a /var/lib/rancher/k3s/server/db/etcd);; + "1.2.29") + echo $(journalctl -D /var/log/journal -u k3s | grep 'Running kube-apiserver' | tail -n1 | grep 'etcd-');; + "2.1") + echo $(grep -A 5 'client-transport-security' /var/lib/rancher/k3s/server/db/etcd/config | grep -E 'cert-file|key-file');; + "2.2") + echo $(grep -A 5 'client-transport-security' /var/lib/rancher/k3s/server/db/etcd/config | grep 'client-cert-auth');; + "2.3") + echo $(grep 'auto-tls' /var/lib/rancher/k3s/server/db/etcd/config);; + "2.4") + echo $(grep -A 5 'peer-transport-security' /var/lib/rancher/k3s/server/db/etcd/config | grep -E 'cert-file|key-file');; + "2.5") + echo $(grep -A 5 'peer-transport-security' /var/lib/rancher/k3s/server/db/etcd/config | grep 'client-cert-auth');; + "2.6") + echo $(grep 'peer-auto-tls' /var/lib/rancher/k3s/server/db/etcd/config);; + "2.7") + echo $(grep 'trusted-ca-file' /var/lib/rancher/k3s/server/db/etcd/config);; + esac +else +# If another database is running, return whatever is required to pass the scan + case $1 in + "1.1.11") + echo "700";; + "1.2.29") + echo "--etcd-certfile AND --etcd-keyfile";; + "2.1") + echo "cert-file AND key-file";; + "2.2") + echo "--client-cert-auth=true";; + "2.3") + echo "false";; + "2.4") + echo "peer-cert-file AND peer-key-file";; + "2.5") + echo "--client-cert-auth=true";; + "2.6") + echo "--peer-auto-tls=false";; + "2.7") + echo "--trusted-ca-file";; + esac +fi + +``` + +**Audit Execution:** + +```bash +./check_for_k3s_etcd.sh 1.2.29 +``` + +**Expected Result**: + +```console +'--etcd-certfile' is present AND '--etcd-keyfile' is present +``` + +**Returned Value**: + +```console +Sep 11 20:52:00 ip-172-31-12-34 k3s[2340]: time="2023-09-11T20:52:00Z" level=info msg="Running kube-apiserver --admission-control-config-file=/etc/rancher/k3s/config/rancher-psact.yaml --advertise-port=6443 --allow-privileged=true --anonymous-auth=false --api-audiences=https://kubernetes.default.svc.cluster.local,k3s --audit-log-maxage=30 --audit-log-maxbackup=10 --audit-log-maxsize=100 --audit-log-path=/var/lib/rancher/k3s/server/logs/audit.log --audit-policy-file=/var/lib/rancher/k3s/server/audit.yaml --authorization-mode=Node,RBAC --bind-address=127.0.0.1 --cert-dir=/var/lib/rancher/k3s/server/tls/temporary-certs --client-ca-file=/var/lib/rancher/k3s/server/tls/client-ca.crt --egress-selector-config-file=/var/lib/rancher/k3s/server/etc/egress-selector-config.yaml --enable-admission-plugins=NodeRestriction,ServiceAccount --enable-aggregator-routing=true --enable-bootstrap-token-auth=true --encryption-provider-config=/var/lib/rancher/k3s/server/cred/encryption-config.json --etcd-cafile=/var/lib/rancher/k3s/server/tls/etcd/server-ca.crt --etcd-certfile=/var/lib/rancher/k3s/server/tls/etcd/client.crt --etcd-keyfile=/var/lib/rancher/k3s/server/tls/etcd/client.key --etcd-servers=https://127.0.0.1:2379 --feature-gates=JobTrackingWithFinalizers=true --kubelet-certificate-authority=/var/lib/rancher/k3s/server/tls/server-ca.crt --kubelet-client-certificate=/var/lib/rancher/k3s/server/tls/client-kube-apiserver.crt --kubelet-client-key=/var/lib/rancher/k3s/server/tls/client-kube-apiserver.key --kubelet-preferred-address-types=InternalIP,ExternalIP,Hostname --profiling=false --proxy-client-cert-file=/var/lib/rancher/k3s/server/tls/client-auth-proxy.crt --proxy-client-key-file=/var/lib/rancher/k3s/server/tls/client-auth-proxy.key --request-timeout=300s --requestheader-allowed-names=system:auth-proxy --requestheader-client-ca-file=/var/lib/rancher/k3s/server/tls/request-header-ca.crt --requestheader-extra-headers-prefix=X-Remote-Extra- --requestheader-group-headers=X-Remote-Group --requestheader-username-headers=X-Remote-User --secure-port=6444 --service-account-issuer=https://kubernetes.default.svc.cluster.local --service-account-key-file=/var/lib/rancher/k3s/server/tls/service.key --service-account-lookup=true --service-account-signing-key-file=/var/lib/rancher/k3s/server/tls/service.current.key --service-cluster-ip-range=10.43.0.0/16 --service-node-port-range=30000-32767 --storage-backend=etcd3 --tls-cert-file=/var/lib/rancher/k3s/server/tls/serving-kube-apiserver.crt --tls-cipher-suites=TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305,TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305 --tls-private-key-file=/var/lib/rancher/k3s/server/tls/serving-kube-apiserver.key" +``` + +### 1.2.26 Ensure that the --tls-cert-file and --tls-private-key-file arguments are set as appropriate (Automated) + + +**Result:** pass + +**Remediation:** +Follow the Kubernetes documentation and set up the TLS connection on the apiserver. +Then, edit the API server pod specification file /etc/kubernetes/manifests/kube-apiserver.yaml +on the control plane node and set the TLS certificate and private key file parameters. +--tls-cert-file= +--tls-private-key-file= + +**Audit:** + +```bash +journalctl -D /var/log/journal -u k3s | grep -A1 'Running kube-apiserver' | tail -n2 +``` + +**Expected Result**: + +```console +'--tls-cert-file' is present AND '--tls-private-key-file' is present +``` + +**Returned Value**: + +```console +Sep 11 20:52:00 ip-172-31-12-34 k3s[2340]: time="2023-09-11T20:52:00Z" level=info msg="Running kube-apiserver --admission-control-config-file=/etc/rancher/k3s/config/rancher-psact.yaml --advertise-port=6443 --allow-privileged=true --anonymous-auth=false --api-audiences=https://kubernetes.default.svc.cluster.local,k3s --audit-log-maxage=30 --audit-log-maxbackup=10 --audit-log-maxsize=100 --audit-log-path=/var/lib/rancher/k3s/server/logs/audit.log --audit-policy-file=/var/lib/rancher/k3s/server/audit.yaml --authorization-mode=Node,RBAC --bind-address=127.0.0.1 --cert-dir=/var/lib/rancher/k3s/server/tls/temporary-certs --client-ca-file=/var/lib/rancher/k3s/server/tls/client-ca.crt --egress-selector-config-file=/var/lib/rancher/k3s/server/etc/egress-selector-config.yaml --enable-admission-plugins=NodeRestriction,ServiceAccount --enable-aggregator-routing=true --enable-bootstrap-token-auth=true --encryption-provider-config=/var/lib/rancher/k3s/server/cred/encryption-config.json --etcd-cafile=/var/lib/rancher/k3s/server/tls/etcd/server-ca.crt --etcd-certfile=/var/lib/rancher/k3s/server/tls/etcd/client.crt --etcd-keyfile=/var/lib/rancher/k3s/server/tls/etcd/client.key --etcd-servers=https://127.0.0.1:2379 --feature-gates=JobTrackingWithFinalizers=true --kubelet-certificate-authority=/var/lib/rancher/k3s/server/tls/server-ca.crt --kubelet-client-certificate=/var/lib/rancher/k3s/server/tls/client-kube-apiserver.crt --kubelet-client-key=/var/lib/rancher/k3s/server/tls/client-kube-apiserver.key --kubelet-preferred-address-types=InternalIP,ExternalIP,Hostname --profiling=false --proxy-client-cert-file=/var/lib/rancher/k3s/server/tls/client-auth-proxy.crt --proxy-client-key-file=/var/lib/rancher/k3s/server/tls/client-auth-proxy.key --request-timeout=300s --requestheader-allowed-names=system:auth-proxy --requestheader-client-ca-file=/var/lib/rancher/k3s/server/tls/request-header-ca.crt --requestheader-extra-headers-prefix=X-Remote-Extra- --requestheader-group-headers=X-Remote-Group --requestheader-username-headers=X-Remote-User --secure-port=6444 --service-account-issuer=https://kubernetes.default.svc.cluster.local --service-account-key-file=/var/lib/rancher/k3s/server/tls/service.key --service-account-lookup=true --service-account-signing-key-file=/var/lib/rancher/k3s/server/tls/service.current.key --service-cluster-ip-range=10.43.0.0/16 --service-node-port-range=30000-32767 --storage-backend=etcd3 --tls-cert-file=/var/lib/rancher/k3s/server/tls/serving-kube-apiserver.crt --tls-cipher-suites=TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305,TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305 --tls-private-key-file=/var/lib/rancher/k3s/server/tls/serving-kube-apiserver.key" Sep 11 20:52:00 ip-172-31-12-34 k3s[2340]: time="2023-09-11T20:52:00Z" level=info msg="Running kube-scheduler --authentication-kubeconfig=/var/lib/rancher/k3s/server/cred/scheduler.kubeconfig --authorization-kubeconfig=/var/lib/rancher/k3s/server/cred/scheduler.kubeconfig --bind-address=127.0.0.1 --cert-dir=/var/lib/rancher/k3s/server/tls/kube-scheduler --kubeconfig=/var/lib/rancher/k3s/server/cred/scheduler.kubeconfig --profiling=false --secure-port=10259" +``` + +### 1.2.27 Ensure that the --client-ca-file argument is set as appropriate (Automated) + + +**Result:** pass + +**Remediation:** +Follow the Kubernetes documentation and set up the TLS connection on the apiserver. +Then, edit the API server pod specification file /etc/kubernetes/manifests/kube-apiserver.yaml +on the control plane node and set the client certificate authority file. +--client-ca-file= + +**Audit:** + +```bash +journalctl -D /var/log/journal -u k3s | grep 'Running kube-apiserver' | tail -n1 | grep 'client-ca-file' +``` + +**Expected Result**: + +```console +'--client-ca-file' is present +``` + +**Returned Value**: + +```console +Sep 11 20:52:00 ip-172-31-12-34 k3s[2340]: time="2023-09-11T20:52:00Z" level=info msg="Running kube-apiserver --admission-control-config-file=/etc/rancher/k3s/config/rancher-psact.yaml --advertise-port=6443 --allow-privileged=true --anonymous-auth=false --api-audiences=https://kubernetes.default.svc.cluster.local,k3s --audit-log-maxage=30 --audit-log-maxbackup=10 --audit-log-maxsize=100 --audit-log-path=/var/lib/rancher/k3s/server/logs/audit.log --audit-policy-file=/var/lib/rancher/k3s/server/audit.yaml --authorization-mode=Node,RBAC --bind-address=127.0.0.1 --cert-dir=/var/lib/rancher/k3s/server/tls/temporary-certs --client-ca-file=/var/lib/rancher/k3s/server/tls/client-ca.crt --egress-selector-config-file=/var/lib/rancher/k3s/server/etc/egress-selector-config.yaml --enable-admission-plugins=NodeRestriction,ServiceAccount --enable-aggregator-routing=true --enable-bootstrap-token-auth=true --encryption-provider-config=/var/lib/rancher/k3s/server/cred/encryption-config.json --etcd-cafile=/var/lib/rancher/k3s/server/tls/etcd/server-ca.crt --etcd-certfile=/var/lib/rancher/k3s/server/tls/etcd/client.crt --etcd-keyfile=/var/lib/rancher/k3s/server/tls/etcd/client.key --etcd-servers=https://127.0.0.1:2379 --feature-gates=JobTrackingWithFinalizers=true --kubelet-certificate-authority=/var/lib/rancher/k3s/server/tls/server-ca.crt --kubelet-client-certificate=/var/lib/rancher/k3s/server/tls/client-kube-apiserver.crt --kubelet-client-key=/var/lib/rancher/k3s/server/tls/client-kube-apiserver.key --kubelet-preferred-address-types=InternalIP,ExternalIP,Hostname --profiling=false --proxy-client-cert-file=/var/lib/rancher/k3s/server/tls/client-auth-proxy.crt --proxy-client-key-file=/var/lib/rancher/k3s/server/tls/client-auth-proxy.key --request-timeout=300s --requestheader-allowed-names=system:auth-proxy --requestheader-client-ca-file=/var/lib/rancher/k3s/server/tls/request-header-ca.crt --requestheader-extra-headers-prefix=X-Remote-Extra- --requestheader-group-headers=X-Remote-Group --requestheader-username-headers=X-Remote-User --secure-port=6444 --service-account-issuer=https://kubernetes.default.svc.cluster.local --service-account-key-file=/var/lib/rancher/k3s/server/tls/service.key --service-account-lookup=true --service-account-signing-key-file=/var/lib/rancher/k3s/server/tls/service.current.key --service-cluster-ip-range=10.43.0.0/16 --service-node-port-range=30000-32767 --storage-backend=etcd3 --tls-cert-file=/var/lib/rancher/k3s/server/tls/serving-kube-apiserver.crt --tls-cipher-suites=TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305,TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305 --tls-private-key-file=/var/lib/rancher/k3s/server/tls/serving-kube-apiserver.key" +``` + +### 1.2.28 Ensure that the --etcd-cafile argument is set as appropriate (Automated) + + +**Result:** pass + +**Remediation:** +Follow the Kubernetes documentation and set up the TLS connection between the apiserver and etcd. +Then, edit the API server pod specification file /etc/kubernetes/manifests/kube-apiserver.yaml +on the control plane node and set the etcd certificate authority file parameter. +--etcd-cafile= + +**Audit:** + +```bash +journalctl -D /var/log/journal -u k3s | grep 'Running kube-apiserver' | tail -n1 | grep 'etcd-cafile' +``` + +**Expected Result**: + +```console +'--etcd-cafile' is present +``` + +**Returned Value**: + +```console +Sep 11 20:52:00 ip-172-31-12-34 k3s[2340]: time="2023-09-11T20:52:00Z" level=info msg="Running kube-apiserver --admission-control-config-file=/etc/rancher/k3s/config/rancher-psact.yaml --advertise-port=6443 --allow-privileged=true --anonymous-auth=false --api-audiences=https://kubernetes.default.svc.cluster.local,k3s --audit-log-maxage=30 --audit-log-maxbackup=10 --audit-log-maxsize=100 --audit-log-path=/var/lib/rancher/k3s/server/logs/audit.log --audit-policy-file=/var/lib/rancher/k3s/server/audit.yaml --authorization-mode=Node,RBAC --bind-address=127.0.0.1 --cert-dir=/var/lib/rancher/k3s/server/tls/temporary-certs --client-ca-file=/var/lib/rancher/k3s/server/tls/client-ca.crt --egress-selector-config-file=/var/lib/rancher/k3s/server/etc/egress-selector-config.yaml --enable-admission-plugins=NodeRestriction,ServiceAccount --enable-aggregator-routing=true --enable-bootstrap-token-auth=true --encryption-provider-config=/var/lib/rancher/k3s/server/cred/encryption-config.json --etcd-cafile=/var/lib/rancher/k3s/server/tls/etcd/server-ca.crt --etcd-certfile=/var/lib/rancher/k3s/server/tls/etcd/client.crt --etcd-keyfile=/var/lib/rancher/k3s/server/tls/etcd/client.key --etcd-servers=https://127.0.0.1:2379 --feature-gates=JobTrackingWithFinalizers=true --kubelet-certificate-authority=/var/lib/rancher/k3s/server/tls/server-ca.crt --kubelet-client-certificate=/var/lib/rancher/k3s/server/tls/client-kube-apiserver.crt --kubelet-client-key=/var/lib/rancher/k3s/server/tls/client-kube-apiserver.key --kubelet-preferred-address-types=InternalIP,ExternalIP,Hostname --profiling=false --proxy-client-cert-file=/var/lib/rancher/k3s/server/tls/client-auth-proxy.crt --proxy-client-key-file=/var/lib/rancher/k3s/server/tls/client-auth-proxy.key --request-timeout=300s --requestheader-allowed-names=system:auth-proxy --requestheader-client-ca-file=/var/lib/rancher/k3s/server/tls/request-header-ca.crt --requestheader-extra-headers-prefix=X-Remote-Extra- --requestheader-group-headers=X-Remote-Group --requestheader-username-headers=X-Remote-User --secure-port=6444 --service-account-issuer=https://kubernetes.default.svc.cluster.local --service-account-key-file=/var/lib/rancher/k3s/server/tls/service.key --service-account-lookup=true --service-account-signing-key-file=/var/lib/rancher/k3s/server/tls/service.current.key --service-cluster-ip-range=10.43.0.0/16 --service-node-port-range=30000-32767 --storage-backend=etcd3 --tls-cert-file=/var/lib/rancher/k3s/server/tls/serving-kube-apiserver.crt --tls-cipher-suites=TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305,TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305 --tls-private-key-file=/var/lib/rancher/k3s/server/tls/serving-kube-apiserver.key" +``` + +### 1.2.29 Ensure that the --encryption-provider-config argument is set as appropriate (Manual) + + +**Result:** Not Applicable + +**Remediation:** +Follow the Kubernetes documentation and configure a EncryptionConfig file. +Then, edit the API server pod specification file /etc/kubernetes/manifests/kube-apiserver.yaml +on the control plane node and set the --encryption-provider-config parameter to the path of that file. +For example, --encryption-provider-config= +Permissive - Enabling encryption changes how data can be recovered as data is encrypted. + +### 1.2.30 Ensure that encryption providers are appropriately configured (Manual) + + +**Result:** Not Applicable + +**Remediation:** +Follow the Kubernetes documentation and configure a EncryptionConfig file. +In this file, choose aescbc, kms or secretbox as the encryption provider. +Permissive - Enabling encryption changes how data can be recovered as data is encrypted. + +### 1.2.32 Ensure that the API Server only makes use of Strong Cryptographic Ciphers (Manual) + + +**Result:** pass + +**Remediation:** +Edit the API server pod specification file /etc/kubernetes/manifests/kube-apiserver.yaml +on the control plane node and set the below parameter. +--tls-cipher-suites=TLS_AES_128_GCM_SHA256,TLS_AES_256_GCM_SHA384,TLS_CHACHA20_POLY1305_SHA256, +TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA,TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256, +TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA,TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384, +TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305,TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256, +TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA,TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256, +TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305, +TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256,TLS_RSA_WITH_3DES_EDE_CBC_SHA,TLS_RSA_WITH_AES_128_CBC_SHA, +TLS_RSA_WITH_AES_128_GCM_SHA256,TLS_RSA_WITH_AES_256_CBC_SHA,TLS_RSA_WITH_AES_256_GCM_SHA384 + +**Audit:** + +```bash +journalctl -D /var/log/journal -u k3s | grep 'Running kube-apiserver' | tail -n1 | grep 'tls-cipher-suites' +``` + +**Expected Result**: + +```console +'--tls-cipher-suites' contains valid elements from 'TLS_AES_128_GCM_SHA256,TLS_AES_256_GCM_SHA384,TLS_CHACHA20_POLY1305_SHA256,TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA,TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA,TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305,TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256,TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA,TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305,TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256,TLS_RSA_WITH_3DES_EDE_CBC_SHA,TLS_RSA_WITH_AES_128_CBC_SHA,TLS_RSA_WITH_AES_128_GCM_SHA256,TLS_RSA_WITH_AES_256_CBC_SHA,TLS_RSA_WITH_AES_256_GCM_SHA384' +``` + +**Returned Value**: + +```console +Sep 11 20:52:00 ip-172-31-12-34 k3s[2340]: time="2023-09-11T20:52:00Z" level=info msg="Running kube-apiserver --admission-control-config-file=/etc/rancher/k3s/config/rancher-psact.yaml --advertise-port=6443 --allow-privileged=true --anonymous-auth=false --api-audiences=https://kubernetes.default.svc.cluster.local,k3s --audit-log-maxage=30 --audit-log-maxbackup=10 --audit-log-maxsize=100 --audit-log-path=/var/lib/rancher/k3s/server/logs/audit.log --audit-policy-file=/var/lib/rancher/k3s/server/audit.yaml --authorization-mode=Node,RBAC --bind-address=127.0.0.1 --cert-dir=/var/lib/rancher/k3s/server/tls/temporary-certs --client-ca-file=/var/lib/rancher/k3s/server/tls/client-ca.crt --egress-selector-config-file=/var/lib/rancher/k3s/server/etc/egress-selector-config.yaml --enable-admission-plugins=NodeRestriction,ServiceAccount --enable-aggregator-routing=true --enable-bootstrap-token-auth=true --encryption-provider-config=/var/lib/rancher/k3s/server/cred/encryption-config.json --etcd-cafile=/var/lib/rancher/k3s/server/tls/etcd/server-ca.crt --etcd-certfile=/var/lib/rancher/k3s/server/tls/etcd/client.crt --etcd-keyfile=/var/lib/rancher/k3s/server/tls/etcd/client.key --etcd-servers=https://127.0.0.1:2379 --feature-gates=JobTrackingWithFinalizers=true --kubelet-certificate-authority=/var/lib/rancher/k3s/server/tls/server-ca.crt --kubelet-client-certificate=/var/lib/rancher/k3s/server/tls/client-kube-apiserver.crt --kubelet-client-key=/var/lib/rancher/k3s/server/tls/client-kube-apiserver.key --kubelet-preferred-address-types=InternalIP,ExternalIP,Hostname --profiling=false --proxy-client-cert-file=/var/lib/rancher/k3s/server/tls/client-auth-proxy.crt --proxy-client-key-file=/var/lib/rancher/k3s/server/tls/client-auth-proxy.key --request-timeout=300s --requestheader-allowed-names=system:auth-proxy --requestheader-client-ca-file=/var/lib/rancher/k3s/server/tls/request-header-ca.crt --requestheader-extra-headers-prefix=X-Remote-Extra- --requestheader-group-headers=X-Remote-Group --requestheader-username-headers=X-Remote-User --secure-port=6444 --service-account-issuer=https://kubernetes.default.svc.cluster.local --service-account-key-file=/var/lib/rancher/k3s/server/tls/service.key --service-account-lookup=true --service-account-signing-key-file=/var/lib/rancher/k3s/server/tls/service.current.key --service-cluster-ip-range=10.43.0.0/16 --service-node-port-range=30000-32767 --storage-backend=etcd3 --tls-cert-file=/var/lib/rancher/k3s/server/tls/serving-kube-apiserver.crt --tls-cipher-suites=TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305,TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305 --tls-private-key-file=/var/lib/rancher/k3s/server/tls/serving-kube-apiserver.key" +``` + +## 1.3 Controller Manager +### 1.3.1 Ensure that the --terminated-pod-gc-threshold argument is set as appropriate (Manual) + + +**Result:** pass + +**Remediation:** +Edit the Controller Manager pod specification file /etc/kubernetes/manifests/kube-controller-manager.yaml +on the control plane node and set the --terminated-pod-gc-threshold to an appropriate threshold, +for example, --terminated-pod-gc-threshold=10 + +**Audit:** + +```bash +journalctl -D /var/log/journal -u k3s | grep 'Running kube-controller-manager' | tail -n1 | grep 'terminated-pod-gc-threshold' +``` + +**Expected Result**: + +```console +'--terminated-pod-gc-threshold' is present +``` + +**Returned Value**: + +```console +Sep 11 20:52:00 ip-172-31-12-34 k3s[2340]: time="2023-09-11T20:52:00Z" level=info msg="Running kube-controller-manager --allocate-node-cidrs=true --authentication-kubeconfig=/var/lib/rancher/k3s/server/cred/controller.kubeconfig --authorization-kubeconfig=/var/lib/rancher/k3s/server/cred/controller.kubeconfig --bind-address=127.0.0.1 --cert-dir=/var/lib/rancher/k3s/server/tls/kube-controller-manager --cluster-cidr=10.42.0.0/16 --cluster-signing-kube-apiserver-client-cert-file=/var/lib/rancher/k3s/server/tls/client-ca.nochain.crt --cluster-signing-kube-apiserver-client-key-file=/var/lib/rancher/k3s/server/tls/client-ca.key --cluster-signing-kubelet-client-cert-file=/var/lib/rancher/k3s/server/tls/client-ca.nochain.crt --cluster-signing-kubelet-client-key-file=/var/lib/rancher/k3s/server/tls/client-ca.key --cluster-signing-kubelet-serving-cert-file=/var/lib/rancher/k3s/server/tls/server-ca.nochain.crt --cluster-signing-kubelet-serving-key-file=/var/lib/rancher/k3s/server/tls/server-ca.key --cluster-signing-legacy-unknown-cert-file=/var/lib/rancher/k3s/server/tls/server-ca.nochain.crt --cluster-signing-legacy-unknown-key-file=/var/lib/rancher/k3s/server/tls/server-ca.key --configure-cloud-routes=false --controllers=*,tokencleaner,-service,-route,-cloud-node-lifecycle --feature-gates=JobTrackingWithFinalizers=true --kubeconfig=/var/lib/rancher/k3s/server/cred/controller.kubeconfig --profiling=false --root-ca-file=/var/lib/rancher/k3s/server/tls/server-ca.crt --secure-port=10257 --service-account-private-key-file=/var/lib/rancher/k3s/server/tls/service.current.key --service-cluster-ip-range=10.43.0.0/16 --terminated-pod-gc-threshold=10 --use-service-account-credentials=true" +``` + +### 1.3.2 Ensure that the --profiling argument is set to false (Automated) + + +**Result:** pass + +**Remediation:** +Edit the Controller Manager pod specification file /etc/kubernetes/manifests/kube-controller-manager.yaml +on the control plane node and set the below parameter. +--profiling=false + +**Audit:** + +```bash +journalctl -D /var/log/journal -u k3s | grep 'Running kube-controller-manager' | tail -n1 | grep 'profiling' +``` + +**Expected Result**: + +```console +'--profiling' is equal to 'false' +``` + +**Returned Value**: + +```console +Sep 11 20:52:00 ip-172-31-12-34 k3s[2340]: time="2023-09-11T20:52:00Z" level=info msg="Running kube-controller-manager --allocate-node-cidrs=true --authentication-kubeconfig=/var/lib/rancher/k3s/server/cred/controller.kubeconfig --authorization-kubeconfig=/var/lib/rancher/k3s/server/cred/controller.kubeconfig --bind-address=127.0.0.1 --cert-dir=/var/lib/rancher/k3s/server/tls/kube-controller-manager --cluster-cidr=10.42.0.0/16 --cluster-signing-kube-apiserver-client-cert-file=/var/lib/rancher/k3s/server/tls/client-ca.nochain.crt --cluster-signing-kube-apiserver-client-key-file=/var/lib/rancher/k3s/server/tls/client-ca.key --cluster-signing-kubelet-client-cert-file=/var/lib/rancher/k3s/server/tls/client-ca.nochain.crt --cluster-signing-kubelet-client-key-file=/var/lib/rancher/k3s/server/tls/client-ca.key --cluster-signing-kubelet-serving-cert-file=/var/lib/rancher/k3s/server/tls/server-ca.nochain.crt --cluster-signing-kubelet-serving-key-file=/var/lib/rancher/k3s/server/tls/server-ca.key --cluster-signing-legacy-unknown-cert-file=/var/lib/rancher/k3s/server/tls/server-ca.nochain.crt --cluster-signing-legacy-unknown-key-file=/var/lib/rancher/k3s/server/tls/server-ca.key --configure-cloud-routes=false --controllers=*,tokencleaner,-service,-route,-cloud-node-lifecycle --feature-gates=JobTrackingWithFinalizers=true --kubeconfig=/var/lib/rancher/k3s/server/cred/controller.kubeconfig --profiling=false --root-ca-file=/var/lib/rancher/k3s/server/tls/server-ca.crt --secure-port=10257 --service-account-private-key-file=/var/lib/rancher/k3s/server/tls/service.current.key --service-cluster-ip-range=10.43.0.0/16 --terminated-pod-gc-threshold=10 --use-service-account-credentials=true" +``` + +### 1.3.3 Ensure that the --use-service-account-credentials argument is set to true (Automated) + + +**Result:** pass + +**Remediation:** +Edit the Controller Manager pod specification file /etc/kubernetes/manifests/kube-controller-manager.yaml +on the control plane node to set the below parameter. +--use-service-account-credentials=true + +**Audit:** + +```bash +journalctl -D /var/log/journal -u k3s | grep 'Running kube-controller-manager' | tail -n1 | grep 'use-service-account-credentials' +``` + +**Expected Result**: + +```console +'--use-service-account-credentials' is not equal to 'false' +``` + +**Returned Value**: + +```console +Sep 11 20:52:00 ip-172-31-12-34 k3s[2340]: time="2023-09-11T20:52:00Z" level=info msg="Running kube-controller-manager --allocate-node-cidrs=true --authentication-kubeconfig=/var/lib/rancher/k3s/server/cred/controller.kubeconfig --authorization-kubeconfig=/var/lib/rancher/k3s/server/cred/controller.kubeconfig --bind-address=127.0.0.1 --cert-dir=/var/lib/rancher/k3s/server/tls/kube-controller-manager --cluster-cidr=10.42.0.0/16 --cluster-signing-kube-apiserver-client-cert-file=/var/lib/rancher/k3s/server/tls/client-ca.nochain.crt --cluster-signing-kube-apiserver-client-key-file=/var/lib/rancher/k3s/server/tls/client-ca.key --cluster-signing-kubelet-client-cert-file=/var/lib/rancher/k3s/server/tls/client-ca.nochain.crt --cluster-signing-kubelet-client-key-file=/var/lib/rancher/k3s/server/tls/client-ca.key --cluster-signing-kubelet-serving-cert-file=/var/lib/rancher/k3s/server/tls/server-ca.nochain.crt --cluster-signing-kubelet-serving-key-file=/var/lib/rancher/k3s/server/tls/server-ca.key --cluster-signing-legacy-unknown-cert-file=/var/lib/rancher/k3s/server/tls/server-ca.nochain.crt --cluster-signing-legacy-unknown-key-file=/var/lib/rancher/k3s/server/tls/server-ca.key --configure-cloud-routes=false --controllers=*,tokencleaner,-service,-route,-cloud-node-lifecycle --feature-gates=JobTrackingWithFinalizers=true --kubeconfig=/var/lib/rancher/k3s/server/cred/controller.kubeconfig --profiling=false --root-ca-file=/var/lib/rancher/k3s/server/tls/server-ca.crt --secure-port=10257 --service-account-private-key-file=/var/lib/rancher/k3s/server/tls/service.current.key --service-cluster-ip-range=10.43.0.0/16 --terminated-pod-gc-threshold=10 --use-service-account-credentials=true" +``` + +### 1.3.4 Ensure that the --service-account-private-key-file argument is set as appropriate (Automated) + + +**Result:** pass + +**Remediation:** +Edit the Controller Manager pod specification file /etc/kubernetes/manifests/kube-controller-manager.yaml +on the control plane node and set the --service-account-private-key-file parameter +to the private key file for service accounts. +--service-account-private-key-file= + +**Audit:** + +```bash +journalctl -D /var/log/journal -u k3s | grep 'Running kube-controller-manager' | tail -n1 | grep 'service-account-private-key-file' +``` + +**Expected Result**: + +```console +'--service-account-private-key-file' is present +``` + +**Returned Value**: + +```console +Sep 11 20:52:00 ip-172-31-12-34 k3s[2340]: time="2023-09-11T20:52:00Z" level=info msg="Running kube-controller-manager --allocate-node-cidrs=true --authentication-kubeconfig=/var/lib/rancher/k3s/server/cred/controller.kubeconfig --authorization-kubeconfig=/var/lib/rancher/k3s/server/cred/controller.kubeconfig --bind-address=127.0.0.1 --cert-dir=/var/lib/rancher/k3s/server/tls/kube-controller-manager --cluster-cidr=10.42.0.0/16 --cluster-signing-kube-apiserver-client-cert-file=/var/lib/rancher/k3s/server/tls/client-ca.nochain.crt --cluster-signing-kube-apiserver-client-key-file=/var/lib/rancher/k3s/server/tls/client-ca.key --cluster-signing-kubelet-client-cert-file=/var/lib/rancher/k3s/server/tls/client-ca.nochain.crt --cluster-signing-kubelet-client-key-file=/var/lib/rancher/k3s/server/tls/client-ca.key --cluster-signing-kubelet-serving-cert-file=/var/lib/rancher/k3s/server/tls/server-ca.nochain.crt --cluster-signing-kubelet-serving-key-file=/var/lib/rancher/k3s/server/tls/server-ca.key --cluster-signing-legacy-unknown-cert-file=/var/lib/rancher/k3s/server/tls/server-ca.nochain.crt --cluster-signing-legacy-unknown-key-file=/var/lib/rancher/k3s/server/tls/server-ca.key --configure-cloud-routes=false --controllers=*,tokencleaner,-service,-route,-cloud-node-lifecycle --feature-gates=JobTrackingWithFinalizers=true --kubeconfig=/var/lib/rancher/k3s/server/cred/controller.kubeconfig --profiling=false --root-ca-file=/var/lib/rancher/k3s/server/tls/server-ca.crt --secure-port=10257 --service-account-private-key-file=/var/lib/rancher/k3s/server/tls/service.current.key --service-cluster-ip-range=10.43.0.0/16 --terminated-pod-gc-threshold=10 --use-service-account-credentials=true" +``` + +### 1.3.5 Ensure that the --root-ca-file argument is set as appropriate (Automated) + + +**Result:** pass + +**Remediation:** +Edit the Controller Manager pod specification file /etc/kubernetes/manifests/kube-controller-manager.yaml +on the control plane node and set the --root-ca-file parameter to the certificate bundle file`. +--root-ca-file= + +**Audit:** + +```bash +journalctl -D /var/log/journal -u k3s | grep 'Running kube-controller-manager' | tail -n1 | grep 'root-ca-file' +``` + +**Expected Result**: + +```console +'--root-ca-file' is present +``` + +**Returned Value**: + +```console +Sep 11 20:52:00 ip-172-31-12-34 k3s[2340]: time="2023-09-11T20:52:00Z" level=info msg="Running kube-controller-manager --allocate-node-cidrs=true --authentication-kubeconfig=/var/lib/rancher/k3s/server/cred/controller.kubeconfig --authorization-kubeconfig=/var/lib/rancher/k3s/server/cred/controller.kubeconfig --bind-address=127.0.0.1 --cert-dir=/var/lib/rancher/k3s/server/tls/kube-controller-manager --cluster-cidr=10.42.0.0/16 --cluster-signing-kube-apiserver-client-cert-file=/var/lib/rancher/k3s/server/tls/client-ca.nochain.crt --cluster-signing-kube-apiserver-client-key-file=/var/lib/rancher/k3s/server/tls/client-ca.key --cluster-signing-kubelet-client-cert-file=/var/lib/rancher/k3s/server/tls/client-ca.nochain.crt --cluster-signing-kubelet-client-key-file=/var/lib/rancher/k3s/server/tls/client-ca.key --cluster-signing-kubelet-serving-cert-file=/var/lib/rancher/k3s/server/tls/server-ca.nochain.crt --cluster-signing-kubelet-serving-key-file=/var/lib/rancher/k3s/server/tls/server-ca.key --cluster-signing-legacy-unknown-cert-file=/var/lib/rancher/k3s/server/tls/server-ca.nochain.crt --cluster-signing-legacy-unknown-key-file=/var/lib/rancher/k3s/server/tls/server-ca.key --configure-cloud-routes=false --controllers=*,tokencleaner,-service,-route,-cloud-node-lifecycle --feature-gates=JobTrackingWithFinalizers=true --kubeconfig=/var/lib/rancher/k3s/server/cred/controller.kubeconfig --profiling=false --root-ca-file=/var/lib/rancher/k3s/server/tls/server-ca.crt --secure-port=10257 --service-account-private-key-file=/var/lib/rancher/k3s/server/tls/service.current.key --service-cluster-ip-range=10.43.0.0/16 --terminated-pod-gc-threshold=10 --use-service-account-credentials=true" +``` + +### 1.3.6 Ensure that the RotateKubeletServerCertificate argument is set to true (Automated) + + +**Result:** Not Applicable + +**Remediation:** +Edit the Controller Manager pod specification file /etc/kubernetes/manifests/kube-controller-manager.yaml +on the control plane node and set the --feature-gates parameter to include RotateKubeletServerCertificate=true. +--feature-gates=RotateKubeletServerCertificate=true +Not Applicable. + +### 1.3.7 Ensure that the --bind-address argument is set to 127.0.0.1 (Automated) + + +**Result:** pass + +**Remediation:** +Edit the Controller Manager pod specification file /etc/kubernetes/manifests/kube-controller-manager.yaml +on the control plane node and ensure the correct value for the --bind-address parameter + +**Audit:** + +```bash +/bin/ps -ef | grep containerd | grep -v grep +``` + +**Expected Result**: + +```console +'--bind-address' is present OR '--bind-address' is not present +``` + +**Returned Value**: + +```console +root 527 1 0 Sep11 ? 00:01:28 /usr/bin/containerd root 663 1 0 Sep11 ? 00:00:08 /usr/bin/dockerd -H fd:// --containerd=/run/containerd/containerd.sock root 2361 2340 3 Sep11 ? 00:40:19 containerd -c /var/lib/rancher/k3s/agent/etc/containerd/config.toml -a /run/k3s/containerd/containerd.sock --state /run/k3s/containerd --root /var/lib/rancher/k3s/agent/containerd root 3021 1 0 Sep11 ? 00:00:29 /var/lib/rancher/k3s/data/3cdacaf539fc388d8e542a8d643948e3c7bfa4a7e91b7521102325e0ce8581b6/bin/containerd-shim-runc-v2 -namespace k8s.io -id 4790d392966915d995e666002c56ed4cce6dd86f305ce2ee390547a1fcbf6c82 -address /run/k3s/containerd/containerd.sock root 3035 1 0 Sep11 ? 00:00:28 /var/lib/rancher/k3s/data/3cdacaf539fc388d8e542a8d643948e3c7bfa4a7e91b7521102325e0ce8581b6/bin/containerd-shim-runc-v2 -namespace k8s.io -id 9d73e6a160ccde6c7c7d4ba0df3b9f696e3de2ebfc0f19a1dcbdf13aea496427 -address /run/k3s/containerd/containerd.sock root 3235 1 0 Sep11 ? 00:00:31 /var/lib/rancher/k3s/data/3cdacaf539fc388d8e542a8d643948e3c7bfa4a7e91b7521102325e0ce8581b6/bin/containerd-shim-runc-v2 -namespace k8s.io -id 587f6221ee9f36c877231ada8d816a799dfda186332c33378d1eb16c72cdc87d -address /run/k3s/containerd/containerd.sock root 4435 1 0 Sep11 ? 00:00:28 /var/lib/rancher/k3s/data/3cdacaf539fc388d8e542a8d643948e3c7bfa4a7e91b7521102325e0ce8581b6/bin/containerd-shim-runc-v2 -namespace k8s.io -id a74c9ec7d99785c2f2d4e6826aa80c22eb8b38249e8f99679ece00a818e9b7b3 -address /run/k3s/containerd/containerd.sock root 4985 1 0 Sep11 ? 00:00:53 /var/lib/rancher/k3s/data/3cdacaf539fc388d8e542a8d643948e3c7bfa4a7e91b7521102325e0ce8581b6/bin/containerd-shim-runc-v2 -namespace k8s.io -id 5b0c9784dbe0fcbe8be10c857976e70ec84a208cb814e87b5ca085a02d434f8c -address /run/k3s/containerd/containerd.sock root 5056 1 0 Sep11 ? 00:00:28 /var/lib/rancher/k3s/data/3cdacaf539fc388d8e542a8d643948e3c7bfa4a7e91b7521102325e0ce8581b6/bin/containerd-shim-runc-v2 -namespace k8s.io -id f3231ff35f18056e74eda14907f296be15f7ea1c6ae5ab7904e27d4d18183301 -address /run/k3s/containerd/containerd.sock root 5868 1 0 Sep11 ? 00:00:27 /var/lib/rancher/k3s/data/3cdacaf539fc388d8e542a8d643948e3c7bfa4a7e91b7521102325e0ce8581b6/bin/containerd-shim-runc-v2 -namespace k8s.io -id 3e908c4d0b10df275bdef6f72fbcfa09517d11cf749236ad020364e14d77bc93 -address /run/k3s/containerd/containerd.sock root 6158 1 0 Sep11 ? 00:00:28 /var/lib/rancher/k3s/data/3cdacaf539fc388d8e542a8d643948e3c7bfa4a7e91b7521102325e0ce8581b6/bin/containerd-shim-runc-v2 -namespace k8s.io -id bec5780a5c73fa3154aa3b5ee26cdf23202db821205893e7e66ae17e6103e97b -address /run/k3s/containerd/containerd.sock root 7366 1 0 Sep11 ? 00:00:28 /var/lib/rancher/k3s/data/3cdacaf539fc388d8e542a8d643948e3c7bfa4a7e91b7521102325e0ce8581b6/bin/containerd-shim-runc-v2 -namespace k8s.io -id a81b78845bdcaef710314c93e5ea0d0617f37a8929472f7b570ab90c6667f57f -address /run/k3s/containerd/containerd.sock root 97274 1 0 16:13 ? 00:00:00 /var/lib/rancher/k3s/data/3cdacaf539fc388d8e542a8d643948e3c7bfa4a7e91b7521102325e0ce8581b6/bin/containerd-shim-runc-v2 -namespace k8s.io -id c90652c935d9e79af45b9a9ac2b4fe315e2a761a0525737fdb95c680123a164c -address /run/k3s/containerd/containerd.sock root 98309 1 0 16:16 ? 00:00:00 /var/lib/rancher/k3s/data/3cdacaf539fc388d8e542a8d643948e3c7bfa4a7e91b7521102325e0ce8581b6/bin/containerd-shim-runc-v2 -namespace k8s.io -id 431a2763636488efd7d104c228d41f4f2ecd8c06a7fc375d8977ab0d238936a8 -address /run/k3s/containerd/containerd.sock root 98493 1 0 16:16 ? 00:00:00 /var/lib/rancher/k3s/data/3cdacaf539fc388d8e542a8d643948e3c7bfa4a7e91b7521102325e0ce8581b6/bin/containerd-shim-runc-v2 -namespace k8s.io -id 5b480d2fa55c8cc0105ec1902887040c017f03d5b1eb6c73c24bb9d523ad9b37 -address /run/k3s/containerd/containerd.sock +``` + +## 1.4 Scheduler +### 1.4.1 Ensure that the --profiling argument is set to false (Automated) + + +**Result:** pass + +**Remediation:** +Edit the Scheduler pod specification file /etc/kubernetes/manifests/kube-scheduler.yaml file +on the control plane node and set the below parameter. +--profiling=false + +**Audit:** + +```bash +journalctl -D /var/log/journal -u k3s | grep 'Running kube-scheduler' | tail -n1 +``` + +**Expected Result**: + +```console +'--profiling' is equal to 'false' +``` + +**Returned Value**: + +```console +Sep 11 20:52:00 ip-172-31-12-34 k3s[2340]: time="2023-09-11T20:52:00Z" level=info msg="Running kube-scheduler --authentication-kubeconfig=/var/lib/rancher/k3s/server/cred/scheduler.kubeconfig --authorization-kubeconfig=/var/lib/rancher/k3s/server/cred/scheduler.kubeconfig --bind-address=127.0.0.1 --cert-dir=/var/lib/rancher/k3s/server/tls/kube-scheduler --kubeconfig=/var/lib/rancher/k3s/server/cred/scheduler.kubeconfig --profiling=false --secure-port=10259" +``` + +### 1.4.2 Ensure that the --bind-address argument is set to 127.0.0.1 (Automated) + + +**Result:** pass + +**Remediation:** +Edit the Scheduler pod specification file /etc/kubernetes/manifests/kube-scheduler.yaml +on the control plane node and ensure the correct value for the --bind-address parameter + +**Audit:** + +```bash +journalctl -D /var/log/journal -u k3s | grep 'Running kube-scheduler' | tail -n1 | grep 'bind-address' +``` + +**Expected Result**: + +```console +'--bind-address' is equal to '127.0.0.1' OR '--bind-address' is not present +``` + +**Returned Value**: + +```console +Sep 11 20:52:00 ip-172-31-12-34 k3s[2340]: time="2023-09-11T20:52:00Z" level=info msg="Running kube-scheduler --authentication-kubeconfig=/var/lib/rancher/k3s/server/cred/scheduler.kubeconfig --authorization-kubeconfig=/var/lib/rancher/k3s/server/cred/scheduler.kubeconfig --bind-address=127.0.0.1 --cert-dir=/var/lib/rancher/k3s/server/tls/kube-scheduler --kubeconfig=/var/lib/rancher/k3s/server/cred/scheduler.kubeconfig --profiling=false --secure-port=10259" +``` + +## 2 Etcd Node Configuration +### 2.1 Ensure that the --cert-file and --key-file arguments are set as appropriate (Automated) + + +**Result:** pass + +**Remediation:** +Follow the etcd service documentation and configure TLS encryption. +Then, edit the etcd pod specification file /etc/kubernetes/manifests/etcd.yaml +on the master node and set the below parameters. +--cert-file= +--key-file= + +**Audit Script:** `check_for_k3s_etcd.sh` + +```bash +#!/bin/bash + +# This script is used to ensure that k3s is actually running etcd (and not other databases like sqlite3) +# before it checks the requirement +set -eE + +handle_error() { + echo "false" +} + +trap 'handle_error' ERR + + +if [[ "$(journalctl -D /var/log/journal -u k3s | grep 'Managed etcd cluster initializing' | grep -v grep | wc -l)" -gt 0 ]]; then + case $1 in + "1.1.11") + echo $(stat -c %a /var/lib/rancher/k3s/server/db/etcd);; + "1.2.29") + echo $(journalctl -D /var/log/journal -u k3s | grep 'Running kube-apiserver' | tail -n1 | grep 'etcd-');; + "2.1") + echo $(grep -A 5 'client-transport-security' /var/lib/rancher/k3s/server/db/etcd/config | grep -E 'cert-file|key-file');; + "2.2") + echo $(grep -A 5 'client-transport-security' /var/lib/rancher/k3s/server/db/etcd/config | grep 'client-cert-auth');; + "2.3") + echo $(grep 'auto-tls' /var/lib/rancher/k3s/server/db/etcd/config);; + "2.4") + echo $(grep -A 5 'peer-transport-security' /var/lib/rancher/k3s/server/db/etcd/config | grep -E 'cert-file|key-file');; + "2.5") + echo $(grep -A 5 'peer-transport-security' /var/lib/rancher/k3s/server/db/etcd/config | grep 'client-cert-auth');; + "2.6") + echo $(grep 'peer-auto-tls' /var/lib/rancher/k3s/server/db/etcd/config);; + "2.7") + echo $(grep 'trusted-ca-file' /var/lib/rancher/k3s/server/db/etcd/config);; + esac +else +# If another database is running, return whatever is required to pass the scan + case $1 in + "1.1.11") + echo "700";; + "1.2.29") + echo "--etcd-certfile AND --etcd-keyfile";; + "2.1") + echo "cert-file AND key-file";; + "2.2") + echo "--client-cert-auth=true";; + "2.3") + echo "false";; + "2.4") + echo "peer-cert-file AND peer-key-file";; + "2.5") + echo "--client-cert-auth=true";; + "2.6") + echo "--peer-auto-tls=false";; + "2.7") + echo "--trusted-ca-file";; + esac +fi + +``` + +**Audit Execution:** + +```bash +./check_for_k3s_etcd.sh 2.1 +``` + +**Expected Result**: + +```console +'cert-file' is present AND 'key-file' is present +``` + +**Returned Value**: + +```console +cert-file: /var/lib/rancher/k3s/server/tls/etcd/server-client.crt key-file: /var/lib/rancher/k3s/server/tls/etcd/server-client.key +``` + +### 2.2 Ensure that the --client-cert-auth argument is set to true (Automated) + + +**Result:** pass + +**Remediation:** +Edit the etcd pod specification file /var/lib/rancher/k3s/server/db/etcd/config on the master +node and set the below parameter. +--client-cert-auth="true" + +**Audit Script:** `check_for_k3s_etcd.sh` + +```bash +#!/bin/bash + +# This script is used to ensure that k3s is actually running etcd (and not other databases like sqlite3) +# before it checks the requirement +set -eE + +handle_error() { + echo "false" +} + +trap 'handle_error' ERR + + +if [[ "$(journalctl -D /var/log/journal -u k3s | grep 'Managed etcd cluster initializing' | grep -v grep | wc -l)" -gt 0 ]]; then + case $1 in + "1.1.11") + echo $(stat -c %a /var/lib/rancher/k3s/server/db/etcd);; + "1.2.29") + echo $(journalctl -D /var/log/journal -u k3s | grep 'Running kube-apiserver' | tail -n1 | grep 'etcd-');; + "2.1") + echo $(grep -A 5 'client-transport-security' /var/lib/rancher/k3s/server/db/etcd/config | grep -E 'cert-file|key-file');; + "2.2") + echo $(grep -A 5 'client-transport-security' /var/lib/rancher/k3s/server/db/etcd/config | grep 'client-cert-auth');; + "2.3") + echo $(grep 'auto-tls' /var/lib/rancher/k3s/server/db/etcd/config);; + "2.4") + echo $(grep -A 5 'peer-transport-security' /var/lib/rancher/k3s/server/db/etcd/config | grep -E 'cert-file|key-file');; + "2.5") + echo $(grep -A 5 'peer-transport-security' /var/lib/rancher/k3s/server/db/etcd/config | grep 'client-cert-auth');; + "2.6") + echo $(grep 'peer-auto-tls' /var/lib/rancher/k3s/server/db/etcd/config);; + "2.7") + echo $(grep 'trusted-ca-file' /var/lib/rancher/k3s/server/db/etcd/config);; + esac +else +# If another database is running, return whatever is required to pass the scan + case $1 in + "1.1.11") + echo "700";; + "1.2.29") + echo "--etcd-certfile AND --etcd-keyfile";; + "2.1") + echo "cert-file AND key-file";; + "2.2") + echo "--client-cert-auth=true";; + "2.3") + echo "false";; + "2.4") + echo "peer-cert-file AND peer-key-file";; + "2.5") + echo "--client-cert-auth=true";; + "2.6") + echo "--peer-auto-tls=false";; + "2.7") + echo "--trusted-ca-file";; + esac +fi + +``` + +**Audit Execution:** + +```bash +./check_for_k3s_etcd.sh 2.2 +``` + +**Expected Result**: + +```console +'--client-cert-auth' is present OR 'client-cert-auth' is equal to 'true' +``` + +**Returned Value**: + +```console +client-cert-auth: true +``` + +### 2.3 Ensure that the --auto-tls argument is not set to true (Automated) + + +**Result:** pass + +**Remediation:** +Edit the etcd pod specification file /var/lib/rancher/k3s/server/db/etcd/config on the master +node and either remove the --auto-tls parameter or set it to false. + --auto-tls=false + +**Audit Script:** `check_for_k3s_etcd.sh` + +```bash +#!/bin/bash + +# This script is used to ensure that k3s is actually running etcd (and not other databases like sqlite3) +# before it checks the requirement +set -eE + +handle_error() { + echo "false" +} + +trap 'handle_error' ERR + + +if [[ "$(journalctl -D /var/log/journal -u k3s | grep 'Managed etcd cluster initializing' | grep -v grep | wc -l)" -gt 0 ]]; then + case $1 in + "1.1.11") + echo $(stat -c %a /var/lib/rancher/k3s/server/db/etcd);; + "1.2.29") + echo $(journalctl -D /var/log/journal -u k3s | grep 'Running kube-apiserver' | tail -n1 | grep 'etcd-');; + "2.1") + echo $(grep -A 5 'client-transport-security' /var/lib/rancher/k3s/server/db/etcd/config | grep -E 'cert-file|key-file');; + "2.2") + echo $(grep -A 5 'client-transport-security' /var/lib/rancher/k3s/server/db/etcd/config | grep 'client-cert-auth');; + "2.3") + echo $(grep 'auto-tls' /var/lib/rancher/k3s/server/db/etcd/config);; + "2.4") + echo $(grep -A 5 'peer-transport-security' /var/lib/rancher/k3s/server/db/etcd/config | grep -E 'cert-file|key-file');; + "2.5") + echo $(grep -A 5 'peer-transport-security' /var/lib/rancher/k3s/server/db/etcd/config | grep 'client-cert-auth');; + "2.6") + echo $(grep 'peer-auto-tls' /var/lib/rancher/k3s/server/db/etcd/config);; + "2.7") + echo $(grep 'trusted-ca-file' /var/lib/rancher/k3s/server/db/etcd/config);; + esac +else +# If another database is running, return whatever is required to pass the scan + case $1 in + "1.1.11") + echo "700";; + "1.2.29") + echo "--etcd-certfile AND --etcd-keyfile";; + "2.1") + echo "cert-file AND key-file";; + "2.2") + echo "--client-cert-auth=true";; + "2.3") + echo "false";; + "2.4") + echo "peer-cert-file AND peer-key-file";; + "2.5") + echo "--client-cert-auth=true";; + "2.6") + echo "--peer-auto-tls=false";; + "2.7") + echo "--trusted-ca-file";; + esac +fi + +``` + +**Audit Execution:** + +```bash +./check_for_k3s_etcd.sh 2.3 +``` + +**Expected Result**: + +```console +'ETCD_AUTO_TLS' is not present OR 'ETCD_AUTO_TLS' is present +``` + +**Returned Value**: + +```console +error: process ID list syntax error Usage: ps [options] Try 'ps --help ' or 'ps --help ' for additional help text. For more details see ps(1). cat: /proc//environ: No such file or directory +``` + +### 2.4 Ensure that the --peer-cert-file and --peer-key-file arguments are set as appropriate (Automated) + + +**Result:** pass + +**Remediation:** +Follow the etcd service documentation and configure peer TLS encryption as appropriate +for your etcd cluster. +Then, edit the etcd pod specification file /var/lib/rancher/k3s/server/db/etcd/config on the +master node and set the below parameters. +--peer-client-file= +--peer-key-file= + +**Audit Script:** `check_for_k3s_etcd.sh` + +```bash +#!/bin/bash + +# This script is used to ensure that k3s is actually running etcd (and not other databases like sqlite3) +# before it checks the requirement +set -eE + +handle_error() { + echo "false" +} + +trap 'handle_error' ERR + + +if [[ "$(journalctl -D /var/log/journal -u k3s | grep 'Managed etcd cluster initializing' | grep -v grep | wc -l)" -gt 0 ]]; then + case $1 in + "1.1.11") + echo $(stat -c %a /var/lib/rancher/k3s/server/db/etcd);; + "1.2.29") + echo $(journalctl -D /var/log/journal -u k3s | grep 'Running kube-apiserver' | tail -n1 | grep 'etcd-');; + "2.1") + echo $(grep -A 5 'client-transport-security' /var/lib/rancher/k3s/server/db/etcd/config | grep -E 'cert-file|key-file');; + "2.2") + echo $(grep -A 5 'client-transport-security' /var/lib/rancher/k3s/server/db/etcd/config | grep 'client-cert-auth');; + "2.3") + echo $(grep 'auto-tls' /var/lib/rancher/k3s/server/db/etcd/config);; + "2.4") + echo $(grep -A 5 'peer-transport-security' /var/lib/rancher/k3s/server/db/etcd/config | grep -E 'cert-file|key-file');; + "2.5") + echo $(grep -A 5 'peer-transport-security' /var/lib/rancher/k3s/server/db/etcd/config | grep 'client-cert-auth');; + "2.6") + echo $(grep 'peer-auto-tls' /var/lib/rancher/k3s/server/db/etcd/config);; + "2.7") + echo $(grep 'trusted-ca-file' /var/lib/rancher/k3s/server/db/etcd/config);; + esac +else +# If another database is running, return whatever is required to pass the scan + case $1 in + "1.1.11") + echo "700";; + "1.2.29") + echo "--etcd-certfile AND --etcd-keyfile";; + "2.1") + echo "cert-file AND key-file";; + "2.2") + echo "--client-cert-auth=true";; + "2.3") + echo "false";; + "2.4") + echo "peer-cert-file AND peer-key-file";; + "2.5") + echo "--client-cert-auth=true";; + "2.6") + echo "--peer-auto-tls=false";; + "2.7") + echo "--trusted-ca-file";; + esac +fi + +``` + +**Audit Execution:** + +```bash +./check_for_k3s_etcd.sh 2.4 +``` + +**Expected Result**: + +```console +'cert-file' is present AND 'key-file' is present +``` + +**Returned Value**: + +```console +cert-file: /var/lib/rancher/k3s/server/tls/etcd/peer-server-client.crt key-file: /var/lib/rancher/k3s/server/tls/etcd/peer-server-client.key +``` + +### 2.5 Ensure that the --peer-client-cert-auth argument is set to true (Automated) + + +**Result:** pass + +**Remediation:** +Edit the etcd pod specification file /var/lib/rancher/k3s/server/db/etcd/config on the master +node and set the below parameter. +--peer-client-cert-auth=true + +**Audit Script:** `check_for_k3s_etcd.sh` + +```bash +#!/bin/bash + +# This script is used to ensure that k3s is actually running etcd (and not other databases like sqlite3) +# before it checks the requirement +set -eE + +handle_error() { + echo "false" +} + +trap 'handle_error' ERR + + +if [[ "$(journalctl -D /var/log/journal -u k3s | grep 'Managed etcd cluster initializing' | grep -v grep | wc -l)" -gt 0 ]]; then + case $1 in + "1.1.11") + echo $(stat -c %a /var/lib/rancher/k3s/server/db/etcd);; + "1.2.29") + echo $(journalctl -D /var/log/journal -u k3s | grep 'Running kube-apiserver' | tail -n1 | grep 'etcd-');; + "2.1") + echo $(grep -A 5 'client-transport-security' /var/lib/rancher/k3s/server/db/etcd/config | grep -E 'cert-file|key-file');; + "2.2") + echo $(grep -A 5 'client-transport-security' /var/lib/rancher/k3s/server/db/etcd/config | grep 'client-cert-auth');; + "2.3") + echo $(grep 'auto-tls' /var/lib/rancher/k3s/server/db/etcd/config);; + "2.4") + echo $(grep -A 5 'peer-transport-security' /var/lib/rancher/k3s/server/db/etcd/config | grep -E 'cert-file|key-file');; + "2.5") + echo $(grep -A 5 'peer-transport-security' /var/lib/rancher/k3s/server/db/etcd/config | grep 'client-cert-auth');; + "2.6") + echo $(grep 'peer-auto-tls' /var/lib/rancher/k3s/server/db/etcd/config);; + "2.7") + echo $(grep 'trusted-ca-file' /var/lib/rancher/k3s/server/db/etcd/config);; + esac +else +# If another database is running, return whatever is required to pass the scan + case $1 in + "1.1.11") + echo "700";; + "1.2.29") + echo "--etcd-certfile AND --etcd-keyfile";; + "2.1") + echo "cert-file AND key-file";; + "2.2") + echo "--client-cert-auth=true";; + "2.3") + echo "false";; + "2.4") + echo "peer-cert-file AND peer-key-file";; + "2.5") + echo "--client-cert-auth=true";; + "2.6") + echo "--peer-auto-tls=false";; + "2.7") + echo "--trusted-ca-file";; + esac +fi + +``` + +**Audit Execution:** + +```bash +./check_for_k3s_etcd.sh 2.5 +``` + +**Expected Result**: + +```console +'--client-cert-auth' is present OR 'client-cert-auth' is equal to 'true' +``` + +**Returned Value**: + +```console +client-cert-auth: true +``` + +### 2.6 Ensure that the --peer-auto-tls argument is not set to true (Automated) + + +**Result:** pass + +**Remediation:** +Edit the etcd pod specification file /var/lib/rancher/k3s/server/db/etcd/config on the master +node and either remove the --peer-auto-tls parameter or set it to false. +--peer-auto-tls=false + +**Audit Script:** `check_for_k3s_etcd.sh` + +```bash +#!/bin/bash + +# This script is used to ensure that k3s is actually running etcd (and not other databases like sqlite3) +# before it checks the requirement +set -eE + +handle_error() { + echo "false" +} + +trap 'handle_error' ERR + + +if [[ "$(journalctl -D /var/log/journal -u k3s | grep 'Managed etcd cluster initializing' | grep -v grep | wc -l)" -gt 0 ]]; then + case $1 in + "1.1.11") + echo $(stat -c %a /var/lib/rancher/k3s/server/db/etcd);; + "1.2.29") + echo $(journalctl -D /var/log/journal -u k3s | grep 'Running kube-apiserver' | tail -n1 | grep 'etcd-');; + "2.1") + echo $(grep -A 5 'client-transport-security' /var/lib/rancher/k3s/server/db/etcd/config | grep -E 'cert-file|key-file');; + "2.2") + echo $(grep -A 5 'client-transport-security' /var/lib/rancher/k3s/server/db/etcd/config | grep 'client-cert-auth');; + "2.3") + echo $(grep 'auto-tls' /var/lib/rancher/k3s/server/db/etcd/config);; + "2.4") + echo $(grep -A 5 'peer-transport-security' /var/lib/rancher/k3s/server/db/etcd/config | grep -E 'cert-file|key-file');; + "2.5") + echo $(grep -A 5 'peer-transport-security' /var/lib/rancher/k3s/server/db/etcd/config | grep 'client-cert-auth');; + "2.6") + echo $(grep 'peer-auto-tls' /var/lib/rancher/k3s/server/db/etcd/config);; + "2.7") + echo $(grep 'trusted-ca-file' /var/lib/rancher/k3s/server/db/etcd/config);; + esac +else +# If another database is running, return whatever is required to pass the scan + case $1 in + "1.1.11") + echo "700";; + "1.2.29") + echo "--etcd-certfile AND --etcd-keyfile";; + "2.1") + echo "cert-file AND key-file";; + "2.2") + echo "--client-cert-auth=true";; + "2.3") + echo "false";; + "2.4") + echo "peer-cert-file AND peer-key-file";; + "2.5") + echo "--client-cert-auth=true";; + "2.6") + echo "--peer-auto-tls=false";; + "2.7") + echo "--trusted-ca-file";; + esac +fi + +``` + +**Audit Execution:** + +```bash +./check_for_k3s_etcd.sh 2.6 +``` + +**Expected Result**: + +```console +'ETCD_PEER_AUTO_TLS' is not present OR 'ETCD_PEER_AUTO_TLS' is present +``` + +**Returned Value**: + +```console +error: process ID list syntax error Usage: ps [options] Try 'ps --help ' or 'ps --help ' for additional help text. For more details see ps(1). cat: /proc//environ: No such file or directory +``` + +### 2.7 Ensure that a unique Certificate Authority is used for etcd (Automated) + + +**Result:** pass + +**Remediation:** +[Manual test] +Follow the etcd documentation and create a dedicated certificate authority setup for the +etcd service. +Then, edit the etcd pod specification file /var/lib/rancher/k3s/server/db/etcd/config on the +master node and set the below parameter. +--trusted-ca-file= + +**Audit Script:** `check_for_k3s_etcd.sh` + +```bash +#!/bin/bash + +# This script is used to ensure that k3s is actually running etcd (and not other databases like sqlite3) +# before it checks the requirement +set -eE + +handle_error() { + echo "false" +} + +trap 'handle_error' ERR + + +if [[ "$(journalctl -D /var/log/journal -u k3s | grep 'Managed etcd cluster initializing' | grep -v grep | wc -l)" -gt 0 ]]; then + case $1 in + "1.1.11") + echo $(stat -c %a /var/lib/rancher/k3s/server/db/etcd);; + "1.2.29") + echo $(journalctl -D /var/log/journal -u k3s | grep 'Running kube-apiserver' | tail -n1 | grep 'etcd-');; + "2.1") + echo $(grep -A 5 'client-transport-security' /var/lib/rancher/k3s/server/db/etcd/config | grep -E 'cert-file|key-file');; + "2.2") + echo $(grep -A 5 'client-transport-security' /var/lib/rancher/k3s/server/db/etcd/config | grep 'client-cert-auth');; + "2.3") + echo $(grep 'auto-tls' /var/lib/rancher/k3s/server/db/etcd/config);; + "2.4") + echo $(grep -A 5 'peer-transport-security' /var/lib/rancher/k3s/server/db/etcd/config | grep -E 'cert-file|key-file');; + "2.5") + echo $(grep -A 5 'peer-transport-security' /var/lib/rancher/k3s/server/db/etcd/config | grep 'client-cert-auth');; + "2.6") + echo $(grep 'peer-auto-tls' /var/lib/rancher/k3s/server/db/etcd/config);; + "2.7") + echo $(grep 'trusted-ca-file' /var/lib/rancher/k3s/server/db/etcd/config);; + esac +else +# If another database is running, return whatever is required to pass the scan + case $1 in + "1.1.11") + echo "700";; + "1.2.29") + echo "--etcd-certfile AND --etcd-keyfile";; + "2.1") + echo "cert-file AND key-file";; + "2.2") + echo "--client-cert-auth=true";; + "2.3") + echo "false";; + "2.4") + echo "peer-cert-file AND peer-key-file";; + "2.5") + echo "--client-cert-auth=true";; + "2.6") + echo "--peer-auto-tls=false";; + "2.7") + echo "--trusted-ca-file";; + esac +fi + +``` + +**Audit Execution:** + +```bash +./check_for_k3s_etcd.sh 2.7 +``` + +**Expected Result**: + +```console +'trusted-ca-file' is present +``` + +**Returned Value**: + +```console +trusted-ca-file: /var/lib/rancher/k3s/server/tls/etcd/server-ca.crt trusted-ca-file: /var/lib/rancher/k3s/server/tls/etcd/peer-ca.crt +``` + +## 3.1 Authentication and Authorization +### 3.1.1 Client certificate authentication should not be used for users (Manual) + + +**Result:** warn + +**Remediation:** +Alternative mechanisms provided by Kubernetes such as the use of OIDC should be +implemented in place of client certificates. + +### 3.1.2 Service account token authentication should not be used for users (Manual) + + +**Result:** warn + +**Remediation:** +Alternative mechanisms provided by Kubernetes such as the use of OIDC should be implemented +in place of service account tokens. + +### 3.1.3 Bootstrap token authentication should not be used for users (Manual) + + +**Result:** warn + +**Remediation:** +Alternative mechanisms provided by Kubernetes such as the use of OIDC should be implemented +in place of bootstrap tokens. + +## 3.2 Logging +### 3.2.1 Ensure that a minimal audit policy is created (Manual) + + +**Result:** pass + +**Remediation:** +Create an audit policy file for your cluster. + +**Audit:** + +```bash +journalctl -D /var/log/journal -u k3s | grep 'Running kube-apiserver' | tail -n1 | grep 'audit-policy-file' +``` + +**Expected Result**: + +```console +'--audit-policy-file' is present +``` + +**Returned Value**: + +```console +Sep 11 20:52:00 ip-172-31-12-34 k3s[2340]: time="2023-09-11T20:52:00Z" level=info msg="Running kube-apiserver --admission-control-config-file=/etc/rancher/k3s/config/rancher-psact.yaml --advertise-port=6443 --allow-privileged=true --anonymous-auth=false --api-audiences=https://kubernetes.default.svc.cluster.local,k3s --audit-log-maxage=30 --audit-log-maxbackup=10 --audit-log-maxsize=100 --audit-log-path=/var/lib/rancher/k3s/server/logs/audit.log --audit-policy-file=/var/lib/rancher/k3s/server/audit.yaml --authorization-mode=Node,RBAC --bind-address=127.0.0.1 --cert-dir=/var/lib/rancher/k3s/server/tls/temporary-certs --client-ca-file=/var/lib/rancher/k3s/server/tls/client-ca.crt --egress-selector-config-file=/var/lib/rancher/k3s/server/etc/egress-selector-config.yaml --enable-admission-plugins=NodeRestriction,ServiceAccount --enable-aggregator-routing=true --enable-bootstrap-token-auth=true --encryption-provider-config=/var/lib/rancher/k3s/server/cred/encryption-config.json --etcd-cafile=/var/lib/rancher/k3s/server/tls/etcd/server-ca.crt --etcd-certfile=/var/lib/rancher/k3s/server/tls/etcd/client.crt --etcd-keyfile=/var/lib/rancher/k3s/server/tls/etcd/client.key --etcd-servers=https://127.0.0.1:2379 --feature-gates=JobTrackingWithFinalizers=true --kubelet-certificate-authority=/var/lib/rancher/k3s/server/tls/server-ca.crt --kubelet-client-certificate=/var/lib/rancher/k3s/server/tls/client-kube-apiserver.crt --kubelet-client-key=/var/lib/rancher/k3s/server/tls/client-kube-apiserver.key --kubelet-preferred-address-types=InternalIP,ExternalIP,Hostname --profiling=false --proxy-client-cert-file=/var/lib/rancher/k3s/server/tls/client-auth-proxy.crt --proxy-client-key-file=/var/lib/rancher/k3s/server/tls/client-auth-proxy.key --request-timeout=300s --requestheader-allowed-names=system:auth-proxy --requestheader-client-ca-file=/var/lib/rancher/k3s/server/tls/request-header-ca.crt --requestheader-extra-headers-prefix=X-Remote-Extra- --requestheader-group-headers=X-Remote-Group --requestheader-username-headers=X-Remote-User --secure-port=6444 --service-account-issuer=https://kubernetes.default.svc.cluster.local --service-account-key-file=/var/lib/rancher/k3s/server/tls/service.key --service-account-lookup=true --service-account-signing-key-file=/var/lib/rancher/k3s/server/tls/service.current.key --service-cluster-ip-range=10.43.0.0/16 --service-node-port-range=30000-32767 --storage-backend=etcd3 --tls-cert-file=/var/lib/rancher/k3s/server/tls/serving-kube-apiserver.crt --tls-cipher-suites=TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305,TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305 --tls-private-key-file=/var/lib/rancher/k3s/server/tls/serving-kube-apiserver.key" +``` + +### 3.2.2 Ensure that the audit policy covers key security concerns (Manual) + + +**Result:** warn + +**Remediation:** +Review the audit policy provided for the cluster and ensure that it covers +at least the following areas, +- Access to Secrets managed by the cluster. Care should be taken to only + log Metadata for requests to Secrets, ConfigMaps, and TokenReviews, in + order to avoid risk of logging sensitive data. +- Modification of Pod and Deployment objects. +- Use of `pods/exec`, `pods/portforward`, `pods/proxy` and `services/proxy`. +For most requests, minimally logging at the Metadata level is recommended +(the most basic level of logging). + +## 4.1 Worker Node Configuration Files +### 4.1.1 Ensure that the kubelet service file permissions are set to 600 or more restrictive (Automated) + + +**Result:** Not Applicable + +**Remediation:** +Run the below command (based on the file location on your system) on the each worker node. +For example, chmod 600 /etc/systemd/system/kubelet.service.d/10-kubeadm.conf +Not Applicable - All configuration is passed in as arguments at container run time. + +### 4.1.2 Ensure that the kubelet service file ownership is set to root:root (Automated) + + +**Result:** Not Applicable + +**Remediation:** +Run the below command (based on the file location on your system) on the each worker node. +For example, +chown root:root /etc/systemd/system/kubelet.service.d/10-kubeadm.conf +Not Applicable. + All configuration is passed in as arguments at container run time. + +### 4.1.3 If proxy kubeconfig file exists ensure permissions are set to 600 or more restrictive (Manual) + + +**Result:** warn + +**Remediation:** +Run the below command (based on the file location on your system) on the each worker node. +For example, +chmod 600 /var/lib/rancher/k3s/agent/kubeproxy.kubeconfig + +**Audit:** + +```bash +stat -c %a /var/lib/rancher/k3s/agent/kubeproxy.kubeconfig +``` + +**Expected Result**: + +```console +'permissions' is present +``` + +**Returned Value**: + +```console +600 +``` + +### 4.1.4 If proxy kubeconfig file exists ensure ownership is set to root:root (Manual) + + +**Result:** pass + +**Remediation:** +Run the below command (based on the file location on your system) on the each worker node. +For example, chown root:root /var/lib/rancher/k3s/agent/kubeproxy.kubeconfig + +**Audit:** + +```bash +/bin/sh -c 'if test -e /var/lib/rancher/k3s/agent/kubeproxy.kubeconfig; then stat -c %U:%G /var/lib/rancher/k3s/agent/kubeproxy.kubeconfig; fi' +``` + +**Expected Result**: + +```console +'root:root' is present +``` + +**Returned Value**: + +```console +root:root +``` + +### 4.1.5 Ensure that the --kubeconfig kubelet.conf file permissions are set to 600 or more restrictive (Automated) + + +**Result:** pass + +**Remediation:** +Run the below command (based on the file location on your system) on the each worker node. +For example, +chmod 600 /var/lib/rancher/k3s/server/cred/admin.kubeconfig + +**Audit:** + +```bash +/bin/sh -c 'if test -e /var/lib/rancher/k3s/server/cred/admin.kubeconfig; then stat -c permissions=%a /var/lib/rancher/k3s/server/cred/admin.kubeconfig; fi' +``` + +**Expected Result**: + +```console +permissions has permissions 600, expected 600 or more restrictive +``` + +**Returned Value**: + +```console +permissions=600 +``` + +### 4.1.6 Ensure that the --kubeconfig kubelet.conf file ownership is set to root:root (Automated) + + +**Result:** pass + +**Remediation:** +Run the below command (based on the file location on your system) on the each worker node. +For example, +chown root:root /var/lib/rancher/k3s/server/cred/admin.kubeconfig + +**Audit:** + +```bash +stat -c %U:%G /var/lib/rancher/k3s/agent/kubelet.kubeconfig +``` + +**Expected Result**: + +```console +'root:root' is present +``` + +**Returned Value**: + +```console +root:root +``` + +### 4.1.7 Ensure that the certificate authorities file permissions are set to 600 or more restrictive (Manual) + + +**Result:** warn + +**Remediation:** +Run the following command to modify the file permissions of the +--client-ca-file chmod 600 + +**Audit:** + +```bash +stat -c %a /var/lib/rancher/k3s/server/tls/server-ca.crt +``` + +**Expected Result**: + +```console +'permissions' is present +``` + +**Returned Value**: + +```console +644 +``` + +### 4.1.8 Ensure that the client certificate authorities file ownership is set to root:root (Manual) + + +**Result:** pass + +**Remediation:** +Run the following command to modify the ownership of the --client-ca-file. +chown root:root + +**Audit:** + +```bash +stat -c %U:%G /var/lib/rancher/k3s/server/tls/client-ca.crt +``` + +**Expected Result**: + +```console +'root:root' is equal to 'root:root' +``` + +**Returned Value**: + +```console +root:root +``` + +### 4.1.9 Ensure that the kubelet --config configuration file has permissions set to 600 or more restrictive (Automated) + + +**Result:** Not Applicable + +**Remediation:** +Run the following command (using the config file location identified in the Audit step) +chmod 600 /var/lib/kubelet/config.yaml + +### 4.1.10 Ensure that the kubelet --config configuration file ownership is set to root:root (Automated) + + +**Result:** Not Applicable + +**Remediation:** +Run the following command (using the config file location identified in the Audit step) +chown root:root /var/lib/kubelet/config.yaml +Not Applicable. +All configuration is passed in as arguments at container run time. + +## 4.2 Kubelet +### 4.2.1 Ensure that the --anonymous-auth argument is set to false (Automated) + + +**Result:** pass + +**Remediation:** +If using a Kubelet config file, edit the file to set `authentication: anonymous: enabled` to +`false`. +If using executable arguments, edit the kubelet service file +/etc/systemd/system/kubelet.service.d/10-kubeadm.conf on each worker node and +set the below parameter in KUBELET_SYSTEM_PODS_ARGS variable. +`--anonymous-auth=false` +Based on your system, restart the kubelet service. For example, +systemctl daemon-reload +systemctl restart kubelet.service + +**Audit:** + +```bash +/bin/sh -c 'if test $(journalctl -D /var/log/journal -u k3s | grep "Running kube-apiserver" | wc -l) -gt 0; then journalctl -D /var/log/journal -u k3s | grep "Running kube-apiserver" | tail -n1 | grep "anonymous-auth" | grep -v grep; else echo "--anonymous-auth=false"; fi' +``` + +**Expected Result**: + +```console +'--anonymous-auth' is equal to 'false' +``` + +**Returned Value**: + +```console +Sep 11 20:52:00 ip-172-31-12-34 k3s[2340]: time="2023-09-11T20:52:00Z" level=info msg="Running kube-apiserver --admission-control-config-file=/etc/rancher/k3s/config/rancher-psact.yaml --advertise-port=6443 --allow-privileged=true --anonymous-auth=false --api-audiences=https://kubernetes.default.svc.cluster.local,k3s --audit-log-maxage=30 --audit-log-maxbackup=10 --audit-log-maxsize=100 --audit-log-path=/var/lib/rancher/k3s/server/logs/audit.log --audit-policy-file=/var/lib/rancher/k3s/server/audit.yaml --authorization-mode=Node,RBAC --bind-address=127.0.0.1 --cert-dir=/var/lib/rancher/k3s/server/tls/temporary-certs --client-ca-file=/var/lib/rancher/k3s/server/tls/client-ca.crt --egress-selector-config-file=/var/lib/rancher/k3s/server/etc/egress-selector-config.yaml --enable-admission-plugins=NodeRestriction,ServiceAccount --enable-aggregator-routing=true --enable-bootstrap-token-auth=true --encryption-provider-config=/var/lib/rancher/k3s/server/cred/encryption-config.json --etcd-cafile=/var/lib/rancher/k3s/server/tls/etcd/server-ca.crt --etcd-certfile=/var/lib/rancher/k3s/server/tls/etcd/client.crt --etcd-keyfile=/var/lib/rancher/k3s/server/tls/etcd/client.key --etcd-servers=https://127.0.0.1:2379 --feature-gates=JobTrackingWithFinalizers=true --kubelet-certificate-authority=/var/lib/rancher/k3s/server/tls/server-ca.crt --kubelet-client-certificate=/var/lib/rancher/k3s/server/tls/client-kube-apiserver.crt --kubelet-client-key=/var/lib/rancher/k3s/server/tls/client-kube-apiserver.key --kubelet-preferred-address-types=InternalIP,ExternalIP,Hostname --profiling=false --proxy-client-cert-file=/var/lib/rancher/k3s/server/tls/client-auth-proxy.crt --proxy-client-key-file=/var/lib/rancher/k3s/server/tls/client-auth-proxy.key --request-timeout=300s --requestheader-allowed-names=system:auth-proxy --requestheader-client-ca-file=/var/lib/rancher/k3s/server/tls/request-header-ca.crt --requestheader-extra-headers-prefix=X-Remote-Extra- --requestheader-group-headers=X-Remote-Group --requestheader-username-headers=X-Remote-User --secure-port=6444 --service-account-issuer=https://kubernetes.default.svc.cluster.local --service-account-key-file=/var/lib/rancher/k3s/server/tls/service.key --service-account-lookup=true --service-account-signing-key-file=/var/lib/rancher/k3s/server/tls/service.current.key --service-cluster-ip-range=10.43.0.0/16 --service-node-port-range=30000-32767 --storage-backend=etcd3 --tls-cert-file=/var/lib/rancher/k3s/server/tls/serving-kube-apiserver.crt --tls-cipher-suites=TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305,TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305 --tls-private-key-file=/var/lib/rancher/k3s/server/tls/serving-kube-apiserver.key" +``` + +### 4.2.2 Ensure that the --authorization-mode argument is not set to AlwaysAllow (Automated) + + +**Result:** pass + +**Remediation:** +If using a Kubelet config file, edit the file to set `authorization.mode` to Webhook. If +using executable arguments, edit the kubelet service file +/etc/systemd/system/kubelet.service.d/10-kubeadm.conf on each worker node and +set the below parameter in KUBELET_AUTHZ_ARGS variable. +--authorization-mode=Webhook +Based on your system, restart the kubelet service. For example, +systemctl daemon-reload +systemctl restart kubelet.service + +**Audit:** + +```bash +/bin/sh -c 'if test $(journalctl -D /var/log/journal -u k3s | grep "Running kube-apiserver" | wc -l) -gt 0; then journalctl -D /var/log/journal -u k3s | grep "Running kube-apiserver" | tail -n1 | grep "authorization-mode" | grep -v grep; else echo "--authorization-mode=Webhook"; fi' +``` + +**Audit Config:** + +```bash +/bin/sh -c 'if test -e /var/lib/kubelet/config.yaml; then /bin/cat /var/lib/kubelet/config.yaml; fi' +``` + +**Expected Result**: + +```console +'--authorization-mode' does not have 'AlwaysAllow' +``` + +**Returned Value**: + +```console +Sep 11 20:52:00 ip-172-31-12-34 k3s[2340]: time="2023-09-11T20:52:00Z" level=info msg="Running kube-apiserver --admission-control-config-file=/etc/rancher/k3s/config/rancher-psact.yaml --advertise-port=6443 --allow-privileged=true --anonymous-auth=false --api-audiences=https://kubernetes.default.svc.cluster.local,k3s --audit-log-maxage=30 --audit-log-maxbackup=10 --audit-log-maxsize=100 --audit-log-path=/var/lib/rancher/k3s/server/logs/audit.log --audit-policy-file=/var/lib/rancher/k3s/server/audit.yaml --authorization-mode=Node,RBAC --bind-address=127.0.0.1 --cert-dir=/var/lib/rancher/k3s/server/tls/temporary-certs --client-ca-file=/var/lib/rancher/k3s/server/tls/client-ca.crt --egress-selector-config-file=/var/lib/rancher/k3s/server/etc/egress-selector-config.yaml --enable-admission-plugins=NodeRestriction,ServiceAccount --enable-aggregator-routing=true --enable-bootstrap-token-auth=true --encryption-provider-config=/var/lib/rancher/k3s/server/cred/encryption-config.json --etcd-cafile=/var/lib/rancher/k3s/server/tls/etcd/server-ca.crt --etcd-certfile=/var/lib/rancher/k3s/server/tls/etcd/client.crt --etcd-keyfile=/var/lib/rancher/k3s/server/tls/etcd/client.key --etcd-servers=https://127.0.0.1:2379 --feature-gates=JobTrackingWithFinalizers=true --kubelet-certificate-authority=/var/lib/rancher/k3s/server/tls/server-ca.crt --kubelet-client-certificate=/var/lib/rancher/k3s/server/tls/client-kube-apiserver.crt --kubelet-client-key=/var/lib/rancher/k3s/server/tls/client-kube-apiserver.key --kubelet-preferred-address-types=InternalIP,ExternalIP,Hostname --profiling=false --proxy-client-cert-file=/var/lib/rancher/k3s/server/tls/client-auth-proxy.crt --proxy-client-key-file=/var/lib/rancher/k3s/server/tls/client-auth-proxy.key --request-timeout=300s --requestheader-allowed-names=system:auth-proxy --requestheader-client-ca-file=/var/lib/rancher/k3s/server/tls/request-header-ca.crt --requestheader-extra-headers-prefix=X-Remote-Extra- --requestheader-group-headers=X-Remote-Group --requestheader-username-headers=X-Remote-User --secure-port=6444 --service-account-issuer=https://kubernetes.default.svc.cluster.local --service-account-key-file=/var/lib/rancher/k3s/server/tls/service.key --service-account-lookup=true --service-account-signing-key-file=/var/lib/rancher/k3s/server/tls/service.current.key --service-cluster-ip-range=10.43.0.0/16 --service-node-port-range=30000-32767 --storage-backend=etcd3 --tls-cert-file=/var/lib/rancher/k3s/server/tls/serving-kube-apiserver.crt --tls-cipher-suites=TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305,TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305 --tls-private-key-file=/var/lib/rancher/k3s/server/tls/serving-kube-apiserver.key" +``` + +### 4.2.3 Ensure that the --client-ca-file argument is set as appropriate (Automated) + + +**Result:** pass + +**Remediation:** +If using a Kubelet config file, edit the file to set `authentication.x509.clientCAFile` to +the location of the client CA file. +If using command line arguments, edit the kubelet service file +/etc/systemd/system/kubelet.service.d/10-kubeadm.conf on each worker node and +set the below parameter in KUBELET_AUTHZ_ARGS variable. +--client-ca-file= +Based on your system, restart the kubelet service. For example, +systemctl daemon-reload +systemctl restart kubelet.service + +**Audit:** + +```bash +/bin/sh -c 'if test $(journalctl -D /var/log/journal -u k3s | grep "Running kube-apiserver" | wc -l) -gt 0; then journalctl -D /var/log/journal -u k3s | grep "Running kube-apiserver" | tail -n1 | grep "client-ca-file" | grep -v grep; else echo "--client-ca-file=/var/lib/rancher/k3s/server/tls/request-header-ca.crt"; fi' +``` + +**Expected Result**: + +```console +'--client-ca-file' is present +``` + +**Returned Value**: + +```console +Sep 11 20:52:00 ip-172-31-12-34 k3s[2340]: time="2023-09-11T20:52:00Z" level=info msg="Running kube-apiserver --admission-control-config-file=/etc/rancher/k3s/config/rancher-psact.yaml --advertise-port=6443 --allow-privileged=true --anonymous-auth=false --api-audiences=https://kubernetes.default.svc.cluster.local,k3s --audit-log-maxage=30 --audit-log-maxbackup=10 --audit-log-maxsize=100 --audit-log-path=/var/lib/rancher/k3s/server/logs/audit.log --audit-policy-file=/var/lib/rancher/k3s/server/audit.yaml --authorization-mode=Node,RBAC --bind-address=127.0.0.1 --cert-dir=/var/lib/rancher/k3s/server/tls/temporary-certs --client-ca-file=/var/lib/rancher/k3s/server/tls/client-ca.crt --egress-selector-config-file=/var/lib/rancher/k3s/server/etc/egress-selector-config.yaml --enable-admission-plugins=NodeRestriction,ServiceAccount --enable-aggregator-routing=true --enable-bootstrap-token-auth=true --encryption-provider-config=/var/lib/rancher/k3s/server/cred/encryption-config.json --etcd-cafile=/var/lib/rancher/k3s/server/tls/etcd/server-ca.crt --etcd-certfile=/var/lib/rancher/k3s/server/tls/etcd/client.crt --etcd-keyfile=/var/lib/rancher/k3s/server/tls/etcd/client.key --etcd-servers=https://127.0.0.1:2379 --feature-gates=JobTrackingWithFinalizers=true --kubelet-certificate-authority=/var/lib/rancher/k3s/server/tls/server-ca.crt --kubelet-client-certificate=/var/lib/rancher/k3s/server/tls/client-kube-apiserver.crt --kubelet-client-key=/var/lib/rancher/k3s/server/tls/client-kube-apiserver.key --kubelet-preferred-address-types=InternalIP,ExternalIP,Hostname --profiling=false --proxy-client-cert-file=/var/lib/rancher/k3s/server/tls/client-auth-proxy.crt --proxy-client-key-file=/var/lib/rancher/k3s/server/tls/client-auth-proxy.key --request-timeout=300s --requestheader-allowed-names=system:auth-proxy --requestheader-client-ca-file=/var/lib/rancher/k3s/server/tls/request-header-ca.crt --requestheader-extra-headers-prefix=X-Remote-Extra- --requestheader-group-headers=X-Remote-Group --requestheader-username-headers=X-Remote-User --secure-port=6444 --service-account-issuer=https://kubernetes.default.svc.cluster.local --service-account-key-file=/var/lib/rancher/k3s/server/tls/service.key --service-account-lookup=true --service-account-signing-key-file=/var/lib/rancher/k3s/server/tls/service.current.key --service-cluster-ip-range=10.43.0.0/16 --service-node-port-range=30000-32767 --storage-backend=etcd3 --tls-cert-file=/var/lib/rancher/k3s/server/tls/serving-kube-apiserver.crt --tls-cipher-suites=TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305,TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305 --tls-private-key-file=/var/lib/rancher/k3s/server/tls/serving-kube-apiserver.key" +``` + +### 4.2.4 Verify that the --read-only-port argument is set to 0 (Manual) + + +**Result:** pass + +**Remediation:** +If using a Kubelet config file, edit the file to set `readOnlyPort` to 0. +If using command line arguments, edit the kubelet service file +/etc/systemd/system/kubelet.service.d/10-kubeadm.conf on each worker node and +set the below parameter in KUBELET_SYSTEM_PODS_ARGS variable. +--read-only-port=0 +Based on your system, restart the kubelet service. For example, +systemctl daemon-reload +systemctl restart kubelet.service + +**Audit:** + +```bash +journalctl -D /var/log/journal -u k3s | grep 'Running kubelet' | tail -n1 | grep 'read-only-port' +``` + +**Audit Config:** + +```bash +/bin/sh -c 'if test -e /var/lib/kubelet/config.yaml; then /bin/cat /var/lib/kubelet/config.yaml; fi' +``` + +**Expected Result**: + +```console +'--read-only-port' is equal to '0' OR '--read-only-port' is not present +``` + +**Returned Value**: + +```console +Sep 11 20:52:15 ip-172-31-12-34 k3s[2340]: time="2023-09-11T20:52:15Z" level=info msg="Running kubelet --address=0.0.0.0 --allowed-unsafe-sysctls=net.ipv4.ip_forward,net.ipv6.conf.all.forwarding --anonymous-auth=false --authentication-token-webhook=true --authorization-mode=Webhook --cgroup-driver=systemd --client-ca-file=/var/lib/rancher/k3s/agent/client-ca.crt --cloud-provider=external --cluster-dns=10.43.0.10 --cluster-domain=cluster.local --container-runtime-endpoint=unix:///run/k3s/containerd/containerd.sock --containerd=/run/k3s/containerd/containerd.sock --eviction-hard=imagefs.available<5%,nodefs.available<5% --eviction-minimum-reclaim=imagefs.available=10%,nodefs.available=10% --fail-swap-on=false --healthz-bind-address=127.0.0.1 --hostname-override=ip-172-31-12-34 --kubeconfig=/var/lib/rancher/k3s/agent/kubelet.kubeconfig --make-iptables-util-chains=true --node-labels=cattle.io/os=linux,rke.cattle.io/machine=af02ecbc-1e4e-422e-8b4d-4b2aa24a9d46 --pod-infra-container-image=rancher/mirrored-pause:3.6 --pod-manifest-path=/var/lib/rancher/k3s/agent/pod-manifests --protect-kernel-defaults=true --read-only-port=0 --resolv-conf=/run/systemd/resolve/resolv.conf --serialize-image-pulls=false --tls-cert-file=/var/lib/rancher/k3s/agent/serving-kubelet.crt --tls-private-key-file=/var/lib/rancher/k3s/agent/serving-kubelet.key" +``` + +### 4.2.5 Ensure that the --streaming-connection-idle-timeout argument is not set to 0 (Manual) + + +**Result:** warn + +**Remediation:** +If using a Kubelet config file, edit the file to set `streamingConnectionIdleTimeout` to a +value other than 0. +If using command line arguments, edit the kubelet service file +/etc/systemd/system/kubelet.service.d/10-kubeadm.conf on each worker node and +set the below parameter in KUBELET_SYSTEM_PODS_ARGS variable. +--streaming-connection-idle-timeout=5m +Based on your system, restart the kubelet service. For example, +systemctl daemon-reload +systemctl restart kubelet.service + +**Audit:** + +```bash +journalctl -D /var/log/journal -u k3s | grep 'Running kubelet' | tail -n1 | grep 'streaming-connection-idle-timeout' +``` + +### 4.2.6 Ensure that the --make-iptables-util-chains argument is set to true (Automated) + + +**Result:** pass + +**Remediation:** +If using a Kubelet config file, edit the file to set `makeIPTablesUtilChains` to `true`. +If using command line arguments, edit the kubelet service file +/etc/systemd/system/kubelet.service.d/10-kubeadm.conf on each worker node and +remove the --make-iptables-util-chains argument from the +KUBELET_SYSTEM_PODS_ARGS variable. +Based on your system, restart the kubelet service. For example: +systemctl daemon-reload +systemctl restart kubelet.service + +**Audit:** + +```bash +journalctl -D /var/log/journal -u k3s | grep 'Running kubelet' | tail -n1 | grep 'make-iptables-util-chains' +``` + +**Expected Result**: + +```console +'--make-iptables-util-chains' is equal to 'true' OR '--make-iptables-util-chains' is not present +``` + +**Returned Value**: + +```console +Sep 11 20:52:15 ip-172-31-12-34 k3s[2340]: time="2023-09-11T20:52:15Z" level=info msg="Running kubelet --address=0.0.0.0 --allowed-unsafe-sysctls=net.ipv4.ip_forward,net.ipv6.conf.all.forwarding --anonymous-auth=false --authentication-token-webhook=true --authorization-mode=Webhook --cgroup-driver=systemd --client-ca-file=/var/lib/rancher/k3s/agent/client-ca.crt --cloud-provider=external --cluster-dns=10.43.0.10 --cluster-domain=cluster.local --container-runtime-endpoint=unix:///run/k3s/containerd/containerd.sock --containerd=/run/k3s/containerd/containerd.sock --eviction-hard=imagefs.available<5%,nodefs.available<5% --eviction-minimum-reclaim=imagefs.available=10%,nodefs.available=10% --fail-swap-on=false --healthz-bind-address=127.0.0.1 --hostname-override=ip-172-31-12-34 --kubeconfig=/var/lib/rancher/k3s/agent/kubelet.kubeconfig --make-iptables-util-chains=true --node-labels=cattle.io/os=linux,rke.cattle.io/machine=af02ecbc-1e4e-422e-8b4d-4b2aa24a9d46 --pod-infra-container-image=rancher/mirrored-pause:3.6 --pod-manifest-path=/var/lib/rancher/k3s/agent/pod-manifests --protect-kernel-defaults=true --read-only-port=0 --resolv-conf=/run/systemd/resolve/resolv.conf --serialize-image-pulls=false --tls-cert-file=/var/lib/rancher/k3s/agent/serving-kubelet.crt --tls-private-key-file=/var/lib/rancher/k3s/agent/serving-kubelet.key" +``` + +### 4.2.7 Ensure that the --hostname-override argument is not set (Manual) + + +**Result:** Not Applicable + +**Remediation:** +Edit the kubelet service file /etc/systemd/system/kubelet.service.d/10-kubeadm.conf +on each worker node and remove the --hostname-override argument from the +KUBELET_SYSTEM_PODS_ARGS variable. +Based on your system, restart the kubelet service. For example, +systemctl daemon-reload +systemctl restart kubelet.service +Not Applicable. + +### 4.2.8 Ensure that the eventRecordQPS argument is set to a level which ensures appropriate event capture (Manual) + + +**Result:** pass + +**Remediation:** +If using a Kubelet config file, edit the file to set `eventRecordQPS` to an appropriate level. +If using command line arguments, edit the kubelet service file +/etc/systemd/system/kubelet.service.d/10-kubeadm.conf on each worker node and +set the below parameter in KUBELET_SYSTEM_PODS_ARGS variable. +Based on your system, restart the kubelet service. For example, +systemctl daemon-reload +systemctl restart kubelet.service + +**Audit:** + +```bash +/bin/ps -fC containerd +``` + +**Audit Config:** + +```bash +/bin/sh -c 'if test -e /var/lib/kubelet/config.yaml; then /bin/cat /var/lib/kubelet/config.yaml; fi' +``` + +**Expected Result**: + +```console +'--event-qps' is present OR '--event-qps' is not present +``` + +**Returned Value**: + +```console +UID PID PPID C STIME TTY TIME CMD root 527 1 0 Sep11 ? 00:01:28 /usr/bin/containerd root 2361 2340 3 Sep11 ? 00:40:19 containerd -c /var/lib/rancher/k3s/agent/etc/containerd/config.toml -a /run/k3s/containerd/containerd.sock --state /run/k3s/containerd --root /var/lib/rancher/k3s/agent/containerd +``` + +### 4.2.9 Ensure that the --tls-cert-file and --tls-private-key-file arguments are set as appropriate (Manual) + + +**Result:** Not Applicable + +**Remediation:** +If using a Kubelet config file, edit the file to set `tlsCertFile` to the location +of the certificate file to use to identify this Kubelet, and `tlsPrivateKeyFile` +to the location of the corresponding private key file. +If using command line arguments, edit the kubelet service file +/etc/systemd/system/kubelet.service.d/10-kubeadm.conf on each worker node and +set the below parameters in KUBELET_CERTIFICATE_ARGS variable. +--tls-cert-file= +--tls-private-key-file= +Based on your system, restart the kubelet service. For example, +systemctl daemon-reload +systemctl restart kubelet.service +Permissive - When generating serving certificates, functionality could break in conjunction with hostname overrides which are required for certain cloud providers. + +### 4.2.10 Ensure that the --rotate-certificates argument is not set to false (Manual) + + +**Result:** pass + +**Remediation:** +If using a Kubelet config file, edit the file to add the line `rotateCertificates` to `true` or +remove it altogether to use the default value. +If using command line arguments, edit the kubelet service file +/etc/systemd/system/kubelet.service.d/10-kubeadm.conf on each worker node and +remove --rotate-certificates=false argument from the KUBELET_CERTIFICATE_ARGS +variable. +Based on your system, restart the kubelet service. For example, +systemctl daemon-reload +systemctl restart kubelet.service + +**Audit:** + +```bash +/bin/ps -fC containerd +``` + +**Audit Config:** + +```bash +/bin/sh -c 'if test -e /var/lib/kubelet/config.yaml; then /bin/cat /var/lib/kubelet/config.yaml; fi' +``` + +**Expected Result**: + +```console +'--rotate-certificates' is present OR '--rotate-certificates' is not present +``` + +**Returned Value**: + +```console +UID PID PPID C STIME TTY TIME CMD root 527 1 0 Sep11 ? 00:01:28 /usr/bin/containerd root 2361 2340 3 Sep11 ? 00:40:19 containerd -c /var/lib/rancher/k3s/agent/etc/containerd/config.toml -a /run/k3s/containerd/containerd.sock --state /run/k3s/containerd --root /var/lib/rancher/k3s/agent/containerd +``` + +### 4.2.11 Verify that the RotateKubeletServerCertificate argument is set to true (Manual) + + +**Result:** pass + +**Remediation:** +Edit the kubelet service file /etc/systemd/system/kubelet.service.d/10-kubeadm.conf +on each worker node and set the below parameter in KUBELET_CERTIFICATE_ARGS variable. +--feature-gates=RotateKubeletServerCertificate=true +Based on your system, restart the kubelet service. For example: +systemctl daemon-reload +systemctl restart kubelet.service +Not Applicable. + +**Audit:** + +```bash +/bin/ps -fC containerd +``` + +**Audit Config:** + +```bash +/bin/cat /var/lib/kubelet/config.yaml +``` + +**Expected Result**: + +```console +'RotateKubeletServerCertificate' is present OR 'RotateKubeletServerCertificate' is not present +``` + +**Returned Value**: + +```console +UID PID PPID C STIME TTY TIME CMD root 527 1 0 Sep11 ? 00:01:28 /usr/bin/containerd root 2361 2340 3 Sep11 ? 00:40:19 containerd -c /var/lib/rancher/k3s/agent/etc/containerd/config.toml -a /run/k3s/containerd/containerd.sock --state /run/k3s/containerd --root /var/lib/rancher/k3s/agent/containerd +``` + +### 4.2.12 Ensure that the Kubelet only makes use of Strong Cryptographic Ciphers (Manual) + + +**Result:** warn + +**Remediation:** +If using a Kubelet config file, edit the file to set `TLSCipherSuites` to +TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305,TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,TLS_RSA_WITH_AES_256_GCM_SHA384,TLS_RSA_WITH_AES_128_GCM_SHA256 +or to a subset of these values. +If using executable arguments, edit the kubelet service file +/etc/systemd/system/kubelet.service.d/10-kubeadm.conf on each worker node and +set the --tls-cipher-suites parameter as follows, or to a subset of these values. +--tls-cipher-suites=TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305,TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,TLS_RSA_WITH_AES_256_GCM_SHA384,TLS_RSA_WITH_AES_128_GCM_SHA256 +Based on your system, restart the kubelet service. For example: +systemctl daemon-reload +systemctl restart kubelet.service + +**Audit:** + +```bash +/bin/ps -fC containerd +``` + +**Audit Config:** + +```bash +/bin/sh -c 'if test -e /var/lib/kubelet/config.yaml; then /bin/cat /var/lib/kubelet/config.yaml; fi' +``` + +**Expected Result**: + +```console +'--tls-cipher-suites' is present +``` + +**Returned Value**: + +```console +UID PID PPID C STIME TTY TIME CMD root 527 1 0 Sep11 ? 00:01:28 /usr/bin/containerd root 2361 2340 3 Sep11 ? 00:40:19 containerd -c /var/lib/rancher/k3s/agent/etc/containerd/config.toml -a /run/k3s/containerd/containerd.sock --state /run/k3s/containerd --root /var/lib/rancher/k3s/agent/containerd +``` + +### 4.2.13 Ensure that a limit is set on pod PIDs (Manual) + + +**Result:** warn + +**Remediation:** +Decide on an appropriate level for this parameter and set it, +either via the --pod-max-pids command line parameter or the PodPidsLimit configuration file setting. + +**Audit:** + +```bash +/bin/ps -fC containerd +``` + +**Audit Config:** + +```bash +/bin/sh -c 'if test -e /var/lib/kubelet/config.yaml; then /bin/cat /var/lib/kubelet/config.yaml; fi' +``` + +**Expected Result**: + +```console +'--pod-max-pids' is present +``` + +**Returned Value**: + +```console +UID PID PPID C STIME TTY TIME CMD root 527 1 0 Sep11 ? 00:01:28 /usr/bin/containerd root 2361 2340 3 Sep11 ? 00:40:19 containerd -c /var/lib/rancher/k3s/agent/etc/containerd/config.toml -a /run/k3s/containerd/containerd.sock --state /run/k3s/containerd --root /var/lib/rancher/k3s/agent/containerd +``` + +## 5.1 RBAC and Service Accounts +### 5.1.1 Ensure that the cluster-admin role is only used where required (Manual) + + +**Result:** warn + +**Remediation:** +Identify all clusterrolebindings to the cluster-admin role. Check if they are used and +if they need this role or if they could use a role with fewer privileges. +Where possible, first bind users to a lower privileged role and then remove the +clusterrolebinding to the cluster-admin role : +kubectl delete clusterrolebinding [name] + +### 5.1.2 Minimize access to secrets (Manual) + + +**Result:** warn + +**Remediation:** +Where possible, remove get, list and watch access to Secret objects in the cluster. + +### 5.1.3 Minimize wildcard use in Roles and ClusterRoles (Manual) + + +**Result:** warn + +**Remediation:** +Where possible replace any use of wildcards in clusterroles and roles with specific +objects or actions. + +### 5.1.4 Minimize access to create pods (Manual) + + +**Result:** warn + +**Remediation:** +Where possible, remove create access to pod objects in the cluster. + +### 5.1.5 Ensure that default service accounts are not actively used. (Manual) + + +**Result:** pass + +**Remediation:** +Create explicit service accounts wherever a Kubernetes workload requires specific access +to the Kubernetes API server. +Modify the configuration of each default service account to include this value +automountServiceAccountToken: false + +**Audit Script:** `check_for_default_sa.sh` + +```bash +#!/bin/bash + +set -eE + +handle_error() { + echo "false" +} + +trap 'handle_error' ERR + +count_sa=$(kubectl get serviceaccounts --all-namespaces -o json | jq -r '.items[] | select(.metadata.name=="default") | select((.automountServiceAccountToken == null) or (.automountServiceAccountToken == true))' | jq .metadata.namespace | wc -l) +if [[ ${count_sa} -gt 0 ]]; then + echo "false" + exit +fi + +for ns in $(kubectl get ns --no-headers -o custom-columns=":metadata.name") +do + for result in $(kubectl get clusterrolebinding,rolebinding -n $ns -o json | jq -r '.items[] | select((.subjects[]?.kind=="ServiceAccount" and .subjects[]?.name=="default") or (.subjects[]?.kind=="Group" and .subjects[]?.name=="system:serviceaccounts"))' | jq -r '"\(.roleRef.kind),\(.roleRef.name)"') + do + read kind name <<<$(IFS=","; echo $result) + resource_count=$(kubectl get $kind $name -n $ns -o json | jq -r '.rules[] | select(.resources[]? != "podsecuritypolicies")' | wc -l) + if [[ ${resource_count} -gt 0 ]]; then + echo "false" + exit + fi + done +done + + +echo "true" + +``` + +**Audit Execution:** + +```bash +./check_for_default_sa.sh +``` + +**Expected Result**: + +```console +'true' is equal to 'true' +``` + +**Returned Value**: + +```console +true +``` + +### 5.1.6 Ensure that Service Account Tokens are only mounted where necessary (Manual) + + +**Result:** warn + +**Remediation:** +Modify the definition of pods and service accounts which do not need to mount service +account tokens to disable it. + +### 5.1.7 Avoid use of system:masters group (Manual) + + +**Result:** warn + +**Remediation:** +Remove the system:masters group from all users in the cluster. + +### 5.1.8 Limit use of the Bind, Impersonate and Escalate permissions in the Kubernetes cluster (Manual) + + +**Result:** warn + +**Remediation:** +Where possible, remove the impersonate, bind and escalate rights from subjects. + +### 5.1.9 Minimize access to create persistent volumes (Manual) + + +**Result:** warn + +**Remediation:** +Where possible, remove create access to PersistentVolume objects in the cluster. + +### 5.1.10 Minimize access to the proxy sub-resource of nodes (Manual) + + +**Result:** warn + +**Remediation:** +Where possible, remove access to the proxy sub-resource of node objects. + +### 5.1.11 Minimize access to the approval sub-resource of certificatesigningrequests objects (Manual) + + +**Result:** warn + +**Remediation:** +Where possible, remove access to the approval sub-resource of certificatesigningrequest objects. + +### 5.1.12 Minimize access to webhook configuration objects (Manual) + + +**Result:** warn + +**Remediation:** +Where possible, remove access to the validatingwebhookconfigurations or mutatingwebhookconfigurations objects + +### 5.1.13 Minimize access to the service account token creation (Manual) + + +**Result:** warn + +**Remediation:** +Where possible, remove access to the token sub-resource of serviceaccount objects. + +## 5.2 Pod Security Standards +### 5.2.1 Ensure that the cluster has at least one active policy control mechanism in place (Manual) + + +**Result:** warn + +**Remediation:** +Ensure that either Pod Security Admission or an external policy control system is in place +for every namespace which contains user workloads. + +### 5.2.2 Minimize the admission of privileged containers (Manual) + + +**Result:** warn + +**Remediation:** +Add policies to each namespace in the cluster which has user workloads to restrict the +admission of privileged containers. + +### 5.2.3 Minimize the admission of containers wishing to share the host process ID namespace (Automated) + + +**Result:** warn + +**Remediation:** +Add policies to each namespace in the cluster which has user workloads to restrict the +admission of `hostPID` containers. + +### 5.2.4 Minimize the admission of containers wishing to share the host IPC namespace (Automated) + + +**Result:** warn + +**Remediation:** +Add policies to each namespace in the cluster which has user workloads to restrict the +admission of `hostIPC` containers. + +### 5.2.5 Minimize the admission of containers wishing to share the host network namespace (Automated) + + +**Result:** warn + +**Remediation:** +Add policies to each namespace in the cluster which has user workloads to restrict the +admission of `hostNetwork` containers. + +### 5.2.6 Minimize the admission of containers with allowPrivilegeEscalation (Automated) + + +**Result:** warn + +**Remediation:** +Add policies to each namespace in the cluster which has user workloads to restrict the +admission of containers with `.spec.allowPrivilegeEscalation` set to `true`. + +### 5.2.7 Minimize the admission of root containers (Automated) + + +**Result:** warn + +**Remediation:** +Create a policy for each namespace in the cluster, ensuring that either `MustRunAsNonRoot` +or `MustRunAs` with the range of UIDs not including 0, is set. + +### 5.2.8 Minimize the admission of containers with the NET_RAW capability (Automated) + + +**Result:** warn + +**Remediation:** +Add policies to each namespace in the cluster which has user workloads to restrict the +admission of containers with the `NET_RAW` capability. + +### 5.2.9 Minimize the admission of containers with added capabilities (Automated) + + +**Result:** warn + +**Remediation:** +Ensure that `allowedCapabilities` is not present in policies for the cluster unless +it is set to an empty array. + +### 5.2.10 Minimize the admission of containers with capabilities assigned (Manual) + + +**Result:** warn + +**Remediation:** +Review the use of capabilites in applications running on your cluster. Where a namespace +contains applicaions which do not require any Linux capabities to operate consider adding +a PSP which forbids the admission of containers which do not drop all capabilities. + +### 5.2.11 Minimize the admission of Windows HostProcess containers (Manual) + + +**Result:** warn + +**Remediation:** +Add policies to each namespace in the cluster which has user workloads to restrict the +admission of containers that have `.securityContext.windowsOptions.hostProcess` set to `true`. + +### 5.2.12 Minimize the admission of HostPath volumes (Manual) + + +**Result:** warn + +**Remediation:** +Add policies to each namespace in the cluster which has user workloads to restrict the +admission of containers with `hostPath` volumes. + +### 5.2.13 Minimize the admission of containers which use HostPorts (Manual) + + +**Result:** warn + +**Remediation:** +Add policies to each namespace in the cluster which has user workloads to restrict the +admission of containers which use `hostPort` sections. + +## 5.3 Network Policies and CNI +### 5.3.1 Ensure that the CNI in use supports NetworkPolicies (Manual) + + +**Result:** warn + +**Remediation:** +If the CNI plugin in use does not support network policies, consideration should be given to +making use of a different plugin, or finding an alternate mechanism for restricting traffic +in the Kubernetes cluster. + +### 5.3.2 Ensure that all Namespaces have NetworkPolicies defined (Manual) + + +**Result:** warn + +**Remediation:** +Follow the documentation and create NetworkPolicy objects as you need them. + +## 5.4 Secrets Management +### 5.4.1 Prefer using Secrets as files over Secrets as environment variables (Manual) + + +**Result:** warn + +**Remediation:** +If possible, rewrite application code to read Secrets from mounted secret files, rather than +from environment variables. + +### 5.4.2 Consider external secret storage (Manual) + + +**Result:** warn + +**Remediation:** +Refer to the Secrets management options offered by your cloud provider or a third-party +secrets management solution. + +## 5.5 Extensible Admission Control +### 5.5.1 Configure Image Provenance using ImagePolicyWebhook admission controller (Manual) + + +**Result:** warn + +**Remediation:** +Follow the Kubernetes documentation and setup image provenance. + +## 5.7 General Policies +### 5.7.1 Create administrative boundaries between resources using namespaces (Manual) + + +**Result:** warn + +**Remediation:** +Follow the documentation and create namespaces for objects in your deployment as you need +them. + +### 5.7.2 Ensure that the seccomp profile is set to docker/default in your Pod definitions (Manual) + + +**Result:** warn + +**Remediation:** +Use `securityContext` to enable the docker/default seccomp profile in your pod definitions. +An example is as below: + securityContext: + seccompProfile: + type: RuntimeDefault + +### 5.7.3 Apply SecurityContext to your Pods and Containers (Manual) + + +**Result:** warn + +**Remediation:** +Follow the Kubernetes documentation and apply SecurityContexts to your Pods. For a +suggested list of SecurityContexts, you may refer to the CIS Security Benchmark for Docker +Containers. + +### 5.7.4 The default namespace should not be used (Manual) + + +**Result:** warn + +**Remediation:** +Ensure that namespaces are created to allow for appropriate segregation of Kubernetes +resources and that all new resources are created in a specific namespace. + diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/rancher-security/hardening-guides/rke2-hardening-guide/rke2-hardening-guide.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/rancher-security/hardening-guides/rke2-hardening-guide/rke2-hardening-guide.md new file mode 100644 index 00000000000..431d87bb1ed --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/rancher-security/hardening-guides/rke2-hardening-guide/rke2-hardening-guide.md @@ -0,0 +1,273 @@ +--- +title: RKE2 加固指南 +--- + + + + + +本文档提供了针对生产环境的 RKE2 集群进行加固的具体指导，以便在使用 Rancher 部署之前进行配置。它概述了满足信息安全中心（Center for Information Security, CIS）Kubernetes benchmark controls 制所需的配置和控制。 + +:::note +这份加固指南描述了如何确保你集群中的节点安全。我们建议你在安装 Kubernetes 之前遵循本指南。 +::: + +此加固指南适用于 RKE2 集群，并与以下版本的 CIS Kubernetes Benchmark、Kubernetes 和 Rancher 相关联： + +| Rancher 版本 | CIS Benchmark 版本 | Kubernetes 版本 | +|-----------------|-----------------------|------------------------------| +| Rancher v2.7 | Benchmark v1.23 | Kubernetes v1.23 | +| Rancher v2.7 | Benchmark v1.24 | Kubernetes v1.24 | +| Rancher v2.7 | Benchmark v1.7 | Kubernetes v1.25 至 v1.26 | + +:::note +- 在 Benchmark v1.24 及更高版本中，由于新的文件权限要求（600 而不是 644），一些检查 ID 可能会失败。受影响的检查 ID 包括：`1.1.1`, `1.1.3`, `1.1.5`, `1.1.7`, `1.1.13`, `1.1.15`, `1.1.17`, `4.1.3`, `4.1.5` 和 `4.1.9`。 +- 在 Benchmark v1.7 中，不再需要 `--protect-kernel-defaults` (4.2.6) 参数，并已被 CIS 删除。 +::: + +有关如何评估加固的 RKE2 集群与官方 CIS benchmark 的更多细节，请参考特定 Kubernetes 和 CIS benchmark 版本的 RKE2 自我评估指南。 + +RKE2 在不需要修改的情况下通过了许多 Kubernetes CIS controls，因为它默认应用了几个安全缓解措施。然而，有一些值得注意的例外情况，需要手动干预才能完全符合 CIS Benchmark 要求： + +1. RKE2 不会修改主机操作系统。因此，作为运维人员，你必须进行一些主机级别的修改。 +2. 某些 CIS controls 对于网络策略和 Pod 安全标准（或 RKE2 v1.25 之前的 Pod 安全策略 (PSP)）将限制集群的功能。你必须选择让 RKE2 为你配置这些功能。为了确保满足这些要求，可以启动 RKE2 并设置 profile 标志为 `cis-1.23`（适用于 v1.25 及更新版本）或 `cis-1.6`（适用于 v1.24 及更早版本）。 + +## 主机级别要求 + +主机级要求有两个方面：内核参数和 etcd 进程/目录配置。这些在本节中进行了概述。 + +### 确保 `protect-kernel-defaults` 已经设置 + + + + +自 CIS benchmark 1.7 开始，不再需要`protect-kernel-defaults`。 + + + + +这是一个 kubelet 标志，如果所需的内核参数未设置或设置为与 kubelet 的默认值不同的值，将导致 kubelet 退出。 + +可以在 Rancher 的集群配置中设置 `protect-kernel-defaults` 标志。 + +```yaml +spec: + rkeConfig: + machineSelectorConfig: + - config: + protect-kernel-defaults: true +``` + + + + +### 设置内核参数 + +建议为集群中的所有节点类型设置以下 `sysctl` 配置。在 `/etc/sysctl.d/90-kubelet.conf` 中设置以下参数： + +```ini +vm.panic_on_oom=0 +vm.overcommit_memory=1 +kernel.panic=10 +kernel.panic_on_oops=1 +``` + +运行 `sudo sysctl -p /etc/sysctl.d/90-kubelet.conf` 以启用设置。 + +### 确保 etcd 配置正确 + +CIS Benchmark 要求 etcd 数据目录由 `etcd` 用户和组拥有。这意味着 etcd 进程必须以主机级别的 `etcd` 用户身份运行。为了实现这一点，在使用有效的 `cis-1.xx` 配置文件启动 RKE2 时，RKE2 会采取以下几个步骤： + +1. 检查主机上是否存在 `etcd` 用户和组。如果不存在，则显示错误并退出。 +2. 使用 `etcd` 作为用户和组所有者创建 etcd 的数据目录。 +3. 通过适当设置 etcd 静态 Pod 的 `SecurityContext`，确保 etcd 进程以 `etcd` 用户和组的身份运行。 + +为满足上述要求，你必须执行以下操作： + +#### 创建 etcd 用户 + +在某些 Linux 发行版中，`useradd` 命令不会创建组。下面包含了 `-U` 标志来解决这个问题。这个标志告诉 `useradd` 创建一个与用户同名的组。 + +```bash +sudo useradd -r -c "etcd user" -s /sbin/nologin -M etcd -U +``` + +## Kubernetes 运行时要求 + +通过 CIS Benchmark 测试的运行时要求主要集中在 Pod 安全、网络策略和内核参数上。当使用有效的 `cis-1.xx` 配置文件时，大部分都会被 RKE2 自动处理，但需要一些额外的运维人员干预是。本节概述了这些内容。 + +### Pod 安全 + +RKE2 始终以一定程度的 Pod 安全性运行。 + + + + +在 v1.25 及更高版本中，[Pod 安全准入(PSAs)](https://kubernetes.io/docs/concepts/security/pod-security-admission/)用于保证 pod 安全。 + +以下是确保加固 RKE2 通过 Rancher 中提供的 CIS v1.23 加固配置文件 `rke2-cis-1.7-hardened` 所需的最低配置。 + +```yaml +spec: + defaultPodSecurityAdmissionConfigurationTemplateName: rancher-restricted + rkeConfig: + machineSelectorConfig: + - config: + profile: cis-1.23 +``` + +当同时设置了 `defaultPodSecurityAdmissionConfigurationTemplateName` 和 `profile` 标志时，Rancher 和 RKE2 会执行以下操作： + +1. 检查是否已满足主机级要求。如果未满足，RKE2 将以致命错误退出，并描述未满足的要求。 +2. 应用允许群集传递关联 controls 的网络策略。 +3. 配置 Pod 安全准入控制器（PSA）使用 PSA 配置模板 `rancher-restricted`，以在所有命名空间中强制执行受限模式，除了模板豁免列表中的命名空间。 + 这些命名空间被豁免，以允许系统 Pod 在没有限制的情况下运行，这是集群正常运行所必需的。 + +:::note +如果你打算将一个 RKE 集群导入到 Rancher 中，请参考[文档](../../../../how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/psa-config-templates.md)了解如何配置 PSA 以豁免 Rancher system 命名空间。 +::: + + + + + +在 Kubernetes v1.24 及更早版本中，`PodSecurityPolicy` 准入控制器始终是启用的。 + +以下是确保 RKE2 加固以通过 Rancher 中提供的 CIS v1.23 加固配置文件 `rke2-cis-1.23-hardened` 所需的最低配置。 + +:::note +在下面的示例中，配置文件设置为`cis-1.6`，这是在上游 RKE2 中定义的值，但集群实际上配置为传递 CIS v1.23 加固配置文件 +::: + +```yaml +spec: + defaultPodSecurityPolicyTemplateName: restricted-noroot + rkeConfig: + machineSelectorConfig: + - config: + profile: cis-1.6 +``` + + +当同时设置了 `defaultPodSecurityPolicyTemplateName` 和 `profile` 标志时，Rancher 和 RKE2 会执行以下操作： + +1. 检查是否已满足主机级要求。如果未满足，RKE2 将以致命错误退出，并描述未满足的要求。 +2. 应用网络策略，以确保集群通过相关的 controls 要求。 +3. 配置运行时 Pod 安全策略，以确保集群通过相关的 controls 要求。 + + + + +:::note +Kubernetes control plane 组件以及关键的附加组件，如 CNI、DNS 和 Ingress，都作为 `kube-system` 命名空间中的 Pod 运行。因此，这个命名空间的限制政策较少，从而使这些组件能够正常运行。 +::: + +### 网络策略 + +当使用有效的 `cis-1.xx` 配置文件运行时，RKE2 将设置适当的 `NetworkPolicies`，以满足 Kubernetes 内置命名空间的 CIS Benchmark 要求。这些命名空间包括：`kube-system`、`kube-public`、`kube-node-lease` 和 `default`。 + +所使用的 `NetworkPolicy` 仅允许同一命名空间内的 Pod 相互通信。值得注意的例外是允许 DNS 请求进行解析。 + +:::note +运维人员必须像管理其他命名空间一样管理额外创建的命名空间的网络策略。 +::: + +### 配置 `default` service account + +**将 `default` service accountsSet 的 `automountServiceAccountToken` 设置为 `false`** + +Kubernetes 提供了一个 `default` service account，用于集群工作负载，在 pod 没有分配特定 service account 时使用。如果需要从 pod 访问 Kubernetes API，则应为该 pod 创建一个特定的 service account，并授予该 service account 权限。`default` service account 应配置为不提供 service account 令牌，并且不具有任何明确的权限分配。 + +对于标准的 RKE2 安装中的每个命名空间，包括 `default` 和 `kube-system`，`default` service account 必须包含此值： + +```yaml +automountServiceAccountToken: false +``` + +对于由集群操作员创建的命名空间，可以使用以下脚本和配置文件来配置 `default` service account。 + +以下配置必须保存到一个名为 `account_update.yaml` 的文件中。 + +```yaml +apiVersion: v1 +kind: ServiceAccount +metadata: + name: default +automountServiceAccountToken: false +``` + +创建一个名为 `account_update.sh` 的 bash 脚本文件。确保运行 `sudo chmod +x account_update.sh` 命令，以便脚本具有执行权限。 + +```bash +#!/bin/bash -e + +for namespace in $(kubectl get namespaces -A -o=jsonpath="{.items[*]['metadata.name']}"); do + echo -n "Patching namespace $namespace - " + kubectl patch serviceaccount default -n ${namespace} -p "$(cat account_update.yaml)" +done +``` + +执行此脚本以将 `account_update.yaml` 配置应用到所有命名空间中的 `default` service account。 + +### API server 审计配置 + +CIS 要求 1.2.19 至 1.2.22 与为 API server 配置审计日志有关。当 RKE2 在设置配置文件标志的情况下启动时，它将自动在 API server 中配置加固的 `--audit-log-` 参数以通过这些 CIS 检查。 + +RKE2 的默认审计策略被配置为不记录 API server 中的请求。这样做是为了允许集群操作员灵活地定制符合其审计要求和需求的审计策略，因为这些策略是针对每个用户的环境和政策而特定的。 + +当使用 `profile` 标志启动 RKE2 时，RKE2 会创建一个默认的审计策略。该策略定义在 `/etc/rancher/rke2/audit-policy.yaml` 中。 + +```yaml +apiVersion: audit.k8s.io/v1 +kind: Policy +metadata: + creationTimestamp: null +rules: +- level: None +``` + +## 加固的 RKE2 模板配置参考 + +参考模板配置用于在 Rancher 中创建加固的 RKE2 自定义集群。该参考不包括其他必需的**集群配置**指令，这些指令会根据你的环境而有所不同。 + + + + +```yaml +apiVersion: provisioning.cattle.io/v1 +kind: Cluster +metadata: + name: # 定义集群名称 +spec: + defaultPodSecurityAdmissionConfigurationTemplateName: rancher-restricted + kubernetesVersion: # 定义 RKE2 版本 + rkeConfig: + machineSelectorConfig: + - config: + profile: cis-1.23 +``` + + + + +```yaml +apiVersion: provisioning.cattle.io/v1 +kind: Cluster +metadata: + name: # 定义集群名称 +spec: + defaultPodSecurityPolicyTemplateName: restricted-noroot + kubernetesVersion: # 定义 RKE2 版本 + rkeConfig: + machineSelectorConfig: + - config: + profile: cis-1.6 + protect-kernel-defaults: true +``` + + + + +## 结论 + +如果你按照本指南操作，由 Rancher 提供的 RKE2 自定义集群将配置为通过 CIS Kubernetes Benchmark 测试。你可以查看我们的 RKE2 自我评估指南，了解我们是如何验证每个 benchmarks 的，并且你可以在你的集群上执行相同的操作。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/rancher-security/hardening-guides/rke2-hardening-guide/rke2-self-assessment-guide-with-cis-v1.7-k8s-v1.25-v1.26-v1.27.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/rancher-security/hardening-guides/rke2-hardening-guide/rke2-self-assessment-guide-with-cis-v1.7-k8s-v1.25-v1.26-v1.27.md new file mode 100644 index 00000000000..a51c617eea8 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/rancher-security/hardening-guides/rke2-hardening-guide/rke2-self-assessment-guide-with-cis-v1.7-k8s-v1.25-v1.26-v1.27.md @@ -0,0 +1,2967 @@ +--- +title: RKE2 自我评估指南 - CIS Benchmark v1.7 - K8s v1.25/v1.26/v1.27 +--- + + + + + +本文档是 [RKE2 加固指南](rke2-hardening-guide.md)的配套文档，该指南提供了关于如何加固正在生产环境中运行并由 Rancher 管理的 RKE2 集群的指导方针。本 benchmark 指南可帮助你根据 CIS Kubernetes Benchmark 中的每个 control 来评估加固集群的安全性。 + +本指南对应以下版本的 Rancher、CIS Benchmarks 和 Kubernetes： + +| Rancher 版本 | CIS Benchmark 版本 | Kubernetes 版本 | +|-----------------|-----------------------|--------------------| +| Rancher v2.7 | Benchmark v1.7 | Kubernetes v1.25/v1.26/v1.27 | + +本指南将介绍各种 controls，并提供更新的示例命令来审计 Rancher 创建的集群中的合规性。由于 Rancher 和 RKE2 将 Kubernetes 服务安装为 Docker 容器，因此 CIS Kubernetes Benchmark 中的许多 control 验证检查不适用。这些检查将返回 `Not Applicable` 的结果。 + +本文档适用于 Rancher 运维人员、安全团队、审计员和决策者。 + +有关每个 control 的更多信息，包括详细描述和未通过测试的补救措施，请参考 CIS Kubernetes Benchmark v1.7 的相应部分。你可以在[互联网安全中心 (CIS)](https://www.cisecurity.org/benchmark/kubernetes/)创建免费账户后下载 benchmark。 + +## 测试方法 + +RKE2 将 control plane 组件作为静态 Pod 启动，由 kubelet 管理，并使用 containerd 作为容器运行时。配置是由初始化时或通过配置文件传递给容器的参数定义的。 + +在 control 审计与原始 CIS benchmark 不同时，提供了针对 Rancher 的特定审计命令以进行测试。在执行测试时，你将需要访问所有 RKE2 节点主机上的命令行。这些命令还使用了 [kubectl](https://kubernetes.io/docs/tasks/tools/)（带有有效的配置文件）和 [jq](https://stedolan.github.io/jq/) 工具，在测试和评估测试结果时这些工具是必需的。 + +:::note + +本指南仅涵盖 `automated`（之前称为 `scored`）测试。 + +::: + +### Controls + +## 1.1 Control Plane Node Configuration Files +### 1.1.1 Ensure that the API server pod specification file permissions are set to 600 or more restrictive (Automated) + + +**Result:** fail + +**Remediation:** +Run the below command (based on the file location on your system) on the +control plane node. +For example, chmod 600 /var/lib/rancher/rke2/agent/pod-manifests/kube-apiserver.yaml + +**Audit:** + +```bash +stat -c permissions=%a /var/lib/rancher/rke2/agent/pod-manifests/kube-apiserver.yaml +``` + +**Expected Result**: + +```console +permissions has permissions 644, expected 600 or more restrictive +``` + +**Returned Value**: + +```console +permissions=644 +``` + +### 1.1.2 Ensure that the API server pod specification file ownership is set to root:root (Automated) + + +**Result:** pass + +**Remediation:** +Run the below command (based on the file location on your system) on the control plane node. +For example, chown root:root /var/lib/rancher/rke2/agent/pod-manifests/kube-apiserver.yaml + +**Audit:** + +```bash +/bin/sh -c 'if test -e /var/lib/rancher/rke2/agent/pod-manifests/kube-apiserver.yaml; then stat -c %U:%G /var/lib/rancher/rke2/agent/pod-manifests/kube-apiserver.yaml; fi' +``` + +**Expected Result**: + +```console +'root:root' is equal to 'root:root' +``` + +**Returned Value**: + +```console +root:root +``` + +### 1.1.3 Ensure that the controller manager pod specification file permissions are set to 600 or more restrictive (Automated) + + +**Result:** fail + +**Remediation:** +Run the below command (based on the file location on your system) on the control plane node. +For example, chmod 600 /var/lib/rancher/rke2/agent/pod-manifests/kube-controller-manager.yaml + +**Audit:** + +```bash +/bin/sh -c 'if test -e /var/lib/rancher/rke2/agent/pod-manifests/kube-controller-manager.yaml; then stat -c permissions=%a /var/lib/rancher/rke2/agent/pod-manifests/kube-controller-manager.yaml; fi' +``` + +**Expected Result**: + +```console +permissions has permissions 644, expected 600 or more restrictive +``` + +**Returned Value**: + +```console +permissions=644 +``` + +### 1.1.4 Ensure that the controller manager pod specification file ownership is set to root:root (Automated) + + +**Result:** pass + +**Remediation:** +Run the below command (based on the file location on your system) on the control plane node. +For example, chown root:root /var/lib/rancher/rke2/agent/pod-manifests/kube-controller-manager.yaml + +**Audit:** + +```bash +/bin/sh -c 'if test -e /var/lib/rancher/rke2/agent/pod-manifests/kube-controller-manager.yaml; then stat -c %U:%G /var/lib/rancher/rke2/agent/pod-manifests/kube-controller-manager.yaml; fi' +``` + +**Expected Result**: + +```console +'root:root' is equal to 'root:root' +``` + +**Returned Value**: + +```console +root:root +``` + +### 1.1.5 Ensure that the scheduler pod specification file permissions are set to 600 or more restrictive (Automated) + + +**Result:** fail + +**Remediation:** +Run the below command (based on the file location on your system) on the control plane node. +For example, chmod 600 /var/lib/rancher/rke2/agent/pod-manifests/kube-scheduler.yaml + +**Audit:** + +```bash +/bin/sh -c 'if test -e /var/lib/rancher/rke2/agent/pod-manifests/kube-scheduler.yaml; then stat -c permissions=%a /var/lib/rancher/rke2/agent/pod-manifests/kube-scheduler.yaml; fi' +``` + +**Expected Result**: + +```console +permissions has permissions 644, expected 600 or more restrictive +``` + +**Returned Value**: + +```console +permissions=644 +``` + +### 1.1.6 Ensure that the scheduler pod specification file ownership is set to root:root (Automated) + + +**Result:** pass + +**Remediation:** +Run the below command (based on the file location on your system) on the control plane node. +For example, chown root:root /var/lib/rancher/rke2/agent/pod-manifests/kube-scheduler.yaml + +**Audit:** + +```bash +/bin/sh -c 'if test -e /var/lib/rancher/rke2/agent/pod-manifests/kube-scheduler.yaml; then stat -c %U:%G /var/lib/rancher/rke2/agent/pod-manifests/kube-scheduler.yaml; fi' +``` + +**Expected Result**: + +```console +'root:root' is present +``` + +**Returned Value**: + +```console +root:root +``` + +### 1.1.7 Ensure that the etcd pod specification file permissions are set to 600 or more restrictive (Automated) + + +**Result:** fail + +**Remediation:** +Run the below command (based on the file location on your system) on the control plane node. +For example, +chmod 600 /var/lib/rancher/rke2/agent/pod-manifests/etcd.yaml + +**Audit:** + +```bash +/bin/sh -c 'if test -e /var/lib/rancher/rke2/agent/pod-manifests/etcd.yaml; then find /var/lib/rancher/rke2/agent/pod-manifests/etcd.yaml -name '*etcd*' | xargs stat -c permissions=%a; fi' +``` + +**Expected Result**: + +```console +permissions has permissions 644, expected 600 or more restrictive +``` + +**Returned Value**: + +```console +permissions=644 +``` + +### 1.1.8 Ensure that the etcd pod specification file ownership is set to root:root (Automated) + + +**Result:** pass + +**Remediation:** +Run the below command (based on the file location on your system) on the control plane node. +For example, +chown root:root /var/lib/rancher/rke2/agent/pod-manifests/etcd.yaml + +**Audit:** + +```bash +/bin/sh -c 'if test -e /var/lib/rancher/rke2/agent/pod-manifests/etcd.yaml; then stat -c %U:%G /var/lib/rancher/rke2/agent/pod-manifests/etcd.yaml; fi' +``` + +**Expected Result**: + +```console +'root:root' is equal to 'root:root' +``` + +**Returned Value**: + +```console +root:root +``` + +### 1.1.9 Ensure that the Container Network Interface file permissions are set to 600 or more restrictive (Manual) + + +**Result:** warn + +**Remediation:** +Run the below command (based on the file location on your system) on the control plane node. +For example, chmod 600 + +**Audit:** + +```bash +ps -fC ${kubeletbin:-kubelet} | grep -- --cni-conf-dir || echo "/etc/cni/net.d" | sed 's%.*cni-conf-dir[= ]\([^ ]*\).*%\1%' | xargs -I{} find {} -mindepth 1 | xargs --no-run-if-empty stat -c permissions=%a find /var/lib/cni/networks -type f 2> /dev/null | xargs --no-run-if-empty stat -c permissions=%a +``` + +**Expected Result**: + +```console +permissions has permissions 644, expected 600 or more restrictive +``` + +**Returned Value**: + +```console +permissions=600 permissions=644 +``` + +### 1.1.10 Ensure that the Container Network Interface file ownership is set to root:root (Manual) + + +**Result:** pass + +**Remediation:** +Run the below command (based on the file location on your system) on the control plane node. +For example, +chown root:root + +**Audit:** + +```bash +ps -fC ${kubeletbin:-kubelet} | grep -- --cni-conf-dir || echo "/etc/cni/net.d" | sed 's%.*cni-conf-dir[= ]\([^ ]*\).*%\1%' | xargs -I{} find {} -mindepth 1 | xargs --no-run-if-empty stat -c %U:%G find /var/lib/cni/networks -type f 2> /dev/null | xargs --no-run-if-empty stat -c %U:%G +``` + +**Expected Result**: + +```console +'root:root' is present +``` + +**Returned Value**: + +```console +root:root root:root +``` + +### 1.1.11 Ensure that the etcd data directory permissions are set to 700 or more restrictive (Automated) + + +**Result:** pass + +**Remediation:** +On the etcd server node, get the etcd data directory, passed as an argument --data-dir, +from the command 'ps -ef | grep etcd'. +Run the below command (based on the etcd data directory found above). For example, +chmod 700 /var/lib/etcd + +**Audit:** + +```bash +stat -c permissions=%a /var/lib/rancher/rke2/server/db/etcd +``` + +**Expected Result**: + +```console +permissions has permissions 700, expected 700 or more restrictive +``` + +**Returned Value**: + +```console +permissions=700 +``` + +### 1.1.12 Ensure that the etcd data directory ownership is set to etcd:etcd (Automated) + + +**Result:** Not Applicable + +**Remediation:** +On the etcd server node, get the etcd data directory, passed as an argument --data-dir, +from the command 'ps -ef | grep etcd'. +Run the below command (based on the etcd data directory found above). +For example, chown etcd:etcd /var/lib/etcd + +### 1.1.13 Ensure that the admin.conf file permissions are set to 600 or more restrictive (Automated) + + +**Result:** fail + +**Remediation:** +Run the below command (based on the file location on your system) on the control plane node. +For example, chmod 600 /etc/kubernetes/admin.conf + +**Audit:** + +```bash +stat -c permissions=%a /var/lib/rancher/rke2/server/cred/admin.kubeconfig +``` + +**Expected Result**: + +```console +permissions has permissions 644, expected 600 or more restrictive +``` + +**Returned Value**: + +```console +permissions=644 +``` + +### 1.1.14 Ensure that the admin.conf file ownership is set to root:root (Automated) + + +**Result:** pass + +**Remediation:** +Run the below command (based on the file location on your system) on the control plane node. +For example, chown root:root /etc/kubernetes/admin.conf + +**Audit:** + +```bash +stat -c %U:%G /var/lib/rancher/rke2/server/cred/admin.kubeconfig +``` + +**Expected Result**: + +```console +'root:root' is equal to 'root:root' +``` + +**Returned Value**: + +```console +root:root +``` + +### 1.1.15 Ensure that the scheduler.conf file permissions are set to 600 or more restrictive (Automated) + + +**Result:** fail + +**Remediation:** +Run the below command (based on the file location on your system) on the control plane node. +For example, +chmod 600 /var/lib/rancher/rke2/server/cred/scheduler.kubeconfig + +**Audit:** + +```bash +/bin/sh -c 'if test -e /var/lib/rancher/rke2/server/cred/scheduler.kubeconfig; then stat -c permissions=%a /var/lib/rancher/rke2/server/cred/scheduler.kubeconfig; fi' +``` + +**Expected Result**: + +```console +'600' is present +``` + +**Returned Value**: + +```console +permissions=644 +``` + +### 1.1.16 Ensure that the scheduler.conf file ownership is set to root:root (Automated) + + +**Result:** pass + +**Remediation:** +Run the below command (based on the file location on your system) on the control plane node. +For example, +chown root:root /var/lib/rancher/rke2/server/cred/scheduler.kubeconfig + +**Audit:** + +```bash +stat -c %U:%G /var/lib/rancher/rke2/server/cred/scheduler.kubeconfig +``` + +**Expected Result**: + +```console +'root:root' is equal to 'root:root' +``` + +**Returned Value**: + +```console +root:root +``` + +### 1.1.17 Ensure that the controller-manager.conf file permissions are set to 600 or more restrictive (Automated) + + +**Result:** fail + +**Remediation:** +Run the below command (based on the file location on your system) on the control plane node. +For example, +chmod 600 /var/lib/rancher/rke2/server/cred/controller.kubeconfig + +**Audit:** + +```bash +/bin/sh -c 'if test -e /var/lib/rancher/rke2/server/cred/controller.kubeconfig; then stat -c permissions=%a /var/lib/rancher/rke2/server/cred/controller.kubeconfig; fi' +``` + +**Expected Result**: + +```console +'600' is present +``` + +**Returned Value**: + +```console +permissions=644 +``` + +### 1.1.18 Ensure that the controller-manager.conf file ownership is set to root:root (Automated) + + +**Result:** pass + +**Remediation:** +Run the below command (based on the file location on your system) on the control plane node. +For example, +chown root:root /var/lib/rancher/rke2/server/cred/controller.kubeconfig + +**Audit:** + +```bash +stat -c %U:%G /var/lib/rancher/rke2/server/cred/controller.kubeconfig +``` + +**Expected Result**: + +```console +'root:root' is equal to 'root:root' +``` + +**Returned Value**: + +```console +root:root +``` + +### 1.1.19 Ensure that the Kubernetes PKI directory and file ownership is set to root:root (Automated) + + +**Result:** pass + +**Remediation:** +Run the below command (based on the file location on your system) on the control plane node. +For example, +chown -R root:root /etc/kubernetes/pki/ + +**Audit:** + +```bash +stat -c %U:%G /var/lib/rancher/rke2/server/tls +``` + +**Expected Result**: + +```console +'root:root' is equal to 'root:root' +``` + +**Returned Value**: + +```console +root:root +``` + +### 1.1.20 Ensure that the Kubernetes PKI certificate file permissions are set to 600 or more restrictive (Manual) + + +**Result:** warn + +**Remediation:** +Run the below command (based on the file location on your system) on the control plane node. +For example, +chmod -R 600 /var/lib/rancher/rke2/server/tls/*.crt + +**Audit:** + +```bash +stat -c permissions=%a /var/lib/rancher/rke2/server/tls/*.crt +``` + +**Expected Result**: + +```console +permissions has permissions 644, expected 600 or more restrictive +``` + +**Returned Value**: + +```console +permissions=644 permissions=644 permissions=644 permissions=644 permissions=644 permissions=644 permissions=644 permissions=644 permissions=644 permissions=644 permissions=644 permissions=644 permissions=644 permissions=644 permissions=644 +``` + +### 1.1.21 Ensure that the Kubernetes PKI key file permissions are set to 600 (Manual) + + +**Result:** pass + +**Remediation:** +Run the below command (based on the file location on your system) on the control plane node. +For example, +chmod -R 600 /var/lib/rancher/rke2/server/tls/*.key + +**Audit:** + +```bash +stat -c permissions=%a /var/lib/rancher/rke2/server/tls/*.key +``` + +**Expected Result**: + +```console +permissions has permissions 600, expected 600 or more restrictive +``` + +**Returned Value**: + +```console +permissions=600 permissions=600 permissions=600 permissions=600 permissions=600 permissions=600 permissions=600 permissions=600 permissions=600 permissions=600 permissions=600 permissions=600 permissions=600 permissions=600 permissions=600 permissions=600 permissions=600 +``` + +## 1.2 API Server +### 1.2.1 Ensure that the --anonymous-auth argument is set to false (Manual) + + +**Result:** warn + +**Remediation:** +Edit the API server pod specification file /var/lib/rancher/rke2/agent/pod-manifests/kube-apiserver.yaml +on the control plane node and set the below parameter. +--anonymous-auth=false + +**Audit:** + +```bash +/bin/ps -ef | grep kube-apiserver | grep -v grep +``` + +### 1.2.2 Ensure that the --token-auth-file parameter is not set (Automated) + + +**Result:** pass + +**Remediation:** +Follow the documentation and configure alternate mechanisms for authentication. Then, +edit the API server pod specification file /var/lib/rancher/rke2/agent/pod-manifests/kube-apiserver.yaml +on the control plane node and remove the --token-auth-file= parameter. + +**Audit:** + +```bash +/bin/ps -ef | grep kube-apiserver | grep -v grep +``` + +**Expected Result**: + +```console +'--token-auth-file' is not present +``` + +**Returned Value**: + +```console +root 2489 2419 8 Sep11 ? 01:41:54 kube-apiserver --admission-control-config-file=/etc/rancher/rke2/rke2-pss.yaml --audit-policy-file=/etc/rancher/rke2/audit-policy.yaml --audit-log-maxage=30 --audit-log-maxbackup=10 --audit-log-maxsize=100 --audit-log-path=/var/lib/rancher/rke2/server/logs/audit.log --admission-control-config-file=/etc/rancher/rke2/config/rancher-psact.yaml --allow-privileged=true --anonymous-auth=false --api-audiences=https://kubernetes.default.svc.cluster.local,rke2 --authorization-mode=Node,RBAC --bind-address=0.0.0.0 --cert-dir=/var/lib/rancher/rke2/server/tls/temporary-certs --client-ca-file=/var/lib/rancher/rke2/server/tls/client-ca.crt --egress-selector-config-file=/var/lib/rancher/rke2/server/etc/egress-selector-config.yaml --enable-admission-plugins=NodeRestriction --enable-aggregator-routing=true --enable-bootstrap-token-auth=true --encryption-provider-config=/var/lib/rancher/rke2/server/cred/encryption-config.json --etcd-cafile=/var/lib/rancher/rke2/server/tls/etcd/server-ca.crt --etcd-certfile=/var/lib/rancher/rke2/server/tls/etcd/client.crt --etcd-keyfile=/var/lib/rancher/rke2/server/tls/etcd/client.key --etcd-servers=https://127.0.0.1:2379 --feature-gates=JobTrackingWithFinalizers=true --kubelet-certificate-authority=/var/lib/rancher/rke2/server/tls/server-ca.crt --kubelet-client-certificate=/var/lib/rancher/rke2/server/tls/client-kube-apiserver.crt --kubelet-client-key=/var/lib/rancher/rke2/server/tls/client-kube-apiserver.key --kubelet-preferred-address-types=InternalIP,ExternalIP,Hostname --profiling=false --proxy-client-cert-file=/var/lib/rancher/rke2/server/tls/client-auth-proxy.crt --proxy-client-key-file=/var/lib/rancher/rke2/server/tls/client-auth-proxy.key --requestheader-allowed-names=system:auth-proxy --requestheader-client-ca-file=/var/lib/rancher/rke2/server/tls/request-header-ca.crt --requestheader-extra-headers-prefix=X-Remote-Extra- --requestheader-group-headers=X-Remote-Group --requestheader-username-headers=X-Remote-User --secure-port=6443 --service-account-issuer=https://kubernetes.default.svc.cluster.local --service-account-key-file=/var/lib/rancher/rke2/server/tls/service.key --service-account-signing-key-file=/var/lib/rancher/rke2/server/tls/service.current.key --service-cluster-ip-range=10.43.0.0/16 --service-node-port-range=30000-32767 --storage-backend=etcd3 --tls-cert-file=/var/lib/rancher/rke2/server/tls/serving-kube-apiserver.crt --tls-cipher-suites=TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305,TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305 --tls-private-key-file=/var/lib/rancher/rke2/server/tls/serving-kube-apiserver.key root 2652 2539 2 Sep11 ? 00:24:53 kube-controller-manager --flex-volume-plugin-dir=/var/lib/kubelet/volumeplugins --terminated-pod-gc-threshold=1000 --permit-port-sharing=true --allocate-node-cidrs=true --authentication-kubeconfig=/var/lib/rancher/rke2/server/cred/controller.kubeconfig --authorization-kubeconfig=/var/lib/rancher/rke2/server/cred/controller.kubeconfig --bind-address=127.0.0.1 --cert-dir=/var/lib/rancher/rke2/server/tls/kube-controller-manager --cluster-cidr=10.42.0.0/16 --cluster-signing-kube-apiserver-client-cert-file=/var/lib/rancher/rke2/server/tls/client-ca.nochain.crt --cluster-signing-kube-apiserver-client-key-file=/var/lib/rancher/rke2/server/tls/client-ca.key --cluster-signing-kubelet-client-cert-file=/var/lib/rancher/rke2/server/tls/client-ca.nochain.crt --cluster-signing-kubelet-client-key-file=/var/lib/rancher/rke2/server/tls/client-ca.key --cluster-signing-kubelet-serving-cert-file=/var/lib/rancher/rke2/server/tls/server-ca.nochain.crt --cluster-signing-kubelet-serving-key-file=/var/lib/rancher/rke2/server/tls/server-ca.key --cluster-signing-legacy-unknown-cert-file=/var/lib/rancher/rke2/server/tls/server-ca.nochain.crt --cluster-signing-legacy-unknown-key-file=/var/lib/rancher/rke2/server/tls/server-ca.key --configure-cloud-routes=false --controllers=*,tokencleaner,-service,-route,-cloud-node-lifecycle --feature-gates=JobTrackingWithFinalizers=true --kubeconfig=/var/lib/rancher/rke2/server/cred/controller.kubeconfig --profiling=false --root-ca-file=/var/lib/rancher/rke2/server/tls/server-ca.crt --secure-port=10257 --service-account-private-key-file=/var/lib/rancher/rke2/server/tls/service.current.key --service-cluster-ip-range=10.43.0.0/16 --use-service-account-credentials=true +``` + +### 1.2.3 Ensure that the --DenyServiceExternalIPs is not set (Automated) + + +**Result:** pass + +**Remediation:** +Edit the API server pod specification file /var/lib/rancher/rke2/agent/pod-manifests/kube-apiserver.yaml +on the control plane node and remove the `DenyServiceExternalIPs` +from enabled admission plugins. + +**Audit:** + +```bash +/bin/ps -ef | grep kube-apiserver | grep -v grep +``` + +**Expected Result**: + +```console +'--enable-admission-plugins' does not have 'DenyServiceExternalIPs' OR '--enable-admission-plugins' is not present +``` + +**Returned Value**: + +```console +root 2489 2419 8 Sep11 ? 01:41:54 kube-apiserver --admission-control-config-file=/etc/rancher/rke2/rke2-pss.yaml --audit-policy-file=/etc/rancher/rke2/audit-policy.yaml --audit-log-maxage=30 --audit-log-maxbackup=10 --audit-log-maxsize=100 --audit-log-path=/var/lib/rancher/rke2/server/logs/audit.log --admission-control-config-file=/etc/rancher/rke2/config/rancher-psact.yaml --allow-privileged=true --anonymous-auth=false --api-audiences=https://kubernetes.default.svc.cluster.local,rke2 --authorization-mode=Node,RBAC --bind-address=0.0.0.0 --cert-dir=/var/lib/rancher/rke2/server/tls/temporary-certs --client-ca-file=/var/lib/rancher/rke2/server/tls/client-ca.crt --egress-selector-config-file=/var/lib/rancher/rke2/server/etc/egress-selector-config.yaml --enable-admission-plugins=NodeRestriction --enable-aggregator-routing=true --enable-bootstrap-token-auth=true --encryption-provider-config=/var/lib/rancher/rke2/server/cred/encryption-config.json --etcd-cafile=/var/lib/rancher/rke2/server/tls/etcd/server-ca.crt --etcd-certfile=/var/lib/rancher/rke2/server/tls/etcd/client.crt --etcd-keyfile=/var/lib/rancher/rke2/server/tls/etcd/client.key --etcd-servers=https://127.0.0.1:2379 --feature-gates=JobTrackingWithFinalizers=true --kubelet-certificate-authority=/var/lib/rancher/rke2/server/tls/server-ca.crt --kubelet-client-certificate=/var/lib/rancher/rke2/server/tls/client-kube-apiserver.crt --kubelet-client-key=/var/lib/rancher/rke2/server/tls/client-kube-apiserver.key --kubelet-preferred-address-types=InternalIP,ExternalIP,Hostname --profiling=false --proxy-client-cert-file=/var/lib/rancher/rke2/server/tls/client-auth-proxy.crt --proxy-client-key-file=/var/lib/rancher/rke2/server/tls/client-auth-proxy.key --requestheader-allowed-names=system:auth-proxy --requestheader-client-ca-file=/var/lib/rancher/rke2/server/tls/request-header-ca.crt --requestheader-extra-headers-prefix=X-Remote-Extra- --requestheader-group-headers=X-Remote-Group --requestheader-username-headers=X-Remote-User --secure-port=6443 --service-account-issuer=https://kubernetes.default.svc.cluster.local --service-account-key-file=/var/lib/rancher/rke2/server/tls/service.key --service-account-signing-key-file=/var/lib/rancher/rke2/server/tls/service.current.key --service-cluster-ip-range=10.43.0.0/16 --service-node-port-range=30000-32767 --storage-backend=etcd3 --tls-cert-file=/var/lib/rancher/rke2/server/tls/serving-kube-apiserver.crt --tls-cipher-suites=TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305,TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305 --tls-private-key-file=/var/lib/rancher/rke2/server/tls/serving-kube-apiserver.key root 2652 2539 2 Sep11 ? 00:24:53 kube-controller-manager --flex-volume-plugin-dir=/var/lib/kubelet/volumeplugins --terminated-pod-gc-threshold=1000 --permit-port-sharing=true --allocate-node-cidrs=true --authentication-kubeconfig=/var/lib/rancher/rke2/server/cred/controller.kubeconfig --authorization-kubeconfig=/var/lib/rancher/rke2/server/cred/controller.kubeconfig --bind-address=127.0.0.1 --cert-dir=/var/lib/rancher/rke2/server/tls/kube-controller-manager --cluster-cidr=10.42.0.0/16 --cluster-signing-kube-apiserver-client-cert-file=/var/lib/rancher/rke2/server/tls/client-ca.nochain.crt --cluster-signing-kube-apiserver-client-key-file=/var/lib/rancher/rke2/server/tls/client-ca.key --cluster-signing-kubelet-client-cert-file=/var/lib/rancher/rke2/server/tls/client-ca.nochain.crt --cluster-signing-kubelet-client-key-file=/var/lib/rancher/rke2/server/tls/client-ca.key --cluster-signing-kubelet-serving-cert-file=/var/lib/rancher/rke2/server/tls/server-ca.nochain.crt --cluster-signing-kubelet-serving-key-file=/var/lib/rancher/rke2/server/tls/server-ca.key --cluster-signing-legacy-unknown-cert-file=/var/lib/rancher/rke2/server/tls/server-ca.nochain.crt --cluster-signing-legacy-unknown-key-file=/var/lib/rancher/rke2/server/tls/server-ca.key --configure-cloud-routes=false --controllers=*,tokencleaner,-service,-route,-cloud-node-lifecycle --feature-gates=JobTrackingWithFinalizers=true --kubeconfig=/var/lib/rancher/rke2/server/cred/controller.kubeconfig --profiling=false --root-ca-file=/var/lib/rancher/rke2/server/tls/server-ca.crt --secure-port=10257 --service-account-private-key-file=/var/lib/rancher/rke2/server/tls/service.current.key --service-cluster-ip-range=10.43.0.0/16 --use-service-account-credentials=true +``` + +### 1.2.4 Ensure that the --kubelet-client-certificate and --kubelet-client-key arguments are set as appropriate (Automated) + + +**Result:** pass + +**Remediation:** +Follow the Kubernetes documentation and set up the TLS connection between the +apiserver and kubelets. Then, edit API server pod specification file +/var/lib/rancher/rke2/agent/pod-manifests/kube-apiserver.yaml on the control plane node and set the +kubelet client certificate and key parameters as below. +--kubelet-client-certificate= +--kubelet-client-key= + +**Audit:** + +```bash +/bin/ps -ef | grep kube-apiserver | grep -v grep +``` + +**Expected Result**: + +```console +'--kubelet-client-certificate' is present AND '--kubelet-client-key' is present +``` + +**Returned Value**: + +```console +root 2489 2419 8 Sep11 ? 01:41:54 kube-apiserver --admission-control-config-file=/etc/rancher/rke2/rke2-pss.yaml --audit-policy-file=/etc/rancher/rke2/audit-policy.yaml --audit-log-maxage=30 --audit-log-maxbackup=10 --audit-log-maxsize=100 --audit-log-path=/var/lib/rancher/rke2/server/logs/audit.log --admission-control-config-file=/etc/rancher/rke2/config/rancher-psact.yaml --allow-privileged=true --anonymous-auth=false --api-audiences=https://kubernetes.default.svc.cluster.local,rke2 --authorization-mode=Node,RBAC --bind-address=0.0.0.0 --cert-dir=/var/lib/rancher/rke2/server/tls/temporary-certs --client-ca-file=/var/lib/rancher/rke2/server/tls/client-ca.crt --egress-selector-config-file=/var/lib/rancher/rke2/server/etc/egress-selector-config.yaml --enable-admission-plugins=NodeRestriction --enable-aggregator-routing=true --enable-bootstrap-token-auth=true --encryption-provider-config=/var/lib/rancher/rke2/server/cred/encryption-config.json --etcd-cafile=/var/lib/rancher/rke2/server/tls/etcd/server-ca.crt --etcd-certfile=/var/lib/rancher/rke2/server/tls/etcd/client.crt --etcd-keyfile=/var/lib/rancher/rke2/server/tls/etcd/client.key --etcd-servers=https://127.0.0.1:2379 --feature-gates=JobTrackingWithFinalizers=true --kubelet-certificate-authority=/var/lib/rancher/rke2/server/tls/server-ca.crt --kubelet-client-certificate=/var/lib/rancher/rke2/server/tls/client-kube-apiserver.crt --kubelet-client-key=/var/lib/rancher/rke2/server/tls/client-kube-apiserver.key --kubelet-preferred-address-types=InternalIP,ExternalIP,Hostname --profiling=false --proxy-client-cert-file=/var/lib/rancher/rke2/server/tls/client-auth-proxy.crt --proxy-client-key-file=/var/lib/rancher/rke2/server/tls/client-auth-proxy.key --requestheader-allowed-names=system:auth-proxy --requestheader-client-ca-file=/var/lib/rancher/rke2/server/tls/request-header-ca.crt --requestheader-extra-headers-prefix=X-Remote-Extra- --requestheader-group-headers=X-Remote-Group --requestheader-username-headers=X-Remote-User --secure-port=6443 --service-account-issuer=https://kubernetes.default.svc.cluster.local --service-account-key-file=/var/lib/rancher/rke2/server/tls/service.key --service-account-signing-key-file=/var/lib/rancher/rke2/server/tls/service.current.key --service-cluster-ip-range=10.43.0.0/16 --service-node-port-range=30000-32767 --storage-backend=etcd3 --tls-cert-file=/var/lib/rancher/rke2/server/tls/serving-kube-apiserver.crt --tls-cipher-suites=TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305,TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305 --tls-private-key-file=/var/lib/rancher/rke2/server/tls/serving-kube-apiserver.key root 2652 2539 2 Sep11 ? 00:24:53 kube-controller-manager --flex-volume-plugin-dir=/var/lib/kubelet/volumeplugins --terminated-pod-gc-threshold=1000 --permit-port-sharing=true --allocate-node-cidrs=true --authentication-kubeconfig=/var/lib/rancher/rke2/server/cred/controller.kubeconfig --authorization-kubeconfig=/var/lib/rancher/rke2/server/cred/controller.kubeconfig --bind-address=127.0.0.1 --cert-dir=/var/lib/rancher/rke2/server/tls/kube-controller-manager --cluster-cidr=10.42.0.0/16 --cluster-signing-kube-apiserver-client-cert-file=/var/lib/rancher/rke2/server/tls/client-ca.nochain.crt --cluster-signing-kube-apiserver-client-key-file=/var/lib/rancher/rke2/server/tls/client-ca.key --cluster-signing-kubelet-client-cert-file=/var/lib/rancher/rke2/server/tls/client-ca.nochain.crt --cluster-signing-kubelet-client-key-file=/var/lib/rancher/rke2/server/tls/client-ca.key --cluster-signing-kubelet-serving-cert-file=/var/lib/rancher/rke2/server/tls/server-ca.nochain.crt --cluster-signing-kubelet-serving-key-file=/var/lib/rancher/rke2/server/tls/server-ca.key --cluster-signing-legacy-unknown-cert-file=/var/lib/rancher/rke2/server/tls/server-ca.nochain.crt --cluster-signing-legacy-unknown-key-file=/var/lib/rancher/rke2/server/tls/server-ca.key --configure-cloud-routes=false --controllers=*,tokencleaner,-service,-route,-cloud-node-lifecycle --feature-gates=JobTrackingWithFinalizers=true --kubeconfig=/var/lib/rancher/rke2/server/cred/controller.kubeconfig --profiling=false --root-ca-file=/var/lib/rancher/rke2/server/tls/server-ca.crt --secure-port=10257 --service-account-private-key-file=/var/lib/rancher/rke2/server/tls/service.current.key --service-cluster-ip-range=10.43.0.0/16 --use-service-account-credentials=true +``` + +### 1.2.5 Ensure that the --kubelet-certificate-authority argument is set as appropriate (Automated) + + +**Result:** pass + +**Remediation:** +Follow the Kubernetes documentation and setup the TLS connection between +the apiserver and kubelets. Then, edit the API server pod specification file +/var/lib/rancher/rke2/agent/pod-manifests/kube-apiserver.yaml on the control plane node and set the +--kubelet-certificate-authority parameter to the path to the cert file for the certificate authority. +--kubelet-certificate-authority= + +**Audit:** + +```bash +/bin/ps -ef | grep kube-apiserver | grep -v grep +``` + +**Expected Result**: + +```console +'--kubelet-certificate-authority' is present +``` + +**Returned Value**: + +```console +root 2489 2419 8 Sep11 ? 01:41:54 kube-apiserver --admission-control-config-file=/etc/rancher/rke2/rke2-pss.yaml --audit-policy-file=/etc/rancher/rke2/audit-policy.yaml --audit-log-maxage=30 --audit-log-maxbackup=10 --audit-log-maxsize=100 --audit-log-path=/var/lib/rancher/rke2/server/logs/audit.log --admission-control-config-file=/etc/rancher/rke2/config/rancher-psact.yaml --allow-privileged=true --anonymous-auth=false --api-audiences=https://kubernetes.default.svc.cluster.local,rke2 --authorization-mode=Node,RBAC --bind-address=0.0.0.0 --cert-dir=/var/lib/rancher/rke2/server/tls/temporary-certs --client-ca-file=/var/lib/rancher/rke2/server/tls/client-ca.crt --egress-selector-config-file=/var/lib/rancher/rke2/server/etc/egress-selector-config.yaml --enable-admission-plugins=NodeRestriction --enable-aggregator-routing=true --enable-bootstrap-token-auth=true --encryption-provider-config=/var/lib/rancher/rke2/server/cred/encryption-config.json --etcd-cafile=/var/lib/rancher/rke2/server/tls/etcd/server-ca.crt --etcd-certfile=/var/lib/rancher/rke2/server/tls/etcd/client.crt --etcd-keyfile=/var/lib/rancher/rke2/server/tls/etcd/client.key --etcd-servers=https://127.0.0.1:2379 --feature-gates=JobTrackingWithFinalizers=true --kubelet-certificate-authority=/var/lib/rancher/rke2/server/tls/server-ca.crt --kubelet-client-certificate=/var/lib/rancher/rke2/server/tls/client-kube-apiserver.crt --kubelet-client-key=/var/lib/rancher/rke2/server/tls/client-kube-apiserver.key --kubelet-preferred-address-types=InternalIP,ExternalIP,Hostname --profiling=false --proxy-client-cert-file=/var/lib/rancher/rke2/server/tls/client-auth-proxy.crt --proxy-client-key-file=/var/lib/rancher/rke2/server/tls/client-auth-proxy.key --requestheader-allowed-names=system:auth-proxy --requestheader-client-ca-file=/var/lib/rancher/rke2/server/tls/request-header-ca.crt --requestheader-extra-headers-prefix=X-Remote-Extra- --requestheader-group-headers=X-Remote-Group --requestheader-username-headers=X-Remote-User --secure-port=6443 --service-account-issuer=https://kubernetes.default.svc.cluster.local --service-account-key-file=/var/lib/rancher/rke2/server/tls/service.key --service-account-signing-key-file=/var/lib/rancher/rke2/server/tls/service.current.key --service-cluster-ip-range=10.43.0.0/16 --service-node-port-range=30000-32767 --storage-backend=etcd3 --tls-cert-file=/var/lib/rancher/rke2/server/tls/serving-kube-apiserver.crt --tls-cipher-suites=TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305,TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305 --tls-private-key-file=/var/lib/rancher/rke2/server/tls/serving-kube-apiserver.key root 2652 2539 2 Sep11 ? 00:24:53 kube-controller-manager --flex-volume-plugin-dir=/var/lib/kubelet/volumeplugins --terminated-pod-gc-threshold=1000 --permit-port-sharing=true --allocate-node-cidrs=true --authentication-kubeconfig=/var/lib/rancher/rke2/server/cred/controller.kubeconfig --authorization-kubeconfig=/var/lib/rancher/rke2/server/cred/controller.kubeconfig --bind-address=127.0.0.1 --cert-dir=/var/lib/rancher/rke2/server/tls/kube-controller-manager --cluster-cidr=10.42.0.0/16 --cluster-signing-kube-apiserver-client-cert-file=/var/lib/rancher/rke2/server/tls/client-ca.nochain.crt --cluster-signing-kube-apiserver-client-key-file=/var/lib/rancher/rke2/server/tls/client-ca.key --cluster-signing-kubelet-client-cert-file=/var/lib/rancher/rke2/server/tls/client-ca.nochain.crt --cluster-signing-kubelet-client-key-file=/var/lib/rancher/rke2/server/tls/client-ca.key --cluster-signing-kubelet-serving-cert-file=/var/lib/rancher/rke2/server/tls/server-ca.nochain.crt --cluster-signing-kubelet-serving-key-file=/var/lib/rancher/rke2/server/tls/server-ca.key --cluster-signing-legacy-unknown-cert-file=/var/lib/rancher/rke2/server/tls/server-ca.nochain.crt --cluster-signing-legacy-unknown-key-file=/var/lib/rancher/rke2/server/tls/server-ca.key --configure-cloud-routes=false --controllers=*,tokencleaner,-service,-route,-cloud-node-lifecycle --feature-gates=JobTrackingWithFinalizers=true --kubeconfig=/var/lib/rancher/rke2/server/cred/controller.kubeconfig --profiling=false --root-ca-file=/var/lib/rancher/rke2/server/tls/server-ca.crt --secure-port=10257 --service-account-private-key-file=/var/lib/rancher/rke2/server/tls/service.current.key --service-cluster-ip-range=10.43.0.0/16 --use-service-account-credentials=true +``` + +### 1.2.6 Ensure that the --authorization-mode argument is not set to AlwaysAllow (Automated) + + +**Result:** pass + +**Remediation:** +Edit the API server pod specification file /var/lib/rancher/rke2/agent/pod-manifests/kube-apiserver.yaml +on the control plane node and set the --authorization-mode parameter to values other than AlwaysAllow. +One such example could be as below. +--authorization-mode=RBAC + +**Audit:** + +```bash +/bin/ps -ef | grep kube-apiserver | grep -v grep +``` + +**Expected Result**: + +```console +'--authorization-mode' does not have 'AlwaysAllow' +``` + +**Returned Value**: + +```console +root 2489 2419 8 Sep11 ? 01:41:54 kube-apiserver --admission-control-config-file=/etc/rancher/rke2/rke2-pss.yaml --audit-policy-file=/etc/rancher/rke2/audit-policy.yaml --audit-log-maxage=30 --audit-log-maxbackup=10 --audit-log-maxsize=100 --audit-log-path=/var/lib/rancher/rke2/server/logs/audit.log --admission-control-config-file=/etc/rancher/rke2/config/rancher-psact.yaml --allow-privileged=true --anonymous-auth=false --api-audiences=https://kubernetes.default.svc.cluster.local,rke2 --authorization-mode=Node,RBAC --bind-address=0.0.0.0 --cert-dir=/var/lib/rancher/rke2/server/tls/temporary-certs --client-ca-file=/var/lib/rancher/rke2/server/tls/client-ca.crt --egress-selector-config-file=/var/lib/rancher/rke2/server/etc/egress-selector-config.yaml --enable-admission-plugins=NodeRestriction --enable-aggregator-routing=true --enable-bootstrap-token-auth=true --encryption-provider-config=/var/lib/rancher/rke2/server/cred/encryption-config.json --etcd-cafile=/var/lib/rancher/rke2/server/tls/etcd/server-ca.crt --etcd-certfile=/var/lib/rancher/rke2/server/tls/etcd/client.crt --etcd-keyfile=/var/lib/rancher/rke2/server/tls/etcd/client.key --etcd-servers=https://127.0.0.1:2379 --feature-gates=JobTrackingWithFinalizers=true --kubelet-certificate-authority=/var/lib/rancher/rke2/server/tls/server-ca.crt --kubelet-client-certificate=/var/lib/rancher/rke2/server/tls/client-kube-apiserver.crt --kubelet-client-key=/var/lib/rancher/rke2/server/tls/client-kube-apiserver.key --kubelet-preferred-address-types=InternalIP,ExternalIP,Hostname --profiling=false --proxy-client-cert-file=/var/lib/rancher/rke2/server/tls/client-auth-proxy.crt --proxy-client-key-file=/var/lib/rancher/rke2/server/tls/client-auth-proxy.key --requestheader-allowed-names=system:auth-proxy --requestheader-client-ca-file=/var/lib/rancher/rke2/server/tls/request-header-ca.crt --requestheader-extra-headers-prefix=X-Remote-Extra- --requestheader-group-headers=X-Remote-Group --requestheader-username-headers=X-Remote-User --secure-port=6443 --service-account-issuer=https://kubernetes.default.svc.cluster.local --service-account-key-file=/var/lib/rancher/rke2/server/tls/service.key --service-account-signing-key-file=/var/lib/rancher/rke2/server/tls/service.current.key --service-cluster-ip-range=10.43.0.0/16 --service-node-port-range=30000-32767 --storage-backend=etcd3 --tls-cert-file=/var/lib/rancher/rke2/server/tls/serving-kube-apiserver.crt --tls-cipher-suites=TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305,TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305 --tls-private-key-file=/var/lib/rancher/rke2/server/tls/serving-kube-apiserver.key root 2652 2539 2 Sep11 ? 00:24:53 kube-controller-manager --flex-volume-plugin-dir=/var/lib/kubelet/volumeplugins --terminated-pod-gc-threshold=1000 --permit-port-sharing=true --allocate-node-cidrs=true --authentication-kubeconfig=/var/lib/rancher/rke2/server/cred/controller.kubeconfig --authorization-kubeconfig=/var/lib/rancher/rke2/server/cred/controller.kubeconfig --bind-address=127.0.0.1 --cert-dir=/var/lib/rancher/rke2/server/tls/kube-controller-manager --cluster-cidr=10.42.0.0/16 --cluster-signing-kube-apiserver-client-cert-file=/var/lib/rancher/rke2/server/tls/client-ca.nochain.crt --cluster-signing-kube-apiserver-client-key-file=/var/lib/rancher/rke2/server/tls/client-ca.key --cluster-signing-kubelet-client-cert-file=/var/lib/rancher/rke2/server/tls/client-ca.nochain.crt --cluster-signing-kubelet-client-key-file=/var/lib/rancher/rke2/server/tls/client-ca.key --cluster-signing-kubelet-serving-cert-file=/var/lib/rancher/rke2/server/tls/server-ca.nochain.crt --cluster-signing-kubelet-serving-key-file=/var/lib/rancher/rke2/server/tls/server-ca.key --cluster-signing-legacy-unknown-cert-file=/var/lib/rancher/rke2/server/tls/server-ca.nochain.crt --cluster-signing-legacy-unknown-key-file=/var/lib/rancher/rke2/server/tls/server-ca.key --configure-cloud-routes=false --controllers=*,tokencleaner,-service,-route,-cloud-node-lifecycle --feature-gates=JobTrackingWithFinalizers=true --kubeconfig=/var/lib/rancher/rke2/server/cred/controller.kubeconfig --profiling=false --root-ca-file=/var/lib/rancher/rke2/server/tls/server-ca.crt --secure-port=10257 --service-account-private-key-file=/var/lib/rancher/rke2/server/tls/service.current.key --service-cluster-ip-range=10.43.0.0/16 --use-service-account-credentials=true +``` + +### 1.2.7 Ensure that the --authorization-mode argument includes Node (Automated) + + +**Result:** pass + +**Remediation:** +Edit the API server pod specification file /var/lib/rancher/rke2/agent/pod-manifests/kube-apiserver.yaml +on the control plane node and set the --authorization-mode parameter to a value that includes Node. +--authorization-mode=Node,RBAC + +**Audit:** + +```bash +/bin/ps -ef | grep kube-apiserver | grep -v grep +``` + +**Expected Result**: + +```console +'--authorization-mode' has 'Node' +``` + +**Returned Value**: + +```console +root 2489 2419 8 Sep11 ? 01:41:54 kube-apiserver --admission-control-config-file=/etc/rancher/rke2/rke2-pss.yaml --audit-policy-file=/etc/rancher/rke2/audit-policy.yaml --audit-log-maxage=30 --audit-log-maxbackup=10 --audit-log-maxsize=100 --audit-log-path=/var/lib/rancher/rke2/server/logs/audit.log --admission-control-config-file=/etc/rancher/rke2/config/rancher-psact.yaml --allow-privileged=true --anonymous-auth=false --api-audiences=https://kubernetes.default.svc.cluster.local,rke2 --authorization-mode=Node,RBAC --bind-address=0.0.0.0 --cert-dir=/var/lib/rancher/rke2/server/tls/temporary-certs --client-ca-file=/var/lib/rancher/rke2/server/tls/client-ca.crt --egress-selector-config-file=/var/lib/rancher/rke2/server/etc/egress-selector-config.yaml --enable-admission-plugins=NodeRestriction --enable-aggregator-routing=true --enable-bootstrap-token-auth=true --encryption-provider-config=/var/lib/rancher/rke2/server/cred/encryption-config.json --etcd-cafile=/var/lib/rancher/rke2/server/tls/etcd/server-ca.crt --etcd-certfile=/var/lib/rancher/rke2/server/tls/etcd/client.crt --etcd-keyfile=/var/lib/rancher/rke2/server/tls/etcd/client.key --etcd-servers=https://127.0.0.1:2379 --feature-gates=JobTrackingWithFinalizers=true --kubelet-certificate-authority=/var/lib/rancher/rke2/server/tls/server-ca.crt --kubelet-client-certificate=/var/lib/rancher/rke2/server/tls/client-kube-apiserver.crt --kubelet-client-key=/var/lib/rancher/rke2/server/tls/client-kube-apiserver.key --kubelet-preferred-address-types=InternalIP,ExternalIP,Hostname --profiling=false --proxy-client-cert-file=/var/lib/rancher/rke2/server/tls/client-auth-proxy.crt --proxy-client-key-file=/var/lib/rancher/rke2/server/tls/client-auth-proxy.key --requestheader-allowed-names=system:auth-proxy --requestheader-client-ca-file=/var/lib/rancher/rke2/server/tls/request-header-ca.crt --requestheader-extra-headers-prefix=X-Remote-Extra- --requestheader-group-headers=X-Remote-Group --requestheader-username-headers=X-Remote-User --secure-port=6443 --service-account-issuer=https://kubernetes.default.svc.cluster.local --service-account-key-file=/var/lib/rancher/rke2/server/tls/service.key --service-account-signing-key-file=/var/lib/rancher/rke2/server/tls/service.current.key --service-cluster-ip-range=10.43.0.0/16 --service-node-port-range=30000-32767 --storage-backend=etcd3 --tls-cert-file=/var/lib/rancher/rke2/server/tls/serving-kube-apiserver.crt --tls-cipher-suites=TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305,TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305 --tls-private-key-file=/var/lib/rancher/rke2/server/tls/serving-kube-apiserver.key root 2652 2539 2 Sep11 ? 00:24:53 kube-controller-manager --flex-volume-plugin-dir=/var/lib/kubelet/volumeplugins --terminated-pod-gc-threshold=1000 --permit-port-sharing=true --allocate-node-cidrs=true --authentication-kubeconfig=/var/lib/rancher/rke2/server/cred/controller.kubeconfig --authorization-kubeconfig=/var/lib/rancher/rke2/server/cred/controller.kubeconfig --bind-address=127.0.0.1 --cert-dir=/var/lib/rancher/rke2/server/tls/kube-controller-manager --cluster-cidr=10.42.0.0/16 --cluster-signing-kube-apiserver-client-cert-file=/var/lib/rancher/rke2/server/tls/client-ca.nochain.crt --cluster-signing-kube-apiserver-client-key-file=/var/lib/rancher/rke2/server/tls/client-ca.key --cluster-signing-kubelet-client-cert-file=/var/lib/rancher/rke2/server/tls/client-ca.nochain.crt --cluster-signing-kubelet-client-key-file=/var/lib/rancher/rke2/server/tls/client-ca.key --cluster-signing-kubelet-serving-cert-file=/var/lib/rancher/rke2/server/tls/server-ca.nochain.crt --cluster-signing-kubelet-serving-key-file=/var/lib/rancher/rke2/server/tls/server-ca.key --cluster-signing-legacy-unknown-cert-file=/var/lib/rancher/rke2/server/tls/server-ca.nochain.crt --cluster-signing-legacy-unknown-key-file=/var/lib/rancher/rke2/server/tls/server-ca.key --configure-cloud-routes=false --controllers=*,tokencleaner,-service,-route,-cloud-node-lifecycle --feature-gates=JobTrackingWithFinalizers=true --kubeconfig=/var/lib/rancher/rke2/server/cred/controller.kubeconfig --profiling=false --root-ca-file=/var/lib/rancher/rke2/server/tls/server-ca.crt --secure-port=10257 --service-account-private-key-file=/var/lib/rancher/rke2/server/tls/service.current.key --service-cluster-ip-range=10.43.0.0/16 --use-service-account-credentials=true +``` + +### 1.2.8 Ensure that the --authorization-mode argument includes RBAC (Automated) + + +**Result:** pass + +**Remediation:** +Edit the API server pod specification file /var/lib/rancher/rke2/agent/pod-manifests/kube-apiserver.yaml +on the control plane node and set the --authorization-mode parameter to a value that includes RBAC, +for example `--authorization-mode=Node,RBAC`. + +**Audit:** + +```bash +/bin/ps -ef | grep kube-apiserver | grep -v grep +``` + +**Expected Result**: + +```console +'--authorization-mode' has 'RBAC' +``` + +**Returned Value**: + +```console +root 2489 2419 8 Sep11 ? 01:41:54 kube-apiserver --admission-control-config-file=/etc/rancher/rke2/rke2-pss.yaml --audit-policy-file=/etc/rancher/rke2/audit-policy.yaml --audit-log-maxage=30 --audit-log-maxbackup=10 --audit-log-maxsize=100 --audit-log-path=/var/lib/rancher/rke2/server/logs/audit.log --admission-control-config-file=/etc/rancher/rke2/config/rancher-psact.yaml --allow-privileged=true --anonymous-auth=false --api-audiences=https://kubernetes.default.svc.cluster.local,rke2 --authorization-mode=Node,RBAC --bind-address=0.0.0.0 --cert-dir=/var/lib/rancher/rke2/server/tls/temporary-certs --client-ca-file=/var/lib/rancher/rke2/server/tls/client-ca.crt --egress-selector-config-file=/var/lib/rancher/rke2/server/etc/egress-selector-config.yaml --enable-admission-plugins=NodeRestriction --enable-aggregator-routing=true --enable-bootstrap-token-auth=true --encryption-provider-config=/var/lib/rancher/rke2/server/cred/encryption-config.json --etcd-cafile=/var/lib/rancher/rke2/server/tls/etcd/server-ca.crt --etcd-certfile=/var/lib/rancher/rke2/server/tls/etcd/client.crt --etcd-keyfile=/var/lib/rancher/rke2/server/tls/etcd/client.key --etcd-servers=https://127.0.0.1:2379 --feature-gates=JobTrackingWithFinalizers=true --kubelet-certificate-authority=/var/lib/rancher/rke2/server/tls/server-ca.crt --kubelet-client-certificate=/var/lib/rancher/rke2/server/tls/client-kube-apiserver.crt --kubelet-client-key=/var/lib/rancher/rke2/server/tls/client-kube-apiserver.key --kubelet-preferred-address-types=InternalIP,ExternalIP,Hostname --profiling=false --proxy-client-cert-file=/var/lib/rancher/rke2/server/tls/client-auth-proxy.crt --proxy-client-key-file=/var/lib/rancher/rke2/server/tls/client-auth-proxy.key --requestheader-allowed-names=system:auth-proxy --requestheader-client-ca-file=/var/lib/rancher/rke2/server/tls/request-header-ca.crt --requestheader-extra-headers-prefix=X-Remote-Extra- --requestheader-group-headers=X-Remote-Group --requestheader-username-headers=X-Remote-User --secure-port=6443 --service-account-issuer=https://kubernetes.default.svc.cluster.local --service-account-key-file=/var/lib/rancher/rke2/server/tls/service.key --service-account-signing-key-file=/var/lib/rancher/rke2/server/tls/service.current.key --service-cluster-ip-range=10.43.0.0/16 --service-node-port-range=30000-32767 --storage-backend=etcd3 --tls-cert-file=/var/lib/rancher/rke2/server/tls/serving-kube-apiserver.crt --tls-cipher-suites=TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305,TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305 --tls-private-key-file=/var/lib/rancher/rke2/server/tls/serving-kube-apiserver.key root 2652 2539 2 Sep11 ? 00:24:53 kube-controller-manager --flex-volume-plugin-dir=/var/lib/kubelet/volumeplugins --terminated-pod-gc-threshold=1000 --permit-port-sharing=true --allocate-node-cidrs=true --authentication-kubeconfig=/var/lib/rancher/rke2/server/cred/controller.kubeconfig --authorization-kubeconfig=/var/lib/rancher/rke2/server/cred/controller.kubeconfig --bind-address=127.0.0.1 --cert-dir=/var/lib/rancher/rke2/server/tls/kube-controller-manager --cluster-cidr=10.42.0.0/16 --cluster-signing-kube-apiserver-client-cert-file=/var/lib/rancher/rke2/server/tls/client-ca.nochain.crt --cluster-signing-kube-apiserver-client-key-file=/var/lib/rancher/rke2/server/tls/client-ca.key --cluster-signing-kubelet-client-cert-file=/var/lib/rancher/rke2/server/tls/client-ca.nochain.crt --cluster-signing-kubelet-client-key-file=/var/lib/rancher/rke2/server/tls/client-ca.key --cluster-signing-kubelet-serving-cert-file=/var/lib/rancher/rke2/server/tls/server-ca.nochain.crt --cluster-signing-kubelet-serving-key-file=/var/lib/rancher/rke2/server/tls/server-ca.key --cluster-signing-legacy-unknown-cert-file=/var/lib/rancher/rke2/server/tls/server-ca.nochain.crt --cluster-signing-legacy-unknown-key-file=/var/lib/rancher/rke2/server/tls/server-ca.key --configure-cloud-routes=false --controllers=*,tokencleaner,-service,-route,-cloud-node-lifecycle --feature-gates=JobTrackingWithFinalizers=true --kubeconfig=/var/lib/rancher/rke2/server/cred/controller.kubeconfig --profiling=false --root-ca-file=/var/lib/rancher/rke2/server/tls/server-ca.crt --secure-port=10257 --service-account-private-key-file=/var/lib/rancher/rke2/server/tls/service.current.key --service-cluster-ip-range=10.43.0.0/16 --use-service-account-credentials=true +``` + +### 1.2.9 Ensure that the admission control plugin EventRateLimit is set (Manual) + + +**Result:** warn + +**Remediation:** +Follow the Kubernetes documentation and set the desired limits in a configuration file. +Then, edit the API server pod specification file /var/lib/rancher/rke2/agent/pod-manifests/kube-apiserver.yaml +and set the below parameters. +--enable-admission-plugins=...,EventRateLimit,... +--admission-control-config-file= + +**Audit:** + +```bash +/bin/ps -ef | grep kube-apiserver | grep -v grep +``` + +**Expected Result**: + +```console +'--enable-admission-plugins' has 'EventRateLimit' +``` + +**Returned Value**: + +```console +root 2489 2419 8 Sep11 ? 01:41:54 kube-apiserver --admission-control-config-file=/etc/rancher/rke2/rke2-pss.yaml --audit-policy-file=/etc/rancher/rke2/audit-policy.yaml --audit-log-maxage=30 --audit-log-maxbackup=10 --audit-log-maxsize=100 --audit-log-path=/var/lib/rancher/rke2/server/logs/audit.log --admission-control-config-file=/etc/rancher/rke2/config/rancher-psact.yaml --allow-privileged=true --anonymous-auth=false --api-audiences=https://kubernetes.default.svc.cluster.local,rke2 --authorization-mode=Node,RBAC --bind-address=0.0.0.0 --cert-dir=/var/lib/rancher/rke2/server/tls/temporary-certs --client-ca-file=/var/lib/rancher/rke2/server/tls/client-ca.crt --egress-selector-config-file=/var/lib/rancher/rke2/server/etc/egress-selector-config.yaml --enable-admission-plugins=NodeRestriction --enable-aggregator-routing=true --enable-bootstrap-token-auth=true --encryption-provider-config=/var/lib/rancher/rke2/server/cred/encryption-config.json --etcd-cafile=/var/lib/rancher/rke2/server/tls/etcd/server-ca.crt --etcd-certfile=/var/lib/rancher/rke2/server/tls/etcd/client.crt --etcd-keyfile=/var/lib/rancher/rke2/server/tls/etcd/client.key --etcd-servers=https://127.0.0.1:2379 --feature-gates=JobTrackingWithFinalizers=true --kubelet-certificate-authority=/var/lib/rancher/rke2/server/tls/server-ca.crt --kubelet-client-certificate=/var/lib/rancher/rke2/server/tls/client-kube-apiserver.crt --kubelet-client-key=/var/lib/rancher/rke2/server/tls/client-kube-apiserver.key --kubelet-preferred-address-types=InternalIP,ExternalIP,Hostname --profiling=false --proxy-client-cert-file=/var/lib/rancher/rke2/server/tls/client-auth-proxy.crt --proxy-client-key-file=/var/lib/rancher/rke2/server/tls/client-auth-proxy.key --requestheader-allowed-names=system:auth-proxy --requestheader-client-ca-file=/var/lib/rancher/rke2/server/tls/request-header-ca.crt --requestheader-extra-headers-prefix=X-Remote-Extra- --requestheader-group-headers=X-Remote-Group --requestheader-username-headers=X-Remote-User --secure-port=6443 --service-account-issuer=https://kubernetes.default.svc.cluster.local --service-account-key-file=/var/lib/rancher/rke2/server/tls/service.key --service-account-signing-key-file=/var/lib/rancher/rke2/server/tls/service.current.key --service-cluster-ip-range=10.43.0.0/16 --service-node-port-range=30000-32767 --storage-backend=etcd3 --tls-cert-file=/var/lib/rancher/rke2/server/tls/serving-kube-apiserver.crt --tls-cipher-suites=TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305,TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305 --tls-private-key-file=/var/lib/rancher/rke2/server/tls/serving-kube-apiserver.key root 2652 2539 2 Sep11 ? 00:24:53 kube-controller-manager --flex-volume-plugin-dir=/var/lib/kubelet/volumeplugins --terminated-pod-gc-threshold=1000 --permit-port-sharing=true --allocate-node-cidrs=true --authentication-kubeconfig=/var/lib/rancher/rke2/server/cred/controller.kubeconfig --authorization-kubeconfig=/var/lib/rancher/rke2/server/cred/controller.kubeconfig --bind-address=127.0.0.1 --cert-dir=/var/lib/rancher/rke2/server/tls/kube-controller-manager --cluster-cidr=10.42.0.0/16 --cluster-signing-kube-apiserver-client-cert-file=/var/lib/rancher/rke2/server/tls/client-ca.nochain.crt --cluster-signing-kube-apiserver-client-key-file=/var/lib/rancher/rke2/server/tls/client-ca.key --cluster-signing-kubelet-client-cert-file=/var/lib/rancher/rke2/server/tls/client-ca.nochain.crt --cluster-signing-kubelet-client-key-file=/var/lib/rancher/rke2/server/tls/client-ca.key --cluster-signing-kubelet-serving-cert-file=/var/lib/rancher/rke2/server/tls/server-ca.nochain.crt --cluster-signing-kubelet-serving-key-file=/var/lib/rancher/rke2/server/tls/server-ca.key --cluster-signing-legacy-unknown-cert-file=/var/lib/rancher/rke2/server/tls/server-ca.nochain.crt --cluster-signing-legacy-unknown-key-file=/var/lib/rancher/rke2/server/tls/server-ca.key --configure-cloud-routes=false --controllers=*,tokencleaner,-service,-route,-cloud-node-lifecycle --feature-gates=JobTrackingWithFinalizers=true --kubeconfig=/var/lib/rancher/rke2/server/cred/controller.kubeconfig --profiling=false --root-ca-file=/var/lib/rancher/rke2/server/tls/server-ca.crt --secure-port=10257 --service-account-private-key-file=/var/lib/rancher/rke2/server/tls/service.current.key --service-cluster-ip-range=10.43.0.0/16 --use-service-account-credentials=true +``` + +### 1.2.10 Ensure that the admission control plugin AlwaysAdmit is not set (Automated) + + +**Result:** pass + +**Remediation:** +Edit the API server pod specification file /var/lib/rancher/rke2/agent/pod-manifests/kube-apiserver.yaml +on the control plane node and either remove the --enable-admission-plugins parameter, or set it to a +value that does not include AlwaysAdmit. + +**Audit:** + +```bash +/bin/ps -ef | grep kube-apiserver | grep -v grep +``` + +**Expected Result**: + +```console +'--enable-admission-plugins' does not have 'AlwaysAdmit' OR '--enable-admission-plugins' is not present +``` + +**Returned Value**: + +```console +root 2489 2419 8 Sep11 ? 01:41:54 kube-apiserver --admission-control-config-file=/etc/rancher/rke2/rke2-pss.yaml --audit-policy-file=/etc/rancher/rke2/audit-policy.yaml --audit-log-maxage=30 --audit-log-maxbackup=10 --audit-log-maxsize=100 --audit-log-path=/var/lib/rancher/rke2/server/logs/audit.log --admission-control-config-file=/etc/rancher/rke2/config/rancher-psact.yaml --allow-privileged=true --anonymous-auth=false --api-audiences=https://kubernetes.default.svc.cluster.local,rke2 --authorization-mode=Node,RBAC --bind-address=0.0.0.0 --cert-dir=/var/lib/rancher/rke2/server/tls/temporary-certs --client-ca-file=/var/lib/rancher/rke2/server/tls/client-ca.crt --egress-selector-config-file=/var/lib/rancher/rke2/server/etc/egress-selector-config.yaml --enable-admission-plugins=NodeRestriction --enable-aggregator-routing=true --enable-bootstrap-token-auth=true --encryption-provider-config=/var/lib/rancher/rke2/server/cred/encryption-config.json --etcd-cafile=/var/lib/rancher/rke2/server/tls/etcd/server-ca.crt --etcd-certfile=/var/lib/rancher/rke2/server/tls/etcd/client.crt --etcd-keyfile=/var/lib/rancher/rke2/server/tls/etcd/client.key --etcd-servers=https://127.0.0.1:2379 --feature-gates=JobTrackingWithFinalizers=true --kubelet-certificate-authority=/var/lib/rancher/rke2/server/tls/server-ca.crt --kubelet-client-certificate=/var/lib/rancher/rke2/server/tls/client-kube-apiserver.crt --kubelet-client-key=/var/lib/rancher/rke2/server/tls/client-kube-apiserver.key --kubelet-preferred-address-types=InternalIP,ExternalIP,Hostname --profiling=false --proxy-client-cert-file=/var/lib/rancher/rke2/server/tls/client-auth-proxy.crt --proxy-client-key-file=/var/lib/rancher/rke2/server/tls/client-auth-proxy.key --requestheader-allowed-names=system:auth-proxy --requestheader-client-ca-file=/var/lib/rancher/rke2/server/tls/request-header-ca.crt --requestheader-extra-headers-prefix=X-Remote-Extra- --requestheader-group-headers=X-Remote-Group --requestheader-username-headers=X-Remote-User --secure-port=6443 --service-account-issuer=https://kubernetes.default.svc.cluster.local --service-account-key-file=/var/lib/rancher/rke2/server/tls/service.key --service-account-signing-key-file=/var/lib/rancher/rke2/server/tls/service.current.key --service-cluster-ip-range=10.43.0.0/16 --service-node-port-range=30000-32767 --storage-backend=etcd3 --tls-cert-file=/var/lib/rancher/rke2/server/tls/serving-kube-apiserver.crt --tls-cipher-suites=TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305,TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305 --tls-private-key-file=/var/lib/rancher/rke2/server/tls/serving-kube-apiserver.key root 2652 2539 2 Sep11 ? 00:24:53 kube-controller-manager --flex-volume-plugin-dir=/var/lib/kubelet/volumeplugins --terminated-pod-gc-threshold=1000 --permit-port-sharing=true --allocate-node-cidrs=true --authentication-kubeconfig=/var/lib/rancher/rke2/server/cred/controller.kubeconfig --authorization-kubeconfig=/var/lib/rancher/rke2/server/cred/controller.kubeconfig --bind-address=127.0.0.1 --cert-dir=/var/lib/rancher/rke2/server/tls/kube-controller-manager --cluster-cidr=10.42.0.0/16 --cluster-signing-kube-apiserver-client-cert-file=/var/lib/rancher/rke2/server/tls/client-ca.nochain.crt --cluster-signing-kube-apiserver-client-key-file=/var/lib/rancher/rke2/server/tls/client-ca.key --cluster-signing-kubelet-client-cert-file=/var/lib/rancher/rke2/server/tls/client-ca.nochain.crt --cluster-signing-kubelet-client-key-file=/var/lib/rancher/rke2/server/tls/client-ca.key --cluster-signing-kubelet-serving-cert-file=/var/lib/rancher/rke2/server/tls/server-ca.nochain.crt --cluster-signing-kubelet-serving-key-file=/var/lib/rancher/rke2/server/tls/server-ca.key --cluster-signing-legacy-unknown-cert-file=/var/lib/rancher/rke2/server/tls/server-ca.nochain.crt --cluster-signing-legacy-unknown-key-file=/var/lib/rancher/rke2/server/tls/server-ca.key --configure-cloud-routes=false --controllers=*,tokencleaner,-service,-route,-cloud-node-lifecycle --feature-gates=JobTrackingWithFinalizers=true --kubeconfig=/var/lib/rancher/rke2/server/cred/controller.kubeconfig --profiling=false --root-ca-file=/var/lib/rancher/rke2/server/tls/server-ca.crt --secure-port=10257 --service-account-private-key-file=/var/lib/rancher/rke2/server/tls/service.current.key --service-cluster-ip-range=10.43.0.0/16 --use-service-account-credentials=true +``` + +### 1.2.11 Ensure that the admission control plugin AlwaysPullImages is set (Manual) + + +**Result:** warn + +**Remediation:** +Edit the API server pod specification file /var/lib/rancher/rke2/agent/pod-manifests/kube-apiserver.yaml +on the control plane node and set the --enable-admission-plugins parameter to include +AlwaysPullImages. +--enable-admission-plugins=...,AlwaysPullImages,... + +**Audit:** + +```bash +/bin/ps -ef | grep kube-apiserver | grep -v grep +``` + +**Expected Result**: + +```console +'--enable-admission-plugins' has 'AlwaysPullImages' +``` + +**Returned Value**: + +```console +root 2489 2419 8 Sep11 ? 01:41:54 kube-apiserver --admission-control-config-file=/etc/rancher/rke2/rke2-pss.yaml --audit-policy-file=/etc/rancher/rke2/audit-policy.yaml --audit-log-maxage=30 --audit-log-maxbackup=10 --audit-log-maxsize=100 --audit-log-path=/var/lib/rancher/rke2/server/logs/audit.log --admission-control-config-file=/etc/rancher/rke2/config/rancher-psact.yaml --allow-privileged=true --anonymous-auth=false --api-audiences=https://kubernetes.default.svc.cluster.local,rke2 --authorization-mode=Node,RBAC --bind-address=0.0.0.0 --cert-dir=/var/lib/rancher/rke2/server/tls/temporary-certs --client-ca-file=/var/lib/rancher/rke2/server/tls/client-ca.crt --egress-selector-config-file=/var/lib/rancher/rke2/server/etc/egress-selector-config.yaml --enable-admission-plugins=NodeRestriction --enable-aggregator-routing=true --enable-bootstrap-token-auth=true --encryption-provider-config=/var/lib/rancher/rke2/server/cred/encryption-config.json --etcd-cafile=/var/lib/rancher/rke2/server/tls/etcd/server-ca.crt --etcd-certfile=/var/lib/rancher/rke2/server/tls/etcd/client.crt --etcd-keyfile=/var/lib/rancher/rke2/server/tls/etcd/client.key --etcd-servers=https://127.0.0.1:2379 --feature-gates=JobTrackingWithFinalizers=true --kubelet-certificate-authority=/var/lib/rancher/rke2/server/tls/server-ca.crt --kubelet-client-certificate=/var/lib/rancher/rke2/server/tls/client-kube-apiserver.crt --kubelet-client-key=/var/lib/rancher/rke2/server/tls/client-kube-apiserver.key --kubelet-preferred-address-types=InternalIP,ExternalIP,Hostname --profiling=false --proxy-client-cert-file=/var/lib/rancher/rke2/server/tls/client-auth-proxy.crt --proxy-client-key-file=/var/lib/rancher/rke2/server/tls/client-auth-proxy.key --requestheader-allowed-names=system:auth-proxy --requestheader-client-ca-file=/var/lib/rancher/rke2/server/tls/request-header-ca.crt --requestheader-extra-headers-prefix=X-Remote-Extra- --requestheader-group-headers=X-Remote-Group --requestheader-username-headers=X-Remote-User --secure-port=6443 --service-account-issuer=https://kubernetes.default.svc.cluster.local --service-account-key-file=/var/lib/rancher/rke2/server/tls/service.key --service-account-signing-key-file=/var/lib/rancher/rke2/server/tls/service.current.key --service-cluster-ip-range=10.43.0.0/16 --service-node-port-range=30000-32767 --storage-backend=etcd3 --tls-cert-file=/var/lib/rancher/rke2/server/tls/serving-kube-apiserver.crt --tls-cipher-suites=TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305,TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305 --tls-private-key-file=/var/lib/rancher/rke2/server/tls/serving-kube-apiserver.key root 2652 2539 2 Sep11 ? 00:24:53 kube-controller-manager --flex-volume-plugin-dir=/var/lib/kubelet/volumeplugins --terminated-pod-gc-threshold=1000 --permit-port-sharing=true --allocate-node-cidrs=true --authentication-kubeconfig=/var/lib/rancher/rke2/server/cred/controller.kubeconfig --authorization-kubeconfig=/var/lib/rancher/rke2/server/cred/controller.kubeconfig --bind-address=127.0.0.1 --cert-dir=/var/lib/rancher/rke2/server/tls/kube-controller-manager --cluster-cidr=10.42.0.0/16 --cluster-signing-kube-apiserver-client-cert-file=/var/lib/rancher/rke2/server/tls/client-ca.nochain.crt --cluster-signing-kube-apiserver-client-key-file=/var/lib/rancher/rke2/server/tls/client-ca.key --cluster-signing-kubelet-client-cert-file=/var/lib/rancher/rke2/server/tls/client-ca.nochain.crt --cluster-signing-kubelet-client-key-file=/var/lib/rancher/rke2/server/tls/client-ca.key --cluster-signing-kubelet-serving-cert-file=/var/lib/rancher/rke2/server/tls/server-ca.nochain.crt --cluster-signing-kubelet-serving-key-file=/var/lib/rancher/rke2/server/tls/server-ca.key --cluster-signing-legacy-unknown-cert-file=/var/lib/rancher/rke2/server/tls/server-ca.nochain.crt --cluster-signing-legacy-unknown-key-file=/var/lib/rancher/rke2/server/tls/server-ca.key --configure-cloud-routes=false --controllers=*,tokencleaner,-service,-route,-cloud-node-lifecycle --feature-gates=JobTrackingWithFinalizers=true --kubeconfig=/var/lib/rancher/rke2/server/cred/controller.kubeconfig --profiling=false --root-ca-file=/var/lib/rancher/rke2/server/tls/server-ca.crt --secure-port=10257 --service-account-private-key-file=/var/lib/rancher/rke2/server/tls/service.current.key --service-cluster-ip-range=10.43.0.0/16 --use-service-account-credentials=true +``` + +### 1.2.12 Ensure that the admission control plugin SecurityContextDeny is set if PodSecurityPolicy is not used (Manual) + + +**Result:** warn + +**Remediation:** +Edit the API server pod specification file /var/lib/rancher/rke2/agent/pod-manifests/kube-apiserver.yaml +on the control plane node and set the --enable-admission-plugins parameter to include +SecurityContextDeny, unless PodSecurityPolicy is already in place. +--enable-admission-plugins=...,SecurityContextDeny,... + +**Audit:** + +```bash +/bin/ps -ef | grep kube-apiserver | grep -v grep +``` + +**Expected Result**: + +```console +'--enable-admission-plugins' has 'SecurityContextDeny' OR '--enable-admission-plugins' has 'PodSecurityPolicy' +``` + +**Returned Value**: + +```console +root 2489 2419 8 Sep11 ? 01:41:54 kube-apiserver --admission-control-config-file=/etc/rancher/rke2/rke2-pss.yaml --audit-policy-file=/etc/rancher/rke2/audit-policy.yaml --audit-log-maxage=30 --audit-log-maxbackup=10 --audit-log-maxsize=100 --audit-log-path=/var/lib/rancher/rke2/server/logs/audit.log --admission-control-config-file=/etc/rancher/rke2/config/rancher-psact.yaml --allow-privileged=true --anonymous-auth=false --api-audiences=https://kubernetes.default.svc.cluster.local,rke2 --authorization-mode=Node,RBAC --bind-address=0.0.0.0 --cert-dir=/var/lib/rancher/rke2/server/tls/temporary-certs --client-ca-file=/var/lib/rancher/rke2/server/tls/client-ca.crt --egress-selector-config-file=/var/lib/rancher/rke2/server/etc/egress-selector-config.yaml --enable-admission-plugins=NodeRestriction --enable-aggregator-routing=true --enable-bootstrap-token-auth=true --encryption-provider-config=/var/lib/rancher/rke2/server/cred/encryption-config.json --etcd-cafile=/var/lib/rancher/rke2/server/tls/etcd/server-ca.crt --etcd-certfile=/var/lib/rancher/rke2/server/tls/etcd/client.crt --etcd-keyfile=/var/lib/rancher/rke2/server/tls/etcd/client.key --etcd-servers=https://127.0.0.1:2379 --feature-gates=JobTrackingWithFinalizers=true --kubelet-certificate-authority=/var/lib/rancher/rke2/server/tls/server-ca.crt --kubelet-client-certificate=/var/lib/rancher/rke2/server/tls/client-kube-apiserver.crt --kubelet-client-key=/var/lib/rancher/rke2/server/tls/client-kube-apiserver.key --kubelet-preferred-address-types=InternalIP,ExternalIP,Hostname --profiling=false --proxy-client-cert-file=/var/lib/rancher/rke2/server/tls/client-auth-proxy.crt --proxy-client-key-file=/var/lib/rancher/rke2/server/tls/client-auth-proxy.key --requestheader-allowed-names=system:auth-proxy --requestheader-client-ca-file=/var/lib/rancher/rke2/server/tls/request-header-ca.crt --requestheader-extra-headers-prefix=X-Remote-Extra- --requestheader-group-headers=X-Remote-Group --requestheader-username-headers=X-Remote-User --secure-port=6443 --service-account-issuer=https://kubernetes.default.svc.cluster.local --service-account-key-file=/var/lib/rancher/rke2/server/tls/service.key --service-account-signing-key-file=/var/lib/rancher/rke2/server/tls/service.current.key --service-cluster-ip-range=10.43.0.0/16 --service-node-port-range=30000-32767 --storage-backend=etcd3 --tls-cert-file=/var/lib/rancher/rke2/server/tls/serving-kube-apiserver.crt --tls-cipher-suites=TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305,TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305 --tls-private-key-file=/var/lib/rancher/rke2/server/tls/serving-kube-apiserver.key root 2652 2539 2 Sep11 ? 00:24:53 kube-controller-manager --flex-volume-plugin-dir=/var/lib/kubelet/volumeplugins --terminated-pod-gc-threshold=1000 --permit-port-sharing=true --allocate-node-cidrs=true --authentication-kubeconfig=/var/lib/rancher/rke2/server/cred/controller.kubeconfig --authorization-kubeconfig=/var/lib/rancher/rke2/server/cred/controller.kubeconfig --bind-address=127.0.0.1 --cert-dir=/var/lib/rancher/rke2/server/tls/kube-controller-manager --cluster-cidr=10.42.0.0/16 --cluster-signing-kube-apiserver-client-cert-file=/var/lib/rancher/rke2/server/tls/client-ca.nochain.crt --cluster-signing-kube-apiserver-client-key-file=/var/lib/rancher/rke2/server/tls/client-ca.key --cluster-signing-kubelet-client-cert-file=/var/lib/rancher/rke2/server/tls/client-ca.nochain.crt --cluster-signing-kubelet-client-key-file=/var/lib/rancher/rke2/server/tls/client-ca.key --cluster-signing-kubelet-serving-cert-file=/var/lib/rancher/rke2/server/tls/server-ca.nochain.crt --cluster-signing-kubelet-serving-key-file=/var/lib/rancher/rke2/server/tls/server-ca.key --cluster-signing-legacy-unknown-cert-file=/var/lib/rancher/rke2/server/tls/server-ca.nochain.crt --cluster-signing-legacy-unknown-key-file=/var/lib/rancher/rke2/server/tls/server-ca.key --configure-cloud-routes=false --controllers=*,tokencleaner,-service,-route,-cloud-node-lifecycle --feature-gates=JobTrackingWithFinalizers=true --kubeconfig=/var/lib/rancher/rke2/server/cred/controller.kubeconfig --profiling=false --root-ca-file=/var/lib/rancher/rke2/server/tls/server-ca.crt --secure-port=10257 --service-account-private-key-file=/var/lib/rancher/rke2/server/tls/service.current.key --service-cluster-ip-range=10.43.0.0/16 --use-service-account-credentials=true +``` + +### 1.2.13 Ensure that the admission control plugin ServiceAccount is set (Automated) + + +**Result:** pass + +**Remediation:** +Follow the documentation and create ServiceAccount objects as per your environment. +Then, edit the API server pod specification file /var/lib/rancher/rke2/agent/pod-manifests/kube-apiserver.yaml +on the control plane node and ensure that the --disable-admission-plugins parameter is set to a +value that does not include ServiceAccount. + +**Audit:** + +```bash +/bin/ps -ef | grep kube-apiserver | grep -v grep +``` + +**Expected Result**: + +```console +'--disable-admission-plugins' is present OR '--disable-admission-plugins' is not present +``` + +**Returned Value**: + +```console +root 2489 2419 8 Sep11 ? 01:41:54 kube-apiserver --admission-control-config-file=/etc/rancher/rke2/rke2-pss.yaml --audit-policy-file=/etc/rancher/rke2/audit-policy.yaml --audit-log-maxage=30 --audit-log-maxbackup=10 --audit-log-maxsize=100 --audit-log-path=/var/lib/rancher/rke2/server/logs/audit.log --admission-control-config-file=/etc/rancher/rke2/config/rancher-psact.yaml --allow-privileged=true --anonymous-auth=false --api-audiences=https://kubernetes.default.svc.cluster.local,rke2 --authorization-mode=Node,RBAC --bind-address=0.0.0.0 --cert-dir=/var/lib/rancher/rke2/server/tls/temporary-certs --client-ca-file=/var/lib/rancher/rke2/server/tls/client-ca.crt --egress-selector-config-file=/var/lib/rancher/rke2/server/etc/egress-selector-config.yaml --enable-admission-plugins=NodeRestriction --enable-aggregator-routing=true --enable-bootstrap-token-auth=true --encryption-provider-config=/var/lib/rancher/rke2/server/cred/encryption-config.json --etcd-cafile=/var/lib/rancher/rke2/server/tls/etcd/server-ca.crt --etcd-certfile=/var/lib/rancher/rke2/server/tls/etcd/client.crt --etcd-keyfile=/var/lib/rancher/rke2/server/tls/etcd/client.key --etcd-servers=https://127.0.0.1:2379 --feature-gates=JobTrackingWithFinalizers=true --kubelet-certificate-authority=/var/lib/rancher/rke2/server/tls/server-ca.crt --kubelet-client-certificate=/var/lib/rancher/rke2/server/tls/client-kube-apiserver.crt --kubelet-client-key=/var/lib/rancher/rke2/server/tls/client-kube-apiserver.key --kubelet-preferred-address-types=InternalIP,ExternalIP,Hostname --profiling=false --proxy-client-cert-file=/var/lib/rancher/rke2/server/tls/client-auth-proxy.crt --proxy-client-key-file=/var/lib/rancher/rke2/server/tls/client-auth-proxy.key --requestheader-allowed-names=system:auth-proxy --requestheader-client-ca-file=/var/lib/rancher/rke2/server/tls/request-header-ca.crt --requestheader-extra-headers-prefix=X-Remote-Extra- --requestheader-group-headers=X-Remote-Group --requestheader-username-headers=X-Remote-User --secure-port=6443 --service-account-issuer=https://kubernetes.default.svc.cluster.local --service-account-key-file=/var/lib/rancher/rke2/server/tls/service.key --service-account-signing-key-file=/var/lib/rancher/rke2/server/tls/service.current.key --service-cluster-ip-range=10.43.0.0/16 --service-node-port-range=30000-32767 --storage-backend=etcd3 --tls-cert-file=/var/lib/rancher/rke2/server/tls/serving-kube-apiserver.crt --tls-cipher-suites=TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305,TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305 --tls-private-key-file=/var/lib/rancher/rke2/server/tls/serving-kube-apiserver.key root 2652 2539 2 Sep11 ? 00:24:53 kube-controller-manager --flex-volume-plugin-dir=/var/lib/kubelet/volumeplugins --terminated-pod-gc-threshold=1000 --permit-port-sharing=true --allocate-node-cidrs=true --authentication-kubeconfig=/var/lib/rancher/rke2/server/cred/controller.kubeconfig --authorization-kubeconfig=/var/lib/rancher/rke2/server/cred/controller.kubeconfig --bind-address=127.0.0.1 --cert-dir=/var/lib/rancher/rke2/server/tls/kube-controller-manager --cluster-cidr=10.42.0.0/16 --cluster-signing-kube-apiserver-client-cert-file=/var/lib/rancher/rke2/server/tls/client-ca.nochain.crt --cluster-signing-kube-apiserver-client-key-file=/var/lib/rancher/rke2/server/tls/client-ca.key --cluster-signing-kubelet-client-cert-file=/var/lib/rancher/rke2/server/tls/client-ca.nochain.crt --cluster-signing-kubelet-client-key-file=/var/lib/rancher/rke2/server/tls/client-ca.key --cluster-signing-kubelet-serving-cert-file=/var/lib/rancher/rke2/server/tls/server-ca.nochain.crt --cluster-signing-kubelet-serving-key-file=/var/lib/rancher/rke2/server/tls/server-ca.key --cluster-signing-legacy-unknown-cert-file=/var/lib/rancher/rke2/server/tls/server-ca.nochain.crt --cluster-signing-legacy-unknown-key-file=/var/lib/rancher/rke2/server/tls/server-ca.key --configure-cloud-routes=false --controllers=*,tokencleaner,-service,-route,-cloud-node-lifecycle --feature-gates=JobTrackingWithFinalizers=true --kubeconfig=/var/lib/rancher/rke2/server/cred/controller.kubeconfig --profiling=false --root-ca-file=/var/lib/rancher/rke2/server/tls/server-ca.crt --secure-port=10257 --service-account-private-key-file=/var/lib/rancher/rke2/server/tls/service.current.key --service-cluster-ip-range=10.43.0.0/16 --use-service-account-credentials=true root 1018768 2419 99 16:17 ? 00:00:00 kubectl get --server=https://localhost:6443/ --client-certificate=/var/lib/rancher/rke2/server/tls/client-kube-apiserver.crt --client-key=/var/lib/rancher/rke2/server/tls/client-kube-apiserver.key --certificate-authority=/var/lib/rancher/rke2/server/tls/server-ca.crt --raw=/readyz +``` + +### 1.2.14 Ensure that the admission control plugin NamespaceLifecycle is set (Automated) + + +**Result:** pass + +**Remediation:** +Edit the API server pod specification file /var/lib/rancher/rke2/agent/pod-manifests/kube-apiserver.yaml +on the control plane node and set the --disable-admission-plugins parameter to +ensure it does not include NamespaceLifecycle. + +**Audit:** + +```bash +/bin/ps -ef | grep kube-apiserver | grep -v grep +``` + +**Expected Result**: + +```console +'--disable-admission-plugins' is present OR '--disable-admission-plugins' is not present +``` + +**Returned Value**: + +```console +root 2489 2419 8 Sep11 ? 01:41:54 kube-apiserver --admission-control-config-file=/etc/rancher/rke2/rke2-pss.yaml --audit-policy-file=/etc/rancher/rke2/audit-policy.yaml --audit-log-maxage=30 --audit-log-maxbackup=10 --audit-log-maxsize=100 --audit-log-path=/var/lib/rancher/rke2/server/logs/audit.log --admission-control-config-file=/etc/rancher/rke2/config/rancher-psact.yaml --allow-privileged=true --anonymous-auth=false --api-audiences=https://kubernetes.default.svc.cluster.local,rke2 --authorization-mode=Node,RBAC --bind-address=0.0.0.0 --cert-dir=/var/lib/rancher/rke2/server/tls/temporary-certs --client-ca-file=/var/lib/rancher/rke2/server/tls/client-ca.crt --egress-selector-config-file=/var/lib/rancher/rke2/server/etc/egress-selector-config.yaml --enable-admission-plugins=NodeRestriction --enable-aggregator-routing=true --enable-bootstrap-token-auth=true --encryption-provider-config=/var/lib/rancher/rke2/server/cred/encryption-config.json --etcd-cafile=/var/lib/rancher/rke2/server/tls/etcd/server-ca.crt --etcd-certfile=/var/lib/rancher/rke2/server/tls/etcd/client.crt --etcd-keyfile=/var/lib/rancher/rke2/server/tls/etcd/client.key --etcd-servers=https://127.0.0.1:2379 --feature-gates=JobTrackingWithFinalizers=true --kubelet-certificate-authority=/var/lib/rancher/rke2/server/tls/server-ca.crt --kubelet-client-certificate=/var/lib/rancher/rke2/server/tls/client-kube-apiserver.crt --kubelet-client-key=/var/lib/rancher/rke2/server/tls/client-kube-apiserver.key --kubelet-preferred-address-types=InternalIP,ExternalIP,Hostname --profiling=false --proxy-client-cert-file=/var/lib/rancher/rke2/server/tls/client-auth-proxy.crt --proxy-client-key-file=/var/lib/rancher/rke2/server/tls/client-auth-proxy.key --requestheader-allowed-names=system:auth-proxy --requestheader-client-ca-file=/var/lib/rancher/rke2/server/tls/request-header-ca.crt --requestheader-extra-headers-prefix=X-Remote-Extra- --requestheader-group-headers=X-Remote-Group --requestheader-username-headers=X-Remote-User --secure-port=6443 --service-account-issuer=https://kubernetes.default.svc.cluster.local --service-account-key-file=/var/lib/rancher/rke2/server/tls/service.key --service-account-signing-key-file=/var/lib/rancher/rke2/server/tls/service.current.key --service-cluster-ip-range=10.43.0.0/16 --service-node-port-range=30000-32767 --storage-backend=etcd3 --tls-cert-file=/var/lib/rancher/rke2/server/tls/serving-kube-apiserver.crt --tls-cipher-suites=TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305,TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305 --tls-private-key-file=/var/lib/rancher/rke2/server/tls/serving-kube-apiserver.key root 2652 2539 2 Sep11 ? 00:24:53 kube-controller-manager --flex-volume-plugin-dir=/var/lib/kubelet/volumeplugins --terminated-pod-gc-threshold=1000 --permit-port-sharing=true --allocate-node-cidrs=true --authentication-kubeconfig=/var/lib/rancher/rke2/server/cred/controller.kubeconfig --authorization-kubeconfig=/var/lib/rancher/rke2/server/cred/controller.kubeconfig --bind-address=127.0.0.1 --cert-dir=/var/lib/rancher/rke2/server/tls/kube-controller-manager --cluster-cidr=10.42.0.0/16 --cluster-signing-kube-apiserver-client-cert-file=/var/lib/rancher/rke2/server/tls/client-ca.nochain.crt --cluster-signing-kube-apiserver-client-key-file=/var/lib/rancher/rke2/server/tls/client-ca.key --cluster-signing-kubelet-client-cert-file=/var/lib/rancher/rke2/server/tls/client-ca.nochain.crt --cluster-signing-kubelet-client-key-file=/var/lib/rancher/rke2/server/tls/client-ca.key --cluster-signing-kubelet-serving-cert-file=/var/lib/rancher/rke2/server/tls/server-ca.nochain.crt --cluster-signing-kubelet-serving-key-file=/var/lib/rancher/rke2/server/tls/server-ca.key --cluster-signing-legacy-unknown-cert-file=/var/lib/rancher/rke2/server/tls/server-ca.nochain.crt --cluster-signing-legacy-unknown-key-file=/var/lib/rancher/rke2/server/tls/server-ca.key --configure-cloud-routes=false --controllers=*,tokencleaner,-service,-route,-cloud-node-lifecycle --feature-gates=JobTrackingWithFinalizers=true --kubeconfig=/var/lib/rancher/rke2/server/cred/controller.kubeconfig --profiling=false --root-ca-file=/var/lib/rancher/rke2/server/tls/server-ca.crt --secure-port=10257 --service-account-private-key-file=/var/lib/rancher/rke2/server/tls/service.current.key --service-cluster-ip-range=10.43.0.0/16 --use-service-account-credentials=true +``` + +### 1.2.15 Ensure that the admission control plugin NodeRestriction is set (Automated) + + +**Result:** pass + +**Remediation:** +Follow the Kubernetes documentation and configure NodeRestriction plug-in on kubelets. +Then, edit the API server pod specification file /var/lib/rancher/rke2/agent/pod-manifests/kube-apiserver.yaml +on the control plane node and set the --enable-admission-plugins parameter to a +value that includes NodeRestriction. +--enable-admission-plugins=...,NodeRestriction,... + +**Audit:** + +```bash +/bin/ps -ef | grep kube-apiserver | grep -v grep +``` + +**Expected Result**: + +```console +'--enable-admission-plugins' has 'NodeRestriction' +``` + +**Returned Value**: + +```console +root 2489 2419 8 Sep11 ? 01:41:54 kube-apiserver --admission-control-config-file=/etc/rancher/rke2/rke2-pss.yaml --audit-policy-file=/etc/rancher/rke2/audit-policy.yaml --audit-log-maxage=30 --audit-log-maxbackup=10 --audit-log-maxsize=100 --audit-log-path=/var/lib/rancher/rke2/server/logs/audit.log --admission-control-config-file=/etc/rancher/rke2/config/rancher-psact.yaml --allow-privileged=true --anonymous-auth=false --api-audiences=https://kubernetes.default.svc.cluster.local,rke2 --authorization-mode=Node,RBAC --bind-address=0.0.0.0 --cert-dir=/var/lib/rancher/rke2/server/tls/temporary-certs --client-ca-file=/var/lib/rancher/rke2/server/tls/client-ca.crt --egress-selector-config-file=/var/lib/rancher/rke2/server/etc/egress-selector-config.yaml --enable-admission-plugins=NodeRestriction --enable-aggregator-routing=true --enable-bootstrap-token-auth=true --encryption-provider-config=/var/lib/rancher/rke2/server/cred/encryption-config.json --etcd-cafile=/var/lib/rancher/rke2/server/tls/etcd/server-ca.crt --etcd-certfile=/var/lib/rancher/rke2/server/tls/etcd/client.crt --etcd-keyfile=/var/lib/rancher/rke2/server/tls/etcd/client.key --etcd-servers=https://127.0.0.1:2379 --feature-gates=JobTrackingWithFinalizers=true --kubelet-certificate-authority=/var/lib/rancher/rke2/server/tls/server-ca.crt --kubelet-client-certificate=/var/lib/rancher/rke2/server/tls/client-kube-apiserver.crt --kubelet-client-key=/var/lib/rancher/rke2/server/tls/client-kube-apiserver.key --kubelet-preferred-address-types=InternalIP,ExternalIP,Hostname --profiling=false --proxy-client-cert-file=/var/lib/rancher/rke2/server/tls/client-auth-proxy.crt --proxy-client-key-file=/var/lib/rancher/rke2/server/tls/client-auth-proxy.key --requestheader-allowed-names=system:auth-proxy --requestheader-client-ca-file=/var/lib/rancher/rke2/server/tls/request-header-ca.crt --requestheader-extra-headers-prefix=X-Remote-Extra- --requestheader-group-headers=X-Remote-Group --requestheader-username-headers=X-Remote-User --secure-port=6443 --service-account-issuer=https://kubernetes.default.svc.cluster.local --service-account-key-file=/var/lib/rancher/rke2/server/tls/service.key --service-account-signing-key-file=/var/lib/rancher/rke2/server/tls/service.current.key --service-cluster-ip-range=10.43.0.0/16 --service-node-port-range=30000-32767 --storage-backend=etcd3 --tls-cert-file=/var/lib/rancher/rke2/server/tls/serving-kube-apiserver.crt --tls-cipher-suites=TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305,TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305 --tls-private-key-file=/var/lib/rancher/rke2/server/tls/serving-kube-apiserver.key root 2652 2539 2 Sep11 ? 00:24:53 kube-controller-manager --flex-volume-plugin-dir=/var/lib/kubelet/volumeplugins --terminated-pod-gc-threshold=1000 --permit-port-sharing=true --allocate-node-cidrs=true --authentication-kubeconfig=/var/lib/rancher/rke2/server/cred/controller.kubeconfig --authorization-kubeconfig=/var/lib/rancher/rke2/server/cred/controller.kubeconfig --bind-address=127.0.0.1 --cert-dir=/var/lib/rancher/rke2/server/tls/kube-controller-manager --cluster-cidr=10.42.0.0/16 --cluster-signing-kube-apiserver-client-cert-file=/var/lib/rancher/rke2/server/tls/client-ca.nochain.crt --cluster-signing-kube-apiserver-client-key-file=/var/lib/rancher/rke2/server/tls/client-ca.key --cluster-signing-kubelet-client-cert-file=/var/lib/rancher/rke2/server/tls/client-ca.nochain.crt --cluster-signing-kubelet-client-key-file=/var/lib/rancher/rke2/server/tls/client-ca.key --cluster-signing-kubelet-serving-cert-file=/var/lib/rancher/rke2/server/tls/server-ca.nochain.crt --cluster-signing-kubelet-serving-key-file=/var/lib/rancher/rke2/server/tls/server-ca.key --cluster-signing-legacy-unknown-cert-file=/var/lib/rancher/rke2/server/tls/server-ca.nochain.crt --cluster-signing-legacy-unknown-key-file=/var/lib/rancher/rke2/server/tls/server-ca.key --configure-cloud-routes=false --controllers=*,tokencleaner,-service,-route,-cloud-node-lifecycle --feature-gates=JobTrackingWithFinalizers=true --kubeconfig=/var/lib/rancher/rke2/server/cred/controller.kubeconfig --profiling=false --root-ca-file=/var/lib/rancher/rke2/server/tls/server-ca.crt --secure-port=10257 --service-account-private-key-file=/var/lib/rancher/rke2/server/tls/service.current.key --service-cluster-ip-range=10.43.0.0/16 --use-service-account-credentials=true +``` + +### 1.2.16 Ensure that the --secure-port argument is not set to 0 - NoteThis recommendation is obsolete and will be deleted per the consensus process (Automated) + + +**Result:** pass + +**Remediation:** +Edit the API server pod specification file /var/lib/rancher/rke2/agent/pod-manifests/kube-apiserver.yaml +on the control plane node and either remove the --secure-port parameter or +set it to a different (non-zero) desired port. + +**Audit:** + +```bash +/bin/ps -ef | grep kube-apiserver | grep -v grep +``` + +**Expected Result**: + +```console +'--secure-port' is greater than 0 OR '--secure-port' is not present +``` + +**Returned Value**: + +```console +root 2489 2419 8 Sep11 ? 01:41:54 kube-apiserver --admission-control-config-file=/etc/rancher/rke2/rke2-pss.yaml --audit-policy-file=/etc/rancher/rke2/audit-policy.yaml --audit-log-maxage=30 --audit-log-maxbackup=10 --audit-log-maxsize=100 --audit-log-path=/var/lib/rancher/rke2/server/logs/audit.log --admission-control-config-file=/etc/rancher/rke2/config/rancher-psact.yaml --allow-privileged=true --anonymous-auth=false --api-audiences=https://kubernetes.default.svc.cluster.local,rke2 --authorization-mode=Node,RBAC --bind-address=0.0.0.0 --cert-dir=/var/lib/rancher/rke2/server/tls/temporary-certs --client-ca-file=/var/lib/rancher/rke2/server/tls/client-ca.crt --egress-selector-config-file=/var/lib/rancher/rke2/server/etc/egress-selector-config.yaml --enable-admission-plugins=NodeRestriction --enable-aggregator-routing=true --enable-bootstrap-token-auth=true --encryption-provider-config=/var/lib/rancher/rke2/server/cred/encryption-config.json --etcd-cafile=/var/lib/rancher/rke2/server/tls/etcd/server-ca.crt --etcd-certfile=/var/lib/rancher/rke2/server/tls/etcd/client.crt --etcd-keyfile=/var/lib/rancher/rke2/server/tls/etcd/client.key --etcd-servers=https://127.0.0.1:2379 --feature-gates=JobTrackingWithFinalizers=true --kubelet-certificate-authority=/var/lib/rancher/rke2/server/tls/server-ca.crt --kubelet-client-certificate=/var/lib/rancher/rke2/server/tls/client-kube-apiserver.crt --kubelet-client-key=/var/lib/rancher/rke2/server/tls/client-kube-apiserver.key --kubelet-preferred-address-types=InternalIP,ExternalIP,Hostname --profiling=false --proxy-client-cert-file=/var/lib/rancher/rke2/server/tls/client-auth-proxy.crt --proxy-client-key-file=/var/lib/rancher/rke2/server/tls/client-auth-proxy.key --requestheader-allowed-names=system:auth-proxy --requestheader-client-ca-file=/var/lib/rancher/rke2/server/tls/request-header-ca.crt --requestheader-extra-headers-prefix=X-Remote-Extra- --requestheader-group-headers=X-Remote-Group --requestheader-username-headers=X-Remote-User --secure-port=6443 --service-account-issuer=https://kubernetes.default.svc.cluster.local --service-account-key-file=/var/lib/rancher/rke2/server/tls/service.key --service-account-signing-key-file=/var/lib/rancher/rke2/server/tls/service.current.key --service-cluster-ip-range=10.43.0.0/16 --service-node-port-range=30000-32767 --storage-backend=etcd3 --tls-cert-file=/var/lib/rancher/rke2/server/tls/serving-kube-apiserver.crt --tls-cipher-suites=TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305,TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305 --tls-private-key-file=/var/lib/rancher/rke2/server/tls/serving-kube-apiserver.key root 2652 2539 2 Sep11 ? 00:24:53 kube-controller-manager --flex-volume-plugin-dir=/var/lib/kubelet/volumeplugins --terminated-pod-gc-threshold=1000 --permit-port-sharing=true --allocate-node-cidrs=true --authentication-kubeconfig=/var/lib/rancher/rke2/server/cred/controller.kubeconfig --authorization-kubeconfig=/var/lib/rancher/rke2/server/cred/controller.kubeconfig --bind-address=127.0.0.1 --cert-dir=/var/lib/rancher/rke2/server/tls/kube-controller-manager --cluster-cidr=10.42.0.0/16 --cluster-signing-kube-apiserver-client-cert-file=/var/lib/rancher/rke2/server/tls/client-ca.nochain.crt --cluster-signing-kube-apiserver-client-key-file=/var/lib/rancher/rke2/server/tls/client-ca.key --cluster-signing-kubelet-client-cert-file=/var/lib/rancher/rke2/server/tls/client-ca.nochain.crt --cluster-signing-kubelet-client-key-file=/var/lib/rancher/rke2/server/tls/client-ca.key --cluster-signing-kubelet-serving-cert-file=/var/lib/rancher/rke2/server/tls/server-ca.nochain.crt --cluster-signing-kubelet-serving-key-file=/var/lib/rancher/rke2/server/tls/server-ca.key --cluster-signing-legacy-unknown-cert-file=/var/lib/rancher/rke2/server/tls/server-ca.nochain.crt --cluster-signing-legacy-unknown-key-file=/var/lib/rancher/rke2/server/tls/server-ca.key --configure-cloud-routes=false --controllers=*,tokencleaner,-service,-route,-cloud-node-lifecycle --feature-gates=JobTrackingWithFinalizers=true --kubeconfig=/var/lib/rancher/rke2/server/cred/controller.kubeconfig --profiling=false --root-ca-file=/var/lib/rancher/rke2/server/tls/server-ca.crt --secure-port=10257 --service-account-private-key-file=/var/lib/rancher/rke2/server/tls/service.current.key --service-cluster-ip-range=10.43.0.0/16 --use-service-account-credentials=true +``` + +### 1.2.17 Ensure that the --profiling argument is set to false (Automated) + + +**Result:** pass + +**Remediation:** +Edit the API server pod specification file /var/lib/rancher/rke2/agent/pod-manifests/kube-apiserver.yaml +on the control plane node and set the below parameter. +--profiling=false + +**Audit:** + +```bash +/bin/ps -ef | grep kube-apiserver | grep -v grep +``` + +**Expected Result**: + +```console +'--profiling' is equal to 'false' +``` + +**Returned Value**: + +```console +root 2489 2419 8 Sep11 ? 01:41:54 kube-apiserver --admission-control-config-file=/etc/rancher/rke2/rke2-pss.yaml --audit-policy-file=/etc/rancher/rke2/audit-policy.yaml --audit-log-maxage=30 --audit-log-maxbackup=10 --audit-log-maxsize=100 --audit-log-path=/var/lib/rancher/rke2/server/logs/audit.log --admission-control-config-file=/etc/rancher/rke2/config/rancher-psact.yaml --allow-privileged=true --anonymous-auth=false --api-audiences=https://kubernetes.default.svc.cluster.local,rke2 --authorization-mode=Node,RBAC --bind-address=0.0.0.0 --cert-dir=/var/lib/rancher/rke2/server/tls/temporary-certs --client-ca-file=/var/lib/rancher/rke2/server/tls/client-ca.crt --egress-selector-config-file=/var/lib/rancher/rke2/server/etc/egress-selector-config.yaml --enable-admission-plugins=NodeRestriction --enable-aggregator-routing=true --enable-bootstrap-token-auth=true --encryption-provider-config=/var/lib/rancher/rke2/server/cred/encryption-config.json --etcd-cafile=/var/lib/rancher/rke2/server/tls/etcd/server-ca.crt --etcd-certfile=/var/lib/rancher/rke2/server/tls/etcd/client.crt --etcd-keyfile=/var/lib/rancher/rke2/server/tls/etcd/client.key --etcd-servers=https://127.0.0.1:2379 --feature-gates=JobTrackingWithFinalizers=true --kubelet-certificate-authority=/var/lib/rancher/rke2/server/tls/server-ca.crt --kubelet-client-certificate=/var/lib/rancher/rke2/server/tls/client-kube-apiserver.crt --kubelet-client-key=/var/lib/rancher/rke2/server/tls/client-kube-apiserver.key --kubelet-preferred-address-types=InternalIP,ExternalIP,Hostname --profiling=false --proxy-client-cert-file=/var/lib/rancher/rke2/server/tls/client-auth-proxy.crt --proxy-client-key-file=/var/lib/rancher/rke2/server/tls/client-auth-proxy.key --requestheader-allowed-names=system:auth-proxy --requestheader-client-ca-file=/var/lib/rancher/rke2/server/tls/request-header-ca.crt --requestheader-extra-headers-prefix=X-Remote-Extra- --requestheader-group-headers=X-Remote-Group --requestheader-username-headers=X-Remote-User --secure-port=6443 --service-account-issuer=https://kubernetes.default.svc.cluster.local --service-account-key-file=/var/lib/rancher/rke2/server/tls/service.key --service-account-signing-key-file=/var/lib/rancher/rke2/server/tls/service.current.key --service-cluster-ip-range=10.43.0.0/16 --service-node-port-range=30000-32767 --storage-backend=etcd3 --tls-cert-file=/var/lib/rancher/rke2/server/tls/serving-kube-apiserver.crt --tls-cipher-suites=TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305,TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305 --tls-private-key-file=/var/lib/rancher/rke2/server/tls/serving-kube-apiserver.key root 2652 2539 2 Sep11 ? 00:24:53 kube-controller-manager --flex-volume-plugin-dir=/var/lib/kubelet/volumeplugins --terminated-pod-gc-threshold=1000 --permit-port-sharing=true --allocate-node-cidrs=true --authentication-kubeconfig=/var/lib/rancher/rke2/server/cred/controller.kubeconfig --authorization-kubeconfig=/var/lib/rancher/rke2/server/cred/controller.kubeconfig --bind-address=127.0.0.1 --cert-dir=/var/lib/rancher/rke2/server/tls/kube-controller-manager --cluster-cidr=10.42.0.0/16 --cluster-signing-kube-apiserver-client-cert-file=/var/lib/rancher/rke2/server/tls/client-ca.nochain.crt --cluster-signing-kube-apiserver-client-key-file=/var/lib/rancher/rke2/server/tls/client-ca.key --cluster-signing-kubelet-client-cert-file=/var/lib/rancher/rke2/server/tls/client-ca.nochain.crt --cluster-signing-kubelet-client-key-file=/var/lib/rancher/rke2/server/tls/client-ca.key --cluster-signing-kubelet-serving-cert-file=/var/lib/rancher/rke2/server/tls/server-ca.nochain.crt --cluster-signing-kubelet-serving-key-file=/var/lib/rancher/rke2/server/tls/server-ca.key --cluster-signing-legacy-unknown-cert-file=/var/lib/rancher/rke2/server/tls/server-ca.nochain.crt --cluster-signing-legacy-unknown-key-file=/var/lib/rancher/rke2/server/tls/server-ca.key --configure-cloud-routes=false --controllers=*,tokencleaner,-service,-route,-cloud-node-lifecycle --feature-gates=JobTrackingWithFinalizers=true --kubeconfig=/var/lib/rancher/rke2/server/cred/controller.kubeconfig --profiling=false --root-ca-file=/var/lib/rancher/rke2/server/tls/server-ca.crt --secure-port=10257 --service-account-private-key-file=/var/lib/rancher/rke2/server/tls/service.current.key --service-cluster-ip-range=10.43.0.0/16 --use-service-account-credentials=true +``` + +### 1.2.18 Ensure that the --audit-log-path argument is set (Automated) + + +**Result:** pass + +**Remediation:** +Edit the API server pod specification file /var/lib/rancher/rke2/agent/pod-manifests/kube-apiserver.yaml +on the control plane node and set the --audit-log-path parameter to a suitable path and +file where you would like audit logs to be written, for example, +--audit-log-path=/var/log/apiserver/audit.log + +**Audit:** + +```bash +/bin/ps -ef | grep kube-apiserver | grep -v grep +``` + +**Expected Result**: + +```console +'--audit-log-path' is present +``` + +**Returned Value**: + +```console +root 2489 2419 8 Sep11 ? 01:41:54 kube-apiserver --admission-control-config-file=/etc/rancher/rke2/rke2-pss.yaml --audit-policy-file=/etc/rancher/rke2/audit-policy.yaml --audit-log-maxage=30 --audit-log-maxbackup=10 --audit-log-maxsize=100 --audit-log-path=/var/lib/rancher/rke2/server/logs/audit.log --admission-control-config-file=/etc/rancher/rke2/config/rancher-psact.yaml --allow-privileged=true --anonymous-auth=false --api-audiences=https://kubernetes.default.svc.cluster.local,rke2 --authorization-mode=Node,RBAC --bind-address=0.0.0.0 --cert-dir=/var/lib/rancher/rke2/server/tls/temporary-certs --client-ca-file=/var/lib/rancher/rke2/server/tls/client-ca.crt --egress-selector-config-file=/var/lib/rancher/rke2/server/etc/egress-selector-config.yaml --enable-admission-plugins=NodeRestriction --enable-aggregator-routing=true --enable-bootstrap-token-auth=true --encryption-provider-config=/var/lib/rancher/rke2/server/cred/encryption-config.json --etcd-cafile=/var/lib/rancher/rke2/server/tls/etcd/server-ca.crt --etcd-certfile=/var/lib/rancher/rke2/server/tls/etcd/client.crt --etcd-keyfile=/var/lib/rancher/rke2/server/tls/etcd/client.key --etcd-servers=https://127.0.0.1:2379 --feature-gates=JobTrackingWithFinalizers=true --kubelet-certificate-authority=/var/lib/rancher/rke2/server/tls/server-ca.crt --kubelet-client-certificate=/var/lib/rancher/rke2/server/tls/client-kube-apiserver.crt --kubelet-client-key=/var/lib/rancher/rke2/server/tls/client-kube-apiserver.key --kubelet-preferred-address-types=InternalIP,ExternalIP,Hostname --profiling=false --proxy-client-cert-file=/var/lib/rancher/rke2/server/tls/client-auth-proxy.crt --proxy-client-key-file=/var/lib/rancher/rke2/server/tls/client-auth-proxy.key --requestheader-allowed-names=system:auth-proxy --requestheader-client-ca-file=/var/lib/rancher/rke2/server/tls/request-header-ca.crt --requestheader-extra-headers-prefix=X-Remote-Extra- --requestheader-group-headers=X-Remote-Group --requestheader-username-headers=X-Remote-User --secure-port=6443 --service-account-issuer=https://kubernetes.default.svc.cluster.local --service-account-key-file=/var/lib/rancher/rke2/server/tls/service.key --service-account-signing-key-file=/var/lib/rancher/rke2/server/tls/service.current.key --service-cluster-ip-range=10.43.0.0/16 --service-node-port-range=30000-32767 --storage-backend=etcd3 --tls-cert-file=/var/lib/rancher/rke2/server/tls/serving-kube-apiserver.crt --tls-cipher-suites=TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305,TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305 --tls-private-key-file=/var/lib/rancher/rke2/server/tls/serving-kube-apiserver.key root 2652 2539 2 Sep11 ? 00:24:53 kube-controller-manager --flex-volume-plugin-dir=/var/lib/kubelet/volumeplugins --terminated-pod-gc-threshold=1000 --permit-port-sharing=true --allocate-node-cidrs=true --authentication-kubeconfig=/var/lib/rancher/rke2/server/cred/controller.kubeconfig --authorization-kubeconfig=/var/lib/rancher/rke2/server/cred/controller.kubeconfig --bind-address=127.0.0.1 --cert-dir=/var/lib/rancher/rke2/server/tls/kube-controller-manager --cluster-cidr=10.42.0.0/16 --cluster-signing-kube-apiserver-client-cert-file=/var/lib/rancher/rke2/server/tls/client-ca.nochain.crt --cluster-signing-kube-apiserver-client-key-file=/var/lib/rancher/rke2/server/tls/client-ca.key --cluster-signing-kubelet-client-cert-file=/var/lib/rancher/rke2/server/tls/client-ca.nochain.crt --cluster-signing-kubelet-client-key-file=/var/lib/rancher/rke2/server/tls/client-ca.key --cluster-signing-kubelet-serving-cert-file=/var/lib/rancher/rke2/server/tls/server-ca.nochain.crt --cluster-signing-kubelet-serving-key-file=/var/lib/rancher/rke2/server/tls/server-ca.key --cluster-signing-legacy-unknown-cert-file=/var/lib/rancher/rke2/server/tls/server-ca.nochain.crt --cluster-signing-legacy-unknown-key-file=/var/lib/rancher/rke2/server/tls/server-ca.key --configure-cloud-routes=false --controllers=*,tokencleaner,-service,-route,-cloud-node-lifecycle --feature-gates=JobTrackingWithFinalizers=true --kubeconfig=/var/lib/rancher/rke2/server/cred/controller.kubeconfig --profiling=false --root-ca-file=/var/lib/rancher/rke2/server/tls/server-ca.crt --secure-port=10257 --service-account-private-key-file=/var/lib/rancher/rke2/server/tls/service.current.key --service-cluster-ip-range=10.43.0.0/16 --use-service-account-credentials=true +``` + +### 1.2.19 Ensure that the --audit-log-maxage argument is set to 30 or as appropriate (Automated) + + +**Result:** pass + +**Remediation:** +Edit the API server pod specification file /var/lib/rancher/rke2/agent/pod-manifests/kube-apiserver.yaml +on the control plane node and set the --audit-log-maxage parameter to 30 +or as an appropriate number of days, for example, +--audit-log-maxage=30 + +**Audit:** + +```bash +/bin/ps -ef | grep kube-apiserver | grep -v grep +``` + +**Expected Result**: + +```console +'--audit-log-maxage' is greater or equal to 30 +``` + +**Returned Value**: + +```console +root 2489 2419 8 Sep11 ? 01:41:54 kube-apiserver --admission-control-config-file=/etc/rancher/rke2/rke2-pss.yaml --audit-policy-file=/etc/rancher/rke2/audit-policy.yaml --audit-log-maxage=30 --audit-log-maxbackup=10 --audit-log-maxsize=100 --audit-log-path=/var/lib/rancher/rke2/server/logs/audit.log --admission-control-config-file=/etc/rancher/rke2/config/rancher-psact.yaml --allow-privileged=true --anonymous-auth=false --api-audiences=https://kubernetes.default.svc.cluster.local,rke2 --authorization-mode=Node,RBAC --bind-address=0.0.0.0 --cert-dir=/var/lib/rancher/rke2/server/tls/temporary-certs --client-ca-file=/var/lib/rancher/rke2/server/tls/client-ca.crt --egress-selector-config-file=/var/lib/rancher/rke2/server/etc/egress-selector-config.yaml --enable-admission-plugins=NodeRestriction --enable-aggregator-routing=true --enable-bootstrap-token-auth=true --encryption-provider-config=/var/lib/rancher/rke2/server/cred/encryption-config.json --etcd-cafile=/var/lib/rancher/rke2/server/tls/etcd/server-ca.crt --etcd-certfile=/var/lib/rancher/rke2/server/tls/etcd/client.crt --etcd-keyfile=/var/lib/rancher/rke2/server/tls/etcd/client.key --etcd-servers=https://127.0.0.1:2379 --feature-gates=JobTrackingWithFinalizers=true --kubelet-certificate-authority=/var/lib/rancher/rke2/server/tls/server-ca.crt --kubelet-client-certificate=/var/lib/rancher/rke2/server/tls/client-kube-apiserver.crt --kubelet-client-key=/var/lib/rancher/rke2/server/tls/client-kube-apiserver.key --kubelet-preferred-address-types=InternalIP,ExternalIP,Hostname --profiling=false --proxy-client-cert-file=/var/lib/rancher/rke2/server/tls/client-auth-proxy.crt --proxy-client-key-file=/var/lib/rancher/rke2/server/tls/client-auth-proxy.key --requestheader-allowed-names=system:auth-proxy --requestheader-client-ca-file=/var/lib/rancher/rke2/server/tls/request-header-ca.crt --requestheader-extra-headers-prefix=X-Remote-Extra- --requestheader-group-headers=X-Remote-Group --requestheader-username-headers=X-Remote-User --secure-port=6443 --service-account-issuer=https://kubernetes.default.svc.cluster.local --service-account-key-file=/var/lib/rancher/rke2/server/tls/service.key --service-account-signing-key-file=/var/lib/rancher/rke2/server/tls/service.current.key --service-cluster-ip-range=10.43.0.0/16 --service-node-port-range=30000-32767 --storage-backend=etcd3 --tls-cert-file=/var/lib/rancher/rke2/server/tls/serving-kube-apiserver.crt --tls-cipher-suites=TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305,TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305 --tls-private-key-file=/var/lib/rancher/rke2/server/tls/serving-kube-apiserver.key root 2652 2539 2 Sep11 ? 00:24:53 kube-controller-manager --flex-volume-plugin-dir=/var/lib/kubelet/volumeplugins --terminated-pod-gc-threshold=1000 --permit-port-sharing=true --allocate-node-cidrs=true --authentication-kubeconfig=/var/lib/rancher/rke2/server/cred/controller.kubeconfig --authorization-kubeconfig=/var/lib/rancher/rke2/server/cred/controller.kubeconfig --bind-address=127.0.0.1 --cert-dir=/var/lib/rancher/rke2/server/tls/kube-controller-manager --cluster-cidr=10.42.0.0/16 --cluster-signing-kube-apiserver-client-cert-file=/var/lib/rancher/rke2/server/tls/client-ca.nochain.crt --cluster-signing-kube-apiserver-client-key-file=/var/lib/rancher/rke2/server/tls/client-ca.key --cluster-signing-kubelet-client-cert-file=/var/lib/rancher/rke2/server/tls/client-ca.nochain.crt --cluster-signing-kubelet-client-key-file=/var/lib/rancher/rke2/server/tls/client-ca.key --cluster-signing-kubelet-serving-cert-file=/var/lib/rancher/rke2/server/tls/server-ca.nochain.crt --cluster-signing-kubelet-serving-key-file=/var/lib/rancher/rke2/server/tls/server-ca.key --cluster-signing-legacy-unknown-cert-file=/var/lib/rancher/rke2/server/tls/server-ca.nochain.crt --cluster-signing-legacy-unknown-key-file=/var/lib/rancher/rke2/server/tls/server-ca.key --configure-cloud-routes=false --controllers=*,tokencleaner,-service,-route,-cloud-node-lifecycle --feature-gates=JobTrackingWithFinalizers=true --kubeconfig=/var/lib/rancher/rke2/server/cred/controller.kubeconfig --profiling=false --root-ca-file=/var/lib/rancher/rke2/server/tls/server-ca.crt --secure-port=10257 --service-account-private-key-file=/var/lib/rancher/rke2/server/tls/service.current.key --service-cluster-ip-range=10.43.0.0/16 --use-service-account-credentials=true +``` + +### 1.2.20 Ensure that the --audit-log-maxbackup argument is set to 10 or as appropriate (Automated) + + +**Result:** pass + +**Remediation:** +Edit the API server pod specification file /var/lib/rancher/rke2/agent/pod-manifests/kube-apiserver.yaml +on the control plane node and set the --audit-log-maxbackup parameter to 10 or to an appropriate +value. For example, +--audit-log-maxbackup=10 + +**Audit:** + +```bash +/bin/ps -ef | grep kube-apiserver | grep -v grep +``` + +**Expected Result**: + +```console +'--audit-log-maxbackup' is greater or equal to 10 +``` + +**Returned Value**: + +```console +root 2489 2419 8 Sep11 ? 01:41:54 kube-apiserver --admission-control-config-file=/etc/rancher/rke2/rke2-pss.yaml --audit-policy-file=/etc/rancher/rke2/audit-policy.yaml --audit-log-maxage=30 --audit-log-maxbackup=10 --audit-log-maxsize=100 --audit-log-path=/var/lib/rancher/rke2/server/logs/audit.log --admission-control-config-file=/etc/rancher/rke2/config/rancher-psact.yaml --allow-privileged=true --anonymous-auth=false --api-audiences=https://kubernetes.default.svc.cluster.local,rke2 --authorization-mode=Node,RBAC --bind-address=0.0.0.0 --cert-dir=/var/lib/rancher/rke2/server/tls/temporary-certs --client-ca-file=/var/lib/rancher/rke2/server/tls/client-ca.crt --egress-selector-config-file=/var/lib/rancher/rke2/server/etc/egress-selector-config.yaml --enable-admission-plugins=NodeRestriction --enable-aggregator-routing=true --enable-bootstrap-token-auth=true --encryption-provider-config=/var/lib/rancher/rke2/server/cred/encryption-config.json --etcd-cafile=/var/lib/rancher/rke2/server/tls/etcd/server-ca.crt --etcd-certfile=/var/lib/rancher/rke2/server/tls/etcd/client.crt --etcd-keyfile=/var/lib/rancher/rke2/server/tls/etcd/client.key --etcd-servers=https://127.0.0.1:2379 --feature-gates=JobTrackingWithFinalizers=true --kubelet-certificate-authority=/var/lib/rancher/rke2/server/tls/server-ca.crt --kubelet-client-certificate=/var/lib/rancher/rke2/server/tls/client-kube-apiserver.crt --kubelet-client-key=/var/lib/rancher/rke2/server/tls/client-kube-apiserver.key --kubelet-preferred-address-types=InternalIP,ExternalIP,Hostname --profiling=false --proxy-client-cert-file=/var/lib/rancher/rke2/server/tls/client-auth-proxy.crt --proxy-client-key-file=/var/lib/rancher/rke2/server/tls/client-auth-proxy.key --requestheader-allowed-names=system:auth-proxy --requestheader-client-ca-file=/var/lib/rancher/rke2/server/tls/request-header-ca.crt --requestheader-extra-headers-prefix=X-Remote-Extra- --requestheader-group-headers=X-Remote-Group --requestheader-username-headers=X-Remote-User --secure-port=6443 --service-account-issuer=https://kubernetes.default.svc.cluster.local --service-account-key-file=/var/lib/rancher/rke2/server/tls/service.key --service-account-signing-key-file=/var/lib/rancher/rke2/server/tls/service.current.key --service-cluster-ip-range=10.43.0.0/16 --service-node-port-range=30000-32767 --storage-backend=etcd3 --tls-cert-file=/var/lib/rancher/rke2/server/tls/serving-kube-apiserver.crt --tls-cipher-suites=TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305,TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305 --tls-private-key-file=/var/lib/rancher/rke2/server/tls/serving-kube-apiserver.key root 2652 2539 2 Sep11 ? 00:24:53 kube-controller-manager --flex-volume-plugin-dir=/var/lib/kubelet/volumeplugins --terminated-pod-gc-threshold=1000 --permit-port-sharing=true --allocate-node-cidrs=true --authentication-kubeconfig=/var/lib/rancher/rke2/server/cred/controller.kubeconfig --authorization-kubeconfig=/var/lib/rancher/rke2/server/cred/controller.kubeconfig --bind-address=127.0.0.1 --cert-dir=/var/lib/rancher/rke2/server/tls/kube-controller-manager --cluster-cidr=10.42.0.0/16 --cluster-signing-kube-apiserver-client-cert-file=/var/lib/rancher/rke2/server/tls/client-ca.nochain.crt --cluster-signing-kube-apiserver-client-key-file=/var/lib/rancher/rke2/server/tls/client-ca.key --cluster-signing-kubelet-client-cert-file=/var/lib/rancher/rke2/server/tls/client-ca.nochain.crt --cluster-signing-kubelet-client-key-file=/var/lib/rancher/rke2/server/tls/client-ca.key --cluster-signing-kubelet-serving-cert-file=/var/lib/rancher/rke2/server/tls/server-ca.nochain.crt --cluster-signing-kubelet-serving-key-file=/var/lib/rancher/rke2/server/tls/server-ca.key --cluster-signing-legacy-unknown-cert-file=/var/lib/rancher/rke2/server/tls/server-ca.nochain.crt --cluster-signing-legacy-unknown-key-file=/var/lib/rancher/rke2/server/tls/server-ca.key --configure-cloud-routes=false --controllers=*,tokencleaner,-service,-route,-cloud-node-lifecycle --feature-gates=JobTrackingWithFinalizers=true --kubeconfig=/var/lib/rancher/rke2/server/cred/controller.kubeconfig --profiling=false --root-ca-file=/var/lib/rancher/rke2/server/tls/server-ca.crt --secure-port=10257 --service-account-private-key-file=/var/lib/rancher/rke2/server/tls/service.current.key --service-cluster-ip-range=10.43.0.0/16 --use-service-account-credentials=true +``` + +### 1.2.21 Ensure that the --audit-log-maxsize argument is set to 100 or as appropriate (Automated) + + +**Result:** Not Applicable + +**Remediation:** +Edit the API server pod specification file /var/lib/rancher/rke2/agent/pod-manifests/kube-apiserver.yaml +on the control plane node and set the --audit-log-maxsize parameter to an appropriate size in MB. +For example, to set it as 100 MB, --audit-log-maxsize=100 + +### 1.2.22 Ensure that the --request-timeout argument is set as appropriate (Automated) + + +**Result:** pass + +**Remediation:** +Edit the API server pod specification file /var/lib/rancher/rke2/agent/pod-manifests/kube-apiserver.yaml +and set the below parameter as appropriate and if needed. +For example, --request-timeout=300s + +**Audit:** + +```bash +/bin/ps -ef | grep kube-apiserver | grep -v grep +``` + +**Expected Result**: + +```console +'--request-timeout' is not present OR '--request-timeout' is present +``` + +**Returned Value**: + +```console +root 2489 2419 8 Sep11 ? 01:41:54 kube-apiserver --admission-control-config-file=/etc/rancher/rke2/rke2-pss.yaml --audit-policy-file=/etc/rancher/rke2/audit-policy.yaml --audit-log-maxage=30 --audit-log-maxbackup=10 --audit-log-maxsize=100 --audit-log-path=/var/lib/rancher/rke2/server/logs/audit.log --admission-control-config-file=/etc/rancher/rke2/config/rancher-psact.yaml --allow-privileged=true --anonymous-auth=false --api-audiences=https://kubernetes.default.svc.cluster.local,rke2 --authorization-mode=Node,RBAC --bind-address=0.0.0.0 --cert-dir=/var/lib/rancher/rke2/server/tls/temporary-certs --client-ca-file=/var/lib/rancher/rke2/server/tls/client-ca.crt --egress-selector-config-file=/var/lib/rancher/rke2/server/etc/egress-selector-config.yaml --enable-admission-plugins=NodeRestriction --enable-aggregator-routing=true --enable-bootstrap-token-auth=true --encryption-provider-config=/var/lib/rancher/rke2/server/cred/encryption-config.json --etcd-cafile=/var/lib/rancher/rke2/server/tls/etcd/server-ca.crt --etcd-certfile=/var/lib/rancher/rke2/server/tls/etcd/client.crt --etcd-keyfile=/var/lib/rancher/rke2/server/tls/etcd/client.key --etcd-servers=https://127.0.0.1:2379 --feature-gates=JobTrackingWithFinalizers=true --kubelet-certificate-authority=/var/lib/rancher/rke2/server/tls/server-ca.crt --kubelet-client-certificate=/var/lib/rancher/rke2/server/tls/client-kube-apiserver.crt --kubelet-client-key=/var/lib/rancher/rke2/server/tls/client-kube-apiserver.key --kubelet-preferred-address-types=InternalIP,ExternalIP,Hostname --profiling=false --proxy-client-cert-file=/var/lib/rancher/rke2/server/tls/client-auth-proxy.crt --proxy-client-key-file=/var/lib/rancher/rke2/server/tls/client-auth-proxy.key --requestheader-allowed-names=system:auth-proxy --requestheader-client-ca-file=/var/lib/rancher/rke2/server/tls/request-header-ca.crt --requestheader-extra-headers-prefix=X-Remote-Extra- --requestheader-group-headers=X-Remote-Group --requestheader-username-headers=X-Remote-User --secure-port=6443 --service-account-issuer=https://kubernetes.default.svc.cluster.local --service-account-key-file=/var/lib/rancher/rke2/server/tls/service.key --service-account-signing-key-file=/var/lib/rancher/rke2/server/tls/service.current.key --service-cluster-ip-range=10.43.0.0/16 --service-node-port-range=30000-32767 --storage-backend=etcd3 --tls-cert-file=/var/lib/rancher/rke2/server/tls/serving-kube-apiserver.crt --tls-cipher-suites=TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305,TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305 --tls-private-key-file=/var/lib/rancher/rke2/server/tls/serving-kube-apiserver.key root 2652 2539 2 Sep11 ? 00:24:53 kube-controller-manager --flex-volume-plugin-dir=/var/lib/kubelet/volumeplugins --terminated-pod-gc-threshold=1000 --permit-port-sharing=true --allocate-node-cidrs=true --authentication-kubeconfig=/var/lib/rancher/rke2/server/cred/controller.kubeconfig --authorization-kubeconfig=/var/lib/rancher/rke2/server/cred/controller.kubeconfig --bind-address=127.0.0.1 --cert-dir=/var/lib/rancher/rke2/server/tls/kube-controller-manager --cluster-cidr=10.42.0.0/16 --cluster-signing-kube-apiserver-client-cert-file=/var/lib/rancher/rke2/server/tls/client-ca.nochain.crt --cluster-signing-kube-apiserver-client-key-file=/var/lib/rancher/rke2/server/tls/client-ca.key --cluster-signing-kubelet-client-cert-file=/var/lib/rancher/rke2/server/tls/client-ca.nochain.crt --cluster-signing-kubelet-client-key-file=/var/lib/rancher/rke2/server/tls/client-ca.key --cluster-signing-kubelet-serving-cert-file=/var/lib/rancher/rke2/server/tls/server-ca.nochain.crt --cluster-signing-kubelet-serving-key-file=/var/lib/rancher/rke2/server/tls/server-ca.key --cluster-signing-legacy-unknown-cert-file=/var/lib/rancher/rke2/server/tls/server-ca.nochain.crt --cluster-signing-legacy-unknown-key-file=/var/lib/rancher/rke2/server/tls/server-ca.key --configure-cloud-routes=false --controllers=*,tokencleaner,-service,-route,-cloud-node-lifecycle --feature-gates=JobTrackingWithFinalizers=true --kubeconfig=/var/lib/rancher/rke2/server/cred/controller.kubeconfig --profiling=false --root-ca-file=/var/lib/rancher/rke2/server/tls/server-ca.crt --secure-port=10257 --service-account-private-key-file=/var/lib/rancher/rke2/server/tls/service.current.key --service-cluster-ip-range=10.43.0.0/16 --use-service-account-credentials=true +``` + +### 1.2.23 Ensure that the --service-account-lookup argument is set to true (Automated) + + +**Result:** pass + +**Remediation:** +Edit the API server pod specification file /var/lib/rancher/rke2/agent/pod-manifests/kube-apiserver.yaml +on the control plane node and set the below parameter. +--service-account-lookup=true +Alternatively, you can delete the --service-account-lookup parameter from this file so +that the default takes effect. + +**Audit:** + +```bash +/bin/ps -ef | grep kube-apiserver | grep -v grep +``` + +**Expected Result**: + +```console +'--service-account-lookup' is not present OR '--service-account-lookup' is present +``` + +**Returned Value**: + +```console +root 2489 2419 8 Sep11 ? 01:41:54 kube-apiserver --admission-control-config-file=/etc/rancher/rke2/rke2-pss.yaml --audit-policy-file=/etc/rancher/rke2/audit-policy.yaml --audit-log-maxage=30 --audit-log-maxbackup=10 --audit-log-maxsize=100 --audit-log-path=/var/lib/rancher/rke2/server/logs/audit.log --admission-control-config-file=/etc/rancher/rke2/config/rancher-psact.yaml --allow-privileged=true --anonymous-auth=false --api-audiences=https://kubernetes.default.svc.cluster.local,rke2 --authorization-mode=Node,RBAC --bind-address=0.0.0.0 --cert-dir=/var/lib/rancher/rke2/server/tls/temporary-certs --client-ca-file=/var/lib/rancher/rke2/server/tls/client-ca.crt --egress-selector-config-file=/var/lib/rancher/rke2/server/etc/egress-selector-config.yaml --enable-admission-plugins=NodeRestriction --enable-aggregator-routing=true --enable-bootstrap-token-auth=true --encryption-provider-config=/var/lib/rancher/rke2/server/cred/encryption-config.json --etcd-cafile=/var/lib/rancher/rke2/server/tls/etcd/server-ca.crt --etcd-certfile=/var/lib/rancher/rke2/server/tls/etcd/client.crt --etcd-keyfile=/var/lib/rancher/rke2/server/tls/etcd/client.key --etcd-servers=https://127.0.0.1:2379 --feature-gates=JobTrackingWithFinalizers=true --kubelet-certificate-authority=/var/lib/rancher/rke2/server/tls/server-ca.crt --kubelet-client-certificate=/var/lib/rancher/rke2/server/tls/client-kube-apiserver.crt --kubelet-client-key=/var/lib/rancher/rke2/server/tls/client-kube-apiserver.key --kubelet-preferred-address-types=InternalIP,ExternalIP,Hostname --profiling=false --proxy-client-cert-file=/var/lib/rancher/rke2/server/tls/client-auth-proxy.crt --proxy-client-key-file=/var/lib/rancher/rke2/server/tls/client-auth-proxy.key --requestheader-allowed-names=system:auth-proxy --requestheader-client-ca-file=/var/lib/rancher/rke2/server/tls/request-header-ca.crt --requestheader-extra-headers-prefix=X-Remote-Extra- --requestheader-group-headers=X-Remote-Group --requestheader-username-headers=X-Remote-User --secure-port=6443 --service-account-issuer=https://kubernetes.default.svc.cluster.local --service-account-key-file=/var/lib/rancher/rke2/server/tls/service.key --service-account-signing-key-file=/var/lib/rancher/rke2/server/tls/service.current.key --service-cluster-ip-range=10.43.0.0/16 --service-node-port-range=30000-32767 --storage-backend=etcd3 --tls-cert-file=/var/lib/rancher/rke2/server/tls/serving-kube-apiserver.crt --tls-cipher-suites=TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305,TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305 --tls-private-key-file=/var/lib/rancher/rke2/server/tls/serving-kube-apiserver.key root 2652 2539 2 Sep11 ? 00:24:53 kube-controller-manager --flex-volume-plugin-dir=/var/lib/kubelet/volumeplugins --terminated-pod-gc-threshold=1000 --permit-port-sharing=true --allocate-node-cidrs=true --authentication-kubeconfig=/var/lib/rancher/rke2/server/cred/controller.kubeconfig --authorization-kubeconfig=/var/lib/rancher/rke2/server/cred/controller.kubeconfig --bind-address=127.0.0.1 --cert-dir=/var/lib/rancher/rke2/server/tls/kube-controller-manager --cluster-cidr=10.42.0.0/16 --cluster-signing-kube-apiserver-client-cert-file=/var/lib/rancher/rke2/server/tls/client-ca.nochain.crt --cluster-signing-kube-apiserver-client-key-file=/var/lib/rancher/rke2/server/tls/client-ca.key --cluster-signing-kubelet-client-cert-file=/var/lib/rancher/rke2/server/tls/client-ca.nochain.crt --cluster-signing-kubelet-client-key-file=/var/lib/rancher/rke2/server/tls/client-ca.key --cluster-signing-kubelet-serving-cert-file=/var/lib/rancher/rke2/server/tls/server-ca.nochain.crt --cluster-signing-kubelet-serving-key-file=/var/lib/rancher/rke2/server/tls/server-ca.key --cluster-signing-legacy-unknown-cert-file=/var/lib/rancher/rke2/server/tls/server-ca.nochain.crt --cluster-signing-legacy-unknown-key-file=/var/lib/rancher/rke2/server/tls/server-ca.key --configure-cloud-routes=false --controllers=*,tokencleaner,-service,-route,-cloud-node-lifecycle --feature-gates=JobTrackingWithFinalizers=true --kubeconfig=/var/lib/rancher/rke2/server/cred/controller.kubeconfig --profiling=false --root-ca-file=/var/lib/rancher/rke2/server/tls/server-ca.crt --secure-port=10257 --service-account-private-key-file=/var/lib/rancher/rke2/server/tls/service.current.key --service-cluster-ip-range=10.43.0.0/16 --use-service-account-credentials=true +``` + +### 1.2.24 Ensure that the --service-account-key-file argument is set as appropriate (Automated) + + +**Result:** pass + +**Remediation:** +Edit the API server pod specification file /var/lib/rancher/rke2/agent/pod-manifests/kube-apiserver.yaml +on the control plane node and set the --service-account-key-file parameter +to the public key file for service accounts. For example, +--service-account-key-file= + +**Audit:** + +```bash +/bin/ps -ef | grep kube-apiserver | grep -v grep +``` + +**Expected Result**: + +```console +'--service-account-key-file' is present +``` + +**Returned Value**: + +```console +root 2489 2419 8 Sep11 ? 01:41:54 kube-apiserver --admission-control-config-file=/etc/rancher/rke2/rke2-pss.yaml --audit-policy-file=/etc/rancher/rke2/audit-policy.yaml --audit-log-maxage=30 --audit-log-maxbackup=10 --audit-log-maxsize=100 --audit-log-path=/var/lib/rancher/rke2/server/logs/audit.log --admission-control-config-file=/etc/rancher/rke2/config/rancher-psact.yaml --allow-privileged=true --anonymous-auth=false --api-audiences=https://kubernetes.default.svc.cluster.local,rke2 --authorization-mode=Node,RBAC --bind-address=0.0.0.0 --cert-dir=/var/lib/rancher/rke2/server/tls/temporary-certs --client-ca-file=/var/lib/rancher/rke2/server/tls/client-ca.crt --egress-selector-config-file=/var/lib/rancher/rke2/server/etc/egress-selector-config.yaml --enable-admission-plugins=NodeRestriction --enable-aggregator-routing=true --enable-bootstrap-token-auth=true --encryption-provider-config=/var/lib/rancher/rke2/server/cred/encryption-config.json --etcd-cafile=/var/lib/rancher/rke2/server/tls/etcd/server-ca.crt --etcd-certfile=/var/lib/rancher/rke2/server/tls/etcd/client.crt --etcd-keyfile=/var/lib/rancher/rke2/server/tls/etcd/client.key --etcd-servers=https://127.0.0.1:2379 --feature-gates=JobTrackingWithFinalizers=true --kubelet-certificate-authority=/var/lib/rancher/rke2/server/tls/server-ca.crt --kubelet-client-certificate=/var/lib/rancher/rke2/server/tls/client-kube-apiserver.crt --kubelet-client-key=/var/lib/rancher/rke2/server/tls/client-kube-apiserver.key --kubelet-preferred-address-types=InternalIP,ExternalIP,Hostname --profiling=false --proxy-client-cert-file=/var/lib/rancher/rke2/server/tls/client-auth-proxy.crt --proxy-client-key-file=/var/lib/rancher/rke2/server/tls/client-auth-proxy.key --requestheader-allowed-names=system:auth-proxy --requestheader-client-ca-file=/var/lib/rancher/rke2/server/tls/request-header-ca.crt --requestheader-extra-headers-prefix=X-Remote-Extra- --requestheader-group-headers=X-Remote-Group --requestheader-username-headers=X-Remote-User --secure-port=6443 --service-account-issuer=https://kubernetes.default.svc.cluster.local --service-account-key-file=/var/lib/rancher/rke2/server/tls/service.key --service-account-signing-key-file=/var/lib/rancher/rke2/server/tls/service.current.key --service-cluster-ip-range=10.43.0.0/16 --service-node-port-range=30000-32767 --storage-backend=etcd3 --tls-cert-file=/var/lib/rancher/rke2/server/tls/serving-kube-apiserver.crt --tls-cipher-suites=TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305,TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305 --tls-private-key-file=/var/lib/rancher/rke2/server/tls/serving-kube-apiserver.key root 2652 2539 2 Sep11 ? 00:24:53 kube-controller-manager --flex-volume-plugin-dir=/var/lib/kubelet/volumeplugins --terminated-pod-gc-threshold=1000 --permit-port-sharing=true --allocate-node-cidrs=true --authentication-kubeconfig=/var/lib/rancher/rke2/server/cred/controller.kubeconfig --authorization-kubeconfig=/var/lib/rancher/rke2/server/cred/controller.kubeconfig --bind-address=127.0.0.1 --cert-dir=/var/lib/rancher/rke2/server/tls/kube-controller-manager --cluster-cidr=10.42.0.0/16 --cluster-signing-kube-apiserver-client-cert-file=/var/lib/rancher/rke2/server/tls/client-ca.nochain.crt --cluster-signing-kube-apiserver-client-key-file=/var/lib/rancher/rke2/server/tls/client-ca.key --cluster-signing-kubelet-client-cert-file=/var/lib/rancher/rke2/server/tls/client-ca.nochain.crt --cluster-signing-kubelet-client-key-file=/var/lib/rancher/rke2/server/tls/client-ca.key --cluster-signing-kubelet-serving-cert-file=/var/lib/rancher/rke2/server/tls/server-ca.nochain.crt --cluster-signing-kubelet-serving-key-file=/var/lib/rancher/rke2/server/tls/server-ca.key --cluster-signing-legacy-unknown-cert-file=/var/lib/rancher/rke2/server/tls/server-ca.nochain.crt --cluster-signing-legacy-unknown-key-file=/var/lib/rancher/rke2/server/tls/server-ca.key --configure-cloud-routes=false --controllers=*,tokencleaner,-service,-route,-cloud-node-lifecycle --feature-gates=JobTrackingWithFinalizers=true --kubeconfig=/var/lib/rancher/rke2/server/cred/controller.kubeconfig --profiling=false --root-ca-file=/var/lib/rancher/rke2/server/tls/server-ca.crt --secure-port=10257 --service-account-private-key-file=/var/lib/rancher/rke2/server/tls/service.current.key --service-cluster-ip-range=10.43.0.0/16 --use-service-account-credentials=true +``` + +### 1.2.25 Ensure that the --etcd-certfile and --etcd-keyfile arguments are set as appropriate (Automated) + + +**Result:** pass + +**Remediation:** +Follow the Kubernetes documentation and set up the TLS connection between the apiserver and etcd. +Then, edit the API server pod specification file /var/lib/rancher/rke2/agent/pod-manifests/kube-apiserver.yaml +on the control plane node and set the etcd certificate and key file parameters. +--etcd-certfile= +--etcd-keyfile= + +**Audit:** + +```bash +/bin/ps -ef | grep kube-apiserver | grep -v grep +``` + +**Expected Result**: + +```console +'--etcd-certfile' is present AND '--etcd-keyfile' is present +``` + +**Returned Value**: + +```console +root 2489 2419 8 Sep11 ? 01:41:54 kube-apiserver --admission-control-config-file=/etc/rancher/rke2/rke2-pss.yaml --audit-policy-file=/etc/rancher/rke2/audit-policy.yaml --audit-log-maxage=30 --audit-log-maxbackup=10 --audit-log-maxsize=100 --audit-log-path=/var/lib/rancher/rke2/server/logs/audit.log --admission-control-config-file=/etc/rancher/rke2/config/rancher-psact.yaml --allow-privileged=true --anonymous-auth=false --api-audiences=https://kubernetes.default.svc.cluster.local,rke2 --authorization-mode=Node,RBAC --bind-address=0.0.0.0 --cert-dir=/var/lib/rancher/rke2/server/tls/temporary-certs --client-ca-file=/var/lib/rancher/rke2/server/tls/client-ca.crt --egress-selector-config-file=/var/lib/rancher/rke2/server/etc/egress-selector-config.yaml --enable-admission-plugins=NodeRestriction --enable-aggregator-routing=true --enable-bootstrap-token-auth=true --encryption-provider-config=/var/lib/rancher/rke2/server/cred/encryption-config.json --etcd-cafile=/var/lib/rancher/rke2/server/tls/etcd/server-ca.crt --etcd-certfile=/var/lib/rancher/rke2/server/tls/etcd/client.crt --etcd-keyfile=/var/lib/rancher/rke2/server/tls/etcd/client.key --etcd-servers=https://127.0.0.1:2379 --feature-gates=JobTrackingWithFinalizers=true --kubelet-certificate-authority=/var/lib/rancher/rke2/server/tls/server-ca.crt --kubelet-client-certificate=/var/lib/rancher/rke2/server/tls/client-kube-apiserver.crt --kubelet-client-key=/var/lib/rancher/rke2/server/tls/client-kube-apiserver.key --kubelet-preferred-address-types=InternalIP,ExternalIP,Hostname --profiling=false --proxy-client-cert-file=/var/lib/rancher/rke2/server/tls/client-auth-proxy.crt --proxy-client-key-file=/var/lib/rancher/rke2/server/tls/client-auth-proxy.key --requestheader-allowed-names=system:auth-proxy --requestheader-client-ca-file=/var/lib/rancher/rke2/server/tls/request-header-ca.crt --requestheader-extra-headers-prefix=X-Remote-Extra- --requestheader-group-headers=X-Remote-Group --requestheader-username-headers=X-Remote-User --secure-port=6443 --service-account-issuer=https://kubernetes.default.svc.cluster.local --service-account-key-file=/var/lib/rancher/rke2/server/tls/service.key --service-account-signing-key-file=/var/lib/rancher/rke2/server/tls/service.current.key --service-cluster-ip-range=10.43.0.0/16 --service-node-port-range=30000-32767 --storage-backend=etcd3 --tls-cert-file=/var/lib/rancher/rke2/server/tls/serving-kube-apiserver.crt --tls-cipher-suites=TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305,TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305 --tls-private-key-file=/var/lib/rancher/rke2/server/tls/serving-kube-apiserver.key root 2652 2539 2 Sep11 ? 00:24:53 kube-controller-manager --flex-volume-plugin-dir=/var/lib/kubelet/volumeplugins --terminated-pod-gc-threshold=1000 --permit-port-sharing=true --allocate-node-cidrs=true --authentication-kubeconfig=/var/lib/rancher/rke2/server/cred/controller.kubeconfig --authorization-kubeconfig=/var/lib/rancher/rke2/server/cred/controller.kubeconfig --bind-address=127.0.0.1 --cert-dir=/var/lib/rancher/rke2/server/tls/kube-controller-manager --cluster-cidr=10.42.0.0/16 --cluster-signing-kube-apiserver-client-cert-file=/var/lib/rancher/rke2/server/tls/client-ca.nochain.crt --cluster-signing-kube-apiserver-client-key-file=/var/lib/rancher/rke2/server/tls/client-ca.key --cluster-signing-kubelet-client-cert-file=/var/lib/rancher/rke2/server/tls/client-ca.nochain.crt --cluster-signing-kubelet-client-key-file=/var/lib/rancher/rke2/server/tls/client-ca.key --cluster-signing-kubelet-serving-cert-file=/var/lib/rancher/rke2/server/tls/server-ca.nochain.crt --cluster-signing-kubelet-serving-key-file=/var/lib/rancher/rke2/server/tls/server-ca.key --cluster-signing-legacy-unknown-cert-file=/var/lib/rancher/rke2/server/tls/server-ca.nochain.crt --cluster-signing-legacy-unknown-key-file=/var/lib/rancher/rke2/server/tls/server-ca.key --configure-cloud-routes=false --controllers=*,tokencleaner,-service,-route,-cloud-node-lifecycle --feature-gates=JobTrackingWithFinalizers=true --kubeconfig=/var/lib/rancher/rke2/server/cred/controller.kubeconfig --profiling=false --root-ca-file=/var/lib/rancher/rke2/server/tls/server-ca.crt --secure-port=10257 --service-account-private-key-file=/var/lib/rancher/rke2/server/tls/service.current.key --service-cluster-ip-range=10.43.0.0/16 --use-service-account-credentials=true +``` + +### 1.2.26 Ensure that the --tls-cert-file and --tls-private-key-file arguments are set as appropriate (Automated) + + +**Result:** pass + +**Remediation:** +Follow the Kubernetes documentation and set up the TLS connection on the apiserver. +Then, edit the API server pod specification file /var/lib/rancher/rke2/agent/pod-manifests/kube-apiserver.yaml +on the control plane node and set the TLS certificate and private key file parameters. +--tls-cert-file= +--tls-private-key-file= + +**Audit:** + +```bash +/bin/ps -ef | grep kube-apiserver | grep -v grep +``` + +**Expected Result**: + +```console +'--tls-cert-file' is present AND '--tls-private-key-file' is present +``` + +**Returned Value**: + +```console +root 2489 2419 8 Sep11 ? 01:41:54 kube-apiserver --admission-control-config-file=/etc/rancher/rke2/rke2-pss.yaml --audit-policy-file=/etc/rancher/rke2/audit-policy.yaml --audit-log-maxage=30 --audit-log-maxbackup=10 --audit-log-maxsize=100 --audit-log-path=/var/lib/rancher/rke2/server/logs/audit.log --admission-control-config-file=/etc/rancher/rke2/config/rancher-psact.yaml --allow-privileged=true --anonymous-auth=false --api-audiences=https://kubernetes.default.svc.cluster.local,rke2 --authorization-mode=Node,RBAC --bind-address=0.0.0.0 --cert-dir=/var/lib/rancher/rke2/server/tls/temporary-certs --client-ca-file=/var/lib/rancher/rke2/server/tls/client-ca.crt --egress-selector-config-file=/var/lib/rancher/rke2/server/etc/egress-selector-config.yaml --enable-admission-plugins=NodeRestriction --enable-aggregator-routing=true --enable-bootstrap-token-auth=true --encryption-provider-config=/var/lib/rancher/rke2/server/cred/encryption-config.json --etcd-cafile=/var/lib/rancher/rke2/server/tls/etcd/server-ca.crt --etcd-certfile=/var/lib/rancher/rke2/server/tls/etcd/client.crt --etcd-keyfile=/var/lib/rancher/rke2/server/tls/etcd/client.key --etcd-servers=https://127.0.0.1:2379 --feature-gates=JobTrackingWithFinalizers=true --kubelet-certificate-authority=/var/lib/rancher/rke2/server/tls/server-ca.crt --kubelet-client-certificate=/var/lib/rancher/rke2/server/tls/client-kube-apiserver.crt --kubelet-client-key=/var/lib/rancher/rke2/server/tls/client-kube-apiserver.key --kubelet-preferred-address-types=InternalIP,ExternalIP,Hostname --profiling=false --proxy-client-cert-file=/var/lib/rancher/rke2/server/tls/client-auth-proxy.crt --proxy-client-key-file=/var/lib/rancher/rke2/server/tls/client-auth-proxy.key --requestheader-allowed-names=system:auth-proxy --requestheader-client-ca-file=/var/lib/rancher/rke2/server/tls/request-header-ca.crt --requestheader-extra-headers-prefix=X-Remote-Extra- --requestheader-group-headers=X-Remote-Group --requestheader-username-headers=X-Remote-User --secure-port=6443 --service-account-issuer=https://kubernetes.default.svc.cluster.local --service-account-key-file=/var/lib/rancher/rke2/server/tls/service.key --service-account-signing-key-file=/var/lib/rancher/rke2/server/tls/service.current.key --service-cluster-ip-range=10.43.0.0/16 --service-node-port-range=30000-32767 --storage-backend=etcd3 --tls-cert-file=/var/lib/rancher/rke2/server/tls/serving-kube-apiserver.crt --tls-cipher-suites=TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305,TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305 --tls-private-key-file=/var/lib/rancher/rke2/server/tls/serving-kube-apiserver.key root 2652 2539 2 Sep11 ? 00:24:53 kube-controller-manager --flex-volume-plugin-dir=/var/lib/kubelet/volumeplugins --terminated-pod-gc-threshold=1000 --permit-port-sharing=true --allocate-node-cidrs=true --authentication-kubeconfig=/var/lib/rancher/rke2/server/cred/controller.kubeconfig --authorization-kubeconfig=/var/lib/rancher/rke2/server/cred/controller.kubeconfig --bind-address=127.0.0.1 --cert-dir=/var/lib/rancher/rke2/server/tls/kube-controller-manager --cluster-cidr=10.42.0.0/16 --cluster-signing-kube-apiserver-client-cert-file=/var/lib/rancher/rke2/server/tls/client-ca.nochain.crt --cluster-signing-kube-apiserver-client-key-file=/var/lib/rancher/rke2/server/tls/client-ca.key --cluster-signing-kubelet-client-cert-file=/var/lib/rancher/rke2/server/tls/client-ca.nochain.crt --cluster-signing-kubelet-client-key-file=/var/lib/rancher/rke2/server/tls/client-ca.key --cluster-signing-kubelet-serving-cert-file=/var/lib/rancher/rke2/server/tls/server-ca.nochain.crt --cluster-signing-kubelet-serving-key-file=/var/lib/rancher/rke2/server/tls/server-ca.key --cluster-signing-legacy-unknown-cert-file=/var/lib/rancher/rke2/server/tls/server-ca.nochain.crt --cluster-signing-legacy-unknown-key-file=/var/lib/rancher/rke2/server/tls/server-ca.key --configure-cloud-routes=false --controllers=*,tokencleaner,-service,-route,-cloud-node-lifecycle --feature-gates=JobTrackingWithFinalizers=true --kubeconfig=/var/lib/rancher/rke2/server/cred/controller.kubeconfig --profiling=false --root-ca-file=/var/lib/rancher/rke2/server/tls/server-ca.crt --secure-port=10257 --service-account-private-key-file=/var/lib/rancher/rke2/server/tls/service.current.key --service-cluster-ip-range=10.43.0.0/16 --use-service-account-credentials=true +``` + +### 1.2.27 Ensure that the --client-ca-file argument is set as appropriate (Automated) + + +**Result:** pass + +**Remediation:** +Follow the Kubernetes documentation and set up the TLS connection on the apiserver. +Then, edit the API server pod specification file /var/lib/rancher/rke2/agent/pod-manifests/kube-apiserver.yaml +on the control plane node and set the client certificate authority file. +--client-ca-file= + +**Audit:** + +```bash +/bin/ps -ef | grep kube-apiserver | grep -v grep +``` + +**Expected Result**: + +```console +'--client-ca-file' is present +``` + +**Returned Value**: + +```console +root 2489 2419 8 Sep11 ? 01:41:54 kube-apiserver --admission-control-config-file=/etc/rancher/rke2/rke2-pss.yaml --audit-policy-file=/etc/rancher/rke2/audit-policy.yaml --audit-log-maxage=30 --audit-log-maxbackup=10 --audit-log-maxsize=100 --audit-log-path=/var/lib/rancher/rke2/server/logs/audit.log --admission-control-config-file=/etc/rancher/rke2/config/rancher-psact.yaml --allow-privileged=true --anonymous-auth=false --api-audiences=https://kubernetes.default.svc.cluster.local,rke2 --authorization-mode=Node,RBAC --bind-address=0.0.0.0 --cert-dir=/var/lib/rancher/rke2/server/tls/temporary-certs --client-ca-file=/var/lib/rancher/rke2/server/tls/client-ca.crt --egress-selector-config-file=/var/lib/rancher/rke2/server/etc/egress-selector-config.yaml --enable-admission-plugins=NodeRestriction --enable-aggregator-routing=true --enable-bootstrap-token-auth=true --encryption-provider-config=/var/lib/rancher/rke2/server/cred/encryption-config.json --etcd-cafile=/var/lib/rancher/rke2/server/tls/etcd/server-ca.crt --etcd-certfile=/var/lib/rancher/rke2/server/tls/etcd/client.crt --etcd-keyfile=/var/lib/rancher/rke2/server/tls/etcd/client.key --etcd-servers=https://127.0.0.1:2379 --feature-gates=JobTrackingWithFinalizers=true --kubelet-certificate-authority=/var/lib/rancher/rke2/server/tls/server-ca.crt --kubelet-client-certificate=/var/lib/rancher/rke2/server/tls/client-kube-apiserver.crt --kubelet-client-key=/var/lib/rancher/rke2/server/tls/client-kube-apiserver.key --kubelet-preferred-address-types=InternalIP,ExternalIP,Hostname --profiling=false --proxy-client-cert-file=/var/lib/rancher/rke2/server/tls/client-auth-proxy.crt --proxy-client-key-file=/var/lib/rancher/rke2/server/tls/client-auth-proxy.key --requestheader-allowed-names=system:auth-proxy --requestheader-client-ca-file=/var/lib/rancher/rke2/server/tls/request-header-ca.crt --requestheader-extra-headers-prefix=X-Remote-Extra- --requestheader-group-headers=X-Remote-Group --requestheader-username-headers=X-Remote-User --secure-port=6443 --service-account-issuer=https://kubernetes.default.svc.cluster.local --service-account-key-file=/var/lib/rancher/rke2/server/tls/service.key --service-account-signing-key-file=/var/lib/rancher/rke2/server/tls/service.current.key --service-cluster-ip-range=10.43.0.0/16 --service-node-port-range=30000-32767 --storage-backend=etcd3 --tls-cert-file=/var/lib/rancher/rke2/server/tls/serving-kube-apiserver.crt --tls-cipher-suites=TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305,TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305 --tls-private-key-file=/var/lib/rancher/rke2/server/tls/serving-kube-apiserver.key root 2652 2539 2 Sep11 ? 00:24:53 kube-controller-manager --flex-volume-plugin-dir=/var/lib/kubelet/volumeplugins --terminated-pod-gc-threshold=1000 --permit-port-sharing=true --allocate-node-cidrs=true --authentication-kubeconfig=/var/lib/rancher/rke2/server/cred/controller.kubeconfig --authorization-kubeconfig=/var/lib/rancher/rke2/server/cred/controller.kubeconfig --bind-address=127.0.0.1 --cert-dir=/var/lib/rancher/rke2/server/tls/kube-controller-manager --cluster-cidr=10.42.0.0/16 --cluster-signing-kube-apiserver-client-cert-file=/var/lib/rancher/rke2/server/tls/client-ca.nochain.crt --cluster-signing-kube-apiserver-client-key-file=/var/lib/rancher/rke2/server/tls/client-ca.key --cluster-signing-kubelet-client-cert-file=/var/lib/rancher/rke2/server/tls/client-ca.nochain.crt --cluster-signing-kubelet-client-key-file=/var/lib/rancher/rke2/server/tls/client-ca.key --cluster-signing-kubelet-serving-cert-file=/var/lib/rancher/rke2/server/tls/server-ca.nochain.crt --cluster-signing-kubelet-serving-key-file=/var/lib/rancher/rke2/server/tls/server-ca.key --cluster-signing-legacy-unknown-cert-file=/var/lib/rancher/rke2/server/tls/server-ca.nochain.crt --cluster-signing-legacy-unknown-key-file=/var/lib/rancher/rke2/server/tls/server-ca.key --configure-cloud-routes=false --controllers=*,tokencleaner,-service,-route,-cloud-node-lifecycle --feature-gates=JobTrackingWithFinalizers=true --kubeconfig=/var/lib/rancher/rke2/server/cred/controller.kubeconfig --profiling=false --root-ca-file=/var/lib/rancher/rke2/server/tls/server-ca.crt --secure-port=10257 --service-account-private-key-file=/var/lib/rancher/rke2/server/tls/service.current.key --service-cluster-ip-range=10.43.0.0/16 --use-service-account-credentials=true +``` + +### 1.2.28 Ensure that the --etcd-cafile argument is set as appropriate (Automated) + + +**Result:** pass + +**Remediation:** +Follow the Kubernetes documentation and set up the TLS connection between the apiserver and etcd. +Then, edit the API server pod specification file /var/lib/rancher/rke2/agent/pod-manifests/kube-apiserver.yaml +on the control plane node and set the etcd certificate authority file parameter. +--etcd-cafile= + +**Audit:** + +```bash +/bin/ps -ef | grep kube-apiserver | grep -v grep +``` + +**Expected Result**: + +```console +'--etcd-cafile' is present +``` + +**Returned Value**: + +```console +root 2489 2419 8 Sep11 ? 01:41:54 kube-apiserver --admission-control-config-file=/etc/rancher/rke2/rke2-pss.yaml --audit-policy-file=/etc/rancher/rke2/audit-policy.yaml --audit-log-maxage=30 --audit-log-maxbackup=10 --audit-log-maxsize=100 --audit-log-path=/var/lib/rancher/rke2/server/logs/audit.log --admission-control-config-file=/etc/rancher/rke2/config/rancher-psact.yaml --allow-privileged=true --anonymous-auth=false --api-audiences=https://kubernetes.default.svc.cluster.local,rke2 --authorization-mode=Node,RBAC --bind-address=0.0.0.0 --cert-dir=/var/lib/rancher/rke2/server/tls/temporary-certs --client-ca-file=/var/lib/rancher/rke2/server/tls/client-ca.crt --egress-selector-config-file=/var/lib/rancher/rke2/server/etc/egress-selector-config.yaml --enable-admission-plugins=NodeRestriction --enable-aggregator-routing=true --enable-bootstrap-token-auth=true --encryption-provider-config=/var/lib/rancher/rke2/server/cred/encryption-config.json --etcd-cafile=/var/lib/rancher/rke2/server/tls/etcd/server-ca.crt --etcd-certfile=/var/lib/rancher/rke2/server/tls/etcd/client.crt --etcd-keyfile=/var/lib/rancher/rke2/server/tls/etcd/client.key --etcd-servers=https://127.0.0.1:2379 --feature-gates=JobTrackingWithFinalizers=true --kubelet-certificate-authority=/var/lib/rancher/rke2/server/tls/server-ca.crt --kubelet-client-certificate=/var/lib/rancher/rke2/server/tls/client-kube-apiserver.crt --kubelet-client-key=/var/lib/rancher/rke2/server/tls/client-kube-apiserver.key --kubelet-preferred-address-types=InternalIP,ExternalIP,Hostname --profiling=false --proxy-client-cert-file=/var/lib/rancher/rke2/server/tls/client-auth-proxy.crt --proxy-client-key-file=/var/lib/rancher/rke2/server/tls/client-auth-proxy.key --requestheader-allowed-names=system:auth-proxy --requestheader-client-ca-file=/var/lib/rancher/rke2/server/tls/request-header-ca.crt --requestheader-extra-headers-prefix=X-Remote-Extra- --requestheader-group-headers=X-Remote-Group --requestheader-username-headers=X-Remote-User --secure-port=6443 --service-account-issuer=https://kubernetes.default.svc.cluster.local --service-account-key-file=/var/lib/rancher/rke2/server/tls/service.key --service-account-signing-key-file=/var/lib/rancher/rke2/server/tls/service.current.key --service-cluster-ip-range=10.43.0.0/16 --service-node-port-range=30000-32767 --storage-backend=etcd3 --tls-cert-file=/var/lib/rancher/rke2/server/tls/serving-kube-apiserver.crt --tls-cipher-suites=TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305,TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305 --tls-private-key-file=/var/lib/rancher/rke2/server/tls/serving-kube-apiserver.key root 2652 2539 2 Sep11 ? 00:24:53 kube-controller-manager --flex-volume-plugin-dir=/var/lib/kubelet/volumeplugins --terminated-pod-gc-threshold=1000 --permit-port-sharing=true --allocate-node-cidrs=true --authentication-kubeconfig=/var/lib/rancher/rke2/server/cred/controller.kubeconfig --authorization-kubeconfig=/var/lib/rancher/rke2/server/cred/controller.kubeconfig --bind-address=127.0.0.1 --cert-dir=/var/lib/rancher/rke2/server/tls/kube-controller-manager --cluster-cidr=10.42.0.0/16 --cluster-signing-kube-apiserver-client-cert-file=/var/lib/rancher/rke2/server/tls/client-ca.nochain.crt --cluster-signing-kube-apiserver-client-key-file=/var/lib/rancher/rke2/server/tls/client-ca.key --cluster-signing-kubelet-client-cert-file=/var/lib/rancher/rke2/server/tls/client-ca.nochain.crt --cluster-signing-kubelet-client-key-file=/var/lib/rancher/rke2/server/tls/client-ca.key --cluster-signing-kubelet-serving-cert-file=/var/lib/rancher/rke2/server/tls/server-ca.nochain.crt --cluster-signing-kubelet-serving-key-file=/var/lib/rancher/rke2/server/tls/server-ca.key --cluster-signing-legacy-unknown-cert-file=/var/lib/rancher/rke2/server/tls/server-ca.nochain.crt --cluster-signing-legacy-unknown-key-file=/var/lib/rancher/rke2/server/tls/server-ca.key --configure-cloud-routes=false --controllers=*,tokencleaner,-service,-route,-cloud-node-lifecycle --feature-gates=JobTrackingWithFinalizers=true --kubeconfig=/var/lib/rancher/rke2/server/cred/controller.kubeconfig --profiling=false --root-ca-file=/var/lib/rancher/rke2/server/tls/server-ca.crt --secure-port=10257 --service-account-private-key-file=/var/lib/rancher/rke2/server/tls/service.current.key --service-cluster-ip-range=10.43.0.0/16 --use-service-account-credentials=true +``` + +### 1.2.29 Ensure that the --encryption-provider-config argument is set as appropriate (Manual) + + +**Result:** pass + +**Remediation:** +Follow the Kubernetes documentation and configure a EncryptionConfig file. +Then, edit the API server pod specification file /var/lib/rancher/rke2/agent/pod-manifests/kube-apiserver.yaml +on the control plane node and set the --encryption-provider-config parameter to the path of that file. +For example, --encryption-provider-config= + +**Audit:** + +```bash +/bin/ps -ef | grep kube-apiserver | grep -v grep +``` + +**Expected Result**: + +```console +'--encryption-provider-config' is present +``` + +**Returned Value**: + +```console +root 2489 2419 8 Sep11 ? 01:41:54 kube-apiserver --admission-control-config-file=/etc/rancher/rke2/rke2-pss.yaml --audit-policy-file=/etc/rancher/rke2/audit-policy.yaml --audit-log-maxage=30 --audit-log-maxbackup=10 --audit-log-maxsize=100 --audit-log-path=/var/lib/rancher/rke2/server/logs/audit.log --admission-control-config-file=/etc/rancher/rke2/config/rancher-psact.yaml --allow-privileged=true --anonymous-auth=false --api-audiences=https://kubernetes.default.svc.cluster.local,rke2 --authorization-mode=Node,RBAC --bind-address=0.0.0.0 --cert-dir=/var/lib/rancher/rke2/server/tls/temporary-certs --client-ca-file=/var/lib/rancher/rke2/server/tls/client-ca.crt --egress-selector-config-file=/var/lib/rancher/rke2/server/etc/egress-selector-config.yaml --enable-admission-plugins=NodeRestriction --enable-aggregator-routing=true --enable-bootstrap-token-auth=true --encryption-provider-config=/var/lib/rancher/rke2/server/cred/encryption-config.json --etcd-cafile=/var/lib/rancher/rke2/server/tls/etcd/server-ca.crt --etcd-certfile=/var/lib/rancher/rke2/server/tls/etcd/client.crt --etcd-keyfile=/var/lib/rancher/rke2/server/tls/etcd/client.key --etcd-servers=https://127.0.0.1:2379 --feature-gates=JobTrackingWithFinalizers=true --kubelet-certificate-authority=/var/lib/rancher/rke2/server/tls/server-ca.crt --kubelet-client-certificate=/var/lib/rancher/rke2/server/tls/client-kube-apiserver.crt --kubelet-client-key=/var/lib/rancher/rke2/server/tls/client-kube-apiserver.key --kubelet-preferred-address-types=InternalIP,ExternalIP,Hostname --profiling=false --proxy-client-cert-file=/var/lib/rancher/rke2/server/tls/client-auth-proxy.crt --proxy-client-key-file=/var/lib/rancher/rke2/server/tls/client-auth-proxy.key --requestheader-allowed-names=system:auth-proxy --requestheader-client-ca-file=/var/lib/rancher/rke2/server/tls/request-header-ca.crt --requestheader-extra-headers-prefix=X-Remote-Extra- --requestheader-group-headers=X-Remote-Group --requestheader-username-headers=X-Remote-User --secure-port=6443 --service-account-issuer=https://kubernetes.default.svc.cluster.local --service-account-key-file=/var/lib/rancher/rke2/server/tls/service.key --service-account-signing-key-file=/var/lib/rancher/rke2/server/tls/service.current.key --service-cluster-ip-range=10.43.0.0/16 --service-node-port-range=30000-32767 --storage-backend=etcd3 --tls-cert-file=/var/lib/rancher/rke2/server/tls/serving-kube-apiserver.crt --tls-cipher-suites=TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305,TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305 --tls-private-key-file=/var/lib/rancher/rke2/server/tls/serving-kube-apiserver.key root 2652 2539 2 Sep11 ? 00:24:53 kube-controller-manager --flex-volume-plugin-dir=/var/lib/kubelet/volumeplugins --terminated-pod-gc-threshold=1000 --permit-port-sharing=true --allocate-node-cidrs=true --authentication-kubeconfig=/var/lib/rancher/rke2/server/cred/controller.kubeconfig --authorization-kubeconfig=/var/lib/rancher/rke2/server/cred/controller.kubeconfig --bind-address=127.0.0.1 --cert-dir=/var/lib/rancher/rke2/server/tls/kube-controller-manager --cluster-cidr=10.42.0.0/16 --cluster-signing-kube-apiserver-client-cert-file=/var/lib/rancher/rke2/server/tls/client-ca.nochain.crt --cluster-signing-kube-apiserver-client-key-file=/var/lib/rancher/rke2/server/tls/client-ca.key --cluster-signing-kubelet-client-cert-file=/var/lib/rancher/rke2/server/tls/client-ca.nochain.crt --cluster-signing-kubelet-client-key-file=/var/lib/rancher/rke2/server/tls/client-ca.key --cluster-signing-kubelet-serving-cert-file=/var/lib/rancher/rke2/server/tls/server-ca.nochain.crt --cluster-signing-kubelet-serving-key-file=/var/lib/rancher/rke2/server/tls/server-ca.key --cluster-signing-legacy-unknown-cert-file=/var/lib/rancher/rke2/server/tls/server-ca.nochain.crt --cluster-signing-legacy-unknown-key-file=/var/lib/rancher/rke2/server/tls/server-ca.key --configure-cloud-routes=false --controllers=*,tokencleaner,-service,-route,-cloud-node-lifecycle --feature-gates=JobTrackingWithFinalizers=true --kubeconfig=/var/lib/rancher/rke2/server/cred/controller.kubeconfig --profiling=false --root-ca-file=/var/lib/rancher/rke2/server/tls/server-ca.crt --secure-port=10257 --service-account-private-key-file=/var/lib/rancher/rke2/server/tls/service.current.key --service-cluster-ip-range=10.43.0.0/16 --use-service-account-credentials=true +``` + +### 1.2.30 Ensure that encryption providers are appropriately configured (Manual) + + +**Result:** warn + +**Remediation:** +Follow the Kubernetes documentation and configure a EncryptionConfig file. +In this file, choose aescbc, kms or secretbox as the encryption provider. + +**Audit:** + +```bash +ENCRYPTION_PROVIDER_CONFIG=$(ps -ef | grep kube-apiserver | grep -- --encryption-provider-config | sed 's%.*encryption-provider-config[= ]\([^ ]*\).*%\1%') if test -e $ENCRYPTION_PROVIDER_CONFIG; then grep -A1 'providers:' $ENCRYPTION_PROVIDER_CONFIG | tail -n1 | grep -o "[A-Za-z]*" | sed 's/^/provider=/'; fi +``` + +**Expected Result**: + +```console +'provider' is present +``` + +### 1.2.31 Ensure that the API Server only makes use of Strong Cryptographic Ciphers (Manual) + + +**Result:** Not Applicable + +**Remediation:** +Edit the API server pod specification file /etc/kubernetes/manifests/kube-apiserver.yaml +on the control plane node and set the below parameter. +--tls-cipher-suites=TLS_AES_128_GCM_SHA256,TLS_AES_256_GCM_SHA384,TLS_CHACHA20_POLY1305_SHA256, +TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA,TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256, +TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA,TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384, +TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305,TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256, +TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA,TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256, +TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305, +TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256,TLS_RSA_WITH_3DES_EDE_CBC_SHA,TLS_RSA_WITH_AES_128_CBC_SHA, +TLS_RSA_WITH_AES_128_GCM_SHA256,TLS_RSA_WITH_AES_256_CBC_SHA,TLS_RSA_WITH_AES_256_GCM_SHA384 +Not Applicable. + +## 1.3 Controller Manager +### 1.3.1 Ensure that the --terminated-pod-gc-threshold argument is set as appropriate (Manual) + + +**Result:** pass + +**Remediation:** +Edit the Controller Manager pod specification file /var/lib/rancher/rke2/agent/pod-manifests/kube-controller-manager.yaml +on the control plane node and set the --terminated-pod-gc-threshold to an appropriate threshold, +for example, --terminated-pod-gc-threshold=10 + +**Audit:** + +```bash +/bin/ps -ef | grep kube-controller-manager | grep -v grep +``` + +**Expected Result**: + +```console +'--terminated-pod-gc-threshold' is present +``` + +**Returned Value**: + +```console +root 2652 2539 2 Sep11 ? 00:24:53 kube-controller-manager --flex-volume-plugin-dir=/var/lib/kubelet/volumeplugins --terminated-pod-gc-threshold=1000 --permit-port-sharing=true --allocate-node-cidrs=true --authentication-kubeconfig=/var/lib/rancher/rke2/server/cred/controller.kubeconfig --authorization-kubeconfig=/var/lib/rancher/rke2/server/cred/controller.kubeconfig --bind-address=127.0.0.1 --cert-dir=/var/lib/rancher/rke2/server/tls/kube-controller-manager --cluster-cidr=10.42.0.0/16 --cluster-signing-kube-apiserver-client-cert-file=/var/lib/rancher/rke2/server/tls/client-ca.nochain.crt --cluster-signing-kube-apiserver-client-key-file=/var/lib/rancher/rke2/server/tls/client-ca.key --cluster-signing-kubelet-client-cert-file=/var/lib/rancher/rke2/server/tls/client-ca.nochain.crt --cluster-signing-kubelet-client-key-file=/var/lib/rancher/rke2/server/tls/client-ca.key --cluster-signing-kubelet-serving-cert-file=/var/lib/rancher/rke2/server/tls/server-ca.nochain.crt --cluster-signing-kubelet-serving-key-file=/var/lib/rancher/rke2/server/tls/server-ca.key --cluster-signing-legacy-unknown-cert-file=/var/lib/rancher/rke2/server/tls/server-ca.nochain.crt --cluster-signing-legacy-unknown-key-file=/var/lib/rancher/rke2/server/tls/server-ca.key --configure-cloud-routes=false --controllers=*,tokencleaner,-service,-route,-cloud-node-lifecycle --feature-gates=JobTrackingWithFinalizers=true --kubeconfig=/var/lib/rancher/rke2/server/cred/controller.kubeconfig --profiling=false --root-ca-file=/var/lib/rancher/rke2/server/tls/server-ca.crt --secure-port=10257 --service-account-private-key-file=/var/lib/rancher/rke2/server/tls/service.current.key --service-cluster-ip-range=10.43.0.0/16 --use-service-account-credentials=true +``` + +### 1.3.2 Ensure that the --profiling argument is set to false (Automated) + + +**Result:** pass + +**Remediation:** +Edit the Controller Manager pod specification file /var/lib/rancher/rke2/agent/pod-manifests/kube-controller-manager.yaml +on the control plane node and set the below parameter. +--profiling=false + +**Audit:** + +```bash +/bin/ps -ef | grep kube-controller-manager | grep -v grep +``` + +**Expected Result**: + +```console +'--profiling' is equal to 'false' +``` + +**Returned Value**: + +```console +root 2652 2539 2 Sep11 ? 00:24:53 kube-controller-manager --flex-volume-plugin-dir=/var/lib/kubelet/volumeplugins --terminated-pod-gc-threshold=1000 --permit-port-sharing=true --allocate-node-cidrs=true --authentication-kubeconfig=/var/lib/rancher/rke2/server/cred/controller.kubeconfig --authorization-kubeconfig=/var/lib/rancher/rke2/server/cred/controller.kubeconfig --bind-address=127.0.0.1 --cert-dir=/var/lib/rancher/rke2/server/tls/kube-controller-manager --cluster-cidr=10.42.0.0/16 --cluster-signing-kube-apiserver-client-cert-file=/var/lib/rancher/rke2/server/tls/client-ca.nochain.crt --cluster-signing-kube-apiserver-client-key-file=/var/lib/rancher/rke2/server/tls/client-ca.key --cluster-signing-kubelet-client-cert-file=/var/lib/rancher/rke2/server/tls/client-ca.nochain.crt --cluster-signing-kubelet-client-key-file=/var/lib/rancher/rke2/server/tls/client-ca.key --cluster-signing-kubelet-serving-cert-file=/var/lib/rancher/rke2/server/tls/server-ca.nochain.crt --cluster-signing-kubelet-serving-key-file=/var/lib/rancher/rke2/server/tls/server-ca.key --cluster-signing-legacy-unknown-cert-file=/var/lib/rancher/rke2/server/tls/server-ca.nochain.crt --cluster-signing-legacy-unknown-key-file=/var/lib/rancher/rke2/server/tls/server-ca.key --configure-cloud-routes=false --controllers=*,tokencleaner,-service,-route,-cloud-node-lifecycle --feature-gates=JobTrackingWithFinalizers=true --kubeconfig=/var/lib/rancher/rke2/server/cred/controller.kubeconfig --profiling=false --root-ca-file=/var/lib/rancher/rke2/server/tls/server-ca.crt --secure-port=10257 --service-account-private-key-file=/var/lib/rancher/rke2/server/tls/service.current.key --service-cluster-ip-range=10.43.0.0/16 --use-service-account-credentials=true +``` + +### 1.3.3 Ensure that the --use-service-account-credentials argument is set to true (Automated) + + +**Result:** pass + +**Remediation:** +Edit the Controller Manager pod specification file /var/lib/rancher/rke2/agent/pod-manifests/kube-controller-manager.yaml +on the control plane node to set the below parameter. +--use-service-account-credentials=true + +**Audit:** + +```bash +/bin/ps -ef | grep kube-controller-manager | grep -v grep +``` + +**Expected Result**: + +```console +'--use-service-account-credentials' is not equal to 'false' +``` + +**Returned Value**: + +```console +root 2652 2539 2 Sep11 ? 00:24:53 kube-controller-manager --flex-volume-plugin-dir=/var/lib/kubelet/volumeplugins --terminated-pod-gc-threshold=1000 --permit-port-sharing=true --allocate-node-cidrs=true --authentication-kubeconfig=/var/lib/rancher/rke2/server/cred/controller.kubeconfig --authorization-kubeconfig=/var/lib/rancher/rke2/server/cred/controller.kubeconfig --bind-address=127.0.0.1 --cert-dir=/var/lib/rancher/rke2/server/tls/kube-controller-manager --cluster-cidr=10.42.0.0/16 --cluster-signing-kube-apiserver-client-cert-file=/var/lib/rancher/rke2/server/tls/client-ca.nochain.crt --cluster-signing-kube-apiserver-client-key-file=/var/lib/rancher/rke2/server/tls/client-ca.key --cluster-signing-kubelet-client-cert-file=/var/lib/rancher/rke2/server/tls/client-ca.nochain.crt --cluster-signing-kubelet-client-key-file=/var/lib/rancher/rke2/server/tls/client-ca.key --cluster-signing-kubelet-serving-cert-file=/var/lib/rancher/rke2/server/tls/server-ca.nochain.crt --cluster-signing-kubelet-serving-key-file=/var/lib/rancher/rke2/server/tls/server-ca.key --cluster-signing-legacy-unknown-cert-file=/var/lib/rancher/rke2/server/tls/server-ca.nochain.crt --cluster-signing-legacy-unknown-key-file=/var/lib/rancher/rke2/server/tls/server-ca.key --configure-cloud-routes=false --controllers=*,tokencleaner,-service,-route,-cloud-node-lifecycle --feature-gates=JobTrackingWithFinalizers=true --kubeconfig=/var/lib/rancher/rke2/server/cred/controller.kubeconfig --profiling=false --root-ca-file=/var/lib/rancher/rke2/server/tls/server-ca.crt --secure-port=10257 --service-account-private-key-file=/var/lib/rancher/rke2/server/tls/service.current.key --service-cluster-ip-range=10.43.0.0/16 --use-service-account-credentials=true +``` + +### 1.3.4 Ensure that the --service-account-private-key-file argument is set as appropriate (Automated) + + +**Result:** pass + +**Remediation:** +Edit the Controller Manager pod specification file /var/lib/rancher/rke2/agent/pod-manifests/kube-controller-manager.yaml +on the control plane node and set the --service-account-private-key-file parameter +to the private key file for service accounts. +--service-account-private-key-file= + +**Audit:** + +```bash +/bin/ps -ef | grep kube-controller-manager | grep -v grep +``` + +**Expected Result**: + +```console +'--service-account-private-key-file' is present +``` + +**Returned Value**: + +```console +root 2652 2539 2 Sep11 ? 00:24:53 kube-controller-manager --flex-volume-plugin-dir=/var/lib/kubelet/volumeplugins --terminated-pod-gc-threshold=1000 --permit-port-sharing=true --allocate-node-cidrs=true --authentication-kubeconfig=/var/lib/rancher/rke2/server/cred/controller.kubeconfig --authorization-kubeconfig=/var/lib/rancher/rke2/server/cred/controller.kubeconfig --bind-address=127.0.0.1 --cert-dir=/var/lib/rancher/rke2/server/tls/kube-controller-manager --cluster-cidr=10.42.0.0/16 --cluster-signing-kube-apiserver-client-cert-file=/var/lib/rancher/rke2/server/tls/client-ca.nochain.crt --cluster-signing-kube-apiserver-client-key-file=/var/lib/rancher/rke2/server/tls/client-ca.key --cluster-signing-kubelet-client-cert-file=/var/lib/rancher/rke2/server/tls/client-ca.nochain.crt --cluster-signing-kubelet-client-key-file=/var/lib/rancher/rke2/server/tls/client-ca.key --cluster-signing-kubelet-serving-cert-file=/var/lib/rancher/rke2/server/tls/server-ca.nochain.crt --cluster-signing-kubelet-serving-key-file=/var/lib/rancher/rke2/server/tls/server-ca.key --cluster-signing-legacy-unknown-cert-file=/var/lib/rancher/rke2/server/tls/server-ca.nochain.crt --cluster-signing-legacy-unknown-key-file=/var/lib/rancher/rke2/server/tls/server-ca.key --configure-cloud-routes=false --controllers=*,tokencleaner,-service,-route,-cloud-node-lifecycle --feature-gates=JobTrackingWithFinalizers=true --kubeconfig=/var/lib/rancher/rke2/server/cred/controller.kubeconfig --profiling=false --root-ca-file=/var/lib/rancher/rke2/server/tls/server-ca.crt --secure-port=10257 --service-account-private-key-file=/var/lib/rancher/rke2/server/tls/service.current.key --service-cluster-ip-range=10.43.0.0/16 --use-service-account-credentials=true +``` + +### 1.3.5 Ensure that the --root-ca-file argument is set as appropriate (Automated) + + +**Result:** pass + +**Remediation:** +Edit the Controller Manager pod specification file /var/lib/rancher/rke2/agent/pod-manifests/kube-controller-manager.yaml +on the control plane node and set the --root-ca-file parameter to the certificate bundle file`. +--root-ca-file= + +**Audit:** + +```bash +/bin/ps -ef | grep kube-controller-manager | grep -v grep +``` + +**Expected Result**: + +```console +'--root-ca-file' is present +``` + +**Returned Value**: + +```console +root 2652 2539 2 Sep11 ? 00:24:53 kube-controller-manager --flex-volume-plugin-dir=/var/lib/kubelet/volumeplugins --terminated-pod-gc-threshold=1000 --permit-port-sharing=true --allocate-node-cidrs=true --authentication-kubeconfig=/var/lib/rancher/rke2/server/cred/controller.kubeconfig --authorization-kubeconfig=/var/lib/rancher/rke2/server/cred/controller.kubeconfig --bind-address=127.0.0.1 --cert-dir=/var/lib/rancher/rke2/server/tls/kube-controller-manager --cluster-cidr=10.42.0.0/16 --cluster-signing-kube-apiserver-client-cert-file=/var/lib/rancher/rke2/server/tls/client-ca.nochain.crt --cluster-signing-kube-apiserver-client-key-file=/var/lib/rancher/rke2/server/tls/client-ca.key --cluster-signing-kubelet-client-cert-file=/var/lib/rancher/rke2/server/tls/client-ca.nochain.crt --cluster-signing-kubelet-client-key-file=/var/lib/rancher/rke2/server/tls/client-ca.key --cluster-signing-kubelet-serving-cert-file=/var/lib/rancher/rke2/server/tls/server-ca.nochain.crt --cluster-signing-kubelet-serving-key-file=/var/lib/rancher/rke2/server/tls/server-ca.key --cluster-signing-legacy-unknown-cert-file=/var/lib/rancher/rke2/server/tls/server-ca.nochain.crt --cluster-signing-legacy-unknown-key-file=/var/lib/rancher/rke2/server/tls/server-ca.key --configure-cloud-routes=false --controllers=*,tokencleaner,-service,-route,-cloud-node-lifecycle --feature-gates=JobTrackingWithFinalizers=true --kubeconfig=/var/lib/rancher/rke2/server/cred/controller.kubeconfig --profiling=false --root-ca-file=/var/lib/rancher/rke2/server/tls/server-ca.crt --secure-port=10257 --service-account-private-key-file=/var/lib/rancher/rke2/server/tls/service.current.key --service-cluster-ip-range=10.43.0.0/16 --use-service-account-credentials=true +``` + +### 1.3.6 Ensure that the RotateKubeletServerCertificate argument is set to true (Automated) + + +**Result:** Not Applicable + +**Remediation:** +Edit the Controller Manager pod specification file /var/lib/rancher/rke2/agent/pod-manifests/kube-controller-manager.yaml +on the control plane node and set the --feature-gates parameter to include RotateKubeletServerCertificate=true. +--feature-gates=RotateKubeletServerCertificate=true + +### 1.3.7 Ensure that the --bind-address argument is set to 127.0.0.1 (Automated) + + +**Result:** pass + +**Remediation:** +Edit the Controller Manager pod specification file /var/lib/rancher/rke2/agent/pod-manifests/kube-controller-manager.yaml +on the control plane node and ensure the correct value for the --bind-address parameter + +**Audit:** + +```bash +/bin/ps -ef | grep kube-controller-manager | grep -v grep +``` + +**Expected Result**: + +```console +'--bind-address' is equal to '127.0.0.1' OR '--bind-address' is not present +``` + +**Returned Value**: + +```console +root 2652 2539 2 Sep11 ? 00:24:53 kube-controller-manager --flex-volume-plugin-dir=/var/lib/kubelet/volumeplugins --terminated-pod-gc-threshold=1000 --permit-port-sharing=true --allocate-node-cidrs=true --authentication-kubeconfig=/var/lib/rancher/rke2/server/cred/controller.kubeconfig --authorization-kubeconfig=/var/lib/rancher/rke2/server/cred/controller.kubeconfig --bind-address=127.0.0.1 --cert-dir=/var/lib/rancher/rke2/server/tls/kube-controller-manager --cluster-cidr=10.42.0.0/16 --cluster-signing-kube-apiserver-client-cert-file=/var/lib/rancher/rke2/server/tls/client-ca.nochain.crt --cluster-signing-kube-apiserver-client-key-file=/var/lib/rancher/rke2/server/tls/client-ca.key --cluster-signing-kubelet-client-cert-file=/var/lib/rancher/rke2/server/tls/client-ca.nochain.crt --cluster-signing-kubelet-client-key-file=/var/lib/rancher/rke2/server/tls/client-ca.key --cluster-signing-kubelet-serving-cert-file=/var/lib/rancher/rke2/server/tls/server-ca.nochain.crt --cluster-signing-kubelet-serving-key-file=/var/lib/rancher/rke2/server/tls/server-ca.key --cluster-signing-legacy-unknown-cert-file=/var/lib/rancher/rke2/server/tls/server-ca.nochain.crt --cluster-signing-legacy-unknown-key-file=/var/lib/rancher/rke2/server/tls/server-ca.key --configure-cloud-routes=false --controllers=*,tokencleaner,-service,-route,-cloud-node-lifecycle --feature-gates=JobTrackingWithFinalizers=true --kubeconfig=/var/lib/rancher/rke2/server/cred/controller.kubeconfig --profiling=false --root-ca-file=/var/lib/rancher/rke2/server/tls/server-ca.crt --secure-port=10257 --service-account-private-key-file=/var/lib/rancher/rke2/server/tls/service.current.key --service-cluster-ip-range=10.43.0.0/16 --use-service-account-credentials=true +``` + +## 1.4 Scheduler +### 1.4.1 Ensure that the --profiling argument is set to false (Automated) + + +**Result:** pass + +**Remediation:** +Edit the Scheduler pod specification file /var/lib/rancher/rke2/agent/pod-manifests/kube-scheduler.yaml file +on the control plane node and set the below parameter. +--profiling=false + +**Audit:** + +```bash +/bin/ps -ef | grep kube-scheduler | grep -v grep +``` + +**Expected Result**: + +```console +'--profiling' is equal to 'false' +``` + +**Returned Value**: + +```console +root 2645 2538 0 Sep11 ? 00:05:26 kube-scheduler --permit-port-sharing=true --authentication-kubeconfig=/var/lib/rancher/rke2/server/cred/scheduler.kubeconfig --authorization-kubeconfig=/var/lib/rancher/rke2/server/cred/scheduler.kubeconfig --bind-address=127.0.0.1 --cert-dir=/var/lib/rancher/rke2/server/tls/kube-scheduler --kubeconfig=/var/lib/rancher/rke2/server/cred/scheduler.kubeconfig --profiling=false --secure-port=10259 +``` + +### 1.4.2 Ensure that the --bind-address argument is set to 127.0.0.1 (Automated) + + +**Result:** pass + +**Remediation:** +Edit the Scheduler pod specification file /var/lib/rancher/rke2/agent/pod-manifests/kube-scheduler.yaml +on the control plane node and ensure the correct value for the --bind-address parameter + +**Audit:** + +```bash +/bin/ps -ef | grep kube-scheduler | grep -v grep +``` + +**Expected Result**: + +```console +'--bind-address' is equal to '127.0.0.1' OR '--bind-address' is not present +``` + +**Returned Value**: + +```console +root 2645 2538 0 Sep11 ? 00:05:26 kube-scheduler --permit-port-sharing=true --authentication-kubeconfig=/var/lib/rancher/rke2/server/cred/scheduler.kubeconfig --authorization-kubeconfig=/var/lib/rancher/rke2/server/cred/scheduler.kubeconfig --bind-address=127.0.0.1 --cert-dir=/var/lib/rancher/rke2/server/tls/kube-scheduler --kubeconfig=/var/lib/rancher/rke2/server/cred/scheduler.kubeconfig --profiling=false --secure-port=10259 +``` + +## 2 Etcd Node Configuration +### 2.1 Ensure that the --cert-file and --key-file arguments are set as appropriate (Automated) + + +**Result:** Not Applicable + +**Remediation:** +Follow the etcd service documentation and configure TLS encryption. +Then, edit the etcd pod specification file /etc/kubernetes/manifests/etcd.yaml +on the master node and set the below parameters. +--cert-file= +--key-file= +Not Applicable. + +### 2.2 Ensure that the --client-cert-auth argument is set to true (Automated) + + +**Result:** Not Applicable + +**Remediation:** +Edit the etcd pod specification file /var/lib/rancher/rke2/agent/pod-manifests/etcd.yaml on the master +node and set the below parameter. +--client-cert-auth="true" +Not Applicable. + +### 2.3 Ensure that the --auto-tls argument is not set to true (Automated) + + +**Result:** pass + +**Remediation:** +Edit the etcd pod specification file /var/lib/rancher/rke2/agent/pod-manifests/etcd.yaml on the master +node and either remove the --auto-tls parameter or set it to false. + --auto-tls=false + +**Audit:** + +```bash +/bin/ps -ef | /bin/grep etcd | /bin/grep -v grep +``` + +**Expected Result**: + +```console +'ETCD_AUTO_TLS' is not present OR 'ETCD_AUTO_TLS' is present +``` + +**Returned Value**: + +```console +PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin HOSTNAME=ip-172-31-14-226 ETCD_UNSUPPORTED_ARCH= FILE_HASH=e9ca6f328e70dd3c17ba78c302ee32927a4961198e95d1d948114a5d7e350d99 NO_PROXY=.svc,.cluster.local,10.42.0.0/16,10.43.0.0/16 POD_HASH=aa1658a59ab75324ef67c786d08307e3 HOME=/ +``` + +### 2.4 Ensure that the --peer-cert-file and --peer-key-file arguments are set as appropriate (Automated) + + +**Result:** Not Applicable + +**Remediation:** +Follow the etcd service documentation and configure peer TLS encryption as appropriate +for your etcd cluster. +Then, edit the etcd pod specification file /var/lib/rancher/rke2/agent/pod-manifests/etcd.yaml on the +master node and set the below parameters. +--peer-client-file= +--peer-key-file= +Not Applicable. + +### 2.5 Ensure that the --peer-client-cert-auth argument is set to true (Automated) + + +**Result:** Not Applicable + +**Remediation:** +Edit the etcd pod specification file /var/lib/rancher/rke2/agent/pod-manifests/etcd.yaml on the master +node and set the below parameter. +--peer-client-cert-auth=true +Not Applicable. + +### 2.6 Ensure that the --peer-auto-tls argument is not set to true (Automated) + + +**Result:** pass + +**Remediation:** +Edit the etcd pod specification file /var/lib/rancher/rke2/agent/pod-manifests/etcd.yaml on the master +node and either remove the --peer-auto-tls parameter or set it to false. +--peer-auto-tls=false + +**Audit:** + +```bash +/bin/ps -ef | /bin/grep etcd | /bin/grep -v grep +``` + +**Expected Result**: + +```console +'ETCD_PEER_AUTO_TLS' is not present OR 'ETCD_PEER_AUTO_TLS' is present +``` + +**Returned Value**: + +```console +PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin HOSTNAME=ip-172-31-14-226 ETCD_UNSUPPORTED_ARCH= FILE_HASH=e9ca6f328e70dd3c17ba78c302ee32927a4961198e95d1d948114a5d7e350d99 NO_PROXY=.svc,.cluster.local,10.42.0.0/16,10.43.0.0/16 POD_HASH=aa1658a59ab75324ef67c786d08307e3 HOME=/ +``` + +### 2.7 Ensure that a unique Certificate Authority is used for etcd (Automated) + + +**Result:** pass + +**Remediation:** +[Manual test] +Follow the etcd documentation and create a dedicated certificate authority setup for the +etcd service. +Then, edit the etcd pod specification file /var/lib/rancher/rke2/agent/pod-manifests/etcd.yaml on the +master node and set the below parameter. +--trusted-ca-file= + +**Audit:** + +```bash +/bin/ps -ef | /bin/grep etcd | /bin/grep -v grep +``` + +**Audit Config:** + +```bash +cat /var/lib/rancher/rke2/server/db/etcd/config +``` + +**Expected Result**: + +```console +'ETCD_TRUSTED_CA_FILE' is present OR '{.peer-transport-security.trusted-ca-file}' is equal to '/var/lib/rancher/rke2/server/tls/etcd/peer-ca.crt' +``` + +**Returned Value**: + +```console +PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin HOSTNAME=ip-172-31-14-226 ETCD_UNSUPPORTED_ARCH= FILE_HASH=e9ca6f328e70dd3c17ba78c302ee32927a4961198e95d1d948114a5d7e350d99 NO_PROXY=.svc,.cluster.local,10.42.0.0/16,10.43.0.0/16 POD_HASH=aa1658a59ab75324ef67c786d08307e3 HOME=/ +``` + +## 3.1 Authentication and Authorization +### 3.1.1 Client certificate authentication should not be used for users (Manual) + + +**Result:** warn + +**Remediation:** +Alternative mechanisms provided by Kubernetes such as the use of OIDC should be +implemented in place of client certificates. + +### 3.1.2 Service account token authentication should not be used for users (Manual) + + +**Result:** warn + +**Remediation:** +Alternative mechanisms provided by Kubernetes such as the use of OIDC should be implemented +in place of service account tokens. + +### 3.1.3 Bootstrap token authentication should not be used for users (Manual) + + +**Result:** warn + +**Remediation:** +Alternative mechanisms provided by Kubernetes such as the use of OIDC should be implemented +in place of bootstrap tokens. + +## 3.2 Logging +### 3.2.1 Ensure that a minimal audit policy is created (Automated) + + +**Result:** pass + +**Remediation:** +Create an audit policy file for your cluster. + +**Audit:** + +```bash +/bin/ps -ef | grep kube-apiserver | grep -v grep +``` + +**Expected Result**: + +```console +'--audit-policy-file' is present +``` + +**Returned Value**: + +```console +root 2489 2419 8 Sep11 ? 01:41:54 kube-apiserver --admission-control-config-file=/etc/rancher/rke2/rke2-pss.yaml --audit-policy-file=/etc/rancher/rke2/audit-policy.yaml --audit-log-maxage=30 --audit-log-maxbackup=10 --audit-log-maxsize=100 --audit-log-path=/var/lib/rancher/rke2/server/logs/audit.log --admission-control-config-file=/etc/rancher/rke2/config/rancher-psact.yaml --allow-privileged=true --anonymous-auth=false --api-audiences=https://kubernetes.default.svc.cluster.local,rke2 --authorization-mode=Node,RBAC --bind-address=0.0.0.0 --cert-dir=/var/lib/rancher/rke2/server/tls/temporary-certs --client-ca-file=/var/lib/rancher/rke2/server/tls/client-ca.crt --egress-selector-config-file=/var/lib/rancher/rke2/server/etc/egress-selector-config.yaml --enable-admission-plugins=NodeRestriction --enable-aggregator-routing=true --enable-bootstrap-token-auth=true --encryption-provider-config=/var/lib/rancher/rke2/server/cred/encryption-config.json --etcd-cafile=/var/lib/rancher/rke2/server/tls/etcd/server-ca.crt --etcd-certfile=/var/lib/rancher/rke2/server/tls/etcd/client.crt --etcd-keyfile=/var/lib/rancher/rke2/server/tls/etcd/client.key --etcd-servers=https://127.0.0.1:2379 --feature-gates=JobTrackingWithFinalizers=true --kubelet-certificate-authority=/var/lib/rancher/rke2/server/tls/server-ca.crt --kubelet-client-certificate=/var/lib/rancher/rke2/server/tls/client-kube-apiserver.crt --kubelet-client-key=/var/lib/rancher/rke2/server/tls/client-kube-apiserver.key --kubelet-preferred-address-types=InternalIP,ExternalIP,Hostname --profiling=false --proxy-client-cert-file=/var/lib/rancher/rke2/server/tls/client-auth-proxy.crt --proxy-client-key-file=/var/lib/rancher/rke2/server/tls/client-auth-proxy.key --requestheader-allowed-names=system:auth-proxy --requestheader-client-ca-file=/var/lib/rancher/rke2/server/tls/request-header-ca.crt --requestheader-extra-headers-prefix=X-Remote-Extra- --requestheader-group-headers=X-Remote-Group --requestheader-username-headers=X-Remote-User --secure-port=6443 --service-account-issuer=https://kubernetes.default.svc.cluster.local --service-account-key-file=/var/lib/rancher/rke2/server/tls/service.key --service-account-signing-key-file=/var/lib/rancher/rke2/server/tls/service.current.key --service-cluster-ip-range=10.43.0.0/16 --service-node-port-range=30000-32767 --storage-backend=etcd3 --tls-cert-file=/var/lib/rancher/rke2/server/tls/serving-kube-apiserver.crt --tls-cipher-suites=TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305,TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305 --tls-private-key-file=/var/lib/rancher/rke2/server/tls/serving-kube-apiserver.key root 2652 2539 2 Sep11 ? 00:24:53 kube-controller-manager --flex-volume-plugin-dir=/var/lib/kubelet/volumeplugins --terminated-pod-gc-threshold=1000 --permit-port-sharing=true --allocate-node-cidrs=true --authentication-kubeconfig=/var/lib/rancher/rke2/server/cred/controller.kubeconfig --authorization-kubeconfig=/var/lib/rancher/rke2/server/cred/controller.kubeconfig --bind-address=127.0.0.1 --cert-dir=/var/lib/rancher/rke2/server/tls/kube-controller-manager --cluster-cidr=10.42.0.0/16 --cluster-signing-kube-apiserver-client-cert-file=/var/lib/rancher/rke2/server/tls/client-ca.nochain.crt --cluster-signing-kube-apiserver-client-key-file=/var/lib/rancher/rke2/server/tls/client-ca.key --cluster-signing-kubelet-client-cert-file=/var/lib/rancher/rke2/server/tls/client-ca.nochain.crt --cluster-signing-kubelet-client-key-file=/var/lib/rancher/rke2/server/tls/client-ca.key --cluster-signing-kubelet-serving-cert-file=/var/lib/rancher/rke2/server/tls/server-ca.nochain.crt --cluster-signing-kubelet-serving-key-file=/var/lib/rancher/rke2/server/tls/server-ca.key --cluster-signing-legacy-unknown-cert-file=/var/lib/rancher/rke2/server/tls/server-ca.nochain.crt --cluster-signing-legacy-unknown-key-file=/var/lib/rancher/rke2/server/tls/server-ca.key --configure-cloud-routes=false --controllers=*,tokencleaner,-service,-route,-cloud-node-lifecycle --feature-gates=JobTrackingWithFinalizers=true --kubeconfig=/var/lib/rancher/rke2/server/cred/controller.kubeconfig --profiling=false --root-ca-file=/var/lib/rancher/rke2/server/tls/server-ca.crt --secure-port=10257 --service-account-private-key-file=/var/lib/rancher/rke2/server/tls/service.current.key --service-cluster-ip-range=10.43.0.0/16 --use-service-account-credentials=true +``` + +### 3.2.2 Ensure that the audit policy covers key security concerns (Manual) + + +**Result:** warn + +**Remediation:** +Review the audit policy provided for the cluster and ensure that it covers +at least the following areas, +- Access to Secrets managed by the cluster. Care should be taken to only + log Metadata for requests to Secrets, ConfigMaps, and TokenReviews, in + order to avoid risk of logging sensitive data. +- Modification of Pod and Deployment objects. +- Use of `pods/exec`, `pods/portforward`, `pods/proxy` and `services/proxy`. +For most requests, minimally logging at the Metadata level is recommended +(the most basic level of logging). + +## 4.1 Worker Node Configuration Files +### 4.1.1 Ensure that the kubelet service file permissions are set to 600 or more restrictive (Automated) + + +**Result:** Not Applicable + +**Remediation:** +Run the below command (based on the file location on your system) on the each worker node. +For example, chmod 600 /etc/systemd/system/kubelet.service.d/10-kubeadm.conf +Not Applicable. + +### 4.1.2 Ensure that the kubelet service file ownership is set to root:root (Automated) + + +**Result:** Not Applicable + +**Remediation:** +Run the below command (based on the file location on your system) on the each worker node. +For example, +chown root:root /etc/systemd/system/kubelet.service.d/10-kubeadm.conf +Not applicable. + +### 4.1.3 If proxy kubeconfig file exists ensure permissions are set to 600 or more restrictive (Manual) + + +**Result:** warn + +**Remediation:** +Run the below command (based on the file location on your system) on the each worker node. +For example, +chmod 600 /var/lib/rancher/rke2/agent/kubeproxy.kubeconfig + +**Audit:** + +```bash +/bin/sh -c 'if test -e /var/lib/rancher/rke2/agent/kubeproxy.kubeconfig; then stat -c permissions=%a /var/lib/rancher/rke2/agent/kubeproxy.kubeconfig; fi' +``` + +**Expected Result**: + +```console +permissions has permissions 644, expected 600 or more restrictive +``` + +**Returned Value**: + +```console +permissions=644 +``` + +### 4.1.4 If proxy kubeconfig file exists ensure ownership is set to root:root (Manual) + + +**Result:** pass + +**Remediation:** +Run the below command (based on the file location on your system) on the each worker node. +For example, chown root:root /var/lib/rancher/rke2/agent/kubeproxy.kubeconfig + +**Audit:** + +```bash +/bin/sh -c 'if test -e /var/lib/rancher/rke2/agent/kubeproxy.kubeconfig; then stat -c %U:%G /var/lib/rancher/rke2/agent/kubeproxy.kubeconfig; fi' +``` + +**Expected Result**: + +```console +'root:root' is present +``` + +**Returned Value**: + +```console +root:root +``` + +### 4.1.5 Ensure that the --kubeconfig kubelet.conf file permissions are set to 600 or more restrictive (Automated) + + +**Result:** fail + +**Remediation:** +Run the below command (based on the file location on your system) on the each worker node. +For example, +chmod 600 /var/lib/rancher/rke2/agent/kubelet.kubeconfig + +**Audit:** + +```bash +/bin/sh -c 'if test -e /var/lib/rancher/rke2/agent/kubelet.kubeconfig; then stat -c permissions=%a /var/lib/rancher/rke2/agent/kubelet.kubeconfig; fi' +``` + +**Expected Result**: + +```console +permissions has permissions 644, expected 600 or more restrictive +``` + +**Returned Value**: + +```console +permissions=644 +``` + +### 4.1.6 Ensure that the --kubeconfig kubelet.conf file ownership is set to root:root (Automated) + + +**Result:** pass + +**Remediation:** +Run the below command (based on the file location on your system) on the each worker node. +For example, +chown root:root /var/lib/rancher/rke2/agent/kubelet.kubeconfig + +**Audit:** + +```bash +/bin/sh -c 'if test -e /var/lib/rancher/rke2/agent/kubelet.kubeconfig; then stat -c %U:%G /var/lib/rancher/rke2/agent/kubelet.kubeconfig; fi' +``` + +**Expected Result**: + +```console +'root:root' is equal to 'root:root' +``` + +**Returned Value**: + +```console +root:root +``` + +### 4.1.7 Ensure that the certificate authorities file permissions are set to 600 or more restrictive (Manual) + + +**Result:** pass + +**Remediation:** +Run the following command to modify the file permissions of the +--client-ca-file chmod 600 + +**Audit Script:** `check_cafile_permissions.sh` + +```bash +#!/usr/bin/env bash + +CAFILE=$(ps -ef | grep kubelet | grep -v apiserver | grep -- --client-ca-file= | awk -F '--client-ca-file=' '{print $2}' | awk '{print $1}') +CAFILE=/node$CAFILE +if test -z $CAFILE; then CAFILE=$kubeletcafile; fi +if test -e $CAFILE; then stat -c permissions=%a $CAFILE; fi + +``` + +**Audit Execution:** + +```bash +./check_cafile_permissions.sh +``` + +**Expected Result**: + +```console +permissions has permissions 600, expected 600 or more restrictive +``` + +**Returned Value**: + +```console +permissions=600 +``` + +### 4.1.8 Ensure that the client certificate authorities file ownership is set to root:root (Manual) + + +**Result:** pass + +**Remediation:** +Run the following command to modify the ownership of the --client-ca-file. +chown root:root + +**Audit Script:** `check_cafile_ownership.sh` + +```bash +#!/usr/bin/env bash + +CAFILE=$(ps -ef | grep kubelet | grep -v apiserver | grep -- --client-ca-file= | awk -F '--client-ca-file=' '{print $2}' | awk '{print $1}') +CAFILE=/node$CAFILE +if test -z $CAFILE; then CAFILE=$kubeletcafile; fi +if test -e $CAFILE; then stat -c %U:%G $CAFILE; fi + +``` + +**Audit Execution:** + +```bash +./check_cafile_ownership.sh +``` + +**Expected Result**: + +```console +'root:root' is equal to 'root:root' +``` + +**Returned Value**: + +```console +root:root +``` + +### 4.1.9 If the kubelet config.yaml configuration file is being used validate permissions set to 600 or more restrictive (Automated) + + +**Result:** fail + +**Remediation:** +Run the following command (using the config file location identified in the Audit step) +chmod 600 /var/lib/rancher/rke2/agent/kubelet.kubeconfig + +**Audit:** + +```bash +/bin/sh -c 'if test -e /var/lib/rancher/rke2/agent/kubelet.kubeconfig; then stat -c permissions=%a /var/lib/rancher/rke2/agent/kubelet.kubeconfig; fi' +``` + +**Expected Result**: + +```console +permissions has permissions 644, expected 600 or more restrictive +``` + +**Returned Value**: + +```console +permissions=644 +``` + +### 4.1.10 If the kubelet config.yaml configuration file is being used validate file ownership is set to root:root (Automated) + + +**Result:** pass + +**Remediation:** +Run the following command (using the config file location identified in the Audit step) +chown root:root /var/lib/rancher/rke2/agent/kubelet.kubeconfig + +**Audit:** + +```bash +/bin/sh -c 'if test -e /var/lib/rancher/rke2/agent/kubelet.kubeconfig; then stat -c %U:%G /var/lib/rancher/rke2/agent/kubelet.kubeconfig; fi' +``` + +**Expected Result**: + +```console +'root:root' is present +``` + +**Returned Value**: + +```console +root:root +``` + +## 4.2 Kubelet +### 4.2.1 Ensure that the --anonymous-auth argument is set to false (Automated) + + +**Result:** pass + +**Remediation:** +If using a Kubelet config file, edit the file to set `authentication: anonymous: enabled` to +`false`. +If using executable arguments, edit the kubelet service file +/etc/systemd/system/kubelet.service.d/10-kubeadm.conf on each worker node and +set the below parameter in KUBELET_SYSTEM_PODS_ARGS variable. +`--anonymous-auth=false` +Based on your system, restart the kubelet service. For example, +systemctl daemon-reload +systemctl restart kubelet.service + +**Audit:** + +```bash +/bin/ps -fC kubelet +``` + +**Audit Config:** + +```bash +/bin/cat /var/lib/rancher/rke2/agent/kubelet.kubeconfig +``` + +**Expected Result**: + +```console +'--anonymous-auth' is equal to 'false' +``` + +**Returned Value**: + +```console +UID PID PPID C STIME TTY TIME CMD root 2236 2075 4 Sep11 ? 00:47:51 kubelet --volume-plugin-dir=/var/lib/kubelet/volumeplugins --file-check-frequency=5s --sync-frequency=30s --address=0.0.0.0 --alsologtostderr=false --anonymous-auth=false --authentication-token-webhook=true --authorization-mode=Webhook --cgroup-driver=systemd --client-ca-file=/var/lib/rancher/rke2/agent/client-ca.crt --cloud-provider=external --cluster-dns=10.43.0.10 --cluster-domain=cluster.local --container-runtime-endpoint=unix:///run/k3s/containerd/containerd.sock --containerd=/run/k3s/containerd/containerd.sock --eviction-hard=imagefs.available<5%,nodefs.available<5% --eviction-minimum-reclaim=imagefs.available=10%,nodefs.available=10% --fail-swap-on=false --healthz-bind-address=127.0.0.1 --hostname-override=ip-172-31-14-226 --kubeconfig=/var/lib/rancher/rke2/agent/kubelet.kubeconfig --log-file=/var/lib/rancher/rke2/agent/logs/kubelet.log --log-file-max-size=50 --logtostderr=false --node-labels=cattle.io/os=linux,rke.cattle.io/machine=1adcc1f7-66f1-4503-b9bc-dfb6e808f27b --pod-infra-container-image=index.docker.io/rancher/pause:3.6 --pod-manifest-path=/var/lib/rancher/rke2/agent/pod-manifests --protect-kernel-defaults=true --read-only-port=0 --resolv-conf=/run/systemd/resolve/resolv.conf --serialize-image-pulls=false --stderrthreshold=FATAL --tls-cert-file=/var/lib/rancher/rke2/agent/serving-kubelet.crt --tls-private-key-file=/var/lib/rancher/rke2/agent/serving-kubelet.key +``` + +### 4.2.2 Ensure that the --authorization-mode argument is not set to AlwaysAllow (Automated) + + +**Result:** pass + +**Remediation:** +If using a Kubelet config file, edit the file to set `authorization.mode` to Webhook. If +using executable arguments, edit the kubelet service file +/etc/systemd/system/kubelet.service.d/10-kubeadm.conf on each worker node and +set the below parameter in KUBELET_AUTHZ_ARGS variable. +--authorization-mode=Webhook +Based on your system, restart the kubelet service. For example, +systemctl daemon-reload +systemctl restart kubelet.service + +**Audit:** + +```bash +/bin/ps -fC kubelet +``` + +**Audit Config:** + +```bash +/bin/cat /var/lib/rancher/rke2/agent/kubelet.kubeconfig +``` + +**Expected Result**: + +```console +'--authorization-mode' does not have 'AlwaysAllow' +``` + +**Returned Value**: + +```console +UID PID PPID C STIME TTY TIME CMD root 2236 2075 4 Sep11 ? 00:47:51 kubelet --volume-plugin-dir=/var/lib/kubelet/volumeplugins --file-check-frequency=5s --sync-frequency=30s --address=0.0.0.0 --alsologtostderr=false --anonymous-auth=false --authentication-token-webhook=true --authorization-mode=Webhook --cgroup-driver=systemd --client-ca-file=/var/lib/rancher/rke2/agent/client-ca.crt --cloud-provider=external --cluster-dns=10.43.0.10 --cluster-domain=cluster.local --container-runtime-endpoint=unix:///run/k3s/containerd/containerd.sock --containerd=/run/k3s/containerd/containerd.sock --eviction-hard=imagefs.available<5%,nodefs.available<5% --eviction-minimum-reclaim=imagefs.available=10%,nodefs.available=10% --fail-swap-on=false --healthz-bind-address=127.0.0.1 --hostname-override=ip-172-31-14-226 --kubeconfig=/var/lib/rancher/rke2/agent/kubelet.kubeconfig --log-file=/var/lib/rancher/rke2/agent/logs/kubelet.log --log-file-max-size=50 --logtostderr=false --node-labels=cattle.io/os=linux,rke.cattle.io/machine=1adcc1f7-66f1-4503-b9bc-dfb6e808f27b --pod-infra-container-image=index.docker.io/rancher/pause:3.6 --pod-manifest-path=/var/lib/rancher/rke2/agent/pod-manifests --protect-kernel-defaults=true --read-only-port=0 --resolv-conf=/run/systemd/resolve/resolv.conf --serialize-image-pulls=false --stderrthreshold=FATAL --tls-cert-file=/var/lib/rancher/rke2/agent/serving-kubelet.crt --tls-private-key-file=/var/lib/rancher/rke2/agent/serving-kubelet.key +``` + +### 4.2.3 Ensure that the --client-ca-file argument is set as appropriate (Automated) + + +**Result:** pass + +**Remediation:** +If using a Kubelet config file, edit the file to set `authentication.x509.clientCAFile` to +the location of the client CA file. +If using command line arguments, edit the kubelet service file +/etc/systemd/system/kubelet.service.d/10-kubeadm.conf on each worker node and +set the below parameter in KUBELET_AUTHZ_ARGS variable. +--client-ca-file= +Based on your system, restart the kubelet service. For example, +systemctl daemon-reload +systemctl restart kubelet.service + +**Audit:** + +```bash +/bin/ps -fC kubelet +``` + +**Audit Config:** + +```bash +/bin/cat /var/lib/rancher/rke2/agent/kubelet.kubeconfig +``` + +**Expected Result**: + +```console +'--client-ca-file' is present +``` + +**Returned Value**: + +```console +UID PID PPID C STIME TTY TIME CMD root 2236 2075 4 Sep11 ? 00:47:51 kubelet --volume-plugin-dir=/var/lib/kubelet/volumeplugins --file-check-frequency=5s --sync-frequency=30s --address=0.0.0.0 --alsologtostderr=false --anonymous-auth=false --authentication-token-webhook=true --authorization-mode=Webhook --cgroup-driver=systemd --client-ca-file=/var/lib/rancher/rke2/agent/client-ca.crt --cloud-provider=external --cluster-dns=10.43.0.10 --cluster-domain=cluster.local --container-runtime-endpoint=unix:///run/k3s/containerd/containerd.sock --containerd=/run/k3s/containerd/containerd.sock --eviction-hard=imagefs.available<5%,nodefs.available<5% --eviction-minimum-reclaim=imagefs.available=10%,nodefs.available=10% --fail-swap-on=false --healthz-bind-address=127.0.0.1 --hostname-override=ip-172-31-14-226 --kubeconfig=/var/lib/rancher/rke2/agent/kubelet.kubeconfig --log-file=/var/lib/rancher/rke2/agent/logs/kubelet.log --log-file-max-size=50 --logtostderr=false --node-labels=cattle.io/os=linux,rke.cattle.io/machine=1adcc1f7-66f1-4503-b9bc-dfb6e808f27b --pod-infra-container-image=index.docker.io/rancher/pause:3.6 --pod-manifest-path=/var/lib/rancher/rke2/agent/pod-manifests --protect-kernel-defaults=true --read-only-port=0 --resolv-conf=/run/systemd/resolve/resolv.conf --serialize-image-pulls=false --stderrthreshold=FATAL --tls-cert-file=/var/lib/rancher/rke2/agent/serving-kubelet.crt --tls-private-key-file=/var/lib/rancher/rke2/agent/serving-kubelet.key +``` + +### 4.2.4 Verify that the --read-only-port argument is set to 0 (Manual) + + +**Result:** pass + +**Remediation:** +If using a Kubelet config file, edit the file to set `readOnlyPort` to 0. +If using command line arguments, edit the kubelet service file +/etc/systemd/system/kubelet.service.d/10-kubeadm.conf on each worker node and +set the below parameter in KUBELET_SYSTEM_PODS_ARGS variable. +--read-only-port=0 +Based on your system, restart the kubelet service. For example, +systemctl daemon-reload +systemctl restart kubelet.service + +**Audit:** + +```bash +/bin/ps -fC kubelet +``` + +**Audit Config:** + +```bash +/bin/cat /var/lib/rancher/rke2/agent/kubelet.kubeconfig +``` + +**Expected Result**: + +```console +'--read-only-port' is equal to '0' OR '--read-only-port' is not present +``` + +**Returned Value**: + +```console +UID PID PPID C STIME TTY TIME CMD root 2236 2075 4 Sep11 ? 00:47:51 kubelet --volume-plugin-dir=/var/lib/kubelet/volumeplugins --file-check-frequency=5s --sync-frequency=30s --address=0.0.0.0 --alsologtostderr=false --anonymous-auth=false --authentication-token-webhook=true --authorization-mode=Webhook --cgroup-driver=systemd --client-ca-file=/var/lib/rancher/rke2/agent/client-ca.crt --cloud-provider=external --cluster-dns=10.43.0.10 --cluster-domain=cluster.local --container-runtime-endpoint=unix:///run/k3s/containerd/containerd.sock --containerd=/run/k3s/containerd/containerd.sock --eviction-hard=imagefs.available<5%,nodefs.available<5% --eviction-minimum-reclaim=imagefs.available=10%,nodefs.available=10% --fail-swap-on=false --healthz-bind-address=127.0.0.1 --hostname-override=ip-172-31-14-226 --kubeconfig=/var/lib/rancher/rke2/agent/kubelet.kubeconfig --log-file=/var/lib/rancher/rke2/agent/logs/kubelet.log --log-file-max-size=50 --logtostderr=false --node-labels=cattle.io/os=linux,rke.cattle.io/machine=1adcc1f7-66f1-4503-b9bc-dfb6e808f27b --pod-infra-container-image=index.docker.io/rancher/pause:3.6 --pod-manifest-path=/var/lib/rancher/rke2/agent/pod-manifests --protect-kernel-defaults=true --read-only-port=0 --resolv-conf=/run/systemd/resolve/resolv.conf --serialize-image-pulls=false --stderrthreshold=FATAL --tls-cert-file=/var/lib/rancher/rke2/agent/serving-kubelet.crt --tls-private-key-file=/var/lib/rancher/rke2/agent/serving-kubelet.key +``` + +### 4.2.5 Ensure that the --streaming-connection-idle-timeout argument is not set to 0 (Manual) + + +**Result:** pass + +**Remediation:** +If using a Kubelet config file, edit the file to set `streamingConnectionIdleTimeout` to a +value other than 0. +If using command line arguments, edit the kubelet service file +/etc/systemd/system/kubelet.service.d/10-kubeadm.conf on each worker node and +set the below parameter in KUBELET_SYSTEM_PODS_ARGS variable. +--streaming-connection-idle-timeout=5m +Based on your system, restart the kubelet service. For example, +systemctl daemon-reload +systemctl restart kubelet.service + +**Audit:** + +```bash +/bin/ps -fC kubelet +``` + +**Audit Config:** + +```bash +/bin/cat /var/lib/rancher/rke2/agent/kubelet.kubeconfig +``` + +**Expected Result**: + +```console +'{.streamingConnectionIdleTimeout}' is present OR '{.streamingConnectionIdleTimeout}' is not present +``` + +**Returned Value**: + +```console +apiVersion: v1 clusters: - cluster: server: https://127.0.0.1:6443 certificate-authority: /var/lib/rancher/rke2/agent/server-ca.crt name: local contexts: - context: cluster: local namespace: default user: user name: Default current-context: Default kind: Config preferences: {} users: - name: user user: client-certificate: /var/lib/rancher/rke2/agent/client-kubelet.crt client-key: /var/lib/rancher/rke2/agent/client-kubelet.key +``` + +### 4.2.6 Ensure that the --make-iptables-util-chains argument is set to true (Automated) + + +**Result:** pass + +**Remediation:** +If using a Kubelet config file, edit the file to set `makeIPTablesUtilChains` to `true`. +If using command line arguments, edit the kubelet service file +/etc/systemd/system/kubelet.service.d/10-kubeadm.conf on each worker node and +remove the --make-iptables-util-chains argument from the +KUBELET_SYSTEM_PODS_ARGS variable. +Based on your system, restart the kubelet service. For example: +systemctl daemon-reload +systemctl restart kubelet.service + +**Audit:** + +```bash +/bin/ps -fC kubelet +``` + +**Audit Config:** + +```bash +/bin/cat /var/lib/rancher/rke2/agent/kubelet.kubeconfig +``` + +**Expected Result**: + +```console +'{.makeIPTablesUtilChains}' is present OR '{.makeIPTablesUtilChains}' is not present +``` + +**Returned Value**: + +```console +apiVersion: v1 clusters: - cluster: server: https://127.0.0.1:6443 certificate-authority: /var/lib/rancher/rke2/agent/server-ca.crt name: local contexts: - context: cluster: local namespace: default user: user name: Default current-context: Default kind: Config preferences: {} users: - name: user user: client-certificate: /var/lib/rancher/rke2/agent/client-kubelet.crt client-key: /var/lib/rancher/rke2/agent/client-kubelet.key +``` + +### 4.2.7 Ensure that the --hostname-override argument is not set (Manual) + + +**Result:** Not Applicable + +**Remediation:** +Edit the kubelet service file /etc/systemd/system/kubelet.service.d/10-kubeadm.conf +on each worker node and remove the --hostname-override argument from the +KUBELET_SYSTEM_PODS_ARGS variable. +Based on your system, restart the kubelet service. For example, +systemctl daemon-reload +systemctl restart kubelet.service +Not Applicable. + +### 4.2.8 Ensure that the eventRecordQPS argument is set to a level which ensures appropriate event capture (Manual) + + +**Result:** pass + +**Remediation:** +If using a Kubelet config file, edit the file to set `eventRecordQPS` to an appropriate level. +If using command line arguments, edit the kubelet service file +/etc/systemd/system/kubelet.service.d/10-kubeadm.conf on each worker node and +set the below parameter in KUBELET_SYSTEM_PODS_ARGS variable. +Based on your system, restart the kubelet service. For example, +systemctl daemon-reload +systemctl restart kubelet.service + +**Audit:** + +```bash +/bin/ps -fC kubelet +``` + +**Audit Config:** + +```bash +/bin/cat /var/lib/rancher/rke2/agent/kubelet.kubeconfig +``` + +**Expected Result**: + +```console +'{.eventRecordQPS}' is present OR '{.eventRecordQPS}' is not present +``` + +**Returned Value**: + +```console +apiVersion: v1 clusters: - cluster: server: https://127.0.0.1:6443 certificate-authority: /var/lib/rancher/rke2/agent/server-ca.crt name: local contexts: - context: cluster: local namespace: default user: user name: Default current-context: Default kind: Config preferences: {} users: - name: user user: client-certificate: /var/lib/rancher/rke2/agent/client-kubelet.crt client-key: /var/lib/rancher/rke2/agent/client-kubelet.key +``` + +### 4.2.9 Ensure that the --tls-cert-file and --tls-private-key-file arguments are set as appropriate (Manual) + + +**Result:** pass + +**Remediation:** +If using a Kubelet config file, edit the file to set `tlsCertFile` to the location +of the certificate file to use to identify this Kubelet, and `tlsPrivateKeyFile` +to the location of the corresponding private key file. +If using command line arguments, edit the kubelet service file +/etc/systemd/system/kubelet.service.d/10-kubeadm.conf on each worker node and +set the below parameters in KUBELET_CERTIFICATE_ARGS variable. +--tls-cert-file= +--tls-private-key-file= +Based on your system, restart the kubelet service. For example, +systemctl daemon-reload +systemctl restart kubelet.service + +**Audit:** + +```bash +/bin/ps -fC kubelet +``` + +**Audit Config:** + +```bash +/bin/cat /var/lib/rancher/rke2/agent/kubelet.kubeconfig +``` + +**Expected Result**: + +```console +'--tls-cert-file' is present AND '--tls-private-key-file' is present +``` + +**Returned Value**: + +```console +UID PID PPID C STIME TTY TIME CMD root 2236 2075 4 Sep11 ? 00:47:51 kubelet --volume-plugin-dir=/var/lib/kubelet/volumeplugins --file-check-frequency=5s --sync-frequency=30s --address=0.0.0.0 --alsologtostderr=false --anonymous-auth=false --authentication-token-webhook=true --authorization-mode=Webhook --cgroup-driver=systemd --client-ca-file=/var/lib/rancher/rke2/agent/client-ca.crt --cloud-provider=external --cluster-dns=10.43.0.10 --cluster-domain=cluster.local --container-runtime-endpoint=unix:///run/k3s/containerd/containerd.sock --containerd=/run/k3s/containerd/containerd.sock --eviction-hard=imagefs.available<5%,nodefs.available<5% --eviction-minimum-reclaim=imagefs.available=10%,nodefs.available=10% --fail-swap-on=false --healthz-bind-address=127.0.0.1 --hostname-override=ip-172-31-14-226 --kubeconfig=/var/lib/rancher/rke2/agent/kubelet.kubeconfig --log-file=/var/lib/rancher/rke2/agent/logs/kubelet.log --log-file-max-size=50 --logtostderr=false --node-labels=cattle.io/os=linux,rke.cattle.io/machine=1adcc1f7-66f1-4503-b9bc-dfb6e808f27b --pod-infra-container-image=index.docker.io/rancher/pause:3.6 --pod-manifest-path=/var/lib/rancher/rke2/agent/pod-manifests --protect-kernel-defaults=true --read-only-port=0 --resolv-conf=/run/systemd/resolve/resolv.conf --serialize-image-pulls=false --stderrthreshold=FATAL --tls-cert-file=/var/lib/rancher/rke2/agent/serving-kubelet.crt --tls-private-key-file=/var/lib/rancher/rke2/agent/serving-kubelet.key +``` + +### 4.2.10 Ensure that the --rotate-certificates argument is not set to false (Automated) + + +**Result:** pass + +**Remediation:** +If using a Kubelet config file, edit the file to add the line `rotateCertificates` to `true` or +remove it altogether to use the default value. +If using command line arguments, edit the kubelet service file +/etc/systemd/system/kubelet.service.d/10-kubeadm.conf on each worker node and +remove --rotate-certificates=false argument from the KUBELET_CERTIFICATE_ARGS +variable. +Based on your system, restart the kubelet service. For example, +systemctl daemon-reload +systemctl restart kubelet.service + +**Audit:** + +```bash +/bin/ps -fC kubelet +``` + +**Audit Config:** + +```bash +/bin/cat /var/lib/rancher/rke2/agent/kubelet.kubeconfig +``` + +**Expected Result**: + +```console +'{.rotateCertificates}' is present OR '{.rotateCertificates}' is not present +``` + +**Returned Value**: + +```console +apiVersion: v1 clusters: - cluster: server: https://127.0.0.1:6443 certificate-authority: /var/lib/rancher/rke2/agent/server-ca.crt name: local contexts: - context: cluster: local namespace: default user: user name: Default current-context: Default kind: Config preferences: {} users: - name: user user: client-certificate: /var/lib/rancher/rke2/agent/client-kubelet.crt client-key: /var/lib/rancher/rke2/agent/client-kubelet.key +``` + +### 4.2.11 Verify that the RotateKubeletServerCertificate argument is set to true (Manual) + + +**Result:** pass + +**Remediation:** +Edit the kubelet service file /etc/systemd/system/kubelet.service.d/10-kubeadm.conf +on each worker node and set the below parameter in KUBELET_CERTIFICATE_ARGS variable. +--feature-gates=RotateKubeletServerCertificate=true +Based on your system, restart the kubelet service. For example: +systemctl daemon-reload +systemctl restart kubelet.service + +**Audit:** + +```bash +/bin/ps -fC kubelet +``` + +**Audit Config:** + +```bash +/bin/cat /var/lib/rancher/rke2/agent/kubelet.kubeconfig +``` + +**Expected Result**: + +```console +'{.featureGates.RotateKubeletServerCertificate}' is present OR '{.featureGates.RotateKubeletServerCertificate}' is not present +``` + +**Returned Value**: + +```console +apiVersion: v1 clusters: - cluster: server: https://127.0.0.1:6443 certificate-authority: /var/lib/rancher/rke2/agent/server-ca.crt name: local contexts: - context: cluster: local namespace: default user: user name: Default current-context: Default kind: Config preferences: {} users: - name: user user: client-certificate: /var/lib/rancher/rke2/agent/client-kubelet.crt client-key: /var/lib/rancher/rke2/agent/client-kubelet.key +``` + +### 4.2.12 Ensure that the Kubelet only makes use of Strong Cryptographic Ciphers (Manual) + + +**Result:** warn + +**Remediation:** +If using a Kubelet config file, edit the file to set `TLSCipherSuites` to +TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305,TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,TLS_RSA_WITH_AES_256_GCM_SHA384,TLS_RSA_WITH_AES_128_GCM_SHA256 +or to a subset of these values. +If using executable arguments, edit the kubelet service file +/etc/systemd/system/kubelet.service.d/10-kubeadm.conf on each worker node and +set the --tls-cipher-suites parameter as follows, or to a subset of these values. +--tls-cipher-suites=TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305,TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,TLS_RSA_WITH_AES_256_GCM_SHA384,TLS_RSA_WITH_AES_128_GCM_SHA256 +Based on your system, restart the kubelet service. For example: +systemctl daemon-reload +systemctl restart kubelet.service + +**Audit:** + +```bash +/bin/ps -fC kubelet +``` + +**Audit Config:** + +```bash +/bin/cat /var/lib/rancher/rke2/agent/kubelet.kubeconfig +``` + +**Expected Result**: + +```console +'{range .tlsCipherSuites[:]}{}{','}{end}' is present +``` + +**Returned Value**: + +```console +apiVersion: v1 clusters: - cluster: server: https://127.0.0.1:6443 certificate-authority: /var/lib/rancher/rke2/agent/server-ca.crt name: local contexts: - context: cluster: local namespace: default user: user name: Default current-context: Default kind: Config preferences: {} users: - name: user user: client-certificate: /var/lib/rancher/rke2/agent/client-kubelet.crt client-key: /var/lib/rancher/rke2/agent/client-kubelet.key +``` + +### 4.2.13 Ensure that a limit is set on pod PIDs (Manual) + + +**Result:** warn + +**Remediation:** +Decide on an appropriate level for this parameter and set it, +either via the --pod-max-pids command line parameter or the PodPidsLimit configuration file setting. + +**Audit:** + +```bash +/bin/ps -fC kubelet +``` + +**Audit Config:** + +```bash +/bin/cat /var/lib/rancher/rke2/agent/kubelet.kubeconfig +``` + +**Expected Result**: + +```console +'{.podPidsLimit}' is present +``` + +**Returned Value**: + +```console +apiVersion: v1 clusters: - cluster: server: https://127.0.0.1:6443 certificate-authority: /var/lib/rancher/rke2/agent/server-ca.crt name: local contexts: - context: cluster: local namespace: default user: user name: Default current-context: Default kind: Config preferences: {} users: - name: user user: client-certificate: /var/lib/rancher/rke2/agent/client-kubelet.crt client-key: /var/lib/rancher/rke2/agent/client-kubelet.key +``` + +## 5.1 RBAC and Service Accounts +### 5.1.1 Ensure that the cluster-admin role is only used where required (Manual) + + +**Result:** warn + +**Remediation:** +Identify all clusterrolebindings to the cluster-admin role. Check if they are used and +if they need this role or if they could use a role with fewer privileges. +Where possible, first bind users to a lower privileged role and then remove the +clusterrolebinding to the cluster-admin role : +kubectl delete clusterrolebinding [name] + +### 5.1.2 Minimize access to secrets (Manual) + + +**Result:** warn + +**Remediation:** +Where possible, remove get, list and watch access to Secret objects in the cluster. + +### 5.1.3 Minimize wildcard use in Roles and ClusterRoles (Manual) + + +**Result:** warn + +**Remediation:** +Where possible replace any use of wildcards in clusterroles and roles with specific +objects or actions. + +### 5.1.4 Minimize access to create pods (Manual) + + +**Result:** warn + +**Remediation:** +Where possible, remove create access to pod objects in the cluster. + +### 5.1.5 Ensure that default service accounts are not actively used. (Manual) + + +**Result:** warn + +**Remediation:** +Create explicit service accounts wherever a Kubernetes workload requires specific access +to the Kubernetes API server. +Modify the configuration of each default service account to include this value +automountServiceAccountToken: false + +### 5.1.6 Ensure that Service Account Tokens are only mounted where necessary (Manual) + + +**Result:** warn + +**Remediation:** +Modify the definition of pods and service accounts which do not need to mount service +account tokens to disable it. + +### 5.1.7 Avoid use of system:masters group (Manual) + + +**Result:** warn + +**Remediation:** +Remove the system:masters group from all users in the cluster. + +### 5.1.8 Limit use of the Bind, Impersonate and Escalate permissions in the Kubernetes cluster (Manual) + + +**Result:** warn + +**Remediation:** +Where possible, remove the impersonate, bind and escalate rights from subjects. + +### 5.1.9 Minimize access to create persistent volumes (Manual) + + +**Result:** warn + +**Remediation:** +Where possible, remove create access to PersistentVolume objects in the cluster. + +### 5.1.10 Minimize access to the proxy sub-resource of nodes (Manual) + + +**Result:** warn + +**Remediation:** +Where possible, remove access to the proxy sub-resource of node objects. + +### 5.1.11 Minimize access to the approval sub-resource of certificatesigningrequests objects (Manual) + + +**Result:** warn + +**Remediation:** +Where possible, remove access to the approval sub-resource of certificatesigningrequest objects. + +### 5.1.12 Minimize access to webhook configuration objects (Manual) + + +**Result:** warn + +**Remediation:** +Where possible, remove access to the validatingwebhookconfigurations or mutatingwebhookconfigurations objects + +### 5.1.13 Minimize access to the service account token creation (Manual) + + +**Result:** warn + +**Remediation:** +Where possible, remove access to the token sub-resource of serviceaccount objects. + +## 5.2 Pod Security Standards +### 5.2.1 Ensure that the cluster has at least one active policy control mechanism in place (Manual) + + +**Result:** warn + +**Remediation:** +Ensure that either Pod Security Admission or an external policy control system is in place +for every namespace which contains user workloads. + +### 5.2.2 Minimize the admission of privileged containers (Manual) + + +**Result:** warn + +**Remediation:** +Add policies to each namespace in the cluster which has user workloads to restrict the +admission of privileged containers. + +### 5.2.3 Minimize the admission of containers wishing to share the host process ID namespace (Manual) + + +**Result:** warn + +**Remediation:** +Add policies to each namespace in the cluster which has user workloads to restrict the +admission of `hostPID` containers. + +### 5.2.4 Minimize the admission of containers wishing to share the host IPC namespace (Manual) + + +**Result:** warn + +**Remediation:** +Add policies to each namespace in the cluster which has user workloads to restrict the +admission of `hostIPC` containers. + +### 5.2.5 Minimize the admission of containers wishing to share the host network namespace (Manual) + + +**Result:** warn + +**Remediation:** +Add policies to each namespace in the cluster which has user workloads to restrict the +admission of `hostNetwork` containers. + +### 5.2.6 Minimize the admission of containers with allowPrivilegeEscalation (Manual) + + +**Result:** warn + +**Remediation:** +Add policies to each namespace in the cluster which has user workloads to restrict the +admission of containers with `.spec.allowPrivilegeEscalation` set to `true`. + +### 5.2.7 Minimize the admission of root containers (Manual) + + +**Result:** warn + +**Remediation:** +Create a policy for each namespace in the cluster, ensuring that either `MustRunAsNonRoot` +or `MustRunAs` with the range of UIDs not including 0, is set. + +### 5.2.8 Minimize the admission of containers with the NET_RAW capability (Manual) + + +**Result:** warn + +**Remediation:** +Add policies to each namespace in the cluster which has user workloads to restrict the +admission of containers with the `NET_RAW` capability. + +### 5.2.9 Minimize the admission of containers with added capabilities (Automated) + + +**Result:** warn + +**Remediation:** +Ensure that `allowedCapabilities` is not present in policies for the cluster unless +it is set to an empty array. + +### 5.2.10 Minimize the admission of containers with capabilities assigned (Manual) + + +**Result:** warn + +**Remediation:** +Review the use of capabilites in applications running on your cluster. Where a namespace +contains applicaions which do not require any Linux capabities to operate consider adding +a PSP which forbids the admission of containers which do not drop all capabilities. + +### 5.2.11 Minimize the admission of Windows HostProcess containers (Manual) + + +**Result:** warn + +**Remediation:** +Add policies to each namespace in the cluster which has user workloads to restrict the +admission of containers that have `.securityContext.windowsOptions.hostProcess` set to `true`. + +### 5.2.12 Minimize the admission of HostPath volumes (Manual) + + +**Result:** warn + +**Remediation:** +Add policies to each namespace in the cluster which has user workloads to restrict the +admission of containers with `hostPath` volumes. + +### 5.2.13 Minimize the admission of containers which use HostPorts (Manual) + + +**Result:** warn + +**Remediation:** +Add policies to each namespace in the cluster which has user workloads to restrict the +admission of containers which use `hostPort` sections. + +## 5.3 Network Policies and CNI +### 5.3.1 Ensure that the CNI in use supports NetworkPolicies (Manual) + + +**Result:** warn + +**Remediation:** +If the CNI plugin in use does not support network policies, consideration should be given to +making use of a different plugin, or finding an alternate mechanism for restricting traffic +in the Kubernetes cluster. + +### 5.3.2 Ensure that all Namespaces have NetworkPolicies defined (Manual) + + +**Result:** warn + +**Remediation:** +Follow the documentation and create NetworkPolicy objects as you need them. + +## 5.4 Secrets Management +### 5.4.1 Prefer using Secrets as files over Secrets as environment variables (Manual) + + +**Result:** warn + +**Remediation:** +If possible, rewrite application code to read Secrets from mounted secret files, rather than +from environment variables. + +### 5.4.2 Consider external secret storage (Manual) + + +**Result:** warn + +**Remediation:** +Refer to the Secrets management options offered by your cloud provider or a third-party +secrets management solution. + +## 5.5 Extensible Admission Control +### 5.5.1 Configure Image Provenance using ImagePolicyWebhook admission controller (Manual) + + +**Result:** warn + +**Remediation:** +Follow the Kubernetes documentation and setup image provenance. + +## 5.7 General Policies +### 5.7.1 Create administrative boundaries between resources using namespaces (Manual) + + +**Result:** warn + +**Remediation:** +Follow the documentation and create namespaces for objects in your deployment as you need +them. + +### 5.7.2 Ensure that the seccomp profile is set to docker/default in your Pod definitions (Manual) + + +**Result:** warn + +**Remediation:** +Use `securityContext` to enable the docker/default seccomp profile in your pod definitions. +An example is as below: + securityContext: + seccompProfile: + type: RuntimeDefault + +### 5.7.3 Apply SecurityContext to your Pods and Containers (Manual) + + +**Result:** warn + +**Remediation:** +Follow the Kubernetes documentation and apply SecurityContexts to your Pods. For a +suggested list of SecurityContexts, you may refer to the CIS Security Benchmark for Docker +Containers. + +### 5.7.4 The default namespace should not be used (Manual) + + +**Result:** warn + +**Remediation:** +Ensure that namespaces are created to allow for appropriate segregation of Kubernetes +resources and that all new resources are created in a specific namespace. + diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/rancher-security/kubernetes-security-best-practices.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/rancher-security/kubernetes-security-best-practices.md new file mode 100644 index 00000000000..5b53a6b0467 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/rancher-security/kubernetes-security-best-practices.md @@ -0,0 +1,11 @@ +--- +title: Kubernetes 安全最佳实践 +--- + +## 限制云元数据 API 访问 + +AWS、Azure、DigitalOcean 或 GCP 等云提供商通常会在本地向实例公开元数据服务。默认情况下，此端点可被运行在云实例上的 pod 访问，包括在托管的 Kubernetes（如 EKS、AKS、DigitalOcean Kubernetes 或 GKE）中的 pod，并且可以包含该节点的云凭证、配置数据（如 kubelet 凭证）以及其他敏感数据。为了降低在云平台上运行的这种风险，请遵循 [Kubernetes 安全建议](https://kubernetes.io/docs/tasks/administer-cluster/securing-a-cluster/#restricting-cloud-metadata-api-access)，即限制授予实例凭证的权限，使用网络策略限制 pod 对元数据 API 的访问，并避免使用配置数据来传递密文。 + +建议你参阅你使用的云提供商的安全最佳实践，获取限制对云实例元数据 API 访问的建议和详情。 + +要获取更多参考资料，请参阅 MITRE ATT&CK 知识库 - [不安全凭证：云实例元数据 API](https://attack.mitre.org/techniques/T1552/005/)。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/rancher-security/psa-restricted-exemptions.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/rancher-security/psa-restricted-exemptions.md new file mode 100644 index 00000000000..d623ef71dfb --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/rancher-security/psa-restricted-exemptions.md @@ -0,0 +1,62 @@ +--- +title: PodSecurityConfiguration 示例 +--- + +以下 PodSecurityConfiguration 包含了 `rancher-restricted` 集群正常运行所需的 Rancher 命名空间豁免。 + +```yaml +apiVersion: apiserver.config.k8s.io/v1 +kind: AdmissionConfiguration +plugins: + - name: PodSecurity + configuration: + apiVersion: pod-security.admission.config.k8s.io/v1 + kind: PodSecurityConfiguration + defaults: + enforce: "restricted" + enforce-version: "latest" + audit: "restricted" + audit-version: "latest" + warn: "restricted" + warn-version: "latest" + exemptions: + usernames: [] + runtimeClasses: [] + namespaces: [calico-apiserver, + calico-system, + cattle-alerting, + cattle-csp-adapter-system, + cattle-elemental-system, + cattle-epinio-system, + cattle-externalip-system, + cattle-fleet-local-system, + cattle-fleet-system, + cattle-gatekeeper-system, + cattle-global-data, + cattle-global-nt, + cattle-impersonation-system, + cattle-istio, + cattle-istio-system, + cattle-logging, + cattle-logging-system, + cattle-monitoring-system, + cattle-neuvector-system, + cattle-prometheus, + cattle-resources-system, + cattle-sriov-system, + cattle-system, + cattle-ui-plugin-system, + cattle-windows-gmsa-system, + cert-manager, + cis-operator-system, + fleet-default, + ingress-nginx, + istio-system, + kube-node-lease, + kube-public, + kube-system, + longhorn-system, + rancher-alerting-drivers, + security-scan, + tigera-operator] +``` diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/rancher-security/rancher-security-best-practices.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/rancher-security/rancher-security-best-practices.md new file mode 100644 index 00000000000..9b13fb3e842 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/rancher-security/rancher-security-best-practices.md @@ -0,0 +1,21 @@ +--- +title: Rancher 安全最佳实践 +--- + + + + + +## 限制对 /version 和 /rancherversion 的公共访问 + +上游（本地） Rancher 实例提供正在运行的 Rancher 版本和用于构建它的 Go 版本信息。这些信息可以通过 `/version` 路径访问，该路径用于诸如自动化版本升级或确认部署成功等任务。上游实例还提供了可通过 `/rancherversion` 路径访问的 Rancher 版本信息。 + +攻击者可能会滥用这些信息来识别正在运行的 Rancher 版本，并与潜在的漏洞相关联以进行利用。如果你的上游 Rancher 实例在网上是公开可访问的，请使用 7 层防火墙来阻止 `/version` 和 `/rancherversion` 路径。 + +更多关于保护服务器的详细信息，请参阅 [OWASP Web Application Security Testing - Enumerate Infrastructure and Application Admin Interfaces](https://owasp.org/www-project-web-security-testing-guide/stable/4-Web_Application_Security_Testing/02-Configuration_and_Deployment_Management_Testing/05-Enumerate_Infrastructure_and_Application_Admin_Interfaces.html)。 + +## 会话管理 + +某些环境可能需要额外的安全控制来管理会话。例如，你可能希望限制用户的并发活动会话或限制可以从哪些地理位置发起这些会话。Rancher 默认情况下不支持这些功能。 + +如果你需要此类功能，请将 7 层防火墙与[外部认证](../../how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/authentication-config/authentication-config.md#外部认证与本地认证)结合使用。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/rancher-security/rancher-security.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/rancher-security/rancher-security.md new file mode 100644 index 00000000000..e2ed8a024a6 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/rancher-security/rancher-security.md @@ -0,0 +1,95 @@ +--- +title: 安全 +--- + + + + + + + + + + + +
+

安全策略

+

Rancher Labs 会负责任地披露问题，并致力于在合理的时间内解决所有问题。

+		 +

报告流程

+

请将安全问题发送至 security-rancher@suse.com。

+		 +

公告

+

订阅 Rancher 公告论坛以获取版本更新。

+
+ +安全是 Rancher 全部功能的基础。Rancher 集成了全部主流认证工具和服务，并提供了企业级的 [RBAC 功能](../../how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/manage-role-based-access-control-rbac.md)，让你的 Kubernetes 集群更加安全。 + +本文介绍了安全相关的文档以及资源，让你的 Rancher 安装和下游 Kubernetes 集群更加安全。 + +## NeuVector 与 Rancher 的集成 + +NeuVector 是一个开源的、以容器为中心的安全应用程序，现已集成到 Rancher 中。NeuVector 提供生产安全、DevOps 漏洞保护和容器防火墙等功能。请参阅 [Rancher 文档](../../integrations-in-rancher/neuvector/neuvector.md) 和 [NeuVector 文档](https://open-docs.neuvector.com/)了解更多信息。 + +## 在 Kubernetes 集群上运行 CIS 安全扫描 + +Rancher 使用 [kube-bench](https://github.com/aquasecurity/kube-bench) 来运行安全扫描，从而检查 Kubernetes 是否按照 [CIS](https://www.cisecurity.org/cis-benchmarks/)（Center for Internet Security，互联网安全中心）Kubernetes Benchmark 中定义的安全最佳实践进行部署。 + +CIS Kubernetes Benchmark 是一个参考文档，用于为 Kubernetes 建立安全配置基线。 + +CIS 是一个 501(c\)(3) 非营利组织，成立于 2000 年 10 月，其使命是识别、开发、验证、促进和维持网络防御的最佳实践方案，并建立和指导社区，以在网络空间中营造信任的环境。 + +CIS Benchmark 是目标系统安全配置的最佳实践。CIS Benchmark 是由安全专家、技术供应商、公开和私人社区成员，以及 CIS Benchmark 开发团队共同志愿开发的。 + +Benchmark 提供两种类型的建议，分别是自动（Automated）和手动（Manual）。我们只运行 Automated 相关的测试。 + +Rancher 在集群上运行 CIS 安全扫描时会生成一份报告，该报告会显示每个测试的结果，包括测试概要以及 `passed`、`skipped` 和 `failed` 的测试数量。报告还包括失败测试的修正步骤。 + +有关详细信息，请参阅[安全扫描](../../how-to-guides/advanced-user-guides/cis-scan-guides/cis-scan-guides.md)。 + +## SELinux RPM + +[安全增强型 Linux (SELinux)](https://en.wikipedia.org/wiki/Security-Enhanced_Linux) 是对 Linux 的安全增强。被政府机构使用之后，SELinux 已成为行业标准，并在 CentOS 7 和 8 上默认启用。 + +我们提供了 `rancher-selinux` 和 `rke2-selinux` 两个 RPM（Red Hat 软件包），让 Rancher 产品能够在 SELinux 主机上正常运行。有关详细信息，请参阅[此页面](selinux-rpm/selinux-rpm.md)。 + +## Rancher 加固指南 + +Rancher 加固指南基于 CIS Kubernetes Benchmark。 + +加固指南为加固 Rancher 的生产安装提供了说明性指导。有关安全管控的完整列表，请参阅 Rancher 的 [CIS Kubernetes Benchmark 自我评估](#cis-benchmark-和自我评估)指南。 + +> 加固指南描述了如何保护集群中的节点，建议在安装 Kubernetes 之前参考加固指南中的步骤。 + +每个加固指南版本都针对特定的 CIS Kubernetes Benchmark、Kubernetes 和 Rancher 版本。 + +## CIS Benchmark 和自我评估 + +Benchmark 自我评估是 Rancher 安全加固指南的辅助。加固指南展示了如何加固集群，而 Benchmark 指南旨在帮助你评估加固集群的安全级别。 + +本指南将介绍各种 controls，并提供更新的示例命令来审计 Rancher 创建的集群的合规性。你可以前往 [CIS 网站](https://www.cisecurity.org/benchmark/kubernetes/)下载原始的 Benchmark 文档。 + +Rancher 自我评估指南的每个版本都对应于强化指南、Rancher、Kubernetes 和 CIS Benchmark 的特定版本。 + +## 第三方渗透测试报告 + +Rancher 会定期聘请第三方对 Rancher 软件栈进行安全审计和渗透测试。被测环境遵循 Rancher 在测试时提供的强化指南。以前的渗透测试报告如下。 + +结果： + +- [Cure53 渗透测试 - 2019 年 7 月](https://releases.rancher.com/documents/security/pen-tests/2019/RAN-01-cure53-report.final.pdf) +- [Untamed Theory 渗透测试 - 2019 年 3 月](https://releases.rancher.com/documents/security/pen-tests/2019/UntamedTheory-Rancher_SecurityAssessment-20190712_v5.pdf) + +请注意，新报告不再共享或公开发布。 + +## Rancher 安全公告和 CVE + +Rancher 致力于向社区通报我们产品中的安全问题。有关我们已解决的问题的 CVE（常见漏洞和暴露）列表，请参阅[此页](security-advisories-and-cves.md)。 + +## Kubernetes 安全最佳实践 + +有关保护 Kubernetes 集群的建议，请参阅 [Kubernetes 安全最佳实践](kubernetes-security-best-practices.md)指南。 + +## Rancher 安全最佳实践 + +有关保护 Rancher Manager 部署的建议，请参阅 [Rancher 安全最佳实践](rancher-security-best-practices.md)指南。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/rancher-security/rancher-webhook-hardening.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/rancher-security/rancher-webhook-hardening.md new file mode 100644 index 00000000000..e6c80bac05f --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/rancher-security/rancher-webhook-hardening.md @@ -0,0 +1,137 @@ +--- +title: 加固 Rancher Webhook +--- + + + + + +Rancher Webhook 是 Rancher 中的一个重要组件，它在强制执行 Rancher 及其工作负载的安全要求方面发挥着重要的作用。为了减少其攻击面，对它的访问应限制为唯一有效的调用方：Kubernetes API server。这可以通过单独使用网络策略和认证，或相互结合使用以加固 webhook 免受攻击。 + +## 使用网络策略阻止外部流量 + +webhook 只应接受来自 Kubernetes API server 的请求。但是默认情况下，webhook 可以接受来自任何源的流量。如果你使用的是支持网络策略的 CNI，则可以创建一个策略来阻止来源不是 API server 的流量。 + +Kubernetes 中内置的网络策略资源无法阻止或允许来自集群主机的流量，并且 `kube-apiserver` 进程在主机网络上运行。因此你必须使用当前集群正在使用的 CNI 的高级网络策略资源。以下是 Calico 和 Cilium 的示例。更多详细的信息，请参阅你使用的 CNI 的文档。 + +### Calico + +使用 `crd.projectcalico.org/v1` API 组中的网络策略资源。使用 `app == 'rancher-webhook'` selector 为 webhook 创建一个规则，并且将 control plane 主机的 CIDR 设置为入口源： + +```yaml +apiVersion: crd.projectcalico.org/v1 +kind: NetworkPolicy +metadata: + name: allow-k8s + namespace: cattle-system +spec: + selector: app == 'rancher-webhook' + types: + - Ingress + ingress: + - action: Allow + protocol: TCP + source: + nets: + - 192.168.42.0/24 # control plane 主机的 CIDR。如果主机位于不同的子网中，则可能会列出多个。 + destination: + selector: + app == 'rancher-webhook' +``` + +### Cilium + +使用 `cilium.io/v2` API 组中的 CiliumNetworkPolicy 资源。将 `host` 和 `remote-node` 键添加到 `fromEntities` 入口规则。这会阻止集群内和外部流量，同时允许来自主机的流量。 + +```yaml +apiVersion: "cilium.io/v2" +kind: CiliumNetworkPolicy +metadata: + name: allow-k8s + namespace: cattle-system +spec: + endpointSelector: + matchLabels: + app: rancher-webhook + ingress: + - fromEntities: + - host + - remote-node +``` + +## 要求 Kubernetes API Server 对 Webhook 进行认证 + +Webhook 应仅接受来自 Kubernetes API server 的请求。默认情况下，webhook 不要求客户端对其进行认证。它可以接受任何请求。你可以配置 webhook 验证凭据，以便只有 API server 可以访问它。更多信息可以在 [Kubernetes 文档](https://kubernetes.io/docs/reference/access-authn-authz/extensible-admission-controllers/#authenticate-apiservers)中找到。 + +1. 配置 API server 向 webhook 提供证书，指向 AdmissionConfiguration 文件以配置 ValidatingAdmissionWebhook 和 MutatingAdmissionWebhook 插件： + + ```yaml + # /etc/rancher/admission/admission.yaml + apiVersion: apiserver.config.k8s.io/v1 + kind: AdmissionConfiguration + plugins: + - name: ValidatingAdmissionWebhook + configuration: + apiVersion: apiserver.config.k8s.io/v1 + kind: WebhookAdmissionConfiguration + kubeConfigFile: "/etc/rancher/admission/kubeconfig" + - name: MutatingAdmissionWebhook + configuration: + apiVersion: apiserver.config.k8s.io/v1 + kind: WebhookAdmissionConfiguration + kubeConfigFile: "/etc/rancher/admission/kubeconfig" + ``` + + 这也是配置其他准入插件的同一配置文件，例如 PodSecurity。如果你的发行版或设置使用了额外的准入插件，请将它们也配置在这里。例如，将 [RKE2 的 PodSecurity 配置](https://docs.rke2.io/security/pod_security_standards)添加到这个文件中。 + +2. 创建准入插件引用的 kubeconfig 文件。Rancher Webhook 仅支持客户端证书认证，因此请生成一个 TLS 密钥对，并且将 kubeconfig 设置为使用 `client-certificate` 和 `client-key` 或者使用 `client-certificate-data` 和 `client-key-data`。 例如： + + ```yaml + # /etc/rancher/admission/kubeconfig + apiVersion: v1 + kind: Config + users: + - name: 'rancher-webhook.cattle-system.svc' + user: + client-certificate: /path/to/client/cert + client-key: /path/to/client/key + ``` + +3. 使用 `--admission-control-config-file` 参数启动 kube-apiserver 服务，并将该参数值指向你的 AdmissionConfiguration 文件。具体的操作方式因发行版而异，并不受普遍支持，例如在托管的 Kubernetes 提供商中可能不支持。请查阅你的 Kubernetes 发行版的文档以获取详细的信息。 + + 对于 RKE2，可以使用这样的配置文件启动 `rke2-server`： + + ```yaml + # /etc/rancher/rke2/config.yaml + kube-apiserver-arg: + - admission-control-config-file=/etc/rancher/admission/admission.yaml + kube-apiserver-extra-mount: + - /etc/rancher/admission:/etc/rancher/admission:ro + ``` + + :::danger + 某些发行版会默认设置此参数。如果你的发行版预配置了它自己的 AdmissionConfiguration，则必须将其包含在你自定义的准入控制的配置文件中。例如，RKE2 在 `/etc/rancher/rke2/rke2-pss.yaml` 安装了一个 AdmissionConfiguration 文件，该文件配置了 PodSecurity 准入插件。在 config.yaml 中设置 `admission-control-config-file` 将会覆盖这个重要的安全设置。要包含两个插件，请参阅 [Default Pod Security Standards 文档](https://docs.rke2.io/security/pod_security_standards)并将相应的插件配置复制到你的 admission.yaml 中。 + ::: + +4. 如果你使用 Rancher 通过现有节点来配置你的集群，请在配置集群之前在节点上创建这些文件。 + + 如果你使用 Rancher 在新节点上配置你的集群，请先允许集群配置完成，然后使用 Rancher 提供的 SSH key 和 IP 地址连接到节点，并将 RKE2 的配置文件放在 `/etc/rancher/rke2/config.yaml.d/` 目录下。 + +5. 使用这些凭证配置集群后，配置 Rancher cluster agent 以在 webhook 中启用认证。创建一个包含以下内容的 chart values 的文件： + + ```yaml + # values.yaml + auth: + clientCA: + allowedCNs: + - + - + ``` + +6. 在配置的集群中的 `cattle-system` 命名空间下创建一个 configmap，并包含这些 values 配置： + + ``` + kubectl --namespace cattle-system create configmap rancher-config --from-file=rancher-webhook=values.yaml + ``` + + webhook 将会使用这些 values 配置重新启动。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/rancher-security/security-advisories-and-cves.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/rancher-security/security-advisories-and-cves.md new file mode 100644 index 00000000000..7850b43a184 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/rancher-security/security-advisories-and-cves.md @@ -0,0 +1,21 @@ +--- +title: 安全公告和 CVE +--- + + + + + +Rancher 致力于向社区披露我们产品的安全问题。我们会针对已解决的问题发布安全公告和 CVE（Common Vulnerabilities and Exposures，通用漏洞披露）。Rancher GitHub 上的[安全页面](https://github.com/rancher/rancher/security/advisories)也会发布新的安全公告。 + +| ID | 描述 | 日期 | 解决 | +|----|-------------|------|------------| +| [CVE-2025-62879](https://github.com/rancher/backup-restore-operator/security/advisories/GHSA-wj3p-5h3x-c74q) | Rancher now provides new versions of the Rancher Backup chart which prevent the leak of secret S3 credentials via the Rancher Backup pod log. | 29 Jan 2026 | Rancher [v2.13.2](https://github.com/rancher/rancher/releases/tag/v2.13.2), [v2.12.6](https://github.com/rancher/rancher/releases/tag/v2.12.6), [v2.11.10](https://github.com/rancher/rancher/releases/tag/v2.11.10), and [v2.10.11](https://github.com/rancher/rancher/releases/tag/v2.10.11) | +| [CVE-2025-67601](https://github.com/rancher/rancher/security/advisories/GHSA-mc24-7m59-4q5p) | Rancher now removes the ability to fetch CA certificates stored in Rancher’s setting `cacerts` when using the `login` command. | 29 Jan 2026 | Rancher [v2.13.2](https://github.com/rancher/rancher/releases/tag/v2.13.2), [v2.12.6](https://github.com/rancher/rancher/releases/tag/v2.12.6), [v2.11.10](https://github.com/rancher/rancher/releases/tag/v2.11.10), and [v2.10.11](https://github.com/rancher/rancher/releases/tag/v2.10.11) | +| [CVE-2023-32199](https://github.com/rancher/rancher/security/advisories/GHSA-j4vr-pcmw-hx59) | Rancher now removes the corresponding ClusterRoleBindings whenever the admin GlobalRole or its GlobalRoleBindings are deleted. Previously orphaned ClusterRoleBindings were marked with the annotation `authz.cluster.cattle.io/admin-globalrole-missing=true`. | 23 Oct 2025 | Rancher [v2.12.3](https://github.com/rancher/rancher/releases/tag/v2.12.3) and [v2.11.7](https://github.com/rancher/rancher/releases/tag/v2.11.7) | +| [CVE-2024-58269](https://github.com/rancher/rancher/security/advisories/GHSA-mw39-9qc2-f7mg) | The Rancher audit log redaction process has changed to the following:

  • It now redacts `kubectl.kubernetes.io/last-applied-configuration` annotations on both Response and Request body contents. Previously it did not redact Response body content.
  • It now redacts Cluster Import URLs on both Request URLs and Referer headers. Previously it did not redact Referer headers.
| 23 Oct 2025 | Rancher [v2.12.3](https://github.com/rancher/rancher/releases/tag/v2.12.3) | +| [CVE-2024-58260](https://github.com/rancher/rancher/security/advisories/GHSA-q82v-h4rq-5c86) | Setting the username of one user as the same username of another user causes an error when either user attempts to log in. Therefore, a user with the `Manage Users` permission could potentially deny any user, including admins, from logging in. To prevent this, usernames have been made immutable once set, and it is not possible to update or create a user with a username that is already in use. | 25 Sep 2025 | Rancher [v2.12.2](https://github.com/rancher/rancher/releases/tag/v2.12.2), [v2.11.6](https://github.com/rancher/rancher/releases/tag/v2.11.6), [v2.10.10](https://github.com/rancher/rancher/releases/tag/v2.10.10), and [v2.9.12](https://github.com/rancher/rancher/releases/tag/v2.9.12) | +| [CVE-2024-58267](https://github.com/rancher/rancher/security/advisories/GHSA-v3vj-5868-2ch2) | The Rancher CLI is modified to print the `requestId` more visibly than as part of the login URL. It also adds a `cli=true` origin marker to the URL. The dashboard is modified to recognize the presence of the `requestId` and uses that to show a warning message to the user, asking for verification that they initiated a CLI login with the related Id. The non-presence of the origin marker enables the dashboard to distinguish between the modified CLI and older CLI’s, and adjust the message accordingly. | 25 Sep 2025 | Rancher [v2.12.2](https://github.com/rancher/rancher/releases/tag/v2.12.2), [v2.11.6](https://github.com/rancher/rancher/releases/tag/v2.11.6), [v2.10.10](https://github.com/rancher/rancher/releases/tag/v2.10.10), and [v2.9.12](https://github.com/rancher/rancher/releases/tag/v2.9.12) | +| [CVE-2025-54468](https://github.com/rancher/rancher/security/advisories/GHSA-mjcp-rj3c-36fr) | `Impersonate-*` headers are removed for requests made through the `/meta/proxy` Rancher endpoint (e.g. when cloud credentials are being created) as the headers may contain identifiable and/or sensitive information. | 25 Sep 2025 | Rancher [v2.12.2](https://github.com/rancher/rancher/releases/tag/v2.12.2), [v2.11.6](https://github.com/rancher/rancher/releases/tag/v2.11.6), [v2.10.10](https://github.com/rancher/rancher/releases/tag/v2.10.10), and [v2.9.12](https://github.com/rancher/rancher/releases/tag/v2.9.12) | +| [CVE-2024-58259](https://github.com/rancher/rancher/security/advisories/GHSA-4h45-jpvh-6p5j) | POSTs to the Rancher API endpoints are now limited to 1 Mi; this is configurable through the settings if you need a larger limit. The Rancher authentication endpoints are configured independently of the main public API (as you might need bigger payloads in the other API endpoints). Suppose you need to increase the maximum allowed payload for authentication. In that case, you can set the environment variable `CATTLE_AUTH_API_BODY_LIMIT` to a quantity, e.g., 2 Mi, which would allow larger payloads for the authentication endpoints. | 28 Aug 2025 | Rancher [v2.12.1](https://github.com/rancher/rancher/releases/tag/v2.12.1), [v2.11.5](https://github.com/rancher/rancher/releases/tag/v2.11.5), [v2.10.9](https://github.com/rancher/rancher/releases/tag/v2.10.9) and [v2.9.11](https://github.com/rancher/rancher/releases/tag/v2.9.11) | +| [CVE-2024-52284](https://github.com/rancher/fleet/security/advisories/GHSA-6h9x-9j5v-7w9h) | Following a recent [change](https://github.com/rancher/fleet/pull/3403) excluding Helm values files from bundles, an edge case subsisted where the values files referenced in `fleet.yaml` with your directory name (e.g., `my-dir/values.yaml` instead of `values.yaml`) would not be excluded, which would potentially expose confidential data in bundle resources. Helm values files are now excluded from bundle resources regardless of how you reference them. | 28 Aug 2025 | Rancher [v2.12.1](https://github.com/rancher/rancher/releases/tag/v2.12.1), [v2.11.5](https://github.com/rancher/rancher/releases/tag/v2.11.5) and [v2.10.9](https://github.com/rancher/rancher/releases/tag/v2.10.9) | diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/rancher-security/selinux-rpm/about-rancher-selinux.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/rancher-security/selinux-rpm/about-rancher-selinux.md new file mode 100644 index 00000000000..8d3c679160b --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/rancher-security/selinux-rpm/about-rancher-selinux.md @@ -0,0 +1,66 @@ +--- +title: 关于 rancher-selinux +--- + +要让 Rancher 使用 SELinux，你必须手动为 SELinux 节点启用一些功能。为了解决这个问题，Rancher 提供了一个 SELinux RPM。 + +The `rancher-selinux` RPM contains a set of SELinux policies designed to grant the necessary privileges to various Rancher components running on Linux systems with SELinux enabled. + +`rancher-selinux` 的 GitHub 仓库在[这里](https://github.com/rancher/rancher-selinux)。 + +## 安装 rancher-selinux RPM + +:::note 要求 + +rancher-selinux RPM 已在 CentOS 7 和 8 上进行了测试。 + +::: + +### 1. 设置 yum 仓库 + +设置 yum 仓库，从而直接在集群中的所有主机上安装 `rancher-selinux`。 + +要使用 RPM 仓库，在 CentOS 7 或 RHEL 7 系统上运行以下 bash 代码片段： + +``` +# cat << EOF > /etc/yum.repos.d/rancher.repo +[rancher] +name=Rancher +baseurl=https://rpm.rancher.io/rancher/production/centos/7/noarch +enabled=1 +gpgcheck=1 +gpgkey=https://rpm.rancher.io/public.key +EOF +``` + +要使用 RPM 仓库，在 CentOS 8 或 RHEL 8 系统上运行以下 bash 代码片段： + +``` +# cat << EOF > /etc/yum.repos.d/rancher.repo +[rancher] +name=Rancher +baseurl=https://rpm.rancher.io/rancher/production/centos/8/noarch +enabled=1 +gpgcheck=1 +gpgkey=https://rpm.rancher.io/public.key +EOF +``` +### 2. 安装 RPM + +安装 RPM： + +``` +yum -y install rancher-selinux +``` + +## 配置 Logging 应用程序以使用 SELinux + +:::note 要求 + +Logging v2 已在 RHEL/CentOS 7 和 8 上使用 SELinux 进行了测试。 + +::: + +在主机上安装 `rancher-selinux` RPM 后，应用程序不会自动运行。它们需要在 RPM 提供的允许的 SELinux 容器域中运行。 + +要将 `rancher-logging` Chart 配置为支持 SELinux，请在安装 Chart 时将 `values.yaml` 中的 `global.seLinux.enabled` 更改为 true。 \ No newline at end of file diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/rancher-security/selinux-rpm/about-rke2-selinux.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/rancher-security/selinux-rpm/about-rke2-selinux.md new file mode 100644 index 00000000000..b5e4a22cad9 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/rancher-security/selinux-rpm/about-rke2-selinux.md @@ -0,0 +1,9 @@ +--- +title: 关于 rke2-selinux +--- + +`rke2-selinux` 为 RKE2 提供策略。如果 RKE2 安装程序脚本检测到它运行在基于 RPM 的发行版上，它会自动安装。 + +`rke2-selinux` 的 GitHub 仓库在[这里](https://github.com/rancher/rke2-selinux)。 + +有关在启用 SELinux 的主机上安装 RKE2 的更多信息，请参阅 [RKE2 文档](https://docs.rke2.io/install/methods#rpm)。 \ No newline at end of file diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/rancher-security/selinux-rpm/selinux-rpm.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/rancher-security/selinux-rpm/selinux-rpm.md new file mode 100644 index 00000000000..2c96bf912ee --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/rancher-security/selinux-rpm/selinux-rpm.md @@ -0,0 +1,20 @@ +--- +title: SELinux RPM +--- + + + + + +[安全增强型 Linux (SELinux)](https://en.wikipedia.org/wiki/Security-Enhanced_Linux) 是对 Linux 的安全增强。 + +它由 Red Hat 开发，是 Linux 上 MAC（mandatory access controls，强制访问控制）的实现。系统管理员可以使用 MAC 设置应用程序和用户是如何访问不同资源的，例如文件、设备、网络和进程间的通信。SELinux 还通过默认限制操作系统来增强安全性。 + +被政府机构使用之后，SELinux 已成为行业标准，并在 CentOS 7 和 8 上默认启用。要检查 SELinux 是否在你的系统上启用和执行，请使用 `getenforce`： + +``` +# getenforce +Enforcing +``` + +我们提供了 [`rancher-selinux`](about-rancher-selinux.md) 和 [`rke2-selinux`](about-rke2-selinux.md) 两个 RPM（Red Hat 软件包），让 Rancher 产品能够在 SELinux 主机上正常运行。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/rancher-webhook.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/rancher-webhook.md new file mode 100644 index 00000000000..4d811b5a23c --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/rancher-webhook.md @@ -0,0 +1,143 @@ +--- +title: Rancher Webhook +--- + + + + + +Rancher-Webhook 是 Rancher 的重要组件，它与 Kubernetes 结合使用，用于增强安全性并为 Rancher 管理的集群启用关键功能。 + +如 [Kubernetes 文档](https://kubernetes.io/docs/reference/access-authn-authz/extensible-admission-controllers/)中所述，它与 Kubernetes 的可扩展准入控制器集成，允许 Rancher-Webhook 检查发送到 Kubernetes API Server 的特定请求，添加自定义和 Rancher 相关的验证，以及 Rancher 相关请求的变化。Rancher-Webhook 使用 `rancher.cattle.io` `ValidatingWebhookConfiguration` 和 `rancher.cattle.io` `MutatingWebhookConfiguration` 管理要验证的资源，并覆盖任何手动编辑。 + +Rancher 将 Rancher-Webhook 作为单独的 deployment 和服务部署在 local 和下游集群中。Rancher 使用 Helm 管理 Rancher-Webhook。需要注意的是，Rancher 可能会覆盖用户对 Helm 版本所做的修改。要安全地修改这些值，请参阅[自定义 Rancher-Webhook 配置](#自定义-rancher-webhook-配置) + +每个 Rancher 版本都设计为与某个具体版本的 Webhook 兼容，为方便起见，下面提供了各版本的兼容列表。 + +**注意：** Rancher 负责管理 webhook 的部署和升级。在多数情况下，不需要用户干预来确保 webhook 版本与你正在运行的 Rancher 版本兼容。 + + + +| Rancher Version | Webhook Version | Availability in Prime | Availability in Community | +|-----------------|-----------------|-----------------------|---------------------------| +| v2.13.3 | v0.9.3 | ✓ | ✓ | +| v2.13.2 | v0.9.2 | ✓ | ✓ | +| v2.13.1 | v0.9.1 | ✓ | ✓ | +| v2.13.0 | v0.9.0 | ✗ | ✓ | + +## 为什么我们需要它？ + +Rancher-Webhook 对于让 Rancher 保护集群免受恶意攻击并启用各种功能至关重要。 +Rancher 依赖 Rancher-Webhook 作为其功能的组成部分。如果没有 Webhook，Rancher 将不是一个完整的产品。 +它为 Rancher 管理的集群提供了必要的保护，防止安全漏洞并确保集群的一致性和稳定性。 + +## Webhook 验证哪些资源? + +你可以在 [webhook 仓库](https://github.com/rancher/webhook/blob/release/v0.4/docs.md)中找到 webhook 当前验证的资源列表。这些文档按组/版本（顶级标题）和资源（下一级标题）进行组织。可以通过查看与特定版本标签关联的 `docs.md` 文件来找到特定于一个版本的检查。请注意，`v0.3.6` 之前的 webhook 版本没有此文件。 + +## 绕过 Webhook + +有时，你必须绕过 Rancher 的 webhook 验证才能执行紧急还原操作或修复其他关键问题。避开操作是彻底的，这意味着在使用它时不会应用任何 webhook 验证或更改。不可能指定绕过某些验证，而让其他验证仍然可用。它们要么全部被绕过，要么全部处于活动状态。 + +:::danger + +Rancher 的 webhook 提供关键的安全保护。只有在所有其他选项都用尽之后，管理员才需要在特定情况下绕过 webhook。此外，应仔细控制绕过 webhook 的权限，切勿将该权限授予非管理员用户。 + +::: + +要绕过 webhook，请模拟 `rancher-webhook-sudo` 服务账号和 `system:masters` 组（两者都是必需的）： + +```bash +kubectl create -f example.yaml --as=system:serviceaccount:cattle-system:rancher-webhook-sudo --as-group=system:masters +``` + +## 自定义 Rancher-Webhook 配置 + +你可以通过 Helm 安装 Rancher-Webhook 时添加自定义 Helm values。在 Rancher-Webhook chart 的安装过程中，Rancher 会检查自定义的 Helm values。这些自定义值必须在 `cattle-system` 命名空间中，名称为 `rancher-config` 的 ConfigMap 的 data 属性下，增加 `rancher-webhook` 的配置定义。此键的值必须是有效的 YAML。 + +```yaml +apiVersion: v1 +kind: ConfigMap +metadata: + name: rancher-config + namespace: cattle-system + labels: + app.kubernetes.io/part-of: "rancher" +data: + rancher-webhook: '{"port": 9553, "priorityClassName": "system-node-critical"}' +``` + +Rancher 会在检测到对 ConfigMap 值的更改时重新部署 Rancher-Webhook Chart。 + +### 在 Rancher 安装过程中自定义 Rancher-Webhook + +使用 Helm 安装 Rancher chart 时，可以在 local 集群中将自定义的 Helm values 添加到 Rancher-Webhook。Rancher-Webhook Chart 中的所有值都可以通过 `webhook` 名称下的嵌套变量访问。 + +这些值在安装过程中会同步到 `rancher-config` ConfigMap 中。 + +```bash +helm install rancher rancher-/rancher \ + --namespace cattle-system \ + ... + --set webhook.port=9553 \ + --set webhook.priorityClassName="system-node-critical" +``` + +## 常见问题 + +### 带有 Calico CNI 的 EKS 集群 + +当 Kubernetes API Server 尝试联系 Rancher-Webhook 时，使用 Calico CNI 运行 EKS 集群的用户可能会遇到错误。 +根据 [Calico 文档](https://docs.tigera.io/calico/latest/getting-started/kubernetes/managed-public-cloud/eks#install-eks-with-calico-networking)，此问题的解决方法是为 Webhook 部署设置 `hostNetwork=true`。用户可以在受影响的集群上使用下面的 Helm 命令更改此设置。 + +```bash +helm repo add rancher-charts https://charts.rancher.io +helm upgrade --reuse-values rancher-webhook rancher-chart/rancher-webhook -n cattle-system --set global.hostNetwork=true +``` + +**注意**：这个临时解决方法可能会违反环境的安全策略。此解决方法还要求主机网络上未使用端口 9443。 + +**注意：** 默认情况下，Helm 使用 secrets。这是某些 webhook 版本验证用于存储信息的数据类型。在这种情况下，请使用 kubectl 更新 deployment 设置 `hostNetwork=true`，然后按照上述配置更新 webhook。 + +### 私有 GKE 集群 + +使用私有 GKE 集群时可能会发生错误，导致 Kubernetes API Server 无法与 Webhook 通信。以下错误消息可能会出现： + +``` +Internal error occurred: failed calling webhook "rancher.cattle.io.namespaces.create-non-kubesystem": failed to call webhook: Post "https://rancher-webhook.cattle-system.svc:443/v1/webhook/validation/namespaces?timeout=10s": context deadline exceeded +``` + +出现此问题的原因是防火墙规则限制了 API Server 与私有集群之间的通信。要解决此通信问题，你必须通过添加防火墙规则来允许 GKE Control Plane 通过端口 9443 与 Rancher-Webhook 进行通信。请参阅 [GKE 文档](https://cloud.google.com/kubernetes-engine/docs/how-to/private-clusters#add_firewall_rules)，了解更新防火墙规则的详细信息和步骤。 + +### 由于 rancher-webhook 阻止访问导致应用部署失败 + +webhook 在 [namespaces](https://github.com/rancher/webhook/blob/release/v0.4/docs.md#psa-label-validation) 上提供额外的验证。其中一项验证可确保用户只有在具有适当权限的情况下才能更新 PSA 相关标签（`updatepsa` for `projects` in `management.cattle.io`）。这可能导致特定 operator（如 Tigera 或 Trident）在尝试部署带有 PSA 标签的命名空间时失败。有几种方法可以解决此问题： + +- 将应用程序配置为创建没有 PSA 标签的命名空间。如果用户希望将 PSA 应用于这些命名空间，则可以在配置后将它们添加到具有所需 PSA 的项目中。请参阅[设置 PSS 和 PSA 资源的文档](../how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/pod-security-standards.md)获取更具体的操作方法。 + - 这是首选选项，但并非所有应用程序都可以以这种方式进行配置。 +- 手动授予操作员管理命名空间下的 PSA 的权限。 + - 此选项将引入安全风险，因为运营商现在将能够为其有权访问的命名空间设置 PSA。这可能允许操作员部署特权 Pod，或通过其他方式实现集群接管。 +- 具有适当权限的用户帐户可以使用适当的配置预先创建命名空间。 + - 此选项取决于应用程序处理现有资源的能力。 + +Another one of these validations ensures that the user has the proper permissions to update the `field.cattle.io/projectId` annotation on a namespace. This is the `manage-namespaces` permission for `projects` in `management.cattle.io`. + +## 特定版本的问题 + +**注意：** 以下是影响特定 Rancher/webhook 版本的高严重性问题的不完整列表。在大多数情况下，这些问题可以通过升级到更新的 Rancher 版本来解决。 + +### 回滚到不兼容的 Webhook 版本 + +**注意：** 这会影响回滚到 Rancher v2.7.5 或更早版本。 + +如果回滚到 Rancher v2.7.5 或更早版本，您可能会看到 webhook 版本太新，无法与运行 v2.7.5 之前版本的 Rancher 的下游集群兼容。这可能会导致各种不兼容问题。例如，项目成员可能无法创建命名空间。此外，当您回滚到下游集群中安装 webhook 之前的版本时，webhook 可能仍保持安装状态，这会导致类似的不兼容问题。 + +为了帮助缓解这些问题，您可以在回滚后运行 [adjust-downstream-webhook](https://github.com/rancherlabs/support-tools/tree/master/adjust-downstream-webhook) shell 脚本。该脚本为相应的 Rancher 版本选择并安装正确的 webhook 版本（或完全删除 webhook）。 + +### 项目用户无法创建命名空间 + +**注意：** 以下内容影响 Rancher v2.7.2 - v2.7.4。 + +项目用户可能无法在项目中创建命名空间，这包括项目所有者。此问题是由于 Rancher 自动将 webhook 升级到与当前安装的 Rancher 版本更新的版本不兼容而导致的。 + +为了帮助缓解这些问题，您可以在回滚后运行 [adjust-downstream-webhook](https://github.com/rancherlabs/support-tools/tree/master/adjust-downstream-webhook) shell 脚本。该脚本为相应的 Rancher 版本选择并安装正确的 webhook 版本（或完全删除 webhook）。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/rke1-template-example-yaml.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/rke1-template-example-yaml.md new file mode 100644 index 00000000000..55a616f36f5 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/rke1-template-example-yaml.md @@ -0,0 +1,113 @@ +--- +title: RKE1 示例 YAML +--- + + + +以下是一个供参考的 RKE 模板配置文件示例。 + +RKE 模板中的 YAML 使用与创建 RKE 集群时相同的自定义项。但是，由于 YAML 位于 Rancher 配置的 RKE 集群的上下文中，因此 RKE 文档中的自定义项需要嵌套在 `rancher_kubernetes_engine` 指令下。 + +```yaml +# +# Cluster Config +# +docker_root_dir: /var/lib/docker + +enable_cluster_alerting: false +# This setting is not enforced. Clusters +# created with this sample template +# would have alerting turned off by default, +# but end users could still turn alerting +# on or off. + +enable_cluster_monitoring: true +# This setting is not enforced. Clusters +# created with this sample template +# would have monitoring turned on +# by default, but end users could still +# turn monitoring on or off. + +enable_network_policy: false +local_cluster_auth_endpoint: + enabled: true +# +# Rancher Config +# +rancher_kubernetes_engine_config: # Your RKE template config goes here. + addon_job_timeout: 30 + authentication: + strategy: x509 + ignore_docker_version: true +# +# # 目前仅支持 Nginx ingress provider +# # 要禁用 Ingress controller，设置 `provider: none` +# # 要在指定节点上禁用 Ingress，使用 node_selector，例如： +# provider: nginx +# node_selector: +# app: ingress +# + ingress: + provider: nginx + kubernetes_version: v1.15.3-rancher3-1 + monitoring: + provider: metrics-server +# +# If you are using calico on AWS +# +# network: +# plugin: calico +# calico_network_provider: +# cloud_provider: aws +# +# # To specify flannel interface +# +# network: +# plugin: flannel +# flannel_network_provider: +# iface: eth1 +# +# # To specify flannel interface for canal plugin +# +# network: +# plugin: canal +# canal_network_provider: +# iface: eth1 +# + network: + options: + flannel_backend_type: vxlan + plugin: canal +# +# services: +# kube-api: +# service_cluster_ip_range: 10.43.0.0/16 +# kube-controller: +# cluster_cidr: 10.42.0.0/16 +# service_cluster_ip_range: 10.43.0.0/16 +# kubelet: +# cluster_domain: cluster.local +# cluster_dns_server: 10.43.0.10 +# + services: + etcd: + backup_config: + enabled: true + interval_hours: 12 + retention: 6 + safe_timestamp: false + creation: 12h + extra_args: + election-timeout: 5000 + heartbeat-interval: 500 + gid: 0 + retention: 72h + snapshot: false + uid: 0 + kube_api: + always_pull_images: false + pod_security_policy: false + service_node_port_range: 30000-32767 + ssh_agent_auth: false +windows_prefered_cluster: false +``` diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/single-node-rancher-in-docker/advanced-options.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/single-node-rancher-in-docker/advanced-options.md new file mode 100644 index 00000000000..ba32b346881 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/single-node-rancher-in-docker/advanced-options.md @@ -0,0 +1,105 @@ +--- +title: Docker 安装高级选项 +--- + +## 自定义 CA 证书 + +如需 Rancher 在验证服务时使用 CA 根证书，请在启动 Rancher 容器时共享包含 CA 根证书的目录。 + +使用命令示例来启动挂载了私有 CA 证书的 Rancher 容器。 + +- 卷标志 (`-v`) 应指定包含 CA 根证书的主机目录。 +- 环境变量标志 (`-e`) 与 `SSL_CERT_DIR` 和目录共同声明一个环境变量，该变量指定容器内挂载了 CA 根证书的目录位置。 +- 你可使用 `-e KEY=VALUE` 或 `--env KEY=VALUE`将环境变量传给 Rancher 容器。 +- 你可使用 `-v host-source-directory:container-destination-directory` 或 `--volume host-source-directory:container-destination-directory`在容器内挂载主机目录。 + +在以下示例将位于 `/host/certs` 主机目录中的 CA 证书，挂载到 Rancher 容器内的 `/container/certs` 上。 + +特权访问是[必须](../../getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/rancher-on-a-single-node-with-docker.md#rancher-特权访问)的。 + +``` +docker run -d --restart=unless-stopped \ + -p 80:80 -p 443:443 \ + -v /host/certs:/container/certs \ + -e SSL_CERT_DIR="/container/certs" \ + --privileged \ + rancher/rancher:latest +``` + +## API 审计日志 + +API 审计日志记录了通过 Rancher Server 进行的所有用户和系统事务。 + +默认情况下，API 审计日志会写入到 Rancher 容器内的 `/var/log/auditlog`。你可将此目录共享为卷，并设置 `AUDIT_LEVEL` 以启用日志。 + +有关更多信息和选项，请参见 [API 审计日志](../../how-to-guides/advanced-user-guides/enable-api-audit-log.md)。 + +特权访问是[必须](../../getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/rancher-on-a-single-node-with-docker.md#rancher-特权访问)的。 + +``` +docker run -d --restart=unless-stopped \ + -p 80:80 -p 443:443 \ + -v /var/log/rancher/auditlog:/var/log/auditlog \ + -e AUDIT_LEVEL=1 \ + --privileged \ + rancher/rancher:latest +``` + +## TLS 设置 + +如需使用不同的 TLS 配置，你可使用 `CATTLE_TLS_MIN_VERSION` 和 `CATTLE_TLS_CIPHERS` 环境变量。例如，将 TLS 1.0 设为可接受的最低 TLS 版本，如下： + +``` +docker run -d --restart=unless-stopped \ + -p 80:80 -p 443:443 \ + -e CATTLE_TLS_MIN_VERSION="1.0" \ + --privileged \ + rancher/rancher:latest +``` + +特权访问是[必须](../../getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/rancher-on-a-single-node-with-docker.md#rancher-特权访问)的。 + +参见 [TLS 设置](../../getting-started/installation-and-upgrade/installation-references/tls-settings.md)了解更多信息和选项。 + +## 离线环境 + +如果要访问此页面以完成离线安装，在运行安装命令时，你必须把私有镜像仓库的 URL 添加到 Server 标志前面。例如，将带有私有镜像仓库 URL 的 `` 添加到 `rancher/rancher:latest` 前面。 + +**示例**： + + /rancher/rancher:latest + +## 持久化数据 + +Rancher 使用 etcd 作为数据存储。如果 Rancher 是使用 Docker 安装的，Rancher 会使用嵌入式 etcd。持久化数据位于容器的 `/var/lib/rancher` 路径中。 + +你可以将主机卷挂载到该位置，来将数据保留在运行它的主机上： + +``` +docker run -d --restart=unless-stopped \ + -p 80:80 -p 443:443 \ + -v /opt/rancher:/var/lib/rancher \ + --privileged \ + rancher/rancher:latest +``` + +特权访问是[必须](../../getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/rancher-on-a-single-node-with-docker.md#rancher-特权访问)的。 + +## 在同一个节点中运行 `rancher/rancher` 和 `rancher/rancher-agent` + +如需使用单个节点运行 Rancher 并将同一个节点添加到集群，你必须调整映射给 `rancher/rancher` 容器的主机端口。 + +如果将节点添加到集群中，节点将部署使用端口 80 和 443 的 NGINX Ingress Controller。而这将与我们建议用于暴露 `rancher/rancher` 容器的默认端口冲突。 + +请知悉我们不建议将此设置用于生产环境，这种方式仅用来方便进行开发/演示。 + +如需更改主机端口映射，将 `-p 80:80 -p 443:443` 替换为 `-p 8080:80 -p 8443:443`： + +``` +docker run -d --restart=unless-stopped \ + -p 8080:80 -p 8443:443 \ + --privileged \ + rancher/rancher:latest +``` + +特权访问是[必须](../../getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/rancher-on-a-single-node-with-docker.md#rancher-特权访问)的。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/single-node-rancher-in-docker/http-proxy-configuration.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/single-node-rancher-in-docker/http-proxy-configuration.md new file mode 100644 index 00000000000..ecfa26274c5 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/single-node-rancher-in-docker/http-proxy-configuration.md @@ -0,0 +1,61 @@ +--- +title: HTTP 代理配置 +--- + +如果你通过代理来操作 Rancher，并想要通过代理访问服务（例如拉取应用商店），你需要提供 Rancher 代理的信息。由于 Rancher 是用 Go 编写的，Rancher 使用如下常见的代理环境变量。 + +请确保 `NO_PROXY` 包含不使用代理的网络地址，网络地址范围和域名。 + +| 环境变量 | 用途 | +| -------------------- | ----------------------------------------------------------------------------------------------------------------------- | +| HTTP_PROXY | 发起 HTTP 连接的代理地址 | +| HTTPS_PROXY | 发起 HTTPS 连接的代理地址 | +| NO_PROXY | 发起连接时不使用代理的网络地址，网络地址范围和域名 | + +:::note 重要提示： + +`NO_PROXY` 必须大写才能使用网络范围 CIDR 表示法。 + +::: + +## 基于 Docker 安装 + +你可使用 `-e KEY=VALUE` 或 `--env KEY=VALUE`将环境变量传给 Rancher 容器。在 [Docker 安装](../../getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/rancher-on-a-single-node-with-docker.md)中，`NO_PROXY` 必须的值为： + +- `localhost` +- `127.0.0.1` +- `0.0.0.0` +- `10.0.0.0/8` +- `cattle-system.svc` +- `.svc` +- `.cluster.local` + +以下示例中，代理服务器可以通过 `http://192.168.0.1:3128` 访问。此外，在访问 `192.168.10.0/24` 网络范围以及 `example.com` 域名下的每个主机名时均不使用代理服务器。 + +``` +docker run -d --restart=unless-stopped \ + -p 80:80 -p 443:443 \ + -e HTTP_PROXY="http://192.168.10.1:3128" \ + -e HTTPS_PROXY="http://192.168.10.1:3128" \ + -e NO_PROXY="localhost,127.0.0.1,0.0.0.0,10.0.0.0/8,cattle-system.svc,192.168.10.0/24,.svc,.cluster.local,example.com" \ + --privileged \ + rancher/rancher:latest +``` + +特权访问是[必须](../../getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/rancher-on-a-single-node-with-docker.md#rancher-特权访问)的。 + +### 离线代理配置 + +你现在可以在配置的离线集群中配置主机驱动集群，以使用代理进行出站连接。 + +除了如上为代理服务器设置默认规则外，你还需要额外添加如下所示的规则，以从代理的 Rancher 环境中配置主机驱动集群。 + +根据你的设置配置文件路径，例如 `/etc/apt/apt.conf.d/proxy.conf`： + +``` +acl SSL_ports port 22 +acl SSL_ports port 2376 + +acl Safe_ports port 22 # ssh +acl Safe_ports port 2376 # docker port +``` diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/single-node-rancher-in-docker/single-node-rancher-in-docker.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/single-node-rancher-in-docker/single-node-rancher-in-docker.md new file mode 100644 index 00000000000..e272daa1ca4 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/single-node-rancher-in-docker/single-node-rancher-in-docker.md @@ -0,0 +1,9 @@ +--- +title: Docker 中的单节点 Rancher +--- + + + + + +以下文档将讨论 Docker 安装的 [HTTP 代理配置](http-proxy-configuration.md)和[高级选项](advanced-options.md)。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/system-tools.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/system-tools.md new file mode 100644 index 00000000000..ce21d6c41fd --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/system-tools.md @@ -0,0 +1,31 @@ +--- +title: 系统工具 +--- + +:::note + +系统工具（System Tools）自 2022 年 6 月起已弃用。 + +::: + +## 日志 + +请使用 [logs-collector](https://github.com/rancherlabs/support-tools/tree/master/collection/rancher/v2.x/logs-collector) 来收集你的集群日志。 + +## Stats + +如果要复制 stats 命令，你可以在集群节点上运行以下命令： + +:::note + +以下命令需要集群节点上的 `sysstat` 包。 + +::: + +``` +/usr/bin/sar -u -r -F 1 1 +``` + +## Remove + +请使用 [Rancher Cleanup](https://github.com/rancher/rancher-cleanup) 工具。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/user-settings/api-keys.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/user-settings/api-keys.md new file mode 100644 index 00000000000..c5e3e8b9e4a --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/user-settings/api-keys.md @@ -0,0 +1,59 @@ +--- +title: API 密钥 +--- + +## API 密钥和用户身份验证 + +如果你想通过外部应用程序来访问 Rancher 集群、项目或其他对象，你可以使用 Rancher API。但是，在你的应用程序可以访问 API 之前，你必须为应用程序提供用于向 Rancher 进行身份验证的密钥。你可以通过 Rancher UI 获取密钥。 + +使用 Rancher CLI 也需要 API 密钥。 + +API 密钥由四个组件组成： + +- **端点**：其他应用程序用来向 Rancher API 发送请求的 IP 地址和路径。 +- **访问密钥**：Token 的用户名。 +- **密文密钥**：Token 的密码。如果应用程序提示你输入两个不同的字符串进行 API 身份验证，你通常需要将两个密钥一起输入。 +- **持有者令牌**：连接在一起的令牌用户名和密码。如果应用程序提示你输入一个身份验证字符串，则使用此字符串。 + +:::note + +用户可以选择启用[令牌哈希（token hashing）](../../api/api-tokens.md)。 + +::: + +## 创建 API 密钥 + +1. 从右上角选择**用户头像 > 账号 & API 密钥**。 + +2. 单击**创建 API 密钥**。 + +3. **可选**：输入 API 密钥的描述并选择有效期或范围。我们建议设置到期日期。 + + API 密钥过期后将失效。有效期短一点会更安全。 + + 有效期将受 `v3/settings/auth-token-max-ttl-minutes` 约束。如果超过 max-ttl，则会以 max-ttl 为有效期创建 API 密钥。 + + 范围将限制 API 密钥，使其仅适用于指定集群的 Kubernetes API。如果集群配置了授权集群端点，你将能够直接针对集群的 API 使用设定了范围的令牌，而无需通过 Rancher Server 进行代理。有关详细信息，请参阅[授权集群端点](../../reference-guides/rancher-manager-architecture/communicating-with-downstream-user-clusters.md#4-授权集群端点)。 + +4. 单击**创建**。 + + **步骤结果**：已创建 API 密钥。将会显示你的 API **端点**、**访问密钥**、**密文密钥**和**持有者令牌**。 + + 使用**持有者令牌**通过 Rancher CLI 进行身份验证。 + +5. 将显示的信息复制到安全位置。此信息仅显示一次，因此如果你丢失了密钥，则必须制作一个新的。 + +## 后续操作 + +- 将 API 密钥信息输入到将向 Rancher API 发送请求的应用程序中。 +- 要了解 Rancher 端点和参数的更多信息，你可以为 Rancher UI 中的对象选择**在 API 中查看**。 +- API 密钥可用于 API 调用和 [Rancher CLI](../cli-with-rancher/cli-with-rancher.md)。 + +## 删除 API 密钥 + +如果要撤销 API 密钥，请将其删除。如果出现以下情况，你需要删除 API 密钥： + +- API 密钥可能已经泄露。 +- API 密钥已过期。 + +要删除 API，选择密钥并单击**删除**。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/user-settings/manage-cloud-credentials.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/user-settings/manage-cloud-credentials.md new file mode 100644 index 00000000000..7221dc761cd --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/user-settings/manage-cloud-credentials.md @@ -0,0 +1,51 @@ +--- +title: 管理云凭证 +--- + +如果要创建[由基础设施提供商托管](../../how-to-guides/new-user-guides/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/use-new-nodes-in-an-infra-provider.md)的集群，则可以使用[节点模板](../../how-to-guides/new-user-guides/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/use-new-nodes-in-an-infra-provider.md#节点模板)来配置集群节点。这些模板使用 Docker Machine 配置选项来定义节点的操作系统镜像以及设置/参数。 + +节点模板可以使用云凭证来访问在基础设施提供商中配置节点所需的凭证信息。多个节点模板可以使用相同的云凭证。云凭证省去了为同一云提供商重新输入访问密钥的麻烦。云凭证存储在 Kubernetes 密文中。 + +只有存在标记为 `password` 的字段时，节点模板才会使用云凭证。默认的 `active` 主机驱动将其账号访问字段标记为 `password`，但可能有一些 `inactive` 主机驱动没有使用它们。这些主机驱动不会使用云凭证。 + +你可以在两种情况下创建云凭证： + +- [在为集群创建节点模板期间](../../how-to-guides/new-user-guides/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/use-new-nodes-in-an-infra-provider.md#节点模板)。 +- 在**用户设置**中。 + +所有云凭证都绑定到创建者的用户配置文件。**不能**与其他用户共享。 + +## 使用用户设置创建云凭证 + +1. 点击 **☰ > 集群管理**。 +1. 单击**云凭证**。 +1. 单击**创建**。 +1. 单击云凭证类型。下拉列表中的选项取决于 Rancher 中的 `active` [主机驱动](../../how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/about-provisioning-drivers/manage-node-drivers.md)。 +1. 输入云凭证的名称。 +1. 根据所选的云凭证类型输入所需的值，从而向基础设施提供商进行身份验证。 +1. 单击**创建**。 + +**结果**：已创建云凭证，它可以立即用于[创建节点模板](../../how-to-guides/new-user-guides/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/use-new-nodes-in-an-infra-provider.md#节点模板)。 + +## 更新云凭证 + +如果访问凭证更改或泄露了，你可以通过更新云凭证来进行轮换，同时保留相同的节点模板。 + +1. 点击 **☰ > 集群管理**。 +1. 单击**云凭证**。 +1. 选择要编辑的云凭证，然后单击 **⋮ > 编辑配置**。 +1. 更新凭证信息并单击**保存**。 + +**结果**：已使用新的访问凭证更新云凭证。[添加新节点](../../how-to-guides/new-user-guides/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/use-new-nodes-in-an-infra-provider.md)时，所有使用此云凭证的现有节点模板都会自动使用更新的信息。 + +## 删除云凭证 + +如果要删除云凭证，云凭证不能有关联的节点模板。如果你无法删除云凭证，请[删除与该云凭证关联的所有节点模板](manage-node-templates.md#删除节点模板)。 + +1. 点击 **☰ > 集群管理**。 +1. 单击**云凭证**。 +1. 你可以删除单个云凭证或进行批量删除。 + + - 要单独删除一个云凭证，请选择你要编辑的云凭证，然后单击 **⋮ > 删除**。 + - 要批量删除云凭证，请从列表中选择一个或多个云凭证。单击**删除**。 +1. 确认你需要删除这些云凭证。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/user-settings/manage-node-templates.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/user-settings/manage-node-templates.md new file mode 100644 index 00000000000..e81f2ff8090 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/user-settings/manage-node-templates.md @@ -0,0 +1,54 @@ +--- +title: 管理节点模板 +--- + +如果要配置[由基础设施提供商托管](../../how-to-guides/new-user-guides/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/use-new-nodes-in-an-infra-provider.md)的集群，则可以使用[节点模板](../../how-to-guides/new-user-guides/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/use-new-nodes-in-an-infra-provider.md#节点模板)来配置集群节点。这些模板使用 Docker Machine 配置选项来定义节点的操作系统镜像以及设置/参数。你可以在两种情况下创建节点模板： + +- [配置节点池集群](../../how-to-guides/new-user-guides/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/use-new-nodes-in-an-infra-provider.md)。 +- 在任何时间使用[用户设置](./user-settings.md)。 + +创建节点模板时，它会绑定到你的用户配置文件。节点模板不能在用户之间共享。你可以从用户设置中删除不再使用的旧节点模板。 + +## 创建节点模板 + +1. 点击 **☰ > 集群管理**。 +1. 单击 **RKE1 配置 > 节点模板**。 +1. 单击**添加模板**。 +1. 选择一个可用的云提供商。然后按照屏幕上的说明配置模板。 + +**结果**：模板已配置。你可以稍后在[配置节点池集群](../../how-to-guides/new-user-guides/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/use-new-nodes-in-an-infra-provider.md)时使用该模板。 + +## 更新节点模板 + +1. 点击 **☰ > 集群管理**。 +1. 单击 **RKE1 配置 > 节点模板**。 +1. 选择要编辑的节点模板并单击 **⋮ > 编辑**。 + + :::note + + 默认的 `active` [主机驱动](../../how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/about-provisioning-drivers/manage-node-drivers.md)和任何标记了 `password` 字段的主机驱动都需要使用[云凭证](../../how-to-guides/new-user-guides/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/use-new-nodes-in-an-infra-provider.md#云凭证)。 + + ::: + +1. 编辑所需信息并单击**保存**。 + +**结果**：节点模板已更新。添加新节点时，使用此节点模板的所有节点池都会自动使用更新的信息。 + +## 克隆节点模板 + +通过用户设置创建新的节点模板时，可以克隆现有模板并快速更新其设置，而无需从头开始创建新的模板。克隆模板避免了为云提供商重新输入访问密钥的麻烦。 + +1. 点击 **☰ > 集群管理**。 +1. 单击 **RKE1 配置 > 节点模板**。 +1. 找到要克隆的模板。然后选择 **⋮ > 克隆**。 +1. 填写表单的其余部分。 + +**结果**：已克隆和配置模板。你可以稍后在[配置节点池集群](../../how-to-guides/new-user-guides/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/use-new-nodes-in-an-infra-provider.md)时使用该模板。 + +## 删除节点模板 + +不再使用节点模板时，你可以将其从用户设置中删除。 + +1. 点击 **☰ > 集群管理**。 +1. 单击 **RKE1 配置 > 节点模板**。 +1. 从列表中选择一个或多个模板。然后点击**删除**。出现提示时确认删除。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/user-settings/user-preferences.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/user-settings/user-preferences.md new file mode 100644 index 00000000000..96650669366 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/user-settings/user-preferences.md @@ -0,0 +1,62 @@ +--- +title: 用户偏好 +--- + +你可以通过偏好设置来个性化你的 Rancher 体验。要更改偏好设置： + +1. 单击右上角的用户头像。 +1. 单击**偏好设置**。 + +## 语言 + +选择 Rancher UI 显示的语言。选项包括： + +- English +- 简体中文 + +## 主题 + +选择 Rancher UI 的背景颜色。如果选择**自动**，背景颜色会在下午 6 点从浅色变为深色，然后在早上 6 点变回浅色。 + +## 登录页面 + +选择登录后显示的页面。选项包括： + +- 主页。 +- 上次访问的页面。 +- 你选择的特定集群。 + +## 显示设置 + +选择信息的显示方式： + +- 日期格式 +- 时间格式 +- 每页行数 +- 在侧边栏显示的集群数量 + +## 确认设置 + +_从 v2.7.2 起可用_ + +选择缩减节点池时是否要求确认。 + +## 高级功能 + +- 启用“在 API 中查看”。 +- 显示由 Rancher 管理的 system 命名空间（不要编辑或删除）。 +- 使用快捷键（shift+T）来切换深色/浅色主题。 +- 隐藏所有类型描述。 +- 启用扩展开发者功能。 + +![](/img/user-preferences-2-7.png) + +## YAML 编辑器 + +- 默认 +- Emacs +- Vim + +## Helm Chart + +选择仅显示已发布的 Helm Chart 还是同时包含预发布版本。如果版本符合 [Semantic Versioning 2.0.0](https://semver.org/) 定义的[规范](https://semver.org/#spec-item-9)，则那么该版本为预发布版本。例如，要显示版本为 `0.1.3-dev.12ab4f` 的 Helm chart，你需要先选择`包括预发布版本`。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/user-settings/user-settings.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/user-settings/user-settings.md new file mode 100644 index 00000000000..47ff9cb2518 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/user-settings/user-settings.md @@ -0,0 +1,19 @@ +--- +title: 用户设置 +--- + + + + + +在 Rancher 中，每个用户都有很多与登录相关的设置，例如个人偏好、API 密钥等。你可以从**用户设置**菜单中配置这些设置。你可以单击主菜单中的头像来打开此菜单。 + +![用户设置菜单](/img/user-settings.png) + +可用的用户设置包括： + +- [API & 密钥](api-keys.md)：如果你想以编程方式与 Rancher 交互，你需要一个 API 密钥。你可以按照本节中的说明获取密钥。 +- [云凭证](manage-cloud-credentials.md)：管理[节点模板](../../how-to-guides/new-user-guides/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/use-new-nodes-in-an-infra-provider.md#节点模板)使用的云凭证，从而[为集群配置节点](../../how-to-guides/new-user-guides/launch-kubernetes-with-rancher/launch-kubernetes-with-rancher.md)。 +- [节点模板](manage-node-templates.md)：管理 [Rancher 用来为集群配置节点](../../how-to-guides/new-user-guides/launch-kubernetes-with-rancher/launch-kubernetes-with-rancher.md)的模板。 +- [偏好设置](user-preferences.md)：设置 Rancher UI 的表面首选项。 +- 登出：结束你的用户会话。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/shared-files/_cluster-capabilities-table.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/shared-files/_cluster-capabilities-table.md new file mode 100644 index 00000000000..0fa7e839985 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/shared-files/_cluster-capabilities-table.md @@ -0,0 +1,22 @@ +| 操作 | Rancher 启动的 Kubernetes 集群 | EKS、GKE 和 AKS 集群1 | 其他托管的 Kubernetes 集群 | 非 EKS 或 GKE 注册集群 | +| --- | --- | ---| ---|----| +| [使用 kubectl 和 kubeconfig 文件来访问集群](../how-to-guides/new-user-guides/manage-clusters/access-clusters/use-kubectl-and-kubeconfig.md) | ✓ | ✓ | ✓ | ✓ | +| [管理集群成员](../how-to-guides/new-user-guides/manage-clusters/access-clusters/add-users-to-clusters.md) | ✓ | ✓ | ✓ | ✓ | +| [编辑和升级集群](../reference-guides/cluster-configuration/cluster-configuration.md) | ✓ | ✓ | ✓ | ✓2 | +| [管理节点](../how-to-guides/new-user-guides/manage-clusters/nodes-and-node-pools.md) | ✓ | ✓ | ✓ | ✓3 | +| [管理持久卷和存储类](../how-to-guides/new-user-guides/manage-clusters/create-kubernetes-persistent-storage/create-kubernetes-persistent-storage.md) | ✓ | ✓ | ✓ | ✓ | +| [管理项目、命名空间和工作负载](../how-to-guides/new-user-guides/manage-clusters/projects-and-namespaces.md) | ✓ | ✓ | ✓ | ✓ | +| [使用应用目录](../how-to-guides/new-user-guides/helm-charts-in-rancher/helm-charts-in-rancher.md) | ✓ | ✓ | ✓ | ✓ | +| 配置工具（[Alerts、Notifiers、Monitoring](../integrations-in-rancher/monitoring-and-alerting/monitoring-and-alerting.md)、[Logging](../integrations-in-rancher/logging/logging.md) 和 [Istio](../integrations-in-rancher/istio/istio.md)） | ✓ | ✓ | ✓ | ✓ | +| [运行安全扫描](../how-to-guides/advanced-user-guides/cis-scan-guides/cis-scan-guides.md) | ✓ | ✓ | ✓ | ✓ | +| [轮换证书](../how-to-guides/new-user-guides/manage-clusters/rotate-certificates.md) | ✓ | ✓ | | | +| [备份](../how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/back-up-rancher-launched-kubernetes-clusters.md)和[恢复](../how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/restore-rancher-launched-kubernetes-clusters-from-backup.md) Rancher 启动的集群 | ✓ | ✓ | | ✓4 | +| [在 Rancher 无法访问集群时清理 Kubernetes 组件](../how-to-guides/new-user-guides/manage-clusters/clean-cluster-nodes.md) | ✓ | | | | + +1. 注册的 EKS、GKE 和 AKS 集群与从 Rancher UI 创建的 EKS、GKE 和 AKS 集群的可用选项一致。不同之处是，从 Rancher UI 中删除已注册的集群后，集群不会被销毁。 + +2. 无法编辑已注册的集群的集群配置选项（[K3s 和 RKE2 集群](../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/register-existing-clusters.md)除外）。 + +3. Rancher UI 为已注册的集群节点提供了封锁、清空和编辑节点的功能。 + +4. 对于使用 etcd 作为 controlplane 的注册集群，必须在 Rancher UI 之外手动创建快照以用于备份和恢复。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/shared-files/_common-ports-table.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/shared-files/_common-ports-table.md new file mode 100644 index 00000000000..b37d40dc276 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/shared-files/_common-ports-table.md @@ -0,0 +1,19 @@ +| 协议 | 端口 | 描述 | +|:--------: |:----------------: |---------------------------------------------------------------------------------- | +| TCP | 22 | Node Driver SSH 配置 | +| TCP | 179 | Calico BGP 端口 | +| TCP | 2376 | Node Driver Docker daemon TLS 端口 | +| TCP | 2379 | etcd 客户端请求 | +| TCP | 2380 | etcd 对等通信 | +| UDP | 8472 | Canal/Flannel VXLAN 覆盖网络 | +| UDP | 4789 | Windows 集群中的 Flannel VXLAN 覆盖网络 | +| TCP | 8443 | Rancher webhook | +| TCP | 9099 | Canal/Flannel livenessProbe/readinessProbe | +| TCP | 9100 | Monitoring 从 Linux node-exporter 中抓取指标所需的默认端口 | +| TCP | 9443 | Rancher webhook | +| TCP | 9796 | Monitoring 从 Windows node-exporter 中抓取指标所需的默认端口 | +| TCP | 6783 | Weave 端口 | +| UDP | 6783-6784 | Weave UDP 端口 | +| TCP | 10250 | Metrics Server 与所有节点 API 的通信 | +| TCP | 10254 | Ingress controller livenessProbe/readinessProbe | +| TCP/UDP | 30000-32767 | NodePort 端口范围 | diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/troubleshooting/general-troubleshooting.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/troubleshooting/general-troubleshooting.md new file mode 100644 index 00000000000..1b3dca69bf8 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/troubleshooting/general-troubleshooting.md @@ -0,0 +1,44 @@ +--- +title: 一般故障排除 +--- + +本文用于帮助你解决使用 Rancher 时遇到的问题。 + +- [Kubernetes 组件](./kubernetes-components/kubernetes-components.md) + + 对以下核心 Kubernetes 集群组件进行故障排除： + * `etcd` + * `kube-apiserver` + * `kube-controller-manager` + * `kube-scheduler` + * `kubelet` + * `kube-proxy` + * `nginx-proxy` + +- [Kubernetes resources](other-troubleshooting-tips/kubernetes-resources.md) + + 本节介绍了对节点、Ingress Controller 和 Rancher Agent 等 Kubernetes 资源进行故障排除的选项。 + +- [网络](other-troubleshooting-tips/networking.md) + + 介绍了解决网络问题的步骤。 + +- [DNS](other-troubleshooting-tips/dns.md) + + 解决集群的名称解析问题。 + +- [对安装在 Kubernetes 上的 Rancher 进行故障排除](other-troubleshooting-tips/rancher-ha.md) + + 解决[安装在 Kubernetes 上的 Rancher Server](../getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/install-upgrade-on-a-kubernetes-cluster.md) 的问题。 + +- [Logging](other-troubleshooting-tips/logging.md) + + 了解可以配置哪些日志级别，以及如何配置日志级别。 + +- [审计日志中的用户 ID 跟踪](other-troubleshooting-tips/user-id-tracking-in-audit-logs.md) + + 了解 Rancher 管理员如何通过外部身份提供程序用户名从 Rancher 审计日志和 Kubernetes 审计日志中跟踪事件。 + +- [过期的 Webhook 证书](other-troubleshooting-tips/expired-webhook-certificate-rotation.md) + + 了解如何在每年到期后轮换 Rancher webhook 证书密钥。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/troubleshooting/kubernetes-components/kubernetes-components.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/troubleshooting/kubernetes-components/kubernetes-components.md new file mode 100644 index 00000000000..38bcba2810d --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/troubleshooting/kubernetes-components/kubernetes-components.md @@ -0,0 +1,21 @@ +--- +title: Kubernetes 组件 +--- + + + + + +本文列出的命令和步骤适用于 [Rancher 启动的 Kubernetes](../../how-to-guides/new-user-guides/launch-kubernetes-with-rancher/launch-kubernetes-with-rancher.md) 集群上的核心 Kubernetes 组件。 + +本文包括以下类别的故障排除提示： + +- [etcd 节点故障排除](troubleshooting-etcd-nodes.md) +- [Controlplane 节点故障排除](troubleshooting-controlplane-nodes.md) +- [nginx-proxy 节点故障排除](troubleshooting-nginx-proxy.md) +- [Worker 节点和通用组件故障排除](troubleshooting-worker-nodes-and-generic-components.md) + +## Kubernetes 组件图 + +![集群图](/img/clusterdiagram.svg)
+线条表示组件之间的通信。而颜色纯粹用于视觉辅助。 \ No newline at end of file diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/troubleshooting/kubernetes-components/troubleshooting-controlplane-nodes.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/troubleshooting/kubernetes-components/troubleshooting-controlplane-nodes.md new file mode 100644 index 00000000000..6c9a8d5291a --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/troubleshooting/kubernetes-components/troubleshooting-controlplane-nodes.md @@ -0,0 +1,51 @@ +--- +title: Controlplane 节点故障排除 +--- + +本文适用于具有 `controlplane` 角色的节点。 + +## 检查 controlplane 容器是否正在运行 + +具有 `controlplane` 角色的节点上启动了三个容器： + +* `kube-apiserver` +* `kube-controller-manager` +* `kube-scheduler` + +容器的状态应该是 **Up**。**Up** 后面显示的时间指的是容器运行的时间。 + +``` +docker ps -a -f=name='kube-apiserver|kube-controller-manager|kube-scheduler' +``` + +输出示例： +``` +CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES +26c7159abbcc rancher/hyperkube:v1.11.5-rancher1 "/opt/rke-tools/en..." 3 hours ago Up 3 hours kube-apiserver +f3d287ca4549 rancher/hyperkube:v1.11.5-rancher1 "/opt/rke-tools/en..." 3 hours ago Up 3 hours kube-scheduler +bdf3898b8063 rancher/hyperkube:v1.11.5-rancher1 "/opt/rke-tools/en..." 3 hours ago Up 3 hours kube-controller-manager +``` + +## controlplane 容器日志记录 + +:::note + +如果你添加了多个具有 `controlplane` 角色的节点，`kube-controller-manager` 和 `kube-scheduler` 会通过 leader 选举来确定 leader。只有当前 leader 会记录执行的操作。有关检索当前的 leader 的更多信息，请参阅 [Kubernetes leader 选举](../other-troubleshooting-tips/kubernetes-resources.md#kubernetes-leader-选举)。 + +::: + +容器的日志记录可能包含问题的信息。 + +``` +docker logs kube-apiserver +docker logs kube-controller-manager +docker logs kube-scheduler +``` + +## RKE2 Server 日志 + +如果 Rancher 配置的 RKE2 集群无法与 Rancher 通信，你可以在下游集群中的 Server 节点上运行此命令，从而获取 RKE2 Server 日志： + +``` +journalctl -u rke2-server -f +``` diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/troubleshooting/kubernetes-components/troubleshooting-etcd-nodes.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/troubleshooting/kubernetes-components/troubleshooting-etcd-nodes.md new file mode 100644 index 00000000000..d64215cebd2 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/troubleshooting/kubernetes-components/troubleshooting-etcd-nodes.md @@ -0,0 +1,283 @@ +--- +title: etcd 节点故障排除 +--- + + + + + +本文介绍了对具有 `etcd` 角色的节点进行故障排除的命令和提示。 + + +## 检查 etcd 容器是否正在运行 + +etcd 容器的状态应该是 **Up**。**Up** 后面显示的时间指的是容器运行的时间。 + +``` +docker ps -a -f=name=etcd$ +``` + +输出示例： +``` +CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES +d26adbd23643 rancher/mirrored-coreos-etcd:v3.5.7 "/usr/local/bin/etcd…" 30 minutes ago Up 30 minutes etcd +``` + +## etcd 容器日志记录 + +容器的日志记录可能包含问题的信息。 + +``` +docker logs etcd +``` +| 日志 | 解释 | +|-----|------------------| +| `health check for peer xxx could not connect: dial tcp IP:2380: getsockopt: connection refused` | 无法连接到端口 2380 上显示的地址。检查 etcd 容器是否在显示地址的主机上运行。 | +| `xxx is starting a new election at term x` | etcd 集群失去了集群仲裁数量，并正在尝试建立一个新的 leader。运行 etcd 的大多数节点关闭/无法访问时，可能会发生这种情况。 | +| `connection error: desc = "transport: Error while dialing dial tcp 0.0.0.0:2379: i/o timeout"; Reconnecting to {0.0.0.0:2379 0 }` | 主机防火墙正在阻止网络通信。 | +| `rafthttp: request cluster ID mismatch` | 具有 etcd 实例日志 `rafthttp: request cluster ID mismatch` 的节点正在尝试加入已经添加另一个对等节点（peer）的集群。你需要从集群中删除该节点，然后再重新添加。 | +| `rafthttp: failed to find member` | 集群状态（`/var/lib/etcd`）包含加入集群的错误信息。你需要从集群中删除该节点，清理状态目录，然后再重新添加。 | + +## etcd 集群和连接检查 + +运行 etcd 的主机的地址配置决定了 etcd 监听的地址。如果为运行 etcd 的主机配置了内部地址，则需要显式指定 `etcdctl` 的端点。如果任何命令的响应是 `Error: context deadline exceeded`，则 etcd 实例不健康（仲裁丢失或实例未正确加入集群）。 + +### 检查所有节点上的 etcd 成员 + +输出应包含具有 `etcd` 角色的所有节点，而且所有节点上的输出应该是相同的。 + +命令： +``` +docker exec etcd etcdctl member list +``` + +### 检查端点状态 + +`RAFT TERM` 的值应该是相等的，而且 `RAFT INDEX` 相差不能太大。 + +命令： +``` +docker exec -e ETCDCTL_ENDPOINTS=$(docker exec etcd etcdctl member list | cut -d, -f5 | sed -e 's/ //g' | paste -sd ',') etcd etcdctl endpoint status --write-out table +``` + +输出示例： +``` ++-----------------+------------------+---------+---------+-----------+-----------+------------+ +| ENDPOINT | ID | VERSION | DB SIZE | IS LEADER | RAFT TERM | RAFT INDEX | ++-----------------+------------------+---------+---------+-----------+-----------+------------+ +| https://IP:2379 | 333ef673fc4add56 | 3.5.7 | 24 MB | false | 72 | 66887 | +| https://IP:2379 | 5feed52d940ce4cf | 3.5.7 | 24 MB | true | 72 | 66887 | +| https://IP:2379 | db6b3bdb559a848d | 3.5.7 | 25 MB | false | 72 | 66887 | ++-----------------+------------------+---------+---------+-----------+-----------+------------+ +``` + +### 检查端点健康 + +命令： +``` +docker exec -e ETCDCTL_ENDPOINTS=$(docker exec etcd etcdctl member list | cut -d, -f5 | sed -e 's/ //g' | paste -sd ',') etcd etcdctl endpoint health +``` + +输出示例： +``` +https://IP:2379 is healthy: successfully committed proposal: took = 2.113189ms +https://IP:2379 is healthy: successfully committed proposal: took = 2.649963ms +https://IP:2379 is healthy: successfully committed proposal: took = 2.451201ms +``` + +### 检查端口 TCP/2379 上的连接 + +命令： +``` +for endpoint in $(docker exec etcd etcdctl member list | cut -d, -f5); do + echo "Validating connection to ${endpoint}/health" + docker run --net=host -v $(docker inspect kubelet --format '{{ range .Mounts }}{{ if eq .Destination "/etc/kubernetes" }}{{ .Source }}{{ end }}{{ end }}')/ssl:/etc/kubernetes/ssl:ro appropriate/curl -s -w "\n" --cacert $(docker inspect -f '{{range $index, $value := .Config.Env}}{{if eq (index (split $value "=") 0) "ETCDCTL_CACERT" }}{{range $i, $part := (split $value "=")}}{{if gt $i 1}}{{print "="}}{{end}}{{if gt $i 0}}{{print $part}}{{end}}{{end}}{{end}}{{end}}' etcd) --cert $(docker inspect -f '{{range $index, $value := .Config.Env}}{{if eq (index (split $value "=") 0) "ETCDCTL_CERT" }}{{range $i, $part := (split $value "=")}}{{if gt $i 1}}{{print "="}}{{end}}{{if gt $i 0}}{{print $part}}{{end}}{{end}}{{end}}{{end}}' etcd) --key $(docker inspect -f '{{range $index, $value := .Config.Env}}{{if eq (index (split $value "=") 0) "ETCDCTL_KEY" }}{{range $i, $part := (split $value "=")}}{{if gt $i 1}}{{print "="}}{{end}}{{if gt $i 0}}{{print $part}}{{end}}{{end}}{{end}}{{end}}' etcd) "${endpoint}/health" +done +``` + +输出示例： +``` +Validating connection to https://IP:2379/health +{"health": "true"} +Validating connection to https://IP:2379/health +{"health": "true"} +Validating connection to https://IP:2379/health +{"health": "true"} +``` + +### 检查端口 TCP/2380 上的连接 + +命令： +``` +for endpoint in $(docker exec etcd etcdctl member list | cut -d, -f4); do + echo "Validating connection to ${endpoint}/version"; + docker run --net=host -v $(docker inspect kubelet --format '{{ range .Mounts }}{{ if eq .Destination "/etc/kubernetes" }}{{ .Source }}{{ end }}{{ end }}')/ssl:/etc/kubernetes/ssl:ro appropriate/curl --http1.1 -s -w "\n" --cacert $(docker inspect -f '{{range $index, $value := .Config.Env}}{{if eq (index (split $value "=") 0) "ETCDCTL_CACERT" }}{{range $i, $part := (split $value "=")}}{{if gt $i 1}}{{print "="}}{{end}}{{if gt $i 0}}{{print $part}}{{end}}{{end}}{{end}}{{end}}' etcd) --cert $(docker inspect -f '{{range $index, $value := .Config.Env}}{{if eq (index (split $value "=") 0) "ETCDCTL_CERT" }}{{range $i, $part := (split $value "=")}}{{if gt $i 1}}{{print "="}}{{end}}{{if gt $i 0}}{{print $part}}{{end}}{{end}}{{end}}{{end}}' etcd) --key $(docker inspect -f '{{range $index, $value := .Config.Env}}{{if eq (index (split $value "=") 0) "ETCDCTL_KEY" }}{{range $i, $part := (split $value "=")}}{{if gt $i 1}}{{print "="}}{{end}}{{if gt $i 0}}{{print $part}}{{end}}{{end}}{{end}}{{end}}' etcd) "${endpoint}/version" +done +``` + +输出示例： +``` +Validating connection to https://IP:2380/version +{"etcdserver":"3.5.7","etcdcluster":"3.5.0"} +Validating connection to https://IP:2380/version +{"etcdserver":"3.5.7","etcdcluster":"3.5.0"} +Validating connection to https://IP:2380/version +{"etcdserver":"3.5.7","etcdcluster":"3.5.0"} +``` + +## etcd 告警 + +etcd 会触发告警（例如空间不足时）。 + +命令： +``` +docker exec etcd etcdctl alarm list +``` + +触发 NOSPACE 告警的输出示例： +``` +memberID:x alarm:NOSPACE +memberID:x alarm:NOSPACE +memberID:x alarm:NOSPACE +``` + +## etcd 空间错误 + +相关的错误消息是 `etcdserver: mvcc: database space exceeded` 或 `applying raft message exceeded backend quota`。告警 `NOSPACE` 会被触发。 + +解决： + +- [压缩键空间](#压缩键空间) +- [对所有 etcd 成员进行碎片整理](#对所有-etcd-成员进行碎片整理) +- [检查端点状态](#检查端点状态) +- [解除告警](#解除告警) + +### 压缩键空间 + +命令： +``` +rev=$(docker exec etcd etcdctl endpoint status --write-out json | egrep -o '"revision":[0-9]*' | egrep -o '[0-9]*') +docker exec etcd etcdctl compact "$rev" +``` + +输出示例： +``` +compacted revision xxx +``` + +### 对所有 etcd 成员进行碎片整理 + +命令： +``` +docker exec -e ETCDCTL_ENDPOINTS=$(docker exec etcd etcdctl member list | cut -d, -f5 | sed -e 's/ //g' | paste -sd ',') etcd etcdctl defrag +``` + +输出示例： +``` +Finished defragmenting etcd member[https://IP:2379] +Finished defragmenting etcd member[https://IP:2379] +Finished defragmenting etcd member[https://IP:2379] +``` + +### 检查端点状态 + +命令： +``` +docker exec -e ETCDCTL_ENDPOINTS=$(docker exec etcd etcdctl member list | cut -d, -f5 | sed -e 's/ //g' | paste -sd ',') etcd etcdctl endpoint status --write-out table +``` + +输出示例： +``` ++-----------------+------------------+---------+---------+-----------+-----------+------------+ +| ENDPOINT | ID | VERSION | DB SIZE | IS LEADER | RAFT TERM | RAFT INDEX | ++-----------------+------------------+---------+---------+-----------+-----------+------------+ +| https://IP:2379 | e973e4419737125 | 3.5.7 | 553 kB | false | 32 | 2449410 | +| https://IP:2379 | 4a509c997b26c206 | 3.5.7 | 553 kB | false | 32 | 2449410 | +| https://IP:2379 | b217e736575e9dd3 | 3.5.7 | 553 kB | true | 32 | 2449410 | ++-----------------+------------------+---------+---------+-----------+-----------+------------+ +``` + +### 解除告警 + +如果压缩和整理碎片后确定数据库大小下降了，则需要解除告警来允许 etcd 再次写入。 + +命令： +``` +docker exec etcd etcdctl alarm list +docker exec etcd etcdctl alarm disarm +docker exec etcd etcdctl alarm list +``` + +输出示例： +``` +docker exec etcd etcdctl alarm list +memberID:x alarm:NOSPACE +memberID:x alarm:NOSPACE +memberID:x alarm:NOSPACE +docker exec etcd etcdctl alarm disarm +docker exec etcd etcdctl alarm list +``` + +## 配置日志级别 + +:::note + +你无法再动态更改 etcd v3.5 或更高版本中的日志级别。 + +::: + +### etcd v3.5 及更高版本 + +要配置 etcd 的日志级别，请编辑集群 YAML： + +``` +services: + etcd: + extra_args: + log-level: "debug" +``` + +### etcd v3.4 及更早版本 + +在早期的 etcd 版本中，你可以使用 API 动态更改日志级别。使用以下命令来配置调试日志： + +``` +docker run --net=host -v $(docker inspect kubelet --format '{{ range .Mounts }}{{ if eq .Destination "/etc/kubernetes" }}{{ .Source }}{{ end }}{{ end }}')/ssl:/etc/kubernetes/ssl:ro appropriate/curl -s -XPUT -d '{"Level":"DEBUG"}' --cacert $(docker exec etcd printenv ETCDCTL_CACERT) --cert $(docker exec etcd printenv ETCDCTL_CERT) --key $(docker exec etcd printenv ETCDCTL_KEY) $(docker exec etcd printenv ETCDCTL_ENDPOINTS)/config/local/log +``` + +要将日志级别重置回默认值 (`INFO`)，你可以使用以下命令。 + +命令： +``` +docker run --net=host -v $(docker inspect kubelet --format '{{ range .Mounts }}{{ if eq .Destination "/etc/kubernetes" }}{{ .Source }}{{ end }}{{ end }}')/ssl:/etc/kubernetes/ssl:ro appropriate/curl -s -XPUT -d '{"Level":"INFO"}' --cacert $(docker exec etcd printenv ETCDCTL_CACERT) --cert $(docker exec etcd printenv ETCDCTL_CERT) --key $(docker exec etcd printenv ETCDCTL_KEY) $(docker exec etcd printenv ETCDCTL_ENDPOINTS)/config/local/log +``` + +## etcd 内容 + +如果要查看 etcd 的内容，你可以查看流事件，也可以直接查询 etcd。详情请参阅以下示例。 + +### 查看流事件 + +命令： +``` +docker exec etcd etcdctl watch --prefix /registry +``` + +如果你只想查看受影响的键（而不是二进制数据），你可以将 `| grep -a ^/registry` 尾附到该命令来过滤键。 + +### 直接查询 etcd + +命令： +``` +docker exec etcd etcdctl get /registry --prefix=true --keys-only +``` + +你可以使用以下命令来处理数据，从而获取每个键的计数摘要： + +``` +docker exec etcd etcdctl get /registry --prefix=true --keys-only | grep -v ^$ | awk -F'/' '{ if ($3 ~ /cattle.io/) {h[$3"/"$4]++} else { h[$3]++ }} END { for(k in h) print h[k], k }' | sort -nr +``` + +## 更换不健康的 etcd 节点 + +如果你 etcd 集群中的某个节点变得不健康，在将新的 etcd 节点添加到集群之前，我们建议你修复或删除故障/不健康的节点。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/troubleshooting/kubernetes-components/troubleshooting-nginx-proxy.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/troubleshooting/kubernetes-components/troubleshooting-nginx-proxy.md new file mode 100644 index 00000000000..c2ee756591f --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/troubleshooting/kubernetes-components/troubleshooting-nginx-proxy.md @@ -0,0 +1,68 @@ +--- +title: nginx-proxy 故障排除 +--- + +每个没有 `controlplane` 角色的节点上都部署了 `nginx-proxy` 容器。`nginx-proxy` 基于具有 `controlplane` 角色的可用节点来动态生成 NGINX 配置，从而提供对这些 `controlplane` 角色节点的访问。 + +## 检查容器是否正在运行 + +该容器称为 `nginx-proxy`，它的状态应该是 `Up`。`Up` 后面显示的时间指的是容器运行的时间。 + +``` +docker ps -a -f=name=nginx-proxy +``` + +输出示例： + +``` +docker ps -a -f=name=nginx-proxy +CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES +c3e933687c0e rancher/rke-tools:v0.1.15 "nginx-proxy CP_HO..." 3 hours ago Up 3 hours nginx-proxy +``` + +## 检查生成的 NGINX 配置 + +生成的配置包括了具有 `controlplane` 角色的节点的 IP 地址。你可以使用以下命令来检查配置： + +``` +docker exec nginx-proxy cat /etc/nginx/nginx.conf +``` + +输出示例： +``` +error_log stderr notice; + +worker_processes auto; +events { + multi_accept on; + use epoll; + worker_connections 1024; +} + +stream { + upstream kube_apiserver { + + server ip_of_controlplane_node1:6443; + + server ip_of_controlplane_node2:6443; + + } + + server { + listen 6443; + proxy_pass kube_apiserver; + proxy_timeout 30; + proxy_connect_timeout 2s; + + } + +} +``` + +## nginx-proxy 容器日志记录 + +容器的日志记录可能包含问题的信息。 + +``` +docker logs nginx-proxy +``` diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/troubleshooting/kubernetes-components/troubleshooting-worker-nodes-and-generic-components.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/troubleshooting/kubernetes-components/troubleshooting-worker-nodes-and-generic-components.md new file mode 100644 index 00000000000..ae6b283c056 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/troubleshooting/kubernetes-components/troubleshooting-worker-nodes-and-generic-components.md @@ -0,0 +1,34 @@ +--- +title: Worker 节点和通用组件故障排除 +--- + +本文包括了运行在所有角色节点上的组件，因此适用于每个节点。 + +## 检查容器是否正在运行 + +具有 `worker` 角色的节点上启动了两个容器： + +* kubelet +* kube-proxy + +容器的状态应该是 `Up`。`Up` 后面显示的时间指的是容器运行的时间。 + +``` +docker ps -a -f=name='kubelet|kube-proxy' +``` + +输出示例： +``` +CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES +158d0dcc33a5 rancher/hyperkube:v1.11.5-rancher1 "/opt/rke-tools/en..." 3 hours ago Up 3 hours kube-proxy +a30717ecfb55 rancher/hyperkube:v1.11.5-rancher1 "/opt/rke-tools/en..." 3 hours ago Up 3 hours kubelet +``` + +## 容器日志记录 + +容器的日志记录可能包含问题的信息。 + +``` +docker logs kubelet +docker logs kube-proxy +``` diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/troubleshooting/other-troubleshooting-tips/dns.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/troubleshooting/other-troubleshooting-tips/dns.md new file mode 100644 index 00000000000..4bb0482942f --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/troubleshooting/other-troubleshooting-tips/dns.md @@ -0,0 +1,220 @@ +--- +title: DNS +--- + +本文列出的命令/步骤可用于检查集群中的名称解析问题。 + +请确保你配置了正确的 kubeconfig（例如，为 Rancher HA 配置了 `export KUBECONFIG=$PWD/kube_config_cluster.yml`）或通过 UI 使用了嵌入式 kubectl。 + +在运行 DNS 检查之前，请检查集群的[默认 DNS 提供商](../../reference-guides/cluster-configuration/rancher-server-configuration/rke1-cluster-configuration.md#默认-dns-提供商)，并确保[覆盖网络正常运行](networking.md#检查覆盖网络是否正常运行)，因为这也可能导致 DNS 解析（部分）失败。 + +## 检查 DNS pod 是否正在运行 + +``` +kubectl -n kube-system get pods -l k8s-app=kube-dns +``` + +使用 CoreDNS 时的示例输出： +``` +NAME READY STATUS RESTARTS AGE +coredns-799dffd9c4-6jhlz 1/1 Running 0 76m +``` + +使用 kube-dns 时的示例输出： +``` +NAME READY STATUS RESTARTS AGE +kube-dns-5fd74c7488-h6f7n 3/3 Running 0 4m13s +``` + +## 检查 DNS 服务是否显示正确的 cluster-ip + +``` +kubectl -n kube-system get svc -l k8s-app=kube-dns +``` + +``` +NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE +service/kube-dns ClusterIP 10.43.0.10 53/UDP,53/TCP 4m13s +``` + +## 检查是否正在解析域名 + +检查是否正在解析内部集群名称（在本例中为 `kubernetes.default`），`Server:` 后面显示的 IP 应与 `kube-dns` 服务的 `CLUSTER-IP` 一致。 + +``` +kubectl run -it --rm --restart=Never busybox --image=busybox:1.28 -- nslookup kubernetes.default +``` + +输出示例： +``` +Server: 10.43.0.10 +Address 1: 10.43.0.10 kube-dns.kube-system.svc.cluster.local + +Name: kubernetes.default +Address 1: 10.43.0.1 kubernetes.default.svc.cluster.local +pod "busybox" deleted +``` + +检查是否正在解析外部名称（在本例中为 `www.google.com`）： + +``` +kubectl run -it --rm --restart=Never busybox --image=busybox:1.28 -- nslookup www.google.com +``` + +输出示例： +``` +Server: 10.43.0.10 +Address 1: 10.43.0.10 kube-dns.kube-system.svc.cluster.local + +Name: www.google.com +Address 1: 2a00:1450:4009:80b::2004 lhr35s04-in-x04.1e100.net +Address 2: 216.58.211.100 ams15s32-in-f4.1e100.net +pod "busybox" deleted +``` + +如果要检查所有主机的域名解析，请执行以下步骤： + +1. 将以下文件另存为 `ds-dnstest.yml`： + + ``` + apiVersion: apps/v1 + kind: DaemonSet + metadata: + name: dnstest + spec: + selector: + matchLabels: + name: dnstest + template: + metadata: + labels: + name: dnstest + spec: + tolerations: + - operator: Exists + containers: + - image: busybox:1.28 + imagePullPolicy: Always + name: alpine + command: ["sleep", "infinity"] + terminationMessagePath: /dev/termination-log + ``` + +2. 通过运行 `kubectl create -f ds-dnstest.yml` 启动它。 +3. 等待 `kubectl rollout status ds/dnstest -w` 返回 `daemon set "dnstest" successfully rolled out`。 +4. 将环境变量 `DOMAIN` 配置为主机能够解析的完全限定域名（Fully Qualified Domain Name，FQDN），例如 `www.google.com`，并运行以下命令让每个主机上的各个容器解析配置的域名（它是单行命令）： + + ``` + export DOMAIN=www.google.com; echo "=> Start DNS resolve test"; kubectl get pods -l name=dnstest --no-headers -o custom-columns=NAME:.metadata.name,HOSTIP:.status.hostIP | while read pod host; do kubectl exec $pod -- /bin/sh -c "nslookup $DOMAIN > /dev/null 2>&1"; RC=$?; if [ $RC -ne 0 ]; then echo $host cannot resolve $DOMAIN; fi; done; echo "=> End DNS resolve test" + ``` + +5. 完成此命令后，如果一切正确，则输出如下： + + ``` + => Start DNS resolve test + => End DNS resolve test + ``` + +如果你在输出中看到错误，则表示主机无法解析给定的 FQDN。 + +在以下错误输出示例中，IP 为 209.97.182.150 的主机阻止了 UDP 端口： + +``` +=> Start DNS resolve test +command terminated with exit code 1 +209.97.182.150 cannot resolve www.google.com +=> End DNS resolve test +``` + +运行 `kubectl delete ds/dnstest` 清理 alpine DaemonSet。 + +## CoreDNS 相关 + +### 检查 CoreDNS 日志记录 + +``` +kubectl -n kube-system logs -l k8s-app=kube-dns +``` + +### 检查配置 + +CoreDNS 配置存储在 `kube-system` 命名空间中 configmap 的 `coredns` 中。 + +``` +kubectl -n kube-system get configmap coredns -o go-template={{.data.Corefile}} +``` + +### 检查 resolv.conf 中的上游名称服务器 + +默认情况下，配置在主机（在 `/etc/resolv.conf` 里）上的名称服务器会用作 CoreDNS 的上游名称服务器。你可以在主机上检查此文件，或将 `dnsPolicy` 设置为 `Default`（将继承其主机的 `/etc/resolv.conf`）并运行以下 Pod： + +``` +kubectl run -i --restart=Never --rm test-${RANDOM} --image=ubuntu --overrides='{"kind":"Pod", "apiVersion":"v1", "spec": {"dnsPolicy":"Default"}}' -- sh -c 'cat /etc/resolv.conf' +``` + +### 启用日志查询 + +你可以通过在 configmap `coredns` 的 Corefile 配置中启用 [log plugin](https://coredns.io/plugins/log/) 来启用日志查询。为此，你可以使用 `kubectl -n kube-system edit configmap coredns`，或运行以下命令来替换配置： + +``` +kubectl get configmap -n kube-system coredns -o json | sed -e 's_loadbalance_log\\n loadbalance_g' | kubectl apply -f - +``` + +这样，所有查询都会记入日志，并且可以使用[检查 CoreDNS 日志记录](#检查-coredns-日志记录)中的命令进行检查。 + +## kube-dns 相关 + +### 检查 kubedns 容器中的上游名称服务器 + +默认情况下，配置在主机（在 `/etc/resolv.conf` 里）上的名称服务器会用作 kube-dns 的上游名称服务器。有时，主机会运行本地缓存 DNS 名称服务器，这意味着 `/etc/resolv.conf` 中的地址将指向 Loopback 范围（`127.0.0.0/8`）内的地址，而容器将无法访问该范围。对于 Ubuntu 18.04，这是由 `systemd-resolved` 进行的。我们会检测 `systemd-resolved` 是否正在运行，并自动使用具有正确上游名称服务器的 `/etc/resolv.conf` 文件（位于 `/run /systemd/resolve/resolv.conf`）。 + +使用以下命令检查 kubedns 容器使用的上游名称服务器： + +``` +kubectl -n kube-system get pods -l k8s-app=kube-dns --no-headers -o custom-columns=NAME:.metadata.name,HOSTIP:.status.hostIP | while read pod host; do echo "Pod ${pod} on host ${host}"; kubectl -n kube-system exec $pod -c kubedns cat /etc/resolv.conf; done +``` + +输出示例： +``` +Pod kube-dns-667c7cb9dd-z4dsf on host x.x.x.x +nameserver 1.1.1.1 +nameserver 8.8.4.4 +``` + +如果输出显示 Loopback 范围（`127.0.0.0/8`）内的地址 ，你可以通过以下两种方式解决此问题： + +* 确保在集群节点上的 `/etc/resolv.conf` 列出了正确的名称服务器。如果需要了解如何进行操作，请参阅你的操作系统文档。请确保你在配置集群之前执行此操作，或在修改后重启节点。 +* 通过配置 `kubelet` 来使用不同的文件进行名称解析，你可以使用如下的 `extra_args`（其中 `/run/resolvconf/resolv.conf` 是具有正确名称服务器的文件）： + +``` +services: + kubelet: + extra_args: + resolv-conf: "/run/resolvconf/resolv.conf" +``` + +:::note + +由于 `kubelet` 在容器内运行，因此 `/etc` 和 `/usr` 中文件的路径位于 `kubelet` 容器内的 `/host/etc` 和 `/host/usr` 中。 + +::: + +请参阅[使用 YAML 编辑集群](../../reference-guides/cluster-configuration/rancher-server-configuration/rke1-cluster-configuration.md#使用-yaml-编辑集群)了解如何应用此修改。集群配置完成后，你必须删除 kube-dns pod 以激活 pod 中的新设置： + +``` +kubectl delete pods -n kube-system -l k8s-app=kube-dns +pod "kube-dns-5fd74c7488-6pwsf" deleted +``` + +你可以[检查是否正在解析域名](#检查是否正在解析域名)来尝试再次解析名称。 + +如果要检查集群中的 kube-dns 配置（例如，检查是否配置了不同的上游名称服务器），你可以运行以下命令来列出 kube-dns 配置： + +``` +kubectl -n kube-system get configmap kube-dns -o go-template='{{range $key, $value := .data}}{{ $key }}{{":"}}{{ $value }}{{"\n"}}{{end}}' +``` + +输出示例： +``` +upstreamNameservers:["1.1.1.1"] +``` diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/troubleshooting/other-troubleshooting-tips/expired-webhook-certificate-rotation.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/troubleshooting/other-troubleshooting-tips/expired-webhook-certificate-rotation.md new file mode 100644 index 00000000000..c2d717c61ce --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/troubleshooting/other-troubleshooting-tips/expired-webhook-certificate-rotation.md @@ -0,0 +1,28 @@ +--- +title: 过期 Webhook 证书轮换 +--- + +如果你的 Rancher 版本安装了 `rancher-webhook`，某些版本创建的证书将在一年后过期。如果证书未续订，你需要轮换你的 webhook 证书。 + +在 Rancher v2.6.3 及更高版本中，rancher-webhook deployments 将在到期日期后 30 天或更短的时间内自动更新其 TLS 证书。如果你使用的是 v2.6.2 或更低版本，你可以通过下面两种方法来解决这个问题。 + +## 1. 如果用户具有集群访问权限，运行以下命令： +``` +kubectl delete secret -n cattle-system cattle-webhook-tls +kubectl delete mutatingwebhookconfigurations.admissionregistration.k8s.io --ignore-not-found=true rancher.cattle.io +kubectl delete pod -n cattle-system -l app=rancher-webhook +``` + +## 2. 如果用户没有集群访问权限，使用 `kubectl`： + +1. 删除 local 集群 `cattle-system` 命名空间中的 `cattle-webhook-tls` 密文。 + +2. 删除 `rancher.cattle.io` mutating webhook。 + +3. 删除 local 集群 `cattle-system` 命名空间中的 `rancher-webhook` pod。 + +:::note + +webhook 证书过期问题不止示例中列出的 `cattle-webhook-tls`。你需要相应地填写你过期的证书密文。 + +::: \ No newline at end of file diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/troubleshooting/other-troubleshooting-tips/kubernetes-resources.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/troubleshooting/other-troubleshooting-tips/kubernetes-resources.md new file mode 100644 index 00000000000..6fee94b2cb4 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/troubleshooting/other-troubleshooting-tips/kubernetes-resources.md @@ -0,0 +1,255 @@ +--- +title: Kubernetes 资源 +--- + +本文列出的命令/步骤可用于检查最重要的 Kubernetes 资源，并应用于 [Rancher 启动的 Kubernetes](../../how-to-guides/new-user-guides/launch-kubernetes-with-rancher/launch-kubernetes-with-rancher.md) 集群。 + +请确保你配置了正确的 kubeconfig（例如，为 Rancher HA 配置了 `export KUBECONFIG=$PWD/kube_config_cluster.yml`）或通过 UI 使用了嵌入式 kubectl。 + + +## 节点 + +### 获取节点 + +运行以下命令并检查以下内容： + +- 集群中的所有节点都已列出，没有缺失的节点。 +- 所有节点的状态都是 **Ready**（如果未处于 **Ready** 状态，请运行 `docker logs kubelet` 检查该节点上的 `kubelet` 容器日志) +- 检查所有节点是否报告了正确的版本。 +- 检查 OS/Kernel/Docker 值是否按预期显示（此问题可能与升级 OS/Kernel/Docker 相关）。 + + +``` +kubectl get nodes -o wide +``` + +输出示例： + +``` +NAME STATUS ROLES AGE VERSION INTERNAL-IP EXTERNAL-IP OS-IMAGE KERNEL-VERSION CONTAINER-RUNTIME +controlplane-0 Ready controlplane 31m v1.13.5 138.68.188.91 Ubuntu 18.04.2 LTS 4.15.0-47-generic docker://18.9.5 +etcd-0 Ready etcd 31m v1.13.5 138.68.180.33 Ubuntu 18.04.2 LTS 4.15.0-47-generic docker://18.9.5 +worker-0 Ready worker 30m v1.13.5 139.59.179.88 Ubuntu 18.04.2 LTS 4.15.0-47-generic docker://18.9.5 +``` + +### 获取节点状况 + +运行以下命令列出具有 [Node Conditions](https://kubernetes.io/docs/concepts/architecture/nodes/#condition) 的节点： + +``` +kubectl get nodes -o go-template='{{range .items}}{{$node := .}}{{range .status.conditions}}{{$node.metadata.name}}{{": "}}{{.type}}{{":"}}{{.status}}{{"\n"}}{{end}}{{end}}' +``` + +运行以下命令，列出具有 active [Node Conditions](https://kubernetes.io/docs/concepts/architecture/nodes/#condition) 的节点，这些节点可能阻止正常操作： + +``` +kubectl get nodes -o go-template='{{range .items}}{{$node := .}}{{range .status.conditions}}{{if ne .type "Ready"}}{{if eq .status "True"}}{{$node.metadata.name}}{{": "}}{{.type}}{{":"}}{{.status}}{{"\n"}}{{end}}{{else}}{{if ne .status "True"}}{{$node.metadata.name}}{{": "}}{{.type}}{{": "}}{{.status}}{{"\n"}}{{end}}{{end}}{{end}}{{end}}' +``` + +输出示例： + +``` +worker-0: DiskPressure:True +``` + +## Kubernetes leader 选举 + +### Kubernetes Controller 管理器 leader + +Leader 由 Leader 选举确定。确定 Leader 后，Leader（`holderIdentity`）会保存在 `kube-controller-manager` 端点中（在本例中为 `controlplane-0`）。 + +``` +kubectl -n kube-system get endpoints kube-controller-manager -o jsonpath='{.metadata.annotations.control-plane\.alpha\.kubernetes\.io/leader}' +{"holderIdentity":"controlplane-0_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx","leaseDurationSeconds":15,"acquireTime":"2018-12-27T08:59:45Z","renewTime":"2018-12-27T09:44:57Z","leaderTransitions":0}> +``` + +### Kubernetes 调度器 Leader + +Leader 由 Leader 选举确定。确定 Leader 后，Leader（`holderIdentity`）会保存在 `kube-scheduler` 端点中（在本例中为 `controlplane-0`）。 + +``` +kubectl -n kube-system get endpoints kube-scheduler -o jsonpath='{.metadata.annotations.control-plane\.alpha\.kubernetes\.io/leader}' +{"holderIdentity":"controlplane-0_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx","leaseDurationSeconds":15,"acquireTime":"2018-12-27T08:59:45Z","renewTime":"2018-12-27T09:44:57Z","leaderTransitions":0}> +``` + +## Ingress Controller + +默认的 Ingress Controller 是 NGINX，作为 DaemonSet 部署在 `ingress-nginx` 命名空间中。Pod 仅会调度到具有 `worker` 角色的节点。 + +检查 pod 是否运行在所有节点上： + +``` +kubectl -n ingress-nginx get pods -o wide +``` + +输出示例： + +``` +kubectl -n ingress-nginx get pods -o wide +NAME READY STATUS RESTARTS AGE IP NODE +default-http-backend-797c5bc547-kwwlq 1/1 Running 0 17m x.x.x.x worker-1 +nginx-ingress-controller-4qd64 1/1 Running 0 14m x.x.x.x worker-1 +nginx-ingress-controller-8wxhm 1/1 Running 0 13m x.x.x.x worker-0 +``` + +如果 pod 无法运行（即状态不是 **Running**，Ready 状态未显示 `1/1`，或者有大量 Restarts），请检查 pod 详细信息，日志和命名空间事件。 + +### Pod 详细信息 + +``` +kubectl -n ingress-nginx describe pods -l app=ingress-nginx +``` + +### Pod 容器日志 + +下面的命令可以显示所有标记为 “app=ingress-nginx” 的 pod 的日志，但是由于 `kubectl logs` 命令的限制，它只会显示 10 行日志。有关详细信息，请参阅 `kubectl logs -h` 的 `--tail`。 + +``` +kubectl -n ingress-nginx logs -l app=ingress-nginx +``` + +如果需要查看完整的日志，请在命令中尾随 pod 名称： + +``` +kubectl -n ingress-nginx logs +``` + +### 命名空间事件 + +``` +kubectl -n ingress-nginx get events +``` + +### 调试日志 + +要启用调试日志： + +``` +kubectl -n ingress-nginx patch ds nginx-ingress-controller --type='json' -p='[{"op": "add", "path": "/spec/template/spec/containers/0/args/-", "value": "--v=5"}]' +``` + +### 检查配置 + +在每个 pod 中检索生成的配置： + +``` +kubectl -n ingress-nginx get pods -l app=ingress-nginx --no-headers -o custom-columns=.NAME:.metadata.name | while read pod; do kubectl -n ingress-nginx exec $pod -- cat /etc/nginx/nginx.conf; done +``` + +## Rancher Agents + +Rancher Agent 用于实现与集群的通信（通过 `cattle-cluster-agent` 的 Kubernetes API）和与节点的通信（通过 `cattle-node-agent` 的集群配置）。 + +#### cattle-node-agent + +检查每个节点上是否存在 cattle-node-agent pod，状态是否为 **Running**，并且重启次数不多： + +``` +kubectl -n cattle-system get pods -l app=cattle-agent -o wide +``` + +输出示例： + +``` +NAME READY STATUS RESTARTS AGE IP NODE +cattle-node-agent-4gc2p 1/1 Running 0 2h x.x.x.x worker-1 +cattle-node-agent-8cxkk 1/1 Running 0 2h x.x.x.x etcd-1 +cattle-node-agent-kzrlg 1/1 Running 0 2h x.x.x.x etcd-0 +cattle-node-agent-nclz9 1/1 Running 0 2h x.x.x.x controlplane-0 +cattle-node-agent-pwxp7 1/1 Running 0 2h x.x.x.x worker-0 +cattle-node-agent-t5484 1/1 Running 0 2h x.x.x.x controlplane-1 +cattle-node-agent-t8mtz 1/1 Running 0 2h x.x.x.x etcd-2 +``` + +检查特定或所有 cattle-node-agent pod 的日志记录： + +``` +kubectl -n cattle-system logs -l app=cattle-agent +``` + +#### cattle-cluster-agent + +检查 cattle-cluster-agent pod 是否存在于集群中，状态是否为 **Running**，并且重启次数不多： + +``` +kubectl -n cattle-system get pods -l app=cattle-cluster-agent -o wide +``` + +输出示例： + +``` +NAME READY STATUS RESTARTS AGE IP NODE +cattle-cluster-agent-54d7c6c54d-ht9h4 1/1 Running 0 2h x.x.x.x worker-1 +``` + +检查 cattle-cluster-agent pod 的日志记录： + +``` +kubectl -n cattle-system logs -l app=cattle-cluster-agent +``` + +## Jobs 和 Pods + +### 检查 Pod 或 Job 的状态是否为 **Running**/**Completed** + +运行以下命令进行检查： + +``` +kubectl get pods --all-namespaces +``` + +如果 Pod 的状态不是 **Running**，你可以通过运行命令来找到根本原因。 + +### 描述 Pod + +``` +kubectl describe pod POD_NAME -n NAMESPACE +``` + +### Pod 容器日志 + +``` +kubectl logs POD_NAME -n NAMESPACE +``` + +如果 Job 的状态不是 **Completed**，你可以通过运行命令来找到根本原因。 + +### 描述 Job + +``` +kubectl describe job JOB_NAME -n NAMESPACE +``` + +### Job Pod 容器的日志 + +``` +kubectl logs -l job-name=JOB_NAME -n NAMESPACE +``` + +### 驱逐的 Pod + +可以根据 [eviction 信号](https://kubernetes.io/docs/tasks/administer-cluster/out-of-resource/#eviction-policy)来驱逐 Pod。 + +检索被驱逐的 Pod 列表（podname 和命名空间）： + +``` +kubectl get pods --all-namespaces -o go-template='{{range .items}}{{if eq .status.phase "Failed"}}{{if eq .status.reason "Evicted"}}{{.metadata.name}}{{" "}}{{.metadata.namespace}}{{"\n"}}{{end}}{{end}}{{end}}' +``` + +要删除所有被驱逐的 pod： + +``` +kubectl get pods --all-namespaces -o go-template='{{range .items}}{{if eq .status.phase "Failed"}}{{if eq .status.reason "Evicted"}}{{.metadata.name}}{{" "}}{{.metadata.namespace}}{{"\n"}}{{end}}{{end}}{{end}}' | while read epod enamespace; do kubectl -n $enamespace delete pod $epod; done +``` + +检索被驱逐的 pod 列表、调度节点以及原因： + +``` +kubectl get pods --all-namespaces -o go-template='{{range .items}}{{if eq .status.phase "Failed"}}{{if eq .status.reason "Evicted"}}{{.metadata.name}}{{" "}}{{.metadata.namespace}}{{"\n"}}{{end}}{{end}}{{end}}' | while read epod enamespace; do kubectl -n $enamespace get pod $epod -o=custom-columns=NAME:.metadata.name,NODE:.spec.nodeName,MSG:.status.message; done +``` + +### Job 未完成 + +如果你启用了 Istio 而且你部署的 Job 未完成，你需要按照[这些步骤](../../how-to-guides/advanced-user-guides/istio-setup-guide/enable-istio-in-namespace.md)将注释添加到 Pod 中。 + +由于 Istio Sidecars 会一直运行，因此即使任务完成了，也不能认为 Job 已完成。这是一个临时的解决方法，它禁止了 Istio 和添加了注释的 Pod 之间的通信。如果你使用了这个方法，由于这个 Job 无法访问服务网格，因此你将不能继续使用 Job 进行集成测试。 \ No newline at end of file diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/troubleshooting/other-troubleshooting-tips/logging.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/troubleshooting/other-troubleshooting-tips/logging.md new file mode 100644 index 00000000000..7b74521fbb9 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/troubleshooting/other-troubleshooting-tips/logging.md @@ -0,0 +1,72 @@ +--- +title: Logging +--- + +## 日志级别 + +Rancher 使用了以下日志级别： + +| 名称 | 描述 | +|---------|-------------| +| `info` | 记录信息性消息。这是默认的日志级别。 | +| `debug` | 记录可用于调试的更详细消息。 | +| `trace` | 记录内部功能的非常详细的消息。非常冗长，并且可能包含敏感信息。 | + +### 如何配置日志级别 + +#### Kubernetes 安装 + +* 配置 debug 日志级别 + +``` +$ KUBECONFIG=./kube_config_cluster.yml +$ kubectl -n cattle-system get pods -l app=rancher --no-headers -o custom-columns=name:.metadata.name | while read rancherpod; do kubectl -n cattle-system exec $rancherpod -c rancher -- loglevel --set debug; done +OK +OK +OK +$ kubectl -n cattle-system logs -l app=rancher -c rancher +``` + +* 配置 info 日志级别 + +``` +$ KUBECONFIG=./kube_config_cluster.yml +$ kubectl -n cattle-system get pods -l app=rancher --no-headers -o custom-columns=name:.metadata.name | while read rancherpod; do kubectl -n cattle-system exec $rancherpod -c rancher -- loglevel --set info; done +OK +OK +OK +``` + +#### Docker 安装 + +* 配置 debug 日志级别 + +``` +$ docker exec -ti loglevel --set debug +OK +$ docker logs -f +``` + +* 配置 info 日志级别 + +``` +$ docker exec -ti loglevel --set info +OK +``` + +## Rancher 主机调试日志 +如果需要解决在基础设施提供商中创建对象的问题，你可以使用 `rancher-machine` 调试日志。 + +你可以在启动 Rancher 时设置环境变量来为 `rancher-machine` 启用调试日志。 + +`CATTLE_WHITELIST_ENVVARS` 环境变量允许用户将特定环境变量列入白名单，让它们能在配置期间传递给 `rancher-machine`。 + +`MACHINE_DEBUG` 变量在 `rancher-machine` 中启用调试日志。 + +因此，通过设置 `MACHINE_DEBUG=true` 并将 `MACHINE_DEBUG` 添加到 `CATTLE_WHITELIST_ENVVARS` 中的变量默认列表（例如 `CATTLE_WHITELIST_ENVVARS=HTTP_PROXY,HTTPS_PROXY,NO_PROXY,MACHINE_DEBUG`），你可以在配置 RKE1、RKE2 和 K3s 集群时在 `rancher-machine` 中启用调试日志。 + +:::caution + +像上面的 `trace` 日志级别一样，`rancher-machine` 调试日志可以包含敏感信息。 + +::: diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/troubleshooting/other-troubleshooting-tips/networking.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/troubleshooting/other-troubleshooting-tips/networking.md new file mode 100644 index 00000000000..d9e28635dae --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/troubleshooting/other-troubleshooting-tips/networking.md @@ -0,0 +1,104 @@ +--- +title: 网络 +--- + +本文列出的命令/步骤可用于检查集群中的网络问题。 + +请确保你配置了正确的 kubeconfig（例如，为 Rancher HA 配置了 `export KUBECONFIG=$PWD/kube_config_cluster.yml`）或通过 UI 使用了嵌入式 kubectl。 + +## 仔细检查你的（主机）防火墙中是否打开了所有必需的端口 + +仔细检查你的（主机）防火墙中是否打开了所有[必需的端口](../../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/node-requirements-for-rancher-managed-clusters.md#网络要求)。其他所需的端口都使用 TCP，而覆盖网络使用 UDP。 + +## 检查覆盖网络是否正常运行 + +你可以将 Pod 调度到集群中的任何主机，但是 NGINX Ingress Controller 需要能够将 `NODE_1` 请求路由到 `NODE_2`。这会在覆盖网络上进行。如果覆盖网络无法正常工作，由于 NGINX Ingress Controller 无法路由到 pod，因此 TCP/HTTP 连接会间歇性失败。 + +要测试覆盖网络，你可以启动以下 `DaemonSet` 定义。这样，每台主机上都会运行一个 `swiss-army-knife` 容器（镜像由 Rancher 工程师开发，可在[此处](https://github.com/rancherlabs/swiss-army-knife)找到），我们使用该镜像在所有主机上的容器之间运行 `ping` 测试。 + +:::note + +此容器[不支持 ARM 节点](https://github.com/leodotcloud/swiss-army-knife/issues/18)（例如 Raspberry Pi）。Pod 日志会显示为 `exec user process caused: exec format error`。 + +::: + +1. 将以下内容另存为 `overlaytest.yml`： + + ``` + apiVersion: apps/v1 + kind: DaemonSet + metadata: + name: overlaytest + spec: + selector: + matchLabels: + name: overlaytest + template: + metadata: + labels: + name: overlaytest + spec: + tolerations: + - operator: Exists + containers: + - image: rancherlabs/swiss-army-knife + imagePullPolicy: Always + name: overlaytest + command: ["sleep", "infinity"] + terminationMessagePath: /dev/termination-log + + ``` + +2. 使用 `kubectl create -f overlaytest.yml` 启动它。 +3. 等待 `kubectl rollout status ds/overlaytest -w` 返回 `daemon set "overlaytest" successfully rolled out`。 +4. 从同一位置运行以下脚本。它会让每个主机上的所有 `overlaytest` 容器相互 ping 通： + ``` + #!/bin/bash + echo "=> Start network overlay test" + kubectl get pods -l name=overlaytest -o jsonpath='{range .items[*]}{@.metadata.name}{" "}{@.spec.nodeName}{"\n"}{end}' | + while read spod shost + do kubectl get pods -l name=overlaytest -o jsonpath='{range .items[*]}{@.status.podIP}{" "}{@.spec.nodeName}{"\n"}{end}' | + while read tip thost + do kubectl --request-timeout='10s' exec $spod -c overlaytest -- /bin/sh -c "ping -c2 $tip > /dev/null 2>&1" + RC=$? + if [ $RC -ne 0 ] + then echo FAIL: $spod on $shost cannot reach pod IP $tip on $thost + else echo $shost can reach $thost + fi + done + done + echo "=> End network overlay test" + ``` + +5. 命令运行完成后，它会输出每条路由的状态： + + ``` + => Start network overlay test + Error from server (NotFound): pods "wk2" not found + FAIL: overlaytest-5bglp on wk2 cannot reach pod IP 10.42.7.3 on wk2 + Error from server (NotFound): pods "wk2" not found + FAIL: overlaytest-5bglp on wk2 cannot reach pod IP 10.42.0.5 on cp1 + Error from server (NotFound): pods "wk2" not found + FAIL: overlaytest-5bglp on wk2 cannot reach pod IP 10.42.2.12 on wk1 + command terminated with exit code 1 + FAIL: overlaytest-v4qkl on cp1 cannot reach pod IP 10.42.7.3 on wk2 + cp1 can reach cp1 + cp1 can reach wk1 + command terminated with exit code 1 + FAIL: overlaytest-xpxwp on wk1 cannot reach pod IP 10.42.7.3 on wk2 + wk1 can reach cp1 + wk1 can reach wk1 + => End network overlay test + ``` + 如果你在输出中看到错误，则说明两台主机上的 Pod 路由存在问题。在上面的输出中，节点 `wk2` 在覆盖网络上没有连接。原因可能是没有为 `wk2` 打开覆盖网络的[必需端口](../../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/node-requirements-for-rancher-managed-clusters.md#网络要求)。 +6. 你现在可以通过运行 `kubectl delete ds/overlaytest` 来清理 DaemonSet。 + +## 检查主机和对等/隧道设备/设备上的 MTU 是否正确配置 + +如果 MTU 在运行 Rancher 的主机、创建/导入集群中的节点或两者之间的设备上配置不正确，Rancher 和 Agent 会记录类似以下的错误信息： + +* `websocket: bad handshake` +* `Failed to connect to proxy` +* `read tcp: i/o timeout` + +有关在 Rancher 和集群节点之间使用 Google Cloud VPN 时如何正确配置 MTU 的示例，请参阅 [Google Cloud VPN：MTU 注意事项](https://cloud.google.com/vpn/docs/concepts/mtu-considerations#gateway_mtu_vs_system_mtu)。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/troubleshooting/other-troubleshooting-tips/rancher-ha.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/troubleshooting/other-troubleshooting-tips/rancher-ha.md new file mode 100644 index 00000000000..23e0ab21787 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/troubleshooting/other-troubleshooting-tips/rancher-ha.md @@ -0,0 +1,79 @@ +--- +title: Rancher HA +--- + +本文列出的命令/步骤可用于检查你的 Rancher Kubernetes 安装。 + +请确保你配置了正确的 kubeconfig（例如，`export KUBECONFIG=$PWD/kube_config_cluster.yml`）。 + +## 检查 Rancher Pod + +Rancher pod 会部署为 `cattle-system` 命名空间中的一个 Deployment。 + +检查 pod 是否运行在所有节点上： + +``` +kubectl -n cattle-system get pods -l app=rancher -o wide +``` + +输出示例： + +``` +NAME READY STATUS RESTARTS AGE IP NODE +rancher-7dbd7875f7-n6t5t 1/1 Running 0 8m x.x.x.x x.x.x.x +rancher-7dbd7875f7-qbj5k 1/1 Running 0 8m x.x.x.x x.x.x.x +rancher-7dbd7875f7-qw7wb 1/1 Running 0 8m x.x.x.x x.x.x.x +``` + +如果 pod 无法运行（即状态不是 **Running**，Ready 状态未显示 `1/1`，或者有大量 Restarts），请检查 pod 详细信息，日志和命名空间事件。 + +### Pod 详细信息 + +``` +kubectl -n cattle-system describe pods -l app=rancher +``` + +### Pod 容器日志 + +``` +kubectl -n cattle-system logs -l app=rancher +``` + +### 命名空间事件 + +``` +kubectl -n cattle-system get events +``` + +## 检查 Ingress + +Ingress 应该具有正确的 `HOSTS`（显示配置的 FQDN）和 `ADDRESS`（将被路由到该主机地址）： + +``` +kubectl -n cattle-system get ingress +``` + +输出示例： + +``` +NAME HOSTS ADDRESS PORTS AGE +rancher rancher.yourdomain.com x.x.x.x,x.x.x.x,x.x.x.x 80, 443 2m +``` + +## 检查 Ingress Controller 日志 + +如果访问你配置的 Rancher FQDN 时没有显示 UI，请检查 Ingress Controller 日志以查看尝试访问 Rancher 时发生了什么： + +``` +kubectl -n ingress-nginx logs -l app=ingress-nginx +``` + +## Leader 选举 + +Leader 由 Leader 选举确定。确定 Leader 后，Leader（`holderIdentity`）会保存在 `cattle-controllers` ConfigMap 中（在本例中为 `rancher-7dbd7875f7-qbj5k`）： + +``` +kubectl -n kube-system get configmap cattle-controllers -o jsonpath='{.metadata.annotations.control-plane\.alpha\.kubernetes\.io/leader}' +{"holderIdentity":"rancher-7dbd7875f7-qbj5k","leaseDurationSeconds":45,"acquireTime":"2019-04-04T11:53:12Z","renewTime":"2019-04-04T12:24:08Z","leaderTransitions":0} +``` + diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/troubleshooting/other-troubleshooting-tips/registered-clusters.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/troubleshooting/other-troubleshooting-tips/registered-clusters.md new file mode 100644 index 00000000000..b50113370e3 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/troubleshooting/other-troubleshooting-tips/registered-clusters.md @@ -0,0 +1,67 @@ +--- +title: 注册集群 +--- + +本文列出的命令/步骤可用于检查你正在注册或已在 Rancher 中注册的集群。 + +请确保你配置了正确的 kubeconfig（例如，`export KUBECONFIG=$PWD/kubeconfig_from_imported_cluster.yml`）。 + +## Rancher Agents + +Rancher Agent 用于实现与集群的通信（通过 cattle-cluster-agent 的 Kubernetes API）和与节点的通信。 + +如果 cattle-cluster-agent 无法连接到配置的 `server-url`，集群将保持在 **Pending** 状态并显示 `Waiting for full cluster configuration`。 + +### cattle-node-agent + +:::note + +cattle-node-agents 只会在使用 RKE 在 Rancher 创建的集群中显示。 + +::: + +检查每个节点上是否存在 cattle-node-agent pod，状态是否为 **Running**，并且重启次数不多： + +``` +kubectl -n cattle-system get pods -l app=cattle-agent -o wide +``` + +输出示例： + +``` +NAME READY STATUS RESTARTS AGE IP NODE +cattle-node-agent-4gc2p 1/1 Running 0 2h x.x.x.x worker-1 +cattle-node-agent-8cxkk 1/1 Running 0 2h x.x.x.x etcd-1 +cattle-node-agent-kzrlg 1/1 Running 0 2h x.x.x.x etcd-0 +cattle-node-agent-nclz9 1/1 Running 0 2h x.x.x.x controlplane-0 +cattle-node-agent-pwxp7 1/1 Running 0 2h x.x.x.x worker-0 +cattle-node-agent-t5484 1/1 Running 0 2h x.x.x.x controlplane-1 +cattle-node-agent-t8mtz 1/1 Running 0 2h x.x.x.x etcd-2 +``` + +检查特定或所有 cattle-node-agent pod 的日志记录： + +``` +kubectl -n cattle-system logs -l app=cattle-agent +``` + +### cattle-cluster-agent + +检查 cattle-cluster-agent pod 是否存在于集群中，状态是否为 **Running**，并且重启次数不多： + +``` +kubectl -n cattle-system get pods -l app=cattle-cluster-agent -o wide +``` + +输出示例： + +``` +NAME READY STATUS RESTARTS AGE IP NODE +cattle-cluster-agent-54d7c6c54d-ht9h4 1/1 Running 0 2h x.x.x.x worker-1 +``` + +检查 cattle-cluster-agent pod 的日志记录： + +``` +kubectl -n cattle-system logs -l app=cattle-cluster-agent +``` diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/troubleshooting/other-troubleshooting-tips/user-id-tracking-in-audit-logs.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/troubleshooting/other-troubleshooting-tips/user-id-tracking-in-audit-logs.md new file mode 100644 index 00000000000..3d5f8069852 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/troubleshooting/other-troubleshooting-tips/user-id-tracking-in-audit-logs.md @@ -0,0 +1,22 @@ +--- +title: 审计日志中的用户 ID 跟踪 +--- + +Rancher 使用以下审计日志来跟踪本地和下游集群中发生的事件： + +* [Kubernetes 审计日志](https://rancher.com/docs/rke/latest/en/config-options/audit-log/) +* [Rancher API 审核日志](../../how-to-guides/advanced-user-guides/enable-api-audit-log.md) + +Rancher 2.6 增强了审计日志，在 Rancher 和下游 Kubernetes 审计日志中都包含了外部身份提供程序名称（即外部身份提供程序中用户的通用名称）。 + +在 Rancher 2.6 之前，如果管理员不知道外部身份提供程序中的用户名和 Rancher 中的 userId (`u-xXXX`) 之间的映射，则无法通过 Rancher 审计日志和 Kubernetes 审计日志来追踪事件。 +要知道这个映射，集群管理员需要能够访问 Rancher API、UI 和 local 管理集群。 + +有了这个功能之后，下游集群管理员就能够查看 Kubernetes 审计日志，并且可以不在 Rancher 中查看任何内容就能知道哪个外部身份提供程序 (IDP) 用户执行了某项操作。 +如果集群传出了审计日志，日志系统的用户就能够识别外部身份提供程序中的用户。 +Rancher 管理员现在能够查看 Rancher 审计日志，并使用外部身份提供程序用户名来跟踪 Kubernetes 审计日志。 + +## 功能描述 + +- 在下游集群启用了 Kubernetes 审计日志后，会在“元数据”级别为每个请求记录外部身份提供程序的用户名。 +- 在 Rancher 启用 Rancher API 审计日志后，每个到达 Rancher API Server 的请求记录（包括登录请求）对应的外部身份提供程序用户名也会记录在 `auditLog.level=1` 中。 diff --git a/versioned_docs/version-2.14/api/api-reference.mdx b/versioned_docs/version-2.14/api/api-reference.mdx new file mode 100644 index 00000000000..caada3bcaf5 --- /dev/null +++ b/versioned_docs/version-2.14/api/api-reference.mdx @@ -0,0 +1,18 @@ +--- +title: API Reference +hide_table_of_contents: true +--- + + + + + +:::note + +At this time, not all Rancher resources are available through the Rancher Kubernetes API. + +::: + +import ApiDocMdx from '@theme/ApiDocMdx'; + + diff --git a/versioned_docs/version-2.14/api/api-tokens.md b/versioned_docs/version-2.14/api/api-tokens.md new file mode 100644 index 00000000000..a05cf03bcfc --- /dev/null +++ b/versioned_docs/version-2.14/api/api-tokens.md @@ -0,0 +1,90 @@ +--- +title: Using API Tokens +--- + + + + + +Rancher v2.8.0 introduced the [Rancher Kubernetes API](./api-reference.mdx) which can be used to manage Rancher resources through `kubectl`. This page covers information on API tokens used with the [Rancher CLI](../reference-guides/cli-with-rancher/cli-with-rancher.md), [kubeconfig files](../how-to-guides/new-user-guides/manage-clusters/access-clusters/authorized-cluster-endpoint.md#about-the-kubeconfig-file), Terraform and the [v3 API browser](./v3-rancher-api-guide.md#enable-view-in-api). + +By default, some cluster-level API tokens are generated with infinite time-to-live (`ttl=0`). In other words, API tokens with `ttl=0` never expire unless you invalidate them. Tokens are not invalidated by changing a password. + +You can deactivate API tokens by deleting them or by deactivating the user account. + +## Deleting Tokens + +To delete a token: + +1. Go to the list of all tokens in the Rancher API view at `https:///v3/tokens`. + +1. Access the token you want to delete by its ID. For example, `https:///v3/tokens/kubectl-shell-user-vqkqt` + +1. Click **Delete**. + +The following is a complete list of tokens generated with `ttl=0`: + +| Token | Description | +| ----------------- | -------------------------------------------------------------------------------------- | +| `kubectl-shell-*` | Access to `kubectl` shell in the browser | +| `agent-*` | Token for agent deployment | +| `compose-token-*` | Token for compose | +| `helm-token-*` | Token for Helm chart deployment | +| `drain-node-*` | Token for drain (Rancher uses `kubectl` for drain because there is no native Kubernetes API). | + +## Setting TTL on Kubeconfig Tokens + +Admins can set a global time-to-live (TTL) on Kubeconfig tokens. Changing the default kubeconfig TTL can be done by navigating to global settings and setting [`kubeconfig-default-token-ttl-minutes`](#kubeconfig-default-token-ttl-minutes) to the desired duration in minutes. As of Rancher v2.8, the default value of [`kubeconfig-default-token-ttl-minutes`](#kubeconfig-default-token-ttl-minutes) is `43200`, which means that tokens expire in 30 days. + +:::note + +This setting is used by all kubeconfig tokens except those created by the CLI to [generate kubeconfig tokens](#disable-tokens-in-generated-kubeconfigs). + +::: + +## Disable Tokens in Generated Kubeconfigs + +Set the `kubeconfig-generate-token` setting to `false`. This setting instructs Rancher to no longer automatically generate a token when a user clicks on download a kubeconfig file. When this setting is deactivated, a generated kubeconfig references the [Rancher CLI](../reference-guides/cli-with-rancher/kubectl-utility.md#authentication-with-kubectl-and-kubeconfig-tokens-with-ttl) to retrieve a short-lived token for the cluster. When this kubeconfig is used in a client, such as `kubectl`, the Rancher CLI needs to be installed to complete the log in request. + +## Token Hashing + +You can [enable token hashing](../how-to-guides/advanced-user-guides/enable-experimental-features/enable-experimental-features.md), where tokens undergo a one-way hash using the SHA256 algorithm. This is a non-reversible process: once enabled, this feature cannot be disabled. You should first evaluate this setting in a test environment, and/or take backups before enabling. + +This feature affects all tokens which include, but are not limited to, the following: + +- Kubeconfig tokens +- Bearer tokens API keys/calls +- Tokens used by internal operations + +## Token Settings + +These global settings affect Rancher token behavior. + +| Setting | Description | +| ------- | ----------- | +| [`auth-user-session-ttl-minutes`](#auth-user-session-ttl-minutes) | TTL in minutes on a user auth session token. | +| [`auth-user-session-idle-ttl-minutes`](#auth-user-session-idle-ttl-minutes) | TTL in minutes on a user auth session token, without user activity. | +| [`kubeconfig-default-token-ttl-minutes`](#kubeconfig-default-token-ttl-minutes) | Default TTL applied to all kubeconfig tokens except for tokens [generated by Rancher CLI](#disable-tokens-in-generated-kubeconfigs). | +| [`auth-token-max-ttl-minutes`](#auth-token-max-ttl-minutes) | Max TTL for all tokens except those controlled by [`auth-user-session-ttl-minutes`](#auth-user-session-ttl-minutes). | +| [`kubeconfig-generate-token`](#kubeconfig-generate-token) | If true, automatically generate tokens when a user downloads a kubeconfig. | + +### auth-user-session-ttl-minutes + +Time to live (TTL) duration in minutes, used to determine when a user auth session token expires. When expired, the user must log in and obtain a new token. This setting is not affected by [`auth-token-max-ttl-minutes`](#auth-token-max-ttl-minutes). Session tokens are created when a user logs into Rancher. + +### auth-user-session-idle-ttl-minutes + +Time to live (TTL) without user activity for login sessions tokens, in minutes. +By default, `auth-user-session-idle-ttl-minutes` is set to the same value as [`auth-user-session-ttl-minutes`](#auth-user-session-ttl-minutes) (for backward compatibility). It must never exceed the value of `auth-user-session-ttl-minutes`. + +### kubeconfig-default-token-ttl-minutes + +Time to live (TTL) duration in minutes, used to determine when a kubeconfig token expires. When the token is expired, the API rejects the token. This setting can't be larger than [`auth-token-max-ttl-minutes`](#auth-token-max-ttl-minutes). This setting applies to tokens generated in a requested kubeconfig file, except for tokens [generated by Rancher CLI](#disable-tokens-in-generated-kubeconfigs). As of Rancher v2.8, the default duration is `43200`, which means that tokens expire in 30 days. + +### auth-token-max-ttl-minutes + +Maximum Time to Live (TTL) in minutes allowed for auth tokens. If a user attempts to create a token with a TTL greater than `auth-token-max-ttl-minutes`, Rancher sets the token TTL to the value of `auth-token-max-ttl-minutes`. Applies to all kubeconfig tokens and API tokens. As of Rancher v2.8, the default duration is `129600`, which means that tokens expire in 90 days. + +### kubeconfig-generate-token + +When true, kubeconfigs requested through the UI contain a valid token. When false, kubeconfigs contain a command that uses the Rancher CLI to prompt the user to log in. [The CLI then retrieves and caches a token for the user](../reference-guides/cli-with-rancher/kubectl-utility.md#authentication-with-kubectl-and-kubeconfig-tokens-with-ttl). diff --git a/versioned_docs/version-2.14/api/extension-apiserver.md b/versioned_docs/version-2.14/api/extension-apiserver.md new file mode 100644 index 00000000000..81c1c4cd33e --- /dev/null +++ b/versioned_docs/version-2.14/api/extension-apiserver.md @@ -0,0 +1,20 @@ +--- +title: Extension API Server +--- + + + + + +Rancher extends Kubernetes with additional APIs by registering an extension API server using the [Kubernetes API Aggregation Layer](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/apiserver-aggregation/). + +## Aggregation Layer is Required + +The API aggregation layer must be configured on the local Kubernetes cluster for the `v1.ext.cattle.io` `APIService` to work correctly. If the `APIService` does not receive a registration request after the Rancher server starts, the pod will crash with a log entry indicating the error. If your pods are consistently failing to detect registration despite having a correctly configured cluster, you can increase the timeout by setting the `.Values.aggregationRegistrationTimeout` in Helm. + +All versions of Kubernetes supported in this Rancher versions K8s distributions (RKE2/K3s) will have the aggregation layer configured and enabled by default. However, if you suspect that your cluster configuration is incorrect, refer to the [Kubernetes Aggregation Layer documentation](https://kubernetes.io/docs/tasks/extend-kubernetes/configure-aggregation-layer/) for information on configuring the aggregation layer. + + +:::note +If the underlying Kubernetes distribution does not support the aggregation layer, you must migrate to a Kubernetes distribution that does before upgrading. +::: diff --git a/versioned_docs/version-2.14/api/quickstart.md b/versioned_docs/version-2.14/api/quickstart.md new file mode 100644 index 00000000000..5bb3057183e --- /dev/null +++ b/versioned_docs/version-2.14/api/quickstart.md @@ -0,0 +1,152 @@ +--- +title: RK-API Quick Start Guide +--- + + + + + +You can access Rancher's resources through the Kubernetes API. This guide helps you get started on using this API as a Rancher user. + +1. In the upper left corner, click **☰ > Global Settings**. +2. Find and copy the address in the `server-url` field. +3. [Create](../reference-guides/user-settings/api-keys.md#creating-an-api-key) a Rancher API key with no scope. + + :::danger + + A Rancher API key with no scope grants unrestricted access to all resources that the user can access. To prevent unauthorized use, this key should be stored securely and rotated frequently. + + ::: + +4. Create a `kubeconfig.yaml` file. Replace `$SERVER_URL` with the server url and `$API_KEY` with your Rancher API key: + + ```yaml + apiVersion: v1 + kind: Config + clusters: + - name: "rancher" + cluster: + server: "$SERVER_URL" + + users: + - name: "rancher" + user: + token: "$API_KEY" + + contexts: + - name: "rancher" + context: + user: "rancher" + cluster: "rancher" + + current-context: "rancher" + ``` + +You can use this file with any compatible tool, such as kubectl or [client-go](https://github.com/kubernetes/client-go). For a quick demo, see the [kubectl example](#api-kubectl-example). + +For more information on handling more complex certificate setups, see [Specifying CA Certs](#specifying-ca-certs). + +For more information on available kubeconfig options, see the [upstream documentation](https://kubernetes.io/docs/tasks/access-application-cluster/configure-access-multiple-clusters/). + +## API kubectl Example + +In this example, we'll show how to use kubectl to create a project, followed by deleting it. For a list of other Rancher resources available, refer to the [API Reference](./api-reference.mdx) page. + +:::note + +At this time, not all Rancher resources are available through the Rancher Kubernetes API. + +::: + +1. Set your KUBECONFIG environment variable to the kubeconfig file you just created: + + ```bash + export KUBECONFIG=$(pwd)/kubeconfig.yaml + ``` + +2. Use `kubectl explain` to view the available fields for projects, or complex sub-fields of resources: + + ```bash + kubectl explain projects + kubectl explain projects.spec + ``` + +Not all resources may have detailed output. + +3. Add the following content to a file named `project.yaml`: + + ```yaml + apiVersion: management.cattle.io/v3 + kind: Project + metadata: + # name should be unique across all projects in every cluster + name: p-abc123 + # generateName can be used instead of `name` to randomly generate a name. + # generateName: p- + # namespace should match spec.ClusterName. + namespace: local + spec: + # clusterName should match `metadata.Name` of the target cluster. + clusterName: local + description: Example Project + # displayName is the human-readable name and is visible from the UI. + displayName: Example + ``` + +4. Create the project: + + ```bash + kubectl create -f project.yaml + ``` + +5. Delete the project: + + How you delete the project depends on how you created the project name. + + **A. If you used `name` when creating the project**: + + ```bash + kubectl delete -f project.yaml + ``` + + **B. If you used `generateName`**: + + Replace `$PROJECT_NAME` with the randomly generated name of the project displayed by Kubectl after you created the project. + + ```bash + kubectl delete project $PROJECT_NAME -n local + ``` + +## Specifying CA Certs + +To ensure that your tools can recognize Rancher's CA certificates, most setups require additional modifications to the above template. + +1. In the upper left corner, click **☰ > Global Settings**. +2. Find and copy the value in the `ca-certs` field. +3. Save the value in a file named `rancher.crt`. + + :::note + If your Rancher instance is proxied by another service, you must extract the certificate that the service is using, and add it to the kubeconfig file, as demonstrated in step 5. + ::: + +4. The following commands convert `rancher.crt` to base64 output, trim all new-lines, and update the cluster in the kubeconfig with the certificate, then finish by removing the `rancher.crt` file: + + ```bash + export KUBECONFIG=$PATH_TO_RANCHER_KUBECONFIG + kubectl config set clusters.rancher.certificate-authority-data $(cat rancher.crt | base64 -i - | tr -d '\n') + rm rancher.crt + ``` +5. (Optional) If you use self-signed certificatess that aren't trusted by your system, you can set the insecure option in your kubeconfig with kubectl: + + :::danger + + This option shouldn't be used in production as it is a security risk. + + ::: + + ```bash + export KUBECONFIG=$PATH_TO_RANCHER_KUBECONFIG + kubectl config set clusters.rancher.insecure-skip-tls-verify true + ``` + + If your Rancher instance is proxied by another service, you must extract the certificate that the service is using, and add it to the kubeconfig file, as demonstrated above. diff --git a/versioned_docs/version-2.14/api/v3-rancher-api-guide.md b/versioned_docs/version-2.14/api/v3-rancher-api-guide.md new file mode 100644 index 00000000000..e04b0896c0e --- /dev/null +++ b/versioned_docs/version-2.14/api/v3-rancher-api-guide.md @@ -0,0 +1,94 @@ +--- +title: Previous v3 Rancher API Guide +--- + + + + + +Rancher v2.8.0 introduced the Rancher Kubernetes API (RK-API). The previous v3 Rancher API is still available. This page describes the v3 API. For more information on RK-API, see the [RK-API quickstart](./quickstart.md) and [reference guide](./api-reference.mdx). + +## How to Use the API + +The previous v3 API has its own user interface accessible from a [web browser](#enable-view-in-api). This is an easy way to see resources, perform actions, and see the equivalent `curl` or HTTP request & response. To access it: + + + + +1. Click your user avatar in the upper right corner. +1. Click **Account & API Keys**. +1. Under the **API Keys** section, find the **API Endpoint** field and click the link. The link looks something like `https:///v3`, where `` is the fully qualified domain name of your Rancher deployment. + + + + +Go to the URL endpoint at `https:///v3`, where `` is the fully qualified domain name of your Rancher deployment. + + + + +## Authentication + +API requests must include authentication information. Authentication is done with HTTP basic authentication using [API keys](../reference-guides/user-settings/api-keys.md). API keys can create new clusters and have access to multiple clusters via `/v3/clusters/`. [Cluster and project roles](../how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/cluster-and-project-roles.md) apply to these keys and restrict what clusters and projects the account can see and what actions they can take. + +By default, certain cluster-level API tokens are generated with infinite time-to-live (`ttl=0`). In other words, API tokens with `ttl=0` never expire unless you invalidate them. For details on how to invalidate them, refer to the [API tokens page](api-tokens.md). + +## Making Requests + +The API is generally RESTful but has several features to make the definition of everything discoverable by a client so that generic clients can be written instead of having to write specific code for every type of resource. For detailed info about the generic API spec, [see further documentation](https://github.com/rancher/api-spec/blob/master/specification.md). + +- Every type has a Schema which describes: + - The URL to get to the collection of this type of resource. + - Every field the resource can have, along with their type, basic validation rules, whether they are required or optional, etc. + - Every action that is possible on this type of resource, with their inputs and outputs (also as schemas). + - Every field that allows filtering. + - What HTTP verb methods are available for the collection itself, or for individual resources in the collection. + +The design allows you to load just the list of schemas and access everything about the API. The UI for the API contains no code specific to Rancher itself. The URL to get Schemas is sent in every HTTP response as a `X-Api-Schemas` header. From there you can follow the `collection` link on each schema to know where to list resources, and follow other `links` inside of the returned resources to get any other information. + +In practice, you may just want to construct URL strings. We highly suggest limiting this to the top-level to list a collection (`/v3/`) or get a specific resource (`/v3//`). Anything deeper than that is subject to change in future releases. + +Resources have relationships between each other called links. Each resource includes a map of `links` with the name of the link and the URL where you can retrieve that information. Again, you should `GET` the resource and then follow the URL in the `links` map, not construct these strings yourself. + +Most resources have actions, which do something or change the state of the resource. To use them, send a HTTP `POST` to the URL in the `actions` map of the action you want. Certain actions require input or produce output. See the individual documentation for each type or the schemas for specific information. + +To edit a resource, send a HTTP `PUT` to the `links.update` link on the resource with the fields that you want to change. If the link is missing then you don't have permission to update the resource. Unknown fields and ones that are not editable are ignored. + +To delete a resource, send a HTTP `DELETE` to the `links.remove` link on the resource. If the link is missing then you don't have permission to update the resource. + +To create a new resource, HTTP `POST` to the collection URL in the schema (which is `/v3/`). + +## Filtering + +Most collections can be filtered on the server-side by common fields using HTTP query parameters. The `filters` map shows you what fields can be filtered on and what the filtered values were for the request you made. The API UI has controls to setup filtering and show you the appropriate request. For simple "equals" matches it's just `field=value`. Modifiers can be added to the field name, for example, `field_gt=42` for "field is greater than 42." See the [API spec](https://github.com/rancher/api-spec/blob/master/specification.md#filtering) for full details. + +## Sorting + +Most collections can be sorted on the server-side by common fields using HTTP query parameters. The `sortLinks` map shows you what sorts are available, along with the URL to get the collection sorted by that. It also includes info about what the current response was sorted by, if specified. + +## Pagination + +API responses are paginated with a limit of 100 resources per page by default. This can be changed with the `limit` query parameter, up to a maximum of 1000, for example, `/v3/pods?limit=1000`. The `pagination` map in collection responses tells you whether or not you have the full result set and has a link to the next page if you do not. + +## Capturing v3 API Calls + +You can use browser developer tools to capture how the v3 API is called. For example, you could follow these steps to use the Chrome developer tools to get the API call for provisioning a Rancher Kubernetes distribution cluster: + +1. In the Rancher UI, go to **Cluster Management** and click **Create.** +1. Click one of the cluster types. This example uses Digital Ocean. +1. Fill out the form with a cluster name and node template, but don't click **Create**. +1. You need to open the developer tools before the cluster creation to see the API call being recorded. To open the tools, right-click the Rancher UI and click **Inspect.** +1. In the developer tools, click the **Network** tab. +1. On the **Network** tab, make sure **Fetch/XHR** is selected. +1. In the Rancher UI, click **Create**. In the developer tools, you should see a new network request with the name `cluster?_replace=true`. +1. Right-click `cluster?_replace=true` and click **Copy > Copy as cURL.** +1. Paste the result into any text editor. You can see the POST request, including the URL it was sent to, all headers, and the full body of the request. This command can be used to create a cluster from the command line. Note: the request should be stored in a safe place because it contains credentials. + +### Enable View in API + +You can also view captured v3 API calls for your respective clusters and resources. This feature is not enabled by default. To enable it: + +1. Click your **User Tile** in the top right corner of the UI and select **Preferences** from the drop-down menu. +2. Under the **Advanced Features** section, click **Enable "View in API"** + +Once checked, the **View in API** link is displayed under the **⋮** sub-menu on resource pages in the UI. diff --git a/versioned_docs/version-2.14/api/workflows/kubeconfigs.md b/versioned_docs/version-2.14/api/workflows/kubeconfigs.md new file mode 100644 index 00000000000..6ef8e2e9817 --- /dev/null +++ b/versioned_docs/version-2.14/api/workflows/kubeconfigs.md @@ -0,0 +1,197 @@ +--- +title: Kubeconfigs +--- + + + + + +## Kubeconfig Resource + +Kubeconfig is a Rancher resource `kubeconfigs.ext.cattle.io` that allows generating `v1.Config` kubeconfig files for interacting with Rancher and clusters managed by Rancher. + +```sh +kubectl api-resources --api-group=ext.cattle.io +``` + +To get a description of the fields and structure of the Kubeconfig resource, run: + +```sh +kubectl explain kubeconfigs.ext.cattle.io +``` + +## Creating a Kubeconfig + +Only a **valid and active** Rancher user can create a Kubeconfig. For example, trying to create a Kubeconfig using a `system:admin` service account will lead to an error: + +```bash +kubectl create -o jsonpath='{.status.value}' -f -< + + + +## Creating a Project + +Project resources may only be created on the management cluster. See below for [creating namespaces under projects in a managed cluster](#creating-a-namespace-in-a-project). + +### Creating a Basic Project + +```bash +kubectl create -f - <:`. + +## Deleting a Project + +Look up the project to delete in the cluster namespace: + +```bash +kubectl --namespace c-m-abcde get projects +``` + +Delete the project under the cluster namespace: + +```bash +kubectl --namespace c-m-abcde delete project p-vwxyz +``` + +Note that this command doesn't delete the namespaces and resources that formerly belonged to the project. + +It does delete all project role template bindings for the projects, so recreating the project will not restore members added to the project, and you have to add users as members again. diff --git a/versioned_docs/version-2.14/api/workflows/tokens.md b/versioned_docs/version-2.14/api/workflows/tokens.md new file mode 100644 index 00000000000..87c11bdb3f3 --- /dev/null +++ b/versioned_docs/version-2.14/api/workflows/tokens.md @@ -0,0 +1,126 @@ +--- +title: Tokens +--- + + + + + +## Token Resource + +Rancher has an imperative API resource `tokens.ext.cattle.io` that allows you to generate tokens for authenticating with Rancher. + +```sh +kubectl api-resources --api-group=ext.cattle.io +``` + +To get a description of the fields and structure of the Token resource, run: + +```sh +kubectl explain tokens.ext.cattle.io +``` + +## Creating a Token + +:::caution +The Token value is only returned once in the `status.value` field. +::: + +Since Rancher v2.13.0 the `status.bearerToken` now contains a fully formed and ready-to-use Bearer token that can be used to authenticate to [Rancher API](../v3-rancher-api-guide.md). + +Only a **valid and active** Rancher user can create a Token. Otherwise, you will get an error displayed (`Error from server (Forbidden)...`) when attempting to create a Token. + +```bash +kubectl create -o jsonpath='{.status.value}' -f -< + + + +Learn about the repositories used for Rancher and Rancher docs, how to build Rancher repositories, and what information to include when you file an issue. + +For more detailed information on how to contribute to the development of Rancher projects, refer to the [Rancher Developer Wiki](https://github.com/rancher/rancher/wiki). The wiki has resources on many topics, including the following: + +- How to set up the Rancher development environment and run tests +- The typical flow of an issue through the development lifecycle +- Coding guidelines and development best practices +- Debugging and troubleshooting +- Developing the Rancher API + +On the Rancher Users Slack, the channel for developers is **#developer**. + +## Rancher Docs + +If you have suggestions for the documentation on this website, [open](https://github.com/rancher/rancher-docs/issues/new/choose) an issue in the main [Rancher docs](https://github.com/rancher/rancher-docs) repository. This repo contains documentation for Rancher v2.0 and later. + +See the [Rancher docs README](https://github.com/rancher/rancher-docs#readme) for more details on contributing to and building the Rancher v2.x docs repo. + +For documentation describing Rancher v1.6 and earlier, see the [Rancher 1.x docs](https://github.com/rancher/rancher.github.io) repo, which contains source files for https://rancher.com/docs/rancher/v1.6/en/. + +## Rancher Repositories + +All of repositories are located within our main GitHub organization. There are many repositories used for Rancher, but we'll provide descriptions of some of the main ones used in Rancher. + +Repository | URL | Description +-----------|-----|------------- +Rancher | https://github.com/rancher/rancher | This repository is the main source code for Rancher 2.x. +Types | https://github.com/rancher/types | This repository is the repository that has all the API types for Rancher 2.x. +API Framework | https://github.com/rancher/norman | This repository is an API framework for building Rancher style APIs backed by Kubernetes Custom Resources. +User Interface | https://github.com/rancher/dashboard/ | This repository is the source of the Dashboard UI. +(Rancher) Docker Machine | https://github.com/rancher/machine | This repository is the source of the Docker Machine binary used when using Node Drivers. This is a fork of the `docker/machine` repository. +machine-package | https://github.com/rancher/machine-package | This repository is used to build the Rancher Docker Machine binary. +kontainer-engine | https://github.com/rancher/kontainer-engine | This repository is the source of kontainer-engine, the tool to provision hosted Kubernetes clusters. +CLI | https://github.com/rancher/cli | This repository is the source code for the Rancher CLI used in Rancher 2.x. +(Rancher) Helm repository | https://github.com/rancher/helm | This repository is the source of the packaged Helm binary. This is a fork of the `helm/helm` repository. +loglevel repository | https://github.com/rancher/loglevel | This repository is the source of the loglevel binary, used to dynamically change log levels. + +To see all libraries/projects used in Rancher, see the [`go.mod` file](https://github.com/rancher/rancher/blob/master/go.mod) in the `rancher/rancher` repository. + +![Rancher diagram](/img/ranchercomponentsdiagram-2.6.svg)
+Rancher components used for provisioning/managing Kubernetes clusters. + +### Building Rancher Repositories + +Every repository should have a Makefile and can be built using the `make` command. The `make` targets are based on the scripts in the `/scripts` directory in the repository, and each target will use [Dapper](https://github.com/rancher/dapper) to run the target in an isolated environment. The `Dockerfile.dapper` will be used for this process, and includes all the necessary build tooling needed. + +The default target is `ci`, and will run `./scripts/validate`, `./scripts/build`, `./scripts/test` and `./scripts/package`. The resulting binaries of the build will be in `./build/bin` and are usually also packaged in a Docker image. + +### Rancher Bugs, Issues or Questions + +If you find any bugs or are having any trouble, please search the [reported issue](https://github.com/rancher/rancher/issues) as someone may have experienced the same issue or we are actively working on a solution. + +If you can't find anything related to your issue, contact us by [filing an issue](https://github.com/rancher/rancher/issues/new). Though we have many repositories related to Rancher, we want the bugs filed in the Rancher repository so we won't miss them! If you want to ask a question or ask fellow users about an use case, we suggest creating a post on the [Rancher Forums](https://forums.rancher.com). + +#### Checklist for Filing Issues + +Please follow this checklist when filing an issue which will helps us investigate and fix the issue. More info means more data we can use to determine what is causing the issue or what might be related to the issue. + +:::note + +For large amounts of data, please use [GitHub Gist](https://gist.github.com/) or similar and link the created resource in the issue. + +::: + +:::note Important: + +Please remove any sensitive data as it will be publicly viewable. + +::: + +- **Resources:** Provide as much as detail as possible on the used resources. As the source of the issue can be many things, including as much of detail as possible helps to determine the root cause. See some examples below: + - **Hosts:** What specifications does the host have, like CPU/memory/disk, what cloud does it happen on, what Amazon Machine Image are you using, what DigitalOcean droplet are you using, what image are you provisioning that we can rebuild or use when we try to reproduce + - **Operating System:** What operating system are you using? Providing specifics helps here like the output of `cat /etc/os-release` for exact OS release and `uname -r` for exact kernel used + - **Docker:** What Docker version are you using, how did you install it? Most of the details of Docker can be found by supplying output of `docker version` and `docker info` + - **Environment:** Are you in a proxy environment, are you using recognized CA/self signed certificates, are you using an external loadbalancer + - **Rancher:** What version of Rancher are you using, this can be found on the bottom left of the UI or be retrieved from the image tag you are running on the host + - **Clusters:** What kind of cluster did you create, how did you create it, what did you specify when you were creating it +- **Steps to reproduce the issue:** Provide as much detail on how you got into the reported situation. This helps the person to reproduce the situation you are in. + - Provide manual steps or automation scripts used to get from a newly created setup to the situation you reported. +- **Logs:** Provide data/logs from the used resources. + - Rancher + - Docker install + + ``` + docker logs \ + --timestamps \ + $(docker ps | grep -E "rancher/rancher:|rancher/rancher " | awk '{ print $1 }') + ``` + - Kubernetes install using `kubectl` + + :::note + + Make sure you configured the correct kubeconfig (for example, `export KUBECONFIG=$PWD/kube_config_cluster.yml` if Rancher is installed on a Kubernetes cluster) or are using the embedded kubectl via the UI. + + ::: + + ``` + kubectl -n cattle-system \ + logs \ + -l app=rancher \ + --timestamps=true + ``` + - System logging (these might not all exist, depending on operating system) + - `/var/log/messages` + - `/var/log/syslog` + - `/var/log/kern.log` + - Docker daemon logging (these might not all exist, depending on operating system) + - `/var/log/docker.log` +- **Metrics:** If you are experiencing performance issues, please provide as much of data (files or screenshots) of metrics which can help determining what is going on. If you have an issue related to a machine, it helps to supply output of `top`, `free -m`, `df` which shows processes/memory/disk usage. diff --git a/versioned_docs/version-2.14/faq/container-network-interface-providers.md b/versioned_docs/version-2.14/faq/container-network-interface-providers.md new file mode 100644 index 00000000000..ef4f647fef7 --- /dev/null +++ b/versioned_docs/version-2.14/faq/container-network-interface-providers.md @@ -0,0 +1,179 @@ +--- +title: Container Network Interface (CNI) Providers +description: Learn about Container Network Interface (CNI), the CNI providers Rancher provides, the features they offer, and how to choose a provider for you +--- + + + + + +## What is CNI? + +CNI (Container Network Interface), a [Cloud Native Computing Foundation project](https://cncf.io/), consists of a specification and libraries for writing plugins to configure network interfaces in Linux containers, along with a number of plugins. CNI concerns itself only with network connectivity of containers and removing allocated resources when the container is deleted. + +Kubernetes uses CNI as an interface between network providers and Kubernetes pod networking. + +![CNI Logo](/img/cni-logo.png) + +For more information visit [CNI GitHub project](https://github.com/containernetworking/cni). + +## What Network Models are Used in CNI? + +CNI network providers implement their network fabric using either an encapsulated network model such as Virtual Extensible Lan ([VXLAN](https://github.com/flannel-io/flannel/blob/master/Documentation/backends.md#vxlan)) or an unencapsulated network model such as Border Gateway Protocol ([BGP](https://en.wikipedia.org/wiki/Border_Gateway_Protocol)). + +### What is an Encapsulated Network? + +This network model provides a logical Layer 2 (L2) network encapsulated over the existing Layer 3 (L3) network topology that spans the Kubernetes cluster nodes. With this model you have an isolated L2 network for containers without needing routing distribution, all at the cost of minimal overhead in terms of processing and increased IP package size, which comes from an IP header generated by overlay encapsulation. Encapsulation information is distributed by UDP ports between Kubernetes workers, interchanging network control plane information about how MAC addresses can be reached. Common encapsulation used in this kind of network model is VXLAN, Internet Protocol Security (IPSec), and IP-in-IP. + +In simple terms, this network model generates a kind of network bridge extended between Kubernetes workers, where pods are connected. + +This network model is used when an extended L2 bridge is preferred. This network model is sensitive to L3 network latencies of the Kubernetes workers. If datacenters are in distinct geolocations, be sure to have low latencies between them to avoid eventual network segmentation. + +CNI network providers using this network model include Flannel, Canal, Weave, and Cilium. By default, Calico is not using this model, but it can be configured to do so. + +![Encapsulated Network](/img/encapsulated-network.png) + +### What is an Unencapsulated Network? + +This network model provides an L3 network to route packets between containers. This model doesn't generate an isolated l2 network, nor generates overhead. These benefits come at the cost of Kubernetes workers having to manage any route distribution that's needed. Instead of using IP headers for encapsulation, this network model uses a network protocol between Kubernetes workers to distribute routing information to reach pods, such as [BGP](https://en.wikipedia.org/wiki/Border_Gateway_Protocol). + +In simple terms, this network model generates a kind of network router extended between Kubernetes workers, which provides information about how to reach pods. + +This network model is used when a routed L3 network is preferred. This mode dynamically updates routes at the OS level for Kubernetes workers. It's less sensitive to latency. + +CNI network providers using this network model include Calico and Cilium. Cilium may be configured with this model although it is not the default mode. + +![Unencapsulated Network](/img/unencapsulated-network.png) + +## What CNI Providers are Provided by Rancher? + +### RKE2 Kubernetes clusters + +Out-of-the-box, Rancher provides the following CNI network providers for RKE2 Kubernetes clusters: Calico, Canal, Cilium, and Flannel. + +You can choose your CNI network provider when you create new Kubernetes clusters from Rancher. + +#### Calico + +![Calico Logo](/img/calico-logo.png) + +Calico enables networking and network policy in Kubernetes clusters across the cloud. By default, Calico uses a pure, unencapsulated IP network fabric and policy engine to provide networking for your Kubernetes workloads. Workloads are able to communicate over both cloud infrastructure and on-prem using BGP. + +Calico also provides a stateless IP-in-IP or VXLAN encapsulation mode that can be used, if necessary. Calico also offers policy isolation, allowing you to secure and govern your Kubernetes workloads using advanced ingress and egress policies. + +Kubernetes workers should open TCP port `179` if using BGP or UDP port `4789` if using VXLAN encapsulation. In addition, TCP port `5473` is needed when using Typha. See [the port requirements for user clusters](../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/node-requirements-for-rancher-managed-clusters.md#networking-requirements) for more details. + +:::note Important: + +In Rancher v2.6.3, Calico probes fail on Windows nodes upon RKE2 installation. Note that this issue is resolved in v2.6.4. + +- To work around this issue, first navigate to `https:///v3/settings/windows-rke2-install-script`. + +- There, change the current setting: `https://raw.githubusercontent.com/rancher/wins/v0.1.3/install.ps1` to this new setting: `https://raw.githubusercontent.com/rancher/rke2/master/windows/rke2-install.ps1`. + +::: + +![Calico Diagram](/img/calico-diagram.svg) + +For more information, see the following pages: + +- [Project Calico Official Site](https://www.projectcalico.org/) +- [Project Calico GitHub Page](https://github.com/projectcalico/calico) + +#### Canal + +![Canal Logo](/img/canal-logo.png) + +Canal is a CNI network provider that gives you the best of Flannel and Calico. It allows users to easily deploy Calico and Flannel networking together as a unified networking solution, combining Calico’s network policy enforcement with the rich superset of Calico (unencapsulated) and/or Flannel (encapsulated) network connectivity options. + +In Rancher, Canal is the default CNI network provider combined with Flannel and VXLAN encapsulation. + +Kubernetes workers should open UDP port `8472` (VXLAN) and TCP port `9099` (health checks). If using Wireguard, you should open UDP ports `51820` and `51821`. For more details, refer to [the port requirements for user clusters](../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/node-requirements-for-rancher-managed-clusters.md). + +![](/img/canal-diagram.png) + +For more information, refer to the [Rancher maintained Canal source](https://github.com/rancher/rke2-charts/tree/main-source/packages/rke2-canal) and the [Canal GitHub Page](https://github.com/projectcalico/canal). + +#### Cilium + +![Cilium Logo](/img/cilium-logo.png) + +Cilium enables networking and network policies (L3, L4, and L7) in Kubernetes. By default, Cilium uses eBPF technologies to route packets inside the node and VXLAN to send packets to other nodes. Unencapsulated techniques can also be configured. + +Cilium recommends kernel versions greater than 5.2 to be able to leverage the full potential of eBPF. Kubernetes workers should open TCP port `8472` for VXLAN and TCP port `4240` for health checks. In addition, ICMP 8/0 must be enabled for health checks. For more information, check [Cilium System Requirements](https://docs.cilium.io/en/latest/operations/system_requirements/#firewall-requirements). + +##### Ingress Routing Across Nodes in Cilium +
+By default, Cilium does not allow pods to contact pods on other nodes. To work around this, enable the ingress controller to route requests across nodes with a `CiliumNetworkPolicy`. + +After selecting the Cilium CNI and enabling Project Network Isolation for your new cluster, configure as follows: + +``` +apiVersion: cilium.io/v2 +kind: CiliumNetworkPolicy +metadata: + name: hn-nodes + namespace: default +spec: + endpointSelector: {} + ingress: + - fromEntities: + - remote-node +``` + +#### Flannel + +![Flannel Logo](/img/flannel-logo.png) + +Flannel is a simple and easy way to configure L3 network fabric designed for Kubernetes. Flannel runs a single binary agent named flanneld on each host, which is responsible for allocating a subnet lease to each host out of a larger, preconfigured address space. Flannel uses either the Kubernetes API or etcd directly to store the network configuration, the allocated subnets, and any auxiliary data (such as the host's public IP). Packets are forwarded using one of several backend mechanisms, with the default encapsulation being [VXLAN](https://github.com/flannel-io/flannel/blob/master/Documentation/backends.md#vxlan). + +Encapsulated traffic is unencrypted by default. Flannel provides two solutions for encryption: + +* [IPSec](https://github.com/flannel-io/flannel/blob/master/Documentation/backends.md#ipsec), which makes use of [strongSwan](https://www.strongswan.org/) to establish encrypted IPSec tunnels between Kubernetes workers. It is an experimental backend for encryption. +* [WireGuard](https://github.com/flannel-io/flannel/blob/master/Documentation/backends.md#wireguard), which is a more faster-performing alternative to strongSwan. + +Kubernetes workers should open UDP port `8472` (VXLAN). See [the port requirements for user clusters](../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/node-requirements-for-rancher-managed-clusters.md#networking-requirements) for more details. + +![Flannel Diagram](/img/flannel-diagram.png) + +For more information, see the [Flannel GitHub Page](https://github.com/flannel-io/flannel). + +## CNI Features by Provider + +The following table summarizes the different features available for each CNI network provider provided by Rancher. + +| Provider | Network Model | Route Distribution | Network Policies | Mesh | External Datastore | Encryption | Ingress/Egress Policies | +| ---- | ---- | ---- | ---- | ---- | ---- | ---- | ---- | +| Canal | Encapsulated (VXLAN) | No | Yes | No | K8s API | Yes | Yes | +| Flannel | Encapsulated (VXLAN) | No | No | No | K8s API | Yes | No | +| Calico | Encapsulated (VXLAN,IPIP) OR Unencapsulated | Yes | Yes | Yes | Etcd and K8s API | Yes | Yes | +| Weave | Encapsulated | Yes | Yes | Yes | No | Yes | Yes | +| Cilium | Encapsulated (VXLAN) | Yes | Yes | Yes | Etcd and K8s API | Yes | Yes | + +- Network Model: Encapsulated or unencapsulated. For more information, see [What Network Models are Used in CNI?](#what-network-models-are-used-in-cni) + +- Route Distribution: An exterior gateway protocol designed to exchange routing and reachability information on the Internet. BGP can assist with pod-to-pod networking between clusters. This feature is a must on unencapsulated CNI network providers, and it is typically done by BGP. If you plan to build clusters split across network segments, route distribution is a feature that's nice-to-have. + +- Network Policies: Kubernetes offers functionality to enforce rules about which services can communicate with each other using network policies. This feature is stable as of Kubernetes v1.7 and is ready to use with certain networking plugins. + +- Mesh: This feature allows service-to-service networking communication between distinct Kubernetes clusters. + +- External Datastore: CNI network providers with this feature need an external datastore for its data. + +- Encryption: This feature allows cyphered and secure network control and data planes. + +- Ingress/Egress Policies: This feature allows you to manage routing control for both Kubernetes and non-Kubernetes communications. + +## CNI Community Popularity + + + +## Which CNI Provider Should I Use? + +It depends on your project needs. There are many different providers, which each have various features and options. There isn't one provider that meets everyone's needs. + +Canal is the default CNI network provider. We recommend it for most use cases. It provides encapsulated networking for containers with Flannel, while adding Calico network policies that can provide project/namespace isolation in terms of networking. + +## How can I configure a CNI network provider? + +Please see [Cluster Options](../reference-guides/cluster-configuration/rancher-server-configuration/rke2-cluster-configuration.md) on how to configure a network provider for your cluster. For more advanced configuration options, please see how to configure your cluster using a [Config File](../reference-guides/cluster-configuration/rancher-server-configuration/rke2-cluster-configuration.md#cluster-config-file-reference). diff --git a/versioned_docs/version-2.14/faq/deprecated-features.md b/versioned_docs/version-2.14/faq/deprecated-features.md new file mode 100644 index 00000000000..4e452e77376 --- /dev/null +++ b/versioned_docs/version-2.14/faq/deprecated-features.md @@ -0,0 +1,22 @@ +--- +title: Deprecated Features in Rancher +--- + + + + + +## Where can I find out which features have been deprecated in Rancher? + +Rancher will publish deprecated features as part of the [release notes](https://github.com/rancher/rancher/releases) for Rancher found on GitHub. Please consult the following patch releases for deprecated features: + +| Patch Version | Release Date | +|---------------|---------------| +| [2.13.3](https://github.com/rancher/rancher/releases/tag/v2.13.3) | February 25, 2026 | +| [2.13.2](https://github.com/rancher/rancher/releases/tag/v2.13.2) | January 29, 2026 | +| [2.13.1](https://github.com/rancher/rancher/releases/tag/v2.13.1) | December 18, 2025 | +| [2.13.0](https://github.com/rancher/rancher/releases/tag/v2.13.0) | November 25, 2025 | + +## What can I expect when a feature is marked for deprecation? + +In the release where functionality is marked as "Deprecated", it will still be available and supported allowing upgrades to follow the usual procedure. Once upgraded, users/admins should start planning to move away from the deprecated functionality before upgrading to the release it marked as removed. The recommendation for new deployments is to not use the deprecated feature. diff --git a/versioned_docs/version-2.14/faq/general-faq.md b/versioned_docs/version-2.14/faq/general-faq.md new file mode 100644 index 00000000000..ca78093f97d --- /dev/null +++ b/versioned_docs/version-2.14/faq/general-faq.md @@ -0,0 +1,47 @@ +--- +title: General FAQ +--- + + + + + +This FAQ is a work in progress designed to answer the questions most frequently asked about Rancher v2.x. + +See the [Technical FAQ](technical-items.md) for frequently asked technical questions. + +## Is it possible to manage Azure Kubernetes Services with Rancher v2.x? + +Yes. See our [Cluster Administration](../how-to-guides/new-user-guides/manage-clusters/manage-clusters.md) guide for what Rancher features are available on AKS, as well as our [documentation on AKS](../getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/rancher-on-aks.md). + +## Does Rancher support Windows? + +Yes. Rancher supports Windows Server 1809 containers. For details on how to set up a cluster with Windows worker nodes, refer to the section on [configuring custom clusters for Windows.](../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/use-windows-clusters/use-windows-clusters.md) + +## Does Rancher support Istio? + +Yes. Rancher supports [Istio](../integrations-in-rancher/istio/istio.md). + +## Will Rancher v2.x support Hashicorp's Vault for storing secrets? + +As of Rancher v2.9, Rancher [supports authentication with service account tokens](../how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/jwt-authentication.md), which is used by Vault and other integrations. + +## Does Rancher v2.x support RKT containers as well? + +At this time, we only support Docker. + +## Does Rancher v2.x support Calico, Contiv, Contrail, Flannel, Weave net, etc., for embedded and registered Kubernetes? + +Out-of-the-box, Rancher provides the following CNI network providers for Kubernetes clusters: Canal, Flannel, Calico and Weave. Always refer to the [Rancher Support Matrix](https://rancher.com/support-maintenance-terms/) for details about what is officially supported. + +## Are you planning on supporting Traefik for existing setups? + +We don't currently plan on providing embedded Traefik support, but we're still exploring load-balancing approaches. + +## Can I import OpenShift Kubernetes clusters into v2.x? + +Our goal is to run any Kubernetes clusters. Therefore, Rancher v2.x should work with OpenShift, but we haven't tested it yet. + +## Is Longhorn integrated with Rancher? + +Yes. Longhorn is integrated with Rancher v2.5 and later. diff --git a/versioned_docs/version-2.14/faq/install-and-configure-kubectl.md b/versioned_docs/version-2.14/faq/install-and-configure-kubectl.md new file mode 100644 index 00000000000..3022cae6816 --- /dev/null +++ b/versioned_docs/version-2.14/faq/install-and-configure-kubectl.md @@ -0,0 +1,27 @@ +--- +title: Installing and Configuring kubectl +--- + + + + + +`kubectl` is a CLI utility for running commands against Kubernetes clusters. It's required for many maintenance and administrative tasks in Rancher 2.x. + +## Installation + +See [kubectl Installation](https://kubernetes.io/docs/tasks/tools/install-kubectl/) for installation on your operating system. + +## Configuration + +When you create a Kubernetes cluster with RKE2/K3s, the Kubeconfig file is stored at `/etc/rancher/rke2/rke2.yaml` or `/etc/rancher/k3s/k3s.yaml` depending on your chosen distribution. These files are used to configure access to the Kubernetes cluster. + +Test your connectivity with `kubectl` and see if you can get the list of nodes back. + +```shell +kubectl get nodes + NAME STATUS ROLES AGE VERSION +165.227.114.63 Ready controlplane,etcd,worker 11m v1.10.1 +165.227.116.167 Ready controlplane,etcd,worker 11m v1.10.1 +165.227.127.226 Ready controlplane,etcd,worker 11m v1.10.1 +``` diff --git a/versioned_docs/version-2.14/faq/rancher-is-no-longer-needed.md b/versioned_docs/version-2.14/faq/rancher-is-no-longer-needed.md new file mode 100644 index 00000000000..e1d1f759206 --- /dev/null +++ b/versioned_docs/version-2.14/faq/rancher-is-no-longer-needed.md @@ -0,0 +1,65 @@ +--- +title: Rancher is No Longer Needed +--- + + + + + +This page is intended to answer questions about what happens if you don't want Rancher anymore, if you don't want a cluster to be managed by Rancher anymore, or if the Rancher server is deleted. + + +## If the Rancher server is deleted, what happens to the workloads in my downstream clusters? + +If Rancher is ever deleted or unrecoverable, all workloads in the downstream Kubernetes clusters managed by Rancher will continue to function as normal. + +## If the Rancher server is deleted, how do I access my downstream clusters? + +The capability to access a downstream cluster without Rancher depends on the type of cluster and the way that the cluster was created. To summarize: + +- **Registered/Imported clusters:** The cluster will be unaffected and you can access the cluster using the same methods that you did before the cluster was registered into Rancher. +- **Hosted Kubernetes clusters:** If you created the cluster in a cloud-hosted Kubernetes provider such as EKS, GKE, or AKS, you can continue to manage the cluster using your provider's cloud credentials. +- **Rancher provisioned clusters:** To access an [RKE2/K3s cluster](../how-to-guides/new-user-guides/launch-kubernetes-with-rancher/launch-kubernetes-with-rancher.md) the cluster must have the [authorized cluster endpoint](../reference-guides/rancher-manager-architecture/communicating-with-downstream-user-clusters.md#4-authorized-cluster-endpoint) enabled, and you must have already downloaded the cluster's kubeconfig file from the Rancher UI. With this endpoint, you can access your cluster with kubectl directly instead of communicating through the Rancher server's [authentication proxy.](../reference-guides/rancher-manager-architecture/communicating-with-downstream-user-clusters.md#1-the-authentication-proxy) For instructions on how to configure kubectl to use the authorized cluster endpoint, refer to the section about directly accessing clusters with [kubectl and the kubeconfig file.](../how-to-guides/new-user-guides/manage-clusters/access-clusters/use-kubectl-and-kubeconfig.md#authenticating-directly-with-a-downstream-cluster) These clusters will use a snapshot of the authentication as it was configured when Rancher was removed. + +## What if I don't want Rancher anymore? + +:::note + +The previously recommended [System Tools](../reference-guides/system-tools.md) has been deprecated since June 2022. + +::: + +If you [installed Rancher on a Kubernetes cluster,](../getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/install-upgrade-on-a-kubernetes-cluster.md) remove Rancher by using the [Rancher Cleanup](https://github.com/rancher/rancher-cleanup) tool. + +Uninstalling Rancher in high-availability (HA) mode will also remove all `helm-operation-*` pods and the following apps: + +- fleet +- fleet-agent +- rancher-operator +- rancher-webhook + +Custom resources (CRDs) and custom namespaces will still need to be manually removed. + +If you installed Rancher with Docker, you can uninstall Rancher by removing the single Docker container that it runs in. + +Imported clusters will not be affected by Rancher being removed. For other types of clusters, refer to the section on [accessing downstream clusters when Rancher is removed.](#if-the-rancher-server-is-deleted-how-do-i-access-my-downstream-clusters) + +## What if I don't want my registered cluster managed by Rancher? + +If a registered cluster is deleted from the Rancher UI, the cluster is detached from Rancher, leaving it intact and accessible by the same methods that were used to access it before it was registered in Rancher. + +To detach the cluster, + +1. In the upper left corner, click **☰ > Cluster Management**. +2. Go to the registered cluster that should be detached from Rancher and click **⋮ > Delete**. +3. Click **Delete**. + +**Result:** The registered cluster is detached from Rancher and functions normally outside of Rancher. + +## What if I don't want my hosted Kubernetes cluster managed by Rancher? + +At this time, there is no functionality to detach these clusters from Rancher. In this context, "detach" is defined as the ability to remove Rancher components from the cluster and manage access to the cluster independently of Rancher. + +The capability to manage these clusters without Rancher is being tracked in this [issue.](https://github.com/rancher/rancher/issues/25234) + +For information about how to access clusters if the Rancher server is deleted, refer to [this section.](#if-the-rancher-server-is-deleted-how-do-i-access-my-downstream-clusters) \ No newline at end of file diff --git a/versioned_docs/version-2.14/faq/security.md b/versioned_docs/version-2.14/faq/security.md new file mode 100644 index 00000000000..165fea2ba91 --- /dev/null +++ b/versioned_docs/version-2.14/faq/security.md @@ -0,0 +1,21 @@ +--- +title: Security FAQ +--- + + + + + +## Is there a Hardening Guide? + +The Hardening Guide is located in the main [Security](../reference-guides/rancher-security/rancher-security.md) section. + +## Have hardened Rancher Kubernetes clusters been evaluated by the CIS Kubernetes Benchmark? Where can I find the results? + +We have run the CIS Kubernetes benchmark against a hardened Rancher Kubernetes cluster. The results of that assessment can be found in the main [Security](../reference-guides/rancher-security/rancher-security.md) section. + +## How does Rancher verify communication with downstream clusters, and what are some associated security concerns? + +Communication between the Rancher server and downstream clusters is performed through agents. Rancher uses either a registered certificate authority (CA) bundle or the local trust store to verify communication between Rancher agents and the Rancher server. Using a CA bundle for verification is more strict, as only the certificates based on that bundle are trusted. If TLS verification for a explicit CA bundle fails, Rancher may fall back to using the local trust store for verifying future communication. Any CA within the local trust store can then be used to generate a valid certificate. + +As described in [Rancher Security Update CVE-2024-22030](https://www.suse.com/c/rancher-security-update/), under a narrow set of circumstances, malicious actors can take over Rancher nodes by exploiting the behavior of Rancher CAs. For the attack to succeed, the malicious actor must generate a valid certificate from either a valid CA in the targeted Rancher server, or from a valid registered CA. The attacker also needs to either hijack or spoof the Rancher server-url as a preliminary step. Rancher is currently evaluating Rancher CA behavior to mitigate against this and any similar avenues of attack. diff --git a/versioned_docs/version-2.14/faq/technical-items.md b/versioned_docs/version-2.14/faq/technical-items.md new file mode 100644 index 00000000000..cdf29707617 --- /dev/null +++ b/versioned_docs/version-2.14/faq/technical-items.md @@ -0,0 +1,184 @@ +--- +title: Technical FAQ +--- + + + + + +## How can I reset the administrator password? + +Docker install: + +``` +$ docker exec -ti reset-password +New password for default administrator (user-xxxxx): + +``` + +Kubernetes install (Helm): + +``` +$ KUBECONFIG=./kube_config_cluster.yml +$ kubectl --kubeconfig $KUBECONFIG -n cattle-system exec $(kubectl --kubeconfig $KUBECONFIG -n cattle-system get pods -l app=rancher --no-headers | head -1 | awk '{ print $1 }') -c rancher -- reset-password +New password for default administrator (user-xxxxx): + +``` + +## I deleted/deactivated the last admin, how can I fix it? + +Docker install: + +``` +$ docker exec -ti ensure-default-admin +New default administrator (user-xxxxx) +New password for default administrator (user-xxxxx): + +``` + +Kubernetes install (Helm): + +``` +$ KUBECONFIG=./kube_config_cluster.yml +$ kubectl --kubeconfig $KUBECONFIG -n cattle-system exec $(kubectl --kubeconfig $KUBECONFIG -n cattle-system get pods -l app=rancher | grep '1/1' | head -1 | awk '{ print $1 }') -- ensure-default-admin +New password for default administrator (user-xxxxx): + +``` + +## How can I enable debug logging? + +See [Troubleshooting: Logging](../troubleshooting/other-troubleshooting-tips/logging.md) + +## My ClusterIP does not respond to ping + +ClusterIP is a virtual IP, which will not respond to ping. Best way to test if the ClusterIP is configured correctly, is by using `curl` to access the IP and port to see if it responds. + +## Where can I manage Node Templates? + +Node Templates can be accessed by opening your account menu (top right) and selecting `Node Templates`. + +## Why is my Layer-4 Load Balancer in `Pending` state? + +The Layer-4 Load Balancer is created as `type: LoadBalancer`. In Kubernetes, this needs a cloud provider or controller that can satisfy these requests, otherwise these will be in `Pending` state forever. More information can be found on [Cloud Providers](../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-cloud-providers/set-up-cloud-providers.md) or [Create External Load Balancer](https://kubernetes.io/docs/tasks/access-application-cluster/create-external-load-balancer/) + +## Where is the state of Rancher stored? + +- Docker Install: in the embedded etcd of the `rancher/rancher` container, located at `/var/lib/rancher`. +- Kubernetes install: default location is in the `/var/lib/rancher/rke2` or `/var/lib/rancher/k3s` directories of the respective RKE2/K3s cluster created to run Rancher. + +## How are the supported Docker versions determined? + +We follow the validated Docker versions for upstream Kubernetes releases. The validated versions can be found under [External Dependencies](https://github.com/kubernetes/kubernetes/blob/master/CHANGELOG/CHANGELOG-1.10.md#external-dependencies) in the Kubernetes release CHANGELOG.md. + +## How can I access nodes created by Rancher? + +SSH keys to access the nodes created by Rancher can be downloaded via the **Nodes** view. Choose the node which you want to access and click on the vertical ⋮ button at the end of the row, and choose **Download Keys** as shown in the picture below. + +![Download Keys](/img/downloadsshkeys.png) + +Unzip the downloaded zip file, and use the file `id_rsa` to connect to you host. Be sure to use the correct username (`rancher` or `docker` for RancherOS, `ubuntu` for Ubuntu, `ec2-user` for Amazon Linux) + +``` +$ ssh -i id_rsa user@ip_of_node +``` + +## How can I automate task X in Rancher? + +The UI consists of static files, and works based on responses of the API. That means every action/task that you can execute in the UI, can be automated via the API. There are 2 ways to do this: + +* Visit `https://your_rancher_ip/v3` and browse the API options. +* Capture the API calls when using the UI (Most commonly used for this is [Chrome Developer Tools](https://developers.google.com/web/tools/chrome-devtools/#network) but you can use anything you like) + +## The IP address of a node changed, how can I recover? + +A node is required to have a static IP configured (or a reserved IP via DHCP). If the IP of a node has changed, you will have to remove it from the cluster and add it again. After it is removed, Rancher will update the cluster to the correct state. If the cluster is no longer in `Provisioning` state, the node is removed from the cluster. + +When the IP address of the node changed, Rancher lost connection to the node, so it will be unable to clean the node properly. See [Cleaning cluster nodes](../how-to-guides/new-user-guides/manage-clusters/clean-cluster-nodes.md) to clean the node. + +When the node is removed from the cluster, and the node is cleaned, you can add the node to the cluster. + +## How can I add more arguments/binds/environment variables to Kubernetes components in a Rancher Launched Kubernetes cluster? + +You can add more arguments/binds/environment variables via the respective [RKE2 Config File](../reference-guides/cluster-configuration/rancher-server-configuration/rke2-cluster-configuration.md#cluster-configuration) or [K3s Config File](../reference-guides/cluster-configuration/rancher-server-configuration/k3s-cluster-configuration.md#cluster-configuration). + +## How do I check if my certificate chain is valid? + +Use the `openssl verify` command to validate your certificate chain: + +:::tip + +Configure `SSL_CERT_DIR` and `SSL_CERT_FILE` to a dummy location to make sure the OS-installed certificates are not used when verifying manually. + +::: + +``` +SSL_CERT_DIR=/dummy SSL_CERT_FILE=/dummy openssl verify -CAfile ca.pem rancher.yourdomain.com.pem +rancher.yourdomain.com.pem: OK +``` + +If you receive the error `unable to get local issuer certificate`, the chain is incomplete. This usually means that there is an intermediate CA certificate that issued your server certificate. If you already have this certificate, you can use it in the verification of the certificate like shown below: + +``` +SSL_CERT_DIR=/dummy SSL_CERT_FILE=/dummy openssl verify -CAfile ca.pem -untrusted intermediate.pem rancher.yourdomain.com.pem +rancher.yourdomain.com.pem: OK +``` + +If you have successfully verified your certificate chain, you should include needed intermediate CA certificates in the server certificate to complete the certificate chain for any connection made to Rancher (for example, by the Rancher agent). The order of the certificates in the server certificate file should be first the server certificate itself (contents of `rancher.yourdomain.com.pem`), followed by intermediate CA certificate(s) (contents of `intermediate.pem`). + +``` +-----BEGIN CERTIFICATE----- +%YOUR_CERTIFICATE% +-----END CERTIFICATE----- +-----BEGIN CERTIFICATE----- +%YOUR_INTERMEDIATE_CERTIFICATE% +-----END CERTIFICATE----- +``` + +If you still get errors during verification, you can retrieve the subject and the issuer of the server certificate using the following command: + +``` +openssl x509 -noout -subject -issuer -in rancher.yourdomain.com.pem +subject= /C=GB/ST=England/O=Alice Ltd/CN=rancher.yourdomain.com +issuer= /C=GB/ST=England/O=Alice Ltd/CN=Alice Intermediate CA +``` + +## How do I check `Common Name` and `Subject Alternative Names` in my server certificate? + +Although technically an entry in `Subject Alternative Names` is required, having the hostname in both `Common Name` and as entry in `Subject Alternative Names` gives you maximum compatibility with older browser/applications. + +Check `Common Name`: + +``` +openssl x509 -noout -subject -in cert.pem +subject= /CN=rancher.my.org +``` + +Check `Subject Alternative Names`: + +``` +openssl x509 -noout -in cert.pem -text | grep DNS + DNS:rancher.my.org +``` + +## Why does it take 5+ minutes for a pod to be rescheduled when a node has failed? + +This is due to a combination of the following default Kubernetes settings: + +* kubelet + * `node-status-update-frequency`: Specifies how often kubelet posts node status to master (default 10s) +* kube-controller-manager + * `node-monitor-period`: The period for syncing NodeStatus in NodeController (default 5s) + * `node-monitor-grace-period`: Amount of time which we allow running Node to be unresponsive before marking it unhealthy (default 40s) + * `pod-eviction-timeout`: The grace period for deleting pods on failed nodes (default 5m0s) + +See [Kubernetes: kubelet](https://kubernetes.io/docs/reference/command-line-tools-reference/kubelet/) and [Kubernetes: kube-controller-manager](https://kubernetes.io/docs/reference/command-line-tools-reference/kube-controller-manager/) for more information on these settings. + +In Kubernetes v1.13, the `TaintBasedEvictions` feature is enabled by default. See [Kubernetes: Taint based Evictions](https://kubernetes.io/docs/concepts/configuration/taint-and-toleration/#taint-based-evictions) for more information. + +* kube-apiserver (Kubernetes v1.13 and up) + * `default-not-ready-toleration-seconds`: Indicates the tolerationSeconds of the toleration for notReady:NoExecute that is added by default to every pod that does not already have such a toleration. + * `default-unreachable-toleration-seconds`: Indicates the tolerationSeconds of the toleration for unreachable:NoExecute that is added by default to every pod that does not already have such a toleration. + +## Can I use keyboard shortcuts in the UI? + +Yes, most parts of the UI can be reached using keyboard shortcuts. For an overview of the available shortcuts, press `?` anywhere in the UI. diff --git a/versioned_docs/version-2.14/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/air-gapped-upgrades.md b/versioned_docs/version-2.14/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/air-gapped-upgrades.md new file mode 100644 index 00000000000..e7ded014194 --- /dev/null +++ b/versioned_docs/version-2.14/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/air-gapped-upgrades.md @@ -0,0 +1,101 @@ +--- +title: Upgrading in an Air-Gapped Environment +--- + + + + + +:::note + +These instructions assume you have already followed the instructions for a Kubernetes upgrade on [this page,](upgrades.md) including the prerequisites, up until step 3. Upgrade Rancher. + +::: + +## Rancher Helm Upgrade Options + +To upgrade with Helm, apply the same options that you used when installing Rancher. Refer to the reference table below to replace each placeholder. Rancher needs to be configured to use the private registry in order to provision any Rancher launched Kubernetes clusters or Rancher tools. + +Based on the choice you made during installation, complete one of the procedures below. + +Placeholder | Description +------------|------------- +`` | The version number of the output tarball. +`` | The DNS name you pointed at your load balancer. +`` | The DNS name for your private registry. +`` | Cert-manager version running on k8s cluster. + + +### Option A: Default Self-signed Certificate + +``` +helm upgrade rancher ./rancher-.tgz \ + --namespace cattle-system \ + --set hostname= \ + --set certmanager.version= \ + --set rancherImage=/rancher/rancher \ + --set systemDefaultRegistry= \ # Set a default private registry to be used in Rancher + --set useBundledSystemChart=true # Use the packaged Rancher system charts +``` + +#### Resolving UPGRADE FAILED Error + +If you encounter the error message, `Error: UPGRADE FAILED: "rancher" has no deployed releases`, Rancher might have been installed via the `helm template` command. To successfully upgrade Rancher, use the following command instead: + +``` +helm template rancher ./rancher-.tgz --output-dir . \ + --no-hooks \ # prevent files for Helm hooks from being generated + --namespace cattle-system \ + --set hostname= \ + --set certmanager.version= \ + --set rancherImage=/rancher/rancher \ + --set systemDefaultRegistry= \ # Set a default private registry to be used in Rancher + --set useBundledSystemChart=true # Use the packaged Rancher system charts +``` + +After you run the Helm command, apply the rendered template: + +``` +kubectl -n cattle-system apply -R -f ./rancher +``` + +### Option B: Certificates from Files using Kubernetes Secrets + +```plain +helm upgrade rancher ./rancher-.tgz \ + --namespace cattle-system \ + --set hostname= \ + --set rancherImage=/rancher/rancher \ + --set ingress.tls.source=secret \ + --set systemDefaultRegistry= \ # Set a default private registry to be used in Rancher + --set useBundledSystemChart=true # Use the packaged Rancher system charts +``` + +If you are using a Private CA signed cert, add `--set privateCA=true` following `--set ingress.tls.source=secret`: + +```plain +helm upgrade rancher ./rancher-.tgz \ + --namespace cattle-system \ + --set hostname= \ + --set rancherImage=/rancher/rancher \ + --set ingress.tls.source=secret \ + --set privateCA=true \ + --set systemDefaultRegistry= \ # Set a default private registry to be used in Rancher + --set useBundledSystemChart=true # Use the packaged Rancher system charts +``` + +## Verify the Upgrade + +Log into Rancher to confirm that the upgrade succeeded. + +:::tip + +Having network issues following upgrade? + +See [Restoring Cluster Networking](https://github.com/rancher/rancher-docs/tree/main/archived_docs/en/version-2.0-2.4/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/upgrades/namespace-migration.md). + +::: + +## Known Upgrade Issues + +A list of known issues for each Rancher version can be found in the release notes on [GitHub](https://github.com/rancher/rancher/releases) and on the [Rancher forums.](https://forums.rancher.com/c/announcements/12) diff --git a/versioned_docs/version-2.14/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/install-upgrade-on-a-kubernetes-cluster.md b/versioned_docs/version-2.14/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/install-upgrade-on-a-kubernetes-cluster.md new file mode 100644 index 00000000000..90b23876201 --- /dev/null +++ b/versioned_docs/version-2.14/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/install-upgrade-on-a-kubernetes-cluster.md @@ -0,0 +1,390 @@ +--- +title: Install/Upgrade Rancher on a Kubernetes Cluster +description: Learn how to install Rancher in development and production environments. Read about single node and high availability installation +--- + + + + + +In this section, you'll learn how to deploy Rancher on a Kubernetes cluster using the Helm CLI. + + +## Prerequisites + +- [Kubernetes Cluster](#kubernetes-cluster) +- [Ingress Controller](#ingress-controller) +- [CLI Tools](#cli-tools) + +### Kubernetes Cluster + +Set up the Rancher server's local Kubernetes cluster. + +Rancher can be installed on any Kubernetes cluster. This cluster can use upstream Kubernetes, or it can use one of Rancher's Kubernetes distributions, or it can be a managed Kubernetes cluster from a provider such as Amazon EKS. + +For help setting up a Kubernetes cluster, we provide these tutorials: + +- **K3s:** For the tutorial to install a K3s Kubernetes cluster, refer to [this page.](../../../how-to-guides/new-user-guides/kubernetes-cluster-setup/k3s-for-rancher.md) For help setting up the infrastructure for a high-availability K3s cluster, refer to [this page.](../../../how-to-guides/new-user-guides/infrastructure-setup/ha-k3s-kubernetes-cluster.md) +- **RKE2:** For the tutorial to install an RKE2 Kubernetes cluster, refer to [this page.](../../../how-to-guides/new-user-guides/kubernetes-cluster-setup/rke2-for-rancher.md) For help setting up the infrastructure for a high-availability RKE2 cluster, refer to [this page.](../../../how-to-guides/new-user-guides/infrastructure-setup/ha-rke2-kubernetes-cluster.md) +- **Amazon EKS:** For details on how to install Rancher on Amazon EKS, including how to install an Ingress controller so that the Rancher server can be accessed, refer to [this page.](rancher-on-amazon-eks.md) +- **AKS:** For details on how to install Rancher with Azure Kubernetes Service, including how to install an Ingress controller so that the Rancher server can be accessed, refer to [this page.](rancher-on-aks.md) +- **GKE:** For details on how to install Rancher with Google Kubernetes Engine, including how to install an Ingress controller so that the Rancher server can be accessed, refer to [this page.](rancher-on-gke.md) GKE has two modes of operation when creating a Kubernetes cluster, Autopilot and Standard mode. The cluster configuration for Autopilot mode has restrictions on editing the kube-system namespace. However, Rancher needs to create resources in the kube-system namespace during installation. As a result, you will not be able to install Rancher on a GKE cluster created in Autopilot mode. + + +### Ingress Controller + +The Rancher UI and API are exposed through an Ingress. This means the Kubernetes cluster that you install Rancher in must contain an Ingress controller. + +For RKE2 and K3s installations, you don't have to install the Ingress controller manually because one is installed by default. + +For distributions that do not include an Ingress Controller by default, like a hosted Kubernetes cluster such as EKS, GKE, or AKS, you have to deploy an Ingress controller first. Note that the Rancher Helm chart does not set an `ingressClassName` on the ingress by default. Because of this, you have to configure the Ingress controller to also watch ingresses without an `ingressClassName`. + +Examples are included in the **Amazon EKS**, **AKS**, and **GKE** tutorials above. + +### CLI Tools + +The following CLI tools are required for setting up the Kubernetes cluster. Please make sure these tools are installed and available in your `$PATH`. + +- [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/#install-kubectl) - Kubernetes command-line tool. +- [helm](https://docs.helm.sh/using_helm/#installing-helm) - Package management for Kubernetes. Refer to the [Helm version requirements](../resources/helm-version-requirements.md) to choose a version of Helm to install Rancher. Refer to the [instructions provided by the Helm project](https://helm.sh/docs/intro/install/) for your specific platform. + +## Install the Rancher Helm Chart + +:::important + +**Important:** In Rancher Community v2.13.1 if your registry configuration is one of the following you may see Rancher generate the `cattle-cluster-agent` image with an incorrect `docker.io` path segment: + +- Environments where a **cluster-scoped container registry** is configured for system images. +- Environments where a **global `system-default-registry`** is configured (e.g. airgap setups), even if no cluster-scoped registry is set. + +**Workaround for Affected Setups:** As a workaround, override the `cattle-cluster-agent` image via the `CATTLE_AGENT_IMAGE` environment variable. This value must **not** contain any registry prefix (Rancher will handle that automatically). It should be set only to the repository and tag, for example:`rancher/rancher-agent:v2.13.1` + +**Helm `install` example:** + +```bash +helm install rancher rancher-latest/rancher \ +... + --set extraEnv[0].name=CATTLE_AGENT_IMAGE \ + --set extraEnv[0].value=rancher/rancher-agent:v2.13.1 +``` + +**Helm `upgrade` example:** + +```bash +helm upgrade rancher rancher-latest/rancher \ +... + --set extraEnv[0].name=CATTLE_AGENT_IMAGE \ + --set extraEnv[0].value=rancher/rancher-agent:v2.13.1 +``` + +**Important Upgrade Note:** + +The `CATTLE_AGENT_IMAGE` override is intended only as a temporary workaround for the affected configurations. Once a Rancher version is available that corrects this behavior, the `CATTLE_AGENT_IMAGE` override should be **removed** from Helm values, so that Rancher can resume managing the agent image normally and automatically track future image and tag changes. See [#53187](https://github.com/rancher/rancher/issues/53187#issuecomment-3676484603) for further information. +::: + +Rancher is installed using the [Helm](https://helm.sh/) package manager for Kubernetes. Helm charts provide templating syntax for Kubernetes YAML manifest documents. With Helm, we can create configurable deployments instead of just using static files. + +For systems without direct internet access, see [Air Gap: Kubernetes install](../other-installation-methods/air-gapped-helm-cli-install/install-rancher-ha.md). + +To choose a Rancher version to install, refer to [Choosing a Rancher Version.](../resources/choose-a-rancher-version.md) + +To choose a version of Helm to install Rancher with, refer to the [Helm version requirements](../resources/helm-version-requirements.md) + +:::note + +The installation instructions assume you are using Helm 3. + +::: + +To set up Rancher, + +1. [Add the Helm chart repository](#1-add-the-helm-chart-repository) +2. [Create a namespace for Rancher](#2-create-a-namespace-for-rancher) +3. [Choose your SSL configuration](#3-choose-your-ssl-configuration) +4. [Install cert-manager](#4-install-cert-manager) (unless you are bringing your own certificates, or TLS will be terminated on a load balancer) +5. [Install Rancher with Helm and your chosen certificate option](#5-install-rancher-with-helm-and-your-chosen-certificate-option) +6. [Verify that the Rancher server is successfully deployed](#6-verify-that-the-rancher-server-is-successfully-deployed) +7. [Save your options](#7-save-your-options) + +### 1. Add the Helm Chart Repository + +Use `helm repo add` command to add the Helm chart repository that contains charts to install Rancher. For more information about the repository choices and which is best for your use case, see [Choosing a Rancher Version](../resources/choose-a-rancher-version.md). + +- Latest: Recommended for trying out the newest features + ``` + helm repo add rancher-latest https://releases.rancher.com/server-charts/latest + ``` +- Stable: Recommended for production environments + ``` + helm repo add rancher-stable https://releases.rancher.com/server-charts/stable + ``` +- Alpha: Experimental preview of upcoming releases. + ``` + helm repo add rancher-alpha https://releases.rancher.com/server-charts/alpha + ``` + Note: Upgrades are not supported to, from, or between Alphas. + +### 2. Create a Namespace for Rancher + +We'll need to define a Kubernetes namespace where the resources created by the Chart should be installed. This should always be `cattle-system`: + +``` +kubectl create namespace cattle-system +``` + +### 3. Choose your SSL Configuration + +The Rancher management server is designed to be secure by default and requires SSL/TLS configuration. + +:::note + +If you want to externally terminate SSL/TLS, see [TLS termination on an External Load Balancer](../installation-references/helm-chart-options.md#external-tls-termination). As outlined on that page, this option does have additional requirements for TLS verification. + +::: + +There are three recommended options for the source of the certificate used for TLS termination at the Rancher server: + +- **Rancher-generated TLS certificate:** In this case, you will need to install `cert-manager` into the cluster. Rancher utilizes `cert-manager` to issue and maintain its certificates. Rancher will generate a CA certificate of its own, and sign a cert using that CA. `cert-manager` is then responsible for managing that certificate. No extra action is needed when `agent-tls-mode` is set to strict. More information can be found on this setting in [Agent TLS Enforcement](../installation-references/tls-settings.md#agent-tls-enforcement). +- **Let's Encrypt:** The Let's Encrypt option also uses `cert-manager`. However, in this case, cert-manager is combined with a special Issuer for Let's Encrypt that performs all actions (including request and validation) necessary for getting a Let's Encrypt issued cert. This configuration uses HTTP validation (`HTTP-01`), so the load balancer must have a public DNS record and be accessible from the internet. When setting `agent-tls-mode` to `strict`, you must also specify `--privateCA=true` and upload the Let's Encrypt CA as described in [Adding TLS Secrets](../resources/add-tls-secrets.md). More information can be found on this setting in [Agent TLS Enforcement](../installation-references/tls-settings.md#agent-tls-enforcement). +- **Bring your own certificate:** This option allows you to bring your own public- or private-CA signed certificate. Rancher will use that certificate to secure websocket and HTTPS traffic. In this case, you must upload this certificate (and associated key) as PEM-encoded files with the name `tls.crt` and `tls.key`. If you are using a private CA, you must also upload that certificate. This is due to the fact that this private CA may not be trusted by your nodes. Rancher will take that CA certificate, and generate a checksum from it, which the various Rancher components will use to validate their connection to Rancher. If `agent-tls-mode` is set to `strict`, the CA must be uploaded, so that downstream clusters can successfully connect. More information can be found on this setting in [Agent TLS Enforcement](../installation-references/tls-settings.md#agent-tls-enforcement). + + +| Configuration | Helm Chart Option | Requires cert-manager | +| ------------------------------ | ----------------------- | ------------------------------------- | +| Rancher Generated Certificates (Default) | `ingress.tls.source=rancher` | [yes](#4-install-cert-manager) | +| Let’s Encrypt | `ingress.tls.source=letsEncrypt` | [yes](#4-install-cert-manager) | +| Certificates from Files | `ingress.tls.source=secret` | no | + +### 4. Install cert-manager + +> You should skip this step if you are bringing your own certificate files (option `ingress.tls.source=secret`), or if you use [TLS termination on an external load balancer](../installation-references/helm-chart-options.md#external-tls-termination). + +This step is only required to use certificates issued by Rancher's generated CA (`ingress.tls.source=rancher`) or to request Let's Encrypt issued certificates (`ingress.tls.source=letsEncrypt`). + +
+ Click to Expand + +:::note Important: + +Recent changes to cert-manager require an upgrade. If you are upgrading Rancher and using a version of cert-manager older than v0.11.0, please see our [upgrade documentation](../resources/upgrade-cert-manager.md). + +::: + +These instructions are adapted from the [official cert-manager documentation](https://cert-manager.io/docs/installation/kubernetes/#installing-with-helm). + +:::note + +To see options on how to customize the cert-manager install (including for cases where your cluster uses PodSecurityPolicies), see the [cert-manager docs](https://artifacthub.io/packages/helm/cert-manager/cert-manager#configuration). + +::: + +``` +# If you have installed the CRDs manually, instead of setting `installCRDs` or `crds.enabled` to `true` in your Helm install command, you should upgrade your CRD resources before upgrading the Helm chart: +kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download//cert-manager.crds.yaml + +# Add the Jetstack Helm repository +helm repo add jetstack https://charts.jetstack.io + +# Update your local Helm chart repository cache +helm repo update + +# Install the cert-manager Helm chart +helm install cert-manager jetstack/cert-manager \ + --namespace cert-manager \ + --create-namespace \ + --set crds.enabled=true +``` + +Once you’ve installed cert-manager, you can verify it is deployed correctly by checking the cert-manager namespace for running pods: + +``` +kubectl get pods --namespace cert-manager + +NAME READY STATUS RESTARTS AGE +cert-manager-5c6866597-zw7kh 1/1 Running 0 2m +cert-manager-cainjector-577f6d9fd7-tr77l 1/1 Running 0 2m +cert-manager-webhook-787858fcdb-nlzsq 1/1 Running 0 2m +``` + +
+ +### 5. Install Rancher with Helm and Your Chosen Certificate Option + +The exact command to install Rancher differs depending on the certificate configuration. + +However, irrespective of the certificate configuration, the name of the Rancher installation in the `cattle-system` namespace should always be `rancher`. + +:::tip Testing and Development: + +This final command to install Rancher requires a domain name that forwards traffic to Rancher. If you are using the Helm CLI to set up a proof-of-concept, you can use a fake domain name when passing the `hostname` option. An example of a fake domain name would be `.sslip.io`, which would expose Rancher on an IP where it is running. Production installs would require a real domain name. + +::: + + + + +The default is for Rancher to generate a CA and uses `cert-manager` to issue the certificate for access to the Rancher server interface. + +Because `rancher` is the default option for `ingress.tls.source`, we are not specifying `ingress.tls.source` when running the `helm install` command. + +- Set the `hostname` to the DNS name you pointed at your load balancer. +- Set the `bootstrapPassword` to something unique for the `admin` user. +- To install a specific Rancher version, use the `--version` flag, example: `--version 2.7.0` + +``` +helm install rancher rancher-/rancher \ + --namespace cattle-system \ + --set hostname=rancher.my.org \ + --set bootstrapPassword=admin +``` + +If you are installing an alpha version, Helm requires adding the `--devel` option to the install command: + +``` +helm install rancher rancher-alpha/rancher --devel +``` + +Wait for Rancher to be rolled out: + +``` +kubectl -n cattle-system rollout status deploy/rancher +Waiting for deployment "rancher" rollout to finish: 0 of 3 updated replicas are available... +deployment "rancher" successfully rolled out +``` + + + + +This option uses `cert-manager` to automatically request and renew [Let's Encrypt](https://letsencrypt.org/) certificates. This is a free service that provides you with a valid certificate as Let's Encrypt is a trusted CA. + +:::note + +You need to have port 80 open as the HTTP-01 challenge can only be done on port 80. + +::: + +In the following command, + +- `hostname` is set to the public DNS record, +- Set the `bootstrapPassword` to something unique for the `admin` user. +- `ingress.tls.source` is set to `letsEncrypt` +- `letsEncrypt.email` is set to the email address used for communication about your certificate (for example, expiry notices) +- Set `letsEncrypt.ingress.class` to whatever your ingress controller is, e.g., `traefik`, `nginx`, `haproxy`, etc. + +:::warning + +When `agent-tls-mode` is set to `strict` (the default value for new installs of Rancher starting from v2.9.0), you must supply the `privateCA=true` chart value (e.x. through `--set privateCA=true`) and upload the Let's Encrypt Certificate Authority as outlined in [Adding TLS Secrets](../resources/add-tls-secrets.md). Information on identifying the Let's Encrypt Root CA can be found in the Let's Encrypt [docs](https://letsencrypt.org/certificates/). If you don't upload the CA, then Rancher may fail to connect to new or existing downstream clusters. + +::: + +``` +helm install rancher rancher-/rancher \ + --namespace cattle-system \ + --set hostname=rancher.my.org \ + --set bootstrapPassword=admin \ + --set ingress.tls.source=letsEncrypt \ + --set letsEncrypt.email=me@example.org \ + --set letsEncrypt.ingress.class=nginx +``` + +If you are installing an alpha version, Helm requires adding the `--devel` option to the install command: + +``` +helm install rancher rancher-alpha/rancher --devel +``` + +Wait for Rancher to be rolled out: + +``` +kubectl -n cattle-system rollout status deploy/rancher +Waiting for deployment "rancher" rollout to finish: 0 of 3 updated replicas are available... +deployment "rancher" successfully rolled out +``` + + + +In this option, Kubernetes secrets are created from your own certificates for Rancher to use. + +When you run this command, the `hostname` option must match the `Common Name` or a `Subject Alternative Names` entry in the server certificate or the Ingress controller will fail to configure correctly. + +Although an entry in the `Subject Alternative Names` is technically required, having a matching `Common Name` maximizes compatibility with older browsers and applications. + +:::note + +If you want to check if your certificates are correct, see [How do I check Common Name and Subject Alternative Names in my server certificate?](../../../faq/technical-items.md#how-do-i-check-common-name-and-subject-alternative-names-in-my-server-certificate) + +::: + +- Set the `hostname`. +- Set the `bootstrapPassword` to something unique for the `admin` user. +- Set `ingress.tls.source` to `secret`. + +``` +helm install rancher rancher-/rancher \ + --namespace cattle-system \ + --set hostname=rancher.my.org \ + --set bootstrapPassword=admin \ + --set ingress.tls.source=secret +``` +If you are installing an alpha version, Helm requires adding the `--devel` option to the install command: + +``` +helm install rancher rancher-alpha/rancher --devel +``` + +If you are using a Private CA signed certificate , add `--set privateCA=true` to the command: + +``` +helm install rancher rancher-/rancher \ + --namespace cattle-system \ + --set hostname=rancher.my.org \ + --set bootstrapPassword=admin \ + --set ingress.tls.source=secret \ + --set privateCA=true +``` + +Now that Rancher is deployed, see [Adding TLS Secrets](../resources/add-tls-secrets.md) to publish the certificate files so Rancher and the Ingress controller can use them. + + + + +The Rancher chart configuration has many options for customizing the installation to suit your specific environment. Here are some common advanced scenarios. + +- [HTTP Proxy](../installation-references/helm-chart-options.md#http-proxy) +- [Private Container Image Registry](../installation-references/helm-chart-options.md#private-registry-and-air-gap-installs) +- [TLS Termination on an External Load Balancer](../installation-references/helm-chart-options.md#external-tls-termination) + +See the [Chart Options](../installation-references/helm-chart-options.md) for the full list of options. + + +### 6. Verify that the Rancher Server is Successfully Deployed + +After adding the secrets, check if Rancher was rolled out successfully: + +``` +kubectl -n cattle-system rollout status deploy/rancher +Waiting for deployment "rancher" rollout to finish: 0 of 3 updated replicas are available... +deployment "rancher" successfully rolled out +``` + +If you see the following error: `error: deployment "rancher" exceeded its progress deadline`, you can check the status of the deployment by running the following command: + +``` +kubectl -n cattle-system get deploy rancher +NAME DESIRED CURRENT UP-TO-DATE AVAILABLE AGE +rancher 3 3 3 3 3m +``` + +It should show the same count for `DESIRED` and `AVAILABLE`. + +### 7. Save Your Options + +Make sure you save the `--set` options you used. You will need to use the same options when you upgrade Rancher to new versions with Helm. + +### Finishing Up + +That's it. You should have a functional Rancher server. + +In a web browser, go to the DNS name that forwards traffic to your load balancer. Then you should be greeted by the colorful login page. + +Doesn't work? Take a look at the [Troubleshooting](troubleshooting.md) Page diff --git a/versioned_docs/version-2.14/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/rancher-on-aks.md b/versioned_docs/version-2.14/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/rancher-on-aks.md new file mode 100644 index 00000000000..6aa9bfda5ac --- /dev/null +++ b/versioned_docs/version-2.14/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/rancher-on-aks.md @@ -0,0 +1,151 @@ +--- +title: Installing Rancher on Azure Kubernetes Service +--- + + + + + +This page covers how to install Rancher on Microsoft's Azure Kubernetes Service (AKS). + +The guide uses command line tools to provision an AKS cluster with an ingress. If you prefer to provision your cluster using the Azure portal, refer to the [official documentation](https://docs.microsoft.com/en-us/azure/aks/kubernetes-walkthrough-portal). + +If you already have an AKS Kubernetes cluster, skip to the step about [installing an ingress.](#5-install-an-ingress) Then install the Rancher Helm chart following the instructions on [this page.](install-upgrade-on-a-kubernetes-cluster.md#install-the-rancher-helm-chart) + +## Prerequisites + +:::caution + +Deploying to Microsoft Azure will incur charges. + +::: + +- [Microsoft Azure Account](https://azure.microsoft.com/en-us/free/): A Microsoft Azure Account is required to create resources for deploying Rancher and Kubernetes. +- [Microsoft Azure Subscription](https://docs.microsoft.com/en-us/azure/cost-management-billing/manage/create-subscription#create-a-subscription-in-the-azure-portal): Use this link to follow a tutorial to create a Microsoft Azure subscription if you don't have one yet. +- [Micsoroft Azure Tenant](https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-create-new-tenant): Use this link and follow instructions to create a Microsoft Azure tenant. +- Your subscription has sufficient quota for at least 2 vCPUs. For details on Rancher server resource requirements, refer to [this section](../installation-requirements/installation-requirements.md) +- When installing Rancher with Helm in Azure, use the L7 load balancer to avoid networking issues. For more information, refer to the documentation on [Azure load balancer limitations](https://docs.microsoft.com/en-us/azure/load-balancer/components#limitations). + +## 1. Prepare your Workstation + +Install the following command line tools on your workstation: + +- The Azure CLI, **az:** For help, refer to these [installation steps.](https://docs.microsoft.com/en-us/cli/azure/) +- **kubectl:** For help, refer to these [installation steps.](https://kubernetes.io/docs/tasks/tools/#kubectl) +- **helm:** For help, refer to these [installation steps.](https://helm.sh/docs/intro/install/) + +## 2. Create a Resource Group + +After installing the CLI, you will need to log in with your Azure account. + +``` +az login +``` + +Create a [resource group](https://docs.microsoft.com/en-us/azure/azure-resource-manager/management/manage-resource-groups-portal) to hold all relevant resources for your cluster. Use a location that applies to your use case. + +``` +az group create --name rancher-rg --location eastus +``` + +## 3. Create the AKS Cluster + +To create an AKS cluster, run the following command. Use a VM size that applies to your use case. Refer to [this article](https://docs.microsoft.com/en-us/azure/virtual-machines/sizes) for available sizes and options. When choosing a Kubernetes version, be sure to first consult the [support matrix](https://rancher.com/support-matrix/) to find the highest version of Kubernetes that has been validated for your Rancher version. + +:::note + +If you're updating from an older version of Kubernetes, to Kubernetes v1.22 or above, you also need to [update](https://kubernetes.github.io/ingress-nginx/user-guide/k8s-122-migration/) ingress-nginx. + +::: + +``` +az aks create \ + --resource-group rancher-rg \ + --name rancher-server \ + --kubernetes-version \ + --node-count 3 \ + --node-vm-size Standard_D2_v3 +``` + +The cluster will take some time to be deployed. + +## 4. Get Access Credentials + +After the cluster is deployed, get the access credentials. + +``` +az aks get-credentials --resource-group rancher-rg --name rancher-server +``` + +This command merges your cluster's credentials into the existing kubeconfig and allows `kubectl` to interact with the cluster. + +## 5. Install an Ingress + +The cluster needs an Ingress so that Rancher can be accessed from outside the cluster. Installing an Ingress requires allocating a public IP address. Ensure you have sufficient quota, otherwise it will fail to assign the IP address. Limits for public IP addresses are applicable at a regional level per subscription. + +To make sure that you choose the correct Ingress-NGINX Helm chart, first find an `Ingress-NGINX version` that's compatible with your Kubernetes version in the [Kubernetes/ingress-nginx support table](https://github.com/kubernetes/ingress-nginx#supported-versions-table). + +Then, list the Helm charts available to you by running the following command: + +``` +helm repo add ingress-nginx https://kubernetes.github.io/ingress-nginx +helm repo update +helm search repo ingress-nginx -l +``` + +The `helm search` command's output contains an `APP VERSION` column. The versions under this column are equivalent to the `Ingress-NGINX version` you chose earlier. Using the app version, select a chart version that bundles an app compatible with your Kubernetes install. For example, if you have Kubernetes v1.24, you can select the v4.6.0 Helm chart, since Ingress-NGINX v1.7.0 comes bundled with that chart, and v1.7.0 is compatible with Kubernetes v1.24. When in doubt, select the most recent compatible version. + +Now that you know which Helm chart `version` you need, run the following command. It installs an `nginx-ingress-controller` with a Kubernetes load balancer service: + +``` +helm search repo ingress-nginx -l +helm upgrade --install \ + ingress-nginx ingress-nginx/ingress-nginx \ + --namespace ingress-nginx \ + --set controller.service.type=LoadBalancer \ + --set controller.service.annotations."service\.beta\.kubernetes\.io/azure-load-balancer-health-probe-request-path"=/healthz \ + --set controller.service.externalTrafficPolicy=Local \ + --version 4.6.0 \ + --create-namespace +``` + +## 6. Get Load Balancer IP + +To get the address of the load balancer, run: + +``` +kubectl get service ingress-nginx-controller --namespace=ingress-nginx +``` + +The result should look similar to the following: + +``` +NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) + AGE +ingress-nginx-controller LoadBalancer 10.0.116.18 40.31.180.83 80:31229/TCP,443:31050/TCP + 67s +``` + +Save the `EXTERNAL-IP`. + +## 7. Set up DNS + +External traffic to the Rancher server will need to be directed at the load balancer you created. + +Set up a DNS to point at the `EXTERNAL-IP` that you saved. This DNS will be used as the Rancher server URL. + +There are many valid ways to set up the DNS. For help, refer to the [Azure DNS documentation](https://docs.microsoft.com/en-us/azure/dns/) + +## 8. Install the Rancher Helm Chart + +Next, install the Rancher Helm chart by following the instructions on [this page.](install-upgrade-on-a-kubernetes-cluster.md#install-the-rancher-helm-chart) The Helm instructions are the same for installing Rancher on any Kubernetes distribution. + +Use that DNS name from the previous step as the Rancher server URL when you install Rancher. It can be passed in as a Helm option. For example, if the DNS name is `rancher.my.org`, you could run the Helm installation command with the option `--set hostname=rancher.my.org`. + +When installing Rancher on top of this setup, you will also need to pass the value below into the Rancher Helm install command in order to set the name of the ingress controller to be used with Rancher's ingress resource: + +``` +--set ingress.ingressClassName=nginx +``` + +Refer [here for the Helm install command](install-upgrade-on-a-kubernetes-cluster.md#5-install-rancher-with-helm-and-your-chosen-certificate-option) for your chosen certificate option. diff --git a/versioned_docs/version-2.14/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/rancher-on-amazon-eks.md b/versioned_docs/version-2.14/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/rancher-on-amazon-eks.md new file mode 100644 index 00000000000..85c83a2d503 --- /dev/null +++ b/versioned_docs/version-2.14/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/rancher-on-amazon-eks.md @@ -0,0 +1,155 @@ +--- +title: Installing Rancher on Amazon EKS +--- + + + + + +This page covers installing Rancher on an Amazon EKS cluster. You can also [install Rancher through the AWS Marketplace](../../quick-start-guides/deploy-rancher-manager/aws-marketplace.md). + +If you already have an EKS Kubernetes cluster, skip to the step about [installing an ingress.](#5-install-an-ingress) Then install the Rancher Helm chart following the instructions on [this page.](install-upgrade-on-a-kubernetes-cluster.md#install-the-rancher-helm-chart) + +## Creating an EKS Cluster for the Rancher Server + +In this section, you'll install an EKS cluster with an ingress by using command line tools. This guide may be useful if you want to use fewer resources while trying out Rancher on EKS. + +:::note Prerequisites: + +- You should already have an AWS account. +- It is recommended to use an IAM user instead of the root AWS account. You will need the IAM user's access key and secret key to configure the AWS command line interface. +- The IAM user needs the minimum IAM policies described in the official [eksctl documentation.](https://eksctl.io/usage/minimum-iam-policies/) + +::: + +### 1. Prepare your Workstation + +Install the following command line tools on your workstation: + +- **The AWS CLI v2:** For help, refer to these [installation steps.](https://docs.aws.amazon.com/cli/latest/userguide/install-cliv2.html) +- **eksctl:** For help, refer to these [installation steps.](https://docs.aws.amazon.com/eks/latest/userguide/eksctl.html) +- **kubectl:** For help, refer to these [installation steps.](https://docs.aws.amazon.com/eks/latest/userguide/install-kubectl.html) +- **helm:** For help, refer to these [installation steps.](https://helm.sh/docs/intro/install/) + +### 2. Configure the AWS CLI + +To configure the AWS CLI, run the following command: + +``` +aws configure +``` + +Then enter the following values: + +| Value | Description | +|-------|-------------| +| AWS Access Key ID | The access key credential for the IAM user with EKS permissions. | +| AWS Secret Access Key | The secret key credential for the IAM user with EKS permissions. | +| Default region name | An [AWS region](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/Concepts.RegionsAndAvailabilityZones.html#Concepts.RegionsAndAvailabilityZones.Regions) where the cluster nodes will be located. | +| Default output format | Enter `json`. | + +### 3. Create the EKS Cluster + +To create an EKS cluster, run the following command. Use the AWS region that applies to your use case. When choosing a Kubernetes version, be sure to first consult the [support matrix](https://rancher.com/support-matrix/) to find the highest version of Kubernetes that has been validated for your Rancher version. + +**Note:** If you're updating from an older version of Kubernetes, to Kubernetes v1.22 or above, you also need to [update](https://kubernetes.github.io/ingress-nginx/user-guide/k8s-122-migration/) ingress-nginx. + +``` +eksctl create cluster \ + --name rancher-server \ + --version \ + --region us-west-2 \ + --nodegroup-name ranchernodes \ + --nodes 3 \ + --nodes-min 1 \ + --nodes-max 4 \ + --managed +``` + +The cluster will take some time to be deployed with CloudFormation. + +### 4. Test the Cluster + +To test the cluster, run: + +``` +eksctl get cluster +``` + +The result should look like the following: + +``` +eksctl get cluster +2021-03-18 15:09:35 [ℹ] eksctl version 0.40.0 +2021-03-18 15:09:35 [ℹ] using region us-west-2 +NAME REGION EKSCTL CREATED +rancher-server-cluster us-west-2 True +``` + +### 5. Install an Ingress + +The cluster needs an Ingress so that Rancher can be accessed from outside the cluster. + +To make sure that you choose the correct Ingress-NGINX Helm chart, first find an `Ingress-NGINX version` that's compatible with your Kubernetes version in the [Kubernetes/ingress-nginx support table](https://github.com/kubernetes/ingress-nginx#supported-versions-table). + +Then, list the Helm charts available to you by running the following command: + +``` +helm repo add ingress-nginx https://kubernetes.github.io/ingress-nginx +helm repo update +helm search repo ingress-nginx -l +``` + +The `helm search` command's output contains an `APP VERSION` column. The versions under this column are equivalent to the `Ingress-NGINX version` you chose earlier. Using the app version, select a chart version that bundles an app compatible with your Kubernetes install. For example, if you have Kubernetes v1.23, you can select the v4.6.0 Helm chart, since Ingress-NGINX v1.7.0 comes bundled with that chart, and v1.7.0 is compatible with Kubernetes v1.23. When in doubt, select the most recent compatible version. + +Now that you know which Helm chart `version` you need, run the following command. It installs an `nginx-ingress-controller` with a Kubernetes load balancer service: + +``` +helm upgrade --install \ + ingress-nginx ingress-nginx/ingress-nginx \ + --namespace ingress-nginx \ + --set controller.service.type=LoadBalancer \ + --version 4.6.0 \ + --create-namespace +``` + +### 6. Get Load Balancer IP + +To get the address of the load balancer, run: + +``` +kubectl get service ingress-nginx-controller --namespace=ingress-nginx +``` + +The result should look similar to the following: + +``` +NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) + AGE +ingress-nginx-controller LoadBalancer 10.100.90.18 a904a952c73bf4f668a17c46ac7c56ab-962521486.us-west-2.elb.amazonaws.com 80:31229/TCP,443:31050/TCP + 27m +``` + +Save the `EXTERNAL-IP`. + +### 7. Set up DNS + +External traffic to the Rancher server will need to be directed at the load balancer you created. + +Set up a DNS to point at the external IP that you saved. This DNS will be used as the Rancher server URL. + +There are many valid ways to set up the DNS. For help, refer to the AWS documentation on [routing traffic to an ELB load balancer.](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/routing-to-elb-load-balancer.html) + +### 8. Install the Rancher Helm Chart + +Next, install the Rancher Helm chart by following the instructions on [this page.](install-upgrade-on-a-kubernetes-cluster.md#install-the-rancher-helm-chart) The Helm instructions are the same for installing Rancher on any Kubernetes distribution. + +Use that DNS name from the previous step as the Rancher server URL when you install Rancher. It can be passed in as a Helm option. For example, if the DNS name is `rancher.my.org`, you could run the Helm installation command with the option `--set hostname=rancher.my.org`. + +When installing Rancher on top of this setup, you will also need to pass the value below into the Rancher Helm install command in order to set the name of the ingress controller to be used with Rancher's ingress resource: + +``` +--set ingress.ingressClassName=nginx +``` + +Refer [here for the Helm install command](install-upgrade-on-a-kubernetes-cluster.md#5-install-rancher-with-helm-and-your-chosen-certificate-option) for your chosen certificate option. diff --git a/versioned_docs/version-2.14/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/rancher-on-gke.md b/versioned_docs/version-2.14/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/rancher-on-gke.md new file mode 100644 index 00000000000..a3c3518e4c0 --- /dev/null +++ b/versioned_docs/version-2.14/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/rancher-on-gke.md @@ -0,0 +1,205 @@ +--- +title: Installing Rancher on a Google Kubernetes Engine Cluster +--- + + + + + +In this section, you'll learn how to install Rancher using Google Kubernetes Engine. + +If you already have a GKE Kubernetes cluster, skip to the step about [installing an ingress.](#7-install-an-ingress) Then install the Rancher Helm chart following the instructions on [this page.](install-upgrade-on-a-kubernetes-cluster.md#install-the-rancher-helm-chart) + +## Prerequisites + +- You will need a Google account. +- You will need a Google Cloud billing account. You can manage your Cloud Billing accounts using the Google Cloud Console. For more information about the Cloud Console, visit [General guide to the console.](https://support.google.com/cloud/answer/3465889?hl=en&ref_topic=3340599) +- You will need a cloud quota for at least one in-use IP address and at least 2 CPUs. For more details about hardware requirements for the Rancher server, refer to [this section.](../installation-requirements/installation-requirements.md) + +## 1. Enable the Kubernetes Engine API + +Take the following steps to enable the Kubernetes Engine API: + +1. Visit the [Kubernetes Engine page](https://console.cloud.google.com/projectselector/kubernetes?_ga=2.169595943.767329331.1617810440-856599067.1617343886) in the Google Cloud Console. +1. Create or select a project. +1. Open the project and enable the Kubernetes Engine API for the project. Wait for the API and related services to be enabled. This can take several minutes. +1. Make sure that billing is enabled for your Cloud project. For information on how to enable billing for your project, refer to the [Google Cloud documentation.](https://cloud.google.com/billing/docs/how-to/modify-project#enable_billing_for_a_project) + +## 2. Open the Cloud Shell + +Cloud Shell is a shell environment for managing resources hosted on Google Cloud. Cloud Shell comes preinstalled with the `gcloud` command-line tool and kubectl command-line tool. The `gcloud` tool provides the primary command-line interface for Google Cloud, and `kubectl` provides the primary command-line interface for running commands against Kubernetes clusters. + +The following sections describe how to launch the cloud shell from the Google Cloud Console or from your local workstation. + +### Cloud Shell + +To launch the shell from the [Google Cloud Console,](https://console.cloud.google.com) go to the upper-right corner of the console and click the terminal button. When hovering over the button, it is labeled **Activate Cloud Shell**. + +### Local Shell + +To install `gcloud` and `kubectl`, perform the following steps: + +1. Install the Cloud SDK by following [these steps.](https://cloud.google.com/sdk/docs/install) The Cloud SDK includes the `gcloud` command-line tool. The steps vary based on your OS. +1. After installing Cloud SDK, install the `kubectl` command-line tool by running the following command: + + ``` + gcloud components install kubectl + ``` + In a later step, `kubectl` will be configured to use the new GKE cluster. +1. [Install Helm 3](https://helm.sh/docs/intro/install/) if it is not already installed. +1. Enable Helm experimental [support for OCI images](https://github.com/helm/community/blob/master/hips/hip-0006.md) with the `HELM_EXPERIMENTAL_OCI` variable. Add the following line to `~/.bashrc` (or `~/.bash_profile` in macOS, or wherever your shell stores environment variables): + + ``` + export HELM_EXPERIMENTAL_OCI=1 + ``` +1. Run the following command to load your updated `.bashrc` file: + + ``` + source ~/.bashrc + ``` + If you are running macOS, use this command: + ``` + source ~/.bash_profile + ``` + + + +## 3. Configure the gcloud CLI + + Set up default gcloud settings using one of the following methods: + +- Using gcloud init, if you want to be walked through setting defaults. +- Using gcloud config, to individually set your project ID, zone, and region. + + + + + 1. Run gcloud init and follow the directions: + + ``` + gcloud init + ``` + If you are using SSH on a remote server, use the --console-only flag to prevent the command from launching a browser: + + ``` + gcloud init --console-only + ``` + 2. Follow the instructions to authorize gcloud to use your Google Cloud account and select the new project that you created. + + + + + + + +## 4. Confirm that gcloud is configured correctly + +Run: + +``` +gcloud config list +``` + +The output should resemble the following: + +``` +[compute] +region = us-west1 # Your chosen region +zone = us-west1-b # Your chosen zone +[core] +account = +disable_usage_reporting = True +project = + +Your active configuration is: [default] +``` + +## 5. Create a GKE Cluster + +The following command creates a three-node cluster. + +Replace `cluster-name` with the name of your new cluster. + +When choosing a Kubernetes version, be sure to first consult the [support matrix](https://rancher.com/support-matrix/) to find the highest version of Kubernetes that has been validated for your Rancher version. + +To successfully create a GKE cluster with Rancher, your GKE must be in Standard mode. GKE has two modes of operation when creating a Kubernetes cluster, Autopilot and Standard mode. The cluster configuration for Autopilot mode has restrictions on editing the kube-system namespace. However, Rancher needs to create resources in the kube-system namespace during installation. As a result, you will not be able to install Rancher on a GKE cluster created in Autopilot mode. For more information about the difference between GKE Autopilot mode and Standard mode, visit [Compare GKE Autopilot and Standard.](https://cloud.google.com/kubernetes-engine/docs/resources/autopilot-standard-feature-comparison) + +**Note:** If you're updating from an older version of Kubernetes, to Kubernetes v1.22 or above, you also need to [update](https://kubernetes.github.io/ingress-nginx/user-guide/k8s-122-migration/) ingress-nginx. + +``` +gcloud container clusters create cluster-name --num-nodes=3 --cluster-version= +``` + +## 6. Get Authentication Credentials + +After creating your cluster, you need to get authentication credentials to interact with the cluster: + +``` +gcloud container clusters get-credentials cluster-name +``` + +This command configures `kubectl` to use the cluster you created. + +## 7. Install an Ingress + +The cluster needs an Ingress so that Rancher can be accessed from outside the cluster. + +The following command installs an `nginx-ingress-controller` with a LoadBalancer service: + +``` +helm repo add ingress-nginx https://kubernetes.github.io/ingress-nginx +helm repo update +helm upgrade --install \ + ingress-nginx ingress-nginx/ingress-nginx \ + --namespace ingress-nginx \ + --set controller.service.type=LoadBalancer \ + --version 4.0.18 \ + --create-namespace +``` + +## 8. Get the Load Balancer IP + +To get the address of the load balancer, run: + +``` +kubectl get service ingress-nginx-controller --namespace=ingress-nginx +``` + +The result should look similar to the following: + +``` +NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE +ingress-nginx-controller LoadBalancer 10.3.244.156 35.233.206.34 80:31876/TCP,443:32497/TCP 81s +``` + +Save the `EXTERNAL-IP`. + +## 9. Set up DNS + +External traffic to the Rancher server will need to be directed at the load balancer you created. + +Set up a DNS to point at the external IP that you saved. This DNS will be used as the Rancher server URL. + +There are many valid ways to set up the DNS. For help, refer to the Google Cloud documentation about [managing DNS records.](https://cloud.google.com/dns/docs/records) + +## 10. Install the Rancher Helm chart + +Next, install the Rancher Helm chart by following the instructions on [this page.](install-upgrade-on-a-kubernetes-cluster.md#install-the-rancher-helm-chart) The Helm instructions are the same for installing Rancher on any Kubernetes distribution. + +Use the DNS name from the previous step as the Rancher server URL when you install Rancher. It can be passed in as a Helm option. For example, if the DNS name is `rancher.my.org`, you could run the Helm installation command with the option `--set hostname=rancher.my.org`. + +When installing Rancher on top of this setup, you will also need to set the name of the ingress controller to be used with Rancher's ingress resource: + +``` +--set ingress.ingressClassName=nginx +``` + +Refer [here for the Helm install command](install-upgrade-on-a-kubernetes-cluster.md#5-install-rancher-with-helm-and-your-chosen-certificate-option) for your chosen certificate option. + +In Rancher v2.7.5, if you intend to use the default GKE ingress on your cluster without enabling VPC-native cluster mode, you need to set the following flag: + +``` +--set service.type=NodePort +``` + +This is necessary because of compatibility issues between this setup and ClusterIP, the default type for `cattle-system/rancher`. diff --git a/versioned_docs/version-2.14/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/rancher-psact.yaml b/versioned_docs/version-2.14/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/rancher-psact.yaml new file mode 100644 index 00000000000..361adde18a6 --- /dev/null +++ b/versioned_docs/version-2.14/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/rancher-psact.yaml @@ -0,0 +1,39 @@ +apiVersion: apiserver.config.k8s.io/v1 +kind: AdmissionConfiguration +plugins: +- configuration: + apiVersion: pod-security.admission.config.k8s.io/v1 + defaults: + audit: restricted + audit-version: latest + enforce: restricted + enforce-version: latest + warn: restricted + warn-version: latest + exemptions: + namespaces: + - ingress-nginx + - kube-system + - cattle-system + - cattle-epinio-system + - cattle-fleet-system + - cattle-fleet-local-system + - longhorn-system + - cattle-neuvector-system + - cattle-monitoring-system + - rancher-alerting-drivers + - cis-operator-system + - cattle-csp-adapter-system + - cattle-externalip-system + - cattle-gatekeeper-system + - istio-system + - cattle-istio-system + - cattle-logging-system + - cattle-windows-gmsa-system + - cattle-sriov-system + - cattle-ui-plugin-system + - tigera-operator + - cattle-provisioning-capi-system + kind: PodSecurityConfiguration + name: PodSecurity + path: "" diff --git a/versioned_docs/version-2.14/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/rollbacks.md b/versioned_docs/version-2.14/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/rollbacks.md new file mode 100644 index 00000000000..1845618a5bf --- /dev/null +++ b/versioned_docs/version-2.14/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/rollbacks.md @@ -0,0 +1,157 @@ +--- +title: Rollbacks +--- + + + + + +This page outlines how to rollback Rancher to a previous version after an upgrade. + +Follow the instructions from this page when: +- The running Rancher instance has been upgraded to a newer version after the backup was made. +- The upstream (local) cluster is the same as where the backup was made. + +:::tip + +* Follow these steps to [migrate Rancher](../../../how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/migrate-rancher-to-new-cluster.md). +* If you need to restore Rancher to its previous state at the same Rancher version, see the [restore documentation](../../../how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/restore-rancher.md). + +::: + +## Alternative Steps for Special Scenarios + +Alternative steps need to be performed for rollbacks in the following scenarios: +- Rolling back from v2.6.4 and later to an earlier version of v2.6.x. +- Rolling back from v2.7.7 and later to an earlier version of v2.7.x. + +In Rancher v2.6.4, the cluster-api module is upgraded from v0.4.4 to v1.0.2. The cluster-api v1.0.2, in turn, upgrades the apiVersions of its Custom Resource Definitions (CRDs) from `cluster.x-k8s.io/v1alpha4` to `cluster.x-k8s.io/v1beta1`. Custom Resources (CRs) that use the older apiVersion (v1alpha4) are incompatible with v1beta1, which causes rollbacks to fail when you attempt to move from Rancher v2.6.4 to any previous version of Rancher v2.6.x. + +In Rancher v2.7.7, the app `rancher-provisioning-capi` is installed on the upstream (local) cluster automatically as a replacement for the embedded cluster-api controllers. Conflicts and unexpected errors will occur if the upstream cluster contains both the app, and Rancher v2.7.6 and earlier. Therefore, alternative steps are needed if you attempt to move from Rancher v2.7.7 to any previous version of Rancher v2.7.x. + +### Step 1: Clean Up the Upstream (Local) Cluster + +To avoid rollback failure, follow these [instructions](https://github.com/rancher/rancher-cleanup/blob/main/README.md) to run the scripts **before** you attempt a restore operation or rollback: + +* `cleanup.sh`: Cleans up the cluster. +* `verify.sh`: Checks for any Rancher-related resources in the cluster. + +:::caution + +There will be downtime while `cleanup.sh` runs, since the script deletes resources created by Rancher. + +::: + +**Result:** all Rancher-related resources should be cleaned up on the upstream (local) cluster. + +See the [rancher/rancher-cleanup repo](https://github.com/rancher/rancher-cleanup) for more details and source code. + +### Step 2: Restore the Backup and Bring Up Rancher + +At this point, there should be no Rancher-related resources on the upstream cluster. Therefore, the next step will be the same as if you were migrating Rancher to a new cluster that contains no Rancher resources. + +Follow these [instructions](../../../how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/migrate-rancher-to-new-cluster.md) to install the Rancher-Backup Helm chart and restore Rancher to its previous state. +Please keep in mind that: +1. Step 3 can be skipped, because the Cert-Manager app should still exist on the upstream (local) cluster if it was installed before. +2. At Step 4, install the Rancher version you intend to roll back to. + +## Rolling Back to Rancher v2.5.0+ + +To roll back to Rancher v2.5.0+, use the **Rancher Backups** application and restore Rancher from backup. + +Rancher has to be started with the lower/previous version after a rollback. + +A restore is performed by creating a Restore custom resource. + +:::note Important: + +* Follow the instructions from this page for restoring Rancher on the same cluster where it was backed up from. In order to migrate Rancher to a new cluster, follow the steps to [migrate Rancher.](../../../how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/migrate-rancher-to-new-cluster.md) + +* While restoring Rancher on the same setup, the Rancher deployment is manually scaled down before the restore starts, then the operator will scale it back up once the restore completes. As a result, Rancher and its UI will be unavailable until the restore is complete. While the UI is unavailable, use the original cluster kubeconfig with the restore YAML file: `kubectl create -f restore.yaml`. + +::: + +### Step 1: Create the Restore Custom Resource + +1. Click **☰ > Cluster Management**. +1. Go to the local cluster and click **Explore**. +1. In the left navigation bar, click **Rancher Backups > Restore**. + :::note + + If the Rancher Backups app is not visible, you will need to install it from the Charts page in **Apps**. Refer [here](../../../how-to-guides/new-user-guides/helm-charts-in-rancher/helm-charts-in-rancher.md#access-charts) for more information. + + ::: + +1. Click **Create**. +1. Create the Restore with the form or with YAML. For help creating the Restore resource using the online form, refer to the [configuration reference](../../../reference-guides/backup-restore-configuration/restore-configuration.md) and to the [examples.](../../../reference-guides/backup-restore-configuration/examples.md) +1. To use the YAML editor, you can click **Create > Create from YAML.** Enter the Restore YAML. The following is an example Restore custom resource: + + ```yaml + apiVersion: resources.cattle.io/v1 + kind: Restore + metadata: + name: restore-migration + spec: + backupFilename: backup-b0450532-cee1-4aa1-a881-f5f48a007b1c-2020-09-15T07-27-09Z.tar.gz + encryptionConfigSecretName: encryptionconfig + storageLocation: + s3: + credentialSecretName: s3-creds + credentialSecretNamespace: default + bucketName: rancher-backups + folder: rancher + region: us-west-2 + endpoint: s3.us-west-2.amazonaws.com + ``` + For help configuring the Restore, refer to the [configuration reference](../../../reference-guides/backup-restore-configuration/restore-configuration.md) and to the [examples.](../../../reference-guides/backup-restore-configuration/examples.md) + +1. Click **Create**. + +**Result:** The backup file is created and updated to the target storage location. The resources are restored in this order: + +1. Custom Resource Definitions (CRDs) +2. Cluster-scoped resources +3. Namespaced resources + +To check how the restore is progressing, you can check the logs of the operator. Follow these steps to get the logs: + +```yaml +kubectl get pods -n cattle-resources-system +kubectl logs -n cattle-resources-system -f +``` + +### Step 2: Roll Back to a Previous Rancher Version + +Rancher can be rolled back using the Helm CLI. To roll back to the previous version: + +```yaml +helm rollback rancher -n cattle-system +``` + +If the previous revision is not the intended target, you can specify a revision to roll back to. To see the deployment history: + +```yaml +helm history rancher -n cattle-system +``` + +When the target revision is determined, perform the rollback. This example will roll back to revision `3`: + +```yaml +helm rollback rancher 3 -n cattle-system +``` + +## Rolling Back to Rancher v2.2-v2.4+ + +To roll back to Rancher before v2.5, follow the procedure detailed here: [Restoring Backups — Kubernetes installs](https://github.com/rancher/rancher-docs/tree/main/archived_docs/en/version-2.0-2.4/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/restore-rancher-launched-kubernetes-clusters-from-backup.md) Restoring a snapshot of the Rancher server cluster will revert Rancher to the version and state at the time of the snapshot. + +For information on how to roll back Rancher installed with Docker, refer to [this page.](../other-installation-methods/rancher-on-a-single-node-with-docker/roll-back-docker-installed-rancher.md) + +:::note + +Managed clusters are authoritative for their state. This means restoring the Rancher server will not revert workload deployments or changes made on managed clusters after the snapshot was taken. + +::: + +## Rolling Back to Rancher v2.0-v2.1 + +Rolling back to Rancher v2.0-v2.1 is no longer supported. The instructions for rolling back to these versions are preserved [here](https://github.com/rancher/rancher-docs/tree/main/archived_docs/en/version-2.0-2.4/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/restore-rancher-launched-kubernetes-clusters-from-backup/roll-back-to-v2.0-v2.1.md) and are intended to be used only in cases where upgrading to Rancher v2.2+ is not feasible. diff --git a/versioned_docs/version-2.14/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/troubleshooting.md b/versioned_docs/version-2.14/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/troubleshooting.md new file mode 100644 index 00000000000..881a6d871a0 --- /dev/null +++ b/versioned_docs/version-2.14/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/troubleshooting.md @@ -0,0 +1,200 @@ +--- +title: Troubleshooting the Rancher Server Kubernetes Cluster +--- + + + + + +This section describes how to troubleshoot an installation of Rancher on a Kubernetes cluster. + +### Relevant Namespaces + +Most of the troubleshooting will be done on objects in these 3 namespaces. + +- `cattle-system` - `rancher` deployment and pods. +- `ingress-nginx` - Ingress controller pods and services. +- `cert-manager` - `cert-manager` pods. + +### "default backend - 404" + +A number of things can cause the ingress-controller not to forward traffic to your rancher instance. Most of the time its due to a bad ssl configuration. + +Things to check + +- [Is Rancher Running](#check-if-rancher-is-running) +- [Cert CN is "Kubernetes Ingress Controller Fake Certificate"](#cert-cn-is-kubernetes-ingress-controller-fake-certificate) + +### Check if Rancher is Running + +Use `kubectl` to check the `cattle-system` system namespace and see if the Rancher pods are in a Running state. + +``` +kubectl -n cattle-system get pods + +NAME READY STATUS RESTARTS AGE +pod/rancher-784d94f59b-vgqzh 1/1 Running 0 10m +``` + +If the state is not `Running`, run a `describe` on the pod and check the Events. + +``` +kubectl -n cattle-system describe pod + +... +Events: + Type Reason Age From Message + ---- ------ ---- ---- ------- + Normal Scheduled 11m default-scheduler Successfully assigned rancher-784d94f59b-vgqzh to localhost + Normal SuccessfulMountVolume 11m kubelet, localhost MountVolume.SetUp succeeded for volume "rancher-token-dj4mt" + Normal Pulling 11m kubelet, localhost pulling image "rancher/rancher:v2.0.4" + Normal Pulled 11m kubelet, localhost Successfully pulled image "rancher/rancher:v2.0.4" + Normal Created 11m kubelet, localhost Created container + Normal Started 11m kubelet, localhost Started container +``` + +### Check the Rancher Logs + +Use `kubectl` to list the pods. + +``` +kubectl -n cattle-system get pods + +NAME READY STATUS RESTARTS AGE +pod/rancher-784d94f59b-vgqzh 1/1 Running 0 10m +``` + +Use `kubectl` and the pod name to list the logs from the pod. + +``` +kubectl -n cattle-system logs -f rancher-784d94f59b-vgqzh +``` + +### Cert CN is "Kubernetes Ingress Controller Fake Certificate" + +Use your browser to check the certificate details. If it says the Common Name is "Kubernetes Ingress Controller Fake Certificate", something may have gone wrong with reading or issuing your SSL cert. + +:::note + +If you are using LetsEncrypt to issue certs, it can sometimes take a few minutes to issue the cert. + +::: + +### Checking for issues with cert-manager issued certs (Rancher Generated or LetsEncrypt) + +`cert-manager` has 3 parts. + +- `cert-manager` pod in the `cert-manager` namespace. +- `Issuer` object in the `cattle-system` namespace. +- `Certificate` object in the `cattle-system` namespace. + +Work backwards and do a `kubectl describe` on each object and check the events. You can track down what might be missing. + +For example there is a problem with the Issuer: + +``` +kubectl -n cattle-system describe certificate +... +Events: + Type Reason Age From Message + ---- ------ ---- ---- ------- + Warning IssuerNotReady 18s (x23 over 19m) cert-manager Issuer rancher not ready +``` + +``` +kubectl -n cattle-system describe issuer +... +Events: + Type Reason Age From Message + ---- ------ ---- ---- ------- + Warning ErrInitIssuer 19m (x12 over 19m) cert-manager Error initializing issuer: secret "tls-rancher" not found + Warning ErrGetKeyPair 9m (x16 over 19m) cert-manager Error getting keypair for CA issuer: secret "tls-rancher" not found +``` + +### Checking for Issues with Your Own SSL Certs + +Your certs get applied directly to the Ingress object in the `cattle-system` namespace. + +Check the status of the Ingress object and see if its ready. + +``` +kubectl -n cattle-system describe ingress +``` + +If its ready and the SSL is still not working you may have a malformed cert or secret. + +Check the nginx-ingress-controller logs. Because the nginx-ingress-controller has multiple containers in its pod you will need to specify the name of the container. + +``` +kubectl -n ingress-nginx logs -f nginx-ingress-controller-rfjrq nginx-ingress-controller +... +W0705 23:04:58.240571 7 backend_ssl.go:49] error obtaining PEM from secret cattle-system/tls-rancher-ingress: error retrieving secret cattle-system/tls-rancher-ingress: secret cattle-system/tls-rancher-ingress was not found +``` + +### No matches for kind "Issuer" + +The SSL configuration option you have chosen requires cert-manager to be installed before installing Rancher or else the following error is shown: + +``` +Error: validation failed: unable to recognize "": no matches for kind "Issuer" in version "certmanager.k8s.io/v1alpha1" +``` + +Install cert-manager and try installing Rancher again. + + +### Canal Pods show READY 2/3 + +The most common cause of this issue is port 8472/UDP is not open between the nodes. Check your local firewall, network routing or security groups. + +Once the network issue is resolved, the `canal` pods should timeout and restart to establish their connections. + +### nginx-ingress-controller Pods show RESTARTS + +The most common cause of this issue is the `canal` pods have failed to establish the overlay network. See [canal Pods show READY `2/3`](#canal-pods-show-ready-23) for troubleshooting. + + +### Failed to dial to /var/run/docker.sock: ssh: rejected: administratively prohibited (open failed) + +Some causes of this error include: + +* User specified to connect with does not have permission to access the Docker socket. This can be checked by logging into the host and running the command `docker ps`: + +``` +$ ssh user@server +user@server$ docker ps +CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES +``` + +See [Manage Docker as a non-root user](https://docs.docker.com/install/linux/linux-postinstall/#manage-docker-as-a-non-root-user) how to set this up properly. + +* When using RedHat/CentOS as operating system, you cannot use the user `root` to connect to the nodes because of [Bugzilla #1527565](https://bugzilla.redhat.com/show_bug.cgi?id=1527565). You will need to add a separate user and configure it to access the Docker socket. See [Manage Docker as a non-root user](https://docs.docker.com/install/linux/linux-postinstall/#manage-docker-as-a-non-root-user) how to set this up properly. + +* SSH server version is not version 6.7 or higher. This is needed for socket forwarding to work, which is used to connect to the Docker socket over SSH. This can be checked using `sshd -V` on the host you are connecting to, or using netcat: +``` +$ nc xxx.xxx.xxx.xxx 22 +SSH-2.0-OpenSSH_6.6.1p1 Ubuntu-2ubuntu2.10 +``` + +### Failed to dial ssh using address [xxx.xxx.xxx.xxx:xx]: ssh: handshake failed: ssh: unable to authenticate, attempted methods [none publickey], no supported methods remain + +The key file specified as `ssh_key_path` is not correct for accessing the node. Double-check if you specified the correct `ssh_key_path` for the node and if you specified the correct user to connect with. + +### Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running? + +The node is not reachable on the configured `address` and `port`. + +### Agent reports TLS errors + +When using Rancher, you may encounter error messages from the `fleet-agent`, `system-agent`, or `cluster-agent`, such as the message below: +``` +tls: failed to verify certificate: x509: failed to load system roots and no roots provided; readdirent /dev/null: not a directory +``` + +This occurs when Rancher was configured with `agent-tls-mode` set to `strict`, but couldn't find cacerts in the `cacert` setting. To resolve the issue, set the `agent-tls-mode` to `system-store`, or upload the CA for Rancher as described in [Adding TLS Secrets](../resources/add-tls-secrets.md). + +### New Cluster Deployment is stuck in "Waiting for Agent to check in" + +When Rancher has `agent-tls-mode` set to `strict`, new clusters may fail to provision and report a generic "Waiting for Agent to check in" error message. The root cause of this is similar to the above case of TLS errors - Rancher's agent can't determine which CA Rancher is using (or can't verify that Rancher's cert is actually signed by the specified certificate authority). + +To resolve the issue, set the `agent-tls-mode` to `system-store` or upload the CA for Rancher as described in [Adding TLS Secrets](../resources/add-tls-secrets.md). + diff --git a/versioned_docs/version-2.14/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/upgrades.md b/versioned_docs/version-2.14/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/upgrades.md new file mode 100644 index 00000000000..d4b8be7d061 --- /dev/null +++ b/versioned_docs/version-2.14/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/upgrades.md @@ -0,0 +1,239 @@ +--- +title: Upgrades +--- + + + + + +The following instructions will guide you through upgrading a Rancher server that was installed on a Kubernetes cluster with Helm. These steps also apply to air-gapped installs with Helm. + +For the instructions to upgrade Rancher installed with Docker, refer to [this page.](../other-installation-methods/rancher-on-a-single-node-with-docker/upgrade-docker-installed-rancher.md) + +## Prerequisites + +### Access to Kubeconfig + +Helm should be run from the same location as your Kubeconfig file, or the same location where you run your `kubectl` commands from. + +If you installed Kubernetes with RKE2/K3s, the Kubeconfig is stored in the `/etc/rancher/rke2/rke2.yaml` or `/etc/rancher/k3s/k3s.yaml` directory depending on your chosen distribution. + +The Kubeconfig can also be manually targeted for the intended cluster with the `--kubeconfig` tag (see: https://helm.sh/docs/helm/helm/) + +### Review Known Issues + +Review the list of known issues for each Rancher version, which can be found in the release notes on [GitHub](https://github.com/rancher/rancher/releases) and on the [Rancher forums.](https://forums.rancher.com/c/announcements/12) + +Note that upgrades _to_ or _from_ any chart in the [rancher-alpha repository](../resources/choose-a-rancher-version.md#helm-chart-repositories) aren't supported. + +### Helm Version + +:::important + +**Important:** In Rancher Community v2.13.1 if your registry configuration is one of the following you may see Rancher generate the `cattle-cluster-agent` image with an incorrect `docker.io` path segment: + +- Environments where a **cluster-scoped container registry** is configured for system images. +- Environments where a **global `system-default-registry`** is configured (e.g. airgap setups), even if no cluster-scoped registry is set. + +**Workaround for Affected Setups:** As a workaround, override the `cattle-cluster-agent` image via the `CATTLE_AGENT_IMAGE` environment variable. This value must **not** contain any registry prefix (Rancher will handle that automatically). It should be set only to the repository and tag, for example:`rancher/rancher-agent:v2.13.1` + +**Helm `install` example:** + +```bash +helm install rancher rancher-latest/rancher \ +... + --set extraEnv[0].name=CATTLE_AGENT_IMAGE \ + --set extraEnv[0].value=rancher/rancher-agent:v2.13.1 +``` + +**Helm `upgrade` example:** + +```bash +helm upgrade rancher rancher-latest/rancher \ +... + --set extraEnv[0].name=CATTLE_AGENT_IMAGE \ + --set extraEnv[0].value=rancher/rancher-agent:v2.13.1 +``` + +**Important Upgrade Note:** + +The `CATTLE_AGENT_IMAGE` override is intended only as a temporary workaround for the affected configurations. Once a Rancher version is available that corrects this behavior, the `CATTLE_AGENT_IMAGE` override should be **removed** from Helm values, so that Rancher can resume managing the agent image normally and automatically track future image and tag changes. See [#53187](https://github.com/rancher/rancher/issues/53187#issuecomment-3676484603) for further information. +::: + +The upgrade instructions assume you are using Helm 3. + + + +For migration of installs started with Helm 2, refer to the official [Helm 2 to 3 migration docs.](https://helm.sh/blog/migrate-from-helm-v2-to-helm-v3/) The [Helm 2 upgrade page here](https://github.com/rancher/rancher-docs/tree/main/archived_docs/en/version-2.0-2.4/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/upgrades/helm2.md) provides a copy of the older upgrade instructions that used Helm 2, and it is intended to be used if upgrading to Helm 3 is not feasible. + +### For air-gapped installs: Populate private registry + +For [air-gapped installs only,](../other-installation-methods/air-gapped-helm-cli-install/air-gapped-helm-cli-install.md) collect and populate images for the new Rancher server version. Follow the guide to [populate your private registry](../other-installation-methods/air-gapped-helm-cli-install/publish-images.md) with the images for the Rancher version that you want to upgrade to. + +### For upgrades with cert-manager older than 0.8.0 + +[Let's Encrypt will be blocking cert-manager instances older than 0.8.0 starting November 1st 2019.](https://community.letsencrypt.org/t/blocking-old-cert-manager-versions/98753) Upgrade cert-manager to the latest version by following [these instructions.](../resources/upgrade-cert-manager.md) + +## Upgrade Outline + +Follow the steps to upgrade Rancher server: + +### 1. Back up Your Kubernetes Cluster that is Running Rancher Server + +Use the [backup application](../../../how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/back-up-rancher.md) to back up Rancher. + +You'll use the backup as a restore point if something goes wrong during upgrade. + +### 2. Update the Helm chart repository + +1. Update your local Helm repo cache. + + ``` + helm repo update + ``` + +1. Get the repository name that you used to install Rancher. + + For information about the repos and their differences, see [Helm Chart Repositories](../resources/choose-a-rancher-version.md#helm-chart-repositories). + + - Latest: Recommended for trying out the newest features + ``` + helm repo add rancher-latest https://releases.rancher.com/server-charts/latest + ``` + - Stable: Recommended for production environments + ``` + helm repo add rancher-stable https://releases.rancher.com/server-charts/stable + ``` + - Alpha: Experimental preview of upcoming releases. + ``` + helm repo add rancher-alpha https://releases.rancher.com/server-charts/alpha + ``` + Note: Upgrades are not supported to, from, or between Alphas. + + ``` + helm repo list + + NAME URL + stable https://charts.helm.sh/stable + rancher- https://releases.rancher.com/server-charts/ + ``` + + :::note + + If you want to switch to a different Helm chart repository, please follow the [steps on how to switch repositories](../resources/choose-a-rancher-version.md#switching-to-a-different-helm-chart-repository). If you switch repositories, make sure to list the repositories again before continuing onto Step 3 to ensure you have the correct one added. + + ::: + +1. Fetch the latest chart to install Rancher from the Helm chart repository. + + This command will pull down the latest charts and save it in the current directory as a `.tgz` file. + + ```plain + helm fetch rancher-/rancher + ``` + You can fetch the chart for the specific version you are upgrading to by adding in the `--version=` tag. For example: + + ```plain + helm fetch rancher-/rancher --version=2.6.8 + ``` + +### 3. Upgrade Rancher + +This section describes how to upgrade normal (Internet-connected) or air-gapped installations of Rancher with Helm. + +:::note Air Gap Instructions: + +If you are installing Rancher in an air-gapped environment, skip the rest of this page and render the Helm template by following the instructions on [this page.](air-gapped-upgrades.md) + +::: + +Get the values, which were passed with `--set`, from the current Rancher Helm chart that is installed. + +``` +helm get values rancher -n cattle-system + +hostname: rancher.my.org +``` + +:::note + +There will be more values that are listed with this command. This is just an example of one of the values. + +::: + +:::tip + +Your deployment name may vary; for example, if you're deploying Rancher through the AWS Marketplace, the deployment name is 'rancher-stable'. +Thus: +``` +helm get values rancher-stable -n cattle-system + +hostname: rancher.my.org +``` + +::: + +If you are upgrading cert-manager to the latest version from v1.5 or below, follow the [cert-manager upgrade docs](../resources/upgrade-cert-manager.md#option-c-upgrade-cert-manager-from-versions-15-and-below) to learn how to upgrade cert-manager without needing to perform an uninstall or reinstall of Rancher. Otherwise, follow the [steps to upgrade Rancher](#steps-to-upgrade-rancher) below. + +#### Steps to Upgrade Rancher + +Upgrade Rancher to the latest version with all your settings. + +Take all the values from the previous step and append them to the command using `--set key=value`. + + +``` +helm upgrade rancher rancher-/rancher \ + --namespace cattle-system \ + --set hostname=rancher.my.org +``` + +:::note + +The above is an example, there may be more values from the previous step that need to be appended. + +::: + +:::tip + +If you deploy Rancher through the AWS Marketplace, the deployment name is 'rancher-stable'. +Thus: +``` +helm upgrade rancher-stable rancher-/rancher \ + --namespace cattle-system \ + --set hostname=rancher.my.org +``` + +::: + +Alternatively, it's possible to export the current values to a file and reference that file during upgrade. For example, to only change the Rancher version: + +1. Export the current values to a file: + ``` + helm get values rancher -n cattle-system -o yaml > values.yaml + ``` +1. Update only the Rancher version: + + + ``` + helm upgrade rancher rancher-/rancher \ + --namespace cattle-system \ + -f values.yaml \ + --version=2.6.8 + ``` + +### 4. Verify the Upgrade + +Log into Rancher to confirm that the upgrade succeeded. + +:::tip + +Having network issues following upgrade? + +See [Restoring Cluster Networking](https://github.com/rancher/rancher-docs/tree/main/archived_docs/en/version-2.0-2.4/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/upgrades/namespace-migration.md). + +::: + +## Known Upgrade Issues + +A list of known issues for each Rancher version can be found in the release notes on [GitHub](https://github.com/rancher/rancher/releases) and on the [Rancher forums.](https://forums.rancher.com/c/announcements/12) diff --git a/versioned_docs/version-2.14/getting-started/installation-and-upgrade/installation-and-upgrade.md b/versioned_docs/version-2.14/getting-started/installation-and-upgrade/installation-and-upgrade.md new file mode 100644 index 00000000000..3a2a15d644d --- /dev/null +++ b/versioned_docs/version-2.14/getting-started/installation-and-upgrade/installation-and-upgrade.md @@ -0,0 +1,96 @@ +--- +title: Installing/Upgrading Rancher +description: Learn how to install Rancher in development and production environments. Read about single node and high availability installation +--- + + + + + +This section provides an overview of the architecture options of installing Rancher, describing advantages of each option. + +## Terminology + +In this section, + +- **The Rancher server** manages and provisions Kubernetes clusters. You can interact with downstream Kubernetes clusters through the Rancher server's user interface. The Rancher management server can be installed on any Kubernetes cluster, including hosted clusters, such as Amazon EKS clusters. +- **RKE (Rancher Kubernetes Engine)** is a certified Kubernetes distribution and CLI/library which creates and manages a Kubernetes cluster. +- **K3s (Lightweight Kubernetes)** is also a fully compliant Kubernetes distribution. It is newer than RKE, easier to use, and more lightweight, with a binary size of less than 100 MB. +- **RKE2** is a fully conformant Kubernetes distribution that focuses on security and compliance within the U.S. Federal Government sector. + +## Overview of Installation Options + +Rancher can be installed on these main architectures: + +### High-availability Kubernetes Install with the Helm CLI + +We recommend using Helm, a Kubernetes package manager, to install Rancher on multiple nodes on a dedicated Kubernetes cluster. For RKE clusters, three nodes are required to achieve a high-availability cluster. For K3s clusters, only two nodes are required. + +### Rancher on EKS Install with the AWS Marketplace + +Rancher can be installed on to Amazon Elastic Kubernetes Service (EKS) [through the AWS Marketplace](../quick-start-guides/deploy-rancher-manager/aws-marketplace.md). The EKS cluster deployed is production-ready and follows AWS best practices. + +### Single-node Kubernetes Install + +Rancher can be installed on a single-node Kubernetes cluster. In this case, the Rancher server doesn't have high availability, which is important for running Rancher in production. + +However, this option is useful if you want to save resources by using a single node in the short term, while preserving a high-availability migration path. In the future, you can add nodes to the cluster to get a high-availability Rancher server. + +### Docker Install + +For test and demonstration purposes, Rancher can be installed with Docker on a single node. A local Kubernetes cluster is installed in the single Docker container, and Rancher is installed on the local cluster. + +The Rancher backup operator can be used to migrate Rancher from the single Docker container install to an installation on a high-availability Kubernetes cluster. For details, refer to the documentation on [migrating Rancher to a new cluster.](../../how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/migrate-rancher-to-new-cluster.md) + +### Other Options + +There are also separate instructions for installing Rancher in an air gap environment or behind an HTTP proxy: + +| Level of Internet Access | Kubernetes Installation - Strongly Recommended | Docker Installation | +| ---------------------------------- | ------------------------------ | ---------- | +| With direct access to the Internet | [Docs](install-upgrade-on-a-kubernetes-cluster/install-upgrade-on-a-kubernetes-cluster.md) | [Docs](other-installation-methods/rancher-on-a-single-node-with-docker/rancher-on-a-single-node-with-docker.md) | +| Behind an HTTP proxy | [Docs](other-installation-methods/rancher-behind-an-http-proxy/rancher-behind-an-http-proxy.md) | These [docs,](other-installation-methods/rancher-on-a-single-node-with-docker/rancher-on-a-single-node-with-docker.md) plus this [configuration](../../reference-guides/single-node-rancher-in-docker/http-proxy-configuration.md) | +| In an air gap environment | [Docs](other-installation-methods/air-gapped-helm-cli-install/air-gapped-helm-cli-install.md) | [Docs](other-installation-methods/air-gapped-helm-cli-install/air-gapped-helm-cli-install.md) | + +We recommend installing Rancher on a Kubernetes cluster, because in a multi-node cluster, the Rancher management server becomes highly available. This high-availability configuration helps maintain consistent access to the downstream Kubernetes clusters that Rancher will manage. + +For that reason, we recommend that for a production-grade architecture, you should set up a high-availability Kubernetes cluster, then install Rancher on it. After Rancher is installed, you can use Rancher to deploy and manage Kubernetes clusters. + +For testing or demonstration purposes, you can install Rancher in single Docker container. In this Docker install, you can use Rancher to set up Kubernetes clusters out-of-the-box. The Docker install allows you to explore the Rancher server functionality, but it is intended to be used for development and testing purposes only. + +Our [instructions for installing Rancher on Kubernetes](install-upgrade-on-a-kubernetes-cluster/install-upgrade-on-a-kubernetes-cluster.md) describe how to first use K3s or RKE to create and manage a Kubernetes cluster, then install Rancher onto that cluster. + +When the nodes in your Kubernetes cluster are running and fulfill the [node requirements,](installation-requirements/installation-requirements.md) you will use Helm to deploy Rancher onto Kubernetes. Helm uses Rancher's Helm chart to install a replica of Rancher on each node in the Kubernetes cluster. We recommend using a load balancer to direct traffic to each replica of Rancher in the cluster. + +For a longer discussion of Rancher architecture, refer to the [architecture overview,](../../reference-guides/rancher-manager-architecture/rancher-manager-architecture.md) [recommendations for production-grade architecture,](../../reference-guides/rancher-manager-architecture/architecture-recommendations.md) or our [best practices guide.](../../reference-guides/best-practices/rancher-server/tips-for-running-rancher.md) + +## Prerequisites + +Before installing Rancher, make sure that your nodes fulfill all of the [installation requirements.](installation-requirements/installation-requirements.md) + +## Architecture Tip + +For the best performance and greater security, we recommend a separate, dedicated Kubernetes cluster for the Rancher management server. Running user workloads on this cluster is not advised. After deploying Rancher, you can [create or import clusters](../../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/kubernetes-clusters-in-rancher-setup.md) for running your workloads. + +For more architecture recommendations, refer to [this page.](../../reference-guides/rancher-manager-architecture/architecture-recommendations.md) + +### More Options for Installations on a Kubernetes Cluster + +Refer to the [Helm chart options](installation-references/helm-chart-options.md) for details on installing Rancher on a Kubernetes cluster with other configurations, including: + +- With [API auditing to record all transactions](installation-references/helm-chart-options.md#api-audit-log) +- With [TLS termination on a load balancer](installation-references/helm-chart-options.md#external-tls-termination) +- With a [custom Ingress](installation-references/helm-chart-options.md#customizing-your-ingress) + +In the Rancher installation instructions, we recommend using K3s or RKE to set up a Kubernetes cluster before installing Rancher on the cluster. Both K3s and RKE have many configuration options for customizing the Kubernetes cluster to suit your specific environment. For the full list of their capabilities, refer to their documentation: + +- [RKE configuration options](https://rancher.com/docs/rke/latest/en/config-options/) +- [K3s configuration options](https://rancher.com/docs/k3s/latest/en/installation/install-options/) + +### More Options for Installations with Docker + +Refer to the [docs about options for Docker installs](other-installation-methods/rancher-on-a-single-node-with-docker/rancher-on-a-single-node-with-docker.md) for details about other configurations including: + +- With [API auditing to record all transactions](../../reference-guides/single-node-rancher-in-docker/advanced-options.md#api-audit-log) +- With an [external load balancer](../../how-to-guides/advanced-user-guides/configure-layer-7-nginx-load-balancer.md) +- With a [persistent data store](../../reference-guides/single-node-rancher-in-docker/advanced-options.md#persistent-data) diff --git a/versioned_docs/version-2.14/getting-started/installation-and-upgrade/installation-references/feature-flags.md b/versioned_docs/version-2.14/getting-started/installation-and-upgrade/installation-references/feature-flags.md new file mode 100644 index 00000000000..dd5da589a28 --- /dev/null +++ b/versioned_docs/version-2.14/getting-started/installation-and-upgrade/installation-references/feature-flags.md @@ -0,0 +1,77 @@ +--- +title: Feature Flags +--- + + + + + +With feature flags, you can try out optional or experimental features, and enable legacy features that are being phased out. + +To learn more about feature values and how to enable them, see [Enabling Experimental Features](../../../how-to-guides/advanced-user-guides/enable-experimental-features/enable-experimental-features.md). + +:::note + +Some feature flags require a restart of the Rancher container. Features that require a restart are marked in the Rancher UI. + +::: + +The following is a list of feature flags available in Rancher. If you've upgraded from a previous Rancher version, you may see additional flags in the Rancher UI, such as `proxy` or `dashboard` (both [discontinued](https://github.com/rancher/rancher-docs/tree/main/archived_docs/en/version-2.5/reference-guides/installation-references/feature-flags.md)): + +- `aggregated-roletemplates`: Use cluster role aggregation architecture for RoleTemplates, ProjectRoleTemplateBindings, and ClusterRoleTemplateBindings. See [RoleTemplate Aggregation](../../../how-to-guides/advanced-user-guides/enable-experimental-features/role-template-aggregation.md) for more information. +- `clean-stale-secrets`: Removes stale secrets from the `cattle-impersonation-system` namespace. This slowly cleans up old secrets which are no longer being used by the impersonation system. +- `continuous-delivery`: Allows Fleet GitOps to be disabled separately from Fleet. See [Continuous Delivery.](../../../how-to-guides/advanced-user-guides/enable-experimental-features/continuous-delivery.md) for more information. +- `fleet`: The Rancher provisioning framework in v2.6 and later requires Fleet. The flag will be automatically enabled when you upgrade, even if you disabled this flag in an earlier version of Rancher. See [Continuous Delivery with Fleet](../../../integrations-in-rancher/fleet/fleet.md) for more information. +- `harvester`: Manages access to the Virtualization Management page, where users can navigate directly to Harvester clusters and access the Harvester UI. See [Harvester Integration Overview](../../../integrations-in-rancher/harvester/overview.md) for more information. +- `imperative-api-extension`: Enables Rancher's [extension API server](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/apiserver-aggregation/) to register new APIs to Kubernetes. This flag is enabled by default. See the [Extension API Server](../../../api/extension-apiserver.md) page for more information. +- `istio-virtual-service-ui`: Enables a [visual interface](../../../how-to-guides/advanced-user-guides/enable-experimental-features/istio-traffic-management-features.md) to create, read, update, and delete Istio virtual services and destination rules, which are Istio traffic management features. +- `legacy`: Enables a set of features from 2.5.x and earlier, that are slowly being phased out in favor of newer implementations. These are a mix of deprecated features as well as features that will eventually be available to newer versions. This flag is disabled by default on new Rancher installations. If you're upgrading from a previous version of Rancher, this flag is enabled. +- `managed-system-upgrade-controller`: Enables the installation of the system-upgrade-controller app in downstream imported RKE2/K3s clusters, as well as in the local cluster if it is an RKE2/K3s cluster. + +:::note Important: + +This `managed-system-upgrade-controller` flag is intended for **internal use only** and does not have an associated Feature CR. Use with caution. + +To control whether Rancher should manage the Kubernetes version of imported RKE2/K3s clusters, it is recommended to use the [imported-cluster-version-management](../../../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/register-existing-clusters.md#configuring-version-management-for-rke2-and-k3s-clusters) feature that is available in Rancher v2.11.0 or newer. + +::: + +:::danger + +If the `managed-system-upgrade-controller` flag was **disabled** in Rancher v2.10.x, and any imported RKE2/K3s clusters were upgraded **outside of Rancher**, follow the steps below to prevent the unexpected installation of the system-upgrade-controller app and to ensure the [imported-cluster-version-management](../../../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/register-existing-clusters.md#configuring-version-management-for-rke2-and-k3s-clusters) feature works correctly: + +1. Upgrade Rancher to v2.11.0 or newer, making sure to **retain** the `managed-system-upgrade-controller=false` feature flag in Helm values if it was set during the v2.10.x installation. +1. After Rancher is fully up and running, disable the `imported-cluster-version-management` setting. You can do this either through the Rancher UI by clicking **☰ > Global Settings > Settings > imported-cluster-version-management**, or by editing the corresponding `Setting.management.cattle.io/v3` custom resource via kubectl. +1. Perform a second Helm upgrade, this time omitting the `managed-system-upgrade-controller=false` feature flag. + +Now, the imported cluster version management is disabled by default, and Rancher no longer installs the system-upgrade-controller app on imported clusters automatically. + +You can enable this feature on a per-cluster basis. For more information, please refer to the [documentation](../../../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/register-existing-clusters.md#configuring-version-management-for-rke2-and-k3s-clusters). + +::: + +- `multi-cluster-management`: Allows multi-cluster provisioning and management of Kubernetes clusters. This flag can only be set at install time. It can't be enabled or disabled later. +- `rke2`: Enables provisioning RKE2 clusters. This flag is enabled by default. +- `token-hashing`: Enables token hashing. Once enabled, existing tokens will be hashed and all new tokens will be hashed automatically with the SHA256 algorithm. Once a token is hashed it can't be undone. This flag can't be disabled after its enabled. See [API Tokens](../../../api/api-tokens.md#token-hashing) for more information. +- `uiextension`: Enables UI extensions. This flag is enabled by default. Enabling or disabling the flag forces the Rancher pod to restart. The first time this flag is set to `Active`, it creates a CRD and enables the controllers and endpoints necessary for the feature to work. If set to `Disabled`, it disables the previously mentioned controllers and endpoints. Setting `uiextension` to `Disabled` has no effect on the CRD -- it does not create a CRD if it does not yet exist, nor does it delete the CRD if it already exists. +- `unsupported-storage-drivers`: Enables types for storage providers and provisioners that aren't enabled by default. See [Allow Unsupported Storage Drivers](../../../how-to-guides/advanced-user-guides/enable-experimental-features/unsupported-storage-drivers.md) for more information. +- `ui-sql-cache`: Enables an SQLite-based cache for UI tables and Server-Side Pagination. See [UI Server-Side Pagination](../../../how-to-guides/advanced-user-guides/ui-server-side-pagination.md) for more information. + +The following table shows the availability and default values for some feature flags in Rancher. Features marked "GA" are generally available: + +| Feature Flag Name | Default Value | Status | Available As Of | Additional Information | +| ----------------------------- | ------------- | ------------ | --------------- | ---------------------- | +| `aggregated-roletemplates` | `Disabled` | Experimental | v2.11.0 | This flag value is locked on install and can't be changed. | +| `clean-stale-secrets` | `Active` | GA | v2.10.2 | | +| `continuous-delivery` | `Active` | GA | v2.6.0 | | +| `external-rules` | v2.7.14: `Disabled`, v2.8.5: `Active` | Removed | v2.7.14, v2.8.5 | This flag affected [external `RoleTemplate` behavior](../../../how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/cluster-and-project-roles.md#external-roletemplate-behavior). It is removed in Rancher v2.9.0 and later as the behavior is enabled by default. | +| `fleet` | `Active` | Can no longer be disabled | v2.6.0 | | +| `fleet` | `Active` | GA | v2.5.0 | | +| `harvester` | `Active` | Experimental | v2.6.1 | | +| `imperative-api-extension` | `Active` | GA | v2.11.0 | | +| `legacy` | `Disabled` for new installs, `Active` for upgrades | GA | v2.6.0 | | +| `managed-system-upgrade-controller` | `Active` | GA | v2.10.0 | | +| `rke2` | `true` | Experimental | v2.6.0 | | +| `token-hashing` | `Disabled` for new installs, `Active` for upgrades | GA | v2.6.0 | | +| `uiextension` | `Active` | GA | v2.9.0 | | +| `ui-sql-cache` | `Active` | GA | v2.9.0 | | diff --git a/versioned_docs/version-2.14/getting-started/installation-and-upgrade/installation-references/helm-chart-options.md b/versioned_docs/version-2.14/getting-started/installation-and-upgrade/installation-references/helm-chart-options.md new file mode 100644 index 00000000000..3ee46920bbd --- /dev/null +++ b/versioned_docs/version-2.14/getting-started/installation-and-upgrade/installation-references/helm-chart-options.md @@ -0,0 +1,316 @@ +--- +title: Rancher Helm Chart Options +keywords: [rancher helm chart, rancher helm options, rancher helm chart options, helm chart rancher, helm options rancher, helm chart options rancher] +--- + + + + + +This page is a configuration reference for the Rancher Helm chart. + +For help choosing a Helm chart version, refer to [this page.](../../../getting-started/installation-and-upgrade/resources/choose-a-rancher-version.md) + +For information on enabling experimental features, refer to [this page.](../../../how-to-guides/advanced-user-guides/enable-experimental-features/enable-experimental-features.md) + +## Common Options + +| Option | Default Value | Description | +| ------------------------- | ------------- | ---------------------------------------------------------------------------------- | +| `bootstrapPassword` | " " | `string` - Set the [bootstrap password](#bootstrap-password) for the first admin user. After logging in, the admin should reset their password. A randomly generated bootstrap password is used if this value is not set. +| `hostname` | " " | `string` - the Fully Qualified Domain Name for your Rancher Server | +| `ingress.tls.source` | "rancher" | `string` - Where to get the cert for the ingress. - "rancher, letsEncrypt, secret" | +| `letsEncrypt.email` | " " | `string` - Your email address | +| `letsEncrypt.environment` | "production" | `string` - Valid options: "staging, production" | +| `privateCA` | false | `bool` - Set to true if your cert is signed by a private CA | + +
+ +## Advanced Options + +| Option | Default Value | Description | +| ------------------------------ | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | +| `additionalTrustedCAs` | false | `bool` - See [Additional Trusted CAs](#additional-trusted-cas) | +| `addLocal` | "true" | `string` - Have Rancher detect and import the "local" (upstream) Rancher server cluster. _Note: This option is no longer available in v2.5.0. Consider using the `restrictedAdmin` option to prevent users from modifying the local cluster._ | +| `agentTLSMode` | "" | `string` - either `system-store` or `strict`. See [Agent TLS Enforcement](./tls-settings.md#agent-tls-enforcement) | +| `antiAffinity` | "preferred" | `string` - AntiAffinity rule for Rancher pods - "preferred, required" | +| `auditLog.destination` | "sidecar" | `string` - Stream to sidecar container console or hostPath volume - "sidecar, hostPath" | +| `auditLog.hostPath` | "/var/log/rancher/audit" | `string` - log file destination on host (only applies when `auditLog.destination` is set to `hostPath`) | +| `auditLog.enabled` | false | `bool` - Enables / disables audit logging. | +| `auditLog.level` | 0 | `int` - Sets the [API Audit Log](../../../how-to-guides/advanced-user-guides/enable-api-audit-log.md) level [0-3]. | +| `auditLog.maxAge` | 1 | `int` - maximum number of days to retain old audit log files (only applies when `auditLog.destination` is set to `hostPath`) | +| `auditLog.maxBackup` | 1 | `int` - maximum number of audit log files to retain (only applies when `auditLog.destination` is set to `hostPath`) | +| `auditLog.maxSize` | 100 | `int` - maximum size in megabytes of the audit log file before it gets rotated (only applies when `auditLog.destination` is set to `hostPath`) | +| `auditLog.image.repository` | "registry.suse.com/bci/bci-micro" | `string` - Location for the image used to collect audit logs. | +| `auditLog.image.tag` | "15.4.14.3" | `string` - Tag for the image used to collect audit logs. | +| `auditLog.image.pullPolicy` | "IfNotPresent" | `string` - Override imagePullPolicy for auditLog images - "Always", "Never", "IfNotPresent". | +| `busyboxImage` | "" | `string` - Image location for busybox image used to collect audit logs. _Note: This option is deprecated use `auditLog.image.repository` to control auditing sidecar image._ | +| `certmanager.version` | "" | `string` - set cert-manager compatibility | +| `debug` | false | `bool` - set debug flag on rancher server | +| `extraEnv` | [] | `list` - set additional environment variables for Rancher | +| `imagePullSecrets` | [] | `list` - list of names of Secret resource containing private registry credentials | +| `ingress.configurationSnippet` | "" | `string` - additional Nginx configuration. Can be used for proxy configuration. | +| `ingress.extraAnnotations` | {} | `map` - additional annotations to customize the ingress | +| `ingress.enabled` | true | When set to false, Helm will not install a Rancher ingress. Set the option to false to deploy your own ingress. | +| `letsEncrypt.ingress.class` | "" | `string` - optional ingress class for the cert-manager acmesolver ingress that responds to the Let's Encrypt ACME challenges. Options: traefik, nginx. | | +| `noProxy` | "127.0.0.0/8,10.0.0.0/8,172.16.0.0/12,192.168.0.0/16,.svc,.cluster.local,cattle-system.svc" | `string` - comma separated list of hostnames or ip address not to use the proxy | | +| `proxy` | "" | `string` - HTTP[S] proxy server for Rancher | +| `rancherImage` | "rancher/rancher" | `string` - rancher image source | +| `rancherImagePullPolicy` | "IfNotPresent" | `string` - Override imagePullPolicy for rancher server images - "Always", "Never", "IfNotPresent" | +| `rancherImageTag` | same as chart version | `string` - rancher/rancher image tag | +| `replicas` | 3 | `int` - Number of Rancher server replicas. Setting to -1 will dynamically choose 1, 2, or 3 based on the number of available nodes in the cluster. | +| `resources` | {} | `map` - rancher pod resource requests & limits | +| `systemDefaultRegistry` | "" | `string` - private registry to be used for all system container images, e.g., http://registry.example.com/ | +| `tls` | "ingress" | `string` - See [External TLS Termination](#external-tls-termination) for details. - "ingress, external" | +| `useBundledSystemChart` | `false` | `bool` - select to use the system-charts packaged with Rancher server. This option is used for air gapped installations. | + + +When using Rancher v2.12.0 and above, Rancher will use an audit logging controller that watches `AuditPolicy` CRs for configuring additional redactions, for more info see [API Audit Log](../../../how-to-guides/advanced-user-guides/enable-api-audit-log.md). + + +### Bootstrap Password + +You can [set a specific bootstrap password](../resources/bootstrap-password.md) during Rancher installation. If you don't set a specific bootstrap password, Rancher randomly generates a password for the first admin account. + +When you log in for the first time, use the bootstrap password you set to log in. If you did not set a bootstrap password, the Rancher UI shows commands that can be used to [retrieve the bootstrap password](../resources/bootstrap-password.md#retrieving-the-bootstrap-password). Run those commands and log in to the account. After you log in for the first time, you are asked to reset the admin password. + +### API Audit Log + +Enabling the [API Audit Log](../../../how-to-guides/advanced-user-guides/enable-api-audit-log.md). + +You can collect this log as you would any container log. Enable [logging](../../../integrations-in-rancher/logging/logging.md) for the `System` Project on the Rancher server cluster. + +```plain +--set auditLog.enabled=true --set auditLog.level=1 +``` + +By default enabling Audit Logging will create a sidecar container in the Rancher pod. This container (`rancher-audit-log`) will stream the log to `stdout`. You can collect this log as you would any container log. When using the sidecar as the audit log destination, the `hostPath`, `maxAge`, `maxBackups`, and `maxSize` options do not apply. It's advised to use your OS or Docker daemon's log rotation features to control disk space use. Enable [logging](../../../integrations-in-rancher/logging/logging.md) for the Rancher server cluster or System Project. + +Set the `auditLog.destination` to `hostPath` to forward logs to volume shared with the host system instead of streaming to a sidecar container. When setting the destination to `hostPath` you may want to adjust the other auditLog parameters for log rotation. + +### Setting Extra Environment Variables + +You can set extra environment variables for Rancher server using `extraEnv`. This list is passed to the Rancher deployment in its YAML format. It is embedded under `env` for the Rancher container. Refer to the Kubernetes documentation for setting container environment variables, `extraEnv` can use any of the keys referenced in [Define Environment Variables for a Container](https://kubernetes.io/docs/tasks/inject-data-application/define-environment-variable-container/#define-an-environment-variable-for-a-container). + +Consider an example that uses the `name` and `value` keys: + +```plain +--set 'extraEnv[0].name=CATTLE_TLS_MIN_VERSION' +--set 'extraEnv[0].value=1.0' +``` + +If passing sensitive data as the value for an environment variable, such as proxy authentication credentials, it is strongly recommended that a secret reference is used. This will prevent sensitive data from being exposed in Helm or the Rancher deployment. + +Consider an example that uses the `name`, `valueFrom.secretKeyRef.name`, and `valueFrom.secretKeyRef.key` keys. See example in [HTTP Proxy](#http-proxy) + +### TLS Settings + +When you install Rancher inside of a Kubernetes cluster, TLS is offloaded at the cluster's ingress controller. The possible TLS settings depend on the used ingress controller. + +See [TLS settings](tls-settings.md) for more information and options. + +### Import `local` Cluster + +By default Rancher server will detect and import the `local` cluster it's running on. User with access to the `local` cluster will essentially have "root" access to all the clusters managed by Rancher server. + +:::caution + +If you turn addLocal off, most Rancher v2.5 features won't work, including the EKS provisioner. + +::: + +If this is a concern in your environment you can set this option to "false" on your initial install. + +This option is only effective on the initial Rancher install. See [Issue 16522](https://github.com/rancher/rancher/issues/16522) for more information. + +```plain +--set addLocal="false" +``` + +### Customizing your Ingress + +To customize or use a different ingress with Rancher server you can set your own Ingress annotations. + +Example on setting a custom certificate issuer: + +```plain +--set ingress.extraAnnotations.'cert-manager\.io/cluster-issuer'=issuer-name +``` + +Example on setting a static proxy header with `ingress.configurationSnippet`. This value is parsed like a template so variables can be used. + +```plain +--set ingress.configurationSnippet='more_set_input_headers X-Forwarded-Host {{ .Values.hostname }};' +``` + +### HTTP Proxy + +Rancher requires internet access for some functionality (Helm charts). Use `proxy` to set your proxy server or use `extraEnv` to set the `HTTPS_PROXY` environment variable to point to your proxy server. + +Add your IP exceptions to the `noProxy` chart value as a comma separated list. Make sure you add the following values: +- Pod cluster IP range (default: `10.42.0.0/16`). +- Service cluster IP range (default: `10.43.0.0/16`). +- Internal cluster domains (default: `.svc,.cluster.local`). +- Any worker cluster `controlplane` nodes. +Rancher supports CIDR notation ranges in this list. + +When not including sensitive data, the `proxy` or `extraEnv` chart options can be used. When using `extraEnv` the `noProxy` Helm option is ignored. Therefore, the `NO_PROXY` environment variable must also be set with `extraEnv`. + +The following is an example of setting proxy using the `proxy` chart option: + +```plain +--set proxy="http:///" +``` + +Example of setting proxy using the `extraEnv` chart option: +```plain +--set extraEnv[1].name=HTTPS_PROXY +--set extraEnv[1].value="http://:/" +--set extraEnv[2].name=NO_PROXY +--set extraEnv[2].value="127.0.0.0/8\,10.0.0.0/8\,172.16.0.0/12\,192.168.0.0/16\,.svc\,.cluster.local" +``` + +When including sensitive data, such as proxy authentication credentials, use the `extraEnv` option with `valueFrom.secretRef` to prevent sensitive data from being exposed in Helm or the Rancher deployment. + +The following is an example of using `extraEnv` to configure proxy. This example secret would contain the value `"http://:@:/"` in the secret's `"https-proxy-url"` key: +```plain +--set extraEnv[1].name=HTTPS_PROXY +--set extraEnv[1].valueFrom.secretKeyRef.name=secret-name +--set extraEnv[1].valueFrom.secretKeyRef.key=https-proxy-url +--set extraEnv[2].name=NO_PROXY +--set extraEnv[2].value="127.0.0.0/8\,10.0.0.0/8\,172.16.0.0/12\,192.168.0.0/16\,.svc\,.cluster.local" +``` + +To learn more about how to configure environment variables, refer to [Define Environment Variables for a Container](https://kubernetes.io/docs/tasks/inject-data-application/define-environment-variable-container/#define-an-environment-variable-for-a-container). + +### Additional Trusted CAs + +If you have private registries, catalogs or a proxy that intercepts certificates, you may need to add more trusted CAs to Rancher. + +```plain +--set additionalTrustedCAs=true +``` + +Once the Rancher deployment is created, copy your CA certs in pem format into a file named `ca-additional.pem` and use `kubectl` to create the `tls-ca-additional` secret in the `cattle-system` namespace. + +```plain +kubectl -n cattle-system create secret generic tls-ca-additional --from-file=ca-additional.pem=./ca-additional.pem +``` + +### Private Registry and Air Gap Installs + +For details on installing Rancher with a private registry, see the [air gap installation docs.](../other-installation-methods/air-gapped-helm-cli-install/air-gapped-helm-cli-install.md) + +## External TLS Termination + +We recommend configuring your load balancer as a Layer 4 balancer, forwarding plain 80/tcp and 443/tcp to the Rancher Management cluster nodes. The Ingress Controller on the cluster will redirect http traffic on port 80 to https on port 443. + +You may terminate the SSL/TLS on a L7 load balancer external to the Rancher cluster (ingress). Use the `--set tls=external` option and point your load balancer at port http 80 on all of the Rancher cluster nodes. This will expose the Rancher interface on http port 80. Be aware that clients that are allowed to connect directly to the Rancher cluster will not be encrypted. If you choose to do this we recommend that you restrict direct access at the network level to just your load balancer. + +:::note + +If you are using a Private CA signed certificate (or if `agent-tls-mode` is set to `strict`), add `--set privateCA=true` and see [Adding TLS Secrets - Using a Private CA Signed Certificate](../../../getting-started/installation-and-upgrade/resources/add-tls-secrets.md) to add the CA cert for Rancher. + +::: + +Your load balancer must support long lived websocket connections and will need to insert proxy headers so Rancher can route links correctly. + +### Configuring Ingress for External TLS when Using NGINX v0.22 + +In NGINX v0.22, the behavior of NGINX has [changed](https://github.com/kubernetes/ingress-nginx/blob/06efac9f0b6f8f84b553f58ccecf79dc42c75cc6/Changelog.md) regarding forwarding headers and external TLS termination. Therefore, in the scenario that you are using external TLS termination configuration with NGINX v0.22, you must enable the `use-forwarded-headers` option for ingress: + +For RKE2 installations, you can create a custom `rke2-ingress-nginx-config.yaml` file at `/var/lib/rancher/rke2/server/manifests/rke2-ingress-nginx-config.yaml` containing this required setting to enable using forwarded headers with external TLS termination. Without this required setting applied, the external LB will continuously respond with redirect loops it receives from the ingress controller. (This can be created before or after rancher is installed, rke2 server agent will notice this addition and automatically apply it.) + +```yaml +--- +apiVersion: helm.cattle.io/v1 +kind: HelmChartConfig +metadata: + name: rke2-ingress-nginx + namespace: kube-system +spec: + valuesContent: |- + controller: + config: + use-forwarded-headers: "true" +``` + +### Required Headers + +- `Host` +- `X-Forwarded-Proto` +- `X-Forwarded-Port` +- `X-Forwarded-For` + +### Recommended Timeouts + +- Read Timeout: `1800 seconds` +- Write Timeout: `1800 seconds` +- Connect Timeout: `30 seconds` + +### Health Checks + +Rancher will respond `200` to health checks on the `/healthz` endpoint. + +### Example NGINX config + +This NGINX configuration is tested on NGINX 1.14. + +:::caution + +This NGINX configuration is only an example and may not suit your environment. For complete documentation, see [NGINX Load Balancing - HTTP Load Balancing](https://docs.nginx.com/nginx/admin-guide/load-balancer/http-load-balancer/). + +::: + +- Replace `IP_NODE1`, `IP_NODE2` and `IP_NODE3` with the IP addresses of the nodes in your cluster. +- Replace both occurrences of `FQDN` to the DNS name for Rancher. +- Replace `/certs/fullchain.pem` and `/certs/privkey.pem` to the location of the server certificate and the server certificate key respectively. + +``` +worker_processes 4; +worker_rlimit_nofile 40000; + +events { + worker_connections 8192; +} + +http { + upstream rancher { + server IP_NODE_1:80; + server IP_NODE_2:80; + server IP_NODE_3:80; + } + + map $http_upgrade $connection_upgrade { + default Upgrade; + '' close; + } + + server { + listen 443 ssl http2; + server_name FQDN; + ssl_certificate /certs/fullchain.pem; + ssl_certificate_key /certs/privkey.pem; + + location / { + proxy_set_header Host $host; + proxy_set_header X-Forwarded-Proto $scheme; + proxy_set_header X-Forwarded-Port $server_port; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + proxy_pass http://rancher; + proxy_http_version 1.1; + proxy_set_header Upgrade $http_upgrade; + proxy_set_header Connection $connection_upgrade; + # This allows the ability for the execute shell window to remain open for up to 15 minutes. Without this parameter, the default is 1 minute and will automatically close. + proxy_read_timeout 900s; + proxy_buffering off; + } + } + + server { + listen 80; + server_name FQDN; + return 301 https://$server_name$request_uri; + } +} +``` diff --git a/versioned_docs/version-2.14/getting-started/installation-and-upgrade/installation-references/installation-references.md b/versioned_docs/version-2.14/getting-started/installation-and-upgrade/installation-references/installation-references.md new file mode 100644 index 00000000000..35c25fb722c --- /dev/null +++ b/versioned_docs/version-2.14/getting-started/installation-and-upgrade/installation-references/installation-references.md @@ -0,0 +1,9 @@ +--- +title: Installation References +--- + + + + + +Please see the following reference guides for other installation resources: [Rancher Helm chart options](helm-chart-options.md), [TLS settings](tls-settings.md), and [feature flags](feature-flags.md). diff --git a/versioned_docs/version-2.14/getting-started/installation-and-upgrade/installation-references/tls-settings.md b/versioned_docs/version-2.14/getting-started/installation-and-upgrade/installation-references/tls-settings.md new file mode 100644 index 00000000000..3e6c745857c --- /dev/null +++ b/versioned_docs/version-2.14/getting-started/installation-and-upgrade/installation-references/tls-settings.md @@ -0,0 +1,104 @@ +--- +title: TLS Settings +--- + + + + + +Changing the default TLS settings depends on the chosen installation method. + +## Running Rancher in a highly available Kubernetes cluster + +When you install Rancher inside of a Kubernetes cluster, TLS is offloaded at the cluster's ingress controller. The possible TLS settings depend on the used ingress controller: + +* nginx-ingress-controller (default for RKE2): [Default TLS Version and Ciphers](https://kubernetes.github.io/ingress-nginx/user-guide/tls/#default-tls-version-and-ciphers). +* traefik (default for K3s): [TLS Options](https://doc.traefik.io/traefik/https/tls/#tls-options). + +## Running Rancher in a single Docker container + +The default TLS configuration only accepts TLS 1.2 and secure TLS cipher suites. You can change this by setting the following environment variables: + +| Parameter | Description | Default | Available options | +|-----|-----|-----|-----| +| `CATTLE_TLS_MIN_VERSION` | Minimum TLS version | `1.2` | `1.0`, `1.1`, `1.2`, `1.3` | +| `CATTLE_TLS_CIPHERS` | Allowed TLS cipher suites | `TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256`,
`TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384`,
`TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305`,
`TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256`,
`TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384`,
`TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305` | See [Golang tls constants](https://golang.org/pkg/crypto/tls/#pkg-constants) | + +## Agent TLS Enforcement + +The `agent-tls-mode` setting controls how Rancher's agents (`cluster-agent`, `fleet-agent`, and `system-agent`) validate Rancher's certificate. + +When the value is set to `strict`, Rancher's agents only trust certificates generated by the Certificate Authority contained in the `cacerts` setting. +When the value is set to `system-store`, Rancher's agents trust any certificate generated by a public Certificate Authority contained in the operating system's trust store including those signed by authorities such as Let's Encrypt. This can be a security risk, since any certificate generated by these external authorities, which are outside the user's control, are considered valid in this state. + +While the `strict` option enables a higher level of security, it requires Rancher to have access to the CA which generated the certificate visible to the agents. In the case of certain certificate configurations (notably, external certificates), this is not automatic, and extra configuration is needed. See the [installation guide](../install-upgrade-on-a-kubernetes-cluster/install-upgrade-on-a-kubernetes-cluster.md#3-choose-your-ssl-configuration) for more information on which scenarios require extra configuration. + +In Rancher v2.9.0 and later, this setting defaults to `strict` on new installs. For users installing or upgrading from a prior Rancher version, it is set to `system-store`. + +### Preparing for the Setting Change + +Each cluster contains a condition in the status field called `AgentTlsStrictCheck`. If `AgentTlsStrictCheck` is set to `"True"`, this indicates that the agents for the cluster are ready to operate in `strict` mode. You can manually inspect each cluster to see if they are ready using the Rancher UI or a kubectl command such as the following: + +```bash +## the below command skips ouputs $CLUSTER_NAME,$STATUS for all non-local clusters +kubectl get cluster.management.cattle.io -o jsonpath='{range .items[?(@.metadata.name!="local")]}{.metadata.name},{.status.conditions[?(@.type=="AgentTlsStrictCheck")].status}{"\n"}{end}' +``` + +### Changing the Setting + +You can change the setting using the Rancher UI or the `agentTLSMode` [helm chart option](./helm-chart-options.md). + +:::note + +If you specify the value through the Helm chart, you may only modify the value with Helm. + +::: + +:::warning + +Depending on your cert setup, additional action may be required, such as uploading the Certificate Authority which signed your certs. Review the [installation guide](../install-upgrade-on-a-kubernetes-cluster/install-upgrade-on-a-kubernetes-cluster.md#3-choose-your-ssl-configuration) before changing the setting to see if any additional requirements apply to your setup. + +::: + +To change the setting's value through the UI, navigate to the **Global Settings** page, and find the `agent-tls-mode` setting near the bottom of the page. When you change the setting through the UI, Rancher first checks that all downstream clusters have the condition `AgentTlsStrictCheck` set to `"True"` before allowing the request. This prevents outages from a certificate mismatch. + + +#### Overriding the Setting Validation Checks + +In some cases, you may want to override the check ensuring all agents can accept the new TLS configuration: + +:::warning + +Rancher checks the status of all downstream clusters to prevent outages. Overriding this check is not recommended, and should be done with great caution. + +::: + +1. As an admin, generate a kubeconfig for the local cluster. In the below examples, this was saved to the `local_kubeconfig.yaml` file. +2. Retrieve the current setting and save it to `setting.yaml`: +```bash +kubectl get setting agent-tls-mode -o yaml --kubeconfig=local_kubeconfig.yaml > setting.yaml +``` +3. Update the `setting.yaml` file, replacing `value` with `strict`. Adding the `cattle.io/force: "true"` annotation overrides the cluster condition check, and should only be done with great care: + +:::warning + +Including the `cattle.io/force` annotation with any value (including, for example `"false"`) overrides the cluster condition check. + +::: + +```yaml +apiVersion: management.cattle.io/v3 +customized: false +default: strict +kind: Setting +metadata: + name: agent-tls-mode + annotations: + cattle.io/force: "true" +source: "" +value: strict +``` +4. Apply the new version of the setting: +```bash +kubectl apply -f setting.yaml --kubeconfig=local_kubeconfig.yaml +``` diff --git a/versioned_docs/version-2.14/getting-started/installation-and-upgrade/installation-requirements/installation-requirements.md b/versioned_docs/version-2.14/getting-started/installation-and-upgrade/installation-requirements/installation-requirements.md new file mode 100644 index 00000000000..c5f7181fca5 --- /dev/null +++ b/versioned_docs/version-2.14/getting-started/installation-and-upgrade/installation-requirements/installation-requirements.md @@ -0,0 +1,198 @@ +--- +title: Installation Requirements +description: Learn the node requirements for each node running Rancher server when you’re configuring Rancher to run either in a Kubernetes setup +--- + + + + + +This page describes the software, hardware, and networking requirements for the nodes where the Rancher server will be installed. The Rancher server can be installed on a single node or a high-availability Kubernetes cluster. + +:::note Important: + +If you install Rancher on a Kubernetes cluster, requirements are different from the [node requirements for downstream user clusters,](../../../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/node-requirements-for-rancher-managed-clusters.md) which will run your apps and services. + +::: + +The Rancher UI works best in Firefox or Chromium based browsers (Chrome, Edge, Opera, Brave, etc). + +See our page on [best practices](../../../reference-guides/best-practices/rancher-server/tips-for-running-rancher.md) for a list of recommendations for running a Rancher server in production. + +## Kubernetes Compatibility with Rancher + +Rancher needs to be installed on a supported Kubernetes version. Consult the [Rancher support matrix](https://www.suse.com/suse-rancher/support-matrix/all-supported-versions) to ensure that your intended version of Kubernetes is supported. + +Regardless of version and distribution, the Kubernetes cluster must have the aggregation API layer properly configured to support the [extension API](../../../api/extension-apiserver.md) used by Rancher. + +### Install Rancher on a Hardened Kubernetes Cluster + +If you install Rancher on a hardened Kubernetes cluster, check the [Exempting Required Rancher Namespaces](../../../how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/psa-config-templates.md#exempting-required-rancher-namespaces) section for detailed requirements. + +### Install Rancher on an IPv6-only or Dual-stack Kubernetes Cluster + +You can deploy Rancher on an IPv6-only or dual-stack Kubernetes cluster. + +For details on Rancher’s IPv6-only and dual-stack support, see the [IPv4/IPv6 Dual-stack](../../../reference-guides/dual-stack.md) page. + +## Operating Systems and Container Runtime Requirements + +All supported operating systems are 64-bit x86. Rancher should work with any modern Linux distribution. + +The [Rancher support matrix](https://www.suse.com/suse-rancher/support-matrix/all-supported-versions) lists which OS versions were tested for each Rancher version. + +The `ntp` (Network Time Protocol) package should be installed. This prevents errors with certificate validation that can occur when the time is not synchronized between the client and server. + +Some distributions of Linux may have default firewall rules that block communication within the Kubernetes cluster. Since Kubernetes v1.19, firewalld must be turned off, because it conflicts with the Kubernetes networking plugins. + +If you don't feel comfortable doing so, you might check suggestions in the [respective issue](https://github.com/rancher/rancher/issues/28840). Some users were successful [creating a separate firewalld zone with a policy of ACCEPT for the Pod CIDR](https://github.com/rancher/rancher/issues/28840#issuecomment-787404822). + +If you plan to run Rancher on ARM64, see [Running on ARM64 (Experimental).](../../../how-to-guides/advanced-user-guides/enable-experimental-features/rancher-on-arm64.md) + +### RKE2 Specific Requirements + +RKE2 bundles its own container runtime, containerd. + +For details on which OS versions were tested with RKE2, refer to the [Rancher support matrix](https://www.suse.com/suse-rancher/support-matrix/all-supported-versions). + +### K3s Specific Requirements + +For the container runtime, K3s bundles its own containerd by default. Alternatively, you can configure K3s to use an already installed Docker runtime. For more information on using K3s with Docker see the [K3s documentation.](https://docs.k3s.io/advanced#using-docker-as-the-container-runtime) + +Rancher needs to be installed on a supported Kubernetes version. To find out which versions of Kubernetes are supported for your Rancher version, refer to the [Rancher support matrix](https://www.suse.com/suse-rancher/support-matrix/all-supported-versions). To specify the K3s version, use the INSTALL_K3S_VERSION environment variable when running the K3s installation script. + +If you are installing Rancher on a K3s cluster with **Raspbian Buster**, follow [these steps](https://rancher.com/docs/k3s/latest/en/advanced/#enabling-legacy-iptables-on-raspbian-buster) to switch to legacy iptables. + +If you are installing Rancher on a K3s cluster with Alpine Linux, follow [these steps](https://rancher.com/docs/k3s/latest/en/advanced/#additional-preparation-for-alpine-linux-setup) for additional setup. + +## Hardware Requirements + +The following sections describe the CPU, memory, and I/O requirements for nodes where Rancher is installed. Requirements vary based on the size of the infrastructure. + +### Practical Considerations + +Rancher's hardware footprint depends on a number of factors, including: + + - Size of the managed infrastructure (e.g., node count, cluster count). + - Complexity of the desired access control rules (e.g., `RoleBinding` object count). + - Number of workloads (e.g., Kubernetes deployments, Fleet deployments). + - Usage patterns (e.g., subset of functionality actively used, frequency of use, number of concurrent users). + +Since there are a high number of influencing factors that may vary over time, the requirements listed here should be understood as reasonable starting points that work well for most use cases. Nevertheless, your use case may have different requirements. For inquiries about a specific scenario please [contact Rancher](https://rancher.com/contact/) for further guidance. + +In particular, requirements on this page are subject to typical use assumptions, which include: + - Under 60,000 total Kubernetes resources, per type. + - Up to 120 pods per node. + - Up to 200 CRDs in the upstream (local) cluster. + - Up to 100 CRDs in downstream clusters. + - Up to 50 Fleet deployments. + +Higher numbers are possible but requirements might be higher. If you have more than 20,000 resources of the same type, loading time of the whole list through the Rancher UI might take several seconds. + +:::note Evolution: + +Rancher's codebase evolves, use cases change, and the body of accumulated Rancher experience grows every day. + +Hardware requirement recommendations are subject to change over time, as guidelines improve in accuracy and become more concrete. + +If you find that your Rancher deployment no longer complies with the listed recommendations, [contact Rancher](https://rancher.com/contact/) for a re-evaluation. + +::: + + +### RKE2 Kubernetes + +The following table lists minimum CPU and memory requirements for each node in the [upstream cluster](../install-upgrade-on-a-kubernetes-cluster/install-upgrade-on-a-kubernetes-cluster.md). + +Please note that a highly available setup with at least three nodes is required for production. + +| Managed Infrastructure Size | Maximum Number of Clusters | Maximum Number of Nodes | vCPUs | RAM | +|-----------------------------|----------------------------|-------------------------|-------|-------| +| Small | 150 | 1500 | 4 | 16 GB | +| Medium | 300 | 3000 | 8 | 32 GB | +| Large (*) | 500 | 5000 | 16 | 64 GB | +| Larger (†) | (†) | (†) | (†) | (†) | + +(*): Large deployments require that you [follow best practices](../../../reference-guides/best-practices/rancher-server/tuning-and-best-practices-for-rancher-at-scale.md) for adequate performance. + +(†): Larger deployment sizes are generally possible with ad-hoc hardware recommendations and tuning. You can [contact Rancher](https://rancher.com/contact/) for a custom evaluation. + +Refer to RKE2 documentation for more detailed information on [RKE2 general requirements](https://docs.rke2.io/install/requirements). + +### K3s Kubernetes + +The following table lists minimum CPU and memory requirements for each node in the [upstream cluster](../install-upgrade-on-a-kubernetes-cluster/install-upgrade-on-a-kubernetes-cluster.md). + +Please note that a highly available setup with at least three nodes is required for production. + +| Managed Infrastructure Size | Maximum Number of Clusters | Maximum Number of Nodes | vCPUs | RAM | External Database Host (*) | +|-----------------------------|----------------------------|-------------------------|-------|-------|----------------------------| +| Small | 150 | 1500 | 4 | 16 GB | 2 vCPUs, 8 GB + 1000 IOPS | +| Medium | 300 | 3000 | 8 | 32 GB | 4 vCPUs, 16 GB + 2000 IOPS | +| Large (†) | 500 | 5000 | 16 | 64 GB | 8 vCPUs, 32 GB + 4000 IOPS | + +(*): External Database Host refers to hosting the K3s cluster data store on an [dedicated external host](https://docs.k3s.io/datastore). This is optional. Exact requirements depend on the external data store. + +(†): Large deployments require that you [follow best practices](../../../reference-guides/best-practices/rancher-server/tuning-and-best-practices-for-rancher-at-scale.md) for adequate performance. + +Refer to the K3s documentation for more detailed information on [general requirements](https://docs.k3s.io/installation/requirements). + +### Hosted Kubernetes + +The following table lists minimum CPU and memory requirements for each node in the [upstream cluster](../install-upgrade-on-a-kubernetes-cluster/install-upgrade-on-a-kubernetes-cluster.md). + +Please note that a highly available setup with at least three nodes is required for production. + +These requirements apply to hosted Kubernetes clusters such as Amazon Elastic Kubernetes Service (EKS), Azure Kubernetes Service (AKS), or Google Kubernetes Engine (GKE). They don't apply to Rancher SaaS solutions such as [Rancher Prime Hosted](https://www.rancher.com/products/rancher). + +| Managed Infrastructure Size | Maximum Number of Clusters | Maximum Number of Nodes | vCPUs | RAM | +|-----------------------------|----------------------------|-------------------------|-------|-------| +| Small | 150 | 1500 | 4 | 16 GB | +| Medium | 300 | 3000 | 8 | 32 GB | +| Large (*) | 500 | 5000 | 16 | 64 GB | + +(*): Large deployments require that you [follow best practices](../../../reference-guides/best-practices/rancher-server/tuning-and-best-practices-for-rancher-at-scale.md) for adequate performance. + +## Ingress + +Each node in the Kubernetes cluster that Rancher is installed on should run an Ingress. + +The Ingress should be deployed as DaemonSet to ensure your load balancer can successfully route traffic to all nodes. + +For RKE2 and K3s installations, you don't have to install the Ingress manually because it is installed by default. + +For hosted Kubernetes clusters (EKS, GKE, AKS), you will need to set up the ingress. + +- **Amazon EKS:** For details on how to install Rancher on Amazon EKS, including how to install an ingress so that the Rancher server can be accessed, refer to [this page.](../install-upgrade-on-a-kubernetes-cluster/rancher-on-amazon-eks.md) +- **AKS:** For details on how to install Rancher with Azure Kubernetes Service, including how to install an ingress so that the Rancher server can be accessed, refer to [this page.](../install-upgrade-on-a-kubernetes-cluster/rancher-on-aks.md) +- **GKE:** For details on how to install Rancher with Google Kubernetes Engine, including how to install an ingress so that the Rancher server can be accessed, refer to [this page.](../install-upgrade-on-a-kubernetes-cluster/rancher-on-gke.md) + +## Disks + +Rancher performance depends on etcd in the cluster performance. To ensure optimal speed, we recommend always using SSD disks to back your Rancher management Kubernetes cluster. On cloud providers, you will also want to use the minimum size that allows the maximum IOPS. In larger clusters, consider using dedicated storage devices for etcd data and wal directories. + +## Networking Requirements + +This section describes the networking requirements for the node(s) where the Rancher server is installed. + +:::caution + +If a server containing Rancher has the `X-Frame-Options=DENY` header, some pages in the new Rancher UI will not be able to render after upgrading from the legacy UI. This is because some legacy pages are embedded as iFrames in the new UI. + +::: + +### Node IP Addresses + +Each node used should have a static IP configured, regardless of whether you are installing Rancher on a single node or on an HA cluster. In case of DHCP, each node should have a DHCP reservation to make sure the node gets the same IP allocated. + +### Port Requirements + +To operate properly, Rancher requires a number of ports to be open on Rancher nodes and on downstream Kubernetes cluster nodes. [Port Requirements](port-requirements.md) lists all the necessary ports for Rancher and Downstream Clusters for the different cluster types. + +### Load Balancer Requirements + +If you use a load balancer, it should be be HTTP/2 compatible. + +To receive help from SUSE Support, Rancher Prime customers who use load balancers (or any other middleboxes such as firewalls), must use one that is HTTP/2 compatible. + +When HTTP/2 is not available, Rancher falls back to HTTP/1.1. However, since HTTP/2 offers improved web application performance, using HTTP/1.1 can create performance issues. diff --git a/versioned_docs/version-2.14/getting-started/installation-and-upgrade/installation-requirements/port-requirements.md b/versioned_docs/version-2.14/getting-started/installation-and-upgrade/installation-requirements/port-requirements.md new file mode 100644 index 00000000000..46ca5ec7d49 --- /dev/null +++ b/versioned_docs/version-2.14/getting-started/installation-and-upgrade/installation-requirements/port-requirements.md @@ -0,0 +1,301 @@ +--- +title: Port Requirements +description: Read about port requirements needed in order for Rancher to operate properly, both for Rancher nodes and downstream Kubernetes cluster nodes +--- + + + + + +import PortsIaasNodes from '@site/src/components/PortsIaasNodes' +import PortsCustomNodes from '@site/src/components/PortsCustomNodes' +import PortsImportedHosted from '@site/src/components/PortsImportedHosted' + +To operate properly, Rancher requires a number of ports to be open on Rancher nodes and on downstream Kubernetes cluster nodes. + +## Rancher Nodes + +The following table lists the ports that need to be open to and from nodes that are running the Rancher server. + +The port requirements differ based on the Rancher server architecture. + +Rancher can be installed on any Kubernetes cluster. For Rancher installs on a K3s or RKE2 Kubernetes cluster, refer to the tabs below. For other Kubernetes distributions, refer to the distribution's documentation for the port requirements for cluster nodes. + +:::note Notes: + +- Rancher nodes may also require additional outbound access for any external authentication provider which is configured (LDAP for example). +- Kubernetes recommends TCP 30000-32767 for node port services. +- For firewalls, traffic may need to be enabled within the cluster and pod CIDR. +- Rancher nodes may also need outbound access to an external S3 location which is used for storing cluster backups (Minio for example). + +::: + +### Ports for Rancher Server Nodes on K3s + +
+ Click to expand + +The K3s server needs port 6443 to be accessible by the nodes. + +The nodes need to be able to reach other nodes over UDP port 8472 when Flannel VXLAN is used. The node should not listen on any other port. K3s uses reverse tunneling such that the nodes make outbound connections to the server and all kubelet traffic runs through that tunnel. However, if you do not use Flannel and provide your own custom CNI, then port 8472 is not needed by K3s. + +If you wish to utilize the metrics server, you will need to open port 10250 on each node. + +:::note Important: + +The VXLAN port on nodes should not be exposed to the world as it opens up your cluster network to be accessed by anyone. Run your nodes behind a firewall/security group that disables access to port 8472. + +::: + +The following tables break down the port requirements for inbound and outbound traffic: + +
Inbound Rules for Rancher Server Nodes
+ +| Protocol | Port | Source | Description +|-----|-----|----------------|---| +| TCP | 80 | Load balancer/proxy that does external SSL termination | Rancher UI/API when external SSL termination is used | +| TCP | 443 |
  • server nodes
  • agent nodes
  • hosted/registered Kubernetes
  • any source that needs to be able to use the Rancher UI or API
| Rancher agent, Rancher UI/API, kubectl | +| TCP | 6443 | K3s server nodes | Kubernetes API +| UDP | 8472 | K3s server and agent nodes | Required only for Flannel VXLAN. +| TCP | 10250 | K3s server and agent nodes | kubelet + +
Outbound Rules for Rancher Nodes
+ +| Protocol | Port | Destination | Description | +| -------- | ---- | -------------------------------------------------------- | --------------------------------------------- | +| TCP | 22 | Any node IP from a node created using Node Driver | SSH provisioning of nodes using Node Driver | +| TCP | 443 | git.rancher.io | Rancher catalog | +| TCP | 2376 | Any node IP from a node created using Node driver | Docker daemon TLS port used by Docker Machine | +| TCP | 6443 | Hosted/Imported Kubernetes API | Kubernetes API server | + +
+ +### Ports for Rancher Server Nodes on RKE2 + +
+ Click to expand + +The RKE2 server needs port 6443 and 9345 to be accessible by other nodes in the cluster. + +All nodes need to be able to reach other nodes over UDP port 8472 when Flannel VXLAN is used. + +If you wish to utilize the metrics server, you will need to open port 10250 on each node. + +:::note Important: + +The VXLAN port on nodes should not be exposed to the world as it opens up your cluster network to be accessed by anyone. Run your nodes behind a firewall/security group that disables access to port 8472. + +::: + +
Inbound Rules for RKE2 Server Nodes
+ +| Protocol | Port | Source | Description +|-----|-----|----------------|---| +| TCP | 9345 | RKE2 server and agent nodes | Node registration. Port should be open on all server nodes to all other nodes in the cluster. +| TCP | 6443 | RKE2 agent nodes | Kubernetes API +| UDP | 8472 | RKE2 server and agent nodes | Required only for Flannel VXLAN +| TCP | 10250 | RKE2 server and agent nodes | kubelet +| TCP | 2379 | RKE2 server nodes | etcd client port +| TCP | 2380 | RKE2 server nodes | etcd peer port +| TCP | 30000-32767 | RKE2 server and agent nodes | NodePort port range. Can use TCP or UDP. +| TCP | 5473 | Calico-node pod connecting to typha pod | Required when deploying with Calico +| HTTP | 80 | Load balancer/proxy that does external SSL termination | Rancher UI/API when external SSL termination is used | +| HTTPS | 443 |
  • hosted/registered Kubernetes
  • any source that needs to be able to use the Rancher UI or API
| Rancher agent, Rancher UI/API, kubectl. Not needed if you have a load balancer doing TLS termination. | + +Typically all outbound traffic is allowed. +
+ +### Ports for Rancher Server in Docker + +
+ Click to expand + +The following tables break down the port requirements for Rancher nodes, for inbound and outbound traffic: + +
Inbound Rules for Rancher Node
+ +| Protocol | Port | Source | Description +|-----|-----|----------------|---| +| TCP | 80 | Load balancer/proxy that does external SSL termination | Rancher UI/API when external SSL termination is used +| TCP | 443 |
  • hosted/registered Kubernetes
  • any source that needs to be able to use the Rancher UI or API
| Rancher agent, Rancher UI/API, kubectl + +
Outbound Rules for Rancher Node
+ +| Protocol | Port | Source | Description | +|-----|-----|----------------|---| +| TCP | 22 | Any node IP from a node created using Node Driver | SSH provisioning of nodes using Node Driver | +| TCP | 443 | git.rancher.io | Rancher catalog | +| TCP | 2376 | Any node IP from a node created using a node driver | Docker daemon TLS port used by Docker Machine | +| TCP | 6443 | Hosted/Imported Kubernetes API | Kubernetes API server | + +
+ +## Downstream Kubernetes Cluster Nodes + +Downstream Kubernetes clusters run your apps and services. This section describes what ports need to be opened on the nodes in downstream clusters so that Rancher can communicate with them. + +The port requirements differ depending on how the downstream cluster was launched. Each of the tabs below list the ports that need to be opened for different [cluster types](../../../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/kubernetes-clusters-in-rancher-setup.md). + +The following diagram depicts the ports that are opened for each [cluster type](../../../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/kubernetes-clusters-in-rancher-setup.md). + +
Port Requirements for the Rancher Management Plane
+ +![Basic Port Requirements](/img/port-communications.svg) + +:::tip + +If security isn't a large concern and you're okay with opening a few additional ports, you can use the table in [Commonly Used Ports](#commonly-used-ports) as your port reference instead of the comprehensive tables below. + +::: + +### Ports for Harvester Clusters + +Refer to the [Harvester Integration Overview](../../../integrations-in-rancher/harvester/overview.md#port-requirements) for more information on Harvester port requirements. + + +### Ports for Rancher Launched Kubernetes Clusters using Node Pools + +
+ Click to expand + +The following table depicts the port requirements for [Rancher Launched Kubernetes](../../../how-to-guides/new-user-guides/launch-kubernetes-with-rancher/launch-kubernetes-with-rancher.md) with nodes created in an [Infrastructure Provider](../../../how-to-guides/new-user-guides/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/use-new-nodes-in-an-infra-provider.md). + +:::note + +The required ports are automatically opened by Rancher during creation of clusters in cloud providers like Amazon EC2 or DigitalOcean. + +::: + + + +
+ +### Ports for Rancher Launched Kubernetes Clusters using Custom Nodes + +
+ Click to expand + +The following table depicts the port requirements for [Rancher Launched Kubernetes](../../../how-to-guides/new-user-guides/launch-kubernetes-with-rancher/launch-kubernetes-with-rancher.md) with [Custom Nodes](../../../reference-guides/cluster-configuration/rancher-server-configuration/use-existing-nodes/use-existing-nodes.md). + + + +
+ +### Ports for Hosted Kubernetes Clusters + +
+ Click to expand + +The following table depicts the port requirements for [hosted clusters](../../../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-clusters-from-hosted-kubernetes-providers/set-up-clusters-from-hosted-kubernetes-providers.md). + + + +
+ +### Ports for Registered Clusters + +:::note + +Registered clusters were called imported clusters before Rancher v2.5. + +::: + +
+ Click to expand + +The following table depicts the port requirements for [registered clusters](../../../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/register-existing-clusters.md). + + + +
+ + +## Other Port Considerations + +### Commonly Used Ports + +These ports are typically opened on your Kubernetes nodes, regardless of what type of cluster it is. + +import CommonPortsTable from '../../../shared-files/_common-ports-table.md'; + + + +---- + +### Local Node Traffic + +Ports marked as `local traffic` (i.e., `9099 TCP`) in the above requirements are used for Kubernetes healthchecks (`livenessProbe` and`readinessProbe`). +These healthchecks are executed on the node itself. In most cloud environments, this local traffic is allowed by default. + +However, this traffic may be blocked when: + +- You have applied strict host firewall policies on the node. +- You are using nodes that have multiple interfaces (multihomed). + +In these cases, you have to explicitly allow this traffic in your host firewall, or in case of public/private cloud hosted machines (i.e. AWS or OpenStack), in your security group configuration. Keep in mind that when using a security group as source or destination in your security group, explicitly opening ports only applies to the private interface of the nodes / instances. + +### Rancher AWS EC2 Security Group + +When using the [AWS EC2 node driver](../../../how-to-guides/new-user-guides/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/create-an-amazon-ec2-cluster.md) to provision cluster nodes in Rancher, you can choose to let Rancher create a security group called `rancher-nodes`. The following rules are automatically added to this security group. + +| Type | Protocol | Port Range | Source/Destination | Rule Type | +|-----------------|:--------:|:-----------:|------------------------|:---------:| +| SSH | TCP | 22 | 0.0.0.0/0 and ::/0 | Inbound | +| HTTP | TCP | 80 | 0.0.0.0/0 and ::/0 | Inbound | +| Custom TCP Rule | TCP | 443 | 0.0.0.0/0 and ::/0 | Inbound | +| Custom TCP Rule | TCP | 2376 | 0.0.0.0/0 and ::/0 | Inbound | +| Custom TCP Rule | TCP | 6443 | 0.0.0.0/0 and ::/0 | Inbound | +| Custom TCP Rule | TCP | 179 | sg-xxx (rancher-nodes) | Inbound | +| Custom TCP Rule | TCP | 9345 | sg-xxx (rancher-nodes) | Inbound | +| Custom TCP Rule | TCP | 2379-2380 | sg-xxx (rancher-nodes) | Inbound | +| Custom TCP Rule | TCP | 10250-10252 | sg-xxx (rancher-nodes) | Inbound | +| Custom TCP Rule | TCP | 10256 | sg-xxx (rancher-nodes) | Inbound | +| Custom UDP Rule | UDP | 4789 | sg-xxx (rancher-nodes) | Inbound | +| Custom UDP Rule | UDP | 8472 | sg-xxx (rancher-nodes) | Inbound | +| Custom TCP Rule | TCP | 30000-32767 | 0.0.0.0/0 and ::/0 | Inbound | +| Custom UDP Rule | UDP | 30000-32767 | 0.0.0.0/0 and ::/0 | Inbound | +| All traffic | All | All | 0.0.0.0/0 and ::/0 | Outbound | + +### Opening SUSE Linux Ports + +SUSE Linux may have a firewall that blocks all ports by default. To open the ports needed for adding the host to a custom cluster, + + + + +1. SSH into the instance. +1. Start YaST in text mode: + ``` + sudo yast2 + ``` + +1. Navigate to **Security and Users** > **Firewall** > **Zones:public** > **Ports**. To navigate within the interface, follow these [instructions](https://doc.opensuse.org/documentation/leap/reference/html/book-reference/cha-yast-text.html#sec-yast-cli-navigate). +1. To open the required ports, enter them into the **TCP Ports** and **UDP Ports** fields. In this example, ports 9796 and 10250 are also opened for monitoring. The resulting fields should look similar to the following: + ```yaml + TCP Ports + 22, 80, 443, 2376, 2379, 2380, 6443, 9099, 9796, 10250, 10254, 30000-32767 + UDP Ports + 8472, 30000-32767 + ``` + +1. When all required ports are enter, select **Accept**. + + + + +1. SSH into the instance. +1. Edit /`etc/sysconfig/SuSEfirewall2` and open the required ports. In this example, ports 9796 and 10250 are also opened for monitoring: + ``` + FW_SERVICES_EXT_TCP="22 80 443 2376 2379 2380 6443 9099 9796 10250 10254 30000:32767" + FW_SERVICES_EXT_UDP="8472 30000:32767" + FW_ROUTE=yes + ``` +1. Restart the firewall with the new ports: + ``` + SuSEfirewall2 + ``` + + + + +**Result:** The node has the open ports required to be added to a custom cluster. diff --git a/versioned_docs/version-2.14/getting-started/installation-and-upgrade/other-installation-methods/air-gapped-helm-cli-install/air-gapped-helm-cli-install.md b/versioned_docs/version-2.14/getting-started/installation-and-upgrade/other-installation-methods/air-gapped-helm-cli-install/air-gapped-helm-cli-install.md new file mode 100644 index 00000000000..0c17691b7de --- /dev/null +++ b/versioned_docs/version-2.14/getting-started/installation-and-upgrade/other-installation-methods/air-gapped-helm-cli-install/air-gapped-helm-cli-install.md @@ -0,0 +1,34 @@ +--- +title: Air-Gapped Helm CLI Install +--- + + + + + +This section is about using the Helm CLI to install the Rancher server in an air gapped environment. An air gapped environment could be where Rancher server will be installed offline, behind a firewall, or behind a proxy. + +The installation steps differ depending on whether Rancher is installed on a K3s Kubernetes cluster or a single Docker container. + +For more information on each installation option, refer to [this page.](../../installation-and-upgrade.md) + +Throughout the installation instructions, there will be _tabs_ for each installation option. + +:::note Important: + +If you install Rancher following the Docker installation guide, there is no upgrade path to transition your Docker Installation to a Kubernetes Installation. + +::: + +## Installation Outline + +1. [Set up infrastructure and private registry](infrastructure-private-registry.md) +2. [Collect and publish images to your private registry](publish-images.md) +3. [Set up a Kubernetes cluster (Skip this step for Docker installations)](install-kubernetes.md) +4. [Install Rancher](install-rancher-ha.md) + +## Upgrades + +To upgrade Rancher with Helm CLI in an air gap environment, follow [this procedure.](../../install-upgrade-on-a-kubernetes-cluster/upgrades.md) + +### [Next: Prepare your Node(s)](infrastructure-private-registry.md) diff --git a/versioned_docs/version-2.14/getting-started/installation-and-upgrade/other-installation-methods/air-gapped-helm-cli-install/docker-install-commands.md b/versioned_docs/version-2.14/getting-started/installation-and-upgrade/other-installation-methods/air-gapped-helm-cli-install/docker-install-commands.md new file mode 100644 index 00000000000..ffd7672f57a --- /dev/null +++ b/versioned_docs/version-2.14/getting-started/installation-and-upgrade/other-installation-methods/air-gapped-helm-cli-install/docker-install-commands.md @@ -0,0 +1,144 @@ +--- +title: Docker Install Commands +--- + + + + + +The Docker installation is for Rancher users who want to test out Rancher. + +Instead of running on a Kubernetes cluster, you install the Rancher server component on a single node using a `docker run` command. Since there is only one node and a single Docker container, if the node goes down, there is no copy of the etcd data available on other nodes and you will lose all the data of your Rancher server. + +The backup application can be used to migrate the Rancher server from a Docker install to a Kubernetes install using [these steps.](../../../../how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/migrate-rancher-to-new-cluster.md) + +For security purposes, SSL (Secure Sockets Layer) is required when using Rancher. SSL secures all Rancher network communication, like when you login or interact with a cluster. + +| Environment Variable Key | Environment Variable Value | Description | +| -------------------------------- | -------------------------------- | ---- | +| `CATTLE_SYSTEM_DEFAULT_REGISTRY` | `` | Configure Rancher server to always pull from your private registry when provisioning clusters. | +| `CATTLE_SYSTEM_CATALOG` | `bundled` | Configure Rancher server to use the packaged copy of Helm system charts. The [system charts](https://github.com/rancher/system-charts) repository contains all the catalog items required for features such as monitoring, logging, alerting and global DNS. These [Helm charts](https://github.com/rancher/system-charts) are located in GitHub, but since you are in an air gapped environment, using the charts that are bundled within Rancher is much easier than setting up a Git mirror. | + +:::note Do you want to.. + +- Configure custom CA root certificate to access your services? See [Custom CA root certificate](../../resources/custom-ca-root-certificates.md). +- Record all transactions with the Rancher API? See [API Auditing](../../../../reference-guides/single-node-rancher-in-docker/advanced-options.md#api-audit-log). + +::: + +Choose from the following options: + +## Option A: Default Self-Signed Certificate + +
+ Click to expand + +If you are installing Rancher in a development or testing environment where identity verification isn't a concern, install Rancher using the self-signed certificate that it generates. This installation option omits the hassle of generating a certificate yourself. + +Log into your Linux host, and then run the installation command below. When entering the command, use the table below to replace each placeholder. + +| Placeholder | Description | +| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | +| `` | Your private registry URL and port. | +| `` | The release tag of the [Rancher version](../../installation-references/helm-chart-options.md) that you want to install. | + +Privileged access is [required.](./install-rancher-ha.md#privileged-access-for-rancher) + +``` +docker run -d --restart=unless-stopped \ + -p 80:80 -p 443:443 \ + -e CATTLE_SYSTEM_DEFAULT_REGISTRY= \ # Set a default private registry to be used in Rancher + -e CATTLE_SYSTEM_CATALOG=bundled \ # Use the packaged Rancher system charts + --privileged \ + /rancher/rancher: +``` + +
+ +## Option B: Bring Your Own Certificate: Self-Signed + +
+ Click to expand + +In development or testing environments where your team will access your Rancher server, create a self-signed certificate for use with your install so that your team can verify they're connecting to your instance of Rancher. + +:::note Prerequisites: + +From a computer with an internet connection, create a self-signed certificate using [OpenSSL](https://www.openssl.org/) or another method of your choice. + +- The certificate files must be in PEM format. +- In your certificate file, include all intermediate certificates in the chain. Order your certificates with your certificate first, followed by the intermediates. For an example, see [Certificate Troubleshooting.](../rancher-on-a-single-node-with-docker/certificate-troubleshooting.md) + +::: + +After creating your certificate, log into your Linux host, and then run the installation command below. When entering the command, use the table below to replace each placeholder. Use the `-v` flag and provide the path to your certificates to mount them in your container. + +| Placeholder | Description | +| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | +| `` | The path to the directory containing your certificate files. | +| `` | The path to your full certificate chain. | +| `` | The path to the private key for your certificate. | +| `` | The path to the certificate authority's certificate. | +| `` | Your private registry URL and port. | +| `` | The release tag of the [Rancher version](../../installation-references/helm-chart-options.md) that you want to install. | + +Privileged access is [required.](./install-rancher-ha.md#privileged-access-for-rancher) + +``` +docker run -d --restart=unless-stopped \ + -p 80:80 -p 443:443 \ + -v //:/etc/rancher/ssl/cert.pem \ + -v //:/etc/rancher/ssl/key.pem \ + -v //:/etc/rancher/ssl/cacerts.pem \ + -e CATTLE_SYSTEM_DEFAULT_REGISTRY= \ # Set a default private registry to be used in Rancher + -e CATTLE_SYSTEM_CATALOG=bundled \ # Use the packaged Rancher system charts + --privileged \ + /rancher/rancher: +``` + +
+ +## Option C: Bring Your Own Certificate: Signed by Recognized CA + +
+ Click to expand + +In development or testing environments where you're exposing an app publicly, use a certificate signed by a recognized CA so that your user base doesn't encounter security warnings. + +:::note Prerequisite: + +The certificate files must be in PEM format. + +::: + +After obtaining your certificate, log into your Linux host, and then run the installation command below. When entering the command, use the table below to replace each placeholder. Because your certificate is signed by a recognized CA, mounting an additional CA certificate file is unnecessary. + +| Placeholder | Description | +| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | +| `` | The path to the directory containing your certificate files. | +| `` | The path to your full certificate chain. | +| `` | The path to the private key for your certificate. | +| `` | Your private registry URL and port. | +| `` | The release tag of the [Rancher version](../../installation-references/helm-chart-options.md) that you want to install. | + +:::note + +Use the `--no-cacerts` as argument to the container to disable the default CA certificate generated by Rancher. + +::: + +Privileged access is [required.](./install-rancher-ha.md#privileged-access-for-rancher) + +``` +docker run -d --restart=unless-stopped \ + -p 80:80 -p 443:443 \ + --no-cacerts \ + -v //:/etc/rancher/ssl/cert.pem \ + -v //:/etc/rancher/ssl/key.pem \ + -e CATTLE_SYSTEM_DEFAULT_REGISTRY= \ # Set a default private registry to be used in Rancher + -e CATTLE_SYSTEM_CATALOG=bundled \ # Use the packaged Rancher system charts + --privileged + /rancher/rancher: +``` + +
diff --git a/versioned_docs/version-2.14/getting-started/installation-and-upgrade/other-installation-methods/air-gapped-helm-cli-install/infrastructure-private-registry.md b/versioned_docs/version-2.14/getting-started/installation-and-upgrade/other-installation-methods/air-gapped-helm-cli-install/infrastructure-private-registry.md new file mode 100644 index 00000000000..40e21d3186a --- /dev/null +++ b/versioned_docs/version-2.14/getting-started/installation-and-upgrade/other-installation-methods/air-gapped-helm-cli-install/infrastructure-private-registry.md @@ -0,0 +1,196 @@ +--- +title: '1. Set up Infrastructure and Private Registry' +--- + + + + + +In this section, you will provision the underlying infrastructure for your Rancher management server in an air gapped environment. You will also set up the private container image registry that must be available to your Rancher node(s). + +An air gapped environment is an environment where the Rancher server is installed offline or behind a firewall. + +The infrastructure depends on whether you are installing Rancher on a K3s Kubernetes cluster, an RKE Kubernetes cluster, or a single Docker container. For more information on each installation option, refer to [this page.](../../installation-and-upgrade.md) + +Rancher can be installed on any Kubernetes cluster. The RKE and K3s Kubernetes infrastructure tutorials below are still included for convenience. + + + + +We recommend setting up the following infrastructure for a high-availability installation: + +- **Two Linux nodes,** typically virtual machines, in the infrastructure provider of your choice. +- **An external database** to store the cluster data. PostgreSQL, MySQL, and etcd are supported. +- **A load balancer** to direct traffic to the two nodes. +- **A DNS record** to map a URL to the load balancer. This will become the Rancher server URL, and downstream Kubernetes clusters will need to reach it. +- **A private image registry** to distribute container images to your machines. + +## 1. Set up Linux Nodes + +These hosts will be disconnected from the internet, but require being able to connect with your private registry. + +Make sure that your nodes fulfill the general installation requirements for [OS, container runtime, hardware, and networking.](../../installation-requirements/installation-requirements.md) + +For an example of one way to set up Linux nodes, refer to this [tutorial](../../../../how-to-guides/new-user-guides/infrastructure-setup/nodes-in-amazon-ec2.md) for setting up nodes as instances in Amazon EC2. + +## 2. Set up External Datastore + +The ability to run Kubernetes using a datastore other than etcd sets K3s apart from other Kubernetes distributions. This feature provides flexibility to Kubernetes operators. The available options allow you to select a datastore that best fits your use case. + +For a high-availability K3s installation, you will need to set up one of the following external databases: + +* [PostgreSQL](https://www.postgresql.org/) (certified against versions 10.7 and 11.5) +* [MySQL](https://www.mysql.com/) (certified against version 5.7) +* [etcd](https://etcd.io/) (certified against version 3.3.15) + +When you install Kubernetes, you will pass in details for K3s to connect to the database. + +For an example of one way to set up the database, refer to this [tutorial](../../../../how-to-guides/new-user-guides/infrastructure-setup/mysql-database-in-amazon-rds.md) for setting up a MySQL database on Amazon's RDS service. + +For the complete list of options that are available for configuring a K3s cluster datastore, refer to the [K3s documentation.](https://rancher.com/docs/k3s/latest/en/installation/datastore/) + +## 3. Set up the Load Balancer + +You will also need to set up a load balancer to direct traffic to the Rancher replica on both nodes. That will prevent an outage of any single node from taking down communications to the Rancher management server. + +When Kubernetes gets set up in a later step, the K3s tool will deploy a Traefik Ingress controller. This controller will listen on ports 80 and 443 of the worker nodes, answering traffic destined for specific hostnames. + +When Rancher is installed (also in a later step), the Rancher system creates an Ingress resource. That Ingress tells the Traefik Ingress controller to listen for traffic destined for the Rancher hostname. The Traefik Ingress controller, when receiving traffic destined for the Rancher hostname, will forward that traffic to the running Rancher pods in the cluster. + +For your implementation, consider if you want or need to use a Layer-4 or Layer-7 load balancer: + +- **A layer-4 load balancer** is the simpler of the two choices, in which you are forwarding TCP traffic to your nodes. We recommend configuring your load balancer as a Layer 4 balancer, forwarding traffic to ports TCP/80 and TCP/443 to the Rancher management cluster nodes. The Ingress controller on the cluster will redirect HTTP traffic to HTTPS and terminate SSL/TLS on port TCP/443. The Ingress controller will forward traffic to port TCP/80 to the Ingress pod in the Rancher deployment. +- **A layer-7 load balancer** is a bit more complicated but can offer features that you may want. For instance, a layer-7 load balancer is capable of handling TLS termination at the load balancer, as opposed to Rancher doing TLS termination itself. This can be beneficial if you want to centralize your TLS termination in your infrastructure. Layer-7 load balancing also offers the capability for your load balancer to make decisions based on HTTP attributes such as cookies, etc. that a layer-4 load balancer is not able to concern itself with. If you decide to terminate the SSL/TLS traffic on a layer-7 load balancer, you will need to use the `--set tls=external` option when installing Rancher in a later step. For more information, refer to the [Rancher Helm chart options.](../../installation-references/helm-chart-options.md#external-tls-termination) + +For an example showing how to set up an NGINX load balancer, refer to [this page.](../../../../how-to-guides/new-user-guides/infrastructure-setup/nginx-load-balancer.md) + +For a how-to guide for setting up an Amazon ELB Network Load Balancer, refer to [this page.](../../../../how-to-guides/new-user-guides/infrastructure-setup/amazon-elb-load-balancer.md) + +:::note Important: + +Do not use this load balancer (i.e, the `local` cluster Ingress) to load balance applications other than Rancher following installation. Sharing this Ingress with other applications may result in websocket errors to Rancher following Ingress configuration reloads for other apps. We recommend dedicating the `local` cluster to Rancher and no other applications. + +::: + +## 4. Set up the DNS Record + +Once you have set up your load balancer, you will need to create a DNS record to send traffic to this load balancer. + +Depending on your environment, this may be an A record pointing to the load balancer IP, or it may be a CNAME pointing to the load balancer hostname. In either case, make sure this record is the hostname that you intend Rancher to respond on. + +You will need to specify this hostname in a later step when you install Rancher, and it is not possible to change it later. Make sure that your decision is a final one. + +For a how-to guide for setting up a DNS record to route domain traffic to an Amazon ELB load balancer, refer to the [official AWS documentation.](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/routing-to-elb-load-balancer) + +## 5. Set up a Private Image Registry + +Rancher supports air gap installs using a private registry. You must have your own private registry or other means of distributing container images to your machines. + +In a later step, when you set up your K3s Kubernetes cluster, you will create a [private registries configuration file](https://rancher.com/docs/k3s/latest/en/installation/private-registry/) with details from this registry. + +If you need to create a private registry, refer to the documentation pages for your respective runtime: + +* [Containerd](https://github.com/containerd/containerd/blob/main/docs/cri/config.md#registry-configuration). + * [Nerdctl commands and managed registry services](https://github.com/containerd/nerdctl/blob/main/docs/registry.md). +* [Docker](https://docs.docker.com/registry/deploying/). + + + + +To install the Rancher management server on a high-availability RKE cluster, we recommend setting up the following infrastructure: + +- **Three Linux nodes,** typically virtual machines, in an infrastructure provider such as Amazon's EC2, Google Compute Engine, or vSphere. +- **A load balancer** to direct front-end traffic to the three nodes. +- **A DNS record** to map a URL to the load balancer. This will become the Rancher server URL, and downstream Kubernetes clusters will need to reach it. +- **A private image registry** to distribute container images to your machines. + +These nodes must be in the same region/data center. You may place these servers in separate availability zones. + +## Why Three Nodes? + +In an RKE cluster, Rancher server data is stored on etcd. This etcd database runs on all three nodes. + +The etcd database requires an odd number of nodes so that it can always elect a leader with a majority of the etcd cluster. If the etcd database cannot elect a leader, etcd can suffer from [split brain](https://www.quora.com/What-is-split-brain-in-distributed-systems), requiring the cluster to be restored from backup. If one of the three etcd nodes fails, the two remaining nodes can elect a leader because they have the majority of the total number of etcd nodes. + +## 1. Set up Linux Nodes + +These hosts will be disconnected from the internet, but require being able to connect with your private registry. + +Make sure that your nodes fulfill the general installation requirements for [OS, container runtime, hardware, and networking.](../../installation-requirements/installation-requirements.md) + +For an example of one way to set up Linux nodes, refer to this [tutorial](../../../../how-to-guides/new-user-guides/infrastructure-setup/nodes-in-amazon-ec2.md) for setting up nodes as instances in Amazon EC2. + +## 2. Set up the Load Balancer + +You will also need to set up a load balancer to direct traffic to the Rancher replica on both nodes. That will prevent an outage of any single node from taking down communications to the Rancher management server. + +When Kubernetes gets set up in a later step, the RKE tool will deploy an NGINX Ingress controller. This controller will listen on ports 80 and 443 of the worker nodes, answering traffic destined for specific hostnames. + +When Rancher is installed (also in a later step), the Rancher system creates an Ingress resource. That Ingress tells the NGINX Ingress controller to listen for traffic destined for the Rancher hostname. The NGINX Ingress controller, when receiving traffic destined for the Rancher hostname, will forward that traffic to the running Rancher pods in the cluster. + +For your implementation, consider if you want or need to use a Layer-4 or Layer-7 load balancer: + +- **A layer-4 load balancer** is the simpler of the two choices, in which you are forwarding TCP traffic to your nodes. We recommend configuring your load balancer as a Layer 4 balancer, forwarding traffic to ports TCP/80 and TCP/443 to the Rancher management cluster nodes. The Ingress controller on the cluster will redirect HTTP traffic to HTTPS and terminate SSL/TLS on port TCP/443. The Ingress controller will forward traffic to port TCP/80 to the Ingress pod in the Rancher deployment. +- **A layer-7 load balancer** is a bit more complicated but can offer features that you may want. For instance, a layer-7 load balancer is capable of handling TLS termination at the load balancer, as opposed to Rancher doing TLS termination itself. This can be beneficial if you want to centralize your TLS termination in your infrastructure. Layer-7 load balancing also offers the capability for your load balancer to make decisions based on HTTP attributes such as cookies, etc. that a layer-4 load balancer is not able to concern itself with. If you decide to terminate the SSL/TLS traffic on a layer-7 load balancer, you will need to use the `--set tls=external` option when installing Rancher in a later step. For more information, refer to the [Rancher Helm chart options.](../../installation-references/helm-chart-options.md#external-tls-termination) + +For an example showing how to set up an NGINX load balancer, refer to [this page.](../../../../how-to-guides/new-user-guides/infrastructure-setup/nginx-load-balancer.md) + +For a how-to guide for setting up an Amazon ELB Network Load Balancer, refer to [this page.](../../../../how-to-guides/new-user-guides/infrastructure-setup/amazon-elb-load-balancer.md) + +:::caution + +Do not use this load balancer (i.e, the `local` cluster Ingress) to load balance applications other than Rancher following installation. Sharing this Ingress with other applications may result in websocket errors to Rancher following Ingress configuration reloads for other apps. We recommend dedicating the `local` cluster to Rancher and no other applications. + +::: + +## 3. Set up the DNS Record + +Once you have set up your load balancer, you will need to create a DNS record to send traffic to this load balancer. + +Depending on your environment, this may be an A record pointing to the LB IP, or it may be a CNAME pointing to the load balancer hostname. In either case, make sure this record is the hostname that you intend Rancher to respond on. + +You will need to specify this hostname in a later step when you install Rancher, and it is not possible to change it later. Make sure that your decision is a final one. + +For a how-to guide for setting up a DNS record to route domain traffic to an Amazon ELB load balancer, refer to the [official AWS documentation.](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/routing-to-elb-load-balancer) + +## 4. Set up a Private Image Registry + +Rancher supports air gap installs using a secure private registry. You must have your own private registry or other means of distributing container images to your machines. + +In a later step, when you set up your RKE Kubernetes cluster, you will create a [private registries configuration file](https://rancher.com/docs/rke/latest/en/config-options/private-registries/) with details from this registry. + +If you need to create a private registry, refer to the documentation pages for your respective runtime: + +* [Containerd](https://github.com/containerd/containerd/blob/main/docs/cri/config.md#registry-configuration). + * [Nerdctl commands and managed registry services](https://github.com/containerd/nerdctl/blob/main/docs/registry.md). +* [Docker](https://docs.docker.com/registry/deploying/). + + + + +:::note Notes: + +- The Docker installation is for Rancher users that are wanting to test out Rancher. Since there is only one node and a single Docker container, if the node goes down, you will lose all the data of your Rancher server. + +- The Rancher backup operator can be used to migrate Rancher from the single Docker container install to an installation on a high-availability Kubernetes cluster. For details, refer to the documentation on [migrating Rancher to a new cluster.](../../../../how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/migrate-rancher-to-new-cluster.md) + +::: + +## 1. Set up a Linux Node + +This host will be disconnected from the Internet, but needs to be able to connect to your private registry. + +Make sure that your node fulfills the general installation requirements for [OS, containers, hardware, and networking.](../../installation-requirements/installation-requirements.md) + +For an example of one way to set up Linux nodes, refer to this [tutorial](../../../../how-to-guides/new-user-guides/infrastructure-setup/nodes-in-amazon-ec2.md) for setting up nodes as instances in Amazon EC2. + +## 2. Set up a Private Docker Registry + +Rancher supports air gap installs using a private registry on your bastion server. You must have your own private registry or other means of distributing container images to your machines. + +If you need help with creating a private registry, please refer to the [official Docker documentation.](https://docs.docker.com/registry/). + + + + +## [Next: Collect and Publish Images to your Private Registry](publish-images.md) diff --git a/versioned_docs/version-2.14/getting-started/installation-and-upgrade/other-installation-methods/air-gapped-helm-cli-install/install-kubernetes.md b/versioned_docs/version-2.14/getting-started/installation-and-upgrade/other-installation-methods/air-gapped-helm-cli-install/install-kubernetes.md new file mode 100644 index 00000000000..1af552dc7e3 --- /dev/null +++ b/versioned_docs/version-2.14/getting-started/installation-and-upgrade/other-installation-methods/air-gapped-helm-cli-install/install-kubernetes.md @@ -0,0 +1,301 @@ +--- +title: '3. Install Kubernetes (Skip for Docker Installs)' +--- + + + + + +:::note + +Skip this section if you are installing Rancher on a single node with Docker. + +::: + +This section describes how to install a Kubernetes cluster according to our [best practices for the Rancher server environment.](../../../../reference-guides/rancher-manager-architecture/architecture-recommendations.md#environment-for-kubernetes-installations) This cluster should be dedicated to run only the Rancher server. + +Rancher can be installed on any Kubernetes cluster, including hosted Kubernetes providers. + +The steps to set up an air-gapped Kubernetes cluster on RKE2 or K3s are shown below. + + + + +In this guide, we are assuming you have created your nodes in your air gapped environment and have a secure Docker private registry on your bastion server. + +## Installation Outline + +1. [Prepare Images Directory](#1-prepare-images-directory) +2. [Create Registry YAML](#2-create-registry-yaml) +3. [Install K3s](#3-install-k3s) +4. [Save and Start Using the kubeconfig File](#4-save-and-start-using-the-kubeconfig-file) + +## 1. Prepare Images Directory + +Obtain the images tar file for your architecture from the [releases](https://github.com/k3s-io/k3s/releases) page for the version of K3s you will be running. + +Place the tar file in the `images` directory before starting K3s on each node, for example: + +```sh +sudo mkdir -p /var/lib/rancher/k3s/agent/images/ +sudo cp ./k3s-airgap-images-$ARCH.tar /var/lib/rancher/k3s/agent/images/ +``` + +## 2. Create Registry YAML + +Create the registries.yaml file at `/etc/rancher/k3s/registries.yaml`. This will tell K3s the necessary details to connect to your private registry. + +The registries.yaml file should look like this before plugging in the necessary information: + +```yaml +--- +mirrors: + customreg: + endpoint: + - "https://ip-to-server:5000" +configs: + customreg: + auth: + username: xxxxxx # this is the registry username + password: xxxxxx # this is the registry password + tls: + cert_file: + key_file: + ca_file: +``` + +Note, at this time only secure registries are supported with K3s (SSL with custom CA). + +For more information on private registries configuration file for K3s, refer to the [K3s documentation.](https://rancher.com/docs/k3s/latest/en/installation/private-registry/) + +## 3. Install K3s + +Rancher needs to be installed on a supported Kubernetes version. To find out which versions of Kubernetes are supported for your Rancher version, refer to the [Rancher Support Matrix](https://www.suse.com/suse-rancher/support-matrix/all-supported-versions/). + +To specify the K3s (Kubernetes) version, use the INSTALL_K3S_VERSION (e.g., `INSTALL_K3S_VERSION="v1.24.10+k3s1"`) environment variable when running the K3s installation script. + +Obtain the K3s binary from the [releases](https://github.com/k3s-io/k3s/releases) page, matching the same version used to get the airgap images tar. +Also obtain the K3s install script at https://get.k3s.io + +Place the binary in `/usr/local/bin` on each node. +Place the install script anywhere on each node, and name it `install.sh`. + +Install K3s on each server: + +``` +INSTALL_K3S_SKIP_DOWNLOAD=true INSTALL_K3S_VERSION= ./install.sh +``` + +Install K3s on each agent: + +``` +INSTALL_K3S_SKIP_DOWNLOAD=true INSTALL_K3S_VERSION= K3S_URL=https://:6443 K3S_TOKEN= ./install.sh +``` + +Where `` is the IP or valid DNS of the server and `` is the node-token from the server found at `/var/lib/rancher/k3s/server/node-token`. + +:::note + +K3s additionally provides a `--resolv-conf` flag for kubelets, which may help with configuring DNS in air-gapped networks. + +::: + +## 4. Save and Start Using the kubeconfig File + +When you installed K3s on each Rancher server node, a `kubeconfig` file was created on the node at `/etc/rancher/k3s/k3s.yaml`. This file contains credentials for full access to the cluster, and you should save this file in a secure location. + +To use this `kubeconfig` file, + +1. Install [kubectl,](https://kubernetes.io/docs/tasks/tools/install-kubectl/#install-kubectl) a Kubernetes command-line tool. +2. Copy the file at `/etc/rancher/k3s/k3s.yaml` and save it to the directory `~/.kube/config` on your local machine. +3. In the kubeconfig file, the `server` directive is defined as localhost. Configure the server as the DNS of your load balancer, referring to port 6443. (The Kubernetes API server will be reached at port 6443, while the Rancher server will be reached at ports 80 and 443.) Here is an example `k3s.yaml`: + +```yaml +apiVersion: v1 +clusters: +- cluster: + certificate-authority-data: [CERTIFICATE-DATA] + server: [LOAD-BALANCER-DNS]:6443 # Edit this line + name: default +contexts: +- context: + cluster: default + user: default + name: default +current-context: default +kind: Config +preferences: {} +users: +- name: default + user: + password: [PASSWORD] + username: admin +``` + +**Result:** You can now use `kubectl` to manage your K3s cluster. If you have more than one kubeconfig file, you can specify which one you want to use by passing in the path to the file when using `kubectl`: + +``` +kubectl --kubeconfig ~/.kube/config/k3s.yaml get pods --all-namespaces +``` + +For more information about the `kubeconfig` file, refer to the [K3s documentation](https://rancher.com/docs/k3s/latest/en/cluster-access/) or the [official Kubernetes documentation](https://kubernetes.io/docs/concepts/configuration/organize-cluster-access-kubeconfig/) about organizing cluster access using `kubeconfig` files. + +## Note on Upgrading + +Upgrading an air-gap environment can be accomplished in the following manner: + +1. Download the new air-gap images (tar file) from the [releases](https://github.com/k3s-io/k3s/releases) page for the version of K3s you will be upgrading to. Place the tar in the `/var/lib/rancher/k3s/agent/images/` directory on each node. Delete the old tar file. +2. Copy and replace the old K3s binary in `/usr/local/bin` on each node. Copy over the install script at https://get.k3s.io (as it is possible it has changed since the last release). Run the script again just as you had done in the past with the same environment variables. +3. Restart the K3s service (if not restarted automatically by installer). + + + + +In this guide, we are assuming you have created your nodes in your air-gapped environment and have a secure Docker private registry on your bastion server. + +## Installation Outline + +1. [Create RKE2 configuration](#1-create-rke2-configuration) +2. [Create Registry YAML](#2-create-registry-yaml) +3. [Install RKE2](#3-install-rke2) +4. [Save and Start Using the kubeconfig File](#4-save-and-start-using-the-kubeconfig-file) + +## 1. Create RKE2 configuration + +Create the config.yaml file at `/etc/rancher/rke2/config.yaml`. This will contain all the configuration options necessary to create a highly available RKE2 cluster. + +On the first server the minimum config is: + +``` +token: my-shared-secret +tls-san: + - loadbalancer-dns-domain.com +``` + +On each other server the config file should contain the same token and tell RKE2 to connect to the existing first server: + +``` +server: https://ip-of-first-server:9345 +token: my-shared-secret +tls-san: + - loadbalancer-dns-domain.com +``` + +For more information, refer to the [RKE2 documentation](https://docs.rke2.io/install/ha). + +:::note + +RKE2 additionally provides a `resolv-conf` option for kubelets, which may help with configuring DNS in air-gap networks. + +::: + +## 2. Create Registry YAML + +Create the registries.yaml file at `/etc/rancher/rke2/registries.yaml`. This will tell RKE2 the necessary details to connect to your private registry. + +The registries.yaml file should look like this before plugging in the necessary information: + +``` +--- +mirrors: + customreg: + endpoint: + - "https://ip-to-server:5000" +configs: + customreg: + auth: + username: xxxxxx # this is the registry username + password: xxxxxx # this is the registry password + tls: + cert_file: + key_file: + ca_file: +``` + +For more information on private registries configuration file for RKE2, refer to the [RKE2 documentation.](https://docs.rke2.io/install/private_registry) + +## 3. Install RKE2 + +Rancher needs to be installed on a supported Kubernetes version. To find out which versions of Kubernetes are supported for your Rancher version, refer to the [support maintenance terms.](https://rancher.com/support-maintenance-terms/) + +Download the install script, rke2, rke2-images, and sha256sum archives from the release and upload them into a directory on each server: + +``` +mkdir /tmp/rke2-artifacts && cd /tmp/rke2-artifacts/ +wget https://github.com/rancher/rke2/releases/download/v1.21.5%2Brke2r2/rke2-images.linux-amd64.tar.zst +wget https://github.com/rancher/rke2/releases/download/v1.21.5%2Brke2r2/rke2.linux-amd64.tar.gz +wget https://github.com/rancher/rke2/releases/download/v1.21.5%2Brke2r2/sha256sum-amd64.txt +curl -sfL https://get.rke2.io --output install.sh +``` + +Next, run install.sh using the directory on each server, as in the example below: + +``` +INSTALL_RKE2_ARTIFACT_PATH=/tmp/rke2-artifacts sh install.sh +``` + +Then enable and start the service on all servers: + +`` +systemctl enable rke2-server.service +systemctl start rke2-server.service +`` + +For more information, refer to the [RKE2 documentation](https://docs.rke2.io/install/airgap). + +## 4. Save and Start Using the kubeconfig File + +When you installed RKE2 on each Rancher server node, a `kubeconfig` file was created on the node at `/etc/rancher/rke2/rke2.yaml`. This file contains credentials for full access to the cluster, and you should save this file in a secure location. + +To use this `kubeconfig` file, + +1. Install [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/#install-kubectl), a Kubernetes command-line tool. +2. Copy the file at `/etc/rancher/rke2/rke2.yaml` and save it to the directory `~/.kube/config` on your local machine. +3. In the kubeconfig file, the `server` directive is defined as localhost. Configure the server as the DNS of your load balancer, referring to port 6443. (The Kubernetes API server will be reached at port 6443, while the Rancher server will be reached at ports 80 and 443.) Here is an example `rke2.yaml`: + +``` +apiVersion: v1 +clusters: +- cluster: + certificate-authority-data: [CERTIFICATE-DATA] + server: [LOAD-BALANCER-DNS]:6443 # Edit this line + name: default +contexts: +- context: + cluster: default + user: default + name: default +current-context: default +kind: Config +preferences: {} +users: +- name: default + user: + password: [PASSWORD] + username: admin +``` + +**Result:** You can now use `kubectl` to manage your RKE2 cluster. If you have more than one kubeconfig file, you can specify which one you want to use by passing in the path to the file when using `kubectl`: + +``` +kubectl --kubeconfig ~/.kube/config/rke2.yaml get pods --all-namespaces +``` + +For more information about the `kubeconfig` file, refer to the [RKE2 documentation](https://docs.rke2.io/cluster_access) or the [official Kubernetes documentation](https://kubernetes.io/docs/concepts/configuration/organize-cluster-access-kubeconfig/) about organizing cluster access using `kubeconfig` files. + +## Note on Upgrading + +Upgrading an air-gap environment can be accomplished in the following manner: + +1. Download the new air-gap artifacts and install script from the [releases](https://github.com/rancher/rke2/releases) page for the version of RKE2 you will be upgrading to. +2. Run the script again just as you had done in the past with the same environment variables. +3. Restart the RKE2 service. + + + + +## Issues or Errors? + +See the [Troubleshooting](../../install-upgrade-on-a-kubernetes-cluster/troubleshooting.md) page. + +## [Next: Install Rancher](install-rancher-ha.md) diff --git a/versioned_docs/version-2.14/getting-started/installation-and-upgrade/other-installation-methods/air-gapped-helm-cli-install/install-rancher-ha.md b/versioned_docs/version-2.14/getting-started/installation-and-upgrade/other-installation-methods/air-gapped-helm-cli-install/install-rancher-ha.md new file mode 100644 index 00000000000..dd4ca193bce --- /dev/null +++ b/versioned_docs/version-2.14/getting-started/installation-and-upgrade/other-installation-methods/air-gapped-helm-cli-install/install-rancher-ha.md @@ -0,0 +1,244 @@ +--- +title: 4. Install Rancher +--- + + + + + +This section is about how to deploy Rancher for your air gapped environment in a high-availability Kubernetes installation. An air gapped environment could be where Rancher server will be installed offline, behind a firewall, or behind a proxy. + +## Privileged Access for Rancher + +When the Rancher server is deployed in the Docker container, a local Kubernetes cluster is installed within the container for Rancher to use. Because many features of Rancher run as deployments, and privileged mode is required to run containers within containers, you will need to install Rancher with the `--privileged` option. + +## Docker Instructions + +If you want to continue the air gapped installation using Docker commands, skip the rest of this page and follow the instructions on [this page.](docker-install-commands.md) + +## Kubernetes Instructions + +Rancher recommends installing Rancher on a Kubernetes cluster. A highly available Kubernetes install is comprised of three nodes running the Rancher server components on a Kubernetes cluster. The persistence layer (etcd) is also replicated on these three nodes, providing redundancy and data duplication in case one of the nodes fails. + +### 1. Add the Helm Chart Repository + +From a system that has access to the internet, fetch the latest Helm chart and copy the resulting manifests to a system that has access to the Rancher server cluster. + +1. If you haven't already, install `helm` locally on a workstation that has internet access. Note: Refer to the [Helm version requirements](../../resources/helm-version-requirements.md) to choose a version of Helm to install Rancher. + +2. Use `helm repo add` command to add the Helm chart repository that contains charts to install Rancher. For more information about the repository choices and which is best for your use case, see [Choosing a Rancher Version](../../resources/choose-a-rancher-version.md). + - Latest: Recommended for trying out the newest features + ``` + helm repo add rancher-latest https://releases.rancher.com/server-charts/latest + ``` + - Stable: Recommended for production environments + ``` + helm repo add rancher-stable https://releases.rancher.com/server-charts/stable + ``` + - Alpha: Experimental preview of upcoming releases. + ``` + helm repo add rancher-alpha https://releases.rancher.com/server-charts/alpha + ``` + Note: Upgrades are not supported to, from, or between Alphas. + +3. Fetch the latest Rancher chart. This will pull down the chart and save it in the current directory as a `.tgz` file. + ```plain + helm fetch rancher-/rancher + ``` + + If you require a specific version of Rancher, you can fetch this with the Helm `--version` parameter like in the following example: + ```plain + helm fetch rancher-stable/rancher --version=v2.4.8 + ``` + +### 2. Choose your SSL Configuration + +Rancher Server is designed to be secure by default and requires SSL/TLS configuration. + +When Rancher is installed on an air gapped Kubernetes cluster, there are two recommended options for the source of the certificate. + +:::note + +If you want terminate SSL/TLS externally, see [TLS termination on an External Load Balancer](../../installation-references/helm-chart-options.md#external-tls-termination). + +::: + +| Configuration | Chart option | Description | Requires cert-manager | +| ------------------------------------------ | ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------- | +| Rancher Generated Self-Signed Certificates | `ingress.tls.source=rancher` | Use certificates issued by Rancher's generated CA (self signed)
This is the **default** and does not need to be added when rendering the Helm template. | yes | +| Certificates from Files | `ingress.tls.source=secret` | Use your own certificate files by creating Kubernetes Secret(s).
This option must be passed when rendering the Rancher Helm template. | no | + +### Helm Chart Options for Air Gap Installations + +When setting up the Rancher Helm template, there are several options in the Helm chart that are designed specifically for air gap installations. + +| Chart Option | Chart Value | Description | +| ----------------------- | -------------------------------- | ---- | +| `certmanager.version` | `` | Configure proper Rancher TLS issuer depending of running cert-manager version. | +| `systemDefaultRegistry` | `` | Configure Rancher server to always pull from your private registry when provisioning clusters. | +| `useBundledSystemChart` | `true` | Configure Rancher server to use the packaged copy of Helm system charts. The [system charts](https://github.com/rancher/system-charts) repository contains all the catalog items required for features such as monitoring, logging, alerting and global DNS. These [Helm charts](https://github.com/rancher/system-charts) are located in GitHub, but since you are in an air gapped environment, using the charts that are bundled within Rancher is much easier than setting up a Git mirror. | + +### 3. Fetch the Cert-Manager Chart + +Based on the choice your made in [2. Choose your SSL Configuration](#2-choose-your-ssl-configuration), complete one of the procedures below. + +#### Option A: Default Self-Signed Certificate + +By default, Rancher generates a CA and uses cert-manager to issue the certificate for access to the Rancher server interface. + +:::note + +Recent changes to cert-manager require an upgrade. If you are upgrading Rancher and using a version of cert-manager older than v0.11.0, please see our [upgrade cert-manager documentation](../../resources/upgrade-cert-manager.md). + +::: + +##### 1. Add the cert-manager Repo + +From a system connected to the internet, add the cert-manager repo to Helm: + +```plain +helm repo add jetstack https://charts.jetstack.io +helm repo update +``` + +##### 2. Fetch the cert-manager Chart + +Fetch the latest cert-manager chart available from the [Helm chart repository](https://artifacthub.io/packages/helm/cert-manager/cert-manager). + +```plain +helm fetch jetstack/cert-manager --version v1.11.0 +``` + +##### 3. Retrieve the cert-manager CRDs + +Download the required CRD file for cert-manager: + ```plain + curl -L -o cert-manager-crd.yaml https://github.com/cert-manager/cert-manager/releases/download/v1.11.0/cert-manager.crds.yaml + ``` + +### 4. Install Rancher + +Copy the fetched charts to a system that has access to the Rancher server cluster to complete installation. + +#### 1. Install cert-manager + +Install cert-manager with the same options you would use to install the chart. Remember to set the `image.repository` option to pull the image from your private registry. + +:::note + +To see options on how to customize the cert-manager install (including for cases where your cluster uses PodSecurityPolicies), see the [cert-manager docs](https://artifacthub.io/packages/helm/cert-manager/cert-manager#configuration). + +::: + +
+ Click to expand + +If you are using self-signed certificates, install cert-manager: + +1. Create the namespace for cert-manager. + + ```plain + kubectl create namespace cert-manager + ``` + +2. Create the cert-manager CustomResourceDefinitions (CRDs). + + ```plain + kubectl apply -f cert-manager-crd.yaml + ``` + +3. Install cert-manager. + + ```plain + helm install cert-manager ./cert-manager-v1.11.0.tgz \ + --namespace cert-manager \ + --set image.repository=/quay.io/jetstack/cert-manager-controller \ + --set webhook.image.repository=/quay.io/jetstack/cert-manager-webhook \ + --set cainjector.image.repository=/quay.io/jetstack/cert-manager-cainjector \ + --set startupapicheck.image.repository=/quay.io/jetstack/cert-manager-ctl + ``` + +
+ +#### 2. Install Rancher + +First, refer to [Adding TLS Secrets](../../resources/add-tls-secrets.md) to publish the certificate files so Rancher and the ingress controller can use them. + +Then, create the namespace for Rancher using kubectl: + +```plain +kubectl create namespace cattle-system +``` + +Next, install Rancher, declaring your chosen options. Use the reference table below to replace each placeholder. Rancher needs to be configured to use the private registry in order to provision any Rancher launched Kubernetes clusters or Rancher tools. + + +Placeholder | Description +------------|------------- +`` | The version number of the output tarball. +`` | The DNS name you pointed at your load balancer. +`` | The DNS name for your private registry. +`` | Cert-manager version running on k8s cluster. + +```plain + helm install rancher ./rancher-.tgz \ + --namespace cattle-system \ + --set hostname= \ + --set certmanager.version= \ + --set rancherImage=/rancher/rancher \ + --set systemDefaultRegistry= \ # Set a default private registry to be used in Rancher + --set useBundledSystemChart=true # Use the packaged Rancher system charts +``` + +**Optional**: To install a specific Rancher version, set the `rancherImageTag` value, example: `--set rancherImageTag=v2.5.8` + +#### Option B: Certificates From Files Using Kubernetes Secrets + +##### 1. Create Secrets + +Create Kubernetes secrets from your own certificates for Rancher to use. The common name for the cert will need to match the `hostname` option in the command below, or the ingress controller will fail to provision the site for Rancher. + +##### 2. Install Rancher + +Install Rancher, declaring your chosen options. Use the reference table below to replace each placeholder. Rancher needs to be configured to use the private registry in order to provision any Rancher launched Kubernetes clusters or Rancher tools. + + +| Placeholder | Description | +| -------------------------------- | ----------------------------------------------- | +| `` | The version number of the output tarball. | +| `` | The DNS name you pointed at your load balancer. | +| `` | The DNS name for your private registry. | + +```plain + helm install rancher ./rancher-.tgz \ + --namespace cattle-system \ + --set hostname= \ + --set rancherImage=/rancher/rancher \ + --set ingress.tls.source=secret \ + --set systemDefaultRegistry= \ # Set a default private registry to be used in Rancher + --set useBundledSystemChart=true # Use the packaged Rancher system charts +``` + +If you are using a Private CA signed cert, add `--set privateCA=true` following `--set ingress.tls.source=secret`: + +```plain + helm install rancher ./rancher-.tgz \ + --namespace cattle-system \ + --set hostname= \ + --set rancherImage=/rancher/rancher \ + --set ingress.tls.source=secret \ + --set privateCA=true \ + --set systemDefaultRegistry= \ # Set a default private registry to be used in Rancher + --set useBundledSystemChart=true # Use the packaged Rancher system charts +``` + +The installation is complete. + +## Additional Resources + +These resources could be helpful when installing Rancher: + +- [Importing and installing extensions in an air-gapped environment](../../../../integrations-in-rancher/rancher-extensions.md#importing-and-installing-extensions-in-an-air-gapped-environment) +- [Rancher Helm chart options](../../installation-references/helm-chart-options.md) +- [Adding TLS secrets](../../resources/add-tls-secrets.md) +- [Troubleshooting Rancher Kubernetes Installations](../../install-upgrade-on-a-kubernetes-cluster/troubleshooting.md) diff --git a/versioned_docs/version-2.14/getting-started/installation-and-upgrade/other-installation-methods/air-gapped-helm-cli-install/publish-images.md b/versioned_docs/version-2.14/getting-started/installation-and-upgrade/other-installation-methods/air-gapped-helm-cli-install/publish-images.md new file mode 100644 index 00000000000..992129fc684 --- /dev/null +++ b/versioned_docs/version-2.14/getting-started/installation-and-upgrade/other-installation-methods/air-gapped-helm-cli-install/publish-images.md @@ -0,0 +1,309 @@ +--- +title: '2. Collect and Publish Images to your Private Registry' +--- + + + + + +This section describes how to set up your private registry so that when you install Rancher, Rancher will pull all the required images from this registry. + +By default, all images used to [provision Kubernetes clusters](../../../../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/kubernetes-clusters-in-rancher-setup.md) or launch any tools in Rancher, e.g. monitoring, pipelines, alerts, are pulled from Docker Hub. In an air gapped installation of Rancher, you will need a private registry that is located somewhere accessible by your Rancher server. Then, you will load the registry with all the images. + +Populating the private registry with images is the same process for installing Rancher with Docker and for installing Rancher on a Kubernetes cluster. + +The steps in this section differ depending on whether or not you are planning to use Rancher to provision a downstream cluster with Windows nodes or not. By default, we provide the steps of how to populate your private registry assuming that Rancher will provision downstream Kubernetes clusters with only Linux nodes. But if you plan on provisioning any [downstream Kubernetes clusters using Windows nodes](../../../../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/use-windows-clusters/use-windows-clusters.md), there are separate instructions to support the images needed. + +:::note Prerequisites: + +You must have a [private registry](https://docs.docker.com/registry/deploying/#run-an-externally-accessible-registry) available to use. + +If the registry has certs, follow [this K3s documentation](https://rancher.com/docs/k3s/latest/en/installation/private-registry/) about adding a private registry. The certs and registry configuration files need to be mounted into the Rancher container. + +::: + + + + +For Rancher servers that will only provision Linux clusters, these are the steps to populate your private registry. + +1. [Find the required assets for your Rancher version](#1-find-the-required-assets-for-your-rancher-version) +2. [Collect the cert-manager image](#2-collect-the-cert-manager-image) (unless you are bringing your own certificates or terminating TLS on a load balancer) +3. [Save the images to your workstation](#3-save-the-images-to-your-workstation) +4. [Populate the private registry](#4-populate-the-private-registry) + +### Prerequisites + +These steps expect you to use a Linux workstation that has internet access, access to your private registry, and at least 20 GB of disk space. + +If you will use ARM64 hosts, the registry must support manifests. As of April 2020, Amazon Elastic Container Registry does not support manifests. + +### 1. Find the required assets for your Rancher version + +1. Go to our [releases page,](https://github.com/rancher/rancher/releases) find the Rancher v2.x.x release that you want to install, and click **Assets**. Note: Don't use releases marked `rc` or `Pre-release`, as they are not stable for production environments. + +2. From the release's **Assets** section, download the following files, which are required to install Rancher in an air gap environment: + +| Release File | Description | +| ---------------- | -------------- | +| `rancher-images.txt` | This file contains a list of images needed to install Rancher, provision clusters and user Rancher tools. | +| `rancher-save-images.sh` | This script pulls all the images in the `rancher-images.txt` from Docker Hub and saves all of the images as `rancher-images.tar.gz`. | +| `rancher-load-images.sh` | This script loads images from the `rancher-images.tar.gz` file and pushes them to your private registry. | + +### 2. Collect the cert-manager image + +:::note + +Skip this step if you are using your own certificates, or if you are terminating TLS on an external load balancer. + +::: + +In a Kubernetes Install, if you elect to use the Rancher default self-signed TLS certificates, you must add the [`cert-manager`](https://artifacthub.io/packages/helm/cert-manager/cert-manager) image to `rancher-images.txt` as well. + +1. Fetch the latest `cert-manager` Helm chart and parse the template for image details: + + :::note + + Recent changes to cert-manager require an upgrade. If you are upgrading Rancher and using a version of cert-manager older than v0.12.0, please see our [upgrade documentation](../../resources/upgrade-cert-manager.md). + + ::: + + ```plain + helm repo add jetstack https://charts.jetstack.io + helm repo update + helm fetch jetstack/cert-manager + helm template ./cert-manager-.tgz | awk '$1 ~ /image:/ {print $2}' | sed s/\"//g >> ./rancher-images.txt + ``` + +2. Sort and unique the images list to remove any overlap between the sources: + + ```plain + sort -u rancher-images.txt -o rancher-images.txt + ``` + +### 3. Save the images to your workstation + +1. Make `rancher-save-images.sh` an executable: + ``` + chmod +x rancher-save-images.sh + ``` + +1. Run `rancher-save-images.sh` with the `rancher-images.txt` image list to create a tarball of all the required images: + ```plain + ./rancher-save-images.sh --image-list ./rancher-images.txt + ``` + **Result:** Docker begins pulling the images used for an air gap install. Be patient. This process takes a few minutes. When the process completes, your current directory will output a tarball named `rancher-images.tar.gz`. Check that the output is in the directory. + +### 4. Populate the private registry + +Next, you will move the images in the `rancher-images.tar.gz` to your private registry using the scripts to load the images. + +Move the images in the `rancher-images.tar.gz` to your private registry using the scripts to load the images. + +The `rancher-images.txt` is expected to be on the workstation in the same directory that you are running the `rancher-load-images.sh` script. The `rancher-images.tar.gz` should also be in the same directory. + +1. Log into your private registry if required: + ```plain + docker login + ``` +1. Make `rancher-load-images.sh` an executable: + ``` + chmod +x rancher-load-images.sh + ``` + +1. Use `rancher-load-images.sh` to extract, tag and push `rancher-images.txt` and `rancher-images.tar.gz` to your private registry: + ```plain + ./rancher-load-images.sh --image-list ./rancher-images.txt --registry + ``` + + + + +For Rancher servers that will provision Linux and Windows clusters, there are distinctive steps to populate your private registry for the Windows images and the Linux images. Since a Windows cluster is a mix of Linux and Windows nodes, the Linux images pushed into the private registry are manifests. + +## Windows Steps + +The Windows images need to be collected and pushed from a Windows server workstation. + +1. Find the required assets for your Rancher version +2. Save the images to your Windows Server workstation +3. Prepare the Docker daemon +4. Populate the private registry + +### Prerequisites + +These steps expect you to use a Windows Server 1809 workstation that has internet access, access to your private registry, and at least 50 GB of disk space. + +The workstation must have Docker 18.02+ in order to support manifests, which are required when provisioning Windows clusters. + +Your registry must support manifests. As of April 2020, Amazon Elastic Container Registry does not support manifests. + + + +### 1. Find the required assets for your Rancher version + +1. Browse to our [releases page](https://github.com/rancher/rancher/releases) and find the Rancher v2.x.x release that you want to install. Don't download releases marked `rc` or `Pre-release`, as they are not stable for production environments. + +2. From the release's "Assets" section, download the following files: + +| Release File | Description | +|----------------------------|------------------| +| `rancher-windows-images.txt` | This file contains a list of Windows images needed to provision Windows clusters. | +| `rancher-save-images.ps1` | This script pulls all the images in the `rancher-windows-images.txt` from Docker Hub and saves all of the images as `rancher-windows-images.tar.gz`. | +| `rancher-load-images.ps1` | This script loads the images from the `rancher-windows-images.tar.gz` file and pushes them to your private registry. | + + + +### 2. Save the images to your Windows Server workstation + +1. Using `powershell`, go to the directory that has the files that were downloaded in the previous step. + +1. Run `rancher-save-images.ps1` to create a tarball of all the required images: + ```plain + ./rancher-save-images.ps1 + ``` + + **Result:** Docker begins pulling the images used for an air gap install. Be patient. This process takes a few minutes. When the process completes, your current directory will output a tarball named `rancher-windows-images.tar.gz`. Check that the output is in the directory. + + + +### 3. Prepare the Docker daemon + +Append your private registry address to the `allow-nondistributable-artifacts` config field in the Docker daemon (`C:\ProgramData\Docker\config\daemon.json`). Since the base image of Windows images are maintained by the `mcr.microsoft.com` registry, this step is required as the layers in the Microsoft registry are missing from Docker Hub and need to be pulled into the private registry. + + ```json + { + ... + "allow-nondistributable-artifacts": [ + ... + "" + ] + ... + } + ``` + + + +### 4. Populate the private registry + +Move the images in the `rancher-windows-images.tar.gz` to your private registry using the scripts to load the images. + +The `rancher-windows-images.txt` is expected to be on the workstation in the same directory that you are running the `rancher-load-images.ps1` script. The `rancher-windows-images.tar.gz` should also be in the same directory. + +1. Using `powershell`, log into your private registry if required: + ```plain + docker login + ``` + +1. Using `powershell`, use `rancher-load-images.ps1` to extract, tag and push the images from `rancher-images.tar.gz` to your private registry: + ```plain + ./rancher-load-images.ps1 --registry + ``` + +## Linux Steps + +The Linux images need to be collected and pushed from a Linux host, but _must be done after_ populating the Windows images into the private registry. These step are different from the Linux only steps as the Linux images that are pushed will actually manifests that support Windows and Linux images. + +1. Find the required assets for your Rancher version +2. Collect all the required images +3. Save the images to your Linux workstation +4. Populate the private registry + +### Prerequisites + +You must populate the private registry with the Windows images before populating the private registry with Linux images. If you have already populated the registry with Linux images, you will need to follow these instructions again as they will publish manifests that support Windows and Linux images. + +These steps expect you to use a Linux workstation that has internet access, access to your private registry, and at least 20 GB of disk space. + +The workstation must have Docker 18.02+ in order to support manifests, which are required when provisioning Windows clusters. + + + +### 1. Find the required assets for your Rancher version + +1. Browse to our [releases page](https://github.com/rancher/rancher/releases) and find the Rancher v2.x.x release that you want to install. Don't download releases marked `rc` or `Pre-release`, as they are not stable for production environments. Click **Assets**. + +2. From the release's **Assets** section, download the following files: + +| Release File | Description | +|----------------------------| -------------------------- | +| `rancher-images.txt` | This file contains a list of images needed to install Rancher, provision clusters and user Rancher tools. | +| `rancher-windows-images.txt` | This file contains a list of images needed to provision Windows clusters. | +| `rancher-save-images.sh` | This script pulls all the images in the `rancher-images.txt` from Docker Hub and saves all of the images as `rancher-images.tar.gz`. | +| `rancher-load-images.sh` | This script loads images from the `rancher-images.tar.gz` file and pushes them to your private registry. | + + + +### 2. Collect all the required images + +**For Kubernetes Installs using Rancher Generated Self-Signed Certificate:** In a Kubernetes Install, if you elect to use the Rancher default self-signed TLS certificates, you must add the [`cert-manager`](https://artifacthub.io/packages/helm/cert-manager/cert-manager) image to `rancher-images.txt` as well. You skip this step if you are using you using your own certificates. + + +1. Fetch the latest `cert-manager` Helm chart and parse the template for image details: + + :::note + + Recent changes to cert-manager require an upgrade. If you are upgrading Rancher and using a version of cert-manager older than v0.12.0, please see our [upgrade documentation](../../resources/upgrade-cert-manager.md). + + ::: + + ```plain + helm repo add jetstack https://charts.jetstack.io + helm repo update + helm fetch jetstack/cert-manager + helm template ./cert-manager-.tgz | awk '$1 ~ /image:/ {print $2}' | sed s/\"//g >> ./rancher-images.txt + ``` + +2. Sort and unique the images list to remove any overlap between the sources: + ```plain + sort -u rancher-images.txt -o rancher-images.txt + ``` + + + +### 3. Save the images to your workstation + +1. Make `rancher-save-images.sh` an executable: + ``` + chmod +x rancher-save-images.sh + ``` + +1. Run `rancher-save-images.sh` with the `rancher-images.txt` image list to create a tarball of all the required images: + ```plain + ./rancher-save-images.sh --image-list ./rancher-images.txt + ``` + +**Result:** Docker begins pulling the images used for an air gap install. Be patient. This process takes a few minutes. When the process completes, your current directory will output a tarball named `rancher-images.tar.gz`. Check that the output is in the directory. + + + +### 4. Populate the private registry + +Move the images in the `rancher-images.tar.gz` to your private registry using the `rancher-load-images.sh script` to load the images. + +The image list, `rancher-images.txt` or `rancher-windows-images.txt`, is expected to be on the workstation in the same directory that you are running the `rancher-load-images.sh` script. The `rancher-images.tar.gz` should also be in the same directory. + +1. Log into your private registry if required: + ```plain + docker login + ``` + +1. Make `rancher-load-images.sh` an executable: + ``` + chmod +x rancher-load-images.sh + ``` + +1. Use `rancher-load-images.sh` to extract, tag and push the images from `rancher-images.tar.gz` to your private registry: + +```plain +./rancher-load-images.sh --image-list ./rancher-images.txt \ + --windows-image-list ./rancher-windows-images.txt \ + --registry +``` + + + + +### [Next step for Kubernetes Installs - Launch a Kubernetes Cluster](install-kubernetes.md) + +### [Next step for Docker Installs - Install Rancher](install-rancher-ha.md) diff --git a/versioned_docs/version-2.14/getting-started/installation-and-upgrade/other-installation-methods/other-installation-methods.md b/versioned_docs/version-2.14/getting-started/installation-and-upgrade/other-installation-methods/other-installation-methods.md new file mode 100644 index 00000000000..aaca1603ad0 --- /dev/null +++ b/versioned_docs/version-2.14/getting-started/installation-and-upgrade/other-installation-methods/other-installation-methods.md @@ -0,0 +1,23 @@ +--- +title: Other Installation Methods +--- + + + + + +### Air Gapped Installations + +Follow [these steps](air-gapped-helm-cli-install/air-gapped-helm-cli-install.md) to install the Rancher server in an air gapped environment. + +An air gapped environment could be where Rancher server will be installed offline, behind a firewall, or behind a proxy. + +### Docker Installations + +The [single-node Docker installation](rancher-on-a-single-node-with-docker/rancher-on-a-single-node-with-docker.md) is for Rancher users that are wanting to test out Rancher. Instead of running on a Kubernetes cluster using Helm, you install the Rancher server component on a single node using a `docker run` command. + +The Docker installation is for development and testing environments only. + +Since there is only one node and a single Docker container, if the node goes down, there is no copy of the etcd data available on other nodes and you will lose all the data of your Rancher server. + +The Rancher backup operator can be used to migrate Rancher from the single Docker container install to an installation on a high-availability Kubernetes cluster. For details, refer to the documentation on [migrating Rancher to a new cluster.](../../../how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/migrate-rancher-to-new-cluster.md) diff --git a/versioned_docs/version-2.14/getting-started/installation-and-upgrade/other-installation-methods/rancher-behind-an-http-proxy/install-kubernetes.md b/versioned_docs/version-2.14/getting-started/installation-and-upgrade/other-installation-methods/rancher-behind-an-http-proxy/install-kubernetes.md new file mode 100644 index 00000000000..5e388aca3de --- /dev/null +++ b/versioned_docs/version-2.14/getting-started/installation-and-upgrade/other-installation-methods/rancher-behind-an-http-proxy/install-kubernetes.md @@ -0,0 +1,114 @@ +--- +title: '2. Install Kubernetes' +--- + + + + + +Once the infrastructure is ready, you can continue with setting up a Kubernetes cluster to install Rancher in. + +The steps to set up RKE2 or K3s are shown below. + +For convenience, export the IP address and port of your proxy into an environment variable and set up the `HTTP_PROXY` variables for your current shell on every node: + +:::caution + +The `NO_PROXY` environment variable is not standardized, and the accepted format of the value can differ between applications. When configuring the `NO_PROXY` variable for Rancher, the value must adhere to the format expected by Golang. + +Specifically, the value should be a comma-delimited string which only contains IP addresses, CIDR notation, domain names, or special DNS labels (e.g. `*`). For a full description of the expected value format, refer to the [**upstream Golang documentation**](https://pkg.go.dev/golang.org/x/net/http/httpproxy#Config) + +::: + +``` +export proxy_host="10.0.0.5:8888" +export HTTP_PROXY=http://${proxy_host} +export HTTPS_PROXY=http://${proxy_host} +export NO_PROXY=127.0.0.0/8,10.0.0.0/8,cattle-system.svc,172.16.0.0/12,192.168.0.0/16 +``` + + + + +First configure the HTTP proxy settings on the K3s systemd service, so that K3s's containerd can pull images through the proxy: + +``` +cat <<'EOF' | sudo tee /etc/default/k3s > /dev/null +HTTP_PROXY=http://${proxy_host} +HTTPS_PROXY=http://${proxy_host} +NO_PROXY=127.0.0.0/8,10.0.0.0/8,cattle-system.svc,172.16.0.0/12,192.168.0.0/16,.svc,.cluster.local +EOF +``` + +Rancher needs to be installed on a supported Kubernetes version. To find out which versions of Kubernetes are supported for your Rancher version, refer to the [Rancher Support Matrix](https://www.suse.com/suse-rancher/support-matrix/all-supported-versions/). + +To specify the K3s (Kubernetes) version, use the INSTALL_K3S_VERSION (e.g., `INSTALL_K3S_VERSION="v1.24.10+k3s1"`) environment variable when running the K3s installation script. + +On the first node, create a new cluster: +``` +curl -sfL https://get.k3s.io | INSTALL_K3S_VERSION= K3S_TOKEN= sh -s - server --cluster-init +``` + +And then join the other nodes: +``` +curl -sfL https://get.k3s.io | INSTALL_K3S_VERSION= K3S_TOKEN= sh -s - server --server https://:6443 +``` + +Where `` is the IP or valid DNS of the server and `` is the node-token from the server found at `/var/lib/rancher/k3s/server/node-token`. + +For more information on installing K3s see the [K3s installation docs](https://docs.k3s.io/installation). + +To have a look at your cluster run: + +``` +kubectl cluster-info +kubectl get pods --all-namespaces +``` + + + + +On every node, run the RKE2 installation script. Ensure that the RKE2 version you are installing is [supported by Rancher](https://www.suse.com/suse-rancher/support-matrix/all-supported-versions/). + +``` +curl -sfL https://get.rke2.io | INSTALL_RKE2_CHANNEL=v1.xx sh - +``` + +Then you have to configure the HTTP proxy settings on the RKE2 systemd service, so that RKE2's containerd can pull images through the proxy: + +``` +cat <<'EOF' | sudo tee /etc/default/rke2-server > /dev/null +HTTP_PROXY=http://${proxy_host} +HTTPS_PROXY=http://${proxy_host} +NO_PROXY=127.0.0.0/8,10.0.0.0/8,cattle-system.svc,172.16.0.0/12,192.168.0.0/16,.svc,.cluster.local +EOF +``` + +Next create the RKE2 configuration file on every node following the [RKE2 High Availability documentation](https://docs.rke2.io/install/ha). + +After that start and enable the `rke2-server` service: + +``` +systemctl enable rke2-server.service +systemctl start rke2-server.service +``` + +For more information on installing RKE2 see the [RKE2 documentation](https://docs.rke2.io). + +To have a look at your cluster run: + +``` +export KUBECONFIG=/etc/rancher/rke2/rke2.yaml +alias kubectl=/var/lib/rancher/rke2/bin/kubectl +kubectl cluster-info +kubectl get pods --all-namespaces +``` + + + + +### Issues or errors? + +See the [Troubleshooting](../../install-upgrade-on-a-kubernetes-cluster/troubleshooting.md) page. + +### [Next: Install Rancher](install-rancher.md) diff --git a/versioned_docs/version-2.14/getting-started/installation-and-upgrade/other-installation-methods/rancher-behind-an-http-proxy/install-rancher.md b/versioned_docs/version-2.14/getting-started/installation-and-upgrade/other-installation-methods/rancher-behind-an-http-proxy/install-rancher.md new file mode 100644 index 00000000000..8b0e910d094 --- /dev/null +++ b/versioned_docs/version-2.14/getting-started/installation-and-upgrade/other-installation-methods/rancher-behind-an-http-proxy/install-rancher.md @@ -0,0 +1,104 @@ +--- +title: 3. Install Rancher +--- + + + + + +Now that you have a running RKE2/K3s cluster, you can install Rancher in it. For security reasons all traffic to Rancher must be encrypted with TLS. For this tutorial you are going to automatically issue a self-signed certificate through [cert-manager](https://cert-manager.io/). In a real-world use-case you will likely use Let's Encrypt or provide your own certificate. + +### Install the Helm CLI + + + +Install the [Helm](https://helm.sh/docs/intro/install/) CLI on a host where you have a kubeconfig to access your Kubernetes cluster: + +``` +curl -fsSL -o get_helm.sh https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 +chmod +x get_helm.sh +sudo ./get_helm.sh +``` + +### Install cert-manager + +Add the cert-manager Helm repository: + +``` +helm repo add jetstack https://charts.jetstack.io +``` + +Create a namespace for cert-manager: + +``` +kubectl create namespace cert-manager +``` + +Install the CustomResourceDefinitions of cert-manager: + +``` +kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download//cert-manager.crds.yaml +``` + +And install it with Helm. Note that cert-manager also needs your proxy configured in case it needs to communicate with Let's Encrypt or other external certificate issuers: + +:::note + +To see options on how to customize the cert-manager install (including for cases where your cluster uses PodSecurityPolicies), see the [cert-manager docs](https://artifacthub.io/packages/helm/cert-manager/cert-manager#configuration). + +::: + +``` +helm upgrade --install cert-manager jetstack/cert-manager \ + --namespace cert-manager \ + --set http_proxy=http://${proxy_host} \ + --set https_proxy=http://${proxy_host} \ + --set no_proxy=127.0.0.0/8\\,10.0.0.0/8\\,cattle-system.svc\\,172.16.0.0/12\\,192.168.0.0/16\\,.svc\\,.cluster.local +``` + +Now you should wait until cert-manager is finished starting up: + +``` +kubectl rollout status deployment -n cert-manager cert-manager +kubectl rollout status deployment -n cert-manager cert-manager-webhook +``` + +### Install Rancher + +Next you can install Rancher itself. First, add the Helm repository: + +``` +helm repo add rancher-latest https://releases.rancher.com/server-charts/latest +``` + +Create a namespace: + +``` +kubectl create namespace cattle-system +``` + +And install Rancher with Helm. Rancher also needs a proxy configuration so that it can communicate with external application catalogs or retrieve Kubernetes version update metadata: + +``` +helm upgrade --install rancher rancher-latest/rancher \ + --namespace cattle-system \ + --set hostname=rancher.example.com \ + --set proxy=http://${proxy_host} \ + --set noProxy=127.0.0.0/8\\,10.0.0.0/8\\,cattle-system.svc\\,172.16.0.0/12\\,192.168.0.0/16\\,.svc\\,.cluster.local +``` + +After waiting for the deployment to finish: + +``` +kubectl rollout status deployment -n cattle-system rancher +``` + +You can now navigate to `https://rancher.example.com` and start using Rancher. + +### Additional Resources + +These resources could be helpful when installing Rancher: + +- [Rancher Helm chart options](../../installation-references/helm-chart-options.md) +- [Adding TLS secrets](../../resources/add-tls-secrets.md) +- [Troubleshooting Rancher Kubernetes Installations](../../install-upgrade-on-a-kubernetes-cluster/troubleshooting.md) diff --git a/versioned_docs/version-2.14/getting-started/installation-and-upgrade/other-installation-methods/rancher-behind-an-http-proxy/rancher-behind-an-http-proxy.md b/versioned_docs/version-2.14/getting-started/installation-and-upgrade/other-installation-methods/rancher-behind-an-http-proxy/rancher-behind-an-http-proxy.md new file mode 100644 index 00000000000..e705d3b4a16 --- /dev/null +++ b/versioned_docs/version-2.14/getting-started/installation-and-upgrade/other-installation-methods/rancher-behind-an-http-proxy/rancher-behind-an-http-proxy.md @@ -0,0 +1,17 @@ +--- +title: Installing Rancher behind an HTTP Proxy +--- + + + + + +In a lot of enterprise environments, servers or VMs running on premise do not have direct Internet access, but must connect to external services through a HTTP(S) proxy for security reasons. This tutorial shows step by step how to set up a highly available Rancher installation in such an environment. + +Alternatively, it is also possible to set up Rancher completely air-gapped without any Internet access. This process is described in detail in the [Rancher docs](../air-gapped-helm-cli-install/air-gapped-helm-cli-install.md). + +## Installation Outline + +1. [Set up infrastructure](set-up-infrastructure.md) +2. [Set up a Kubernetes cluster](install-kubernetes.md) +3. [Install Rancher](install-rancher.md) diff --git a/versioned_docs/version-2.14/getting-started/installation-and-upgrade/other-installation-methods/rancher-behind-an-http-proxy/set-up-infrastructure.md b/versioned_docs/version-2.14/getting-started/installation-and-upgrade/other-installation-methods/rancher-behind-an-http-proxy/set-up-infrastructure.md new file mode 100644 index 00000000000..1f88ab83204 --- /dev/null +++ b/versioned_docs/version-2.14/getting-started/installation-and-upgrade/other-installation-methods/rancher-behind-an-http-proxy/set-up-infrastructure.md @@ -0,0 +1,67 @@ +--- +title: '1. Set up Infrastructure' +--- + + + + + +In this section, you will provision the underlying infrastructure for your Rancher management server with internet access through a HTTP proxy. + +To install the Rancher management server on a high-availability RKE2/K3s cluster, we recommend setting up the following infrastructure: + +- **Three Linux nodes,** typically virtual machines, in an infrastructure provider such as Amazon's EC2, Google Compute Engine, or vSphere. +- **A load balancer** to direct front-end traffic to the three nodes. +- **A DNS record** to map a URL to the load balancer. This will become the Rancher server URL, and downstream Kubernetes clusters will need to reach it. + +These nodes must be in the same region/data center. You may place these servers in separate availability zones. + +### Why three nodes? + +In an RKE2/K3s cluster, Rancher server data is stored on etcd. This etcd database runs on all three nodes. + +The etcd database requires an odd number of nodes so that it can always elect a leader with a majority of the etcd cluster. If the etcd database cannot elect a leader, etcd can suffer from [split brain](https://www.quora.com/What-is-split-brain-in-distributed-systems), requiring the cluster to be restored from backup. If one of the three etcd nodes fails, the two remaining nodes can elect a leader because they have the majority of the total number of etcd nodes. + +### 1. Set up Linux Nodes + +These hosts will connect to the internet through an HTTP proxy. + +Make sure that your nodes fulfill the general installation requirements for [OS, container runtime, hardware, and networking.](../../installation-requirements/installation-requirements.md) + +For an example of one way to set up Linux nodes, refer to this [tutorial](../../../../how-to-guides/new-user-guides/infrastructure-setup/nodes-in-amazon-ec2.md) for setting up nodes as instances in Amazon EC2. + +### 2. Set up the Load Balancer + +You will also need to set up a load balancer to direct traffic to the Rancher replica on both nodes. That will prevent an outage of any single node from taking down communications to the Rancher management server. + +When Kubernetes gets set up in a later step, the RKE2/K3s tool will deploy an NGINX Ingress controller. This controller will listen on ports 80 and 443 of the worker nodes, answering traffic destined for specific hostnames. + +When Rancher is installed (also in a later step), the Rancher system creates an Ingress resource. That Ingress tells the NGINX Ingress controller to listen for traffic destined for the Rancher hostname. The NGINX Ingress controller, when receiving traffic destined for the Rancher hostname, will forward that traffic to the running Rancher pods in the cluster. + +For your implementation, consider if you want or need to use a Layer-4 or Layer-7 load balancer: + +- **A layer-4 load balancer** is the simpler of the two choices, in which you are forwarding TCP traffic to your nodes. We recommend configuring your load balancer as a Layer 4 balancer, forwarding traffic to ports TCP/80 and TCP/443 to the Rancher management cluster nodes. The Ingress controller on the cluster will redirect HTTP traffic to HTTPS and terminate SSL/TLS on port TCP/443. The Ingress controller will forward traffic to port TCP/80 to the Ingress pod in the Rancher deployment. +- **A layer-7 load balancer** is a bit more complicated but can offer features that you may want. For instance, a layer-7 load balancer is capable of handling TLS termination at the load balancer, as opposed to Rancher doing TLS termination itself. This can be beneficial if you want to centralize your TLS termination in your infrastructure. Layer-7 load balancing also offers the capability for your load balancer to make decisions based on HTTP attributes such as cookies, etc. that a layer-4 load balancer is not able to concern itself with. If you decide to terminate the SSL/TLS traffic on a layer-7 load balancer, you will need to use the `--set tls=external` option when installing Rancher in a later step. For more information, refer to the [Rancher Helm chart options.](../../installation-references/helm-chart-options.md#external-tls-termination) + +For an example showing how to set up an NGINX load balancer, refer to [this page.](../../../../how-to-guides/new-user-guides/infrastructure-setup/nginx-load-balancer.md) + +For a how-to guide for setting up an Amazon ELB Network Load Balancer, refer to [this page.](../../../../how-to-guides/new-user-guides/infrastructure-setup/amazon-elb-load-balancer.md) + +:::note Important: + +Do not use this load balancer (i.e, the `local` cluster Ingress) to load balance applications other than Rancher following installation. Sharing this Ingress with other applications may result in websocket errors to Rancher following Ingress configuration reloads for other apps. We recommend dedicating the `local` cluster to Rancher and no other applications. + +::: + +### 3. Set up the DNS Record + +Once you have set up your load balancer, you will need to create a DNS record to send traffic to this load balancer. + +Depending on your environment, this may be an A record pointing to the LB IP, or it may be a CNAME pointing to the load balancer hostname. In either case, make sure this record is the hostname that you intend Rancher to respond on. + +You will need to specify this hostname in a later step when you install Rancher, and it is not possible to change it later. Make sure that your decision is a final one. + +For a how-to guide for setting up a DNS record to route domain traffic to an Amazon ELB load balancer, refer to the [official AWS documentation.](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/routing-to-elb-load-balancer) + + +### [Next: Set up a Kubernetes cluster](install-kubernetes.md) diff --git a/versioned_docs/version-2.14/getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/certificate-troubleshooting.md b/versioned_docs/version-2.14/getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/certificate-troubleshooting.md new file mode 100644 index 00000000000..fe8e3c83294 --- /dev/null +++ b/versioned_docs/version-2.14/getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/certificate-troubleshooting.md @@ -0,0 +1,94 @@ +--- +title: Troubleshooting Certificates +--- + + + + + + + +## How Do I Know if My Certificates are in PEM Format? + +You can recognize the PEM format by the following traits: + +- The file begins with the following header: + ``` + -----BEGIN CERTIFICATE----- + ``` +- The header is followed by a long string of characters. +- The file ends with a footer: + -----END CERTIFICATE----- + +PEM Certificate Example: + +``` +----BEGIN CERTIFICATE----- +MIIGVDCCBDygAwIBAgIJAMiIrEm29kRLMA0GCSqGSIb3DQEBCwUAMHkxCzAJBgNV +... more lines +VWQqljhfacYPgp8KJUJENQ9h5hZ2nSCrI+W00Jcw4QcEdCI8HL5wmg== +-----END CERTIFICATE----- +``` + +PEM Certificate Key Example: + +``` +-----BEGIN RSA PRIVATE KEY----- +MIIGVDCCBDygAwIBAgIJAMiIrEm29kRLMA0GCSqGSIb3DQEBCwUAMHkxCzAJBgNV +... more lines +VWQqljhfacYPgp8KJUJENQ9h5hZ2nSCrI+W00Jcw4QcEdCI8HL5wmg== +-----END RSA PRIVATE KEY----- +``` + +If your key looks like the example below, see [Converting a Certificate Key From PKCS8 to PKCS1.](#converting-a-certificate-key-from-pkcs8-to-pkcs1) + +``` +-----BEGIN PRIVATE KEY----- +MIIGVDCCBDygAwIBAgIJAMiIrEm29kRLMA0GCSqGSIb3DQEBCwUAMHkxCzAJBgNV +... more lines +VWQqljhfacYPgp8KJUJENQ9h5hZ2nSCrI+W00Jcw4QcEdCI8HL5wmg== +-----END PRIVATE KEY----- +``` + +## Converting a Certificate Key From PKCS8 to PKCS1 + +If you are using a PKCS8 certificate key file, Rancher will log the following line: + +``` +ListenConfigController cli-config [listener] failed with : failed to read private key: asn1: structure error: tags don't match (2 vs {class:0 tag:16 length:13 isCompound:true}) +``` + +To make this work, you will need to convert the key from PKCS8 to PKCS1 using the command below: + +``` +openssl rsa -in key.pem -out convertedkey.pem +``` + +You can now use `convertedkey.pem` as certificate key file for Rancher. + +## What is the Order of Certificates if I Want to Add My Intermediate(s)? + +The order of adding certificates is as follows: + +``` +-----BEGIN CERTIFICATE----- +%YOUR_CERTIFICATE% +-----END CERTIFICATE----- +-----BEGIN CERTIFICATE----- +%YOUR_INTERMEDIATE_CERTIFICATE% +-----END CERTIFICATE----- +``` + +## How Do I Validate My Certificate Chain? + +You can validate the certificate chain by using the `openssl` binary. If the output of the command (see the command example below) ends with `Verify return code: 0 (ok)`, your certificate chain is valid. The `ca.pem` file must be the same as you added to the `rancher/rancher` container. + +When using a certificate signed by a recognized Certificate Authority, you can omit the `-CAfile` parameter. + +Command: + +``` +openssl s_client -CAfile ca.pem -connect rancher.yourdomain.com:443 +... + Verify return code: 0 (ok) +``` \ No newline at end of file diff --git a/versioned_docs/version-2.14/getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/rancher-on-a-single-node-with-docker.md b/versioned_docs/version-2.14/getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/rancher-on-a-single-node-with-docker.md new file mode 100644 index 00000000000..4ccc34749e7 --- /dev/null +++ b/versioned_docs/version-2.14/getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/rancher-on-a-single-node-with-docker.md @@ -0,0 +1,213 @@ +--- +title: Installing Rancher on a Single Node Using Docker +description: For development and testing environments only, use a Docker install. Install Docker on a single Linux host, and deploy Rancher with a single Docker container. +--- + + + + + + + +Rancher can be installed by running a single Docker container. + +In this installation scenario, you'll install Docker on a single Linux host, and then deploy Rancher on your host using a single Docker container. + +:::note Want to use an external load balancer? + +See [Docker Install with an External Load Balancer](../../../../how-to-guides/advanced-user-guides/configure-layer-7-nginx-load-balancer.md) instead. + +::: + +A Docker installation of Rancher is recommended only for development and testing purposes. The ability to migrate Rancher to a high-availability cluster depends on the Rancher version: + +The Rancher backup operator can be used to migrate Rancher from the single Docker container install to an installation on a high-availability Kubernetes cluster. For details, refer to the documentation on [migrating Rancher to a new cluster.](../../../../how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/migrate-rancher-to-new-cluster.md) + +## Privileged Access for Rancher + +When the Rancher server is deployed in the Docker container, a local Kubernetes cluster is installed within the container for Rancher to use. Because many features of Rancher run as deployments, and privileged mode is required to run containers within containers, you will need to install Rancher with the `--privileged` option. + +## Requirements for OS, Docker, Hardware, and Networking + +Make sure that your node fulfills the general [installation requirements.](../../installation-requirements/installation-requirements.md) + +## 1. Provision Linux Host + +Provision a single Linux host according to our [Requirements](../../installation-requirements/installation-requirements.md) to launch your Rancher server. + +## 2. Choose an SSL Option and Install Rancher + +For security purposes, SSL (Secure Sockets Layer) is required when using Rancher. SSL secures all Rancher network communication, like when you login or interact with a cluster. + +:::tip Do you want to.. + +- Use a proxy? See [HTTP Proxy Configuration](../../../../reference-guides/single-node-rancher-in-docker/http-proxy-configuration.md) +- Configure custom CA root certificate to access your services? See [Custom CA root certificate](../../../../reference-guides/single-node-rancher-in-docker/advanced-options.md#custom-ca-certificate/) +- Complete an Air Gap Installation? See [Air Gap: Docker Install](../air-gapped-helm-cli-install/air-gapped-helm-cli-install.md) +- Record all transactions with the Rancher API? See [API Auditing](../../../../reference-guides/single-node-rancher-in-docker/advanced-options.md#api-audit-log) + +::: + +Choose from the following options: + +- [Option A: Default Rancher-generated Self-signed Certificate](#option-a-default-rancher-generated-self-signed-certificate) +- [Option B: Bring Your Own Certificate, Self-signed](#option-b-bring-your-own-certificate-self-signed) +- [Option C: Bring Your Own Certificate, Signed by a Recognized CA](#option-c-bring-your-own-certificate-signed-by-a-recognized-ca) +- [Option D: Let's Encrypt Certificate](#option-d-lets-encrypt-certificate) +- [Option E: Localhost tunneling, no Certificate](#option-e-localhost-tunneling-no-certificate) + +### Option A: Default Rancher-generated Self-signed Certificate + +If you are installing Rancher in a development or testing environment where identity verification isn't a concern, install Rancher using the self-signed certificate that it generates. This installation option omits the hassle of generating a certificate yourself. + +Log into your host, and run the command below: + +``` +docker run -d --restart=unless-stopped \ + -p 80:80 -p 443:443 \ + --privileged \ + rancher/rancher:latest +``` + +### Option B: Bring Your Own Certificate, Self-signed +In development or testing environments where your team will access your Rancher server, create a self-signed certificate for use with your install so that your team can verify they're connecting to your instance of Rancher. + +:::note Prerequisites: + +Create a self-signed certificate using [OpenSSL](https://www.openssl.org/) or another method of your choice. + +- The certificate files must be in PEM format. +- In your certificate file, include all intermediate certificates in the chain. Order your certificates with your certificate first, followed by the intermediates. For an example, see [Certificate Troubleshooting.](certificate-troubleshooting.md) + +::: + +After creating your certificate, run the Docker command below to install Rancher. Use the `-v` flag and provide the path to your certificates to mount them in your container. + +| Placeholder | Description | +| ------------------- | --------------------- | +| `` | The path to the directory containing your certificate files. | +| `` | The path to your full certificate chain. | +| `` | The path to the private key for your certificate. | +| `` | The path to the certificate authority's certificate. | + +Log into your host, and run the command below: + +``` +docker run -d --restart=unless-stopped \ + -p 80:80 -p 443:443 \ + -v //:/etc/rancher/ssl/cert.pem \ + -v //:/etc/rancher/ssl/key.pem \ + -v //:/etc/rancher/ssl/cacerts.pem \ + --privileged \ + rancher/rancher:latest +``` + +### Option C: Bring Your Own Certificate, Signed by a Recognized CA + +In production environments where you're exposing an app publicly, you would use a certificate signed by a recognized CA so that your user base doesn't encounter security warnings. + +The Docker install is not recommended for production. These instructions are provided for testing and development purposes only. + +:::note Prerequisites: + +- The certificate files must be in PEM format. +- In your certificate file, include all intermediate certificates provided by the recognized CA. Order your certificates with your certificate first, followed by the intermediates. For an example, see [Certificate Troubleshooting.](certificate-troubleshooting.md) + +::: + +After obtaining your certificate, run the Docker command below. + +- Use the `-v` flag and provide the path to your certificates to mount them in your container. Because your certificate is signed by a recognized CA, mounting an additional CA certificate file is unnecessary. +- Use the `--no-cacerts` as argument to the container to disable the default CA certificate generated by Rancher. + +| Placeholder | Description | +| ------------------- | ----------------------------- | +| `` | The path to the directory containing your certificate files. | +| `` | The path to your full certificate chain. | +| `` | The path to the private key for your certificate. | + +Log into your host, and run the command below: + +``` +docker run -d --restart=unless-stopped \ + -p 80:80 -p 443:443 \ + -v //:/etc/rancher/ssl/cert.pem \ + -v //:/etc/rancher/ssl/key.pem \ + --privileged \ + rancher/rancher:latest \ + --no-cacerts +``` + +### Option D: Let's Encrypt Certificate + +:::caution + +Let's Encrypt provides rate limits for requesting new certificates. Therefore, limit how often you create or destroy the container. For more information, see [Let's Encrypt documentation on rate limits](https://letsencrypt.org/docs/rate-limits/). + +::: + +For production environments, you also have the option of using [Let's Encrypt](https://letsencrypt.org/) certificates. Let's Encrypt uses an http-01 challenge to verify that you have control over your domain. You can confirm that you control the domain by pointing the hostname that you want to use for Rancher access (for example, `rancher.mydomain.com`) to the IP of the machine it is running on. You can bind the hostname to the IP address by creating an A record in DNS. + +The Docker install is not recommended for production. These instructions are provided for testing and development purposes only. + +:::note Prerequisites: + +- Let's Encrypt is an Internet service. Therefore, this option cannot be used in an internal/air gapped network. +- Create a record in your DNS that binds your Linux host IP address to the hostname that you want to use for Rancher access (`rancher.mydomain.com` for example). +- Open port `TCP/80` on your Linux host. The Let's Encrypt http-01 challenge can come from any source IP address, so port `TCP/80` must be open to all IP addresses. + +::: + +After you fulfill the prerequisites, you can install Rancher using a Let's Encrypt certificate by running the following command. + +| Placeholder | Description | +| ----------------- | ------------------- | +| `` | Your domain address | + +Log into your host, and run the command below: + +``` +docker run -d --restart=unless-stopped \ + -p 80:80 -p 443:443 \ + --privileged \ + rancher/rancher:latest \ + --acme-domain +``` + +### Option E: Localhost tunneling, no Certificate + +If you are installing Rancher in a development or testing environment where you have a localhost tunneling solution running, such as [ngrok](https://ngrok.com/), avoid generating a certificate. This installation option doesn't require a certificate. + +- You will use `--no-cacerts` in the argument to disable the default CA certificate generated by Rancher. + +Log into your host, and run the command below: + +``` +docker run -d --restart=unless-stopped \ + -p 80:80 -p 443:443 \ + --privileged \ + rancher/rancher:latest \ + --no-cacerts +``` + +## Advanced Options + +When installing Rancher on a single node with Docker, there are several advanced options that can be enabled: + +- Custom CA Certificate +- API Audit Log +- TLS Settings +- Air Gap +- Persistent Data +- Running `rancher/rancher` and `rancher/rancher-agent` on the Same Node + +Refer to [this page](../../../../reference-guides/single-node-rancher-in-docker/advanced-options.md) for details. + +## Troubleshooting + +Refer to [this page](certificate-troubleshooting.md) for frequently asked questions and troubleshooting tips. + +## What's Next? + +- **Recommended:** Review Single Node [Backup](../../../../how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/back-up-docker-installed-rancher.md) and [Restore](../../../../how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/restore-docker-installed-rancher.md). Although you don't have any data you need to back up right now, we recommend creating backups after regular Rancher use. +- Create a Kubernetes cluster: [Provisioning Kubernetes Clusters](../../../../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/kubernetes-clusters-in-rancher-setup.md). diff --git a/versioned_docs/version-2.14/getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/roll-back-docker-installed-rancher.md b/versioned_docs/version-2.14/getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/roll-back-docker-installed-rancher.md new file mode 100644 index 00000000000..bc679f07a08 --- /dev/null +++ b/versioned_docs/version-2.14/getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/roll-back-docker-installed-rancher.md @@ -0,0 +1,97 @@ +--- +title: Rolling Back Rancher Installed with Docker +--- + + + + + + + +If a Rancher upgrade does not complete successfully, you'll have to roll back to your Rancher setup that you were using before [Docker Upgrade](upgrade-docker-installed-rancher.md). Rolling back restores: + +- Your previous version of Rancher. +- Your data backup created before upgrade. + +## Before You Start + +During rollback to a prior version of Rancher, you'll enter a series of commands, filling placeholders with data from your environment. These placeholders are denoted with angled brackets and all capital letters (``). Here's an example of a command with a placeholder: + +``` +docker pull rancher/rancher: +``` + +In this command, `` is the version of Rancher you were running before your unsuccessful upgrade. `v2.0.5` for example. + +Cross reference the image and reference table below to learn how to obtain this placeholder data. Write down or copy this information before starting the procedure below. + +Terminal docker ps Command, Displaying Where to Find <PRIOR_RANCHER_VERSION> and <RANCHER_CONTAINER_NAME>![Placeholder Reference](/img/placeholder-ref-2.png) + +| Placeholder | Example | Description | +| -------------------------- | -------------------------- | ------------------------------------------------------- | +| `` | `v2.0.5` | The rancher/rancher image you used before upgrade. | +| `` | `festive_mestorf` | The name of your Rancher container. | +| `` | `v2.0.5` | The version of Rancher that the backup is for. | +| `` | `9-27-18` | The date that the data container or backup was created. | +
+ +You can obtain `` and `` by logging into your Rancher Server by remote connection and entering the command to view the containers that are running: `docker ps`. You can also view containers that are stopped using a different command: `docker ps -a`. Use these commands for help anytime during while creating backups. + +## Rolling Back Rancher + +If you have issues upgrading Rancher, roll it back to its latest known healthy state by pulling the last version you used and then restoring the backup you made before upgrade. + +:::danger + +Rolling back to a previous version of Rancher destroys any changes made to Rancher following the upgrade. Unrecoverable data loss may occur. + +::: + +1. Using a remote Terminal connection, log into the node running your Rancher Server. + +1. Pull the version of Rancher that you were running before upgrade. Replace the `` with that version. + + For example, if you were running Rancher v2.0.5 before upgrade, pull v2.0.5. + + ``` + docker pull rancher/rancher: + ``` + +1. Stop the container currently running Rancher Server. Replace `` with the name of your Rancher container. + + ``` + docker stop + ``` + You can obtain the name for your Rancher container by entering `docker ps`. + +1. Move the backup tarball that you created during completion of [Docker Upgrade](upgrade-docker-installed-rancher.md) onto your Rancher Server. Change to the directory that you moved it to. Enter `dir` to confirm that it's there. + + If you followed the naming convention we suggested in [Docker Upgrade](upgrade-docker-installed-rancher.md), it will have a name similar to (`rancher-data-backup--.tar.gz`). + +1. Run the following command to replace the data in the `rancher-data` container with the data in the backup tarball, replacing the placeholder. Don't forget to close the quotes. + + ``` + docker run --volumes-from rancher-data \ + -v $PWD:/backup busybox sh -c "rm /var/lib/rancher/* -rf \ + && tar zxvf /backup/rancher-data-backup--.tar.gz" + ``` + +1. Start a new Rancher Server container with the `` tag placeholder pointing to the data container. + ``` + docker run -d --volumes-from rancher-data \ + --restart=unless-stopped \ + -p 80:80 -p 443:443 \ + --privileged \ + rancher/rancher: + ``` + Privileged access is [required.](rancher-on-a-single-node-with-docker.md#privileged-access-for-rancher) + + :::danger + + **_Do not_** stop the rollback after initiating it, even if the rollback process seems longer than expected. Stopping the rollback may result in database issues during future upgrades. + + ::: + +1. Wait a few moments and then open Rancher in a web browser. Confirm that the rollback succeeded and that your data is restored. + +**Result:** Rancher is rolled back to its version and data state before upgrade. diff --git a/versioned_docs/version-2.14/getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/upgrade-docker-installed-rancher.md b/versioned_docs/version-2.14/getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/upgrade-docker-installed-rancher.md new file mode 100644 index 00000000000..fbdc5c0356e --- /dev/null +++ b/versioned_docs/version-2.14/getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/upgrade-docker-installed-rancher.md @@ -0,0 +1,436 @@ +--- +title: Upgrading Rancher Installed with Docker +--- + + + + + + + +The following instructions will guide you through upgrading a Rancher server that was installed with Docker. + +## Prerequisites + +- **Review the [known upgrade issues](../../install-upgrade-on-a-kubernetes-cluster/upgrades.md#known-upgrade-issues)** section in the Rancher documentation for the most noteworthy issues to consider when upgrading Rancher. A more complete list of known issues for each Rancher version can be found in the release notes on [GitHub](https://github.com/rancher/rancher/releases) and on the [Rancher forums](https://forums.rancher.com/c/announcements/12). Note that upgrades to or from any chart in the [rancher-alpha repository](../../resources/choose-a-rancher-version.md#helm-chart-repositories) aren’t supported. +- **For [air gap installs only,](../air-gapped-helm-cli-install/air-gapped-helm-cli-install.md) collect and populate images for the new Rancher server version**. Follow the guide to [populate your private registry](../air-gapped-helm-cli-install/publish-images.md) with the images for the Rancher version that you want to upgrade to. + +## Placeholder Review + +During upgrade, you'll enter a series of commands, filling placeholders with data from your environment. These placeholders are denoted with angled brackets and all capital letters (``). + +Here's an **example** of a command with a placeholder: + +``` +docker stop +``` + +In this command, `` is the name of your Rancher container. + +## Get Data for Upgrade Commands + +To obtain the data to replace the placeholders, run: + +``` +docker ps +``` + +Write down or copy this information before starting the upgrade. + +Terminal docker ps Command, Displaying Where to Find <RANCHER_CONTAINER_TAG> and <RANCHER_CONTAINER_NAME> + +![Placeholder Reference](/img/placeholder-ref.png) + +| Placeholder | Example | Description | +| -------------------------- | -------------------------- | --------------------------------------------------------- | +| `` | `v2.1.3` | The rancher/rancher image you pulled for initial install. | +| `` | `festive_mestorf` | The name of your Rancher container. | +| `` | `v2.1.3` | The version of Rancher that you're creating a backup for. | +| `` | `2018-12-19` | The date that the data container or backup was created. | +
+ +You can obtain `` and `` by logging into your Rancher server by remote connection and entering the command to view the containers that are running: `docker ps`. You can also view containers that are stopped using a different command: `docker ps -a`. Use these commands for help anytime during while creating backups. + +## Upgrade + +:::danger +Rancher upgrades to version 2.12.0 and later will be blocked if any RKE1-related resources are detected, as the Rancher Kubernetes Engine (RKE/RKE1) is end of life as of **July 31, 2025**. For detailed cleanup and recovery steps, refer to the [RKE1 Resource Validation and Upgrade Requirements in Rancher v2.12](#rke1-resource-validation-and-upgrade-requirements-in-rancher-v212). +::: + +During upgrade, you create a copy of the data from your current Rancher container and a backup in case something goes wrong. Then you deploy the new version of Rancher in a new container using your existing data. +### 1. Create a copy of the data from your Rancher server container + +1. Using a remote Terminal connection, log into the node running your Rancher server. + +1. Stop the container currently running Rancher server. Replace `` with the name of your Rancher container. + + ``` + docker stop + ``` + +1. Use the command below, replacing each placeholder, to create a data container from the Rancher container that you just stopped. + + ``` + docker create --volumes-from --name rancher-data rancher/rancher: + ``` + +### 2. Create a backup tarball + +1. From the data container that you just created (rancher-data), create a backup tarball (rancher-data-backup-<RANCHER_VERSION>-<DATE>.tar.gz). + + This tarball will serve as a rollback point if something goes wrong during upgrade. Use the following command, replacing each placeholder. + ``` + docker run --volumes-from rancher-data -v "$PWD:/backup" --rm busybox tar zcvf /backup/rancher-data-backup--.tar.gz /var/lib/rancher + ``` + + **Step Result:** When you enter this command, a series of commands should run. + +1. Enter the `ls` command to confirm that the backup tarball was created. It will have a name similar to `rancher-data-backup--.tar.gz`. + + ``` + [rancher@ip-10-0-0-50 ~]$ ls + rancher-data-backup-v2.1.3-20181219.tar.gz + ``` + +1. Move your backup tarball to a safe location external from your Rancher server. + +### 3. Pull the New Docker Image + +Pull the image of the Rancher version that you want to upgrade to. + +Placeholder | Description +------------|------------- +`` | The release tag of the [Rancher version](../../installation-references/helm-chart-options.md) that you want to upgrade to. + +``` +docker pull rancher/rancher: +``` + +### 4. Start the New Rancher Server Container + +Start a new Rancher server container using the data from the `rancher-data` container. Remember to pass in all the environment variables that you had used when you started the original container. + +:::danger + +**_Do not_** stop the upgrade after initiating it, even if the upgrade process seems longer than expected. Stopping the upgrade may result in database migration errors during future upgrades. + +::: + +If you used a proxy, see [HTTP Proxy Configuration.](../../../../reference-guides/single-node-rancher-in-docker/http-proxy-configuration.md) + +If you configured a custom CA root certificate to access your services, see [Custom CA root certificate.](../../../../reference-guides/single-node-rancher-in-docker/advanced-options.md#custom-ca-certificate) + +If you are recording all transactions with the Rancher API, see [API Auditing](../../../../reference-guides/single-node-rancher-in-docker/advanced-options.md#api-audit-log) + +To see the command to use when starting the new Rancher server container, choose from the following options: + +- Docker Upgrade +- Docker Upgrade for Air Gap Installs + + + + +Select which option you had installed Rancher server + +#### Option A: Default Self-Signed Certificate + +
+ Click to expand + +If you have selected to use the Rancher generated self-signed certificate, you add the `--volumes-from rancher-data` to the command that you had started your original Rancher server container. + +Placeholder | Description +------------|------------- +`` | The release tag of the [Rancher version](../../installation-references/helm-chart-options.md) that you want to upgrade to. + +``` +docker run -d --volumes-from rancher-data \ + --restart=unless-stopped \ + -p 80:80 -p 443:443 \ + --privileged \ + rancher/rancher: +``` + +Privileged access is [required.](rancher-on-a-single-node-with-docker.md#privileged-access-for-rancher) + +
+ +#### Option B: Bring Your Own Certificate: Self-Signed + +
+Click to expand + +If you have selected to bring your own self-signed certificate, you add the `--volumes-from rancher-data` to the command that you had started your original Rancher server container and need to have access to the same certificate that you had originally installed with. + +:::note Reminder of the Cert Prerequisite: + +The certificate files must be in PEM format. In your certificate file, include all intermediate certificates in the chain. Order your certificates with your certificate first, followed by the intermediates. + +::: + +Placeholder | Description +------------|------------- + `` | The path to the directory containing your certificate files. +`` | The path to your full certificate chain. +`` | The path to the private key for your certificate. +`` | The path to the certificate authority's certificate. +`` | The release tag of the [Rancher version](../../installation-references/helm-chart-options.md) that you want to upgrade to. + +``` +docker run -d --volumes-from rancher-data \ + --restart=unless-stopped \ + -p 80:80 -p 443:443 \ + -v //:/etc/rancher/ssl/cert.pem \ + -v //:/etc/rancher/ssl/key.pem \ + -v //:/etc/rancher/ssl/cacerts.pem \ + --privileged \ + rancher/rancher: +``` + +Privileged access is [required.](rancher-on-a-single-node-with-docker.md#privileged-access-for-rancher) + +
+ +#### Option C: Bring Your Own Certificate: Signed by Recognized CA + +
+ Click to expand + +If you have selected to use a certificate signed by a recognized CA, you add the `--volumes-from rancher-data` to the command that you had started your original Rancher server container and need to have access to the same certificates that you had originally installed with. Remember to include `--no-cacerts` as an argument to the container to disable the default CA certificate generated by Rancher. + +:::note Reminder of the Cert Prerequisite: + +The certificate files must be in PEM format. In your certificate file, include all intermediate certificates provided by the recognized CA. Order your certificates with your certificate first, followed by the intermediates. For an example, see [Certificate Troubleshooting.](certificate-troubleshooting.md) + +::: + +Placeholder | Description +------------|------------- +`` | The path to the directory containing your certificate files. +`` | The path to your full certificate chain. +`` | The path to the private key for your certificate. +`` | The release tag of the [Rancher version](../../installation-references/helm-chart-options.md) that you want to upgrade to. + +``` +docker run -d --volumes-from rancher-data \ + --restart=unless-stopped \ + -p 80:80 -p 443:443 \ + -v //:/etc/rancher/ssl/cert.pem \ + -v //:/etc/rancher/ssl/key.pem \ + --privileged \ + rancher/rancher: \ + --no-cacerts +``` + +Privileged access is [required.](rancher-on-a-single-node-with-docker.md#privileged-access-for-rancher) +
+ +#### Option D: Let's Encrypt Certificate + +
+ Click to expand + +:::caution + +Let's Encrypt provides rate limits for requesting new certificates. Therefore, limit how often you create or destroy the container. For more information, see [Let's Encrypt documentation on rate limits](https://letsencrypt.org/docs/rate-limits/). + +::: + +If you have selected to use [Let's Encrypt](https://letsencrypt.org/) certificates, you add the `--volumes-from rancher-data` to the command that you had started your original Rancher server container and need to provide the domain that you had used when you originally installed Rancher. + +:::note Reminder of the Cert Prerequisites: + +- Create a record in your DNS that binds your Linux host IP address to the hostname that you want to use for Rancher access (`rancher.mydomain.com` for example). +- Open port `TCP/80` on your Linux host. The Let's Encrypt http-01 challenge can come from any source IP address, so port `TCP/80` must be open to all IP addresses. + +::: + +Placeholder | Description +------------|------------- +`` | The release tag of the [Rancher version](../../installation-references/helm-chart-options.md) that you want to upgrade to. +`` | The domain address that you had originally started with + +``` +docker run -d --volumes-from rancher-data \ + --restart=unless-stopped \ + -p 80:80 -p 443:443 \ + --privileged \ + rancher/rancher: \ + --acme-domain +``` + +Privileged access is [required.](rancher-on-a-single-node-with-docker.md#privileged-access-for-rancher) + +
+ + + + +For security purposes, SSL (Secure Sockets Layer) is required when using Rancher. SSL secures all Rancher network communication, like when you login or interact with a cluster. + +When starting the new Rancher server container, choose from the following options: + +#### Option A: Default Self-Signed Certificate + +
+ Click to expand + +If you have selected to use the Rancher generated self-signed certificate, you add the `--volumes-from rancher-data` to the command that you had started your original Rancher server container. + +Placeholder | Description +------------|------------- +`` | Your private registry URL and port. +`` | The release tag of the [Rancher version](../../installation-references/helm-chart-options.md) that you want to to upgrade to. + +``` + docker run -d --volumes-from rancher-data \ + --restart=unless-stopped \ + -p 80:80 -p 443:443 \ + -e CATTLE_SYSTEM_DEFAULT_REGISTRY= \ # Set a default private registry to be used in Rancher + -e CATTLE_SYSTEM_CATALOG=bundled \ # Use the packaged Rancher system charts + --privileged \ + /rancher/rancher: +``` + +Privileged access is [required.](rancher-on-a-single-node-with-docker.md#privileged-access-for-rancher) +
+ +#### Option B: Bring Your Own Certificate: Self-Signed + +
+ Click to expand + +If you have selected to bring your own self-signed certificate, you add the `--volumes-from rancher-data` to the command that you had started your original Rancher server container and need to have access to the same certificate that you had originally installed with. + +:::note Reminder of the Cert Prerequisite: + +The certificate files must be in PEM format. In your certificate file, include all intermediate certificates in the chain. Order your certificates with your certificate first, followed by the intermediates. For an example, see [Certificate Troubleshooting.](certificate-troubleshooting.md) + +::: + +Placeholder | Description +------------|------------- +`` | The path to the directory containing your certificate files. +`` | The path to your full certificate chain. +`` | The path to the private key for your certificate. +`` | The path to the certificate authority's certificate. +`` | Your private registry URL and port. +`` | The release tag of the [Rancher version](../../installation-references/helm-chart-options.md) that you want to upgrade to. + +``` +docker run -d --restart=unless-stopped \ + -p 80:80 -p 443:443 \ + -v //:/etc/rancher/ssl/cert.pem \ + -v //:/etc/rancher/ssl/key.pem \ + -v //:/etc/rancher/ssl/cacerts.pem \ + -e CATTLE_SYSTEM_DEFAULT_REGISTRY= \ # Set a default private registry to be used in Rancher + -e CATTLE_SYSTEM_CATALOG=bundled \ # Use the packaged Rancher system charts + --privileged \ + /rancher/rancher: +``` +Privileged access is [required.](rancher-on-a-single-node-with-docker.md#privileged-access-for-rancher) +
+ +#### Option C: Bring Your Own Certificate: Signed by Recognized CA + +
+ Click to expand + +If you have selected to use a certificate signed by a recognized CA, you add the `--volumes-from rancher-data` to the command that you had started your original Rancher server container and need to have access to the same certificates that you had originally installed with. + + :::note Reminder of the Cert Prerequisite: + + The certificate files must be in PEM format. In your certificate file, include all intermediate certificates provided by the recognized CA. Order your certificates with your certificate first, followed by the intermediates. For an example, see [Certificate Troubleshooting.](certificate-troubleshooting.md) + + ::: + +Placeholder | Description +------------|------------- +`` | The path to the directory containing your certificate files. +`` | The path to your full certificate chain. +`` | The path to the private key for your certificate. +`` | Your private registry URL and port. +`` | The release tag of the [Rancher version](../../installation-references/helm-chart-options.md) that you want to upgrade to. + +:::note + +Use the `--no-cacerts` as argument to the container to disable the default CA certificate generated by Rancher. + +::: + +``` +docker run -d --volumes-from rancher-data \ + --restart=unless-stopped \ + -p 80:80 -p 443:443 \ + --no-cacerts \ + -v //:/etc/rancher/ssl/cert.pem \ + -v //:/etc/rancher/ssl/key.pem \ + -e CATTLE_SYSTEM_DEFAULT_REGISTRY= \ # Set a default private registry to be used in Rancher + -e CATTLE_SYSTEM_CATALOG=bundled \ # Use the packaged Rancher system charts + --privileged + /rancher/rancher: +``` +privileged access is [required.](rancher-on-a-single-node-with-docker.md#privileged-access-for-rancher) +
+ + + + +**Result:** You have upgraded Rancher. Data from your upgraded server is now saved to the `rancher-data` container for use in future upgrades. + +### 5. Verify the Upgrade + +Log into Rancher. Confirm that the upgrade succeeded by checking the version displayed in the bottom-left corner of the browser window. + +:::note Having network issues in your user clusters following upgrade? + +See [Restoring Cluster Networking](https://github.com/rancher/rancher-docs/tree/main/archived_docs/en/version-2.0-2.4/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/upgrades/namespace-migration.md). + +::: + +### 6. Clean up Your Old Rancher Server Container + +Remove the previous Rancher server container. If you only stop the previous Rancher server container (and don't remove it), the container may restart after the next server reboot. + +## RKE1 Resource Validation and Upgrade Requirements in Rancher v2.12 + +Rancher v2.12.0 and later has removed support for the Rancher Kubernetes Engine (RKE/RKE1). During upgrade, Rancher validates the cluster resources and blocks the upgrade if any RKE1-related resources are detected. + +This validation affects the following resource types: + +- Clusters with `rkeConfig` (`clusters.management.cattle.io`) +- NodeTemplates (`nodetemplates.management.cattle.io`) +- ClusterTemplates (`clustertemplates.management.cattle.io`) + +This is particularly relevant for single-node Docker installations, where Rancher is not running during the upgrade. In such cases, controllers are not available to automatically clean up deprecated resources, and the upgrade process will fail early with an error listing the blocking resources. + +### 1. Pre-Upgrade (Recommended) + +Before upgrading, while Rancher is still running: + +- Run the `pre-upgrade-hook` cleanup script to delete all RKE1 clusters and templates. You can find the script in the Rancher GitHub repository: [pre-upgrade-hook.sh](https://github.com/rancher/rancher/blob/v2.12.0/chart/scripts/pre-upgrade-hook.sh). +- This allows Rancher to clean up associated resources and finalizers. + +### 2. Post-Upgrade Failure Due to Residual RKE1 Resources + +If the upgrade to Rancher v2.12.0 or later is attempted without prior cleanup of RKE1 resources: + +- The upgrade will fail and display an error listing the resource names that are preventing the upgrade. +- This occurs because Rancher includes validation to detect and block upgrades when unsupported RKE1 resources are still present. +- To proceed, [rollback](#rolling-back) to the previous Rancher version, delete the identified resources, and then retry after [manual cleanup](#manual-cleanup-after-rollback). + +:::note Helm-based Rancher +Helm-based Rancher installations are not affected by this issue, as Rancher remains available during the upgrade and can perform resource cleanup as needed. +::: + +### Manual Cleanup After Rollback + +Users should perform the following steps after rolling back to a previous Rancher version: + +- **Manually delete** the resources listed in the upgrade error message (e.g., RKE1 clusters, NodeTemplates, ClusterTemplates). +- If deletion is blocked due to **finalizers**, edit the resources and remove the `metadata.finalizers` field. +- If a **validating webhook** prevents deletion (e.g., for the `system-project`), please refer to the [Bypassing the Webhook](../../../../reference-guides/rancher-webhook.md#bypassing-the-webhook) documentation. + +## Rolling Back + +If your upgrade does not complete successfully, you can roll back Rancher server and its data back to its last healthy state. For more information, see [Docker Rollback](roll-back-docker-installed-rancher.md). diff --git a/versioned_docs/version-2.14/getting-started/installation-and-upgrade/resources/add-tls-secrets.md b/versioned_docs/version-2.14/getting-started/installation-and-upgrade/resources/add-tls-secrets.md new file mode 100644 index 00000000000..27eff062f25 --- /dev/null +++ b/versioned_docs/version-2.14/getting-started/installation-and-upgrade/resources/add-tls-secrets.md @@ -0,0 +1,65 @@ +--- +title: Adding TLS Secrets +--- + + + + + +Kubernetes will create all the objects and services for Rancher, but it will not become available until we populate the `tls-rancher-ingress` secret in the `cattle-system` namespace with the certificate and key. + +Combine the server certificate followed by any intermediate certificate(s) needed into a file named `tls.crt`. Copy your certificate key into a file named `tls.key`. + +For example, [acme.sh](https://acme.sh) provides server certificate and CA chains in `fullchain.cer` file. +This `fullchain.cer` should be renamed to `tls.crt` & certificate key file as `tls.key`. + +Use `kubectl` with the `tls` secret type to create the secrets. + +``` +kubectl -n cattle-system create secret tls tls-rancher-ingress \ + --cert=tls.crt \ + --key=tls.key +``` + +:::note + +If you want to replace the certificate, you can delete the `tls-rancher-ingress` secret using `kubectl -n cattle-system delete secret tls-rancher-ingress` and add a new one using the command shown above. If you are using a private CA signed certificate, replacing the certificate is only possible if the new certificate is signed by the same CA as the certificate currently in use. + +::: + +## Using a Private CA Signed Certificate + +If you are using a private CA, Rancher requires a copy of the private CA's root certificate or certificate chain, which the Rancher Agent uses to validate the connection to the server. + +Create a file named `cacerts.pem` that only contains the root CA certificate or certificate chain from your private CA, and use `kubectl` to create the `tls-ca` secret in the `cattle-system` namespace. + +``` +kubectl -n cattle-system create secret generic tls-ca \ + --from-file=cacerts.pem +``` + +:::note + +The configured `tls-ca` secret is retrieved when Rancher starts. On a running Rancher installation the updated CA will take effect after new Rancher pods are started. + +The certificate chain must be properly formatted, or components may fail to download resources from the Rancher server. + +::: + +## Adding Additional CA Certificates + +If you are using a node driver that makes API requests with a different CA than the one configured for Rancher, you can add additional root certificates and certificate chains. + +Create a unique file ending in `.pem` for each certificate that is required, and use kubectl to create the +`tls-additional` secret in the `cattle-system` namespace. + +```console +kubectl -n cattle-system create secret generic tls-additional \ + --from-file=cacerts1.pem=cacerts1.pem --from-file=cacerts2.pem=cacerts2.pem +``` + +Rancher mounts these CA root certificates and certificate chains into the node driver pod during provisioning. + +## Updating a Private CA Certificate + +Follow the steps on [this page](update-rancher-certificate.md) to update the SSL certificate of the ingress in a Rancher [high availability Kubernetes installation](../install-upgrade-on-a-kubernetes-cluster/install-upgrade-on-a-kubernetes-cluster.md) or to switch from the default self-signed certificate to a custom certificate. diff --git a/versioned_docs/version-2.14/getting-started/installation-and-upgrade/resources/bootstrap-password.md b/versioned_docs/version-2.14/getting-started/installation-and-upgrade/resources/bootstrap-password.md new file mode 100644 index 00000000000..c1ec2ecdcfb --- /dev/null +++ b/versioned_docs/version-2.14/getting-started/installation-and-upgrade/resources/bootstrap-password.md @@ -0,0 +1,68 @@ +--- +title: Setting up the Bootstrap Password +--- + + + + + +When you install Rancher, you can set a bootstrap password for the first admin account. + +If you choose not to set a bootstrap password, Rancher randomly generates a bootstrap password for the first admin account. + +For details on how to set the bootstrap password, see below. + +## Password Requirements + +The bootstrap password can be any length. + +When you reset the first admin account's password after first login, the new password must be at least 12 characters long. + +You can [customize the minimum password length](../../../how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/authentication-config/manage-users-and-groups.md#minimum-password-length) for user accounts, within limitations. + +Minimum password length can be any positive integer value between 2 and 256. Decimal values and leading zeroes are not allowed. + +## Specifying the Bootstrap Password + + + + +During [Rancher installation](../install-upgrade-on-a-kubernetes-cluster/install-upgrade-on-a-kubernetes-cluster.md), set `bootstrapPassword` alongside any other flags for the Rancher Helm chart. For example: + +```bash +helm install rancher rancher-/rancher \ + --set bootstrapPassword= +``` + + + + +Pass the following value to the [Docker install command](../other-installation-methods/air-gapped-helm-cli-install/docker-install-commands.md): + +```bash +-e CATTLE_BOOTSTRAP_PASSWORD= +``` + + + + +## Retrieving the Bootstrap Password + +The bootstrap password is stored in the Docker container logs. After Rancher is installed, the UI shows instructions for how to retrieve the password based on your installation method. + + + + +```bash +kubectl get secret --namespace cattle-system bootstrap-secret -o go-template='{{ .data.bootstrapPassword|base64decode}}{{ "\n" }}' +``` + + + + +```bash +docker logs container-id 2>&1 | grep "Bootstrap Password:" +``` + + + \ No newline at end of file diff --git a/versioned_docs/version-2.14/getting-started/installation-and-upgrade/resources/choose-a-rancher-version.md b/versioned_docs/version-2.14/getting-started/installation-and-upgrade/resources/choose-a-rancher-version.md new file mode 100644 index 00000000000..89a9b2ce977 --- /dev/null +++ b/versioned_docs/version-2.14/getting-started/installation-and-upgrade/resources/choose-a-rancher-version.md @@ -0,0 +1,122 @@ +--- +title: Choosing a Rancher Version +--- + + + + + +This section describes how to choose a Rancher version. + +For a high-availability installation of Rancher, which is recommended for production, the Rancher server is installed using a **Helm chart** on a Kubernetes cluster. Refer to the [Helm version requirements](helm-version-requirements.md) to choose a version of Helm to install Rancher. + +For Docker installations of Rancher, which is used for development and testing, you will install Rancher as a **Docker image**. + + + + +When installing, upgrading, or rolling back Rancher Server when it is [installed on a Kubernetes cluster](../install-upgrade-on-a-kubernetes-cluster/install-upgrade-on-a-kubernetes-cluster.md), Rancher server is installed using a Helm chart on a Kubernetes cluster. Therefore, as you prepare to install or upgrade a high availability Rancher configuration, you must add a Helm chart repository that contains the charts for installing Rancher. + +Refer to the [Helm version requirements](helm-version-requirements.md) to choose a version of Helm to install Rancher. + +### Helm Chart Repositories + +Rancher provides several different Helm chart repositories to choose from. We align our latest and stable Helm chart repositories with the Docker tags that are used for a Docker installation. Therefore, the `rancher-latest` repository will contain charts for all the Rancher versions that have been tagged as `rancher/rancher:latest`. When a Rancher version has been promoted to the `rancher/rancher:stable`, it will get added to the `rancher-stable` repository. + +| Type | Command to Add the Repo | Description of the Repo | +| -------------- | ------------ | ----------------- | +| rancher-latest | `helm repo add rancher-latest https://releases.rancher.com/server-charts/latest` | Adds a repository of Helm charts for the latest versions of Rancher. We recommend using this repo for testing out new Rancher builds. | +| rancher-stable | `helm repo add rancher-stable https://releases.rancher.com/server-charts/stable` | Adds a repository of Helm charts for older, stable versions of Rancher. We recommend using this repo for production environments. | +| rancher-alpha | `helm repo add rancher-alpha https://releases.rancher.com/server-charts/alpha` | Adds a repository of Helm charts for alpha versions of Rancher for previewing upcoming releases. These releases are discouraged in production environments. Upgrades _to_ or _from_ charts in the rancher-alpha repository to any other chart, regardless or repository, aren't supported. | + +Instructions on when to select these repos are available below in [Switching to a Different Helm Chart Repository](#switching-to-a-different-helm-chart-repository). + +:::note + +All charts in the `rancher-stable` repository will correspond with any Rancher version tagged as `stable`. + +::: + +### Helm Chart Versions + +Rancher Helm chart versions match the Rancher version (i.e `appVersion`). Once you've added the repo you can search it to show available versions with the following command: +    `helm search repo --versions` + +If you have several repos you can specify the repo name, ie. `helm search repo rancher-stable/rancher --versions`
+For more information, see https://helm.sh/docs/helm/helm_search_repo/ + +To fetch a specific version of your chosen repo, define the `--version` parameter like in the following example:
+    `helm fetch rancher-stable/rancher --version=2.4.8` + +### Switching to a Different Helm Chart Repository + +After installing Rancher, if you want to change which Helm chart repository to install Rancher from, you will need to follow these steps. + +:::note + +Because the rancher-alpha repository contains only alpha charts, switching between the rancher-alpha repository and the rancher-stable or rancher-latest repository for upgrades is not supported. + +::: + +- Latest: Recommended for trying out the newest features + ``` + helm repo add rancher-latest https://releases.rancher.com/server-charts/latest + ``` +- Stable: Recommended for production environments + ``` + helm repo add rancher-stable https://releases.rancher.com/server-charts/stable + ``` +- Alpha: Experimental preview of upcoming releases. + ``` + helm repo add rancher-alpha https://releases.rancher.com/server-charts/alpha + ``` + Note: Upgrades are not supported to, from, or between Alphas. + +1. List the current Helm chart repositories. + + ```plain + helm repo list + + NAME URL + stable https://charts.helm.sh/stable + rancher- https://releases.rancher.com/server-charts/ + ``` + +2. Remove the existing Helm Chart repository that contains your charts to install Rancher, which will either be `rancher-stable` or `rancher-latest` depending on what you had initially added. + + ```plain + helm repo remove rancher- + ``` + +3. Add the Helm chart repository that you want to start installing Rancher from. + + ```plain + helm repo add rancher- https://releases.rancher.com/server-charts/ + ``` + +4. Continue to follow the steps to [upgrade Rancher](../install-upgrade-on-a-kubernetes-cluster/upgrades.md) from the new Helm chart repository. + + + + +When performing [Docker installs](../other-installation-methods/rancher-on-a-single-node-with-docker/rancher-on-a-single-node-with-docker.md), upgrades, or rollbacks, you can use _tags_ to install a specific version of Rancher. + +### Server Tags + +Rancher Server is distributed as a Docker image, which have tags attached to them. You can specify this tag when entering the command to deploy Rancher. Remember that if you use a tag without an explicit version (like `latest` or `stable`), you must explicitly pull a new version of that image tag. Otherwise, any image cached on the host will be used. + +| Tag | Description | +| -------------------------- | ------ | +| `rancher/rancher:latest` | Our latest development release. These builds are validated through our CI automation framework. These releases are not recommended for production environments. | +| `rancher/rancher:stable` | Our newest stable release. This tag is recommended for production. | +| `rancher/rancher:` | You can install specific versions of Rancher by using the tag from a previous release. See what's available at Docker Hub. | + +:::note + +- The `master` tag or any tag with `-rc` or another suffix is meant for the Rancher testing team to validate. You should not use these tags, as these builds are not officially supported. +- Want to install an alpha review for preview? Install using one of the alpha tags listed on our [announcements page](https://forums.rancher.com/c/announcements) (e.g., `v2.2.0-alpha1`). Caveat: Alpha releases cannot be upgraded to or from any other release. + +::: + + + diff --git a/versioned_docs/version-2.14/getting-started/installation-and-upgrade/resources/custom-ca-root-certificates.md b/versioned_docs/version-2.14/getting-started/installation-and-upgrade/resources/custom-ca-root-certificates.md new file mode 100644 index 00000000000..18d811c02f1 --- /dev/null +++ b/versioned_docs/version-2.14/getting-started/installation-and-upgrade/resources/custom-ca-root-certificates.md @@ -0,0 +1,28 @@ +--- +title: About Custom CA Root Certificates +--- + + + + + +If you're using Rancher in an internal production environment where you aren't exposing apps publicly, use a certificate from a private certificate authority (CA). + +Services that Rancher needs to access are sometimes configured with a certificate from a custom/internal CA root, also known as self signed certificate. If the presented certificate from the service cannot be validated by Rancher, the following error displays: `x509: certificate signed by unknown authority`. + +To validate the certificate, the CA root certificates need to be added to Rancher. As Rancher is written in Go, we can use the environment variable `SSL_CERT_DIR` to point to the directory where the CA root certificates are located in the container. The CA root certificates directory can be mounted using the Docker volume option (`-v host-source-directory:container-destination-directory`) when starting the Rancher container. + +Examples of services that Rancher can access: + +- Catalogs +- Authentication providers +- Accessing hosting/cloud API when using Node Drivers + +## Installing with the custom CA Certificate + +For details on starting a Rancher container with your private CA certificates mounted, refer to the installation docs: + +- [Docker install Custom CA certificate options](../../../reference-guides/single-node-rancher-in-docker/advanced-options.md#custom-ca-certificate) + +- [Kubernetes install options for Additional Trusted CAs](../installation-references/helm-chart-options.md#additional-trusted-cas) + diff --git a/versioned_docs/version-2.14/getting-started/installation-and-upgrade/resources/helm-version-requirements.md b/versioned_docs/version-2.14/getting-started/installation-and-upgrade/resources/helm-version-requirements.md new file mode 100644 index 00000000000..080040c64c0 --- /dev/null +++ b/versioned_docs/version-2.14/getting-started/installation-and-upgrade/resources/helm-version-requirements.md @@ -0,0 +1,35 @@ +--- +title: Helm Version Requirements +--- + + + + + +This section contains the requirements for Helm, which is the tool used to install Rancher on a high-availability Kubernetes cluster. + +> The installation instructions have been updated for Helm 3. For migration of installs started with Helm 2, refer to the official [Helm 2 to 3 Migration Docs.](https://helm.sh/blog/migrate-from-helm-v2-to-helm-v3/) [This section](https://github.com/rancher/rancher-docs/tree/main/archived_docs/en/version-2.0-2.4/getting-started/installation-and-upgrade/advanced-options/advanced-use-cases/helm2/helm2.md) provides a copy of the older high-availability Rancher installation instructions that used Helm 2, and it is intended to be used if upgrading to Helm 3 is not feasible. + + + +## Identifying the Proper Helm v3 Version + +Select any Helm v3 version that is officially compatible with the Kubernetes version range you are using from our [Rancher Support Matrix](https://www.suse.com/suse-rancher/support-matrix/all-supported-versions). + +To apply this rule, you may need to reference two external resources: + +- **Helm Version Compatibility:** Refer to the [Helm Version Support Policy](https://helm.sh/docs/topics/version_skew/) and select the version matching the rule for your Rancher minor target. +- **Rancher's Kubernetes Support Range:** Use the [Rancher Support Matrix](https://www.suse.com/suse-rancher/support-matrix/all-supported-versions) to identify the Kubernetes versions supported by your target Rancher minor version. + +### Example + +- **Scenario:** You are targeting Rancher v2.11.4, which supports Kubernetes versions 1.30 through 1.32. +- **Application:** Our rule requires a Helm version that supports this range. You can verify this by checking the Helm version's compatibility with the highest version in the range, Kubernetes v1.32. +- **Result:** You find that both Helm v3.17 and Helm v3.18 support the Kubernetes v1.30-v1.32 range. +- Although both work, we recommend Helm v3.18 because it is the newest Helm minor version overlapping the supported Kubernetes range. + +## Additional Notes + +- Helm v3.2.x or higher is required to install or upgrade Rancher v2.5. +- Helm v2 support was removed in Rancher v2.9.x. +- When using tools that run Helm commands for you (like Terraform), you must make sure they are configured to use the correct Helm version. diff --git a/versioned_docs/version-2.14/getting-started/installation-and-upgrade/resources/local-system-charts.md b/versioned_docs/version-2.14/getting-started/installation-and-upgrade/resources/local-system-charts.md new file mode 100644 index 00000000000..4e07236b0fe --- /dev/null +++ b/versioned_docs/version-2.14/getting-started/installation-and-upgrade/resources/local-system-charts.md @@ -0,0 +1,17 @@ +--- +title: Setting up Local System Charts for Air Gapped Installations +--- + + + + + +The [Charts](https://github.com/rancher/charts) repository contains all the Helm catalog items required for features such as monitoring, logging, alerting and Istio. + +In an air gapped installation of Rancher, you will need to configure Rancher to use a local copy of the system charts. This section describes how to use local system charts using a CLI flag. + +## Using Local System Charts + +A local copy of `system-charts` has been packaged into the `rancher/rancher` container. To be able to use these features in an air gap install, you will need to run the Rancher install command with an extra environment variable, `CATTLE_SYSTEM_CATALOG=bundled`, which tells Rancher to use the local copy of the charts instead of attempting to fetch them from GitHub. + +Example commands for a Rancher installation with a bundled `system-charts` are included in the [air gap installation](../other-installation-methods/air-gapped-helm-cli-install/air-gapped-helm-cli-install.md) instructions for Docker and Helm installs. diff --git a/versioned_docs/version-2.14/getting-started/installation-and-upgrade/resources/resources.md b/versioned_docs/version-2.14/getting-started/installation-and-upgrade/resources/resources.md new file mode 100644 index 00000000000..b5c215c5755 --- /dev/null +++ b/versioned_docs/version-2.14/getting-started/installation-and-upgrade/resources/resources.md @@ -0,0 +1,29 @@ +--- +title: Resources +--- + + + + + +### Docker Installations + +The [single-node Docker installation](../other-installation-methods/rancher-on-a-single-node-with-docker/rancher-on-a-single-node-with-docker.md) is for Rancher users that are wanting to test out Rancher. Instead of running on a Kubernetes cluster using Helm, you install the Rancher server component on a single node using a `docker run` command. + +Since there is only one node and a single Docker container, if the node goes down, there is no copy of the etcd data available on other nodes and you will lose all the data of your Rancher server. + +### Air-Gapped Installations + +Follow [these steps](../other-installation-methods/air-gapped-helm-cli-install/air-gapped-helm-cli-install.md) to install the Rancher server in an air gapped environment. + +An air gapped environment could be where Rancher server will be installed offline, behind a firewall, or behind a proxy. + +### Advanced Options + +When installing Rancher, there are several advanced options that can be enabled during installation. Within each install guide, these options are presented. Learn more about these options: + +- [Custom CA Certificate](custom-ca-root-certificates.md) +- [API Audit Log](../../../how-to-guides/advanced-user-guides/enable-api-audit-log.md) +- [TLS Settings](../installation-references/tls-settings.md) +- [etcd configuration](../../../how-to-guides/advanced-user-guides/tune-etcd-for-large-installs.md) +- [Local System Charts for Air Gap Installations](local-system-charts.md) | v2.3.0 | diff --git a/versioned_docs/version-2.14/getting-started/installation-and-upgrade/resources/update-rancher-certificate.md b/versioned_docs/version-2.14/getting-started/installation-and-upgrade/resources/update-rancher-certificate.md new file mode 100644 index 00000000000..d5eb9bfd716 --- /dev/null +++ b/versioned_docs/version-2.14/getting-started/installation-and-upgrade/resources/update-rancher-certificate.md @@ -0,0 +1,267 @@ +--- +title: Updating the Rancher Certificate +--- + + + + + +## Updating a Private CA Certificate + +Follow these steps to rotate an SSL certificate and private CA used by Rancher [installed on a Kubernetes cluster](../install-upgrade-on-a-kubernetes-cluster/install-upgrade-on-a-kubernetes-cluster.md), or migrate to an SSL certificate signed by a private CA. + +A summary of the steps is as follows: + +1. Create or update the `tls-rancher-ingress` Kubernetes secret object with the new certificate and private key. +1. Create or update the `tls-ca` Kubernetes secret object with the root CA certificate (only required when using a private CA). +1. Update the Rancher installation using the Helm CLI. +1. Reconfigure the Rancher agents to trust the new CA certificate. +1. Select Force Update of Fleet clusters to connect fleet-agent to Rancher. + +The details of these instructions are below. + +### 1. Create/update the certificate secret object + +First, concatenate the server certificate followed by any intermediate certificate(s) to a file named `tls.crt` and provide the corresponding certificate key in a file named `tls.key`. + +Use the following command to create the `tls-rancher-ingress` secret object in the Rancher (local) management cluster: + +```bash +kubectl -n cattle-system create secret tls tls-rancher-ingress \ + --cert=tls.crt \ + --key=tls.key +``` + +Alternatively, to update an existing `tls-rancher-ingress` secret: + +```bash +kubectl -n cattle-system create secret tls tls-rancher-ingress \ + --cert=tls.crt \ + --key=tls.key \ + --dry-run --save-config -o yaml | kubectl apply -f - +``` + +### 2. Create/update the CA certificate secret object + +If the new certificate was signed by a private CA, you will need to copy the corresponding root CA certificate into a file named `cacerts.pem` and create or update the `tls-ca` secret in the `cattle-system` namespace. If the certificate was signed by an intermediate CA, then the `cacerts.pem` must contain both the intermediate and root CA certificates (in this order). + +To create the initial `tls-ca` secret: + +```bash +kubectl -n cattle-system create secret generic tls-ca \ + --from-file=cacerts.pem +``` + +To update an existing `tls-ca` secret: + +```bash +kubectl -n cattle-system create secret generic tls-ca \ + --from-file=cacerts.pem \ + --dry-run --save-config -o yaml | kubectl apply -f - +``` + +### 3. Reconfigure the Rancher deployment + +If the certificate source remains the same (for example, `secret`), please follow the steps in Step 3a. + +However, if the certificate source is changing (for example, `letsEncrypt` to `secret`), follow the steps in 3b. + +#### 3a. Redeploy the Rancher pods + +This step is required when the certificate source remains the same, but the CA certificate is being updated. + +In this scenario a redeploy of the Rancher pods is needed, this is because the `tls-ca` secret is read by the Rancher pods when starting. + +The command below can be used to redeploy the Rancher pods: +```bash +kubectl rollout restart deploy/rancher -n cattle-system +``` + +When the change is completed, navigate to `https:///v3/settings/cacerts` to verify that the value matches the CA certificate written in the `tls-ca` secret earlier. The CA `cacerts` value may not update until all of the redeployed Rancher pods start. + +#### 3b. Update the Helm values for Rancher + +This step is required if the certificate source is changing. If Rancher was previously configured to use the default self-signed certificate (`ingress.tls.source=rancher`) or Let's Encrypt (`ingress.tls.source=letsEncrypt`), and is now using a certificate signed by a private CA (`ingress.tls.source=secret`). + +The below steps update the Helm values for the Rancher chart, so the Rancher pods and ingress are reconfigured to use the new private CA certificate created in Step 1 & 2. + + 1. Adjust the values that were used during initial installation, store the current values with: + ```bash + helm get values rancher -n cattle-system -o yaml > values.yaml + ``` + 1. Retrieve the version string of the currently deployed Rancher chart to use below: + ```bash + helm ls -n cattle-system + ``` + 1. Update the current Helm values in the `values.yaml` file to contain: + ```yaml + ingress: + tls: + source: secret + privateCA: true + ``` + :::note Important: + As the certificate is signed by a private CA, it is important to ensure [`privateCA: true`](../installation-references/helm-chart-options.md#common-options) is set in the `values.yaml` file. + ::: + 1. Upgrade the Helm application instance using the `values.yaml` file and the current chart version. The version must match to prevent an upgrade of Rancher. + ```bash + helm upgrade rancher rancher-stable/rancher \ + --namespace cattle-system \ + -f values.yaml \ + --version + ``` + +When the change is completed, navigate to `https:///v3/settings/cacerts` to verify that the value matches the CA certificate written in the `tls-ca` secret earlier. The CA `cacerts` value may not update until all Rancher pods start. + +### 4. Reconfigure Rancher agents to trust the private CA + +This section covers three methods to reconfigure Rancher agents to trust the private CA. This step is required if either of the following is true: + +- Rancher was previously configured to use the Rancher self-signed certificate (`ingress.tls.source=rancher`) or with a Let's Encrypt issued certificate (`ingress.tls.source=letsEncrypt`) +- The certificate was signed by a different private CA + +#### Why is this step required? + +When Rancher is configured with a certificate signed by a private CA, the CA certificate chain is trusted by Rancher agent containers. Agents compare the checksum of the downloaded certificate against the `CATTLE_CA_CHECKSUM` environment variable. This means that, when the private CA certificate used by Rancher has changed, the environment variable `CATTLE_CA_CHECKSUM` must be updated accordingly. + +#### Which method should I choose? + +Method 1 is the easiest, but requires all clusters to be connected to Rancher after the certificates have been rotated. This is usually the case if the process is performed right after updating or redeploying the Rancher deployment (Step 3). + +If the clusters have lost connection to Rancher but [Authorized Cluster Endpoint](../../../how-to-guides/new-user-guides/manage-clusters/access-clusters/authorized-cluster-endpoint.md) (ACE) is enabled on all clusters, then go with method 2. + +Method 3 can be used as a fallback if method 1 and 2 are not possible. + +#### Method 1: Force a redeploy of the Rancher agents + +For each downstream cluster run the following command using the Kubeconfig file of the Rancher (local) management cluster. + +```bash +kubectl annotate clusters.management.cattle.io io.cattle.agent.force.deploy=true +``` + +:::note +Locate the cluster ID (c-xxxxx) for the downstream cluster, this can be seen in the browser URL bar when viewing the cluster in the Rancher UI, under Cluster Management. +::: + +This command will cause the agent manifest to be reapplied with the checksum of the new certificate. + +#### Method 2: Manually update the checksum environment variable + +Manually patch the agent Kubernetes objects by updating the `CATTLE_CA_CHECKSUM` environment variable to the value matching the checksum of the new CA certificate. Generate the new checksum value like so: + +```bash +curl -k -s -fL /v3/settings/cacerts | jq -r .value | sha256sum | awk '{print $1}' +``` + +Using a Kubeconfig for each downstream cluster update the environment variable for the two agent deployments. If the [ACE](../../../how-to-guides/new-user-guides/manage-clusters/access-clusters/authorized-cluster-endpoint.md) is enabled for the cluster, [the kubectl context can be adjusted](../../../how-to-guides/new-user-guides/manage-clusters/access-clusters/use-kubectl-and-kubeconfig.md#authenticating-directly-with-a-downstream-cluster) to connect directly to the downstream cluster. + +```bash +kubectl edit -n cattle-system ds/cattle-node-agent +kubectl edit -n cattle-system deployment/cattle-cluster-agent +``` + +#### Method 3: Manually redeploy the Rancher agents + +With this method the Rancher agents are reapplied by running a set of commands on a control plane node of each downstream cluster. + +Repeat the below steps for each downstream cluster: + + 1. Retrieve the agent registration kubectl command: + 1. Locate the cluster ID (c-xxxxx) for the downstream cluster, this can be seen in the URL when viewing the cluster in the Rancher UI under Cluster Management + 1. Add the Rancher server URL and cluster ID to the following URL: `https:///v3/clusterregistrationtokens?clusterId=` + 1. Copy the command from the `insecureCommand` field, this command is used because a private CA is un use + + 2. Run the kubectl command from the previous step using a kubeconfig for the downstream cluster with one of the following methods: + 1. If the [ACE](../../../how-to-guides/new-user-guides/manage-clusters/access-clusters/authorized-cluster-endpoint.md) is enabled for the cluster, [the context can be adjusted](../../../how-to-guides/new-user-guides/manage-clusters/access-clusters/use-kubectl-and-kubeconfig.md#authenticating-directly-with-a-downstream-cluster) to connect directly to the downstream cluster + 1. Alternatively, SSH into the control plane node: + - RKE: Use the [steps in the document here](https://github.com/rancherlabs/support-tools/tree/master/how-to-retrieve-kubeconfig-from-custom-cluster) to generate a kubeconfig + - RKE2/K3s: Use the kubeconfig populated during installation + +### 5. Force Update Fleet clusters to reconnect the fleet-agent to Rancher + +Select 'Force Update' for the clusters within the [Continuous Delivery](../../../integrations-in-rancher/fleet/overview.md#accessing-fleet-in-the-rancher-ui) view of the Rancher UI to allow the fleet-agent in downstream clusters to successfully connect to Rancher. + +#### Why is this step required? + +Fleet agents in Rancher managed clusters store a kubeconfig that is used to connect to Rancher. The kubeconfig contains a `certificate-authority-data` field containing the CA for the certificate used by Rancher. When changing the CA, this block needs to be updated to allow the fleet-agent to trust the certificate used by Rancher. + +## Updating from a Private CA Certificate to a Public CA Certificate + +Follow these steps to perform the opposite procedure as shown above, to change from a certificate issued by a private CA, to a public or self-signed CA. + +### 1. Create/update the certificate secret object + +First, concatenate the server certificate followed by any intermediate certificate(s) to a file named `tls.crt` and provide the corresponding certificate key in a file named `tls.key`. + +Use the following command to create the `tls-rancher-ingress` secret object in the Rancher (local) management cluster: + +```bash +kubectl -n cattle-system create secret tls tls-rancher-ingress \ + --cert=tls.crt \ + --key=tls.key +``` + +Alternatively, to update an existing `tls-rancher-ingress` secret: + +```bash +kubectl -n cattle-system create secret tls tls-rancher-ingress \ + --cert=tls.crt \ + --key=tls.key \ + --dry-run --save-config -o yaml | kubectl apply -f - +``` + +### 2. Delete the CA certificate secret object + +You will delete the `tls-ca` secret in the `cattle-system` namespace as it is no longer needed. You may also optionally save a copy of the `tls-ca` secret if desired. + +To save the existing `tls-ca` secret: + +```bash +kubectl -n cattle-system get secret tls-ca -o yaml > tls-ca.yaml +``` + +To delete the existing `tls-ca` secret: + +```bash +kubectl -n cattle-system delete secret tls-ca +``` + +### 3. Reconfigure the Rancher deployment + +This step is required if the certificate source is changing. In this scenario it's likely only changing because Rancher was previously configured to use the default self-signed certificate (`ingress.tls.source=rancher`). + +The below steps update the Helm values for the Rancher chart, so the Rancher pods and ingress are reconfigured to use the new certificate created in Step 1. + + 1. Adjust the values that were used during initial installation, store the current values with: + ```bash + helm get values rancher -n cattle-system -o yaml > values.yaml + ``` + 1. Also get the version string of the currently deployed Rancher chart: + ```bash + helm ls -n cattle-system + ``` + 1. Update the current Helm values in the `values.yaml` file: + 1. As a private CA is no longer being used, remove the `privateCA: true` field, or set this to `false` + 1. Adjust the `ingress.tls.source` field as necessary. Please [refer to the chart options](../installation-references/helm-chart-options.md#common-options) for more details. Here are some examples: + 1. If using a public CA continue with a value of: `secret` + 1. If using Let's Encrypt update the value to: `letsEncrypt` + 1. Update the Helm values for the Rancher chart using the `values.yaml` file, and the current chart version to prevent an upgrade: + ```bash + helm upgrade rancher rancher-stable/rancher \ + --namespace cattle-system \ + -f values.yaml \ + --version + ``` + +### 4. Reconfigure Rancher agents for the non-private/common certificate + +As a private CA is no longer being used, the `CATTLE_CA_CHECKSUM` environment variable on the downstream cluster agents should be removed or set to "" (an empty string). + +### 5. Force Update Fleet clusters to reconnect the fleet-agent to Rancher + +Select 'Force Update' for the clusters within the [Continuous Delivery](../../../integrations-in-rancher/fleet/overview.md#accessing-fleet-in-the-rancher-ui) view of the Rancher UI to allow the fleet-agent in downstream clusters to successfully connect to Rancher. + +#### Why is this step required? + +Fleet agents in Rancher managed clusters store a kubeconfig that is used to connect to Rancher. The kubeconfig contains a `certificate-authority-data` field containing the CA for the certificate used by Rancher. When changing the CA, this block needs to be updated to allow the fleet-agent to trust the certificate used by Rancher. diff --git a/versioned_docs/version-2.14/getting-started/installation-and-upgrade/resources/upgrade-cert-manager.md b/versioned_docs/version-2.14/getting-started/installation-and-upgrade/resources/upgrade-cert-manager.md new file mode 100644 index 00000000000..ff5f495f501 --- /dev/null +++ b/versioned_docs/version-2.14/getting-started/installation-and-upgrade/resources/upgrade-cert-manager.md @@ -0,0 +1,288 @@ +--- +title: Upgrading Cert-Manager +--- + + + + + +Rancher is compatible with the API version cert-manager.io/v1 and was last tested with cert-manager version v1.13.1. + +Rancher uses cert-manager to automatically generate and renew TLS certificates for HA deployments of Rancher. As of Fall 2019, three important changes to cert-manager are set to occur that you need to take action on if you have an HA deployment of Rancher: + +1. [Let's Encrypt will be blocking cert-manager instances older than 0.8.0 starting November 1st 2019.](https://community.letsencrypt.org/t/blocking-old-cert-manager-versions/98753) +1. [Cert-manager is deprecating and replacing the certificate.spec.acme.solvers field](https://cert-manager.io/docs/installation/upgrading/upgrading-0.7-0.8/). This change has no exact deadline. +1. [Cert-manager is deprecating `v1alpha1` API and replacing its API group](https://cert-manager.io/docs/installation/upgrading/upgrading-0.10-0.11/) + +To address these changes, this guide will do two things: + +1. Document the procedure for upgrading cert-manager +1. Explain the cert-manager API changes and link to cert-manager's official documentation for migrating your data + +:::note Important: + +If you are upgrading cert-manager to the latest version from a version older than 1.5, follow the steps in [Option C](#option-c-upgrade-cert-manager-from-versions-15-and-below) below to do so. Note that you do not need to reinstall Rancher to perform this upgrade. + +::: + +## Upgrade Cert-Manager + +The namespace used in these instructions depends on the namespace cert-manager is currently installed in. If it is in kube-system use that in the instructions below. You can verify by running `kubectl get pods --all-namespaces` and checking which namespace the cert-manager-\* pods are listed in. Do not change the namespace cert-manager is running in or this can cause issues. + +In order to upgrade cert-manager, follow these instructions: + +### Option A: Upgrade cert-manager with Internet Access + +
+ Click to expand + +1. [Back up existing resources](https://cert-manager.io/docs/tutorials/backup/) as a precaution + + ```plain + kubectl get -o yaml --all-namespaces \ + issuer,clusterissuer,certificates,certificaterequests > cert-manager-backup.yaml + ``` + + :::note Important: + + If you are upgrading from a version older than 0.11.0, Update the apiVersion on all your backed up resources from `certmanager.k8s.io/v1alpha1` to `cert-manager.io/v1alpha2`. If you use any cert-manager annotations on any of your other resources, you will need to update them to reflect the new API group. For details, refer to the documentation on [additional annotation changes.](https://cert-manager.io/docs/installation/upgrading/upgrading-0.10-0.11/#additional-annotation-changes) + + ::: + +1. [Uninstall existing deployment](https://cert-manager.io/docs/installation/uninstall/kubernetes/#uninstalling-with-helm) + + ```plain + helm uninstall cert-manager + ``` + + Delete the CustomResourceDefinition using the link to the version vX.Y.Z you installed + + ```plain + kubectl delete -f https://github.com/cert-manager/cert-manager/releases/download/vX.Y.Z/cert-manager.crds.yaml + + ``` + +1. Install the CustomResourceDefinition resources separately + + ```plain + kubectl apply --validate=false -f https://github.com/cert-manager/cert-manager/releases/download/vX.Y.Z/cert-manager.crds.yaml + + ``` + + :::note + + If you are running Kubernetes v1.15 or below, you will need to add the `--validate=false` flag to your `kubectl apply` command above. Otherwise, you will receive a validation error relating to the `x-kubernetes-preserve-unknown-fields` field in cert-manager’s CustomResourceDefinition resources. This is a benign error and occurs due to the way kubectl performs resource validation. + + ::: + +1. Create the namespace for cert-manager if needed + + ```plain + kubectl create namespace cert-manager + ``` + +1. Add the Jetstack Helm repository + + ```plain + helm repo add jetstack https://charts.jetstack.io + ``` + +1. Update your local Helm chart repository cache + + ```plain + helm repo update + ``` + +1. Install the new version of cert-manager + + ```plain + helm install \ + cert-manager jetstack/cert-manager \ + --namespace cert-manager + ``` + +1. [Restore back up resources](https://cert-manager.io/docs/tutorials/backup/#restoring-resources) + + ```plain + kubectl apply -f cert-manager-backup.yaml + ``` + +
+ +### Option B: Upgrade cert-manager in an Air-Gapped Environment + +
+ Click to expand + +### Prerequisites + +Before you can perform the upgrade, you must prepare your air gapped environment by adding the necessary container images to your private registry and downloading or rendering the required Kubernetes manifest files. + +1. Follow the guide to [Prepare your Private Registry](../other-installation-methods/air-gapped-helm-cli-install/publish-images.md) with the images needed for the upgrade. + +1. From a system connected to the internet, add the cert-manager repo to Helm + + ```plain + helm repo add jetstack https://charts.jetstack.io + helm repo update + ``` + +1. Fetch the latest cert-manager chart available from the [Helm chart repository](https://artifacthub.io/packages/helm/cert-manager/cert-manager). + + ```plain + helm fetch jetstack/cert-manager + ``` + +1. Render the cert manager template with the options you would like to use to install the chart. Remember to set the `image.repository` option to pull the image from your private registry. This will create a `cert-manager` directory with the Kubernetes manifest files. + + The Helm 3 command is as follows: + + ```plain + helm template cert-manager ./cert-manager-v0.12.0.tgz --output-dir . \ + --namespace cert-manager \ + --set image.repository=/quay.io/jetstack/cert-manager-controller + --set webhook.image.repository=/quay.io/jetstack/cert-manager-webhook + --set cainjector.image.repository=/quay.io/jetstack/cert-manager-cainjector + ``` + + + + The Helm 2 command is as follows: + + ```plain + helm template ./cert-manager-v0.12.0.tgz --output-dir . \ + --name cert-manager --namespace cert-manager \ + --set image.repository=/quay.io/jetstack/cert-manager-controller + --set webhook.image.repository=/quay.io/jetstack/cert-manager-webhook + --set cainjector.image.repository=/quay.io/jetstack/cert-manager-cainjector + ``` + +1. Download the required CRD file for cert-manager (old and new) + + ```plain + curl -L -o cert-manager-crd.yaml https://raw.githubusercontent.com/cert-manager/cert-manager/release-0.12/deploy/manifests/00-crds.yaml + curl -L -o cert-manager/cert-manager-crd-old.yaml https://raw.githubusercontent.com/cert-manager/cert-manager/release-X.Y/deploy/manifests/00-crds.yaml + ``` + +### Install cert-manager + +1. Back up existing resources as a precaution + + ```plain + kubectl get -o yaml --all-namespaces \ + issuer,clusterissuer,certificates,certificaterequests > cert-manager-backup.yaml + ``` + + :::note Important: + + If you are upgrading from a version older than 0.11.0, Update the apiVersion on all your backed up resources from `certmanager.k8s.io/v1alpha1` to `cert-manager.io/v1alpha2`. If you use any cert-manager annotations on any of your other resources, you will need to update them to reflect the new API group. For details, refer to the documentation on [additional annotation changes.](https://cert-manager.io/docs/installation/upgrading/upgrading-0.10-0.11/#additional-annotation-changes) + + ::: + +1. Delete the existing cert-manager installation + + ```plain + kubectl -n cert-manager \ + delete deployment,sa,clusterrole,clusterrolebinding \ + -l 'app=cert-manager' -l 'chart=cert-manager-v0.5.2' + ``` + + Delete the CustomResourceDefinition using the link to the version vX.Y you installed + + ```plain + kubectl delete -f cert-manager/cert-manager-crd-old.yaml + ``` + +1. Install the CustomResourceDefinition resources separately + + ```plain + kubectl apply -f cert-manager/cert-manager-crd.yaml + ``` + + :::note Important: + + If you are running Kubernetes v1.15 or below, you will need to add the `--validate=false` flag to your `kubectl apply` command above. Otherwise, you will receive a validation error relating to the `x-kubernetes-preserve-unknown-fields` field in cert-manager’s CustomResourceDefinition resources. This is a benign error and occurs due to the way kubectl performs resource validation. + + ::: + +1. Create the namespace for cert-manager + + ```plain + kubectl create namespace cert-manager + ``` + +1. Install cert-manager + + ```plain + kubectl -n cert-manager apply -R -f ./cert-manager + ``` + +1. [Restore back up resources](https://cert-manager.io/docs/tutorials/backup/#restoring-resources) + + ```plain + kubectl apply -f cert-manager-backup.yaml + ``` + +
+ +### Option C: Upgrade cert-manager from Versions 1.5 and Below + +
+ Click to expand + +Previously, in order to upgrade cert-manager from an older version, an uninstall and reinstall of Rancher was recommended. Using the method below, you may upgrade cert-manager without those additional steps in order to better preserve your production environment: + +1. Install `cmctl`, the cert-manager CLI tool, using [the installation guide](https://cert-manager.io/docs/usage/cmctl/#installation). + +1. Ensure that any cert-manager custom resources that may have been stored in etcd at a deprecated API version get migrated to v1: + + ``` + cmctl upgrade migrate-api-version + ``` + Refer to the [API version migration docs](https://cert-manager.io/docs/usage/cmctl/#migrate-api-version) for more information. Please also see the [docs to upgrade from 1.5 to 1.6](https://cert-manager.io/docs/installation/upgrading/upgrading-1.5-1.6/) and the [docs to upgrade from 1.6. to 1.7](https://cert-manager.io/docs/installation/upgrading/upgrading-1.6-1.7/) if needed. + +1. Upgrade cert-manager to v1.7.1 with a normal `helm upgrade`. You may go directly from version 1.5 to 1.7 if desired. + +1. Follow the Helm tutorial to [update the API version of a release manifest](https://helm.sh/docs/topics/kubernetes_apis/#updating-api-versions-of-a-release-manifest). The chart release name is `release_name=rancher` and the release namespace is `release_namespace=cattle-system`. + +1. In the decoded file, search for `cert-manager.io/v1beta1` and **replace it** with `cert-manager.io/v1`. + +1. Upgrade Rancher normally with `helm upgrade`. + +
+ +### Verify the Deployment + +Once you’ve installed cert-manager, you can verify it is deployed correctly by checking the kube-system namespace for running pods: + +``` +kubectl get pods --namespace cert-manager + +NAME READY STATUS RESTARTS AGE +cert-manager-5c6866597-zw7kh 1/1 Running 0 2m +cert-manager-cainjector-577f6d9fd7-tr77l 1/1 Running 0 2m +cert-manager-webhook-787858fcdb-nlzsq 1/1 Running 0 2m +``` + +## Cert-Manager API change and data migration + +--- + +Rancher now supports cert-manager versions 1.6.2 and 1.7.1. We recommend v1.7.x because v 1.6.x will reach end-of-life on March 30, 2022. To read more, see the [cert-manager docs](../install-upgrade-on-a-kubernetes-cluster/install-upgrade-on-a-kubernetes-cluster.md#4-install-cert-manager). For instructions on upgrading cert-manager from version 1.5 to 1.6, see the upstream cert-manager documentation [here](https://cert-manager.io/docs/installation/upgrading/upgrading-1.5-1.6/). For instructions on upgrading cert-manager from version 1.6 to 1.7, see the upstream cert-manager documentation [here](https://cert-manager.io/docs/installation/upgrading/upgrading-1.6-1.7/). + +--- + +Cert-manager has deprecated the use of the `certificate.spec.acme.solvers` field and will drop support for it completely in an upcoming release. + +Per the cert-manager documentation, a new format for configuring ACME certificate resources was introduced in v0.8. Specifically, the challenge solver configuration field was moved. Both the old format and new are supported as of v0.9, but support for the old format will be dropped in an upcoming release of cert-manager. The cert-manager documentation strongly recommends that after upgrading you update your ACME Issuer and Certificate resources to the new format. + +Details about the change and migration instructions can be found in the [cert-manager v0.7 to v0.8 upgrade instructions](https://cert-manager.io/docs/installation/upgrading/upgrading-0.7-0.8/). + +The v0.11 release marks the removal of the v1alpha1 API that was used in previous versions of cert-manager, as well as our API group changing to be cert-manager.io instead of certmanager.k8s.io. + +We have also removed support for the old configuration format that was deprecated in the v0.8 release. This means you must transition to using the new solvers style configuration format for your ACME issuers before upgrading to v0.11. For more information, see the [upgrading to v0.8 guide](https://cert-manager.io/docs/installation/upgrading/upgrading-0.7-0.8/). + +Details about the change and migration instructions can be found in the [cert-manager v0.10 to v0.11 upgrade instructions](https://cert-manager.io/docs/installation/upgrading/upgrading-0.10-0.11/). + +More info about [cert-manager upgrade information](https://cert-manager.io/docs/installation/upgrade/). + diff --git a/versioned_docs/version-2.14/getting-started/installation-and-upgrade/upgrade-and-roll-back-kubernetes.md b/versioned_docs/version-2.14/getting-started/installation-and-upgrade/upgrade-and-roll-back-kubernetes.md new file mode 100644 index 00000000000..9794732ef29 --- /dev/null +++ b/versioned_docs/version-2.14/getting-started/installation-and-upgrade/upgrade-and-roll-back-kubernetes.md @@ -0,0 +1,129 @@ +--- +title: Upgrading and Rolling Back Kubernetes +--- + + + + + +Following an upgrade to the latest version of Rancher, downstream Kubernetes clusters can be upgraded to use the latest supported version of Kubernetes. + +Rancher calls RKE (Rancher Kubernetes Engine) as a library when provisioning and editing RKE clusters. For more information on configuring the upgrade strategy for RKE clusters, refer to the [RKE documentation](https://rancher.com/docs/rke/latest/en/). + + +## Tested Kubernetes Versions + +Before a new version of Rancher is released, it's tested with the latest minor versions of Kubernetes to ensure compatibility. For details on which versions of Kubernetes were tested on each Rancher version, refer to the [support maintenance terms.](https://rancher.com/support-maintenance-terms/all-supported-versions/rancher-v2.6.0/) + +## How Upgrades Work + +RKE v1.1.0 changed the way that clusters are upgraded. + +In this section of the [RKE documentation,](https://rancher.com/docs/rke/latest/en/upgrades/how-upgrades-work) you'll learn what happens when you edit or upgrade your RKE Kubernetes cluster. + + +## Recommended Best Practice for Upgrades + +When upgrading the Kubernetes version of a cluster, we recommend that you: + +1. Take a snapshot. +1. Initiate a Kubernetes upgrade. +1. If the upgrade fails, revert the cluster to the pre-upgrade Kubernetes version. This is achieved by selecting the **Restore etcd and Kubernetes version** option. This will return your cluster to the pre-upgrade kubernetes version before restoring the etcd snapshot. + +The restore operation will work on a cluster that is not in a healthy or active state. + +## Upgrading the Kubernetes Version + +:::note Prerequisites: + +- The options below are available for [Rancher-launched Kubernetes clusters](../../how-to-guides/new-user-guides/launch-kubernetes-with-rancher/launch-kubernetes-with-rancher.md) and [Registered K3s Kubernetes clusters](../../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/register-existing-clusters.md#additional-features-for-registered-rke2-and-k3s-clusters). +- The following options also apply to imported RKE2 clusters that you have registered. If you import a cluster from an external cloud platform but don't register it, you won't be able to upgrade the Kubernetes version from Rancher. +- Before upgrading Kubernetes, [back up your cluster.](../../how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/backup-restore-and-disaster-recovery.md) + +::: + +1. In the upper left corner, click **☰ > Cluster Management**. +1. On the **Clusters** page, go to the cluster you want to upgrade and click **⋮ > Edit Config**. +1. From the **Kubernetes Version** drop-down, choose the version of Kubernetes that you want to use for the cluster. +1. Click **Save**. + +**Result:** Kubernetes begins upgrading for the cluster. + +## Rolling Back + +A cluster can be restored to a backup in which the previous Kubernetes version was used. For more information, refer to the following sections: + +- [Backing up a cluster](../../how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/back-up-rancher-launched-kubernetes-clusters.md#how-snapshots-work) +- [Restoring a cluster from backup](../../how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/restore-rancher-launched-kubernetes-clusters-from-backup.md#restoring-a-cluster-from-a-snapshot) + +## Configuring the Upgrade Strategy + +As of RKE v1.1.0, additional upgrade options became available to give you more granular control over the upgrade process. These options can be used to maintain availability of your applications during a cluster upgrade if certain [conditions and requirements](https://rancher.com/docs/rke/latest/en/upgrades/maintaining-availability) are met. + +The upgrade strategy can be configured in the Rancher UI, or by editing the `cluster.yml`. More advanced options are available by editing the `cluster.yml`. + +### Configuring the Maximum Unavailable Worker Nodes in the Rancher UI + +From the Rancher UI, the maximum number of unavailable worker nodes can be configured. During a cluster upgrade, worker nodes will be upgraded in batches of this size. + +By default, the maximum number of unavailable worker is defined as 10 percent of all worker nodes. This number can be configured as a percentage or as an integer. When defined as a percentage, the batch size is rounded down to the nearest node, with a minimum of one node. + +To change the default number or percentage of worker nodes, + +1. In the upper left corner, click **☰ > Cluster Management**. +1. On the **Clusters** page, go to the cluster you want to upgrade and click **⋮ > Edit Config**. +1. In the **Upgrade Strategy** tab, enter the **Worker Concurrency** as a fixed number or percentage. To get this number, you can take the number of nodes in your cluster and subtract the max unavailable nodes. +1. Click **Save**. + +**Result:** The cluster is updated to use the new upgrade strategy. + +### Enabling Draining Nodes During Upgrades from the Rancher UI + +By default, RKE [cordons](https://kubernetes.io/docs/concepts/architecture/nodes/#manual-node-administration) each node before upgrading it. [Draining](https://kubernetes.io/docs/tasks/administer-cluster/safely-drain-node/) is disabled during upgrades by default. If draining is enabled in the cluster configuration, RKE will both cordon and drain the node before it is upgraded. + +To enable draining each node during a cluster upgrade, + +1. In the upper left corner, click **☰ > Cluster Management**. +1. On the **Clusters** page, go to the cluster you want to enable node draining and click **⋮ > Edit Config**. +1. Click **⋮ > Edit**. +1. In the **Upgrade Strategy** tab, go to the **Drain nodes** field and click **Yes**. Node draining is configured separately for control plane and worker nodes. +1. Configure the options for how pods are deleted. For more information about each option, refer to [this section.](../../how-to-guides/new-user-guides/manage-clusters/nodes-and-node-pools.md#aggressive-and-safe-draining-options) +1. Optionally, configure a grace period. The grace period is the timeout given to each pod for cleaning things up, so they will have chance to exit gracefully. Pods might need to finish any outstanding requests, roll back transactions or save state to some external storage. If this value is negative, the default value specified in the pod will be used. +1. Optionally, configure a timeout, which is the amount of time the drain should continue to wait before giving up. +1. Click **Save**. + +**Result:** The cluster is updated to use the new upgrade strategy. + +:::note + +- There is a [known issue](https://github.com/rancher/rancher/issues/25478) in which the Rancher UI doesn't show the state of etcd and controlplane as drained, even though they are being drained. +- During an upgrade, nodes may be drained even when no user-visible YAML changes are present. This can occur if non-dynamic configuration files are updated or if a new `system-agent-installer` image is introduced. In such cases, Rancher generates a new upgrade plan, resulting in a new plan hash. When `Upgrade Strategy` is set to `Drain nodes`, this plan change can trigger node draining. + +::: + +### Maintaining Availability for Applications During Upgrades + +In [this section of the RKE documentation,](https://rancher.com/docs/rke/latest/en/upgrades/maintaining-availability/) you'll learn the requirements to prevent downtime for your applications when upgrading the cluster. + +### Configuring the Upgrade Strategy in the cluster.yml + +More advanced upgrade strategy configuration options are available by editing the `cluster.yml`. + +For details, refer to [Configuring the Upgrade Strategy](https://rancher.com/docs/rke/latest/en/upgrades/configuring-strategy) in the RKE documentation. The section also includes an example `cluster.yml` for configuring the upgrade strategy. + +## Troubleshooting + +If a node doesn't come up after an upgrade, the `rke up` command errors out. + +No upgrade will proceed if the number of unavailable nodes exceeds the configured maximum. + +If an upgrade stops, you may need to fix an unavailable node or remove it from the cluster before the upgrade can continue. + +A failed node could be in many different states: + +- Powered off +- Unavailable +- User drains a node while upgrade is in process, so there are no kubelets on the node +- The upgrade itself failed + +If the max unavailable number of nodes is reached during an upgrade, Rancher user clusters will be stuck in updating state and not move forward with upgrading any other control plane nodes. It will continue to evaluate the set of unavailable nodes in case one of the nodes becomes available. If the node cannot be fixed, you must remove the node in order to continue the upgrade. diff --git a/versioned_docs/version-2.14/getting-started/installation-and-upgrade/upgrade-kubernetes-without-upgrading-rancher.md b/versioned_docs/version-2.14/getting-started/installation-and-upgrade/upgrade-kubernetes-without-upgrading-rancher.md new file mode 100644 index 00000000000..f07f4407cd4 --- /dev/null +++ b/versioned_docs/version-2.14/getting-started/installation-and-upgrade/upgrade-kubernetes-without-upgrading-rancher.md @@ -0,0 +1,97 @@ +--- +title: Upgrading Kubernetes without Upgrading Rancher +--- + + + + + + + +The RKE metadata feature allows you to provision clusters with new versions of Kubernetes as soon as they are released, without upgrading Rancher. This feature is useful for taking advantage of patch versions of Kubernetes, for example, if you want to upgrade to Kubernetes v1.14.7 when your Rancher server originally supported v1.14.6. + +:::note + +The Kubernetes API can change between minor versions. Therefore, we don't support introducing minor Kubernetes versions, such as introducing v1.15 when Rancher currently supports v1.14. You would need to upgrade Rancher to add support for minor Kubernetes versions. + +::: + +Rancher's Kubernetes metadata contains information specific to the Kubernetes version that Rancher uses to provision [RKE clusters](../../how-to-guides/new-user-guides/launch-kubernetes-with-rancher/launch-kubernetes-with-rancher.md). Rancher syncs the data periodically and creates custom resource definitions (CRDs) for **system images,** **service options** and **addon templates**. Consequently, when a new Kubernetes version is compatible with the Rancher server version, the Kubernetes metadata makes the new version available to Rancher for provisioning clusters. The metadata gives you an overview of the information that the [Rancher Kubernetes Engine](https://rancher.com/docs/rke/latest/en/) (RKE) uses for deploying various Kubernetes versions. + +This table below describes the CRDs that are affected by the periodic data sync. + +:::note + +Only administrators can edit metadata CRDs. It is recommended not to update existing objects unless explicitly advised. + +::: + +| Resource | Description | Rancher API URL | +|----------|-------------|-----------------| +| System Images | List of system images used to deploy Kubernetes through RKE. | `/v3/rkek8ssystemimages` | +| Service Options | Default options passed to Kubernetes components like `kube-api`, `scheduler`, `kubelet`, `kube-proxy`, and `kube-controller-manager` | `/v3/rkek8sserviceoptions` | +| Addon Templates | YAML definitions used to deploy addon components like Canal, Calico, Flannel, Weave, Kube-dns, CoreDNS, `metrics-server`, `nginx-ingress` | `/v3/rkeaddons` | + +Administrators might configure the RKE metadata settings to do the following: + +- Refresh the Kubernetes metadata, if a new patch version of Kubernetes comes out and they want Rancher to provision clusters with the latest version of Kubernetes without having to upgrade Rancher +- Change the metadata URL that Rancher uses to sync the metadata, which is useful for air gap setups if you need to sync Rancher locally instead of with GitHub +- Prevent Rancher from auto-syncing the metadata, which is one way to prevent new and unsupported Kubernetes versions from being available in Rancher + +## Refresh Kubernetes Metadata + +The option to refresh the Kubernetes metadata is available for administrators by default, or for any user who has the **Manage Cluster Drivers** [global role.](../../how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/global-permissions.md) + +To force Rancher to refresh the Kubernetes metadata, a manual refresh action is available: + +1. In the upper left corner, click **☰ > Cluster Management**. +1. In the left navigation menu, click **Drivers**. +1. Click **Refresh Kubernetes Metadata**. + +You can configure Rancher to only refresh metadata when desired by setting `refresh-interval-minutes` to `0` (see below) and using this button to perform the metadata refresh manually when desired. + +### Configuring the Metadata Synchronization + +:::caution + +Only administrators can change these settings. + +::: + +The RKE metadata config controls how often Rancher syncs metadata and where it downloads data from. You can configure the metadata from the settings in the Rancher UI, or through the Rancher API at the endpoint `v3/settings/rke-metadata-config`. + +The way that the metadata is configured depends on the Rancher version. + +To edit the metadata config in Rancher, + +1. In the upper left corner, click **☰ > Global Settings**. +1. Go to the **rke-metadata-config** section. Click **⋮ > Edit Setting**. +1. You can optionally fill in the following parameters: + + - `refresh-interval-minutes`: This is the amount of time that Rancher waits to sync the metadata. To disable the periodic refresh, set `refresh-interval-minutes` to 0. + - `url`: This is the HTTP path that Rancher fetches data from. The path must be a direct path to a JSON file. For example, the default URL for Rancher v2.4 is `https://releases.rancher.com/kontainer-driver-metadata/release-v2.4/data.json`. +1. Click **Save**. + +If you don't have an air gap setup, you don't need to specify the URL where Rancher gets the metadata, because the default setting is to pull from [Rancher's metadata Git repository.](https://github.com/rancher/kontainer-driver-metadata/blob/dev-v2.5/data/data.json) + +However, if you have an [air gap setup,](#air-gap-setups) you will need to mirror the Kubernetes metadata repository in a location available to Rancher. Then you need to change the URL to point to the new location of the JSON file. + +## Air Gap Setups + +Rancher relies on a periodic refresh of the `rke-metadata-config` to download new Kubernetes version metadata if it is supported with the current version of the Rancher server. For a table of compatible Kubernetes and Rancher versions, refer to the [service terms section.](https://rancher.com/support-maintenance-terms/all-supported-versions/rancher-v2.2.8/) + +If you have an air gap setup, you might not be able to get the automatic periodic refresh of the Kubernetes metadata from Rancher's Git repository. In that case, you should disable the periodic refresh to prevent your logs from showing errors. Optionally, you can configure your metadata settings so that Rancher can sync with a local copy of the RKE metadata. + +To sync Rancher with a local mirror of the RKE metadata, an administrator would configure the `rke-metadata-config` settings to point to the mirror. For details, refer to [Configuring the Metadata Synchronization.](#configuring-the-metadata-synchronization) + +After new Kubernetes versions are loaded into the Rancher setup, additional steps would be required in order to use them for launching clusters. Rancher needs access to updated system images. While the metadata settings can only be changed by administrators, any user can download the Rancher system images and prepare a private container image registry for them. + +To download the system images for the private registry: + +1. Click **☰** in the top left corner. +1. At the bottom of the left navigation, click the Rancher version number. +1. Download the OS specific image lists for Linux or Windows. +1. Download `rancher-images.txt`. +1. Prepare the private registry using the same steps during the [air gap install](other-installation-methods/air-gapped-helm-cli-install/publish-images.md), but instead of using the `rancher-images.txt` from the releases page, use the one obtained from the previous steps. + +**Result:** The air gap installation of Rancher can now sync the Kubernetes metadata. If you update your private registry when new versions of Kubernetes are released, you can provision clusters with the new version without having to upgrade Rancher. diff --git a/versioned_docs/version-2.14/getting-started/overview.md b/versioned_docs/version-2.14/getting-started/overview.md new file mode 100644 index 00000000000..62cf4710724 --- /dev/null +++ b/versioned_docs/version-2.14/getting-started/overview.md @@ -0,0 +1,69 @@ +--- +title: Overview +--- + + + + + +Rancher is a container management platform built for organizations that deploy containers in production. Rancher makes it easy to run Kubernetes everywhere, meet IT requirements, and empower DevOps teams. + +## Run Kubernetes Everywhere + +Kubernetes has become the container orchestration standard. Most cloud and virtualization vendors now offer it as standard infrastructure. Rancher users have the choice of creating Kubernetes clusters with Rancher Kubernetes distributions (RKE2/K3s) or cloud Kubernetes services, such as GKE, AKS, and EKS. Rancher users can also import and manage their existing Kubernetes clusters created using any Kubernetes distribution or installer. + +## Meet IT Requirements + +Rancher supports centralized authentication, access control, and monitoring for all Kubernetes clusters under its control. For example, you can: + +- Use your Active Directory credentials to access Kubernetes clusters hosted by cloud vendors, such as GKE. +- Setup and enforce access control and security policies across all users, groups, projects, clusters, and clouds. +- View the health and capacity of your Kubernetes clusters from a single-pane-of-glass. + +## Empower DevOps Teams + +Rancher provides an intuitive user interface for DevOps engineers to manage their application workload. The user does not need to have in-depth knowledge of Kubernetes concepts to start using Rancher. Rancher catalog contains a set of useful DevOps tools. Rancher is certified with a wide selection of cloud native ecosystem products, including, for example, security tools, monitoring systems, container registries, and storage and networking drivers. + +The following figure illustrates the role Rancher plays in IT and DevOps organizations. Each team deploys their applications on the public or private clouds they choose. IT administrators gain visibility and enforce policies across all users, clusters, and clouds. + +![Platform](/img/platform.png) + +## Features of the Rancher API Server + +The Rancher API server is built on top of an embedded Kubernetes API server and an etcd database. It implements the following functionalities: + +### Authorization and Role-Based Access Control + +- **User management:** The Rancher API server [manages user identities](../how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/authentication-config/authentication-config.md) that correspond to external authentication providers like Active Directory or GitHub, in addition to local users. +- **Authorization:** The Rancher API server manages [access control](../how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/manage-role-based-access-control-rbac.md) and [security](../how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/pod-security-standards.md) standards. + +### Working with Kubernetes + +- **Provisioning Kubernetes clusters:** The Rancher API server can [provision Kubernetes](../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/kubernetes-clusters-in-rancher-setup.md) on existing nodes, or perform [Kubernetes upgrades.](installation-and-upgrade/upgrade-and-roll-back-kubernetes.md) +- **Catalog management:** Rancher provides the ability to use a [catalog of Helm charts](../how-to-guides/new-user-guides/helm-charts-in-rancher/helm-charts-in-rancher.md) that make it easy to repeatedly deploy applications. +- **Managing projects:** A project is a group of multiple namespaces and access control policies within a cluster. A project is a Rancher concept, not a Kubernetes concept, which allows you to manage multiple namespaces as a group and perform Kubernetes operations in them. The Rancher UI provides features for [project administration](../how-to-guides/advanced-user-guides/manage-projects/manage-projects.md) and for [managing applications within projects.](../how-to-guides/new-user-guides/kubernetes-resources-setup/kubernetes-resources-setup.md) +- **Fleet Continuous Delivery:** Within Rancher, you can leverage [Fleet Continuous Delivery](../integrations-in-rancher/fleet/fleet.md) to deploy applications from git repositories, without any manual operation, to targeted downstream Kubernetes clusters. +- **Istio:** Our [integration with Istio](../integrations-in-rancher/istio/istio.md) is designed so that a Rancher operator, such as an administrator or cluster owner, can deliver Istio to developers. Then developers can use Istio to enforce security policies, troubleshoot problems, or manage traffic for green/blue deployments, canary deployments, or A/B testing. + +### Working with Cloud Infrastructure + +- **Tracking nodes:** The Rancher API server tracks identities of all the [nodes](../how-to-guides/new-user-guides/manage-clusters/nodes-and-node-pools.md) in all clusters. +- **Setting up infrastructure:** When configured to use a cloud provider, Rancher can dynamically provision [new nodes](../how-to-guides/new-user-guides/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/use-new-nodes-in-an-infra-provider.md) and [persistent storage](../how-to-guides/new-user-guides/manage-clusters/create-kubernetes-persistent-storage/create-kubernetes-persistent-storage.md) in the cloud. + +### Cluster Visibility + +- **Logging:** Rancher can integrate with a variety of popular logging services and tools that exist outside of your Kubernetes clusters. +- **Monitoring:** Using Rancher, you can monitor the state and processes of your cluster nodes, Kubernetes components, and software deployments through integration with Prometheus, a leading open-source monitoring solution. +- **Alerting:** To keep your clusters and applications healthy and driving your organizational productivity forward, you need to stay informed of events occurring in your clusters and projects, both planned and unplanned. + +## Editing Downstream Clusters with Rancher + +The options and settings available for an existing cluster change based on the method that you used to provision it. + +After a cluster is created with Rancher, a cluster administrator can manage cluster membership or manage node pools, among [other options.](../reference-guides/cluster-configuration/cluster-configuration.md) + +The following table summarizes the options and settings available for each cluster type: + +import ClusterCapabilitiesTable from '../shared-files/_cluster-capabilities-table.md'; + + diff --git a/versioned_docs/version-2.14/getting-started/quick-start-guides/deploy-rancher-manager/aws-marketplace.md b/versioned_docs/version-2.14/getting-started/quick-start-guides/deploy-rancher-manager/aws-marketplace.md new file mode 100644 index 00000000000..ddc461d0a59 --- /dev/null +++ b/versioned_docs/version-2.14/getting-started/quick-start-guides/deploy-rancher-manager/aws-marketplace.md @@ -0,0 +1,11 @@ +--- +title: Rancher Prime AWS Marketplace Quick Start +description: Deploy SUSE Rancher from the AWS Marketplace listing. +--- + + + + + +You can quickly deploy Rancher Prime on Amazon Elastic Kubernetes Service (EKS.) To learn more, see the [instructions](https://suse-enceladus.github.io/marketplace-docs/rancher-prime/aws/?repository=rancher-payg-billing-adapter-llc-prd) under Usage Information in the [AWS Marketplace listing](https://aws.amazon.com/marketplace/pp/prodview-f2bvszurj2p2c). + diff --git a/versioned_docs/version-2.14/getting-started/quick-start-guides/deploy-rancher-manager/aws.md b/versioned_docs/version-2.14/getting-started/quick-start-guides/deploy-rancher-manager/aws.md new file mode 100644 index 00000000000..d3293cf8599 --- /dev/null +++ b/versioned_docs/version-2.14/getting-started/quick-start-guides/deploy-rancher-manager/aws.md @@ -0,0 +1,99 @@ +--- +title: Rancher AWS Quick Start Guide +description: Read this step by step Rancher AWS guide to quickly deploy a Rancher server with a single-node downstream Kubernetes cluster attached. +--- + + + + + +The following steps will quickly deploy a Rancher server on AWS in a single-node K3s Kubernetes cluster, with a single-node downstream Kubernetes cluster attached. + +:::caution + +The intent of these guides is to quickly launch a sandbox that you can use to evaluate Rancher. These guides are not intended for production environments. For comprehensive setup instructions, see [Installation](../../installation-and-upgrade/installation-and-upgrade.md). + +::: + +## Prerequisites + +:::caution + +Deploying to Amazon AWS will incur charges. + +::: + +- [Amazon AWS Account](https://aws.amazon.com/account/): An Amazon AWS Account is required to create resources for deploying Rancher and Kubernetes. +- [Amazon AWS Access Key](https://docs.aws.amazon.com/general/latest/gr/managing-aws-access-keys.html): Use this link to follow a tutorial to create an Amazon AWS Access Key if you don't have one yet. +- [IAM Policy created](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_create.html#access_policies_create-start): Defines the permissions an account attached with this policy has. +- Install [Terraform](https://developer.hashicorp.com/terraform/install): Used to provision the server and cluster in Amazon AWS. + +### Example IAM Policy + +The AWS module just creates an EC2 KeyPair, an EC2 SecurityGroup and an EC2 instance. A simple policy would be: + +```json +{ + "Version": "2012-10-17", + "Statement": [ + { + "Effect": "Allow", + "Action": "ec2:*", + "Resource": "*" + } + ] +} +``` + +## Getting Started + +1. Clone [Rancher Quickstart](https://github.com/rancher/quickstart) to a folder using `git clone https://github.com/rancher/quickstart`. + +2. Go into the AWS folder containing the Terraform files by executing `cd quickstart/rancher/aws`. + +3. Rename the `terraform.tfvars.example` file to `terraform.tfvars`. + +4. Edit `terraform.tfvars` and customize the following variables: + + - `aws_access_key` - Amazon AWS Access Key + - `aws_secret_key` - Amazon AWS Secret Key + - `rancher_server_admin_password` - Admin password for created Rancher server. See [Setting up the Bootstrap Password](../../installation-and-upgrade/resources/bootstrap-password.md#password-requirements) for password requirements. + +5. **Optional:** Modify optional variables within `terraform.tfvars`. See the [Quickstart Readme](https://github.com/rancher/quickstart) and the [AWS Quickstart Readme](https://github.com/rancher/quickstart/tree/master/rancher/aws) for more information. +Suggestions include: + + - `aws_region` - Amazon AWS region, choose the closest instead of the default (`us-east-1`) + - `prefix` - Prefix for all created resources + - `instance_type` - EC2 instance size used, minimum is `t3a.medium` but `t3a.large` or `t3a.xlarge` could be used if within budget + - `add_windows_node` - If true, an additional Windows worker node is added to the workload cluster + +6. Run `terraform init`. + +7. To initiate the creation of the environment, run `terraform apply --auto-approve`. Then wait for output similar to the following: + + ``` + Apply complete! Resources: 16 added, 0 changed, 0 destroyed. + + Outputs: + + rancher_node_ip = xx.xx.xx.xx + rancher_server_url = https://rancher.xx.xx.xx.xx.sslip.io + workload_node_ip = yy.yy.yy.yy + ``` + +8. Paste the `rancher_server_url` from the output above into the browser. Log in when prompted (default username is `admin`, use the password set in `rancher_server_admin_password`). +9. ssh to the Rancher Server using the `id_rsa` key generated in `quickstart/rancher/aws`. + +##### Result + +Two Kubernetes clusters are deployed into your AWS account, one running Rancher Server and the other ready for experimentation deployments. Please note that while this setup is a great way to explore Rancher functionality, a production setup should follow our high availability setup guidelines. SSH keys for the VMs are auto-generated and stored in the module directory. + +## What's Next? + +Use Rancher to create a deployment. For more information, see [Creating Deployments](../deploy-workloads/deploy-workloads.md). + +## Destroying the Environment + +1. From the `quickstart/rancher/aws` folder, execute `terraform destroy --auto-approve`. + +2. Wait for confirmation that all resources have been destroyed. diff --git a/versioned_docs/version-2.14/getting-started/quick-start-guides/deploy-rancher-manager/azure.md b/versioned_docs/version-2.14/getting-started/quick-start-guides/deploy-rancher-manager/azure.md new file mode 100644 index 00000000000..dd53fbabc4c --- /dev/null +++ b/versioned_docs/version-2.14/getting-started/quick-start-guides/deploy-rancher-manager/azure.md @@ -0,0 +1,85 @@ +--- +title: Rancher Azure Quick Start Guide +description: Read this step by step Rancher Azure guide to quickly deploy a Rancher server with a single-node downstream Kubernetes cluster attached. +--- + + + + + +The following steps will quickly deploy a Rancher server on Azure in a single-node K3s Kubernetes cluster, with a single-node downstream Kubernetes cluster attached. + +:::caution + +The intent of these guides is to quickly launch a sandbox that you can use to evaluate Rancher. These guides are not intended for production environments. For comprehensive setup instructions, see [Installation](../../installation-and-upgrade/installation-and-upgrade.md). + +::: + +## Prerequisites + +:::caution + +Deploying to Microsoft Azure will incur charges. + +::: + +- [Microsoft Azure Account](https://azure.microsoft.com/en-us/free/): A Microsoft Azure Account is required to create resources for deploying Rancher and Kubernetes. +- [Microsoft Azure Subscription](https://docs.microsoft.com/en-us/azure/cost-management-billing/manage/create-subscription#create-a-subscription-in-the-azure-portal): Use this link to follow a tutorial to create a Microsoft Azure subscription if you don't have one yet. +- [Micsoroft Azure Tenant](https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-create-new-tenant): Use this link and follow instructions to create a Microsoft Azure tenant. +- [Microsoft Azure Client ID/Secret](https://docs.microsoft.com/en-us/azure/active-directory/develop/howto-create-service-principal-portal): Use this link and follow instructions to create a Microsoft Azure client and secret. +- [Terraform](https://developer.hashicorp.com/terraform/install): Used to provision the server and cluster in Microsoft Azure. + + +## Getting Started + +1. Clone [Rancher Quickstart](https://github.com/rancher/quickstart) to a folder using `git clone https://github.com/rancher/quickstart`. + +2. Go into the Azure folder containing the Terraform files by executing `cd quickstart/rancher/azure`. + +3. Rename the `terraform.tfvars.example` file to `terraform.tfvars`. + +4. Edit `terraform.tfvars` and customize the following variables: + - `azure_subscription_id` - Microsoft Azure Subscription ID + - `azure_client_id` - Microsoft Azure Client ID + - `azure_client_secret` - Microsoft Azure Client Secret + - `azure_tenant_id` - Microsoft Azure Tenant ID + - `rancher_server_admin_password` - Admin password for created Rancher server. See [Setting up the Bootstrap Password](../../installation-and-upgrade/resources/bootstrap-password.md#password-requirements) for password requirements. + +5. **Optional:** Modify optional variables within `terraform.tfvars`. +See the [Quickstart Readme](https://github.com/rancher/quickstart) and the [Azure Quickstart Readme](https://github.com/rancher/quickstart/tree/master/rancher/azure) for more information. Suggestions include: + - `azure_location` - Microsoft Azure region, choose the closest instead of the default (`East US`) + - `prefix` - Prefix for all created resources + - `instance_type` - Compute instance size used, minimum is `Standard_DS2_v2` but `Standard_DS2_v3` or `Standard_DS3_v2` could be used if within budget + - `add_windows_node` - If true, an additional Windows worker node is added to the workload cluster + - `windows_admin_password` - The admin password of the windows worker node + +6. Run `terraform init`. + +7. To initiate the creation of the environment, run `terraform apply --auto-approve`. Then wait for output similar to the following: + + ``` + Apply complete! Resources: 16 added, 0 changed, 0 destroyed. + + Outputs: + + rancher_node_ip = xx.xx.xx.xx + rancher_server_url = https://rancher.xx.xx.xx.xx.sslip.io + workload_node_ip = yy.yy.yy.yy + ``` + +8. Paste the `rancher_server_url` from the output above into the browser. Log in when prompted (default username is `admin`, use the password set in `rancher_server_admin_password`). +9. ssh to the Rancher Server using the `id_rsa` key generated in `quickstart/rancher/azure`. + +#### Result + +Two Kubernetes clusters are deployed into your Azure account, one running Rancher Server and the other ready for experimentation deployments. Please note that while this setup is a great way to explore Rancher functionality, a production setup should follow our high availability setup guidelines. SSH keys for the VMs are auto-generated and stored in the module directory. + +### What's Next? + +Use Rancher to create a deployment. For more information, see [Creating Deployments](../deploy-workloads/deploy-workloads.md). + +## Destroying the Environment + +1. From the `quickstart/rancher/azure` folder, execute `terraform destroy --auto-approve`. + +2. Wait for confirmation that all resources have been destroyed. diff --git a/versioned_docs/version-2.14/getting-started/quick-start-guides/deploy-rancher-manager/deploy-rancher-manager.md b/versioned_docs/version-2.14/getting-started/quick-start-guides/deploy-rancher-manager/deploy-rancher-manager.md new file mode 100644 index 00000000000..af0c27aac71 --- /dev/null +++ b/versioned_docs/version-2.14/getting-started/quick-start-guides/deploy-rancher-manager/deploy-rancher-manager.md @@ -0,0 +1,24 @@ +--- +title: Deploying Rancher Server +--- + + + + + +Use one of the following guides to deploy and provision Rancher and a Kubernetes cluster in the provider of your choice. + +- [AWS](aws.md) (uses Terraform) +- [AWS Marketplace](aws-marketplace.md) (uses Amazon EKS) +- [Azure](azure.md) (uses Terraform) +- [DigitalOcean](digitalocean.md) (uses Terraform) +- [GCP](gcp.md) (uses Terraform) +- [Hetzner Cloud](hetzner-cloud.md) (uses Terraform) +- [Linode](linode.md) (uses Terraform) +- [Vagrant](vagrant.md) +- [Equinix Metal](equinix-metal.md) +- [Outscale](outscale-qs.md) (uses Terraform) + +If you prefer, the following guide will take you through the same process in individual steps. Use this if you want to run Rancher in a different provider, on prem, or if you would just like to see how easy it is. + +- [Manual Install](helm-cli.md) diff --git a/versioned_docs/version-2.14/getting-started/quick-start-guides/deploy-rancher-manager/digitalocean.md b/versioned_docs/version-2.14/getting-started/quick-start-guides/deploy-rancher-manager/digitalocean.md new file mode 100644 index 00000000000..146c247f7a4 --- /dev/null +++ b/versioned_docs/version-2.14/getting-started/quick-start-guides/deploy-rancher-manager/digitalocean.md @@ -0,0 +1,78 @@ +--- +title: Rancher DigitalOcean Quick Start Guide +description: Read this step by step Rancher DigitalOcean guide to quickly deploy a Rancher server with a single-node downstream Kubernetes cluster attached. +--- + + + + + +The following steps will quickly deploy a Rancher server on DigitalOcean in a single-node K3s Kubernetes cluster, with a single-node downstream Kubernetes cluster attached. + +:::caution + +The intent of these guides is to quickly launch a sandbox that you can use to evaluate Rancher. These guides are not intended for production environments. For comprehensive setup instructions, see [Installation](../../installation-and-upgrade/installation-and-upgrade.md). + +::: + +## Prerequisites + +:::caution + +Deploying to DigitalOcean will incur charges. + +::: + +- [DigitalOcean Account](https://www.digitalocean.com): You will require an account on DigitalOcean as this is where the server and cluster will run. +- [DigitalOcean Access Key](https://www.digitalocean.com/community/tutorials/how-to-create-a-digitalocean-space-and-api-key): Use this link to create a DigitalOcean Access Key if you don't have one. +- [Terraform](https://developer.hashicorp.com/terraform/install): Used to provision the server and cluster to DigitalOcean. + + +## Getting Started + +1. Clone [Rancher Quickstart](https://github.com/rancher/quickstart) to a folder using `git clone https://github.com/rancher/quickstart`. + +2. Go into the DigitalOcean folder containing the Terraform files by executing `cd quickstart/rancher/do`. + +3. Rename the `terraform.tfvars.example` file to `terraform.tfvars`. + +4. Edit `terraform.tfvars` and customize the following variables: + - `do_token` - DigitalOcean access key + - `rancher_server_admin_password` - Admin password for created Rancher server. See [Setting up the Bootstrap Password](../../installation-and-upgrade/resources/bootstrap-password.md#password-requirements) for password requirements. + +5. **Optional:** Modify optional variables within `terraform.tfvars`. +See the [Quickstart Readme](https://github.com/rancher/quickstart) and the [DO Quickstart Readme](https://github.com/rancher/quickstart/tree/master/rancher/do) for more information. Suggestions include: + - `do_region` - DigitalOcean region, choose the closest instead of the default (`nyc1`) + - `prefix` - Prefix for all created resources + - `droplet_size` - Droplet size used, minimum is `s-2vcpu-4gb` but `s-4vcpu-8gb` could be used if within budget + +6. Run `terraform init`. + +7. To initiate the creation of the environment, run `terraform apply --auto-approve`. Then wait for output similar to the following: + + ``` + Apply complete! Resources: 15 added, 0 changed, 0 destroyed. + + Outputs: + + rancher_node_ip = xx.xx.xx.xx + rancher_server_url = https://rancher.xx.xx.xx.xx.sslip.io + workload_node_ip = yy.yy.yy.yy + ``` + +8. Paste the `rancher_server_url` from the output above into the browser. Log in when prompted (default username is `admin`, use the password set in `rancher_server_admin_password`). +9. ssh to the Rancher Server using the `id_rsa` key generated in `quickstart/rancher/do`. + +#### Result + +Two Kubernetes clusters are deployed into your DigitalOcean account, one running Rancher Server and the other ready for experimentation deployments. Please note that while this setup is a great way to explore Rancher functionality, a production setup should follow our high availability setup guidelines. SSH keys for the VMs are auto-generated and stored in the module directory. + +### What's Next? + +Use Rancher to create a deployment. For more information, see [Creating Deployments](../deploy-workloads/deploy-workloads.md). + +## Destroying the Environment + +1. From the `quickstart/rancher/do` folder, execute `terraform destroy --auto-approve`. + +2. Wait for confirmation that all resources have been destroyed. diff --git a/versioned_docs/version-2.14/getting-started/quick-start-guides/deploy-rancher-manager/equinix-metal.md b/versioned_docs/version-2.14/getting-started/quick-start-guides/deploy-rancher-manager/equinix-metal.md new file mode 100644 index 00000000000..98a91950391 --- /dev/null +++ b/versioned_docs/version-2.14/getting-started/quick-start-guides/deploy-rancher-manager/equinix-metal.md @@ -0,0 +1,108 @@ +--- +title: Rancher Equinix Metal Quick Start +--- + + + + + +## This tutorial walks you through the following: + +- Provisioning an Equinix Metal Server +- Installation of Rancher 2.x +- Creation of your first cluster +- Deployment of an application, Nginx + +:::caution + +The intent of these guides is to quickly launch a sandbox that you can use to evaluate Rancher. The Docker install is not recommended for production environments. For comprehensive setup instructions, see [Installation](../../installation-and-upgrade/installation-and-upgrade.md). + +::: + +## Quick Start Outline + +This Quick Start Guide is divided into different tasks for easier consumption. + +
+ +## Prerequisites + +- An [Equinix Metal account](https://deploy.equinix.com/developers/docs/metal/identity-access-management/users/) +- An [Equinix Metal project](https://deploy.equinix.com/developers/docs/metal/projects/creating-a-project/) + + +### 1. Provision a Equinix Metal Host + +Begin deploying an Equinix Metal Host. Equinix Metal Servers can be provisioned from either the Equinix Metal console, API, or CLI. You can find instructions for each deployment type on the [Equinix Metal deployment documentation](https://deploy.equinix.com/developers/docs/metal/deploy/on-demand/). You can find additional information on Equinix Metal server types in the [Equinix Metal Documentation](https://deploy.equinix.com/developers/docs/metal/hardware/standard-servers/). + +:::note Notes: + +- When provisioning a new Equinix Metal Server via the CLI or API you will need to provide the following information: project-id, plan, metro, and operating-system. +- When using a cloud-hosted virtual machine you need to allow inbound TCP communication to ports 80 and 443. Please see your cloud host's documentation for information regarding port configuration. +- For a full list of port requirements, refer to [Docker Installation](../../../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/node-requirements-for-rancher-managed-clusters.md). +- Provision the host according to our [Requirements](../../installation-and-upgrade/installation-requirements/installation-requirements.md). + +::: +### 2. Install Rancher + +To install Rancher on your Equinix Metal host, connect to it and then use a shell to install. + +1. Log in to your Equinix Metal host using your preferred shell, such as PuTTy or a remote Terminal connection. + +2. From your shell, enter the following command: + + ``` + sudo docker run -d --restart=unless-stopped -p 80:80 -p 443:443 --privileged rancher/rancher + ``` + +**Result:** Rancher is installed. + +### 3. Log In + +Log in to Rancher to begin using the application. After you log in, you'll make some one-time configurations. + +1. Open a web browser and enter the IP address of your host: `https://`. + + Replace `` with your host IP address. + +2. When prompted, create a password for the default `admin` account there cowpoke! + +3. Set the **Rancher Server URL**. The URL can either be an IP address or a host name. However, each node added to your cluster must be able to connect to this URL.

If you use a hostname in the URL, this hostname must be resolvable by DNS on the nodes you want to add to you cluster. + +
+ +### 4. Create the Cluster + +Welcome to Rancher! You are now able to create your first Kubernetes cluster. + +In this task, you can use the versatile **Custom** option. This option lets you add _any_ Linux host (cloud-hosted VM, on-prem VM, or bare-metal) to be used in a cluster. + +1. Click **☰ > Cluster Management**. +1. From the **Clusters** page, click **Create**. +1. Choose **Custom**. +1. Enter a **Cluster Name**. +1. Click **Next**. +1. From **Node Role**, select _all_ the roles: **etcd**, **Control**, and **Worker**. + - **Optional**: Rancher auto-detects the IP addresses used for Rancher communication and cluster communication. You can override these using `Public Address` and `Internal Address` in the **Node Address** section. +1. Copy the registration command to your clipboard. +1. Log in to your Linux host using your preferred shell, such as PuTTy or a remote Terminal connection. Run the command copied to your clipboard. +1. When you finish running the command on your Linux host, click **Done**. + +**Result:** + +Your cluster is created and assigned a state of **Provisioning**. Rancher is standing up your cluster. + +You can access your cluster after its state is updated to **Active**. + +**Active** clusters are assigned two Projects: + +- `Default`, containing the `default` namespace +- `System`, containing the `cattle-system`, `ingress-nginx`, `kube-public`, and `kube-system` namespaces + +#### Finished + +Congratulations! You have created your first cluster. + +#### What's Next? + +Use Rancher to create a deployment. For more information, see [Creating Deployments](../deploy-workloads/deploy-workloads.md). diff --git a/versioned_docs/version-2.14/getting-started/quick-start-guides/deploy-rancher-manager/gcp.md b/versioned_docs/version-2.14/getting-started/quick-start-guides/deploy-rancher-manager/gcp.md new file mode 100644 index 00000000000..fd3c949ac68 --- /dev/null +++ b/versioned_docs/version-2.14/getting-started/quick-start-guides/deploy-rancher-manager/gcp.md @@ -0,0 +1,81 @@ +--- +title: Rancher GCP Quick Start Guide +description: Read this step by step Rancher GCP guide to quickly deploy a Rancher server with a single-node downstream Kubernetes cluster attached. +--- + + + + + +The following steps will quickly deploy a Rancher server on GCP in a single-node K3s Kubernetes cluster, with a single-node downstream Kubernetes cluster attached. + +:::caution + +The intent of these guides is to quickly launch a sandbox that you can use to evaluate Rancher. These guides are not intended for production environments. For comprehensive setup instructions, see [Installation](../../installation-and-upgrade/installation-and-upgrade.md). + +::: + +## Prerequisites + +:::caution + +Deploying to Google GCP will incur charges. + +::: + +- [Google GCP Account](https://console.cloud.google.com/): A Google GCP Account is required to create resources for deploying Rancher and Kubernetes. +- [Google GCP Project](https://cloud.google.com/appengine/docs/standard/nodejs/building-app/creating-project): Use this link to follow a tutorial to create a GCP Project if you don't have one yet. +- [Google GCP Service Account](https://cloud.google.com/iam/docs/creating-managing-service-account-keys): Use this link and follow instructions to create a GCP service account and token file. +- [Terraform](https://developer.hashicorp.com/terraform/install): Used to provision the server and cluster in Google GCP. + + +## Getting Started + +1. Clone [Rancher Quickstart](https://github.com/rancher/quickstart) to a folder using `git clone https://github.com/rancher/quickstart`. + +2. Go into the GCP folder containing the Terraform files by executing `cd quickstart/rancher/gcp`. + +3. Rename the `terraform.tfvars.example` file to `terraform.tfvars`. + +4. Edit `terraform.tfvars` and customize the following variables: + - `gcp_account_json` - GCP service account file path and file name + - `rancher_server_admin_password` - Admin password for created Rancher server. See [Setting up the Bootstrap Password](../../installation-and-upgrade/resources/bootstrap-password.md#password-requirements) for password requirements. + +5. **Optional:** Modify optional variables within `terraform.tfvars`. +See the [Quickstart Readme](https://github.com/rancher/quickstart) and the [GCP Quickstart Readme](https://github.com/rancher/quickstart/tree/master/rancher/gcp) for more information. +Suggestions include: + - `gcp_region` - Google GCP region, choose the closest instead of the default (`us-east4`) + - `gcp_zone` - Google GCP zone, choose the closest instead of the default (`us-east4-a`) + - `prefix` - Prefix for all created resources + - `machine_type` - Compute instance size used, minimum is `n1-standard-1` but `n1-standard-2` or `n1-standard-4` could be used if within budget + +6. Run `terraform init`. + +7. To initiate the creation of the environment, run `terraform apply --auto-approve`. Then wait for output similar to the following: + + ``` + Apply complete! Resources: 16 added, 0 changed, 0 destroyed. + + Outputs: + + rancher_node_ip = xx.xx.xx.xx + rancher_server_url = https://rancher.xx.xx.xx.xx.sslip.io + workload_node_ip = yy.yy.yy.yy + ``` + +8. Paste the `rancher_server_url` from the output above into the browser. Log in when prompted (default username is `admin`, use the password set in `rancher_server_admin_password`). +9. ssh to the Rancher Server using the `id_rsa` key generated in `quickstart/rancher/gcp`. + +#### Result + +Two Kubernetes clusters are deployed into your GCP account, one running Rancher Server and the other ready for experimentation deployments. Please note that while this setup is a great way to explore Rancher functionality, a production setup should follow our high availability setup guidelines. SSH keys for the VMs are auto-generated and stored in the module directory. + +### What's Next? + +Use Rancher to create a deployment. For more information, see [Creating Deployments](../deploy-workloads/deploy-workloads.md). + +## Destroying the Environment + +1. From the `quickstart/rancher/gcp` folder, execute `terraform destroy --auto-approve`. + +2. Wait for confirmation that all resources have been destroyed. diff --git a/versioned_docs/version-2.14/getting-started/quick-start-guides/deploy-rancher-manager/helm-cli.md b/versioned_docs/version-2.14/getting-started/quick-start-guides/deploy-rancher-manager/helm-cli.md new file mode 100644 index 00000000000..75c541ffe21 --- /dev/null +++ b/versioned_docs/version-2.14/getting-started/quick-start-guides/deploy-rancher-manager/helm-cli.md @@ -0,0 +1,155 @@ +--- +title: Helm CLI Quick Start +--- + + + + + +These instructions capture a quick way to set up a proof-of-concept Rancher installation. + +These instructions assume you have a Linux virtual machine that you will communicate with from your local workstation. Rancher will be installed on the Linux machine. You will need to retrieve the IP address of that machine so that you can access Rancher from your local workstation. Rancher is designed to manage Kubernetes clusters remotely, so any Kubernetes cluster that Rancher manages in the future will also need to be able to reach this IP address. + +We don't recommend installing Rancher locally because it creates a networking problem. Installing Rancher on localhost does not allow Rancher to communicate with downstream Kubernetes clusters, so on localhost you wouldn't be able to test Rancher's cluster provisioning or cluster management functionality. + +Your Linux machine can be anywhere. It could be an Amazon EC2 instance, a Digital Ocean droplet, or an Azure virtual machine, to name a few examples. Other Rancher docs often use 'node' as a generic term for all of these. One possible way to deploy a Linux machine is by setting up an Amazon EC2 instance as shown in [this tutorial](../../../how-to-guides/new-user-guides/infrastructure-setup/nodes-in-amazon-ec2.md). + +The full installation requirements are [here](../../installation-and-upgrade/installation-requirements/installation-requirements.md). + +## Install K3s on Linux + +Rancher needs to be installed on a supported Kubernetes version. To find out which versions of Kubernetes are supported for your Rancher version, refer to the [Rancher Support Matrix](https://www.suse.com/suse-rancher/support-matrix/all-supported-versions/). + +To specify the K3s (Kubernetes) version, use the INSTALL_K3S_VERSION (e.g., `INSTALL_K3S_VERSION="v1.24.10+k3s1"`) environment variable when running the K3s installation script. + +Install a K3s cluster by running this command on the Linux machine: + +``` +curl -sfL https://get.k3s.io | INSTALL_K3S_VERSION= sh -s - server --cluster-init +``` + +Using `--cluster-init` allows K3s to use embedded etcd as the datastore and has the ability to convert to an HA setup. Refer to [High Availability with Embedded DB](https://rancher.com/docs/k3s/latest/en/installation/ha-embedded/). + +Save the IP of the Linux machine. + +## Save the kubeconfig to your workstation + +The kubeconfig file is important for accessing the Kubernetes cluster. Copy the file at `/etc/rancher/k3s/k3s.yaml` from the Linux machine and save it to your local workstation in the directory `~/.kube/config`. One way to do this is by using the `scp` tool and run this command on your local machine: + + + + +``` +scp root@:/etc/rancher/k3s/k3s.yaml ~/.kube/config +``` + +In some cases it may need to make sure that your shell has the environment variable `KUBECONFIG=~/.kube/config` defined, for instance, it can be exported in your profile or rc files. + + + + +By default, "scp" is not a recognized command, so we need to install a module first. + +In Windows Powershell: + +``` +Find-Module Posh-SSH +Install-Module Posh-SSH + +## Get the remote kubeconfig file +scp root@:/etc/rancher/k3s/k3s.yaml $env:USERPROFILE\.kube\config +``` + + + + +## Edit the Rancher server URL in the kubeconfig + +In the kubeconfig file, you will need to change the value of the `server` field to `:6443`. The Kubernetes API server will be reached at port 6443, while the Rancher server will be reached at ports 80 and 443. This edit is needed so that when you run Helm or kubectl commands from your local workstation, you will be able to communicate with the Kubernetes cluster that Rancher will be installed on. + + + + +One way to open the kubeconfig file for editing is to use Vim: + +``` +vi ~/.kube/config +``` + +Press `i` to put Vim in insert mode. To save your work, press `Esc`. Then press `:wq` and press `Enter`. + + + + + +In Windows Powershell, you can use `notepad.exe` for editing the kubeconfig file: + +``` +notepad.exe $env:USERPROFILE\.kube\config +``` + +Once edited, either press `ctrl+s` or go to `File > Save` to save your work. + + + + +## Install Rancher with Helm + +Then from your local workstation, run the following commands. You will need to have [kubectl](https://kubernetes.io/docs/tasks/tools/#kubectl) and [helm](https://helm.sh/docs/intro/install/) installed. + +:::note + +To see options on how to customize the cert-manager install (including for cases where your cluster uses PodSecurityPolicies), see the [cert-manager docs](https://artifacthub.io/packages/helm/cert-manager/cert-manager#configuration). + +::: + +``` +helm repo add rancher-latest https://releases.rancher.com/server-charts/latest + +kubectl create namespace cattle-system + +kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download//cert-manager.crds.yaml + +helm repo add jetstack https://charts.jetstack.io + +helm repo update + +helm install cert-manager jetstack/cert-manager \ + --namespace cert-manager \ + --create-namespace + +# Windows Powershell +helm install cert-manager jetstack/cert-manager ` + --namespace cert-manager ` + --create-namespace +``` + +The final command to install Rancher is below. The command requires a domain name that forwards traffic to the Linux machine. For the sake of simplicity in this tutorial, you can use a fake domain name to create your proof-of-concept. An example of a fake domain name would be `.sslip.io`. + +To install a specific Rancher version, use the `--version` flag (e.g., `--version 2.6.6`). Otherwise, the latest Rancher is installed by default. Refer to [Choosing a Rancher Version](../../installation-and-upgrade/resources/choose-a-rancher-version.md). + + +See [Setting up the Bootstrap Password](../../installation-and-upgrade/resources/bootstrap-password.md#password-requirements) for password requirements. + +``` +helm install rancher rancher-latest/rancher \ + --namespace cattle-system \ + --set hostname=.sslip.io \ + --set replicas=1 \ + --set bootstrapPassword= + +# Windows Powershell +helm install rancher rancher-latest/rancher ` + --namespace cattle-system ` + --set hostname=.sslip.io ` + --set replicas=1 ` + --set bootstrapPassword= +``` + +Now if you navigate to `.sslip.io` in a web browser, you should see the Rancher UI. + +To make these instructions simple, we used a fake domain name and self-signed certificates to do this installation. Therefore, you will probably need to add a security exception to your web browser to see the Rancher UI. Note that for production installs, you would need a high-availability setup with a load balancer, a real domain name and real certificates. + +These instructions also left out the full installation requirements and other installation options. If you have any issues with these steps, refer to the full [Helm CLI installation docs.](../../installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/install-upgrade-on-a-kubernetes-cluster.md) + +To launch new Kubernetes clusters with your new Rancher server, you may need to set up cloud credentials in Rancher. For more information, see [Launching Kubernetes clusters with Rancher.](../../../how-to-guides/new-user-guides/launch-kubernetes-with-rancher/launch-kubernetes-with-rancher.md) diff --git a/versioned_docs/version-2.14/getting-started/quick-start-guides/deploy-rancher-manager/hetzner-cloud.md b/versioned_docs/version-2.14/getting-started/quick-start-guides/deploy-rancher-manager/hetzner-cloud.md new file mode 100644 index 00000000000..e5d1f5d0260 --- /dev/null +++ b/versioned_docs/version-2.14/getting-started/quick-start-guides/deploy-rancher-manager/hetzner-cloud.md @@ -0,0 +1,80 @@ +--- +title: Rancher Hetzner Cloud Quick Start Guide +description: Read this step by step Rancher Hetzner Cloud guide to quickly deploy a Rancher server with a single-node downstream Kubernetes cluster attached. +--- + + + + + +The following steps will quickly deploy a Rancher server on Hetzner Cloud in a single-node K3s Kubernetes cluster, with a single-node downstream Kubernetes cluster attached. + +:::caution + +The intent of these guides is to quickly launch a sandbox that you can use to evaluate Rancher. These guides are not intended for production environments. For comprehensive setup instructions, see [Installation](../../installation-and-upgrade/installation-and-upgrade.md). + +::: + +## Prerequisites + +:::caution + +Deploying to Hetzner Cloud will incur charges. + +::: + +- [Hetzner Cloud Account](https://www.hetzner.com): You will require an account on Hetzner as this is where the server and cluster will run. +- [Hetzner API Access Key](https://docs.hetzner.cloud/#getting-started): Use these instructions to create a Hetzner Cloud API Key if you don't have one. +- [Terraform](https://developer.hashicorp.com/terraform/install): Used to provision the server and cluster to Hetzner. + + +## Getting Started + +1. Clone [Rancher Quickstart](https://github.com/rancher/quickstart) to a folder using `git clone https://github.com/rancher/quickstart`. + +2. Go into the Hetzner folder containing the Terraform files by executing `cd quickstart/rancher/hcloud`. + +3. Rename the `terraform.tfvars.example` file to `terraform.tfvars`. + +4. Edit `terraform.tfvars` and customize the following variables: + - `hcloud_token` - Hetzner API access key + - `rancher_server_admin_password` - Admin password for created Rancher server. See [Setting up the Bootstrap Password](../../installation-and-upgrade/resources/bootstrap-password.md#password-requirements) for password requirements. + +5. **Optional:** Modify optional variables within `terraform.tfvars`. +See the [Quickstart Readme](https://github.com/rancher/quickstart) and the [Hetzner Quickstart Readme](https://github.com/rancher/quickstart/tree/master/rancher/hcloud) for more information. +Suggestions include: + + - `prefix` - Prefix for all created resources + - `instance_type` - Instance type, minimum required is `cx21` + - `hcloud_location` - Hetzner Cloud location, choose the closest instead of the default (`fsn1`) + +6. Run `terraform init`. + +7. To initiate the creation of the environment, run `terraform apply --auto-approve`. Then wait for output similar to the following: + + ``` + Apply complete! Resources: 15 added, 0 changed, 0 destroyed. + + Outputs: + + rancher_node_ip = xx.xx.xx.xx + rancher_server_url = https://rancher.xx.xx.xx.xx.sslip.io + workload_node_ip = yy.yy.yy.yy + ``` + +8. Paste the `rancher_server_url` from the output above into the browser. Log in when prompted (default username is `admin`, use the password set in `rancher_server_admin_password`). +9. ssh to the Rancher Server using the `id_rsa` key generated in `quickstart/rancher/hcloud`. + +#### Result + +Two Kubernetes clusters are deployed into your Hetzner account, one running Rancher Server and the other ready for experimentation deployments. Please note that while this setup is a great way to explore Rancher functionality, a production setup should follow our high availability setup guidelines. SSH keys for the VMs are auto-generated and stored in the module directory. + +### What's Next? + +Use Rancher to create a deployment. For more information, see [Creating Deployments](../deploy-workloads/deploy-workloads.md). + +## Destroying the Environment + +1. From the `quickstart/rancher/hcloud` folder, execute `terraform destroy --auto-approve`. + +2. Wait for confirmation that all resources have been destroyed. diff --git a/versioned_docs/version-2.14/getting-started/quick-start-guides/deploy-rancher-manager/linode.md b/versioned_docs/version-2.14/getting-started/quick-start-guides/deploy-rancher-manager/linode.md new file mode 100644 index 00000000000..f82f5f3120b --- /dev/null +++ b/versioned_docs/version-2.14/getting-started/quick-start-guides/deploy-rancher-manager/linode.md @@ -0,0 +1,82 @@ +--- +title: Rancher Linode Quick Start Guide +description: Read this step by step guide to quickly deploy a Rancher server with a single-node downstream Kubernetes cluster attached. +--- + + + + + +The following steps will quickly deploy a Rancher server on Linode in a single-node K3s Kubernetes cluster, with a single-node downstream Kubernetes cluster attached. + +:::caution + +The intent of these guides is to quickly launch a sandbox that you can use to evaluate Rancher. These guides are not intended for production environments. For comprehensive setup instructions, see [Installation](../../installation-and-upgrade/installation-and-upgrade.md). + +::: + +## Prerequisites + +:::caution + +Deploying to Linode will incur charges. + +::: + +- [Linode Account](https://www.linode.com/): The Linode account to run provision server and cluster under. +- [Linode Personal Access Token](https://techdocs.akamai.com/cloud-computing/docs/manage-personal-access-tokens): A Linode Personal Access Token to authenticate with. +- [Terraform](https://developer.hashicorp.com/terraform/install): Used to provision the server and cluster on Linode. + + +## Getting Started + +1. Clone [Rancher Quickstart](https://github.com/rancher/quickstart) to a folder using `git clone https://github.com/rancher/quickstart`. + +2. Go into the Linode folder containing the Terraform files by executing `cd quickstart/rancher/linode`. + +3. Rename the `terraform.tfvars.example` file to `terraform.tfvars`. + +4. Edit `terraform.tfvars` and customize the following variables: + - `linode_token` - The Linode Personal Access Token mentioned above. + - `rancher_server_admin_password` - Admin password for created Rancher server. See [Setting up the Bootstrap Password](../../installation-and-upgrade/resources/bootstrap-password.md#password-requirements) for password requirements. + +5. **Optional:** Modify optional variables within `terraform.tfvars`. +See the [Quickstart Readme](https://github.com/rancher/quickstart) and the [Linode Quickstart Readme](https://github.com/rancher/quickstart/tree/master/rancher/linode) for more information. Suggestions include: + - `linode_region` - The target Linode region to provision the server and cluster in. + - Default: `eu-central` + - For a complete list of regions, see the [official Region Availability page](https://www.linode.com/global-infrastructure/availability/). + - `prefix` - The prefix for all created infrastructure. + - `linode_type` - The type/plan that all infrastructure Linodes should use. + - Default: `g6-standard-2` + - For a complete list of plans, see the [official Plan Types page](https://techdocs.akamai.com/cloud-computing/docs/compute-instance-plan-types). + +6. Run `terraform init`. + +7. To initiate the creation of the environment, run `terraform apply --auto-approve`. Then wait for output similar to the following: + + ``` + Apply complete! Resources: 15 added, 0 changed, 0 destroyed. + + Outputs: + + rancher_node_ip = xx.xx.xx.xx + rancher_server_url = https://rancher.xx.xx.xx.xx.sslip.io + workload_node_ip = yy.yy.yy.yy + ``` + +8. Paste the `rancher_server_url` from the output above into the browser and log in when prompted. The default username is `admin` and the password is defined in `rancher_server_admin_password`. +9. `ssh` into the Rancher Server using the `id_rsa` key generated in `quickstart/rancher/linode`. + +#### Result + +Two Kubernetes clusters are deployed on your Linode account, one running Rancher Server and the other ready for experimentation deployments. Please note that while this setup is a great way to explore Rancher functionality, a production setup should follow our high availability setup guidelines. SSH keys for the VMs are auto-generated and stored in the module directory. + +### What's Next? + +Use Rancher to create a deployment. For more information, see [Creating Deployments](../deploy-workloads/deploy-workloads.md). + +## Destroying the Environment + +1. From the `quickstart/rancher/linode` folder, execute `terraform destroy --auto-approve`. + +2. Wait for confirmation that all resources have been destroyed. diff --git a/versioned_docs/version-2.14/getting-started/quick-start-guides/deploy-rancher-manager/outscale-qs.md b/versioned_docs/version-2.14/getting-started/quick-start-guides/deploy-rancher-manager/outscale-qs.md new file mode 100644 index 00000000000..b36e180ab93 --- /dev/null +++ b/versioned_docs/version-2.14/getting-started/quick-start-guides/deploy-rancher-manager/outscale-qs.md @@ -0,0 +1,80 @@ +--- +title: Rancher Outscale Quick Start Guide +description: Read this step by step Rancher Outscale guide to quickly deploy a Rancher server with a single-node downstream Kubernetes cluster attached. +--- + + + + + +The following steps will quickly deploy a Rancher server on Outscale in a single-node K3s Kubernetes cluster, with a single-node downstream Kubernetes cluster attached. + +:::note + +The intent of these guides is to quickly launch a sandbox that you can use to evaluate Rancher. These guides are not intended for production environments. For comprehensive setup instructions, see [Installation](../../installation-and-upgrade/installation-and-upgrade.md). + +::: + +## Prerequisites + +:::caution + +Deploying to Outscale will incur charges. + +::: + +- [Outscale Account](https://en.outscale.com/): You will require an account on Outscale as this is where the server and cluster will run. +- [Outscale Access Key](https://docs.outscale.com/en/userguide/About-Access-Keys.html): Use these instructions to create an Outscale Access Key if you don't have one. +- [Terraform](https://developer.hashicorp.com/terraform/install): Used to provision the server and cluster in Outscale. + + +## Getting Started + +1. Clone [Rancher Quickstart](https://github.com/rancher/quickstart) to a folder using `git clone https://github.com/rancher/quickstart`. + +2. Go into the Outscale folder containing the Terraform files by executing `cd quickstart/rancher/outscale`. + +3. Rename the `terraform.tfvars.example` file to `terraform.tfvars`. + +4. Edit `terraform.tfvars` and customize the following variables: + - `access_key_id` - Outscale access key + - `secret_key_id` - Outscale secret key + - `rancher_server_admin_password` - Admin password for created Rancher server. See [Setting up the Bootstrap Password](../../installation-and-upgrade/resources/bootstrap-password.md#password-requirements) for password requirements. + +5. **Optional:** Modify optional variables within `terraform.tfvars`. +See the [Quickstart Readme](https://github.com/rancher/quickstart) and the [Outscale Quickstart Readme](https://github.com/rancher/quickstart/tree/master/rancher/outscale) for more information. +Suggestions include: + - `region` - Outscale region, choose the closest instead of the default (`eu-west-2`) + - `prefix` - Prefix for all created resources + - `instance_type` - Instance type, minimum required is `tinav3.c2r4p3` + +6. Run `terraform init`. + +7. To initiate the creation of the environment, run `terraform apply --auto-approve`. Then wait for output similar to the following: + + ``` + Apply complete! Resources: 21 added, 0 changed, 0 destroyed. + + Outputs: + + rancher_node_ip = xx.xx.xx.xx + rancher_server_url = https://rancher.xx.xx.xx.xx.sslip.io + workload_node_ip = yy.yy.yy.yy + ``` + +8. Paste the `rancher_server_url` from the output above into the browser. Log in when prompted (default username is `admin`, use the password set in `rancher_server_admin_password`). +9. ssh to the Rancher Server using the `id_rsa` key generated in `quickstart/rancher/outscale`. + +#### Result + +Two Kubernetes clusters are deployed into your Outscale account, one running Rancher Server and the other ready for experimentation deployments. Please note that while this setup is a great way to explore Rancher functionality, a production setup should follow our high availability setup guidelines. SSH keys for the VMs are auto-generated and stored in the module directory. + +### What's Next? + +Use Rancher to create a deployment. For more information, see [Creating Deployments](../deploy-workloads/deploy-workloads.md). + +## Destroying the Environment + +1. From the `quickstart/rancher/outscale` folder, execute `terraform destroy --auto-approve`. + +2. Wait for confirmation that all resources have been destroyed. diff --git a/versioned_docs/version-2.14/getting-started/quick-start-guides/deploy-rancher-manager/prime.md b/versioned_docs/version-2.14/getting-started/quick-start-guides/deploy-rancher-manager/prime.md new file mode 100644 index 00000000000..5a2d182a7f0 --- /dev/null +++ b/versioned_docs/version-2.14/getting-started/quick-start-guides/deploy-rancher-manager/prime.md @@ -0,0 +1,13 @@ +--- +title: Rancher Prime +--- + + + + + +SUSE Rancher introduces Rancher Prime – an evolution of Rancher – from version v2.7. Rancher Prime is the new commercially available enterprise offering of Rancher, built on the same open source code. The Rancher project will continue to be 100% open source. Prime introduces additional value with greater security assurances, extended lifecycles, access to focused architectures and Kubernetes advisories. Rancher Prime will also offer options to get production support for innovative Rancher projects. With Rancher Prime, installation assets are hosted on a trusted registry owned and managed by Rancher. + +To get started with Rancher Prime, [go to this page](https://www.rancher.com/quick-start) and fill out the form. + +At a minimum, users are expected to have a working knowledge of Kubernetes and peripheral functions such as Permissions, Roles and RBAC. diff --git a/versioned_docs/version-2.14/getting-started/quick-start-guides/deploy-rancher-manager/vagrant.md b/versioned_docs/version-2.14/getting-started/quick-start-guides/deploy-rancher-manager/vagrant.md new file mode 100644 index 00000000000..560ec41cb6e --- /dev/null +++ b/versioned_docs/version-2.14/getting-started/quick-start-guides/deploy-rancher-manager/vagrant.md @@ -0,0 +1,56 @@ +--- +title: Rancher Vagrant Quick Start +--- + + + + + +The following steps quickly deploy a Rancher Server with a single node cluster attached. + +:::caution + +The intent of these guides is to quickly launch a sandbox that you can use to evaluate Rancher. These guides are not intended for production environments. For comprehensive setup instructions, see [Installation](../../installation-and-upgrade/installation-and-upgrade.md). + +::: + +## Prerequisites + +- [Vagrant](https://developer.hashicorp.com/vagrant): Vagrant is required as this is used to provision the machine based on the Vagrantfile. +- [Virtualbox](https://www.virtualbox.org): The virtual machines that Vagrant provisions need to be provisioned to VirtualBox. +- At least 4GB of free RAM. + +:::note + +Vagrant requires plugins to create VirtualBox VMs. Install them with the following commands: +- `vagrant plugin install vagrant-vboxmanage` +- `vagrant plugin install vagrant-vbguest` + +::: + +## Getting Started + +1. Clone [Rancher Quickstart](https://github.com/rancher/quickstart) to a folder using `git clone https://github.com/rancher/quickstart`. + +2. Go into the folder containing the Vagrantfile by executing `cd quickstart/rancher/vagrant`. + +3. **Optional:** Edit `config.yaml` to: + + - Change the number of nodes and the memory allocations, if required. (`node.count`, `node.cpus`, `node.memory`) + - Change the password of the `admin` user for logging into Rancher. (`admin_password`) + +4. To initiate the creation of the environment run, `vagrant up --provider=virtualbox`. + +5. Once provisioning finishes, go to `https://192.168.56.101` in the browser. The default user/password is `admin/adminPassword`. + +**Result:** Rancher Server and your Kubernetes cluster is installed on VirtualBox. + +### What's Next? + +Use Rancher to create a deployment. For more information, see [Creating Deployments](../deploy-workloads/deploy-workloads.md). + +## Destroying the Environment + +1. From the `quickstart/rancher/vagrant` folder execute `vagrant destroy -f`. + +2. Wait for the confirmation that all resources have been destroyed. diff --git a/versioned_docs/version-2.14/getting-started/quick-start-guides/deploy-workloads/deploy-workloads.md b/versioned_docs/version-2.14/getting-started/quick-start-guides/deploy-workloads/deploy-workloads.md new file mode 100644 index 00000000000..3a7034c05df --- /dev/null +++ b/versioned_docs/version-2.14/getting-started/quick-start-guides/deploy-workloads/deploy-workloads.md @@ -0,0 +1,12 @@ +--- +title: Deploying Workloads +--- + + + + + +These guides walk you through the deployment of an application, including how to expose the application for use outside of the cluster. + +- [Workload with Ingress](workload-ingress.md) +- [Workload with NodePort](nodeports.md) diff --git a/versioned_docs/version-2.14/getting-started/quick-start-guides/deploy-workloads/nodeports.md b/versioned_docs/version-2.14/getting-started/quick-start-guides/deploy-workloads/nodeports.md new file mode 100644 index 00000000000..5d04570718f --- /dev/null +++ b/versioned_docs/version-2.14/getting-started/quick-start-guides/deploy-workloads/nodeports.md @@ -0,0 +1,142 @@ +--- +title: Workload with NodePort Quick Start +--- + + + + + +### Prerequisite + +You have a running cluster with at least 1 node. + +### 1. Deploying a Workload + +You're ready to create your first Kubernetes [workload](https://kubernetes.io/docs/concepts/workloads/). A workload is an object that includes pods along with other files and info needed to deploy your application. + +For this workload, you'll be deploying the application Rancher Hello-World. + +1. Click **☰ > Cluster Management**. +1. From the **Clusters** page, go to the cluster where the workload should be deployed and click **Explore**. +1. Click **Workload**. +1. Click **Create**. +1. Enter a **Name** for your workload. +1. From the **Container Image** field, enter `rancher/hello-world`. This field is case-sensitive. +1. Click **Add Port**. +1. From the **Service Type** drop-down, make sure that **NodePort** is selected. + + ![As a dropdown, NodePort (On every node selected)](/img/nodeport-dropdown.png) + +1. From the **Publish the container port** field, enter port `80`. + + ![Publish the container port, 80 entered](/img/container-port-field.png) + +1. Click **Create**. + +**Result:** + +* Your workload is deployed. This process might take a few minutes to complete. +* When your workload completes deployment, it's assigned a state of **Active**. You can view this status from the project's **Workloads** page. + +
+ +### 2. Viewing Your Application + +From the **Workloads** page, click the link underneath your workload. If your deployment succeeded, your application opens. + +### Attention: Cloud-Hosted Sandboxes + +When using a cloud-hosted virtual machine, you may not have access to the port running the container. In this event, you can test Nginx in an ssh session on the local machine using `Execute Shell`. Use the port number after the `:` in the link under your workload if available, which is `31568` in this example. + +```html +gettingstarted@rancher:~$ curl http://localhost:31568 + + + + Rancher + + + + + +

Hello world!

+

My hostname is hello-world-66b4b9d88b-78bhx

+
+

k8s services found 2

+ + INGRESS_D1E1A394F61C108633C4BD37AEDDE757 tcp://10.43.203.31:80
+ + KUBERNETES tcp://10.43.0.1:443
+ +
+
+ + +
+ + +
+ + + +gettingstarted@rancher:~$ + +``` + +### Finished + +Congratulations! You have successfully deployed a workload exposed via a NodePort. + +#### What's Next? + +When you're done using your sandbox, destroy the Rancher Server and your cluster. See one of the following: + +- [Amazon AWS: Destroying the Environment](../deploy-rancher-manager/aws.md#destroying-the-environment) +- [DigitalOcean: Destroying the Environment](../deploy-rancher-manager/digitalocean.md#destroying-the-environment) +- [Vagrant: Destroying the Environment](../deploy-rancher-manager/vagrant.md#destroying-the-environment) diff --git a/versioned_docs/version-2.14/getting-started/quick-start-guides/deploy-workloads/workload-ingress.md b/versioned_docs/version-2.14/getting-started/quick-start-guides/deploy-workloads/workload-ingress.md new file mode 100644 index 00000000000..c0078fe4662 --- /dev/null +++ b/versioned_docs/version-2.14/getting-started/quick-start-guides/deploy-workloads/workload-ingress.md @@ -0,0 +1,77 @@ +--- +title: Workload with Ingress Quick Start +--- + + + + + +### Prerequisite + +You have a running cluster with at least 1 node. + +### 1. Deploying a Workload + +You're ready to create your first Kubernetes [workload](https://kubernetes.io/docs/concepts/workloads/). A workload is an object that includes pods along with other files and info needed to deploy your application. + +For this workload, you'll be deploying the application Rancher Hello-World. + +1. Click **☰ > Cluster Management**. +1. Go to the cluster that you created and click **Explore**. +1. Click **Workload**. +1. Click **Create**. +1. Click **Deployment**. +1. Enter a **Name** for your workload. +1. From the **Container Image** field, enter `rancher/hello-world`. This field is case-sensitive. +1. Click **Add Port** and `Cluster IP` for the `Service Type` and enter `80` in the **Private Container Port** field. You may leave the `Name` blank or specify any name that you wish. Adding a port enables access to the application inside and outside of the cluster. For more information, see [Services](../../../how-to-guides/new-user-guides/kubernetes-resources-setup/workloads-and-pods/workloads-and-pods.md#services). +1. Click **Create**. + +**Result:** + +* Your workload is deployed. This process might take a few minutes to complete. +* When your workload completes deployment, it's assigned a state of **Active**. You can view this status from the project's **Workloads** page. + +### 2. Expose The Application Via An Ingress + +Now that the application is up and running, it needs to be exposed so that other services can connect. + +1. Click **☰ > Cluster Management**. +1. Go to the cluster that you created and click **Explore**. + +1. Click **Service Discovery > Ingresses**. + +1. Click **Create.** + +1. When choosing **Namespace**, ensure it is the same as the one used when you created your deployment. Otherwise, your deployment will not be available when you attempt to select **Target Service**, as in Step 8 below. + +1. Enter a **Name**, such as **hello**. + +1. Specify your **Path**, such as `/hello`. + +1. In the **Target Service** field, drop down the list and choose the name that you set for your service. + +1. In the **Port** field, drop down the list and select `80`. + +1. Click **Create** at the bottom right. + +**Result:** The application is assigned a `sslip.io` address and exposed. It may take a minute or two to populate. + + +### View Your Application + +From the **Deployments** page, find the **Endpoints** column for your deployment and click on an endpoint. The endpoints available will depend on how you configured the port you added to your deployment. For endpoints where you do not see a randomly assigned port, append the path you specified when creating the ingress to the IP address. For example, if your endpoint looks like `xxx.xxx.xxx.xxx` or `https://xxx.xxx.xxx.xxx` change it to `xxx.xxx.xxx.xxx/hello` or `https://xxx.xxx.xxx.xxx/hello`. + +Your application will open in a separate window. + +#### Finished + +Congratulations! You have successfully deployed a workload exposed via an ingress. + +#### What's Next? + +When you're done using your sandbox, destroy the Rancher Server and your cluster. See one of the following: + +- [Amazon AWS: Destroying the Environment](../deploy-rancher-manager/aws.md#destroying-the-environment) +- [DigitalOcean: Destroying the Environment](../deploy-rancher-manager/digitalocean.md#destroying-the-environment) +- [Linode: Destroying the Environment](../deploy-rancher-manager/linode.md#destroying-the-environment) +- [Vagrant: Destroying the Environment](../deploy-rancher-manager/vagrant.md#destroying-the-environment) diff --git a/versioned_docs/version-2.14/getting-started/quick-start-guides/quick-start-guides.md b/versioned_docs/version-2.14/getting-started/quick-start-guides/quick-start-guides.md new file mode 100644 index 00000000000..424fe7d8802 --- /dev/null +++ b/versioned_docs/version-2.14/getting-started/quick-start-guides/quick-start-guides.md @@ -0,0 +1,21 @@ +--- +title: Rancher Deployment Quick Start Guides +--- + + + + + +:::caution + +The intent of these guides is to quickly launch a sandbox that you can use to evaluate Rancher. These guides are not intended for production environments. For comprehensive setup instructions, see [Installation](../installation-and-upgrade/installation-and-upgrade.md). + +::: + +Use this section of the docs to jump start your deployment and testing of Rancher 2.x. It contains instructions for a simple Rancher setup and some common use cases. We plan on adding more content to this section in the future. + +We have Quick Start Guides for: + +- [Deploying Rancher Server](deploy-rancher-manager/deploy-rancher-manager.md): Get started running Rancher using the method most convenient for you. + +- [Deploying Workloads](deploy-workloads/deploy-workloads.md): Deploy a simple [workload](https://kubernetes.io/docs/concepts/workloads/) and expose it, letting you access it from outside the cluster. diff --git a/versioned_docs/version-2.14/glossary.md b/versioned_docs/version-2.14/glossary.md new file mode 100644 index 00000000000..1db06477569 --- /dev/null +++ b/versioned_docs/version-2.14/glossary.md @@ -0,0 +1,17 @@ +--- +title: Glossary +--- + + + + + +This page covers Rancher-specific terminology and symbols which might be unfamiliar, or which differ between Rancher versions. + +```mdx-code-block +import Glossary, {toc as GlossaryTOC} from "/shared-files/_glossary.md" + + + +export const toc = GlossaryTOC; +``` \ No newline at end of file diff --git a/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/advanced-user-guides.md b/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/advanced-user-guides.md new file mode 100644 index 00000000000..68ffc4c7ed3 --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/advanced-user-guides.md @@ -0,0 +1,11 @@ +--- +title: Advanced User Guides +--- + + + + + +Advanced user guides are "problem-oriented" docs in which users learn how to answer questions or solve problems. The major difference between these and the new user guides is that these guides are geared toward more experienced or advanced users who have more technical needs from their documentation. These users already have an understanding of Rancher and its functions. They know what they need to accomplish; they just need additional guidance to complete some more complex task they they have encountered while working. + +It should be noted that neither new user guides nor advanced user guides provide detailed explanations or discussions (these kinds of docs belong elsewhere). How-to guides focus on the action of guiding users through repeatable, effective steps to learn new skills, master some task, or overcome some problem. \ No newline at end of file diff --git a/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/compliance-scan-guides/compliance-scan-guides.md b/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/compliance-scan-guides/compliance-scan-guides.md new file mode 100644 index 00000000000..c90922ec778 --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/compliance-scan-guides/compliance-scan-guides.md @@ -0,0 +1,16 @@ +--- +title: Compliance Scan Guides +--- + + + + + +- [Install rancher-compliance](install-rancher-compliance.md) +- [Uninstall rancher-compliance](uninstall-rancher-compliance.md) +- [Run a Scan](run-a-scan.md) +- [Run a Scan Periodically on a Schedule](run-a-scan-periodically-on-a-schedule.md) +- [View Reports](view-reports.md) +- [Enable Alerting for rancher-compliance](enable-alerting-for-rancher-compliance.md) +- [Configure Alerts for Periodic Scan on a Schedule](configure-alerts-for-periodic-scan-on-a-schedule.md) +- [Create a Custom Benchmark Version to Run](create-a-custom-compliance-version-to-run.md) diff --git a/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/compliance-scan-guides/configure-alerts-for-periodic-scan-on-a-schedule.md b/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/compliance-scan-guides/configure-alerts-for-periodic-scan-on-a-schedule.md new file mode 100644 index 00000000000..3f53f30dc9a --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/compliance-scan-guides/configure-alerts-for-periodic-scan-on-a-schedule.md @@ -0,0 +1,44 @@ +--- +title: Configure Alerts for Periodic Scan on a Schedule +--- + + + + + +It is possible to run a ClusterScan on a schedule. + +A scheduled scan can also specify if you should receive alerts when the scan completes. + +Alerts are supported only for a scan that runs on a schedule. + +The compliance application supports two types of alerts: + +- Alert on scan completion: This alert is sent out when the scan run finishes. The alert includes details including the ClusterScan's name and the ClusterScanProfile name. +- Alert on scan failure: This alert is sent out if there are some test failures in the scan run or if the scan is in a `Fail` state. + +:::note Prerequisite + +Before enabling alerts for `rancher-compliance`, make sure to install the `rancher-monitoring` application and configure the Receivers and Routes. For more information, see [this section.](../../../reference-guides/monitoring-v2-configuration/receivers.md) + +While configuring the routes for `rancher-compliance` alerts, you can specify the matching using the key-value pair `job: rancher-compliance-scan`. An example route configuration is [here.](../../../reference-guides/monitoring-v2-configuration/receivers.md#example-route-config-for-compliance-scan-alerts) + +::: + +To configure alerts for a scan that runs on a schedule, + +1. Please enable alerts on the `rancher-compliance` application. For more information, see [this page](../../../how-to-guides/advanced-user-guides/compliance-scan-guides/enable-alerting-for-rancher-compliance.md). +1. In the upper left corner, click **☰ > Cluster Management**. +1. On the **Clusters** page, go to the cluster where you want to run a Compliance scan and click **Explore**. +1. Click **compliance > Scan**. +1. Click **Create**. +1. Choose a cluster scan profile. The profile determines which CIS Benchmark version will be used and which tests will be performed. If you choose the Default profile, then the Compliance Operator will choose a profile applicable to the type of Kubernetes cluster it is installed on. +1. Choose the option **Run scan on a schedule**. +1. Enter a valid [cron schedule expression](https://en.wikipedia.org/wiki/Cron#CRON_expression) in the field **Schedule**. +1. Check the boxes next to the Alert types under **Alerting**. +1. Optional: Choose a **Retention Count**, which indicates the number of reports maintained for this recurring scan. By default this count is 3. When this retention limit is reached, older reports will get purged. +1. Click **Create**. + +**Result:** The scan runs and reschedules to run according to the cron schedule provided. Alerts are sent out when the scan finishes if routes and receiver are configured under `rancher-monitoring` application. + +A report is generated with the scan results every time the scan runs. To see the latest results, click the name of the scan that appears. diff --git a/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/compliance-scan-guides/create-a-custom-compliance-version-to-run.md b/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/compliance-scan-guides/create-a-custom-compliance-version-to-run.md new file mode 100644 index 00000000000..a15fc96a7fd --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/compliance-scan-guides/create-a-custom-compliance-version-to-run.md @@ -0,0 +1,13 @@ +--- +title: Create a Custom Compliance Version for Running a Cluster Scan +--- + + + + + +There could be some Kubernetes cluster setups that require custom configurations of the Compliance tests. For example, the path to the Kubernetes config files or certs might be different than the standard location where the upstream Compliance look for them. + +It is now possible to create a custom compliance version for running a cluster scan using the `rancher-compliance` application. + +For details, see [this page.](../../../integrations-in-rancher/compliance-scans/custom-benchmark.md) \ No newline at end of file diff --git a/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/compliance-scan-guides/enable-alerting-for-rancher-compliance.md b/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/compliance-scan-guides/enable-alerting-for-rancher-compliance.md new file mode 100644 index 00000000000..d5328a0dd0c --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/compliance-scan-guides/enable-alerting-for-rancher-compliance.md @@ -0,0 +1,24 @@ +--- +title: Enable Alerting for Rancher Compliance +--- + + + + + +Alerts can be configured to be sent out for a scan that runs on a schedule. + +:::note Prerequisite: + +Before enabling alerts for `rancher-compliance`, make sure to install the `rancher-monitoring` application and configure the Receivers and Routes. For more information, see [this section.](../../../reference-guides/monitoring-v2-configuration/receivers.md) + +While configuring the routes for `rancher-compliance` alerts, you can specify the matching using the key-value pair `job: rancher-compliance-scan`. An example route configuration is [here.](../../../reference-guides/monitoring-v2-configuration/receivers.md#example-route-config-for-compliance-scan-alerts) + +::: + +While installing or upgrading the `rancher-compliance` Helm chart, set the following flag to `true` in the `values.yaml`: + +```yaml +alerts: + enabled: true +``` \ No newline at end of file diff --git a/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/compliance-scan-guides/install-rancher-compliance.md b/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/compliance-scan-guides/install-rancher-compliance.md new file mode 100644 index 00000000000..c00eab90648 --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/compliance-scan-guides/install-rancher-compliance.md @@ -0,0 +1,15 @@ +--- +title: Install Rancher Compliance +--- + + + + + +1. In the upper left corner, click **☰ > Cluster Management**. +1. On the **Clusters** page, go to the cluster where you want to install Compliance and click **Explore**. +1. In the left navigation bar, click **Apps > Charts**. +1. Click **Compliance** +1. Click **Install**. + +**Result:** The compliance scan application is deployed on the Kubernetes cluster. diff --git a/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/compliance-scan-guides/run-a-scan-periodically-on-a-schedule.md b/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/compliance-scan-guides/run-a-scan-periodically-on-a-schedule.md new file mode 100644 index 00000000000..ed0d251592e --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/compliance-scan-guides/run-a-scan-periodically-on-a-schedule.md @@ -0,0 +1,24 @@ +--- +title: Run a Scan Periodically on a Schedule +--- + + + + + +To run a ClusterScan on a schedule, + +1. In the upper left corner, click **☰ > Cluster Management**. +1. On the **Clusters** page, go to the cluster where you want to run a Compliance scan and click **Explore**. +1. Click **Compliance > Scan**. +1. Choose a cluster scan profile. The profile determines which CIS Benchmark version will be used and which tests will be performed. If you choose the Default profile, then the Compliance Operator will choose a profile applicable to the type of Kubernetes cluster it is installed on. +1. Choose the option **Run scan on a schedule**. +1. Enter a valid cron schedule expression in the field **Schedule**. +1. Choose a **Retention** count, which indicates the number of reports maintained for this recurring scan. By default this count is 3. When this retention limit is reached, older reports will get purged. +1. Click **Create**. + +**Result:** The scan runs and reschedules to run according to the cron schedule provided. The **Next Scan** value indicates the next time this scan will run again. + +A report is generated with the scan results every time the scan runs. To see the latest results, click the name of the scan that appears. + +You can also see the previous reports by choosing the report from the **Reports** dropdown on the scan detail page. diff --git a/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/compliance-scan-guides/run-a-scan.md b/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/compliance-scan-guides/run-a-scan.md new file mode 100644 index 00000000000..5b91cdb7e52 --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/compliance-scan-guides/run-a-scan.md @@ -0,0 +1,26 @@ +--- +title: Run a Scan +--- + + + + + +When a ClusterScan custom resource is created, it launches a new compliance scan on the cluster for the chosen ClusterScanProfile. + +:::note + +There is currently a limitation of running only one compliance scan at a time for a cluster. If you create multiple ClusterScan custom resources, they will be run one after the other by the operator, and until one scan finishes, the rest of the ClusterScan custom resources will be in the "Pending" state. + +::: + +To run a scan, + +1. In the upper left corner, click **☰ > Cluster Management**. +1. On the **Clusters** page, go to the cluster where you want to run a compliance scan and click **Explore**. +1. Click **Compliance > Scan**. +1. Click **Create**. +1. Choose a cluster scan profile. The profile determines which CIS Benchmark version will be used and which tests will be performed. If you choose the Default profile, then the Compliance Operator will choose a profile applicable to the type of Kubernetes cluster it is installed on. +1. Click **Create**. + +**Result:** A report is generated with the scan results. To see the results, click the name of the scan that appears. diff --git a/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/compliance-scan-guides/uninstall-rancher-compliance.md b/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/compliance-scan-guides/uninstall-rancher-compliance.md new file mode 100644 index 00000000000..313acf79555 --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/compliance-scan-guides/uninstall-rancher-compliance.md @@ -0,0 +1,13 @@ +--- +title: Uninstall Rancher Compliance +--- + + + + + +1. From the **Cluster Dashboard,** go to the left navigation bar and click **Apps > Installed Apps**. +1. Go to the `compliance-operator-system` namespace and check the boxes next to `rancher-compliance-crd` and `rancher-compliance`. +1. Click **Delete** and confirm **Delete**. + +**Result:** The `rancher-compliance` application is uninstalled. \ No newline at end of file diff --git a/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/compliance-scan-guides/view-reports.md b/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/compliance-scan-guides/view-reports.md new file mode 100644 index 00000000000..ad042390485 --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/compliance-scan-guides/view-reports.md @@ -0,0 +1,23 @@ +--- +title: View Reports +--- + + + + + +To view the generated Compliance scan reports, + +1. In the upper left corner, click **☰ > Cluster Management**. +1. On the **Clusters** page, go to the cluster where you want to run a Compliance scan and click **Explore**. +1. Click **Compliance > Scan**. +1. The **Scans** page will show the generated reports. To see a detailed report, go to a scan report and click the name. + +One can download the report from the Scans list or from the scan detail page. + +To get the verbose version of the compliance scan results, run the following command on the cluster that was scanned. Note that the scan must be completed before this can be done. + +```console +export REPORT="scan-report-name" +kubectl get clusterscanreports.compliance.cattle.io $REPORT -o json |jq ".spec.reportJSON | fromjson" | jq -r ".actual_value_map_data" | base64 -d | gunzip | jq . +``` diff --git a/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/configure-layer-7-nginx-load-balancer.md b/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/configure-layer-7-nginx-load-balancer.md new file mode 100644 index 00000000000..7a4384b4dad --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/configure-layer-7-nginx-load-balancer.md @@ -0,0 +1,265 @@ +--- +title: Docker Install with TLS Termination at Layer-7 NGINX Load Balancer +--- + + + + + +For development and testing environments that have a special requirement to terminate TLS/SSL at a load balancer instead of your Rancher Server container, deploy Rancher and configure a load balancer to work with it conjunction. + +A layer-7 load balancer can be beneficial if you want to centralize your TLS termination in your infrastructure. Layer-7 load balancing also offers the capability for your load balancer to make decisions based on HTTP attributes such as cookies, etc. that a layer-4 load balancer is not able to concern itself with. + +This install procedure walks you through deployment of Rancher using a single container, and then provides a sample configuration for a layer-7 NGINX load balancer. + +## Requirements for OS, Docker, Hardware, and Networking + +Make sure that your node fulfills the general [installation requirements.](../../getting-started/installation-and-upgrade/installation-requirements/installation-requirements.md) + +## Installation Outline + + +## 1. Provision Linux Host + +Provision a single Linux host according to our [Requirements](../../getting-started/installation-and-upgrade/installation-requirements/installation-requirements.md) to launch your Rancher Server. + +## 2. Choose an SSL Option and Install Rancher + +For security purposes, SSL (Secure Sockets Layer) is required when using Rancher. SSL secures all Rancher network communication, like when you login or interact with a cluster. + +:::note Do you want to.. + +- Complete an Air Gap Installation? +- Record all transactions with the Rancher API? + +See [Advanced Options](#advanced-options) below before continuing. + +::: + +Choose from the following options: + +
+ Option A-Bring Your Own Certificate: Self-Signed + +If you elect to use a self-signed certificate to encrypt communication, you must install the certificate on your load balancer (which you'll do later) and your Rancher container. Run the Docker command to deploy Rancher, pointing it toward your certificate. + +:::note Prerequisites: + +Create a self-signed certificate. + +- The certificate files must be in PEM format. + +::: + +**To Install Rancher Using a Self-Signed Cert:** + +1. While running the Docker command to deploy Rancher, point Docker toward your CA certificate file. + + ``` + docker run -d --restart=unless-stopped \ + -p 80:80 -p 443:443 \ + -v /etc/your_certificate_directory/cacerts.pem:/etc/rancher/ssl/cacerts.pem \ + rancher/rancher:latest + ``` + +
+
+ Option B-Bring Your Own Certificate: Signed by Recognized CA + +If your cluster is public facing, it's best to use a certificate signed by a recognized CA. + +:::note Prerequisites: + +- The certificate files must be in PEM format. + +::: + +**To Install Rancher Using a Cert Signed by a Recognized CA:** + +If you use a certificate signed by a recognized CA, installing your certificate in the Rancher container isn't necessary. We do have to make sure there is no default CA certificate generated and stored, you can do this by passing the `--no-cacerts` parameter to the container. + +1. Enter the following command. + + ``` + docker run -d --restart=unless-stopped \ + -p 80:80 -p 443:443 \ + rancher/rancher:latest --no-cacerts + ``` + +
+ +## 3. Configure Load Balancer + +When using a load balancer in front of your Rancher container, there's no need for the container to redirect port communication from port 80 or port 443. By passing the header `X-Forwarded-Proto: https` header, this redirect is disabled. + +The load balancer or proxy has to be configured to support the following: + +- **WebSocket** connections +- **SPDY** / **HTTP/2** protocols +- Passing / setting the following headers: + + | Header | Value | Description | + |--------|-------|-------------| + | `Host` | Hostname used to reach Rancher. | To identify the server requested by the client. + | `X-Forwarded-Proto` | `https` | To identify the protocol that a client used to connect to the load balancer or proxy.

**Note:** If this header is present, `rancher/rancher` does not redirect HTTP to HTTPS. + | `X-Forwarded-Port` | Port used to reach Rancher. | To identify the protocol that client used to connect to the load balancer or proxy. + | `X-Forwarded-For` | IP of the client connection. | To identify the originating IP address of a client. +### Example NGINX configuration + +This NGINX configuration is tested on NGINX 1.14. + +:::note + +This NGINX configuration is only an example and may not suit your environment. For complete documentation, see [NGINX Load Balancing - HTTP Load Balancing](https://docs.nginx.com/nginx/admin-guide/load-balancer/http-load-balancer/). + +::: + +- Replace `rancher-server` with the IP address or hostname of the node running the Rancher container. +- Replace both occurrences of `FQDN` to the DNS name for Rancher. +- Replace `/certs/fullchain.pem` and `/certs/privkey.pem` to the location of the server certificate and the server certificate key respectively. + +``` +worker_processes 4; +worker_rlimit_nofile 40000; + +events { + worker_connections 8192; +} + +http { + upstream rancher { + server rancher-server:80; + } + + map $http_upgrade $connection_upgrade { + default Upgrade; + '' close; + } + + server { + listen 443 ssl http2; + server_name FQDN; + ssl_certificate /certs/fullchain.pem; + ssl_certificate_key /certs/privkey.pem; + + location / { + proxy_set_header Host $host; + proxy_set_header X-Forwarded-Proto $scheme; + proxy_set_header X-Forwarded-Port $server_port; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + proxy_pass http://rancher; + proxy_http_version 1.1; + proxy_set_header Upgrade $http_upgrade; + proxy_set_header Connection $connection_upgrade; + # This allows the ability for the execute shell window to remain open for up to 15 minutes. Without this parameter, the default is 1 minute and will automatically close. + proxy_read_timeout 900s; + proxy_buffering off; + } + } + + server { + listen 80; + server_name FQDN; + return 301 https://$server_name$request_uri; + } +} +``` + +
+ +## What's Next? + +- **Recommended:** Review Single Node [Backup](../../how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/back-up-docker-installed-rancher.md) and [Restore](../../how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/restore-docker-installed-rancher.md). Although you don't have any data you need to back up right now, we recommend creating backups after regular Rancher use. +- Create a Kubernetes cluster: [Provisioning Kubernetes Clusters](../new-user-guides/kubernetes-clusters-in-rancher-setup/kubernetes-clusters-in-rancher-setup.md). + +
+ +## FAQ and Troubleshooting + +For help troubleshooting certificates, see [this section.](../../getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/certificate-troubleshooting.md) + +## Advanced Options + +### API Auditing + +If you want to record all transactions with the Rancher API, enable the [API Auditing](enable-api-audit-log.md) feature by adding the flags below into your install command. + + -e AUDIT_LEVEL=1 \ + -e AUDIT_LOG_ENABLED=true \ + -e AUDIT_LOG_PATH=/var/log/auditlog/rancher-api-audit.log \ + -e AUDIT_LOG_MAXAGE=20 \ + -e AUDIT_LOG_MAXBACKUP=20 \ + -e AUDIT_LOG_MAXSIZE=100 \ + +### Air Gap + +If you are visiting this page to complete an [Air Gap Installation](../../getting-started/installation-and-upgrade/other-installation-methods/air-gapped-helm-cli-install/air-gapped-helm-cli-install.md), you must pre-pend your private registry URL to the server tag when running the installation command in the option that you choose. Add `` with your private registry URL in front of `rancher/rancher:latest`. + +**Example:** + + /rancher/rancher:latest + +### Persistent Data + +Rancher uses etcd as a datastore. When Rancher is installed with Docker, the embedded etcd is being used. The persistent data is at the following path in the container: `/var/lib/rancher`. + +You can bind mount a host volume to this location to preserve data on the host it is running on: + +``` +docker run -d --restart=unless-stopped \ + -p 80:80 -p 443:443 \ + -v /opt/rancher:/var/lib/rancher \ + --privileged \ + rancher/rancher:latest +``` + +This operation requires [privileged access](../../getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/rancher-on-a-single-node-with-docker.md#privileged-access-for-rancher). + +This layer 7 NGINX configuration is tested on NGINX version 1.13 (mainline) and 1.14 (stable). + +:::note + +This NGINX configuration is only an example and may not suit your environment. For complete documentation, see [NGINX Load Balancing - TCP and UDP Load Balancer](https://docs.nginx.com/nginx/admin-guide/load-balancer/tcp-udp-load-balancer/). + +::: + +``` +upstream rancher { + server rancher-server:80; +} + +map $http_upgrade $connection_upgrade { + default Upgrade; + '' close; +} + +server { + listen 443 ssl http2; + server_name rancher.yourdomain.com; + ssl_certificate /etc/your_certificate_directory/fullchain.pem; + ssl_certificate_key /etc/your_certificate_directory/privkey.pem; + + location / { + proxy_set_header Host $host; + proxy_set_header X-Forwarded-Proto $scheme; + proxy_set_header X-Forwarded-Port $server_port; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + proxy_pass http://rancher; + proxy_http_version 1.1; + proxy_set_header Upgrade $http_upgrade; + proxy_set_header Connection $connection_upgrade; + # This allows the ability for the execute shell window to remain open for up to 15 minutes. Without this parameter, the default is 1 minute and will automatically close. + proxy_read_timeout 900s; + proxy_buffering off; + } +} + +server { + listen 80; + server_name rancher.yourdomain.com; + return 301 https://$server_name$request_uri; +} +``` + +
+ diff --git a/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/configure-oidc-provider.md b/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/configure-oidc-provider.md new file mode 100644 index 00000000000..9f85fd52168 --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/configure-oidc-provider.md @@ -0,0 +1,138 @@ +--- +title: Configure Rancher as an OIDC provider +--- + + + + + +Rancher can function as a standard OpenID Connect (OIDC) provider, allowing external applications to use Rancher for authentication. +This can be used for enabling single sign-on (SSO) across Rancher Prime components. For example, see the [documentation](https://documentation.suse.com/cloudnative/suse-observability/latest/en/setup/security/authentication/oidc.html) for configuring the OIDC provider for SUSE Observability. + +The OIDC provider can be enabled with the `oidc-provider` feature flag. When this flag is on the following endpoints are available: + +- `https://{rancher-url}/oidc/authorize`: This endpoint initiates the authentication flow. If a user is already logged into Rancher, it returns an authorization code. Otherwise, it redirects the user to the Rancher login page. Authorization codes and related request information are securely stored in session secrets. Codes are single-use and expire after 10 minutes. + +- `https://{rancher-url}/oidc/token`: This endpoint exchanges an authorization code for an `id_token`, `access_token`, and `refresh_token`. + +- `https://{rancher-url}/oidc/.well-known/openid-configuration`: This endpoint returns a JSON document containing the OIDC provider's configuration, including endpoint URLs, supported scopes, claims, and other relevant details. + +- `https://{rancher-url}/oidc/userinfo`: This endpoint provides information about the authenticated user. + +The OIDC provider supports the OIDC Authentication Code Flow with PKCE. + +## Configure OIDCClient + +An `OIDCClient` represents an external application that will be authenticating against Rancher. + +### Programmatically + +Create an `OIDCClient`: + +```yaml +apiVersion: management.cattle.io/v3 +kind: OIDCClient +metadata: + name: oidc-client-test +spec: + tokenExpirationSeconds: 600 # expiration of the id_token and access_token + refreshTokenExpirationSeconds: 3600 # expiration of the refresh_token + redirectURIs: + - "https://myredirecturl.com" # replace with your redirect url +``` +Rancher automatically generates a client ID and client secret for each `OIDCClient`. +Once the resource is created, Rancher populates the status field with the client id: + +```yaml +apiVersion: management.cattle.io/v3 +kind: OIDCClient +metadata: + name: oidc-client-test +spec: + tokenExpirationSeconds: 600 # expiration of the id_token and access_token + refreshTokenExpirationSeconds: 3600 # expiration of the refresh_token + redirectURIs: + - "https://myredirecturl.com" # replace with your redirect url +status: + clientID: client-xxx + clientSecrets: + client-secret-1: + createdAt: "xxx" + lastFiveCharacters: xxx +``` + +Rancher automatically generates a Kubernetes `Secret` in the `cattle-oidc-client-secrets` namespace for each `OIDCClient` resource. The Secret's name matches the `OIDCClient` client ID. +Initially, the `Secret` contains a single client secret. + +To retrieve the client secret: + +``` +kubectl get secret client-xxx -n cattle-oidc-client-secrets -o jsonpath="{.data.client-secret-1}" | base64 -d +``` + +Output: + +``` +secret-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx +``` + +You can now use this client ID and client secret in your OIDC client application. + +#### Managing Client Secrets + +You can manage multiple client secrets per `OIDCClient`. Use annotations on the `OIDCClient` resource to perform secret operations: + +- Creation: Adding the `cattle.io/oidc-client-secret-create: true` annotation triggers the creation of a new client secret. +- Removal: Adding the `cattle.io/oidc-client-secret-remove:client-secret-1` annotation removes the specified client secrets. +- Regeneration: Adding the `cattle.io/oidc-client-secret-regenerate:client-secret-1` annotation regenerates the specified client secrets. + +### Rancher UI + +Create an OIDCClient: + +1. In the top left corner, click **☰ > Users & Authentication**. +1. In the left navigation menu, click **OIDC Apps**. +1. Click **Add Application**. Fill out the **Create OIDC App** form. +1. Click **Add Application**. + +#### Managing Client Secrets + +In the OIDC App page: + +- Creation: Click **Add new secret**. +- Removal: Click **⋮ > Delete** +- Regeneration: Click **⋮ > Regenerate** + +## Signing key + +A default key pair for signing the `id_token`, `access_token`, and `refresh_token` tokens is created by Rancher in a `Secret` called `oidc-signing-key` in the `cattle-system` namespace. Only one key will be used for signing, but multiple public keys can be returned in the jwks endpoint in order to avoid disruption when doing a key rotation. + +### Rotation without disruption + +In order to create a new key pair for signing you need to manually create a new keypair and add it to the `oidc-signing-key` `Secret` + +Example: + +```yaml +apiVersion: v1 +kind: Secret +metadata: + name: oidc-signing-key +type: Opaque +data: + key2.pem: + key1.pub: + key2.pub: +``` + +Rancher will sign tokens using `key2.pem`, while the JWKS endpoint will serve both `key1.pub` and `key2.pub`. This ensures a smooth +key rotation from `key1` to `key2` without disrupting existing token verification. Note that only one private key (.pem) can be stored in the +secret at a time, and each key pair must share the same base name, differing only by their suffix: .pem for the private key and .pub for the public key. + +### Rotation with disruption + +Removing the `oidc-signing-key` `Secret` will cause Rancher to regenerate the signing key on the next restart. + +:::warning +This will invalidate all previously issued `id_token`, `access_token`, and `refresh_token` tokens making them unusable. +::: diff --git a/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/enable-api-audit-log-in-downstream-clusters.md b/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/enable-api-audit-log-in-downstream-clusters.md new file mode 100644 index 00000000000..79408d319b4 --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/enable-api-audit-log-in-downstream-clusters.md @@ -0,0 +1,204 @@ +--- +title: Enabling the API Audit Log in Downstream Clusters +--- + + + + + +Kubernetes auditing provides a security-relevant chronological set of records about a cluster. Kube-apiserver performs auditing. Requests generate an event at each stage of its execution, which is then preprocessed according to a certain policy and written to a backend. The policy determines what’s recorded and the backend persists the records. + +You might want to configure the audit log as part of compliance with the Center for Internet Security (CIS) Kubernetes Benchmark controls. + +For configuration details, refer to the [official Kubernetes documentation](https://kubernetes.io/docs/tasks/debug/debug-cluster/audit/). + + + + + +### Method 1 (Recommended): Set `audit-policy-file` in `machineGlobalConfig` or `machineSelectorConfig` + +You can set `audit-policy-file` in the configuration file using either `machineGlobalConfig` or `machineSelectorConfig`. + +When using `machineGlobalConfig`, Rancher delivers the file to the path `/var/lib/rancher/rke2/etc/config-files/audit-policy-file` on **all nodes** (both control plane and worker nodes), and sets the proper options in the RKE2 server. This may cause unwanted worker node reconciliation when the audit policy is modified. + +To avoid worker node reconciliation, use `machineSelectorConfig` with a label selector to target only control plane nodes. This ensures that the audit policy file is only delivered to control plane nodes. + +Example using `machineGlobalConfig`: +```yaml +apiVersion: provisioning.cattle.io/v1 +kind: Cluster +spec: + rkeConfig: + machineGlobalConfig: + audit-policy-file: | + apiVersion: audit.k8s.io/v1 + kind: Policy + rules: + - level: RequestResponse + resources: + - group: "" + resources: + - pods +``` + +Example using `machineSelectorConfig` (recommended to avoid worker node reconciliation): +```yaml +apiVersion: provisioning.cattle.io/v1 +kind: Cluster +spec: + rkeConfig: + machineSelectorConfig: + - config: + audit-policy-file: | + apiVersion: audit.k8s.io/v1 + kind: Policy + rules: + - level: RequestResponse + resources: + - group: "" + resources: + - pods + machineLabelSelector: + matchLabels: + rke.cattle.io/control-plane-role: 'true' +``` + +### Method 2: Use the Directives, `machineSelectorFiles` and `machineGlobalConfig` + +:::note + +This feature is available in Rancher v2.7.2 and later. + +::: + +You can use `machineSelectorFiles` to deliver the audit policy file to the control plane nodes, and `machineGlobalConfig` to set the options on kube-apiserver. + +As a prerequisite, you must create a [secret](../new-user-guides/kubernetes-resources-setup/secrets.md) or [configmap](../new-user-guides/kubernetes-resources-setup/configmaps.md) to be the source of the audit policy. + +The secret or configmap must meet the following requirements: + +1. It must be in the `fleet-default` namespace where the Cluster object exists. +2. It must have the annotation `rke.cattle.io/object-authorized-for-clusters: ,` which permits the target clusters to use it. + +:::tip + +Rancher Dashboard provides an easy-to-use form for creating the secret or configmap. + +::: + +Example: + +```yaml +apiVersion: v1 +data: + audit-policy: >- + IyBMb2cgYWxsIHJlcXVlc3RzIGF0IHRoZSBNZXRhZGF0YSBsZXZlbC4KYXBpVmVyc2lvbjogYXVkaXQuazhzLmlvL3YxCmtpbmQ6IFBvbGljeQpydWxlczoKLSBsZXZlbDogTWV0YWRhdGE= +kind: Secret +metadata: + annotations: + rke.cattle.io/object-authorized-for-clusters: cluster1 + name: + namespace: fleet-default +``` + +Enable and configure the audit log by editing the cluster in YAML, and utilizing the `machineSelectorFiles` and `machineGlobalConfig` directives. + +Example: + +```yaml +apiVersion: provisioning.cattle.io/v1 +kind: Cluster +spec: + rkeConfig: + machineGlobalConfig: + kube-apiserver-arg: + - audit-policy-file=/dev-audit-policy.yaml + - audit-log-path=/dev-audit.logs + machineSelectorFiles: + - fileSources: + - configMap: + name: '' + secret: + items: + - key: audit-policy + path: /dev-audit-policy.yaml + name: dev-audit-policy + machineLabelSelector: + matchLabels: + rke.cattle.io/control-plane-role: 'true' +``` + +For more information about cluster configuration, refer to the [RKE2 cluster configuration reference](../../reference-guides/cluster-configuration/rancher-server-configuration/rke2-cluster-configuration.md) pages. + + + + + +:::note + +This feature is available in Rancher v2.7.2 and later. + +::: + +You can use `machineSelectorFiles` to deliver the audit policy file to the control plane nodes, and `machineGlobalConfig` to set the options on kube-apiserver. + +As a prerequisite, you must create a [secret](../new-user-guides/kubernetes-resources-setup/secrets.md) or [configmap](../new-user-guides/kubernetes-resources-setup/configmaps.md) to be the source of the audit policy. + +The secret or configmap must meet the following requirements: + +1. It must be in the `fleet-default` namespace where the Cluster object exists. +2. It must have the annotation `rke.cattle.io/object-authorized-for-clusters: ,` which permits the target clusters to use it. + +:::tip + +Rancher Dashboard provides an easy-to-use form for creating the [secret](../new-user-guides/kubernetes-resources-setup/secrets.md) or [configmap](../new-user-guides/kubernetes-resources-setup/configmaps.md). + +::: + +Example: + +```yaml +apiVersion: v1 +data: + audit-policy: >- + IyBMb2cgYWxsIHJlcXVlc3RzIGF0IHRoZSBNZXRhZGF0YSBsZXZlbC4KYXBpVmVyc2lvbjogYXVkaXQuazhzLmlvL3YxCmtpbmQ6IFBvbGljeQpydWxlczoKLSBsZXZlbDogTWV0YWRhdGE= +kind: Secret +metadata: + annotations: + rke.cattle.io/object-authorized-for-clusters: cluster1 + name: + namespace: fleet-default +``` + +Enable and configure the audit log by editing the cluster in YAML, and utilizing the `machineSelectorFiles` and `machineGlobalConfig` directives. + +Example: + +```yaml +apiVersion: provisioning.cattle.io/v1 +kind: Cluster +spec: + rkeConfig: + machineGlobalConfig: + kube-apiserver-arg: + - audit-policy-file=/dev-audit-policy.yaml + - audit-log-path=/dev-audit.logs + machineSelectorFiles: + - fileSources: + - configMap: + name: '' + secret: + items: + - key: audit-policy + path: /dev-audit-policy.yaml + name: dev-audit-policy + machineLabelSelector: + matchLabels: + rke.cattle.io/control-plane-role: 'true' +``` + +For more information about cluster configuration, refer to the [K3s cluster configuration reference](../../reference-guides/cluster-configuration/rancher-server-configuration/k3s-cluster-configuration.md) pages. + + + diff --git a/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/enable-api-audit-log.md b/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/enable-api-audit-log.md new file mode 100644 index 00000000000..36e9a7f5ad3 --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/enable-api-audit-log.md @@ -0,0 +1,685 @@ +--- +title: Enabling the API Audit Log to Record System Events +--- + + + + + +You can enable the API audit log to record the sequence of system events initiated by individual users. You can know what happened, when it happened, who initiated it, and what cluster it affected. When you enable this feature, all requests to the Rancher API and all responses from it are written to a log. + +You can enable API Auditing during Rancher installation or upgrade. + +## Enabling API Audit Log + +The Audit Log is enabled and configured by passing environment variables to the Rancher server container. See the following to enable on your installation. + +- [Docker Install](../../reference-guides/single-node-rancher-in-docker/advanced-options.md#api-audit-log) + +- [Kubernetes Install](../../getting-started/installation-and-upgrade/installation-references/helm-chart-options.md#api-audit-log) + +## API Audit Log Options + +The usage below defines rules about what the audit log should record and what data it should include: + +| Parameter | Description | +| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `AUDIT_LOG_ENABLED` | `false` - Disables the audit log (default setting).
`true` - Enables the audit log. | +| `AUDIT_LEVEL` | `0` - Log request and response metadata (default setting).
`1` - Log request and response headers.
`2` - Log request body.
`3` - Log response body. Each log level is cumulative and each subsequent level logs the previous level data. Each log transaction for a request/response pair uses the same `auditID` value.

See [Audit Level Logging](#audit-log-levels) for a table that displays what each setting logs. | +| `AUDIT_LOG_PATH` | Log path for Rancher Server API. Default path is `/var/log/auditlog/rancher-api-audit.log`. You can mount the log directory to host.

Usage Example: `AUDIT_LOG_PATH=/my/custom/path/`
| +| `AUDIT_LOG_MAXAGE` | Defined the maximum number of days to retain old audit log files. Default is 10 days. | +| `AUDIT_LOG_MAXBACKUP` | Defines the maximum number of audit log files to retain. Default is 10. | +| `AUDIT_LOG_MAXSIZE` | Defines the maximum size in megabytes of the audit log file before it gets rotated. Default size is 100M. | + +
+ +### Audit Log Levels + +The following table displays what parts of API transactions are logged for each [`AUDIT_LEVEL`](#api-audit-log-options) setting. + + +| `AUDIT_LEVEL` Setting | Metadata | Request Headers | Response Headers | Request Body | Response Body | +|--------------------------------|----------------|---------------------------|-----------------------------|----------------------|-----------------------| +| 0 | ✓ | +| 1 | ✓ | ✓ | ✓ +| 2 | ✓ | ✓ | ✓ | ✓ +| 3 | ✓ | ✓ | ✓ | ✓ | ✓ + +## Audit Log policies + +Audit log policies allow end users to configure redactions using `AuditPolicy` cluster-scoped CRs in addition to the [default redactions and filters](#default-redactions--filters). + +All configured audit log policies are additive. + +Redaction policies for headers utilize a regular expression (regex) engine to redact headers, while a JSONPath engine is used to redact request/response headers. + +The JSONPath engine does not support the script or filter expressions. For getting started with JSONPath expressions, a good resource to consult is [Stafan Goessner's article on JSONPath](https://goessner.net/articles/JsonPath/). + +The structure of an audit policy CR is as follows: + +```yaml +apiVersion: auditlog.cattle.io/v1 +kind: AuditPolicy +spec: + enabled : true # true/false + # list of API request filters + filters: + - action: allow # allow/deny + # would allow logs sent to "/foo/some/endpoint" but not "/foo" or "/foobar". + requestURI: "/foo/.*" + # additionalRedactions allows configuration of redactions on headers using `jsonpath` expressions + additionalRedactions: + # redacts headers based on regex expressions + - headers: + - "Cache.*" + # paths redacts information from request and response bodies based on json path expressions + paths: + - "$.gitCommit" + verbosity: + level : 0 # matches the levels in the above audit log table + # request allows fine-grained control over which request data + # gets included. This overrides the behaviour of the generic verbosity.level + request: + headers : true # true/false + body : true # true/false + # response allows fine-grained control over which response data + # gets included. This overrides the behaviour of the generic verbosity.level + response: + headers : true # true/false + body: true # true/false +``` + +### Examples + +The following example shows only logging requests containing `login` in the request path to the audit log path: + +```yaml +apiVersion: auditlog.cattle.io/v1 +kind: AuditPolicy +metadata: + name: filters +spec: + filters: + - action: deny + requestUri: ".*" + - action: allow + requestUri: ".*login.*" +``` + +The following example shows how to redact specific fields containing `gitCommint` in request/response bodies: + +```yaml +apiVersion: auditlog.cattle.io/v1 +kind: AuditPolicy +metadata: + name: redactions +spec: + additionalRedactions: + - paths: + - "$.gitCommit" +``` + +### Default redactions & filters + +The audit log controller comes with default built-in redactions for common sensitive information. + +#### Redacted headers + +Generic headers: +- `Cookie` +- `Set-Cookie` +- `X-Api-Set-Cookie-Header` +- `Authorization` +- `X-Api-Tunnel-Params` +- `X-Api-Tunnel-Token` +- `X-Api-Auth-Header` +- `X-Amz-Security-Token` + + +#### Redacted body fields + +Generic body fields: + +- `credentials` +- `applicationSecret` +- `oauthCredential` +- `serviceAccountCredential` +- `spKey` +- `spCert` +- `certificate` +- `privateKey` +- `secretsEncryptionConfig` +- `manifestUrl` +- `insecureWindowsNodeCommand` +- `insecureNodeCommand` +- `insecureCommand` +- `command` +- `nodeCommand` +- `windowsNodeCommand` +- `clientRandom` + +Generic body regex redactor: +- `".*([pP]assword|[Kk]ube[Cc]onfig|[Tt]oken).*"` + +#### Cluster Driver + +By default, any API request with fields tied to cluster drivers will have any non `public*` or `optional*` fields redacted by the audit log controller. + +#### Redacted URIs + +Any endpoint containing `secrets` or `configmaps` will have relevant fields stripped from both the request and response bodies. Additionally, any endpoint containing `/v3/imports/*` will have its URI redacted. + + +## Viewing API Audit Logs + +### Docker Install + +Share the `AUDIT_LOG_PATH` directory (Default: `/var/log/auditlog`) with the host system. The log can be parsed by standard CLI tools or forwarded on to a log collection tool like Fluentd, Filebeat, Logstash, etc. + +### Kubernetes Install + +Enabling the API Audit Log with the Helm chart install will create a `rancher-audit-log` sidecar container in the Rancher pod. This container will stream the log to standard output (stdout). You can view the log as you would any container log. + +The `rancher-audit-log` container is part of the `rancher` pod in the `cattle-system` namespace. + +#### CLI + +```bash +kubectl -n cattle-system logs -f rancher-84d886bdbb-s4s69 rancher-audit-log +``` + +#### Shipping the Audit Log + +You can enable Rancher's built in log collection and shipping for the cluster to ship the audit and other services logs to a supported collection endpoint. See [Rancher Tools - Logging](../../integrations-in-rancher/logging/logging.md) for details. + +## Audit Log Samples + +After you enable auditing, each API request or response is logged by Rancher in the form of JSON. Each of the following code samples provide examples of how to identify each API transaction. + +### Metadata Level + +If you set your `AUDIT_LEVEL` to `0`, Rancher logs the metadata header for every API request, but neither the body nor the request and response headers. The metadata provides basic information about the API transaction, such as the transaction ID, the initiator of the transaction, the time it occurred, etc. + +```json +{ + "auditID": "40bd4e40-875b-4020-933e-4c4f4c4db366", + "requestURI": "/v3/schemas", + "user": { + "name": "user-6j5s6", + "group": [ + "system:authenticated", + "system:cattle:authenticated" + ], + "extra": { + "principalid": [ + "local://user-6j5s6" + ], + "requesthost": [ + "localhost:8443" + ], + "requesttokenid": [ + "token-zs42h" + ], + "username": [ + "admin" + ] + } + }, + "method": "GET", + "remoteAddr": "127.0.0.1:58652", + "responseCode": 200, + "requestTimestamp": "2025-06-30T11:13:25-04:00", + "responseTimestamp": "2025-06-30T11:13:25-04:00" +} +``` + +### Metadata and headers level + +If you set your `AUDIT_LEVEL` to `1`, Rancher logs the metadata and the request and response headers for every API request. + +```json +{ + "auditID": "f8c83dc6-a080-4e2e-ab43-552bddf01716", + "requestURI": "/v1/apps.deployments?page=1&pagesize=100&sort=metadata.name&filter=metadata.namespace!=p-npsl5&filter=metadata.namespace!=p-nzp6c&filter=metadata.namespace!=cattle-fleet-clusters-system&filter=metadata.namespace!=cattle-fleet-system&filter=metadata.namespace!=cattle-global-data&filter=metadata.namespace!=cattle-impersonation-system&filter=metadata.namespace!=cattle-provisioning-capi-system&filter=metadata.namespace!=cattle-system&filter=metadata.namespace!=cattle-ui-plugin-system&filter=metadata.namespace!=cluster-fleet-local-local-1a3d67d0a899&filter=metadata.namespace!=fleet-default&filter=metadata.namespace!=fleet-local&filter=metadata.namespace!=kube-node-lease&filter=metadata.namespace!=kube-public&filter=metadata.namespace!=kube-system&exclude=metadata.managedFields", + "user": { + "name": "user-6j5s6", + "group": [ + "system:authenticated", + "system:cattle:authenticated" + ], + "extra": { + "principalid": [ + "local://user-6j5s6" + ], + "requesthost": [ + "localhost:8443" + ], + "requesttokenid": [ + "token-zs42h" + ], + "username": [ + "admin" + ] + } + }, + "method": "GET", + "remoteAddr": "127.0.0.1:58833", + "responseCode": 200, + "requestTimestamp": "2025-06-30T11:17:04-04:00", + "responseTimestamp": "2025-06-30T11:17:04-04:00", + "requestHeader": { + "Accept": [ + "application/json" + ], + "Accept-Encoding": [ + "gzip, deflate, br, zstd" + ], + "Accept-Language": [ + "en-US,en;q=0.5" + ], + "Connection": [ + "keep-alive" + ], + "Cookie": [ + "[redacted]" + ], + "Referer": [ + "https://localhost:8443/dashboard/c/local/explorer/apps.deployment" + ], + "Sec-Fetch-Dest": [ + "empty" + ], + "Sec-Fetch-Mode": [ + "cors" + ], + "Sec-Fetch-Site": [ + "same-origin" + ], + "User-Agent": [ + "Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:140.0) Gecko/20100101 Firefox/140.0" + ], + "X-Api-Csrf": [ + "fccc690cab7b0c169b3fc6527edadef3" + ] + }, + "responseHeader": { + "Cache-Control": [ + "no-cache, no-store, must-revalidate" + ], + "Content-Encoding": [ + "gzip" + ], + "Content-Type": [ + "application/json" + ], + "Expires": [ + "Wed 24 Feb 1982 18:42:00 GMT" + ], + "X-Api-Cattle-Auth": [ + "true" + ], + "X-Api-Schemas": [ + "https://localhost:8443/v1/schemas" + ], + "X-Content-Type-Options": [ + "nosniff" + ] + } +} +``` + +### Metadata, headers and Request Body Level + +If you set your `AUDIT_LEVEL` to `2`, Rancher logs the metadata, the request and response headers and the request body for every API request. + +The code sample below depicts an API request, with both its metadata, headers and request body. + +```json +{ + "auditID": "d1088a09-2a13-4450-970e-0d44bd2c49ee", + "requestURI": "/v3/projects", + "user": { + "name": "user-6j5s6", + "group": [ + "system:authenticated", + "system:cattle:authenticated" + ], + "extra": { + "principalid": [ + "local://user-6j5s6" + ], + "requesthost": [ + "localhost:8443" + ], + "requesttokenid": [ + "token-zs42h" + ], + "username": [ + "admin" + ] + } + }, + "method": "POST", + "remoteAddr": "127.0.0.1:49966", + "responseCode": 201, + "requestTimestamp": "2025-06-30T12:32:13-04:00", + "responseTimestamp": "2025-06-30T12:32:13-04:00", + "requestHeader": { + "Accept": [ + "application/json" + ], + "Accept-Encoding": [ + "gzip, deflate, br, zstd" + ], + "Accept-Language": [ + "en-US,en;q=0.5" + ], + "Connection": [ + "keep-alive" + ], + "Content-Length": [ + "214" + ], + "Content-Type": [ + "application/json" + ], + "Cookie": [ + "[redacted]" + ], + "Impersonate-Extra-Principalid": [ + "local://user-6j5s6" + ], + "Impersonate-Extra-Requesthost": [ + "localhost:8443" + ], + "Impersonate-Extra-Requesttokenid": [ + "token-zs42h" + ], + "Impersonate-Extra-Username": [ + "admin" + ], + "Impersonate-Group": [ + "system:authenticated", + "system:cattle:authenticated" + ], + "Impersonate-User": [ + "user-6j5s6" + ], + "Origin": [ + "https://localhost:8443" + ], + "Priority": [ + "u=0" + ], + "Referer": [ + "https://localhost:8443/dashboard/c/local/explorer/management.cattle.io.project/create" + ], + "Sec-Fetch-Dest": [ + "empty" + ], + "Sec-Fetch-Mode": [ + "cors" + ], + "Sec-Fetch-Site": [ + "same-origin" + ], + "User-Agent": [ + "Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:140.0) Gecko/20100101 Firefox/140.0" + ], + "X-Api-Csrf": [ + "fccc690cab7b0c169b3fc6527edadef3" + ] + }, + "responseHeader": { + "Cache-Control": [ + "no-cache, no-store, must-revalidate" + ], + "Content-Encoding": [ + "gzip" + ], + "Content-Type": [ + "application/json" + ], + "Expires": [ + "Wed 24 Feb 1982 18:42:00 GMT" + ], + "X-Api-Cattle-Auth": [ + "true" + ], + "X-Api-Schemas": [ + "https://localhost:8443/v3/project/schemas" + ], + "X-Content-Type-Options": [ + "nosniff" + ] + }, + "requestBody": { + "annotations": {}, + "clusterId": "local", + "containerDefaultResourceLimit": {}, + "creatorId": "local://user-6j5s6", + "labels": {}, + "name": "example-project", + "namespaceDefaultResourceQuota": {}, + "resourceQuota": {}, + "type": "project" + } +} +``` + +### Metadata, Headers, Request Body and Response Body Level + +If you set your `AUDIT_LEVEL` to `3`, Rancher logs the metadata, request and response headers and request body and response. + +The code sample below depicts an example of an API request with that information logged. + +```json +{ + "auditID": "a9549a5b-4351-4bd5-adcd-12f7ec667a6b", + "requestURI": "/v3/projects", + "user": { + "name": "user-6j5s6", + "group": [ + "system:authenticated", + "system:cattle:authenticated" + ], + "extra": { + "principalid": [ + "local://user-6j5s6" + ], + "requesthost": [ + "localhost:8443" + ], + "requesttokenid": [ + "token-zs42h" + ], + "username": [ + "admin" + ] + } + }, + "method": "POST", + "remoteAddr": "127.0.0.1:50454", + "responseCode": 201, + "requestTimestamp": "2025-06-30T12:42:24-04:00", + "responseTimestamp": "2025-06-30T12:42:24-04:00", + "requestHeader": { + "Accept": [ + "application/json" + ], + "Accept-Encoding": [ + "gzip, deflate, br, zstd" + ], + "Accept-Language": [ + "en-US,en;q=0.5" + ], + "Connection": [ + "keep-alive" + ], + "Content-Length": [ + "214" + ], + "Content-Type": [ + "application/json" + ], + "Cookie": [ + "[redacted]" + ], + "Impersonate-Extra-Principalid": [ + "local://user-6j5s6" + ], + "Impersonate-Extra-Requesthost": [ + "localhost:8443" + ], + "Impersonate-Extra-Requesttokenid": [ + "token-zs42h" + ], + "Impersonate-Extra-Username": [ + "admin" + ], + "Impersonate-Group": [ + "system:authenticated", + "system:cattle:authenticated" + ], + "Impersonate-User": [ + "user-6j5s6" + ], + "Origin": [ + "https://localhost:8443" + ], + "Priority": [ + "u=0" + ], + "Referer": [ + "https://localhost:8443/dashboard/c/local/explorer/management.cattle.io.project/create" + ], + "Sec-Fetch-Dest": [ + "empty" + ], + "Sec-Fetch-Mode": [ + "cors" + ], + "Sec-Fetch-Site": [ + "same-origin" + ], + "User-Agent": [ + "Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:140.0) Gecko/20100101 Firefox/140.0" + ], + "X-Api-Csrf": [ + "fccc690cab7b0c169b3fc6527edadef3" + ] + }, + "responseHeader": { + "Cache-Control": [ + "no-cache, no-store, must-revalidate" + ], + "Content-Encoding": [ + "gzip" + ], + "Content-Type": [ + "application/json" + ], + "Expires": [ + "Wed 24 Feb 1982 18:42:00 GMT" + ], + "X-Api-Cattle-Auth": [ + "true" + ], + "X-Api-Schemas": [ + "https://localhost:8443/v3/project/schemas" + ], + "X-Content-Type-Options": [ + "nosniff" + ] + }, + "requestBody": { + "annotations": {}, + "clusterId": "local", + "containerDefaultResourceLimit": {}, + "creatorId": "local://user-6j5s6", + "labels": {}, + "name": "example-project", + "namespaceDefaultResourceQuota": {}, + "resourceQuota": {}, + "type": "project" + }, + "responseBody": { + "actions": { + "exportYaml": "https://localhost:8443/v3/projects/local:p-qt6tq?action=exportYaml" + }, + "annotations": { + "authz.management.cattle.io/creator-role-bindings": "{\"required\":[\"project-owner\"]}" + }, + "backingNamespace": "local-p-qt6tq", + "baseType": "project", + "clusterId": "local", + "containerDefaultResourceLimit": { + "type": "/v3/schemas/containerResourceLimit" + }, + "created": "2025-06-30T16:42:24Z", + "createdTS": 1751301744000, + "creatorId": "user-6j5s6", + "id": "local:p-qt6tq", + "labels": { + "cattle.io/creator": "norman" + }, + "links": { + "basicAuths": "https://localhost:8443/v3/projects/local:p-qt6tq/basicauths", + "certificates": "https://localhost:8443/v3/projects/local:p-qt6tq/certificates", + "configMaps": "https://localhost:8443/v3/projects/local:p-qt6tq/configmaps", + "cronJobs": "https://localhost:8443/v3/projects/local:p-qt6tq/cronjobs", + "daemonSets": "https://localhost:8443/v3/projects/local:p-qt6tq/daemonsets", + "deployments": "https://localhost:8443/v3/projects/local:p-qt6tq/deployments", + "dnsRecords": "https://localhost:8443/v3/projects/local:p-qt6tq/dnsrecords", + "dockerCredentials": "https://localhost:8443/v3/projects/local:p-qt6tq/dockercredentials", + "horizontalPodAutoscalers": "https://localhost:8443/v3/projects/local:p-qt6tq/horizontalpodautoscalers", + "ingresses": "https://localhost:8443/v3/projects/local:p-qt6tq/ingresses", + "jobs": "https://localhost:8443/v3/projects/local:p-qt6tq/jobs", + "namespacedBasicAuths": "https://localhost:8443/v3/projects/local:p-qt6tq/namespacedbasicauths", + "namespacedCertificates": "https://localhost:8443/v3/projects/local:p-qt6tq/namespacedcertificates", + "namespacedDockerCredentials": "https://localhost:8443/v3/projects/local:p-qt6tq/namespaceddockercredentials", + "namespacedSecrets": "https://localhost:8443/v3/projects/local:p-qt6tq/namespacedsecrets", + "namespacedServiceAccountTokens": "[redacted]", + "namespacedSshAuths": "https://localhost:8443/v3/projects/local:p-qt6tq/namespacedsshauths", + "persistentVolumeClaims": "https://localhost:8443/v3/projects/local:p-qt6tq/persistentvolumeclaims", + "pods": "https://localhost:8443/v3/projects/local:p-qt6tq/pods", + "projectNetworkPolicies": "https://localhost:8443/v3/projects/local:p-qt6tq/projectnetworkpolicies", + "projectRoleTemplateBindings": "https://localhost:8443/v3/projects/local:p-qt6tq/projectroletemplatebindings", + "remove": "https://localhost:8443/v3/projects/local:p-qt6tq", + "replicaSets": "https://localhost:8443/v3/projects/local:p-qt6tq/replicasets", + "replicationControllers": "https://localhost:8443/v3/projects/local:p-qt6tq/replicationcontrollers", + "secrets": "https://localhost:8443/v3/projects/local:p-qt6tq/secrets", + "self": "https://localhost:8443/v3/projects/local:p-qt6tq", + "serviceAccountTokens": "[redacted]", + "services": "https://localhost:8443/v3/projects/local:p-qt6tq/services", + "sshAuths": "https://localhost:8443/v3/projects/local:p-qt6tq/sshauths", + "statefulSets": "https://localhost:8443/v3/projects/local:p-qt6tq/statefulsets", + "subscribe": "https://localhost:8443/v3/projects/local:p-qt6tq/subscribe", + "update": "https://localhost:8443/v3/projects/local:p-qt6tq", + "workloads": "https://localhost:8443/v3/projects/local:p-qt6tq/workloads" + }, + "name": "example-project", + "namespaceDefaultResourceQuota": { + "limit": { + "type": "/v3/schemas/resourceQuotaLimit" + }, + "type": "/v3/schemas/namespaceResourceQuota" + }, + "namespaceId": null, + "resourceQuota": { + "limit": { + "type": "/v3/schemas/resourceQuotaLimit" + }, + "type": "/v3/schemas/projectResourceQuota", + "usedLimit": { + "type": "/v3/schemas/resourceQuotaLimit" + } + }, + "state": "active", + "transitioning": "no", + "transitioningMessage": "", + "type": "project", + "uuid": "b582603b-7826-4302-8393-792df2611265" + } +} +``` \ No newline at end of file diff --git a/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/enable-cluster-agent-scheduling-customization.md b/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/enable-cluster-agent-scheduling-customization.md new file mode 100644 index 00000000000..cc4d178281f --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/enable-cluster-agent-scheduling-customization.md @@ -0,0 +1,78 @@ +--- +title: Enabling Cluster Agent Scheduling Customization +--- + + + + + +The `cattle-cluster-agent` allows enabling automatic deployment of a Priority Class and Pod Disruption Budget. + +When this feature is enabled, all newly provisioned Node Driver, Custom, and Imported RKE2 and K3s clusters will automatically deploy a Priority Class and Pod Disruption Budget during the provisioning process. Existing clusters can be gradually updated with this new behavior using the [Rancher UI or by setting a specific annotation](#updating-existing-clusters) on cluster objects. + +This feature is disabled by default. + +## Enabling Cluster Agent Scheduling Customization + +:::info +Enabling or disabling this feature only impacts new clusters. Existing downstream clusters will not be automatically updated. See [_Updating Existing Clusters_](#updating-existing-clusters). +::: + +1. In the upper left corner, click **☰ > Global Settings** +1. Select **Feature Flags** +1. Find the `cluster-agent-scheduling-customization` feature and click **⋮ > Activate** + +## Configuring the Global Settings + +You can customize the default Priority Class (PC) and Pod Disruption Budget (PDB) by updating the `cluster-agent-default-priority-class` and `cluster-agent-default-pod-disruption-budget` global settings in the Rancher UI. Note that both the Priority Class and Pod Disruption Budget have configuration restrictions: + ++ The `Value` set for the default PC cannot be less than negative 1 billion, or greater than 1 billion. ++ The `PreemptionPolicy` set for the PC must be equal to `PreemptLowerPriority` or `Never`. ++ You cannot configure the PDB `minAvailable` and `maxUnavailable` fields to both have a non-zero value. ++ The PDB `minAvailable` must either be a non-negative whole number integer, or a non-negative whole number percent (e.g. `1` or `100%`). ++ The PDB `maxUnavailable` must either be a non-negative whole number integer, or a non-negative whole number percent (e.g. `1` or `100%`). + + +## Updating Existing Clusters + +:::info +When this feature is disabled, you cannot modify the cluster agent scheduling customization fields for existing clusters. However, you can always remove the configuration, regardless of the feature's status. +::: + +After enabling this feature, you can configure scheduling customization for existing clusters in two ways: + ++ **Using the Rancher UI** + + Edit the desired cluster and navigate to the **Cluster Agent** tab within the **Cluster Configuration** section. + + Enable the `Prevent Rancher cluster agent pod eviction` checkbox. + + The necessary fields on the associated `clusters.provisioning.cattle.io` or `clusters.management.cattle.io` object will be automatically configured using the values set in the global settings. + + Save the cluster. ++ **Using an annotation** + + The `provisioning.cattle.io/enable-scheduling-customization` annotation can be used to update clusters without requiring the use of the Rancher UI. This annotation will be automatically removed from the cluster after the Priority Class and Pod Disruption Budget are configured. + + The value of this annotation can be either `true` or `false`, to add or remove scheduling customization automatically. + + For Node Driver Provisioned and Custom clusters, apply this annotation on the associated `clusters.provisioning.cattle.io` object. + + For Imported clusters, apply the annotation on the associated `clusters.management.cattle.io` object. + +## Applying Updated Global Settings + +In order to prevent unexpected changes in scheduler behavior, Rancher does not update existing downstream clusters when the `cluster-agent-default-priority-class` and `cluster-agent-default-pod-disruption-budget` global settings are changed. There are two ways to update existing clusters to use the most recent global settings: + ++ **Using the Rancher UI** + + When configuring a cluster, an additional checkbox will be shown in the **Cluster Agent** tab within the **Cluster Configuration** section. Checking the `Apply global settings for Priority Class and Pod Disruption Budget` checkbox will automatically update the Priority Class and Pod Disruption Budget to match the global settings once the cluster is saved. ++ **Adjusting the cluster yaml** + + You may manually adjust the relevant fields in the cluster object using `kubectl` or the Rancher UI 'Edit As Yaml' feature. Scheduling customization can be found in the `spec.ClusterAgentDeploymentCustomization.SchedulingCustomization` section of the cluster object. + + Alternatively, the `provisioning.cattle.io/enable-scheduling-customization` annotation can be used to remove and re-add the updated scheduling customization fields set on a specific cluster. + +## Downstream Objects + +When this feature is enabled for a given cluster, two downstream resources will be automatically created by Rancher: + ++ A Pod Disruption Budget will be automatically created in the `cattle-system` namespace, named `cattle-cluster-agent-pod-disruption-budget`. ++ A Priority Class will be automatically created, named `cattle-cluster-agent-priority-class`. + +These objects are maintained by Rancher and must not be modified or deleted. The Rancher server will automatically update these objects to match the configuration set on the Cluster object and remove them when they are no longer needed. + +### RBAC considerations + +Before enabling this feature on a downstream cluster, cluster administrators should assess their current RBAC configuration to prevent common access to the `cattle-cluster-agent-priority-class`. In cases where external users have access to a cluster, such as when offering clusters as a service, it is recommended to limit access to the `cattle-cluster-agent-priority-class` object to prevent changes or deletion. + +Similar considerations do not need to be made for the `cattle-cluster-agent-pod-disruption-budget` object, as Pod Disruption Budgets are namespaced objects. Rancher will create the `cattle-cluster-agent-pod-disruption-budget` in the privileged `cattle-system` namespace. diff --git a/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/enable-experimental-features/continuous-delivery.md b/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/enable-experimental-features/continuous-delivery.md new file mode 100644 index 00000000000..1f56c890f43 --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/enable-experimental-features/continuous-delivery.md @@ -0,0 +1,17 @@ +--- +title: Continuous Delivery +--- + + + + + +[Continuous Delivery with Fleet](../../../integrations-in-rancher/fleet/fleet.md) comes preinstalled in Rancher and can't be fully disabled. However, the Fleet feature for GitOps continuous delivery may be disabled using the `continuous-delivery` feature flag. + +To enable or disable this feature, refer to the instructions on [the main page about enabling experimental features.](enable-experimental-features.md) + +Environment Variable Key | Default Value | Description +---|---|--- + `continuous-delivery` | `true` | This flag disables the GitOps continuous delivery feature of Fleet. | + +If Fleet was disabled in Rancher v2.5.x, it will become enabled if Rancher is upgraded to v2.6.x. Only the continuous delivery part of Fleet can be disabled. When `continuous-delivery` is disabled, the `gitjob` deployment is no longer deployed into the Rancher server's local cluster, and `continuous-delivery` is not shown in the Rancher UI. diff --git a/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/enable-experimental-features/enable-experimental-features.md b/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/enable-experimental-features/enable-experimental-features.md new file mode 100644 index 00000000000..5aafc84e1e7 --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/enable-experimental-features/enable-experimental-features.md @@ -0,0 +1,125 @@ +--- +title: Enabling Experimental Features +--- + + + + + +Rancher includes some features that are experimental and disabled by default. You might want to enable these features, for example, if you decide that the benefits of using an [unsupported storage type](unsupported-storage-drivers.md) outweighs the risk of using an untested feature. Feature flags were introduced to allow you to try these features that are not enabled by default. + +The features can be enabled in three ways: + +- [Enable features when starting Rancher.](#enabling-features-when-starting-rancher) When installing Rancher with a CLI, you can use a feature flag to enable a feature by default. +- [Enable features from the Rancher UI](#enabling-features-with-the-rancher-ui) by going to the **Settings** page. +- [Enable features with the Rancher API](#enabling-features-with-the-rancher-api) after installing Rancher. + +Each feature has two values: + +- A default value, which can be configured with a flag or environment variable from the command line +- A set value, which can be configured with the Rancher API or UI + +If no value has been set, Rancher uses the default value. + +Because the API sets the actual value and the command line sets the default value, that means that if you enable or disable a feature with the API or UI, it will override any value set with the command line. + +For example, if you install Rancher, then set a feature flag to true with the Rancher API, then upgrade Rancher with a command that sets the feature flag to false, the default value will still be false, but the feature will still be enabled because it was set with the Rancher API. If you then deleted the set value (true) with the Rancher API, setting it to NULL, the default value (false) would take effect. See the [feature flags page](../../../getting-started/installation-and-upgrade/installation-references/feature-flags.md) for more information. + +## Enabling Features when Starting Rancher + +When you install Rancher, enable the feature you want with a feature flag. The command is different depending on whether you are installing Rancher on a single node or if you are doing a Kubernetes Installation of Rancher. + +### Enabling Features for Kubernetes Installs + +:::note + +Values set from the Rancher API will override the value passed in through the command line. + +::: + +When installing Rancher with a Helm chart, use the `--set` option. In the below example, two features are enabled by passing the feature flag names in a comma separated list: + + +``` +helm install rancher rancher-latest/rancher \ + --namespace cattle-system \ + --set hostname=rancher.my.org \ + --set 'extraEnv[0].name=CATTLE_FEATURES' + --set 'extraEnv[0].value==true,=true' +``` + +:::note + +If you are installing an alpha version, Helm requires adding the `--devel` option to the command. + +::: + +### Enabling Features for Air Gap Installs + +To perform an [air gap installation of Rancher](../../../getting-started/installation-and-upgrade/other-installation-methods/air-gapped-helm-cli-install/install-rancher-ha.md), add a Helm chart repository and download a Helm chart, then install Rancher with Helm. + +When you install the Helm chart, you should pass in feature flag names in a comma separated list, as in the following example: + +``` +helm install rancher ./rancher-.tgz \ + --namespace cattle-system \ + --set hostname= \ + --set rancherImage=/rancher/rancher \ + --set ingress.tls.source=secret \ + --set systemDefaultRegistry= \ # Set a default private registry to be used in Rancher + --set useBundledSystemChart=true # Use the packaged Rancher system charts + --set 'extraEnv[0].name=CATTLE_FEATURES' + --set 'extraEnv[0].value==true,=true' +``` + +### Enabling Features for Docker Installs + +When installing Rancher with Docker, use the `--features` option. In the below example, two features are enabled by passing the feature flag names in a comma separated list: + +``` +docker run -d -p 80:80 -p 443:443 \ + --restart=unless-stopped \ + rancher/rancher:rancher-latest \ + --features==true,=true +``` + + +## Enabling Features with the Rancher UI + +1. In the upper left corner, click **☰ > Global Settings**. +1. Click **Feature Flags**. +1. To enable a feature, go to the disabled feature you want to enable and click **⋮ > Activate**. + +**Result:** The feature is enabled. + +### Disabling Features with the Rancher UI + +1. In the upper left corner, click **☰ > Global Settings**. +1. Click **Feature Flags**. You will see a list of experimental features. +1. To disable a feature, go to the enabled feature you want to disable and click **⋮ > Deactivate**. + +**Result:** The feature is disabled. + +## Enabling Features with the Rancher API + +1. Go to `/v3/features`. +1. In the `data` section, you will see an array containing all of the features that can be turned on with feature flags. The name of the feature is in the `id` field. Click the name of the feature you want to enable. +1. In the upper left corner of the screen, under **Operations,** click **Edit**. +1. In the **Value** drop-down menu, click **True**. +1. Click **Show Request**. +1. Click **Send Request**. +1. Click **Close**. + +**Result:** The feature is enabled. + +### Disabling Features with the Rancher API + +1. Go to `/v3/features`. +1. In the `data` section, you will see an array containing all of the features that can be turned on with feature flags. The name of the feature is in the `id` field. Click the name of the feature you want to enable. +1. In the upper left corner of the screen, under **Operations,** click **Edit**. +1. In the **Value** drop-down menu, click **False**. +1. Click **Show Request**. +1. Click **Send Request**. +1. Click **Close**. + +**Result:** The feature is disabled. diff --git a/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/enable-experimental-features/istio-traffic-management-features.md b/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/enable-experimental-features/istio-traffic-management-features.md new file mode 100644 index 00000000000..ac7861a0d83 --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/enable-experimental-features/istio-traffic-management-features.md @@ -0,0 +1,36 @@ +--- +title: UI for Istio Virtual Services and Destination Rules +--- + + + + + +This feature enables a UI that lets you create, read, update and delete virtual services and destination rules, which are traffic management features of Istio. + +> **Prerequisite:** Turning on this feature does not enable Istio. A cluster administrator needs to [enable Istio for the cluster](../istio-setup-guide/istio-setup-guide.md) in order to use the feature. + +To enable or disable this feature, refer to the instructions on [the main page about enabling experimental features.](enable-experimental-features.md) + +Environment Variable Key | Default Value | Status | Available as of +---|---|---|--- +`istio-virtual-service-ui` |`false` | Experimental | v2.3.0 +`istio-virtual-service-ui` | `true` | GA | v2.3.2 + +## About this Feature + +A central advantage of Istio's traffic management features is that they allow dynamic request routing, which is useful for canary deployments, blue/green deployments, or A/B testing. + +When enabled, this feature turns on a page that lets you configure some traffic management features of Istio using the Rancher UI. Without this feature, you need to use `kubectl` to manage traffic with Istio. + +The feature enables two UI tabs: one tab for **Virtual Services** and another for **Destination Rules**. + +- **Virtual services** intercept and direct traffic to your Kubernetes services, allowing you to direct percentages of traffic from a request to different services. You can use them to define a set of routing rules to apply when a host is addressed. For details, refer to the [Istio documentation.](https://istio.io/docs/reference/config/networking/v1alpha3/virtual-service/) +- **Destination rules** serve as the single source of truth about which service versions are available to receive traffic from virtual services. You can use these resources to define policies that apply to traffic that is intended for a service after routing has occurred. For details, refer to the [Istio documentation.](https://istio.io/docs/reference/config/networking/v1alpha3/destination-rule) + +To see these tabs, + +1. Click **☰ > Cluster Management**. +1. Go to the cluster where Istio is installed and click **Explore**. +1. In the left navigation bar, click **Istio**. +1. You will see tabs for **Kiali** and **Jaeger**. From the left navigation bar, you can view and configure **Virtual Services** and **Destination Rules**. \ No newline at end of file diff --git a/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/enable-experimental-features/rancher-on-arm64.md b/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/enable-experimental-features/rancher-on-arm64.md new file mode 100644 index 00000000000..a7da226c92d --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/enable-experimental-features/rancher-on-arm64.md @@ -0,0 +1,27 @@ +--- +title: "Running on ARM64 Mixed Architecture (Experimental)" +--- + + + + + +:::caution + +Running on an ARM64 mixed architecture platform is currently an experimental feature and is not yet officially supported in Rancher. Therefore, we do not recommend using ARM64 mixed architecture based nodes in a production environment. + +::: + +The following options are available when using an ARM64 platform: + +- Create custom cluster and adding ARM64 based node(s) + - Kubernetes cluster version must be 1.12 or higher +- Importing clusters that contain ARM64 based nodes + - Kubernetes cluster version must be 1.12 or higher + +Depending on your cluster provisioning refer to [RKE2 cluster configuration options](../../../reference-guides/cluster-configuration/rancher-server-configuration/rke2-cluster-configuration.md) or [K3s cluster configuration options](../../../reference-guides/cluster-configuration/rancher-server-configuration/k3s-cluster-configuration.md) for more information. + +The following features are not tested: + +- Monitoring, alerts, notifiers, pipelines and logging +- Launching apps from the catalog diff --git a/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/enable-experimental-features/role-template-aggregation.md b/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/enable-experimental-features/role-template-aggregation.md new file mode 100644 index 00000000000..d5ec106cb2a --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/enable-experimental-features/role-template-aggregation.md @@ -0,0 +1,21 @@ +--- +title: RoleTemplate Aggregation +--- + + + + + +:::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. diff --git a/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/enable-experimental-features/unsupported-storage-drivers.md b/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/enable-experimental-features/unsupported-storage-drivers.md new file mode 100644 index 00000000000..3670d00e39b --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/enable-experimental-features/unsupported-storage-drivers.md @@ -0,0 +1,43 @@ +--- +title: Allowing Unsupported Storage Drivers +--- + + + + + +This feature allows you to use types for storage providers and provisioners that are not enabled by default. + +To enable or disable this feature, refer to the instructions on [the main page about enabling experimental features.](enable-experimental-features.md) + +Environment Variable Key | Default Value | Description +---|---|--- + `unsupported-storage-drivers` | `false` | This feature enables types for storage providers and provisioners that are not enabled by default. + +### Types for Persistent Volume Plugins that are Enabled by Default +Below is a list of storage types for persistent volume plugins that are enabled by default. When enabling this feature flag, any persistent volume plugins that are not on this list are considered experimental and unsupported: + +Name | Plugin +--------|---------- +Amazon EBS Disk | `aws-ebs` +AzureFile | `azure-file` +AzureDisk | `azure-disk` +Google Persistent Disk | `gce-pd` +Longhorn | `flex-volume-longhorn` +VMware vSphere Volume | `vsphere-volume` +Local | `local` +Network File System | `nfs` +hostPath | `host-path` + +### Types for StorageClass that are Enabled by Default +Below is a list of storage types for a StorageClass that are enabled by default. When enabling this feature flag, any persistent volume plugins that are not on this list are considered experimental and unsupported: + +Name | Plugin +--------|-------- +Amazon EBS Disk | `aws-ebs` +AzureFile | `azure-file` +AzureDisk | `azure-disk` +Google Persistent Disk | `gce-pd` +Longhorn | `flex-volume-longhorn` +VMware vSphere Volume | `vsphere-volume` +Local | `local` \ No newline at end of file diff --git a/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/enable-user-retention.md b/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/enable-user-retention.md new file mode 100644 index 00000000000..ca811be2b83 --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/enable-user-retention.md @@ -0,0 +1,62 @@ +--- +title: Enabling User Retention +--- + + + + + +In Rancher v2.8.5 and later, you can enable user retention to automatically disable or delete inactive user accounts after a configurable time period. + +The user retention feature is off by default. + +## Enabling User Retention with kubectl + +To enable user retention, you must set `user-retention-cron`. You must also set at least one of `disable-inactive-user-after` or `delete-inactive-user-after`. You can use `kubectl edit setting ` to open your editor of choice and set these values. + +## Configuring Rancher to Delete Users, Disable Users, or Combine Operations + +Rancher uses two global user retention settings to determine if and when users are disabled or deleted after a certain period of inactivity. Disabled accounts must be re-enabled before users can log in again. If an account is deleted without being disabled, users may be able to log in through external authentication and the deleted account will be recreated. + +The global settings, `disable-inactive-user-after` and `delete-inactive-user-after`, do not block one another from running. + +For example, you can set both operations to run. If you give `disable-inactive-user-after` a shorter duration than `delete-inactive-user-after`, the user retention process disables inactive accounts before deleting them. + +You can also edit some user retention settings on a specific user's `UserAttribute`. Setting these values overrides the global settings. See [User-specific User Retention Overrides](#user-specific-user-retention-overrides) for more details. + +### Required User Retention Settings + +The following are global settings: + +- `user-retention-cron`: Describes how often the user retention process runs. The value is a cron expression (for example, `0 * * * *` for every hour). + - `disable-inactive-user-after`: The amount of time that a user account can be inactive before the process disables an account. Disabling an account forces the user to request that an administrator re-enable the account before they can log in to use it. Values are expressed in [time.Duration units](https://pkg.go.dev/time#ParseDuration) (for example, `720h` for 720 hours or 30 days). The value must be greater than `auth-user-session-ttl-minutes`, which is `16h` by default. If the value is not set, set to the empty string, or is equal to 0, the process does not disable any inactive accounts. +- `delete-inactive-user-after`: The amount of time that a user account can be inactive before the process deletes the account. Values are expressed in time.Duration units (for example, `720h` for 720 hours or 30 days). The value must be greater than `auth-user-session-ttl-minutes`, which is `16h` by default. The value should be greater than `336h` (14 days), otherwise it is rejected by the Rancher webhook. If you need the value to be lower than 14 days, you can [bypass the webhook](../../reference-guides/rancher-webhook.md#bypassing-the-webhook). If the value is not set, set to the empty string, or is equal to 0, the process does not delete any inactive accounts. + +### Optional User Retention Settings + +The following are global settings: + +- `user-retention-dry-run`: If set to `true`, the user retention process runs without actually deleting or disabling any user accounts. This can help test user retention behavior before allowing the process to disable or delete user accounts in a production environment. +- `user-last-login-default`: If a user does not have `UserAttribute.LastLogin` set on their account, this setting is used instead. The value is expressed as an [RFC 3339 date-time](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) truncated to the last second; for example, `2023-03-01T00:00:00Z`. If the value is set to the empty string or is equal to 0, this setting is not used. + +#### User-specific User Retention Overrides + +The following are user-specific overrides to the global settings for special cases. These settings are applied by editing the `UserAttribute` associated with a given account: + +``` +kubectl edit userattribute +``` + +- `disableAfter`: The user-specific override for `disable-inactive-user-after`. The value is expressed in [time.Duration units](https://pkg.go.dev/time#ParseDuration) and truncated to the second. If the value is set to `0s` then the account won't be subject to disabling. +- `deleteAfter`: The user-specific override for `delete-inactive-user-after`. The value is expressed in [time.Duration units](https://pkg.go.dev/time#ParseDuration) and truncated to the second. If the value is set to `0s` then the account won't be subject to deletion. + +## Viewing User Retention Settings in the Rancher UI + +You can see which user retention settings are applied to which users. + +1. In the upper left corner, click **☰ > Users & Authentication**. +1. In the left navigation menu, select **Users**. + +The **Disable After** and **Delete After** columns for each user account indicate how long the account can be inactive before it is disabled or deleted from Rancher. There is also a **Last Login** column roughly indicating when the account was last active. + +The same information is available if you click a user's name in the **Users** table and select the **Detail** tab. diff --git a/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/istio-setup-guide/enable-istio-in-cluster.md b/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/istio-setup-guide/enable-istio-in-cluster.md new file mode 100644 index 00000000000..28d085e74df --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/istio-setup-guide/enable-istio-in-cluster.md @@ -0,0 +1,40 @@ +--- +title: Enable Istio in the Cluster +--- + + + + + +:::warning + +[Rancher-Istio](https://github.com/rancher/charts/tree/release-v2.11/charts/rancher-istio) will be deprecated in Rancher v2.12.0; turn to the [SUSE Rancher Application Collection](https://apps.rancher.io) build of Istio for enhanced security (included in SUSE Rancher Prime subscriptions). + +Detailed information can be found in [this announcement](https://forums.suse.com/t/deprecation-of-rancher-istio/45043). + +::: + +:::note Prerequisites: + +- Only a user with the `cluster-admin` [Kubernetes default role](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#user-facing-roles) assigned can configure and install Istio in a Kubernetes cluster. +- To install Istio on an RKE2 cluster, additional steps are required. For details, see [this section.](../../../integrations-in-rancher/istio/configuration-options/install-istio-on-rke2-cluster.md) +- To install Istio in a cluster where project network isolation is enabled, additional steps are required. For details, see [this section.](../../../integrations-in-rancher/istio/configuration-options/project-network-isolation.md) + +::: + +1. Click **☰ > Cluster Management**. +1. Go to the where you want to enable Istio and click **Explore**. +1. Click **Apps**. +1. Click **Charts**. +1. Click **Istio**. +1. If you have not already installed your own monitoring app, you will be prompted to install the rancher-monitoring app. Optional: Set your Selector or Scrape config options on rancher-monitoring app install. +1. Optional: Configure member access and [resource limits](../../../integrations-in-rancher/istio/cpu-and-memory-allocations.md) for the Istio components. Ensure you have enough resources on your worker nodes to enable Istio. +1. Optional: Make additional configuration changes to values.yaml if needed. +1. Optional: Add further resources or configuration via the [overlay file](../../../integrations-in-rancher/istio/configuration-options/configuration-options.md#overlay-file). +1. Click **Install**. + +**Result:** Istio is installed at the cluster level. + +## Additional Config Options + +For more information on configuring Istio, refer to the [configuration reference.](../../../integrations-in-rancher/istio/configuration-options/configuration-options.md) diff --git a/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/istio-setup-guide/enable-istio-in-namespace.md b/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/istio-setup-guide/enable-istio-in-namespace.md new file mode 100644 index 00000000000..bb07375866f --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/istio-setup-guide/enable-istio-in-namespace.md @@ -0,0 +1,64 @@ +--- +title: Enable Istio in a Namespace +--- + + + + + +:::warning + +[Rancher-Istio](https://github.com/rancher/charts/tree/release-v2.11/charts/rancher-istio) will be deprecated in Rancher v2.12.0; turn to the [SUSE Rancher Application Collection](https://apps.rancher.io) build of Istio for enhanced security (included in SUSE Rancher Prime subscriptions). + +Detailed information can be found in [this announcement](https://forums.suse.com/t/deprecation-of-rancher-istio/45043). + +::: + +You will need to manually enable Istio in each namespace that you want to be tracked or controlled by Istio. When Istio is enabled in a namespace, the Envoy sidecar proxy will be automatically injected into all new workloads that are deployed in the namespace. + +This namespace setting will only affect new workloads in the namespace. Any preexisting workloads will need to be re-deployed to leverage the sidecar auto injection. + +:::note Prerequisite: + +To enable Istio in a namespace, the cluster must have Istio installed. + +::: + +1. Click **☰ > Cluster Management**. +1. Go to the cluster that you created and click **Explore**. +1. Click **Cluster > Projects/Namespaces**. +1. Go to the namespace where you want to enable Istio and click **⋮ > Enable Istio Auto Injection**. Alternately, click the namespace, and then on the namespace detail page, click **⋮ > Enable Istio Auto Injection**. + +**Result:** The namespace now has the label `istio-injection=enabled`. All new workloads deployed in this namespace will have the Istio sidecar injected by default. + +### Verifying that Automatic Istio Sidecar Injection is Enabled + +To verify that Istio is enabled, deploy a hello-world workload in the namespace. Go to the workload and click the pod name. In the **Containers** section, you should see the `istio-proxy` container. + +### Excluding Workloads from Being Injected with the Istio Sidecar + +If you need to exclude a workload from getting injected with the Istio sidecar, use the following annotation on the workload: + +``` +sidecar.istio.io/inject: “false” +``` + +To add the annotation to a workload, + +1. Click **☰ > Cluster Management**. +1. Go to the cluster that you created and click **Explore**. +1. Click **Workload**. +1. Go to the workload that should not have the sidecar and edit as yaml +1. Add the following key, value `sidecar.istio.io/inject: false` as an annotation on the workload +1. Click **Save**. + +**Result:** The Istio sidecar will not be injected into the workload. + +:::note + +If you are having issues with a Job you deployed not completing, you will need to add this annotation to your pod using the provided steps. Since Istio Sidecars run indefinitely, a Job cannot be considered complete even after its task has completed. + +::: + + +### [Next: Add Deployments with the Istio Sidecar ](use-istio-sidecar.md) \ No newline at end of file diff --git a/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/istio-setup-guide/generate-and-view-traffic.md b/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/istio-setup-guide/generate-and-view-traffic.md new file mode 100644 index 00000000000..d035123351f --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/istio-setup-guide/generate-and-view-traffic.md @@ -0,0 +1,40 @@ +--- +title: Generate and View Traffic from Istio +--- + + + + + +:::warning + +[Rancher-Istio](https://github.com/rancher/charts/tree/release-v2.11/charts/rancher-istio) will be deprecated in Rancher v2.12.0; turn to the [SUSE Rancher Application Collection](https://apps.rancher.io) build of Istio for enhanced security (included in SUSE Rancher Prime subscriptions). + +Detailed information can be found in [this announcement](https://forums.suse.com/t/deprecation-of-rancher-istio/45043). + +::: + +## The Kiali Traffic Graph + +The Istio overview page provides a link to the Kiali dashboard. From the Kiali dashboard, you can view graphs for each namespace. The Kiali graph provides a powerful way to visualize the topology of your Istio service mesh. It shows you which services communicate with each other. + +## Prerequisites + +To enable traffic to show up in the graph, ensure that you have Prometheus installed in the cluster. `Rancher-istio` installs Kiali, and configures it by default to work with the `rancher-monitoring` chart. You can use `rancher-monitoring` or install your own monitoring solution. + +Additionally, for Istio installations version `103.1.0+up1.19.6` and later, Kiali uses a token value for its authentication strategy. If you are trying to generate or retrieve the token (e.g. for login), note that the name of the Kiali service account in Rancher is `kiali`. For more information, refer to the [Kiali token authentication FAQ](https://kiali.io/docs/faq/authentication/). + +Optional: You can configure which namespaces data scraping occurs in by setting the Helm chart options described in [Selectors & Scrape Configs](../../../integrations-in-rancher/istio/configuration-options/selectors-and-scrape-configurations.md). + +## Traffic Visualization + +To see the traffic graph follow the steps below: + +1. In the cluster where Istio is installed, click **Istio** in the left navigation bar. +1. Click the **Kiali** link. +1. Click on **Graph** in the side nav. +1. Change the namespace in the **Namespace** dropdown to view the traffic for each namespace. + +If you refresh the URL to the BookInfo app several times, you should be able to see green arrows on the Kiali graph showing traffic to `v1` and `v3` of the `reviews` service. The control panel on the right side of the graph lets you configure details including how many minutes of the most recent traffic should be shown on the graph. + +For additional tools and visualizations, you can go to Grafana, and Prometheus dashboards from the **Monitoring** **Overview** page diff --git a/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/istio-setup-guide/istio-setup-guide.md b/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/istio-setup-guide/istio-setup-guide.md new file mode 100644 index 00000000000..48959d0aee8 --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/istio-setup-guide/istio-setup-guide.md @@ -0,0 +1,42 @@ +--- +title: Istio Setup Guides +--- + + + + + +:::warning + +[Rancher-Istio](https://github.com/rancher/charts/tree/release-v2.11/charts/rancher-istio) will be deprecated in Rancher v2.12.0; turn to the [SUSE Rancher Application Collection](https://apps.rancher.io) build of Istio for enhanced security (included in SUSE Rancher Prime subscriptions). + +Detailed information can be found in [this announcement](https://forums.suse.com/t/deprecation-of-rancher-istio/45043). + +::: + +This section describes how to enable Istio and start using it in your projects. + +If you use Istio for traffic management, you will need to allow external traffic to the cluster. In that case, you will need to follow all of the steps below. + +## Prerequisites + +This guide assumes you have already [installed Rancher,](../../../getting-started/installation-and-upgrade/installation-and-upgrade.md) and you have already [provisioned a separate Kubernetes cluster](../../new-user-guides/kubernetes-clusters-in-rancher-setup/kubernetes-clusters-in-rancher-setup.md) on which you will install Istio. + +The nodes in your cluster must meet the [CPU and memory requirements.](../../../integrations-in-rancher/istio/cpu-and-memory-allocations.md) + +The workloads and services that you want to be controlled by Istio must meet [Istio's requirements.](https://istio.io/docs/setup/additional-setup/requirements/) + +## Install + +:::tip Quick Setup Tip: + +If you don't need external traffic to reach Istio, and you just want to set up Istio for monitoring and tracing traffic within the cluster, skip the steps for [setting up the Istio gateway](set-up-istio-gateway.md) and [setting up Istio's components for traffic management.](set-up-traffic-management.md) + +::: + +1. [Enable Istio in the cluster.](enable-istio-in-cluster.md) +1. [Enable Istio in all the namespaces where you want to use it.](enable-istio-in-namespace.md) +1. [Add deployments and services that have the Istio sidecar injected.](use-istio-sidecar.md) +1. [Set up the Istio gateway. ](set-up-istio-gateway.md) +1. [Set up Istio's components for traffic management.](set-up-traffic-management.md) +1. [Generate traffic and see Istio in action.](generate-and-view-traffic.md) diff --git a/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/istio-setup-guide/set-up-istio-gateway.md b/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/istio-setup-guide/set-up-istio-gateway.md new file mode 100644 index 00000000000..7c2c03208c8 --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/istio-setup-guide/set-up-istio-gateway.md @@ -0,0 +1,158 @@ +--- +title: Set up the Istio Gateway +--- + + + + + +:::warning + +[Rancher-Istio](https://github.com/rancher/charts/tree/release-v2.11/charts/rancher-istio) will be deprecated in Rancher v2.12.0; turn to the [SUSE Rancher Application Collection](https://apps.rancher.io) build of Istio for enhanced security (included in SUSE Rancher Prime subscriptions). + +Detailed information can be found in [this announcement](https://forums.suse.com/t/deprecation-of-rancher-istio/45043). + +::: + +The gateway to each cluster can have its own port or load balancer, which is unrelated to a service mesh. By default, each Rancher-provisioned cluster has one NGINX ingress controller allowing traffic into the cluster. + +You can use the Nginx Ingress controller with or without Istio installed. If this is the only gateway to your cluster, Istio will be able to route traffic from service to service, but Istio will not be able to receive traffic from outside the cluster. + +To allow Istio to receive external traffic, you need to enable Istio's gateway, which works as a north-south proxy for external traffic. When you enable the Istio gateway, the result is that your cluster will have two Ingresses. + +You will also need to set up a Kubernetes gateway for your services. This Kubernetes resource points to Istio's implementation of the ingress gateway to the cluster. + +You can route traffic into the service mesh with a load balancer or use Istio's NodePort gateway. This section describes how to set up the NodePort gateway. + +For more information on the Istio gateway, refer to the [Istio documentation.](https://istio.io/docs/reference/config/networking/v1alpha3/gateway/) + +![In an Istio-enabled cluster, you can have two Ingresses: the default Nginx Ingress, and the default Istio controller.](/img/istio-ingress.svg) + +## Enable an Istio Gateway + +The ingress gateway is a Kubernetes service that will be deployed in your cluster. The Istio Gateway allows for more extensive customization and flexibility. + +1. Click **☰ > Cluster Management**. +1. Go to the cluster that you created and click **Explore**. +1. In the left navigation bar, click **Istio > Gateways**. +1. Click **Create from Yaml**. +1. Paste your Istio Gateway yaml, or **Read from File**. +1. Click **Create**. + +**Result:** The gateway is deployed, and will now route traffic with applied rules. + +## Example Istio Gateway + +We add the BookInfo app deployments in services when going through the Workloads example. Next we add an Istio Gateway so that the app is accessible from outside your cluster. + +1. Click **☰ > Cluster Management**. +1. Go to the cluster that you created and click **Explore**. +1. In the left navigation bar, click **Istio > Gateways**. +1. Click **Create from Yaml**. +1. Copy and paste the Gateway yaml provided below. +1. Click **Create**. + +```yaml +apiVersion: networking.istio.io/v1alpha3 +kind: Gateway +metadata: + name: bookinfo-gateway +spec: + selector: + istio: ingressgateway # use istio default controller + servers: + - port: + number: 80 + name: http + protocol: HTTP + hosts: + - "*" +--- +``` + +Then to deploy the VirtualService that provides the traffic routing for the Gateway: + +1. Click **☰ > Cluster Management**. +1. Go to the cluster that you created and click **Explore**. +1. In the left navigation bar, click **Istio > VirtualServices**. +1. Copy and paste the VirtualService yaml provided below. +1. Click **Create**. + +```yaml +apiVersion: networking.istio.io/v1alpha3 +kind: VirtualService +metadata: + name: bookinfo +spec: + hosts: + - "*" + gateways: + - bookinfo-gateway + http: + - match: + - uri: + exact: /productpage + - uri: + prefix: /static + - uri: + exact: /login + - uri: + exact: /logout + - uri: + prefix: /api/v1/products + route: + - destination: + host: productpage + port: + number: 9080 +``` + +**Result:** You have configured your gateway resource so that Istio can receive traffic from outside the cluster. + +Confirm that the resource exists by running: +``` +kubectl get gateway -A +``` + +The result should be something like this: +``` +NAME AGE +bookinfo-gateway 64m +``` + +### Access the ProductPage Service from a Web Browser + +To test and see if the BookInfo app deployed correctly, the app can be viewed a web browser using the Istio controller IP and port, combined with the request name specified in your Kubernetes gateway resource: + +`http://:/productpage` + +To get the ingress gateway URL and port, + +1. Click **☰ > Cluster Management**. +1. Go to the cluster that you created and click **Explore**. +1. In the left navigation bar, click **Workload**. +1. Scroll down to the `istio-system` namespace. +1. Within `istio-system`, there is a workload named `istio-ingressgateway`. Under the name of this workload, you should see links, such as `80/tcp`. +1. Click one of those links. This should show you the URL of the ingress gateway in your web browser. Append `/productpage` to the URL. + +**Result:** You should see the BookInfo app in the web browser. + +For help inspecting the Istio controller URL and ports, try the commands the [Istio documentation.](https://istio.io/docs/tasks/traffic-management/ingress/ingress-control/#determining-the-ingress-ip-and-ports) + +## Troubleshooting + +The [official Istio documentation](https://istio.io/docs/tasks/traffic-management/ingress/ingress-control/#troubleshooting) suggests `kubectl` commands to inspect the correct ingress host and ingress port for external requests. + +### Confirming that the Kubernetes Gateway Matches Istio's Ingress Controller + +You can try the steps in this section to make sure the Kubernetes gateway is configured properly. + +In the gateway resource, the selector refers to Istio's default ingress controller by its label, in which the key of the label is `istio` and the value is `ingressgateway`. To make sure the label is appropriate for the gateway, do the following: + +1. Click **☰ > Cluster Management**. +1. Go to the cluster that you created and click **Explore**. +1. In the left navigation bar, click **Workload**. +1. Scroll down to the `istio-system` namespace. +1. Within `istio-system`, there is a workload named `istio-ingressgateway`. Click the name of this workload and go to the **Labels and Annotations** section. You should see that it has the key `istio` and the value `ingressgateway`. This confirms that the selector in the Gateway resource matches Istio's default ingress controller. + +### [Next: Set up Istio's Components for Traffic Management](set-up-traffic-management.md) diff --git a/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/istio-setup-guide/set-up-traffic-management.md b/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/istio-setup-guide/set-up-traffic-management.md new file mode 100644 index 00000000000..789fb1c5865 --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/istio-setup-guide/set-up-traffic-management.md @@ -0,0 +1,87 @@ +--- +title: Set up Istio's Components for Traffic Management +--- + + + + + +:::warning + +[Rancher-Istio](https://github.com/rancher/charts/tree/release-v2.11/charts/rancher-istio) will be deprecated in Rancher v2.12.0; turn to the [SUSE Rancher Application Collection](https://apps.rancher.io) build of Istio for enhanced security (included in SUSE Rancher Prime subscriptions). + +Detailed information can be found in [this announcement](https://forums.suse.com/t/deprecation-of-rancher-istio/45043). + +::: + +A central advantage of traffic management in Istio is that it allows dynamic request routing. Some common applications for dynamic request routing include canary deployments and blue/green deployments. The two key resources in Istio traffic management are *virtual services* and *destination rules*. + +- [Virtual services](https://istio.io/docs/reference/config/networking/v1alpha3/virtual-service/) intercept and direct traffic to your Kubernetes services, allowing you to divide percentages of traffic from a request to different services. You can use them to define a set of routing rules to apply when a host is addressed. +- [Destination rules](https://istio.io/docs/reference/config/networking/v1alpha3/destination-rule/) serve as the single source of truth about which service versions are available to receive traffic from virtual services. You can use these resources to define policies that apply to traffic that is intended for a service after routing has occurred. + +This section describes how to add an example virtual service that corresponds to the `reviews` microservice in the sample BookInfo app. The purpose of this service is to divide traffic between two versions of the `reviews` service. + +In this example, we take the traffic to the `reviews` service and intercept it so that 50 percent of it goes to `v1` of the service and 50 percent goes to `v2`. + +After this virtual service is deployed, we will generate traffic and see from the Kiali visualization that traffic is being routed evenly between the two versions of the service. + +To deploy the virtual service and destination rules for the `reviews` service, +1. Click **☰ > Cluster Management**. +1. Go to the cluster where Istio is installed and click **Explore**. +1. In the cluster where Istio is installed, click **Istio > DestinationRules** in the left navigation bar. +1. Click **Create**. +1. Copy and paste the DestinationRule yaml provided below. +1. Click **Create**. +1. Click **Edit as YAML** and use this configuration: + + ```yaml + apiVersion: networking.istio.io/v1alpha3 + kind: DestinationRule + metadata: + name: reviews + spec: + host: reviews + subsets: + - name: v1 + labels: + version: v1 + - name: v2 + labels: + version: v2 + - name: v3 + labels: + version: v3 + ``` +1. Click **Create**. + +Then to deploy the VirtualService that provides the traffic routing that utilizes the DestinationRule: + +1. Click **VirtualService** in the side nav bar. +1. Click **Create from Yaml**. +1. Copy and paste the VirtualService yaml provided below. +1. Click **Create**. + +```yaml +apiVersion: networking.istio.io/v1alpha3 +kind: VirtualService +metadata: + name: reviews +spec: + hosts: + - reviews + http: + - route: + - destination: + host: reviews + subset: v1 + weight: 50 + - destination: + host: reviews + subset: v3 + weight: 50 +--- +``` + +**Result:** When you generate traffic to this service (for example, by refreshing the ingress gateway URL), the Kiali traffic graph will reflect that traffic to the `reviews` service is divided evenly between `v1` and `v3`. + +### [Next: Generate and View Traffic](generate-and-view-traffic.md) diff --git a/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/istio-setup-guide/use-istio-sidecar.md b/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/istio-setup-guide/use-istio-sidecar.md new file mode 100644 index 00000000000..cfdd9b22aca --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/istio-setup-guide/use-istio-sidecar.md @@ -0,0 +1,371 @@ +--- +title: Add Deployments and Services with the Istio Sidecar +--- + + + + + +:::warning + +[Rancher-Istio](https://github.com/rancher/charts/tree/release-v2.11/charts/rancher-istio) will be deprecated in Rancher v2.12.0; turn to the [SUSE Rancher Application Collection](https://apps.rancher.io) build of Istio for enhanced security (included in SUSE Rancher Prime subscriptions). + +Detailed information can be found in [this announcement](https://forums.suse.com/t/deprecation-of-rancher-istio/45043). + +::: + +:::note Prerequisite: + +To enable Istio for a workload, the cluster and namespace must have the Istio app installed. + +::: + +Enabling Istio in a namespace only enables automatic sidecar injection for new workloads. To enable the Envoy sidecar for existing workloads, you need to enable it manually for each workload. + +To inject the Istio sidecar on an existing workload in the namespace, + +1. In the upper left corner, click **☰ > Cluster Management**. +1. On the **Clusters** page, go to the cluster where you want to see the visualizations and click **Explore**. +1. Click **Workload**. +1. Go to the workload where you want to inject the Istio sidecar and click **⋮ > Redeploy**. When the workload is redeployed, it will have the Envoy sidecar automatically injected. + +Wait a few minutes for the workload to upgrade to have the istio sidecar. Click it and go to the Containers section. You should be able to see `istio-proxy` alongside your original workload. This means the Istio sidecar is enabled for the workload. Istio is doing all the wiring for the sidecar envoy. Now Istio can do all the features automatically if you enable them in the yaml. + +### Add Deployments and Services + +There are a few ways to add new **Deployments** in your namespace: + +1. Click **☰ > Cluster Management**. +1. Go to the cluster that you created and click **Explore**. +1. Click **Workload**. +1. Click **Create**. +1. Click **Deployment**. +1. Fill out the form, or **Edit as Yaml**. +1. Click **Create**. + +To add a **Service** to your namespace: + +1. Click **☰ > Cluster Management**. +1. Go to the cluster that you created and click **Explore**. +1. Click **Service Discovery > Services**. +1. Click **Create**. +1. Select the type of service that you want. +1. Fill out the form, or **Edit as Yaml**. +1. Click **Create** + +You can also create deployments and services using the kubectl **shell** + +1. Run `kubectl create -f .yaml` if your file is stored locally in the cluster +1. Or run `cat<< EOF | kubectl apply -f -`, paste the file contents into the terminal, then run `EOF` to complete the command. + +### Example Deployments and Services + +Next we add the Kubernetes resources for the sample deployments and services for the BookInfo app in Istio's documentation. + +1. Click **☰ > Cluster Management**. +1. Go to the cluster that you created and click **Explore**. +1. In the top navigation bar, open the kubectl shell. +1. Run `cat<< EOF | kubectl apply -f -` +1. Copy the below resources into the the shell. +1. Run `EOF` + +This will set up the following sample resources from Istio's example BookInfo app: + +Details service and deployment: + +- A `details` Service +- A ServiceAccount for `bookinfo-details` +- A `details-v1` Deployment + +Ratings service and deployment: + +- A `ratings` Service +- A ServiceAccount for `bookinfo-ratings` +- A `ratings-v1` Deployment + +Reviews service and deployments (three versions): + +- A `reviews` Service +- A ServiceAccount for `bookinfo-reviews` +- A `reviews-v1` Deployment +- A `reviews-v2` Deployment +- A `reviews-v3` Deployment + +Productpage service and deployment: + +This is the main page of the app, which will be visible from a web browser. The other services will be called from this page. + +- A `productpage` service +- A ServiceAccount for `bookinfo-productpage` +- A `productpage-v1` Deployment + +### Resource YAML + +```yaml +# Copyright 2017 Istio Authors +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +################################################################################################## +# Details service +################################################################################################## +apiVersion: v1 +kind: Service +metadata: + name: details + labels: + app: details + service: details +spec: + ports: + - port: 9080 + name: http + selector: + app: details +--- +apiVersion: v1 +kind: ServiceAccount +metadata: + name: bookinfo-details +--- +apiVersion: apps/v1 +kind: Deployment +metadata: + name: details-v1 + labels: + app: details + version: v1 +spec: + replicas: 1 + selector: + matchLabels: + app: details + version: v1 + template: + metadata: + labels: + app: details + version: v1 + spec: + serviceAccountName: bookinfo-details + containers: + - name: details + image: docker.io/istio/examples-bookinfo-details-v1:1.15.0 + imagePullPolicy: IfNotPresent + ports: + - containerPort: 9080 +--- +################################################################################################## +# Ratings service +################################################################################################## +apiVersion: v1 +kind: Service +metadata: + name: ratings + labels: + app: ratings + service: ratings +spec: + ports: + - port: 9080 + name: http + selector: + app: ratings +--- +apiVersion: v1 +kind: ServiceAccount +metadata: + name: bookinfo-ratings +--- +apiVersion: apps/v1 +kind: Deployment +metadata: + name: ratings-v1 + labels: + app: ratings + version: v1 +spec: + replicas: 1 + selector: + matchLabels: + app: ratings + version: v1 + template: + metadata: + labels: + app: ratings + version: v1 + spec: + serviceAccountName: bookinfo-ratings + containers: + - name: ratings + image: docker.io/istio/examples-bookinfo-ratings-v1:1.15.0 + imagePullPolicy: IfNotPresent + ports: + - containerPort: 9080 +--- +################################################################################################## +# Reviews service +################################################################################################## +apiVersion: v1 +kind: Service +metadata: + name: reviews + labels: + app: reviews + service: reviews +spec: + ports: + - port: 9080 + name: http + selector: + app: reviews +--- +apiVersion: v1 +kind: ServiceAccount +metadata: + name: bookinfo-reviews +--- +apiVersion: apps/v1 +kind: Deployment +metadata: + name: reviews-v1 + labels: + app: reviews + version: v1 +spec: + replicas: 1 + selector: + matchLabels: + app: reviews + version: v1 + template: + metadata: + labels: + app: reviews + version: v1 + spec: + serviceAccountName: bookinfo-reviews + containers: + - name: reviews + image: docker.io/istio/examples-bookinfo-reviews-v1:1.15.0 + imagePullPolicy: IfNotPresent + ports: + - containerPort: 9080 +--- +apiVersion: apps/v1 +kind: Deployment +metadata: + name: reviews-v2 + labels: + app: reviews + version: v2 +spec: + replicas: 1 + selector: + matchLabels: + app: reviews + version: v2 + template: + metadata: + labels: + app: reviews + version: v2 + spec: + serviceAccountName: bookinfo-reviews + containers: + - name: reviews + image: docker.io/istio/examples-bookinfo-reviews-v2:1.15.0 + imagePullPolicy: IfNotPresent + ports: + - containerPort: 9080 +--- +apiVersion: apps/v1 +kind: Deployment +metadata: + name: reviews-v3 + labels: + app: reviews + version: v3 +spec: + replicas: 1 + selector: + matchLabels: + app: reviews + version: v3 + template: + metadata: + labels: + app: reviews + version: v3 + spec: + serviceAccountName: bookinfo-reviews + containers: + - name: reviews + image: docker.io/istio/examples-bookinfo-reviews-v3:1.15.0 + imagePullPolicy: IfNotPresent + ports: + - containerPort: 9080 +--- +################################################################################################## +# Productpage services +################################################################################################## +apiVersion: v1 +kind: Service +metadata: + name: productpage + labels: + app: productpage + service: productpage +spec: + ports: + - port: 9080 + name: http + selector: + app: productpage +--- +apiVersion: v1 +kind: ServiceAccount +metadata: + name: bookinfo-productpage +--- +apiVersion: apps/v1 +kind: Deployment +metadata: + name: productpage-v1 + labels: + app: productpage + version: v1 +spec: + replicas: 1 + selector: + matchLabels: + app: productpage + version: v1 + template: + metadata: + labels: + app: productpage + version: v1 + spec: + serviceAccountName: bookinfo-productpage + containers: + - name: productpage + image: docker.io/istio/examples-bookinfo-productpage-v1:1.15.0 + imagePullPolicy: IfNotPresent + ports: + - containerPort: 9080 +--- +``` + +### [Next: Set up the Istio Gateway](set-up-istio-gateway.md) diff --git a/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/manage-projects/manage-project-resource-quotas/about-project-resource-quotas.md b/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/manage-projects/manage-project-resource-quotas/about-project-resource-quotas.md new file mode 100644 index 00000000000..be7d1b5a57a --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/manage-projects/manage-project-resource-quotas/about-project-resource-quotas.md @@ -0,0 +1,74 @@ +--- +title: How Resource Quotas Work in Rancher Projects +--- + + + + + +Resource quotas in Rancher include the same functionality as the [native version of Kubernetes](https://kubernetes.io/docs/concepts/policy/resource-quotas/). However, in Rancher, resource quotas have been extended so that you can apply them to projects. + +In a standard Kubernetes deployment, resource quotas are applied to individual namespaces. However, you cannot apply the quota to your namespaces simultaneously with a single action. Instead, the resource quota must be applied multiple times. + +In the following diagram, a Kubernetes administrator is trying to enforce a resource quota without Rancher. The administrator wants to apply a resource quota that sets the same CPU and memory limit to every namespace in his cluster (`Namespace 1-4`) . However, in the base version of Kubernetes, each namespace requires a unique resource quota. The administrator has to create four different resource quotas that have the same specs configured (`Resource Quota 1-4`) and apply them individually. + +Base Kubernetes: Unique Resource Quotas Being Applied to Each Namespace + +![Native Kubernetes Resource Quota Implementation](/img/kubernetes-resource-quota.svg) + +Resource quotas are a little different in Rancher. In Rancher, you apply a resource quota to the project, and then the quota propagates to each namespace, whereafter Kubernetes enforces your limits using the native version of resource quotas. If you want to change the quota for a specific namespace, you can override it. + +The resource quota includes two limits, which you set while creating or editing a project: + + +- **Project Limits:** + + This set of values configures a total limit for each specified resource shared among all namespaces in the project. + +- **Namespace Default Limits:** + + This set of values configures the default quota limit available for each namespace for each specified resource. + When a namespace is created in the project without overrides, this limit is automatically bound to the namespace and enforced. + + +In the following diagram, a Rancher administrator wants to apply a resource quota that sets the same CPU and memory limit for every namespace in their project (`Namespace 1-4`). However, in Rancher, the administrator can set a resource quota for the project (`Project Resource Quota`) rather than individual namespaces. This quota includes resource limits for both the entire project (`Project Limit`) and individual namespaces (`Namespace Default Limit`). Rancher then propagates the `Namespace Default Limit` quotas to each namespace (`Namespace Resource Quota`) when created. + +Rancher: Resource Quotas Propagating to Each Namespace + +![Rancher Resource Quota Implementation](/img/rancher-resource-quota.png) + +Let's highlight some more nuanced functionality for namespaces created **_within_** the Rancher UI. If a quota is deleted at the project level, it will also be removed from all namespaces contained within that project, despite any overrides that may exist. Further, updating an existing namespace default limit for a quota at the project level will not result in that value being propagated to existing namespaces in the project; the updated value will only be applied to newly created namespaces in that project. To update a namespace default limit for existing namespaces you can delete and subsequently recreate the quota at the project level with the new default value. This will result in the new default value being applied to all existing namespaces in the project. + +Before creating a namespace in a project, Rancher compares the amounts of the project's available resources and requested resources, regardless of whether they come from the default or overridden limits. +If the requested resources exceed the remaining capacity in the project for those resources, Rancher will assign the namespace the remaining capacity for that resource. + +However, this is not the case with namespaces created **_outside_** of Rancher's UI. For namespaces created via `kubectl`, Rancher +will assign a resource quota that has a **zero** amount for any resource that requested more capacity than what remains in the project. + +To create a namespace in an existing project via `kubectl`, use the `field.cattle.io/projectId` annotation. To override the default +requested quota limit, use the `field.cattle.io/resourceQuota` annotation. + +Note that Rancher will only override limits for resources that are defined on the project quota. + +``` +apiVersion: v1 +kind: Namespace +metadata: + annotations: + field.cattle.io/projectId: [your-cluster-ID]:[your-project-ID] + field.cattle.io/resourceQuota: '{"limit":{"limitsCpu":"100m", "configMaps": "50"}}' + name: my-ns +``` +In this example, if the project's quota does not include configMaps in its list of resources, then Rancher will ignore `configMaps` in this override. + +Users are advised to create dedicated `ResourceQuota` objects in namespaces to configure additional custom limits for resources not defined on the project. +Resource quotas are native Kubernetes objects, and Rancher will ignore user-defined quotas in namespaces belonging to a project with a quota, +thus giving users more control. + +The following table explains the key differences between the two quota types. + +| Rancher Resource Quotas | Kubernetes Resource Quotas | +| ---------------------------------------------------------- | -------------------------------------------------------- | +| Applies to projects and namespace. | Applies to namespaces only. | +| Creates resource pool for all namespaces in project. | Applies static resource limits to individual namespaces. | +| Applies resource quotas to namespaces through propagation. | Applies only to the assigned namespace. diff --git a/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/manage-projects/manage-project-resource-quotas/manage-project-resource-quotas.md b/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/manage-projects/manage-project-resource-quotas/manage-project-resource-quotas.md new file mode 100644 index 00000000000..a0ed1060085 --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/manage-projects/manage-project-resource-quotas/manage-project-resource-quotas.md @@ -0,0 +1,50 @@ +--- +title: Project Resource Quotas +--- + + + + + +In situations where several teams share a cluster, one team may overconsume the resources available: CPU, memory, storage, services, Kubernetes objects like pods or secrets, and so on. To prevent this overconsumption, you can apply a _resource quota_, which is a Rancher feature that limits the resources available to a project or namespace. + +This page is a how-to guide for creating resource quotas in existing projects. + +Resource quotas can also be set when a new project is created. For details, refer to the section on [creating new projects.](../../../new-user-guides/manage-clusters/projects-and-namespaces.md#creating-projects) + +Resource quotas in Rancher include the same functionality as the [native version of Kubernetes](https://kubernetes.io/docs/concepts/policy/resource-quotas/). In Rancher, resource quotas have been extended so that you can apply them to projects. For details on how resource quotas work with projects in Rancher, refer to [this page.](about-project-resource-quotas.md) + +### Applying Resource Quotas to Existing Projects + +Edit resource quotas when: + +- You want to limit the resources that a project and its namespaces can use. +- You want to scale the resources available to a project up or down when a resource quota is already in effect. + +1. In the upper left corner, click **☰ > Cluster Management**. +1. On the **Clusters** page, go to the cluster where you want to apply a resource quota and click **Explore**. +1. Click **Cluster > Projects/Namespaces**. +1. Make sure that the **Projects/Namespaces** page is in **Group by Project** view mode. + ![Screenshot highlighting the "Group by Project" icon, above the list of projects. It resembles a folder.](/img/edit-project-config-for-resource-quotas-group-by-project.png) + +1. Find the project that you want to add a resource quota to, and select the **⋮** that's on the same row as the project's name. + ![Screenshot highlighting triple dots icon at the end of the same row as the project name.](/img/edit-project-config-for-resource-quotas-dots.png) + +1. Select **Edit Config**. + +1. Expand **Resource Quotas** and click **Add Resource**. Alternatively, you can edit existing quotas. + +1. Select a Resource Type. For more information on types, see the [quota type reference.](resource-quota-types.md) + +1. Enter values for the **Project Limit** and the **Namespace Default Limit**. + + | Field | Description | + | ----------------------- | -------------------------------------------------------------------------------------------------------- | + | Project Limit | The overall resource limit for the project. | + | Namespace Default Limit | The default resource limit available for each namespace. This limit is propagated to each namespace in the project. The combined limit of all project namespaces shouldn't exceed the project limit. | + +1. **Optional:** Add more quotas. + +1. Click **Create**. + +**Result:** The resource quota is applied to your project and namespaces. When you add more namespaces in the future, Rancher validates that the project can accommodate the namespace. If the project can't allocate the resources, you may still create namespaces, but they will be given a resource quota of 0. Subsequently, Rancher will not allow you to create any resources restricted by this quota. diff --git a/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/manage-projects/manage-project-resource-quotas/override-default-limit-in-namespaces.md b/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/manage-projects/manage-project-resource-quotas/override-default-limit-in-namespaces.md new file mode 100644 index 00000000000..9f6c8ca5655 --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/manage-projects/manage-project-resource-quotas/override-default-limit-in-namespaces.md @@ -0,0 +1,38 @@ +--- +title: Overriding the Default Limit for a Namespace +--- + + + + + +Although the **Namespace Default Limit** propagates from the project to each namespace when created, in some cases, you may need to increase (or decrease) the quotas for a specific namespace. In this situation, you can override the default limits by editing the namespace. + +In the diagram below, the Rancher administrator has a resource quota in effect for their project. However, the administrator wants to override the namespace limits for `Namespace 3` so that it has more resources available. Therefore, the administrator [raises the namespace limits](../../../new-user-guides/manage-clusters/projects-and-namespaces.md) for `Namespace 3` so that the namespace can access more resources. + +Namespace Default Limit Override + +![Namespace Default Limit Override](/img/rancher-resource-quota-override.svg) + +How to: [Editing Namespace Resource Quotas](../../../new-user-guides/manage-clusters/projects-and-namespaces.md) + +### Editing Namespace Resource Quotas + +If there is a resource quota configured for a project, you can override the namespace default limit to provide a specific namespace with access to more (or less) project resources. + +1. In the upper left corner, click **☰ > Cluster Management**. +1. On the **Clusters** page, go to the cluster where you want to edit a namespace resource quota and click **Explore**. +1. Click **Cluster > Projects/Namespaces**. +1. Find the namespace for which you want to edit the resource quota. Click **⋮ > Edit Config**. +1. Edit the resource limits. These limits determine the resources available to the namespace. The limits must be set within the configured project limits. + + For more information about each **Resource Type**, see [the type reference](resource-quota-types.md). + + :::note + + - If a resource quota is not configured for the project, these options will not be available. + - If you enter limits that exceed the configured project limits, Rancher will not let you save your edits. + + ::: + +**Result:** Your override is applied to the namespace's resource quota. diff --git a/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/manage-projects/manage-project-resource-quotas/resource-quota-types.md b/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/manage-projects/manage-project-resource-quotas/resource-quota-types.md new file mode 100644 index 00000000000..e789f5bf38b --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/manage-projects/manage-project-resource-quotas/resource-quota-types.md @@ -0,0 +1,31 @@ +--- +title: Resource Quota Type Reference +--- + + + + + +When you create a resource quota, you are configuring the pool of resources available to the project. You can set the following resource limits for the following resource types. + +| Resource Type | Description | +| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| CPU Limit* | The maximum amount of CPU (in [millicores](https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container/#meaning-of-cpu)) allocated to the project/namespace.1 | +| CPU Reservation* | The minimum amount of CPU (in millicores) guaranteed to the project/namespace.1 | +| Memory Limit* | The maximum amount of memory (in bytes) allocated to the project/namespace.1 | +| Memory Reservation* | The minimum amount of memory (in bytes) guaranteed to the project/namespace.1 | +| Storage Reservation | The minimum amount of storage (in gigabytes) guaranteed to the project/namespace. | +| Services Load Balancers | The maximum number of load balancers services that can exist in the project/namespace. | +| Services Node Ports | The maximum number of node port services that can exist in the project/namespace. | +| Pods | The maximum number of pods that can exist in the project/namespace in a non-terminal state (i.e., pods with a state of `.status.phase in (Failed, Succeeded)` equal to true). | +| Services | The maximum number of services that can exist in the project/namespace. | +| ConfigMaps | The maximum number of ConfigMaps that can exist in the project/namespace. | +| Persistent Volume Claims | The maximum number of persistent volume claims that can exist in the project/namespace. | +| Replications Controllers | The maximum number of replication controllers that can exist in the project/namespace. | +| Secrets | The maximum number of secrets that can exist in the project/namespace. | + +:::note ***** + +When setting resource quotas, if you set anything related to CPU or Memory (i.e. limits or reservations) on a project / namespace, all containers will require a respective CPU or Memory field set during creation. A container default resource limit can be set at the same time to avoid the need to explicitly set these limits for every workload. See the [Kubernetes documentation](https://kubernetes.io/docs/concepts/policy/resource-quotas/#requests-vs-limits) for more details on why this is required. + +::: \ No newline at end of file diff --git a/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/manage-projects/manage-project-resource-quotas/set-container-default-resource-limits.md b/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/manage-projects/manage-project-resource-quotas/set-container-default-resource-limits.md new file mode 100644 index 00000000000..dd4e3241319 --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/manage-projects/manage-project-resource-quotas/set-container-default-resource-limits.md @@ -0,0 +1,44 @@ +--- +title: Setting Container Default Resource Limits +--- + + + + + +When setting resource quotas, if you set anything related to CPU or Memory (i.e. limits or reservations) on a project / namespace, all containers will require a respective CPU or Memory field set during creation. See the [Kubernetes documentation](https://kubernetes.io/docs/concepts/policy/resource-quotas/#requests-vs-limits) for more details on why this is required. + +To avoid setting these limits on each and every container during workload creation, a default container resource limit can be specified on the namespace. + +### Editing the Container Default Resource Limit + +Edit the container default resource limit when: + +- You have a CPU or Memory resource quota set on a project, and want to supply the corresponding default values for a container. +- You want to edit the default container resource limit. + +1. In the upper left corner, click **☰ > Cluster Management**. +1. On the **Clusters** page, go to the cluster where you want to edit the default resource limit and click **Explore**. +1. Click **Cluster > Projects/Namespaces**. +1. Find the project that you want to edit the container default resource limit. From that project, select **⋮ > Edit Config**. +1. Expand **Container Default Resource Limit** and edit the values. + +### Resource Limit Propagation + +When the default container resource limit is set at a project level, the parameter will be propagated to any namespace created in the project after the limit has been set. For any existing namespace in a project, this limit will not be automatically propagated. You will need to manually set the default container resource limit for any existing namespaces in the project in order for it to be used when creating any containers. + +You can set a default container resource limit on a project and launch any catalog applications. + +Once a container default resource limit is configured on a namespace, the default will be pre-populated for any containers created in that namespace. These limits/reservations can always be overridden during workload creation. + +### Container Resource Quota Types + +The following resource limits can be configured: + +| Resource Type | Description | +| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| CPU Limit | The maximum amount of CPU (in [millicores](https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container/#meaning-of-cpu)) allocated to the container.| +| CPU Reservation | The minimum amount of CPU (in millicores) guaranteed to the container. | +| Memory Limit | The maximum amount of memory (in bytes) allocated to the container. | +| Memory Reservation | The minimum amount of memory (in bytes) guaranteed to the container. +| NVIDIA GPU Limit/Reservation | The amount of GPUs allocated to the container. The limit and reservation are always the same for GPUs. | diff --git a/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/manage-projects/manage-projects.md b/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/manage-projects/manage-projects.md new file mode 100644 index 00000000000..55c6fdd631a --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/manage-projects/manage-projects.md @@ -0,0 +1,40 @@ +--- +title: Project Administration +--- + + + + + +_Projects_ are objects introduced in Rancher that help organize namespaces in your Kubernetes cluster. You can use projects to create multi-tenant clusters, which allows a group of users to share the same underlying resources without interacting with each other's applications. + +In terms of hierarchy: + +- Clusters contain projects +- Projects contain namespaces + +Within Rancher, projects allow you to manage multiple namespaces as a single entity. In native Kubernetes, which does not include projects, features like role-based access rights or cluster resources are assigned to individual namespaces. In clusters where multiple namespaces require the same set of access rights, assigning these rights to each individual namespace can become tedious. Even though all namespaces require the same rights, there's no way to apply those rights to all of your namespaces in a single action. You'd have to repetitively assign these rights to each namespace! + +Rancher projects resolve this issue by allowing you to apply resources and access rights at the project level. Each namespace in the project then inherits these resources and policies, so you only have to assign them to the project once, rather than assigning them to each individual namespace. + +You can use projects to perform actions like: + +- [Assign users access to a group of namespaces](../../new-user-guides/add-users-to-projects.md) +- Assign users [specific roles in a project](../../new-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/cluster-and-project-roles.md#project-roles). A role can be owner, member, read-only, or [custom](../../new-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/custom-roles.md) +- [Set resource quotas](manage-project-resource-quotas/manage-project-resource-quotas.md) +- [Manage namespaces](../../new-user-guides/manage-namespaces.md) +- [Configure tools](../../../reference-guides/rancher-project-tools.md) + +### Authorization + +Non-administrative users are only authorized for project access after an [administrator](../../new-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/global-permissions.md), [cluster owner or member](../../new-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/cluster-and-project-roles.md#cluster-roles), or [project owner](../../new-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/cluster-and-project-roles.md#project-roles) adds them to the project's **Members** tab. + +Whoever creates the project automatically becomes a [project owner](../../new-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/cluster-and-project-roles.md#project-roles). + +## Switching between Projects + +To switch between projects, use the drop-down available in the navigation bar. Alternatively, you can switch between projects directly in the navigation bar. + +1. In the upper left corner, click **☰ > Cluster Management**. +1. On the **Clusters** page, go to the cluster where you want to switch projects and click **Explore**. +1. In the top navigation bar, select the project that you want to open. diff --git a/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/monitoring-alerting-guides/create-persistent-grafana-dashboard.md b/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/monitoring-alerting-guides/create-persistent-grafana-dashboard.md new file mode 100644 index 00000000000..ec292886fb3 --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/monitoring-alerting-guides/create-persistent-grafana-dashboard.md @@ -0,0 +1,159 @@ +--- +title: Persistent Grafana Dashboards +--- + + + + + +To allow the Grafana dashboard to persist after the Grafana instance restarts, add the dashboard configuration JSON into a ConfigMap. ConfigMaps also allow the dashboards to be deployed with a GitOps or CD based approach. This allows the dashboard to be put under version control. + +- [Creating a Persistent Grafana Dashboard](#creating-a-persistent-grafana-dashboard) +- [Known Issues](#known-issues) + +## Creating a Persistent Grafana Dashboard + + + + +:::note Prerequisites: + +- The monitoring application needs to be installed. +- To create the persistent dashboard, you must have at least the **Manage Config Maps** Rancher RBAC permissions assigned to you in the project or namespace that contains the Grafana Dashboards. This correlates to the `monitoring-dashboard-edit` or `monitoring-dashboard-admin` Kubernetes native RBAC Roles exposed by the Monitoring chart. +- To see the links to the external monitoring UIs, including Grafana dashboards, you will need at least a [project-member role.](../../../integrations-in-rancher/monitoring-and-alerting/rbac-for-monitoring.md#users-with-rancher-based-permissions) + +::: + +### 1. Get the JSON model of the dashboard that you want to persist + +To create a persistent dashboard, you will need to get the JSON model of the dashboard you want to persist. You can use a premade dashboard or build your own. + +To use a premade dashboard, go to [https://grafana.com/grafana/dashboards](https://grafana.com/grafana/dashboards), open up its detail page, and click on the **Download JSON** button to get the JSON model for the next step. + +To use your own dashboard: + +1. Click on the link to open Grafana. On the cluster detail page, click **Monitoring**. +1. Log in to Grafana. Note: The default Admin username and password for the Grafana instance is `admin/prom-operator`. Alternative credentials can also be supplied on deploying or upgrading the chart. + + :::note + + Regardless of who has the password, in order to access the Grafana instance, you still need at least the Manage Services or View Monitoring permissions in the project that Rancher Monitoring is deployed into. Alternative credentials can also be supplied on deploying or upgrading the chart. + + ::: + +1. Create a dashboard using Grafana's UI. Once complete, go to the dashboard's settings by clicking on the gear icon in the top navigation menu. In the left navigation menu, click **JSON Model**. +1. Copy the JSON data structure that appears. + +### 2. Create a ConfigMap using the Grafana JSON model + +Create a ConfigMap in the namespace that contains your Grafana Dashboards (e.g. `cattle-dashboards` by default). + +The ConfigMap should look like this: + +```yaml +apiVersion: v1 +kind: ConfigMap +metadata: + labels: + grafana_dashboard: "1" + name: + namespace: cattle-dashboards # Change if using a non-default namespace +data: + .json: |- + +``` + +By default, Grafana is configured to watch all ConfigMaps with the `grafana_dashboard` label within the `cattle-dashboards` namespace. + +To specify that you would like Grafana to watch for ConfigMaps across all namespaces, refer to [this section](#configuring-namespaces-for-the-grafana-dashboard-configmap). + +To create the ConfigMap through the Rancher UI, first make sure that you are currently logged in to the Grafana UI, to ensure that dashboards import without encountering permissions issues. Then, return to the Rancher UI and perform the following steps: + +1. In the upper left corner, click **☰ > Cluster Management**. +1. On the **Clusters** page, go to the cluster where you want to see the visualizations and click **Explore**. +1. Click **More Resources > Core > ConfigMaps**. +1. Click **Create**. +1. On the **Data** tab, set up the key-value pairs similar to the example above. When entering the value for `.json`, click **Read from File** to upload the JSON data model as the value. +1. On the **Labels & Annotations** tab, click **Add Label** and enter `grafana_dashboard` as the key, and `1` as the value. +1. Click **Create**. + +**Result:** After the ConfigMap is created, it should show up on the Grafana UI and be persisted even if the Grafana pod is restarted. + +:::note + +The actual key-value pair may differ if you have modified the Helm chart to watch a different dashboard label and value. + +::: + +Dashboards that are persisted using ConfigMaps cannot be deleted or edited from the Grafana UI. + +If you attempt to delete the dashboard in the Grafana UI, you will see the error message "Dashboard cannot be deleted because it was provisioned." To delete the dashboard, you will need to delete the ConfigMap. + +### Configuring Namespaces for the Grafana Dashboard ConfigMap + +To specify that you would like Grafana to watch for ConfigMaps across all namespaces, set this value in the `rancher-monitoring` Helm chart: + +``` +grafana.sidecar.dashboards.searchNamespace=ALL +``` + +Note that the RBAC roles exposed by the Monitoring chart to add Grafana Dashboards are still restricted to giving permissions for users to add dashboards in the namespace defined in `grafana.dashboards.namespace`, which defaults to `cattle-dashboards`. + + + + +:::note Prerequisites: + +- The monitoring application needs to be installed. +- You must have the cluster-admin ClusterRole permission. + +::: + +1. In the upper left corner, click **☰ > Cluster Management**. +1. On the **Clusters** page, go to the cluster where you want to configure the Grafana namespace and click **Explore**. +1. In the left navigation bar, click **Monitoring**. +1. Click **Grafana**. +1. Log in to Grafana. Note: The default Admin username and password for the Grafana instance is `admin/prom-operator`. Alternative credentials can also be supplied on deploying or upgrading the chart. + + :::note + + Regardless of who has the password, cluster administrator permission in Rancher is still required to access the Grafana instance. + + ::: + +1. Go to the dashboard that you want to persist. In the top navigation menu, go to the dashboard settings by clicking the gear icon. +1. In the left navigation menu, click **JSON Model**. +1. Copy the JSON data structure that appears. +1. Create a ConfigMap in the `cattle-dashboards` namespace. The ConfigMap needs to have the label `grafana_dashboard: "1"`. Paste the JSON into the ConfigMap in the format shown in the example below: + + ```yaml + apiVersion: v1 + kind: ConfigMap + metadata: + labels: + grafana_dashboard: "1" + name: + namespace: cattle-dashboards + data: + .json: |- + + ``` + +**Result:** After the ConfigMap is created, it should show up on the Grafana UI and be persisted even if the Grafana pod is restarted. + +Dashboards that are persisted using ConfigMaps cannot be deleted from the Grafana UI. If you attempt to delete the dashboard in the Grafana UI, you will see the error message "Dashboard cannot be deleted because it was provisioned." To delete the dashboard, you will need to delete the ConfigMap. + +To prevent the persistent dashboard from being deleted when Monitoring v2 is uninstalled, add the following annotation to the `cattle-dashboards` namespace: + +``` +helm.sh/resource-policy: "keep" +``` + + + + +## Known Issues + +For users who are using Monitoring V2 v9.4.203 or below, uninstalling the Monitoring chart will delete the `cattle-dashboards` namespace, which will delete all persisted dashboards, unless the namespace is marked with the annotation `helm.sh/resource-policy: "keep"`. + +This annotation will be added by default in the new monitoring chart released by Rancher v2.5.8, but it still needs to be manually applied for users of earlier Rancher versions. diff --git a/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/monitoring-alerting-guides/customize-grafana-dashboard.md b/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/monitoring-alerting-guides/customize-grafana-dashboard.md new file mode 100644 index 00000000000..c3b315f3e5b --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/monitoring-alerting-guides/customize-grafana-dashboard.md @@ -0,0 +1,43 @@ +--- +title: Customizing Grafana Dashboards +--- + + + + + +In this section, you'll learn how to customize the Grafana dashboard to show metrics that apply to a certain container. + +### Prerequisites + +Before you can customize a Grafana dashboard, the `rancher-monitoring` application must be installed. + +To see the links to the external monitoring UIs, including Grafana dashboards, you will need at least a [project-member role.](../../../integrations-in-rancher/monitoring-and-alerting/rbac-for-monitoring.md#users-with-rancher-based-permissions) + +### Signing in to Grafana + +1. In the Rancher UI, go to the cluster that has the dashboard you want to customize. +1. In the left navigation menu, click **Monitoring.** +1. Click **Grafana.** The Grafana dashboard should open in a new tab. +1. Go to the log in icon in the lower left corner and click **Sign In.** +1. Log in to Grafana. The default Admin username and password for the Grafana instance is `admin/prom-operator`. (Regardless of who has the password, cluster administrator permission in Rancher is still required access the Grafana instance.) Alternative credentials can also be supplied on deploying or upgrading the chart. + + +### Getting the PromQL Query Powering a Grafana Panel + +For any panel, you can click the title and click **Explore** to get the PromQL queries powering the graphic. + +For this example, we would like to get the CPU usage for the Alertmanager container, so we click **CPU Utilization > Inspect.** + +The **Data** tab shows the underlying data as a time series, with the time in first column and the PromQL query result in the second column. Copy the PromQL query. + +``` +(1 - (avg(irate({__name__=~"node_cpu_seconds_total|windows_cpu_time_total",mode="idle"}[5m])))) * 100 +``` + +You can then modify the query in the Grafana panel or create a new Grafana panel using the query. + +See also: + +- [Grafana docs on editing a panel](https://grafana.com/docs/grafana/latest/panels-visualizations/configure-panel-options/#edit-a-panel) +- [Grafana docs on adding a panel to a dashboard](https://grafana.com/docs/grafana/latest/panels-visualizations/panel-editor-overview) diff --git a/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/monitoring-alerting-guides/debug-high-memory-usage.md b/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/monitoring-alerting-guides/debug-high-memory-usage.md new file mode 100644 index 00000000000..020b06924d6 --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/monitoring-alerting-guides/debug-high-memory-usage.md @@ -0,0 +1,23 @@ +--- +title: Debugging High Memory Usage +--- + + + + + +Every time series in Prometheus is uniquely identified by its [metric name](https://prometheus.io/docs/practices/naming/#metric-names) and optional key-value pairs called [labels.](https://prometheus.io/docs/practices/naming/#labels) + +The labels allow the ability to filter and aggregate the time series data, but they also multiply the amount of data that Prometheus collects. + +Each time series has a defined set of labels, and Prometheus generates a new time series for all unique combinations of labels. If a metric has two labels attached, two time series are generated for that metric. Changing any label value, including adding or removing a label, will create a new time series. + +Prometheus is optimized to store data that is index-based on series. It is designed for a relatively consistent number of time series and a relatively large number of samples that need to be collected from the exporters over time. + +Inversely, Prometheus is not optimized to accommodate a rapidly changing number of time series. For that reason, large bursts of memory usage can occur when monitoring is installed on clusters where many resources are being created and destroyed, especially on multi-tenant clusters. + +### Reducing Memory Bursts + +To reduce memory consumption, Prometheus can be configured to store fewer time series, by scraping fewer metrics or by attaching fewer labels to the time series. To see which series use the most memory, you can check the TSDB (time series database) status page in the Prometheus UI. + +Distributed Prometheus solutions such as [Thanos](https://thanos.io/) and [Cortex](https://cortexmetrics.io/) use an alternate architecture in which multiple small Prometheus instances are deployed. In the case of Thanos, the metrics from each Prometheus are aggregated into the common Thanos deployment, and then those metrics are exported to a persistent store, such as S3. This more robust architecture avoids burdening any single Prometheus instance with too many time series, while also preserving the ability to query metrics on a global level. \ No newline at end of file diff --git a/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/monitoring-alerting-guides/enable-monitoring.md b/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/monitoring-alerting-guides/enable-monitoring.md new file mode 100644 index 00000000000..c1f3f7a1aba --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/monitoring-alerting-guides/enable-monitoring.md @@ -0,0 +1,147 @@ +--- +title: Enable Monitoring +--- + + + + + +As an [administrator](../../new-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/global-permissions.md) or [cluster owner](../../new-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/cluster-and-project-roles.md#cluster-roles), you can configure Rancher to deploy Prometheus to monitor your Kubernetes cluster. + +This page describes how to enable monitoring and alerting within a cluster using the new monitoring application. + +You can enable monitoring with or without SSL. + +## Requirements + +- Allow traffic on port 9796 for each of your nodes. Prometheus scrapes metrics from these ports. + - You may also need to allow traffic on port 10254 for each of your nodes, if [PushProx](../../../integrations-in-rancher/monitoring-and-alerting/how-monitoring-works.md#pushprox) is disabled (`ingressNginx.enabled` set to `false`), or you've upgraded from a previous Rancher version that had v1 monitoring already installed. +- Make sure that your cluster fulfills the resource requirements. The cluster should have at least 1950Mi memory available, 2700m CPU, and 50Gi storage. See [Configuring Resource Limits and Requests](../../../reference-guides/monitoring-v2-configuration/helm-chart-options.md#configuring-resource-limits-and-requests) for a breakdown of the resource limits and requests. + +:::note + +If you want to set up Alertmanager, Grafana or Ingress, it has to be done with the settings on the Helm chart deployment. It's problematic to create Ingress outside the deployment. + +::: + +## Setting Resource Limits and Requests + +The resource requests and limits can be configured when installing `rancher-monitoring`. To configure Prometheus resources from the Rancher UI, click **Apps > Monitoring** in the upper left corner. + +For more information about the default limits, see [this page.](../../../reference-guides/monitoring-v2-configuration/helm-chart-options.md#configuring-resource-limits-and-requests) + +## Install the Monitoring Application + +### Enable Monitoring for use without SSL + +1. Click **☰ > Cluster Management**. +1. Go to the cluster that you created and click **Explore**. +1. Click **Cluster Tools** (bottom left corner). +1. Click **Install** by Monitoring. +1. Optional: Customize requests, limits and more for Alerting, Prometheus, and Grafana in the Values step. For help, refer to the [configuration reference.](../../../reference-guides/monitoring-v2-configuration/helm-chart-options.md) + +**Result:** The monitoring app is deployed in the `cattle-monitoring-system` namespace. + +### Enable Monitoring for use with SSL + +1. Follow the steps on [this page](../../new-user-guides/kubernetes-resources-setup/secrets.md) to create a secret in order for SSL to be used for alerts. + - The secret should be created in the `cattle-monitoring-system` namespace. If it doesn't exist, create it first. + - Add the `ca`, `cert`, and `key` files to the secret. +1. In the upper left corner, click **☰ > Cluster Management**. +1. On the **Clusters** page, go to the cluster where you want to enable monitoring for use with SSL and click **Explore**. +1. Click **Apps > Charts**. +1. Click **Monitoring**. +1. Click **Install** or **Update**, depending on whether you have already installed Monitoring. +1. Check the box for **Customize Helm options before install** and click **Next**. +1. Click **Alerting**. +1. In the **Additional Secrets** field, add the secrets created earlier. + +**Result:** The monitoring app is deployed in the `cattle-monitoring-system` namespace. + +When [creating a receiver,](../../../reference-guides/monitoring-v2-configuration/receivers.md#creating-receivers-in-the-rancher-ui) SSL-enabled receivers such as email or webhook will have a **SSL** section with fields for **CA File Path**, **Cert File Path**, and **Key File Path**. Fill in these fields with the paths to each of `ca`, `cert`, and `key`. The path will be of the form `/etc/alertmanager/secrets/name-of-file-in-secret`. + +For example, if you created a secret with these key-value pairs: + +```yaml +ca.crt=`base64-content` +cert.pem=`base64-content` +key.pfx=`base64-content` +``` + +Then **Cert File Path** would be set to `/etc/alertmanager/secrets/cert.pem`. + +## Rancher Performance Dashboard + +When monitoring is installed on the upstream (local) cluster, you are given basic health metrics about the Rancher pods, such as CPU and memory data. To get advanced metrics for your local Rancher server, you must additionally enable the Rancher Performance Dashboard for Grafana. + +This dashboard provides access to the following advanced metrics: + +- Handler Average Execution Times Over Last 5 Minutes +- Rancher API Average Request Times Over Last 5 Minutes +- Subscribe Average Request Times Over Last 5 Minutes +- Lasso Controller Work Queue Depth (Top 20) +- Number of Rancher Requests (Top 20) +- Number of Failed Rancher API Requests (Top 20) +- K8s Proxy Store Average Request Times Over Last 5 Minutes (Top 20) +- K8s Proxy Client Average Request Times Over Last 5 Minutes (Top 20) +- Cached Objects by GroupVersionKind (Top 20) +- Lasso Handler Executions (Top 20) +- Handler Executions Over Last 2 Minutes (Top 20) +- Total Handler Executions with Error (Top 20) +- Data Transmitted by Remote Dialer Sessions (Top 20) +- Errors for Remote Dialer Sessions (Top 20) +- Remote Dialer Connections Removed (Top 20) +- Remote Dialer Connections Added by Client (Top 20) + +:::note + +Profiling data (such as advanced memory or CPU analysis) is not present as it is a very context-dependent technique that's meant for debugging and not intended for normal observation. + +::: + +### Enabling the Rancher Performance Dashboard + +To enable the Rancher Performance Dashboard: + + + + +Use the following options with the Helm CLI: + +```bash +--set extraEnv\[0\].name="CATTLE_PROMETHEUS_METRICS" --set-string extraEnv\[0\].value=true +``` + +You can also include the following snippet in your Rancher Helm chart's values.yaml file: + +```yaml +extraEnv: + - name: "CATTLE_PROMETHEUS_METRICS" + value: "true" +``` + + + + +1. Click **☰ > Cluster Management**. +1. Go to the row of the `local` cluster and click **Explore**. +1. Click **Workloads > Deployments**. +1. Use the dropdown menu at the top to filter for **All Namespaces**. +1. Under the `cattle-system` namespace, go to the `rancher` row and click **⋮ > Edit Config** +1. Under **Environment Variables**, click **Add Variable**. +1. For **Type**, select `Key/Value Pair`. +1. For **Variable Name**, enter `CATTLE_PROMETHEUS_METRICS`. +1. For **Value**, enter `true`. +1. Click **Save** to apply the change. + + + + +### Accessing the Rancher Performance Dashboard + +1. Click **☰ > Cluster Management**. +1. Go to the row of the `local` cluster and click **Explore**. +1. Click **Monitoring** +1. Select the **Grafana** dashboard. +1. From the sidebar, click **Search dashboards**. +1. Enter `Rancher Performance Debugging` and select it. diff --git a/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/monitoring-alerting-guides/monitoring-alerting-guides.md b/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/monitoring-alerting-guides/monitoring-alerting-guides.md new file mode 100644 index 00000000000..d5ac47c78f4 --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/monitoring-alerting-guides/monitoring-alerting-guides.md @@ -0,0 +1,14 @@ +--- +title: Monitoring/Alerting Guides +--- + + + + + +- [Enable monitoring](enable-monitoring.md) +- [Uninstall monitoring](uninstall-monitoring.md) +- [Monitoring workloads](set-up-monitoring-for-workloads.md) +- [Customizing Grafana dashboards](customize-grafana-dashboard.md) +- [Persistent Grafana dashboards](create-persistent-grafana-dashboard.md) +- [Debugging high memory usage](debug-high-memory-usage.md) diff --git a/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/monitoring-alerting-guides/prometheus-federator-guides/customize-grafana-dashboards.md b/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/monitoring-alerting-guides/prometheus-federator-guides/customize-grafana-dashboards.md new file mode 100644 index 00000000000..50a45a16216 --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/monitoring-alerting-guides/prometheus-federator-guides/customize-grafana-dashboards.md @@ -0,0 +1,11 @@ +--- +title: Customizing Grafana Dashboards +--- + + + + + +Grafana dashboards are customized the same way whether it's for rancher-monitoring or for Prometheus Federator. + +For instructions, refer to [this page](../customize-grafana-dashboard.md). \ No newline at end of file diff --git a/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/monitoring-alerting-guides/prometheus-federator-guides/enable-prometheus-federator.md b/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/monitoring-alerting-guides/prometheus-federator-guides/enable-prometheus-federator.md new file mode 100644 index 00000000000..589875199e8 --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/monitoring-alerting-guides/prometheus-federator-guides/enable-prometheus-federator.md @@ -0,0 +1,90 @@ +--- +title: Enable Prometheus Federator +--- + + + + + +## Requirements + +By default, Prometheus Federator is configured and intended to be deployed alongside [rancher-monitoring](../../../../integrations-in-rancher/monitoring-and-alerting/monitoring-and-alerting.md), which deploys Prometheus Operator alongside a Cluster Prometheus that each Project Monitoring Stack is configured to federate namespace-scoped metrics from by default. + +For instructions on installing rancher-monitoring, refer to [this page](../enable-monitoring.md). + +The default configuration should already be compatible with your rancher-monitoring stack. However, to optimize the security and usability of Prometheus Federator in your cluster, we recommend making these additional configurations to rancher-monitoring: + +- [Ensure the cattle-monitoring-system namespace is placed into the System Project](#ensure-the-cattle-monitoring-system-namespace-is-placed-into-the-system-project-or-a-similarly-locked-down-project-that-has-access-to-other-projects-in-the-cluster). +- [Configure rancher-monitoring to only watch for resources created by the Helm chart itself](#configure-rancher-monitoring-to-only-watch-for-resources-created-by-the-helm-chart-itself). +- [Increase the CPU / memory limits of the Cluster Prometheus](#increase-the-cpu--memory-limits-of-the-cluster-prometheus). + +### Ensure the cattle-monitoring-system namespace is placed into the System Project (or a similarly locked down Project that has access to other Projects in the cluster) + +![Select Projects-Namespaces](/img/install-in-system-project.png) + +Prometheus Operator's security model expects that the namespace it is deployed into (e.g., `cattle-monitoring-system`) has limited access for anyone except Cluster Admins to avoid privilege escalation via execing into Pods (such as the Jobs executing Helm operations). In addition, deploying Prometheus Federator and all Project Prometheus stacks into the System Project ensures that each Project Prometheus is able to reach out to scrape workloads across all Projects, even if Network Policies are defined via Project Network Isolation. It also provides limited access for Project Owners, Project Members, and other users so that they're unable to access data that they shouldn't have access to (i.e., being allowed to exec into pods, set up the ability to scrape namespaces outside of a given Project, etc.). + +1. Open the `System` project to check your namespaces: + + Click **Cluster > Projects/Namespaces** in the Rancher UI. This will display all of the namespaces in the `System` project: + + ![Select Projects-Namespaces](/img/cattle-monitoring-system.png) + +1. If you have an existing Monitoring V2 installation within the `cattle-monitoring-system` namespace, but that namespace is not in the `System` project, you may move the `cattle-monitoring-system` namespace into the `System` project or into another project of limited access. To do so, you may either: + + - Drag and drop the namespace into the `System` project or + - Select **⋮** to the right of the namespace, click **Move**, then choose `System` from the **Target Project** dropdown + + ![Move to a New Project](/img/move-to-new-project.png) + +### Configure rancher-monitoring to only watch for resources created by the Helm chart itself + +Since each Project Monitoring Stack will watch the other namespaces and collect additional custom workload metrics or dashboards already, it's recommended to configure the following settings on all selectors to ensure that the Cluster Prometheus Stack only monitors resources created by the Helm Chart itself: + +``` +matchLabels: + release: "rancher-monitoring" +``` + +The following selector fields are recommended to have this value: +- `.Values.alertmanager.alertmanagerSpec.alertmanagerConfigSelector` +- `.Values.prometheus.prometheusSpec.serviceMonitorSelector` +- `.Values.prometheus.prometheusSpec.podMonitorSelector` +- `.Values.prometheus.prometheusSpec.ruleSelector` +- `.Values.prometheus.prometheusSpec.probeSelector` + +Once this setting is turned on, you can always create ServiceMonitors or PodMonitors that are picked up by the Cluster Prometheus by adding the label `release: "rancher-monitoring"` to them, in which case they will be ignored by Project Monitoring Stacks automatically by default, even if the namespace in which those ServiceMonitors or PodMonitors reside in are not system namespaces. + +:::note + +If you don't want to allow users to be able to create ServiceMonitors and PodMonitors that aggregate into the Cluster Prometheus in Project namespaces, you can additionally set the namespaceSelectors on the chart to only target system namespaces (which must contain `cattle-monitoring-system` and `cattle-dashboards`, where resources are deployed into by default by rancher-monitoring; you will also need to monitor the `default` namespace to get apiserver metrics or create a custom ServiceMonitor to scrape apiserver metrics from the Service residing in the default namespace) to limit your Cluster Prometheus from picking up other Prometheus Operator CRs. In that case, it would be recommended to turn `.Values.prometheus.prometheusSpec.ignoreNamespaceSelectors=true` to allow you to define ServiceMonitors that can monitor non-system namespaces from within a system namespace. + +::: + +### Increase the CPU / memory limits of the Cluster Prometheus + +Depending on a cluster's setup, it's generally recommended to give a large amount of dedicated memory to the Cluster Prometheus to avoid restarts due to out-of-memory errors (OOMKilled) usually caused by churn created in the cluster that causes a large number of high cardinality metrics to be generated and ingested by Prometheus within one block of time. This is one of the reasons why the default Rancher Monitoring stack expects around 4GB of RAM to be able to operate in a normal-sized cluster. However, when introducing Project Monitoring Stacks that are all sending `/federate` requests to the same Cluster Prometheus and are reliant on the Cluster Prometheus being "up" to federate that system data on their namespaces, it's even more important that the Cluster Prometheus has an ample amount of CPU / memory assigned to it to prevent an outage that can cause data gaps across all Project Prometheis in the cluster. + +:::note + +There are no specific recommendations on how much memory the Cluster Prometheus should be configured with since it depends entirely on the user's setup (namely the likelihood of encountering a high churn rate and the scale of metrics that could be generated at that time); it generally varies per setup. + +::: + +## Install the Prometheus Federator Application + +1. Click **☰ > Cluster Management**. +1. Go to the cluster that you want to install Prometheus Federator and click **Explore**. +1. Click **Apps -> Charts**. +1. Click the **Prometheus Federator** chart. +1. Click **Install**. +1. On the **Metadata** page, click **Next**. +1. In the **Namespaces** > **Project Release Namespace Project ID** field, the `System Project` is used as the default but can be overridden with another project with similarly [limited access](#ensure-the-cattle-monitoring-system-namespace-is-placed-into-the-system-project-or-a-similarly-locked-down-project-that-has-access-to-other-projects-in-the-cluster). Project IDs can be found with the following command run in the local upstream cluster: + + ```plain + kubectl get projects -A -o custom-columns="NAMESPACE":.metadata.namespace,"ID":.metadata.name,"NAME":.spec.displayName + ``` + +1. Click **Install**. + +**Result:** The Prometheus Federator app is deployed in the `cattle-monitoring-system` namespace. diff --git a/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/monitoring-alerting-guides/prometheus-federator-guides/project-monitors.md b/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/monitoring-alerting-guides/prometheus-federator-guides/project-monitors.md new file mode 100644 index 00000000000..8efe48f4ae8 --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/monitoring-alerting-guides/prometheus-federator-guides/project-monitors.md @@ -0,0 +1,21 @@ +--- +title: Installing Project Monitors +--- + + + + + +Install **Project Monitors** in each project where you want to enable project monitoring. + +1. Click **☰ > Cluster Management**. + +1. On the **Clusters** page, go to the cluster where you want to enable monitoring and click **Explore**. + +1. Click **Monitoring > Project Monitors** on the left nav bar. Then click **Create** in the upper right. + + ![Project Monitors](/img/project-monitors.png) + +1. Select your project from the drop-down menu, then click **Create** again. + + ![Create Project Monitors](/img/create-project-monitors.png) diff --git a/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/monitoring-alerting-guides/prometheus-federator-guides/prometheus-federator-guides.md b/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/monitoring-alerting-guides/prometheus-federator-guides/prometheus-federator-guides.md new file mode 100644 index 00000000000..c266c30f1c6 --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/monitoring-alerting-guides/prometheus-federator-guides/prometheus-federator-guides.md @@ -0,0 +1,12 @@ +--- +title: Prometheus Federator Guides +--- + + + + + +- [Enable Prometheus Operator](enable-prometheus-federator.md) +- [Uninstall Prometheus Operator](uninstall-prometheus-federator.md) +- [Customize Grafana Dashboards](customize-grafana-dashboards.md) +- [Set Up Workloads](set-up-workloads.md) \ No newline at end of file diff --git a/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/monitoring-alerting-guides/prometheus-federator-guides/set-up-workloads.md b/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/monitoring-alerting-guides/prometheus-federator-guides/set-up-workloads.md new file mode 100644 index 00000000000..d816f9b9e68 --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/monitoring-alerting-guides/prometheus-federator-guides/set-up-workloads.md @@ -0,0 +1,17 @@ +--- +title: Setting up Prometheus Federator for a Workload +--- + + + + + +### Display CPU and Memory Metrics for a Workload + +Displaying CPU and memory metrics with Prometheus Federator is done the same way as with rancher-monitoring. For instructions, refer [here](../set-up-monitoring-for-workloads.md#display-cpu-and-memory-metrics-for-a-workload). + +### Setting up Metrics Beyond CPU and Memory + +Setting up metrics beyond CPU and memory with Prometheus Federator is done the same way as with rancher-monitoring. For instructions, refer [here](../set-up-monitoring-for-workloads.md#setting-up-metrics-beyond-cpu-and-memory). + + diff --git a/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/monitoring-alerting-guides/prometheus-federator-guides/uninstall-prometheus-federator.md b/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/monitoring-alerting-guides/prometheus-federator-guides/uninstall-prometheus-federator.md new file mode 100644 index 00000000000..d5703cf33aa --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/monitoring-alerting-guides/prometheus-federator-guides/uninstall-prometheus-federator.md @@ -0,0 +1,17 @@ +--- +title: Uninstall Prometheus Federator +--- + + + + + +1. Click **☰ > Cluster Management**. +1. Go to the cluster that you created and click **Explore**. +1. In the left navigation bar, click **Apps**. +1. Click **Installed Apps**. +1. Go to the `cattle-monitoring-system` namespace and check the boxes for `rancher-monitoring-crd` and `rancher-monitoring`. +1. Click **Delete**. +1. Confirm **Delete**. + +**Result:** `prometheus-federator` is uninstalled. diff --git a/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/monitoring-alerting-guides/set-up-monitoring-for-workloads.md b/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/monitoring-alerting-guides/set-up-monitoring-for-workloads.md new file mode 100644 index 00000000000..e2fe488780e --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/monitoring-alerting-guides/set-up-monitoring-for-workloads.md @@ -0,0 +1,31 @@ +--- +title: Setting up Monitoring for a Workload +--- + + + + + +If you only need CPU and memory time series for the workload, you don't need to deploy a ServiceMonitor or PodMonitor because the monitoring application already collects metrics data on resource usage by default. + +The steps for setting up monitoring for workloads depend on whether you want basic metrics such as CPU and memory for the workload, or whether you want to scrape custom metrics from the workload. + +If you only need CPU and memory time series for the workload, you don't need to deploy a ServiceMonitor or PodMonitor because the monitoring application already collects metrics data on resource usage by default. The resource usage time series data is in Prometheus's local time series database. + +Grafana shows the data in aggregate, but you can see the data for the individual workload by using a PromQL query that extracts the data for that workload. Once you have the PromQL query, you can execute the query individually in the Prometheus UI and see the time series visualized there, or you can use the query to customize a Grafana dashboard to display the workload metrics. For examples of PromQL queries for workload metrics, see [this section](../../../integrations-in-rancher/monitoring-and-alerting/promql-expressions.md#workload-metrics). + +To set up custom metrics for your workload, you will need to set up an exporter and create a new ServiceMonitor custom resource to configure Prometheus to scrape metrics from your exporter. + +### Display CPU and Memory Metrics for a Workload + +By default, the monitoring application already scrapes CPU and memory. + +To get some fine-grained detail for a particular workload, you can customize a Grafana dashboard to display the metrics for a particular workload. + +### Setting up Metrics Beyond CPU and Memory + +For custom metrics, you will need to expose the metrics on your application in a format supported by Prometheus. + +Then we recommend that you should create a new ServiceMonitor custom resource. When this resource is created, the Prometheus custom resource will be automatically updated so that its scrape configuration includes the new custom metrics endpoint. Then Prometheus will begin scraping metrics from the endpoint. + +You can also create a PodMonitor to expose the custom metrics endpoint, but ServiceMonitors are more appropriate for the majority of use cases. diff --git a/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/monitoring-alerting-guides/uninstall-monitoring.md b/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/monitoring-alerting-guides/uninstall-monitoring.md new file mode 100644 index 00000000000..688d54a0506 --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/monitoring-alerting-guides/uninstall-monitoring.md @@ -0,0 +1,23 @@ +--- +title: Uninstall Monitoring +--- + + + + + +1. Click **☰ > Cluster Management**. +1. Go to the cluster that you created and click **Explore**. +1. In the left navigation bar, click **Apps**. +1. Click **Installed Apps**. +1. Go to the `cattle-monitoring-system` namespace and check the boxes for `rancher-monitoring-crd` and `rancher-monitoring`. +1. Click **Delete**. +1. Confirm **Delete**. + +**Result:** `rancher-monitoring` is uninstalled. + +:::note Persistent Grafana Dashboards: + +For users who are using Monitoring V2 v9.4.203 or below, uninstalling the Monitoring chart will delete the cattle-dashboards namespace, which will delete all persisted dashboards, unless the namespace is marked with the annotation `helm.sh/resource-policy: "keep"`. This annotation is added by default in Monitoring V2 v14.5.100+ but can be manually applied on the cattle-dashboards namespace before an uninstall if an older version of the Monitoring chart is currently installed onto your cluster. + +::: \ No newline at end of file diff --git a/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/monitoring-v2-configuration-guides/advanced-configuration/advanced-configuration.md b/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/monitoring-v2-configuration-guides/advanced-configuration/advanced-configuration.md new file mode 100644 index 00000000000..16d99c82a75 --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/monitoring-v2-configuration-guides/advanced-configuration/advanced-configuration.md @@ -0,0 +1,19 @@ +--- +title: Advanced Configuration +--- + + + + + +### Alertmanager + +For information on configuring the Alertmanager custom resource, see [this page.](alertmanager.md) + +### Prometheus + +For information on configuring the Prometheus custom resource, see [this page.](prometheus.md) + +### PrometheusRules + +For information on configuring the Prometheus custom resource, see [this page.](prometheusrules.md) \ No newline at end of file diff --git a/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/monitoring-v2-configuration-guides/advanced-configuration/alertmanager.md b/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/monitoring-v2-configuration-guides/advanced-configuration/alertmanager.md new file mode 100644 index 00000000000..bc213ee0637 --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/monitoring-v2-configuration-guides/advanced-configuration/alertmanager.md @@ -0,0 +1,47 @@ +--- +title: Alertmanager Configuration +--- + + + + + +It is usually not necessary to directly edit the Alertmanager custom resource. For most use cases, you will only need to edit the Receivers and Routes to configure notifications. + +When Receivers and Routes are updated, the monitoring application will automatically update the Alertmanager custom resource to be consistent with those changes. + +:::note + +This section assumes familiarity with how monitoring components work together. For more information about Alertmanager, see [this section.](../../../../integrations-in-rancher/monitoring-and-alerting/how-monitoring-works.md#3-how-alertmanager-works) + +::: + +## About the Alertmanager Custom Resource + +By default, Rancher Monitoring deploys a single Alertmanager onto a cluster that uses a default Alertmanager Config Secret. + +You may want to edit the Alertmanager custom resource if you would like to take advantage of advanced options that are not exposed in the Rancher UI forms, such as the ability to create a routing tree structure that is more than two levels deep. + +It is also possible to create more than one Alertmanager in a cluster, which may be useful if you want to implement namespace-scoped monitoring. In this case, you should manage the Alertmanager custom resources using the same underlying Alertmanager Config Secret. + +### Deeply Nested Routes + +While the Rancher UI only supports a routing tree that is two levels deep, you can configure more deeply nested routing structures by editing the Alertmanager YAML. + +### Multiple Alertmanager Replicas + +As part of the chart deployment options, you can opt to increase the number of replicas of the Alertmanager deployed onto your cluster. The replicas can all be managed using the same underlying Alertmanager Config Secret. + +This Secret should be updated or modified any time you want to: + +- Add in new notifiers or receivers +- Change the alerts that should be sent to specific notifiers or receivers +- Change the group of alerts that are sent out + +By default, you can either choose to supply an existing Alertmanager Config Secret (i.e. any Secret in the `cattle-monitoring-system` namespace) or allow Rancher Monitoring to deploy a default Alertmanager Config Secret onto your cluster. + +By default, the Alertmanager Config Secret created by Rancher will never be modified or deleted on an upgrade or uninstall of the `rancher-monitoring` chart. This restriction prevents users from losing or overwriting their alerting configuration when executing operations on the chart. + +For more information on what fields can be specified in the Alertmanager Config Secret, please look at the [Prometheus Alertmanager docs.](https://prometheus.io/docs/alerting/latest/alertmanager/) + +The full spec for the Alertmanager configuration file and what it takes in can be found [here.](https://prometheus.io/docs/alerting/latest/configuration/#configuration-file) \ No newline at end of file diff --git a/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/monitoring-v2-configuration-guides/advanced-configuration/prometheus.md b/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/monitoring-v2-configuration-guides/advanced-configuration/prometheus.md new file mode 100644 index 00000000000..122316d018d --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/monitoring-v2-configuration-guides/advanced-configuration/prometheus.md @@ -0,0 +1,23 @@ +--- +title: Prometheus Configuration +--- + + + + + +It is usually not necessary to directly edit the Prometheus custom resource because the monitoring application automatically updates it based on changes to ServiceMonitors and PodMonitors. + +:::note + +This section assumes familiarity with how monitoring components work together. For more information, see [this section.](../../../../integrations-in-rancher/monitoring-and-alerting/how-monitoring-works.md) + +::: + +## About the Prometheus Custom Resource + +The Prometheus CR defines a desired Prometheus deployment. The Prometheus Operator observes the Prometheus CR. When the CR changes, the Prometheus Operator creates `prometheus-rancher-monitoring-prometheus`, a Prometheus deployment based on the CR configuration. + +The Prometheus CR specifies details such as rules and what Alertmanagers are connected to Prometheus. Rancher builds this CR for you. + +Monitoring V2 only supports one Prometheus per cluster. However, you might want to edit the Prometheus CR if you want to limit monitoring to certain namespaces. \ No newline at end of file diff --git a/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/monitoring-v2-configuration-guides/advanced-configuration/prometheusrules.md b/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/monitoring-v2-configuration-guides/advanced-configuration/prometheusrules.md new file mode 100644 index 00000000000..cacbf5c1197 --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/monitoring-v2-configuration-guides/advanced-configuration/prometheusrules.md @@ -0,0 +1,84 @@ +--- +title: Configuring PrometheusRules +--- + + + + + +A PrometheusRule defines a group of Prometheus alerting and/or recording rules. + +:::note + +This section assumes familiarity with how monitoring components work together. For more information, see [this section.](../../../../integrations-in-rancher/monitoring-and-alerting/how-monitoring-works.md) + +::: + +### Creating PrometheusRules in the Rancher UI + +:::note Prerequisite: + +The monitoring application needs to be installed. + +::: + +To create rule groups in the Rancher UI, + +1. Go to the cluster where you want to create rule groups. Click **Monitoring > Advanced** and click **Prometheus Rules**. +1. Click **Create**. +1. Enter a **Group Name**. +1. Configure the rules. In Rancher's UI, we expect a rule group to contain either alert rules or recording rules, but not both. For help filling out the forms, refer to the configuration options below. +1. Click **Create**. + +**Result:** Alerts can be configured to send notifications to the receiver(s). + +### About the PrometheusRule Custom Resource + +When you define a Rule (which is declared within a RuleGroup in a PrometheusRule resource), the [spec of the Rule itself](https://github.com/prometheus-operator/prometheus-operator/blob/main/Documentation/api-reference/api.md#rule) contains labels that are used by Alertmanager to figure out which Route should receive this Alert. For example, an Alert with the label `team: front-end` will be sent to all Routes that match on that label. + +Prometheus rule files are held in PrometheusRule custom resources. A PrometheusRule allows you to define one or more RuleGroups. Each RuleGroup consists of a set of Rule objects that can each represent either an alerting or a recording rule with the following fields: + +- The name of the new alert or record +- A PromQL expression for the new alert or record +- Labels that should be attached to the alert or record that identify it (e.g. cluster name or severity) +- Annotations that encode any additional important pieces of information that need to be displayed on the notification for an alert (e.g. summary, description, message, runbook URL, etc.). This field is not required for recording rules. + +For more information on what fields can be specified, please look at the [Prometheus Operator spec.](https://github.com/prometheus-operator/prometheus-operator/blob/main/Documentation/api-reference/api.md#prometheusrulespec) + +Use the label selector field `ruleSelector` in the Prometheus object to define the rule files that you want to be mounted into Prometheus. + +For examples, refer to the Prometheus documentation on [recording rules](https://prometheus.io/docs/prometheus/latest/configuration/recording_rules/) and [alerting rules.](https://prometheus.io/docs/prometheus/latest/configuration/alerting_rules/) + +## Configuration + +### Rule Group + +| Field | Description | +|-------|----------------| +| Group Name | The name of the group. Must be unique within a rules file. | +| Override Group Interval | Duration in seconds for how often rules in the group are evaluated. | + + +### Alerting Rules + +[Alerting rules](https://prometheus.io/docs/prometheus/latest/configuration/alerting_rules/) allow you to define alert conditions based on PromQL (Prometheus Query Language) expressions and to send notifications about firing alerts to an external service. + +| Field | Description | +|-------|----------------| +| Alert Name | The name of the alert. Must be a valid label value. | +| Wait To Fire For | Duration in seconds. Alerts are considered firing once they have been returned for this long. Alerts which have not yet fired for long enough are considered pending. | +| PromQL Expression | The PromQL expression to evaluate. Prometheus will evaluate the current value of this PromQL expression on every evaluation cycle and all resultant time series will become pending/firing alerts. For more information, refer to the [Prometheus documentation](https://prometheus.io/docs/prometheus/latest/querying/basics/) or our [example PromQL expressions.](../../../../integrations-in-rancher/monitoring-and-alerting/promql-expressions.md) | +| Labels | Labels to add or overwrite for each alert. | +| Severity | When enabled, labels are attached to the alert or record that identify it by the severity level. | +| Severity Label Value | Critical, warning, or none | +| Annotations | Annotations are a set of informational labels that can be used to store longer additional information, such as alert descriptions or runbook links. A [runbook](https://en.wikipedia.org/wiki/Runbook) is a set of documentation about how to handle alerts. The annotation values can be [templated.](https://prometheus.io/docs/prometheus/latest/configuration/alerting_rules/#templating) | + +### Recording Rules + +[Recording rules](https://prometheus.io/docs/prometheus/latest/configuration/recording_rules/#recording-rules) allow you to precompute frequently needed or computationally expensive PromQL (Prometheus Query Language) expressions and save their result as a new set of time series. + +| Field | Description | +|-------|----------------| +| Time Series Name | The name of the time series to output to. Must be a valid metric name. | +| PromQL Expression | The PromQL expression to evaluate. Prometheus will evaluate the current value of this PromQL expression on every evaluation cycle and the result will be recorded as a new set of time series with the metric name as given by 'record'. For more information about expressions, refer to the [Prometheus documentation](https://prometheus.io/docs/prometheus/latest/querying/basics/) or our [example PromQL expressions.](../../../../integrations-in-rancher/monitoring-and-alerting/promql-expressions.md) | +| Labels | Labels to add or overwrite before storing the result. | diff --git a/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/monitoring-v2-configuration-guides/monitoring-v2-configuration-guides.md b/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/monitoring-v2-configuration-guides/monitoring-v2-configuration-guides.md new file mode 100644 index 00000000000..c28816c19fb --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/monitoring-v2-configuration-guides/monitoring-v2-configuration-guides.md @@ -0,0 +1,55 @@ +--- +title: Monitoring Configuration Guides +--- + + + + + +This page captures some of the most important options for configuring Monitoring V2 in the Rancher UI. + +For information on configuring custom scrape targets and rules for Prometheus, please refer to the upstream documentation for the [Prometheus Operator.](https://github.com/prometheus-operator/prometheus-operator) Some of the most important custom resources are explained in the Prometheus Operator [design documentation.](https://github.com/prometheus-operator/prometheus-operator/blob/main/Documentation/getting-started/design.md) The Prometheus Operator documentation can help also you set up RBAC, Thanos, or custom configuration. + +## Setting Resource Limits and Requests + +The resource requests and limits for the monitoring application can be configured when installing `rancher-monitoring`. For more information about the default limits, see [this page.](../../../reference-guides/monitoring-v2-configuration/helm-chart-options.md#configuring-resource-limits-and-requests) + +:::tip + +On an idle cluster, Monitoring may have high CPU usage. To improve performance, turn off the Prometheus adapter. + +::: + +## Prometheus Configuration + +It is usually not necessary to directly edit the Prometheus custom resource. + +Instead, to configure Prometheus to scrape custom metrics, you will only need to create a new ServiceMonitor or PodMonitor to configure Prometheus to scrape additional metrics. + + +### ServiceMonitor and PodMonitor Configuration + +For details, see [this page.](../../../reference-guides/monitoring-v2-configuration/servicemonitors-and-podmonitors.md) + +### Advanced Prometheus Configuration + +For more information about directly editing the Prometheus custom resource, which may be helpful in advanced use cases, see [this page.](advanced-configuration/prometheus.md) + +## Alertmanager Configuration + +The Alertmanager custom resource usually doesn't need to be edited directly. For most common use cases, you can manage alerts by updating Routes and Receivers. + +Routes and receivers are part of the configuration of the alertmanager custom resource. In the Rancher UI, Routes and Receivers are not true custom resources, but pseudo-custom resources that the Prometheus Operator uses to synchronize your configuration with the Alertmanager custom resource. When routes and receivers are updated, the monitoring application will automatically update Alertmanager to reflect those changes. + +For some advanced use cases, you may want to configure alertmanager directly. For more information, refer to [this page.](advanced-configuration/alertmanager.md) + +### Receivers + +Receivers are used to set up notifications. For details on how to configure receivers, see [this page.](../../../reference-guides/monitoring-v2-configuration/receivers.md) +### Routes + +Routes filter notifications before they reach receivers. Each route needs to refer to a receiver that has already been configured. For details on how to configure routes, see [this page.](../../../reference-guides/monitoring-v2-configuration/routes.md) + +### Advanced + +For more information about directly editing the Alertmanager custom resource, which may be helpful in advanced use cases, see [this page.](advanced-configuration/alertmanager.md) \ No newline at end of file diff --git a/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/open-ports-with-firewalld.md b/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/open-ports-with-firewalld.md new file mode 100644 index 00000000000..b4554167411 --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/open-ports-with-firewalld.md @@ -0,0 +1,121 @@ +--- +title: Opening Ports with firewalld +--- + + + + + +:::danger + +Enabling firewalld can cause serious network communication problems. + +For proper network function, firewalld must be disabled on systems running RKE2. [Firewalld conflicts with Canal](https://docs.rke2.io/known_issues#firewalld-conflicts-with-default-networking), RKE2's default networking stack. + +Firewalld must also be disabled on systems running Kubernetes 1.19 and later. + +If you enable firewalld on systems running Kubernetes 1.18 or earlier, understand that this may cause networking issues. CNIs in Kubernetes dynamically update iptables and networking rules independently of any external firewalls, such as firewalld. This can cause unexpected behavior when the CNI and the external firewall conflict. + +::: + +Some distributions of Linux [derived from RHEL,](https://en.wikipedia.org/wiki/Red_Hat_Enterprise_Linux#Rebuilds) including Oracle Linux, may have default firewall rules that block communication with Helm. + +For example, one Oracle Linux image in AWS has REJECT rules that stop Helm from communicating with Tiller: + +``` +Chain INPUT (policy ACCEPT) +target prot opt source destination +ACCEPT all -- anywhere anywhere state RELATED,ESTABLISHED +ACCEPT icmp -- anywhere anywhere +ACCEPT all -- anywhere anywhere +ACCEPT tcp -- anywhere anywhere state NEW tcp dpt:ssh +REJECT all -- anywhere anywhere reject-with icmp-host-prohibited + +Chain FORWARD (policy ACCEPT) +target prot opt source destination +REJECT all -- anywhere anywhere reject-with icmp-host-prohibited + +Chain OUTPUT (policy ACCEPT) +target prot opt source destination +``` + +You can check the default firewall rules with this command: + +``` +sudo iptables --list +``` + +This section describes how to use `firewalld` to apply the [firewall port rules](../../getting-started/installation-and-upgrade/installation-requirements/installation-requirements.md#port-requirements) for nodes in a high-availability Rancher server cluster. + +## Prerequisite + +Install v7.x or later ofv`firewalld`: + +``` +yum install firewalld +systemctl start firewalld +systemctl enable firewalld +``` + +## Applying Firewall Port Rules + +In the Rancher high-availability installation instructions, the Rancher server is set up on three nodes that have all three Kubernetes roles: etcd, controlplane, and worker. If your Rancher server nodes have all three roles, run the following commands on each node: + +``` +firewall-cmd --permanent --add-port=22/tcp +firewall-cmd --permanent --add-port=80/tcp +firewall-cmd --permanent --add-port=443/tcp +firewall-cmd --permanent --add-port=2376/tcp +firewall-cmd --permanent --add-port=2379/tcp +firewall-cmd --permanent --add-port=2380/tcp +firewall-cmd --permanent --add-port=6443/tcp +firewall-cmd --permanent --add-port=8472/udp +firewall-cmd --permanent --add-port=9099/tcp +firewall-cmd --permanent --add-port=10250/tcp +firewall-cmd --permanent --add-port=10254/tcp +firewall-cmd --permanent --add-port=30000-32767/tcp +firewall-cmd --permanent --add-port=30000-32767/udp +``` +If your Rancher server nodes have separate roles, use the following commands based on the role of the node: + +``` +# For etcd nodes, run the following commands: +firewall-cmd --permanent --add-port=2376/tcp +firewall-cmd --permanent --add-port=2379/tcp +firewall-cmd --permanent --add-port=2380/tcp +firewall-cmd --permanent --add-port=8472/udp +firewall-cmd --permanent --add-port=9099/tcp +firewall-cmd --permanent --add-port=10250/tcp + +# For control plane nodes, run the following commands: +firewall-cmd --permanent --add-port=80/tcp +firewall-cmd --permanent --add-port=443/tcp +firewall-cmd --permanent --add-port=2376/tcp +firewall-cmd --permanent --add-port=6443/tcp +firewall-cmd --permanent --add-port=8472/udp +firewall-cmd --permanent --add-port=9099/tcp +firewall-cmd --permanent --add-port=10250/tcp +firewall-cmd --permanent --add-port=10254/tcp +firewall-cmd --permanent --add-port=30000-32767/tcp +firewall-cmd --permanent --add-port=30000-32767/udp + +# For worker nodes, run the following commands: +firewall-cmd --permanent --add-port=22/tcp +firewall-cmd --permanent --add-port=80/tcp +firewall-cmd --permanent --add-port=443/tcp +firewall-cmd --permanent --add-port=2376/tcp +firewall-cmd --permanent --add-port=8472/udp +firewall-cmd --permanent --add-port=9099/tcp +firewall-cmd --permanent --add-port=10250/tcp +firewall-cmd --permanent --add-port=10254/tcp +firewall-cmd --permanent --add-port=30000-32767/tcp +firewall-cmd --permanent --add-port=30000-32767/udp +``` + +After the `firewall-cmd` commands have been run on a node, use the following command to enable the firewall rules: + +``` +firewall-cmd --reload +``` + +**Result:** The firewall is updated so that Helm can communicate with the Rancher server nodes. diff --git a/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/tune-etcd-for-large-installs.md b/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/tune-etcd-for-large-installs.md new file mode 100644 index 00000000000..73827ab809a --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/tune-etcd-for-large-installs.md @@ -0,0 +1,36 @@ +--- +title: Tuning etcd for Large Installations +--- + + + + + +When Rancher is used to manage [a large infrastructure](../../getting-started/installation-and-upgrade/installation-requirements/installation-requirements.md) it is recommended to increase the default keyspace for etcd from the default 2 GB. The maximum setting is 8 GB and the host should have enough RAM to keep the entire dataset in memory. When increasing this value you should also increase the size of the host. The keyspace size can also be adjusted in smaller installations if you anticipate a high rate of change of pods during the garbage collection interval. + +The etcd data set is automatically cleaned up on a five-minute interval by Kubernetes. There are situations, e.g. deployment thrashing, where enough events could be written to etcd and deleted before garbage collection occurs and cleans things up causing the keyspace to fill up. If you see `mvcc: database space exceeded` errors, in the etcd logs or Kubernetes API server logs, you should consider increasing the keyspace size. This can be accomplished by setting the [quota-backend-bytes](https://etcd.io/docs/v3.5/op-guide/maintenance/#space-quota) setting on the etcd servers. + +## Example: This Snippet of the RKE2/K3s config.yaml file Increases the Keyspace Size to 5GB + +```yaml +# RKE2/K3s config.yaml +--- +etcd-arg: + - "quota-backend-bytes=5368709120" +``` + +## Scaling etcd Disk Performance + +You can follow the recommendations from [the etcd docs](https://etcd.io/docs/v3.5/tuning/#disk) on how to tune the disk priority on the host. + +Additionally, to reduce IO contention on the disks for etcd, you can use a dedicated device for the data and wal directory. Based on etcd best practices, mirroring RAID configurations are unnecessary because etcd replicates data between the nodes in the cluster. You can use striping RAID configurations to increase available IOPS. + +To implement this solution in an RKE2/K3s cluster, the `/var/lib/etcd/data` and `/var/lib/etcd/wal` directories will need to have disks mounted and formatted on the underlying host. In the `extra_args` directive of the `etcd` service, you must include the `wal_dir` directory. Without specifying the `wal_dir`, etcd process will try to manipulate the underlying `wal` mount with insufficient permissions. + +```yaml +# RKE2/K3s config.yaml +--- +etcd-arg: + - "data-dir=/var/lib/etcd/data" + - "wal-dir=/var/lib/etcd/wal" +``` diff --git a/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/ui-server-side-pagination.md b/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/ui-server-side-pagination.md new file mode 100644 index 00000000000..66c088e85ff --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/ui-server-side-pagination.md @@ -0,0 +1,81 @@ +--- +title: UI Server-Side Pagination +--- + + + + + +Server-Side Pagination (SSP) is a Rancher feature to provide significant performance improvements across the UI for resources with high counts, restricting the amount of resources browser fetches and stores in memory. + +Note that SSP is optional, **enabled by default**, and it can be disabled via the feature flag `ui-sql-cache`. + +## Disk Space + +:::important +It is crucial that you review the available disk space on your nodes and plan accordingly before upgrading to Rancher v2.12.0 and later to avoid potential disk pressure and pod eviction issues. +::: + +The SSP relies on a caching mechanism that introduces a new requirement for ephemeral disk space on your cluster nodes. This cache, an internal SQLite database, is stored within the container's file system. This affects the nodes running the **Rancher server pods** (`rancher` in the `cattle-system` namespace on the local cluster) and the nodes running the **Rancher agent pods** (`cattle-cluster-agent` in the `cattle-system` namespace on all downstream clusters). + +The amount of disk space required is dynamic and depends on the quantity and size of Kubernetes resources visualized in the UI. As a guideline, the cache may consume approximately **twice the size of the raw Kubernetes objects** it stores. + +For example, internal tests showed that caching 5000 ConfigMaps, totaling 50 MB, consumed 81 MB of disk space. For a conservative, high-level estimate, you can plan for the available disk space on each relevant node to be at least **twice the size of your etcd snapshot**. For most production environments, ensuring a few extra gigabytes of storage are available on the relevant nodes is a safe starting point. + +Please note this space counts against [ephemeral storage](https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/#setting-requests-and-limits-for-local-ephemeral-storage) requests and limits you might have set for your Rancher container via the `resource` value in the Helm chart. Make sure those settings provide for abundant available space. + +If you see the error `database or disk is full (13)` in the pod logs, this is a symptom that more space needs to be allocated. + +SQLite-backed caching persists copies of any cached Kubernetes objects to disk. See [Encrypting SQLite-backed Caching](#encrypting-sqlite-backed-caches) if this is a security concern. + +## Enabling Server-Side Pagination + +1. In the upper left corner, click **☰ > Global Settings > Feature Flags**. +1. Find **`ui-sql-cache`** and select **⋮ > Activate > Activate**. +1. Wait for Rancher to restart. This also restarts agents on all downstream clusters. +1. Reload the page with the browser button (or the equivalent keyboard combination, typically `CTRL + R` on Windows and Linux, and `⌘ + R` on macOS). + +## Disabling Server-Side Pagination + +1. In the upper left corner, click **☰ > Global Settings > Feature Flags**. +1. Find **`ui-sql-cache`** and select **⋮ > Deactivate > Deactivate**. +1. Wait for Rancher to restart. This also restarts agents on all downstream clusters. +1. Reload the page with the browser button (or the equivalent keyboard combination, typically `CTRL + R` on Windows and Linux, and `⌘ + R` on macOS). + +## Encrypting SQLite-backed Caches + +UI server-side pagination persists copies of any cached Kubernetes objects to disk. If you're concerned about the safety of this data, you can encrypt all objects before they are persisted to disk, by setting the environment variable `CATTLE_ENCRYPT_CACHE_ALL` to `true` in `rancher` pods in the upstream cluster and `cattle-cluster-agent` pods in the downstream clusters. + +Secrets and security Tokens are always encrypted regardless of the above setting. + +## Known Limitations of UI Server-Side Pagination + +This release improves the performance of most pages used to view, create or edit resources within the `local` or downstream clusters i.e. the Cluster Explorer view. However, RBAC related resources and areas outside the Cluster Explorer are not yet covered by this feature. + +Additionally, the following limitations are present when the feature is enabled. These mainly revolve around different sort or filter behaviors in affected lists: + +- Resources in lists are automatically updated, however, not instantaneously. +- All lists that utilize Server-Side Pagination: + - `State` column sort and filter features work on the resources `metadata.state.name` field instead of one deduced locally by the UI. + - Updates are shown every 5 seconds, rather than instantly. +- Cluster Explorer: + - Project/Namespace filter does not support filtering namespaces by all namespaces not in a project via the `Not in a Project` entry. + - `Cluster` group --> `Nodes` page + - The following columns are not sortable or filterable: `Roles`, `External/Internal IP`, `CPU`, `RAM` (logic to determine their value is calculated in the browser) + - `Workloads` list: + - The `Workloads` list, which showed multiple different resource types has been removed. + - Server-Side Pagination of multiple resources is not currently possible. + - `Workloads` group --> All lists + - `Pod Restarts` and `Workload Health` columns have been removed. + - [Re-enable Pod Restart Count and Pod Health columns for Workload lists #14211](https://github.com/rancher/dashboard/issues/14211) + - `Workloads` group / `Job` List + - `Duration` is not sortable (sorting on a duration). + - [Implement more complex server-side pagination sorting #12815](https://github.com/rancher/dashboard/issues/12815) + - `Workloads` group / `Pod` List + - `Images` is not sortable (sorting on an array). + - `Service Discovery` group / `Ingresses` + - `Default` is not sortable/filterable (logic to determine their value is calculated in the browser). + - `Storage` group / `ConfigMaps` + - `Data` is not sortable/filterable (logic to determine their value is calculated in the browser). + - `Storage` group / `Secrets` + - `Data` is not sortable/filterable (logic to determine their value is calculated in the browser). diff --git a/versioned_docs/version-2.14/how-to-guides/new-user-guides/add-users-to-projects.md b/versioned_docs/version-2.14/how-to-guides/new-user-guides/add-users-to-projects.md new file mode 100644 index 00000000000..e9ceaf945aa --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/new-user-guides/add-users-to-projects.md @@ -0,0 +1,74 @@ +--- +title: Adding Users to Projects +--- + + + + + +If you want to provide a user with access and permissions to _specific_ projects and resources within a cluster, assign the user a project membership. + +You can add members to a project as it is created, or add them to an existing project. + +:::tip + +Want to provide a user with access to _all_ projects within a cluster? See [Adding Cluster Members](../../how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/cluster-and-project-roles.md) instead. + +::: + +## Adding Members to a New Project + +You can add members to a project as you create it (recommended if possible). For details on creating a new project, refer to the [cluster administration section.](../../how-to-guides/new-user-guides/manage-clusters/projects-and-namespaces.md) + +## Adding Members to an Existing Project + +Following project creation, you can add users as project members so that they can access its resources. + +1. In the upper left corner, click **☰ > Cluster Management**. +1. On the **Clusters** page, go to the cluster where you want to add members to a project and click **Explore**. +1. Click **Cluster > Projects/Namespaces**. +1. Go to the project where you want to add members. Next to the **Create Namespace** button above the project name, click **☰**. Select **Edit Config**. +1. In the **Members** tab, click **Add**. +1. Search for the user or group that you want to add to the project. + + :::note Notes: + + - At least 2 characters must be typed in the search box for results to appear. + - Users can be searched based on their username or display name. + - Search is prefix-based (e.g., a user named `Stan Dard` will appear when searching for `Sta`, but not when searching for `Dar`) and case-sensitive. + + ::: + + If external authentication is configured: + + - Rancher returns users from your external authentication source as you type. + + - A drop-down allows you to add groups instead of individual users. The dropdown only lists groups that you, the logged in user, are included in. + + :::note + + If you are logged in as a local user, external users do not display in your search results. + + ::: + +1. Assign the user or group **Project** roles. + + [What are Project Roles?](../../how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/cluster-and-project-roles.md) + + :::note Notes: + + - Users assigned the `Owner` or `Member` role for a project automatically inherit the `namespace creation` role. However, this role is a [Kubernetes ClusterRole](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#role-and-clusterrole), meaning its scope extends to all projects in the cluster. Therefore, users explicitly assigned the `Owner` or `Member` role for a project can create or delete namespaces in other projects they're assigned to, even with only the `Read Only` role assigned. + + - By default, the Rancher role of `project-member` inherits from the `Kubernetes-edit` role, and the `project-owner` role inherits from the `Kubernetes-admin` role. As such, both `project-member` and `project-owner` roles will allow for namespace management, including the ability to create and delete namespaces. + + - For `Custom` roles, you can modify the list of individual roles available for assignment. + + - To add roles to the list, [Add a Custom Role](../../how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/custom-roles.md). + - To remove roles from the list, [Lock/Unlock Roles](../../how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/locked-roles.md). + + ::: + +**Result:** The chosen users are added to the project. + +- To revoke project membership, select the user and click **Delete**. This action deletes membership, not the user. +- To modify a user's roles in the project, delete them from the project, and then re-add them with modified roles. diff --git a/versioned_docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/about-provisioning-drivers/about-provisioning-drivers.md b/versioned_docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/about-provisioning-drivers/about-provisioning-drivers.md new file mode 100644 index 00000000000..6edd8965a06 --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/about-provisioning-drivers/about-provisioning-drivers.md @@ -0,0 +1,46 @@ +--- +title: About Provisioning Drivers +--- + + + + + +Drivers in Rancher allow you to manage which providers can be used to deploy [hosted Kubernetes clusters](../../kubernetes-clusters-in-rancher-setup/set-up-clusters-from-hosted-kubernetes-providers/set-up-clusters-from-hosted-kubernetes-providers.md) or [nodes in an infrastructure provider](../../launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/use-new-nodes-in-an-infra-provider.md) to allow Rancher to deploy and manage Kubernetes. + +### Rancher Drivers + +With Rancher drivers, you can enable/disable existing built-in drivers that are packaged in Rancher. Alternatively, you can add your own driver if Rancher has not yet implemented it. + +There are two types of drivers within Rancher: + +* [Cluster Drivers](#cluster-drivers) +* [Node Drivers](#node-drivers) + +### Cluster Drivers + +Cluster drivers are used to provision [hosted Kubernetes clusters](../../kubernetes-clusters-in-rancher-setup/set-up-clusters-from-hosted-kubernetes-providers/set-up-clusters-from-hosted-kubernetes-providers.md), such as GKE, EKS, AKS, etc.. The availability of which cluster driver to display when creating a cluster is defined based on the cluster driver's status. Only `active` cluster drivers will be displayed as an option for creating clusters for hosted Kubernetes clusters. By default, Rancher is packaged with several existing cluster drivers, but you can also create custom cluster drivers to add to Rancher. + +By default, Rancher has activated several hosted Kubernetes cloud providers including: + +* [Amazon EKS](../../kubernetes-clusters-in-rancher-setup/set-up-clusters-from-hosted-kubernetes-providers/eks.md) +* [Google GKE](../../kubernetes-clusters-in-rancher-setup/set-up-clusters-from-hosted-kubernetes-providers/gke.md) +* [Azure AKS](../../kubernetes-clusters-in-rancher-setup/set-up-clusters-from-hosted-kubernetes-providers/aks.md) + +### Node Drivers + +Node drivers are used to provision hosts, which Rancher uses to launch and manage Kubernetes clusters. A node driver is the same as a [Docker Machine driver](https://github.com/docker/docs/blob/vnext-engine/machine/drivers/index.md). The availability of which node driver to display when creating node templates is defined based on the node driver's status. Only `active` node drivers will be displayed as an option for creating node templates. By default, Rancher is packaged with many existing Docker Machine drivers, but you can also create custom node drivers to add to Rancher. + +If there are specific node drivers that you don't want to show to your users, you would need to de-activate these node drivers. + +Rancher supports several major cloud providers, but by default, these node drivers are active and available for deployment: + +* [Amazon EC2](../../launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/create-an-amazon-ec2-cluster.md) +* [Azure](../../launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/create-an-azure-cluster.md) +* [Digital Ocean](../../launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/create-a-digitalocean-cluster.md) +* [vSphere](../../launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/vsphere/vsphere.md) + +There are several other node drivers that are disabled by default, but are packaged in Rancher: + +* [Harvester](../../../../integrations-in-rancher/harvester/overview.md#harvester-node-driver/), available as of Rancher v2.6.1 +* [Google GCE](../../launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/create-a-google-compute-engine-cluster.md), available as of Rancher v2.12.0 diff --git a/versioned_docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/about-provisioning-drivers/manage-cluster-drivers.md b/versioned_docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/about-provisioning-drivers/manage-cluster-drivers.md new file mode 100644 index 00000000000..4e0819074a8 --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/about-provisioning-drivers/manage-cluster-drivers.md @@ -0,0 +1,46 @@ +--- +title: Cluster Drivers +--- + + + + + +Cluster drivers are used to create clusters in a [hosted Kubernetes provider](../../kubernetes-clusters-in-rancher-setup/set-up-clusters-from-hosted-kubernetes-providers/set-up-clusters-from-hosted-kubernetes-providers.md), such as Google GKE. The availability of which cluster driver to display when creating clusters is defined by the cluster driver's status. Only `active` cluster drivers will be displayed as an option for creating clusters. By default, Rancher is packaged with several existing cloud provider cluster drivers, but you can also add custom cluster drivers to Rancher. + +If there are specific cluster drivers that you do not want to show your users, you may deactivate those cluster drivers within Rancher and they will not appear as an option for cluster creation. + +### Managing Cluster Drivers + +:::note Prerequisites: + +To create, edit, or delete cluster drivers, you need _one_ of the following permissions: + +- [Administrator Global Permissions](../manage-role-based-access-control-rbac/global-permissions.md) +- [Custom Global Permissions](../manage-role-based-access-control-rbac/global-permissions.md#custom-global-permissions) with the [Manage Cluster Drivers](../manage-role-based-access-control-rbac/global-permissions.md) role assigned. + +::: + +## Activating/Deactivating Cluster Drivers + +By default, Rancher only activates drivers for the most popular cloud providers, Google GKE, Amazon EKS and Azure AKS. If you want to show or hide any node driver, you can change its status. + +1. In the upper left corner, click **☰ > Cluster Management**. + +2. In the left navigation menu, click **Drivers**. + +3. On the **Cluster Drivers** tab, select the driver that you wish to activate or deactivate and click **⋮ > Activate** or **⋮ > Deactivate**. + +## Adding Custom Cluster Drivers + +If you want to use a cluster driver that Rancher doesn't support out-of-the-box, you can add the provider's driver in order to start using them to create _hosted_ kubernetes clusters. + +1. In the upper left corner, click **☰ > Cluster Management**. +1. In the left navigation menu, click **Drivers**. +1. On the **Cluster Drivers** tab, click **Add Cluster Driver**. +1. Complete the **Add Cluster Driver** form. Then click **Create**. + + +### Developing your own Cluster Driver + +In order to develop cluster driver to add to Rancher, please refer to our [example](https://github.com/rancher-plugins/kontainer-engine-driver-example). diff --git a/versioned_docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/about-provisioning-drivers/manage-node-drivers.md b/versioned_docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/about-provisioning-drivers/manage-node-drivers.md new file mode 100644 index 00000000000..86b1ed48986 --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/about-provisioning-drivers/manage-node-drivers.md @@ -0,0 +1,61 @@ +--- +title: Node Drivers +--- + + + + + +A node driver is the same as a [Docker Machine driver](https://github.com/docker/docs/blob/vnext-engine/machine/drivers/index.md). Node drivers are used to provision hosts, which Rancher uses to launch and manage Kubernetes clusters. By default, Rancher is packaged with many node drivers, but you can also create and add custom node drivers to Rancher. + +Only `Active` node drivers are displayed in the Rancher UI when you create node templates. If there are specific node drivers that you don't want to show your users, you must deactivate these node drivers. + +## Managing Node Drivers + +:::note Prerequisites: + +To create, edit, or delete drivers, you need _one_ of the following permissions: + +- [Administrator Global Permissions](../manage-role-based-access-control-rbac/global-permissions.md) +- [Custom Global Permissions](../manage-role-based-access-control-rbac/global-permissions.md#custom-global-permissions) with the [Manage Node Drivers](../manage-role-based-access-control-rbac/global-permissions.md) role assigned. + +::: + +### Activating/Deactivating Node Drivers + +By default, Rancher only activates drivers for the most popular cloud providers, such as Amazon EC2, Azure, DigitalOcean, Linode and vSphere. If you want to show or hide any node driver, you can change its status. + +1. In the upper left corner, click **☰ > Cluster Management**. +1. In the left navigation menu, click **Drivers**. +1. On the **Node Drivers** tab, select the driver that you wish to activate or deactivate and click **⋮ > Activate** or **⋮ > Deactivate**. + +:::danger + +You can lose access to clusters after deactivating a node driver. + +Deactivating a node driver doesn't just affect its visibility in the Rancher UI. When you deactivate or delete a node driver, any nodes deployed with that driver become inaccessible. + +For example, if you deactivate a vSphere node driver to hide it in the UI, and you have a vSphere cluster that was deployed with that driver, the initial node in the cluster will fail, and the entire cluster will become inaccessible. Attempts to delete the vSphere nodes will fail, with nodes stuck in an extended `Removing` state. + +Before you deactivate a node driver, make sure that it has no associated clusters. One way to check is to see if the respective platform for a driver is listed among your clusters: + +1. In the upper left corner, click **☰ > Cluster Management**. +1. Select **Clusters**. +1. Check the **Provider** column of the table for instances of the node driver you are deactivating. + +::: + +### Adding Custom Node Drivers + +If you want to use a node driver that Rancher doesn't support out-of-the-box, you can add that provider's driver in order to start using them to create node templates and eventually node pools for your Kubernetes cluster. + +1. In the upper left corner, click **☰ > Cluster Management**. +1. In the left navigation menu, click **Drivers**. +1. On **Node Drivers** tab, click **Add Node Driver**. +1. Complete the **Add Node Driver** form. Then click **Create**. + +### Developing Your Own Node Drivers + +Node drivers are implemented with [Rancher Machine](https://github.com/rancher/machine), a fork of [Docker Machine](https://github.com/docker/machine). Docker Machine is no longer under active development. + +Refer to the original [Docker Machine documentation](https://github.com/docker/docs/blob/vnext-engine/machine/overview.md) for details on how to develop your own node drivers. diff --git a/versioned_docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/about-rke1-templates.md b/versioned_docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/about-rke1-templates.md new file mode 100644 index 00000000000..1ecbe229d25 --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/about-rke1-templates.md @@ -0,0 +1,132 @@ +--- +title: About RKE1 Templates +--- + + + + + + + +RKE templates are designed to allow DevOps and security teams to standardize and simplify the creation of Kubernetes clusters. + +RKE is the [Rancher Kubernetes Engine,](https://rancher.com/docs/rke/latest/en/) which is the tool that Rancher uses to provision Kubernetes clusters. + +With Kubernetes increasing in popularity, there is a trend toward managing a larger number of smaller clusters. When you want to create many clusters, it’s more important to manage them consistently. Multi-cluster management comes with challenges to enforcing security and add-on configurations that need to be standardized before turning clusters over to end users. + +RKE templates help standardize these configurations. Regardless of whether clusters are created with the Rancher UI, the Rancher API, or an automated process, Rancher will guarantee that every cluster it provisions from an RKE template is uniform and consistent in the way it is produced. + +Admins control which cluster options can be changed by end users. RKE templates can also be shared with specific users and groups, so that admins can create different RKE templates for different sets of users. + +If a cluster was created with an RKE template, you can't change it to a different RKE template. You can only update the cluster to a new revision of the same template. + +You can [save the configuration of an existing cluster as an RKE template.](apply-templates.md#converting-an-existing-cluster-to-use-an-rke-template) Then the cluster's settings can only be changed if the template is updated. The new template can also be used to launch new clusters. + +The core features of RKE templates allow DevOps and security teams to: + +- Standardize cluster configuration and ensure that Rancher-provisioned clusters are created following best practices +- Prevent less technical users from making uninformed choices when provisioning clusters +- Share different templates with different sets of users and groups +- Delegate ownership of templates to users who are trusted to make changes to them +- Control which users can create templates +- Require users to create clusters from a template + +## Configurable Settings + +RKE templates can be created in the Rancher UI or defined in YAML format. They can define all the same parameters that can be specified when you use Rancher to provision custom nodes or nodes from an infrastructure provider: + +- Cloud provider options +- Pod security options +- Network providers +- Ingress controllers +- Network security configuration +- Network plugins +- Private registry URL and credentials +- Add-ons +- Kubernetes options, including configurations for Kubernetes components such as kube-api, kube-controller, kubelet, and services + +The [add-on section](#add-ons) of an RKE template is especially powerful because it allows a wide range of customization options. + +## Scope of RKE Templates + +RKE templates are supported for Rancher-provisioned clusters. The templates can be used to provision custom clusters or clusters that are launched by an infrastructure provider. + +RKE templates are for defining Kubernetes and Rancher settings. Node templates are responsible for configuring nodes. For tips on how to use RKE templates in conjunction with hardware, refer to [RKE Templates and Hardware](infrastructure.md). + +RKE templates can be created from scratch to pre-define cluster configuration. They can be applied to launch new clusters, or templates can also be exported from existing running clusters. + +The settings of an existing cluster can be [saved as an RKE template.](apply-templates.md#converting-an-existing-cluster-to-use-an-rke-template) This creates a new template and binds the cluster settings to the template, so that the cluster can only be upgraded if the [template is updated](manage-rke1-templates.md#updating-a-template), and the cluster is upgraded to [use a newer version of the template.](manage-rke1-templates.md#upgrading-a-cluster-to-use-a-new-template-revision) The new template can also be used to create new clusters. + + +## Example Scenarios +When an organization has both basic and advanced Rancher users, administrators might want to give the advanced users more options for cluster creation, while restricting the options for basic users. + +These [example scenarios](example-use-cases.md) describe how an organization could use templates to standardize cluster creation. + +Some of the example scenarios include the following: + +- **Enforcing templates:** Administrators might want to [enforce one or more template settings for everyone](example-use-cases.md#enforcing-a-template-setting-for-everyone) if they want all new Rancher-provisioned clusters to have those settings. +- **Sharing different templates with different users:** Administrators might give [different templates to basic and advanced users,](example-use-cases.md#templates-for-basic-and-advanced-users) so that basic users can have more restricted options and advanced users can use more discretion when creating clusters. +- **Updating template settings:** If an organization's security and DevOps teams decide to embed best practices into the required settings for new clusters, those best practices could change over time. If the best practices change, [a template can be updated to a new revision](example-use-cases.md#updating-templates-and-clusters-created-with-them) and clusters created from the template can [upgrade to the new version](manage-rke1-templates.md#upgrading-a-cluster-to-use-a-new-template-revision) of the template. +- **Sharing ownership of a template:** When a template owner no longer wants to maintain a template, or wants to share ownership of the template, this scenario describes how [template ownership can be shared.](example-use-cases.md#allowing-other-users-to-control-and-share-a-template) + +## Template Management + +When you create an RKE template, it is available in the Rancher UI from the **Cluster Management** view under **RKE Templates**. When you create a template, you become the template owner, which gives you permission to revise and share the template. You can share the RKE templates with specific users or groups, and you can also make it public. + +Administrators can turn on template enforcement to require users to always use RKE templates when creating a cluster. This allows administrators to guarantee that Rancher always provisions clusters with specific settings. + +RKE template updates are handled through a revision system. If you want to change or update a template, you create a new revision of the template. Then a cluster that was created with the older version of the template can be upgraded to the new template revision. + +In an RKE template, settings can be restricted to what the template owner chooses, or they can be open for the end user to select the value. The difference is indicated by the **Allow User Override** toggle over each setting in the Rancher UI when the template is created. + +For the settings that cannot be overridden, the end user will not be able to directly edit them. In order for a user to get different options of these settings, an RKE template owner would need to create a new revision of the RKE template, which would allow the user to upgrade and change that option. + +The documents in this section explain the details of RKE template management: + +- [Getting permission to create templates](creator-permissions.md) +- [Creating and revising templates](manage-rke1-templates.md) +- [Enforcing template settings](enforce-templates.md#requiring-new-clusters-to-use-an-rke-template) +- [Overriding template settings](override-template-settings.md) +- [Sharing templates with cluster creators](access-or-share-templates.md#sharing-templates-with-specific-users-or-groups) +- [Sharing ownership of a template](access-or-share-templates.md#sharing-ownership-of-templates) + +An [example YAML configuration file for a template](../../../../reference-guides/rke1-template-example-yaml.md) is provided for reference. + +## Applying Templates + +You can [create a cluster from a template](apply-templates.md#creating-a-cluster-from-an-rke-template) that you created, or from a template that has been [shared with you.](access-or-share-templates.md) + +If the RKE template owner creates a new revision of the template, you can [upgrade your cluster to that revision.](apply-templates.md#updating-a-cluster-created-with-an-rke-template) + +RKE templates can be created from scratch to pre-define cluster configuration. They can be applied to launch new clusters, or templates can also be exported from existing running clusters. + +You can [save the configuration of an existing cluster as an RKE template.](apply-templates.md#converting-an-existing-cluster-to-use-an-rke-template) Then the cluster's settings can only be changed if the template is updated. + +## Standardizing Hardware + +RKE templates are designed to standardize Kubernetes and Rancher settings. If you want to standardize your infrastructure as well, one option is to use RKE templates [in conjunction with other tools](infrastructure.md). + +Another option is to use [cluster templates,](../../manage-clusters/manage-cluster-templates.md) which include node pool configuration options, but don't provide configuration enforcement. + +## YAML Customization + +If you define an RKE template as a YAML file, you can modify this [example RKE template YAML](../../../../reference-guides/rke1-template-example-yaml.md). The YAML in the RKE template uses the same customization that Rancher uses when creating an RKE cluster, but since the YAML is located within the context of a Rancher provisioned cluster, you will need to nest the RKE template customization under the `rancher_kubernetes_engine_config` directive in the YAML. + +The RKE documentation also has [annotated](https://rancher.com/docs/rke/latest/en/example-yamls/) `cluster.yml` files that you can use for reference. + +For guidance on available options, refer to the RKE documentation on [cluster configuration.](https://rancher.com/docs/rke/latest/en/config-options/) + +### Add-ons + +The add-on section of the RKE template configuration file works the same way as the [add-on section of a cluster configuration file](https://rancher.com/docs/rke/latest/en/config-options/add-ons/). + +The user-defined add-ons directive allows you to either call out and pull down Kubernetes manifests or put them inline directly. If you include these manifests as part of your RKE template, Rancher will provision those in the cluster. + +Some things you could do with add-ons include: + +- Install applications on the Kubernetes cluster after it starts +- Install plugins on nodes that are deployed with a Kubernetes daemonset +- Automatically set up namespaces, service accounts, or role binding + +The RKE template configuration must be nested within the `rancher_kubernetes_engine_config` directive. To set add-ons, when creating the template, you will click **Edit as YAML**. Then use the `addons` directive to add a manifest, or the `addons_include` directive to set which YAML files are used for the add-ons. For more information on custom add-ons, refer to the [user-defined add-ons documentation.](https://rancher.com/docs/rke/latest/en/config-options/add-ons/user-defined-add-ons/) diff --git a/versioned_docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/access-or-share-templates.md b/versioned_docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/access-or-share-templates.md new file mode 100644 index 00000000000..c12a1f03ef0 --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/access-or-share-templates.md @@ -0,0 +1,68 @@ +--- +title: Access and Sharing +--- + + + + + +If you are an RKE template owner, you can share it with users or groups of users, who can then use the template to create clusters. + +Since RKE templates are specifically shared with users and groups, owners can share different RKE templates with different sets of users. + +When you share a template, each user can have one of two access levels: + +- **Owner:** This user can update, delete, and share the templates that they own. The owner can also share the template with other users. +- **User:** These users can create clusters using the template. They can also upgrade those clusters to new revisions of the same template. When you share a template as **Make Public (read-only),** all users in your Rancher setup have the User access level for the template. + +If you create a template, you automatically become an owner of that template. + +If you want to delegate responsibility for updating the template, you can share ownership of the template. For details on how owners can modify templates, refer to the [documentation about revising templates.](manage-rke1-templates.md) + +There are several ways to share templates: + +- Add users to a new RKE template during template creation +- Add users to an existing RKE template +- Make the RKE template public, sharing it with all users in the Rancher setup +- Share template ownership with users who are trusted to modify the template + +### Sharing Templates with Specific Users or Groups + +To allow users or groups to create clusters using your template, you can give them the basic **User** access level for the template. + +1. In the upper left corner, click **☰ > Cluster Management**. +1. Under **RKE1 configuration**, click **RKE Templates**. +1. Go to the template that you want to share and click the **⋮ > Edit**. +1. In the **Share Template** section, click on **Add Member**. +1. Search in the **Name** field for the user or group you want to share the template with. +1. Choose the **User** access type. +1. Click **Save**. + +**Result:** The user or group can create clusters using the template. + +### Sharing Templates with All Users + +1. In the upper left corner, click **☰ > Cluster Management**. +1. In the left navigation menu, click **RKE1 Configuration > RKE Templates**. +1. Go to the template that you want to share and click the **⋮ > Edit**. +1. Under **Share Template,** check the box for **Make Public (read-only)**. +1. Click **Save**. + +**Result:** All users in the Rancher setup can create clusters using the template. + +### Sharing Ownership of Templates + +If you are the creator of a template, you might want to delegate responsibility for maintaining and updating a template to another user or group. + +In that case, you can give users the Owner access type, which allows another user to update your template, delete it, or share access to it with other users. + +To give Owner access to a user or group, + +1. In the upper left corner, click **☰ > Cluster Management**. +1. Under **RKE1 configuration**, click **RKE Templates**. +1. Go to the RKE template that you want to share and click the **⋮ > Edit**. +1. Under **Share Template**, click on **Add Member** and search in the **Name** field for the user or group you want to share the template with. +1. In the **Access Type** field, click **Owner**. +1. Click **Save**. + +**Result:** The user or group has the Owner access type, and can modify, share, or delete the template. \ No newline at end of file diff --git a/versioned_docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/apply-templates.md b/versioned_docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/apply-templates.md new file mode 100644 index 00000000000..365c879aee4 --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/apply-templates.md @@ -0,0 +1,63 @@ +--- +title: Applying Templates +--- + + + + + +You can create a cluster from an RKE template that you created, or from a template that has been [shared with you.](access-or-share-templates.md) + +RKE templates can be applied to new clusters. + +You can [save the configuration of an existing cluster as an RKE template.](#converting-an-existing-cluster-to-use-an-rke-template) Then the cluster's settings can only be changed if the template is updated. + +You can't change a cluster to use a different RKE template. You can only update the cluster to a new revision of the same template. + + +### Creating a Cluster from an RKE Template + +To add a cluster [hosted by an infrastructure provider](../../launch-kubernetes-with-rancher/launch-kubernetes-with-rancher.md) using an RKE template, use these steps: + +1. In the upper left corner, click **☰ > Cluster Management**. +1. On the **Clusters** page, click **Create** and choose the infrastructure provider. +1. Provide the cluster name and node template details as usual. +1. To use an RKE template, under the **Cluster Options**, check the box for **Use an existing RKE template and revision**. +1. Choose an RKE template and revision from the dropdown menu. +1. Optional: You can edit any settings that the RKE template owner marked as **Allow User Override** when the template was created. If there are settings that you want to change, but don't have the option to, you will need to contact the template owner to get a new revision of the template. Then you will need to edit the cluster to upgrade it to the new revision. +1. Click **Create** to launch the cluster. + +### Updating a Cluster Created with an RKE Template + +When the template owner creates a template, each setting has a switch in the Rancher UI that indicates if users can override the setting. + +- If the setting allows a user override, you can update these settings in the cluster by [editing the cluster.](../../../../reference-guides/cluster-configuration/cluster-configuration.md) +- If the switch is turned off, you cannot change these settings unless the cluster owner creates a template revision that lets you override them. If there are settings that you want to change, but don't have the option to, you will need to contact the template owner to get a new revision of the template. + +If a cluster was created from an RKE template, you can edit the cluster to update the cluster to a new revision of the template. + +An existing cluster's settings can be [saved as an RKE template.](#converting-an-existing-cluster-to-use-an-rke-template) In that situation, you can also edit the cluster to update the cluster to a new revision of the template. + +:::note + +You can't change the cluster to use a different RKE template. You can only update the cluster to a new revision of the same template. + +::: + +### Converting an Existing Cluster to Use an RKE Template + +This section describes how to create an RKE template from an existing cluster. + +RKE templates cannot be applied to existing clusters, except if you save an existing cluster's settings as an RKE template. This exports the cluster's settings as a new RKE template, and also binds the cluster to that template. The result is that the cluster can only be changed if the [template is updated,](manage-rke1-templates.md#updating-a-template) and the cluster is upgraded to [use a newer version of the template.](manage-rke1-templates.md#upgrading-a-cluster-to-use-a-new-template-revision) + +To convert an existing cluster to use an RKE template, + +1. In the upper left corner, click **☰ > Cluster Management**. +1. On the **Clusters** page, go to the cluster that will be converted to use an RKE template. Click **⋮ > Save as RKE Template**. +1. Enter a name for the template in the form that appears, and click **Create**. + +**Results:** + +- A new RKE template is created. +- The cluster is converted to use the new template. +- New clusters can be [created from the new template.](#creating-a-cluster-from-an-rke-template) \ No newline at end of file diff --git a/versioned_docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/creator-permissions.md b/versioned_docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/creator-permissions.md new file mode 100644 index 00000000000..b4a0f290620 --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/creator-permissions.md @@ -0,0 +1,61 @@ +--- +title: Template Creator Permissions +--- + + + + + +Administrators have the permission to create RKE templates, and only administrators can give that permission to other users. + +For more information on administrator permissions, refer to the [documentation on global permissions](../manage-role-based-access-control-rbac/global-permissions.md). + +## Giving Users Permission to Create Templates + +Templates can only be created by users who have the global permission **Create RKE Templates**. + +Administrators have the global permission to create templates, and only administrators can give that permission to other users. + +For information on allowing users to modify existing templates, refer to [Sharing Templates.](access-or-share-templates.md) + +Administrators can give users permission to create RKE templates in two ways: + +- By editing the permissions of an [individual user](#allowing-a-user-to-create-templates) +- By changing the [default permissions of new users](#allowing-new-users-to-create-templates-by-default) + +### Allowing a User to Create Templates + +An administrator can individually grant the role **Create RKE Templates** to any existing user by following these steps: + +1. In the upper left corner, click **☰ > Users & Authentication**. +1. In the left navigation bar, click **Users**. +1. Choose the user you want to edit and click **⋮ > Edit Config**. +1. In the **Built-in** section, check the box for **Create new RKE Cluster Templates** role along with any other roles the user should have. You may want to also check the box for **Create RKE Template Revisions**. +1. Click **Save**. + +**Result:** The user has permission to create RKE templates. + +### Allowing New Users to Create Templates by Default + +Alternatively, the administrator can give all new users the default permission to create RKE templates by following the following steps. This will not affect the permissions of existing users. + +1. In the upper left corner, click **☰ > Users & Authentication**. +1. In the left navigation bar, click **Role Templates**. +1. Select **Create new RKE Cluster Templates** and click **⋮ > Edit Config**. +1. Select the option **Yes: Default role for new users**. +1. Click **Save**. +1. If you would like new users to also be able to create RKE template revisions, enable that role as default as well. + +**Result:** Any new user created in this Rancher installation will be able to create RKE templates. Existing users will not get this permission. + +### Revoking Permission to Create Templates + +Administrators can remove a user's permission to create templates with the following steps. Note: Administrators have full control over all resources regardless of whether fine-grained permissions are selected. + +1. In the upper left corner, click **☰ > Users & Authentication**. +1. In the left navigation bar, click **Users**. +1. Choose the user you want to edit permissions for and click **⋮ > Edit Config**. +1. In the **Built-in** section, un-check the box for **Create RKE Templates** and **Create RKE Template Revisions,** if applicable. In this section, you can change the user back to a standard user, or give the user a different set of permissions. +1. Click **Save**. + +**Result:** The user cannot create RKE templates. \ No newline at end of file diff --git a/versioned_docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/enforce-templates.md b/versioned_docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/enforce-templates.md new file mode 100644 index 00000000000..142d3d615d0 --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/enforce-templates.md @@ -0,0 +1,47 @@ +--- +title: Enforcing Templates +--- + + + + + +This section describes how template administrators can enforce templates in Rancher, restricting the ability of users to create clusters without a template. + +By default, any standard user in Rancher can create clusters. But when RKE template enforcement is turned on, + +- Only an administrator has the ability to create clusters without a template. +- All standard users must use an RKE template to create a new cluster. +- Standard users cannot create a cluster without using a template. + +Users can only create new templates if the administrator [gives them permission.](creator-permissions.md#allowing-a-user-to-create-templates) + +After a cluster is created with an RKE template, the cluster creator cannot edit settings that are defined in the template. The only way to change those settings after the cluster is created is to [upgrade the cluster to a new revision](apply-templates.md#updating-a-cluster-created-with-an-rke-template) of the same template. If cluster creators want to change template-defined settings, they would need to contact the template owner to get a new revision of the template. For details on how template revisions work, refer to the [documentation on revising templates.](manage-rke1-templates.md#updating-a-template) + +## Requiring New Clusters to Use an RKE Template + +You might want to require new clusters to use a template to ensure that any cluster launched by a [standard user](../manage-role-based-access-control-rbac/global-permissions.md) will use the Kubernetes and/or Rancher settings that are vetted by administrators. + +To require new clusters to use an RKE template, administrators can turn on RKE template enforcement with the following steps: + +1. Click **☰ > Global Settings**. +1. Go to the `cluster-template-enforcement` setting. Click **⋮ > Edit Setting**. +1. Set the value to **True** and click **Save**. + + :::note Important: + + When the admin sets the `cluster-template-enforcement` to True, they also need to share the `clusterTemplates` with users so that users can select one of these templates to create the cluster. + + ::: + +**Result:** All clusters provisioned by Rancher must use a template, unless the creator is an administrator. + +## Disabling RKE Template Enforcement + +To allow new clusters to be created without an RKE template, administrators can turn off RKE template enforcement with the following steps: + +1. Click **☰ > Global Settings**. +1. Go to the `cluster-template-enforcement` setting. Click **⋮ > Edit Setting**. +1. Set the value to **False** and click **Save**. + +**Result:** When clusters are provisioned by Rancher, they don't need to use a template. diff --git a/versioned_docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/example-use-cases.md b/versioned_docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/example-use-cases.md new file mode 100644 index 00000000000..4471ffd9300 --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/example-use-cases.md @@ -0,0 +1,74 @@ +--- +title: Example Scenarios +--- + + + + + +These example scenarios describe how an organization could use templates to standardize cluster creation. + +- **Enforcing templates:** Administrators might want to [enforce one or more template settings for everyone](#enforcing-a-template-setting-for-everyone) if they want all new Rancher-provisioned clusters to have those settings. +- **Sharing different templates with different users:** Administrators might give [different templates to basic and advanced users,](#templates-for-basic-and-advanced-users) so that basic users have more restricted options and advanced users have more discretion when creating clusters. +- **Updating template settings:** If an organization's security and DevOps teams decide to embed best practices into the required settings for new clusters, those best practices could change over time. If the best practices change, [a template can be updated to a new revision](#updating-templates-and-clusters-created-with-them) and clusters created from the template can upgrade to the new version of the template. +- **Sharing ownership of a template:** When a template owner no longer wants to maintain a template, or wants to delegate ownership of the template, this scenario describes how [template ownership can be shared.](#allowing-other-users-to-control-and-share-a-template) + + +## Enforcing a Template Setting for Everyone + +Let's say there is an organization in which the administrators decide that all new clusters should be created with Kubernetes version 1.14. + +1. First, an administrator creates a template which specifies the Kubernetes version as 1.14 and marks all other settings as **Allow User Override**. +1. The administrator makes the template public. +1. The administrator turns on template enforcement. + +**Results:** + +- All Rancher users in the organization have access to the template. +- All new clusters created by [standard users](../manage-role-based-access-control-rbac/global-permissions.md) with this template will use Kubernetes 1.14 and they are unable to use a different Kubernetes version. By default, standard users don't have permission to create templates, so this template will be the only template they can use unless more templates are shared with them. +- All standard users must use a cluster template to create a new cluster. They cannot create a cluster without using a template. + +In this way, the administrators enforce the Kubernetes version across the organization, while still allowing end users to configure everything else. + +## Templates for Basic and Advanced Users + +Let's say an organization has both basic and advanced users. Administrators want the basic users to be required to use a template, while the advanced users and administrators create their clusters however they want. + +1. First, an administrator turns on [RKE template enforcement.](enforce-templates.md#requiring-new-clusters-to-use-an-rke-template) This means that every [standard user](../manage-role-based-access-control-rbac/global-permissions.md) in Rancher will need to use an RKE template when they create a cluster. +1. The administrator then creates two templates: + + - One template for basic users, with almost every option specified except for access keys + - One template for advanced users, which has most or all options has **Allow User Override** turned on + +1. The administrator shares the advanced template with only the advanced users. +1. The administrator makes the template for basic users public, so the more restrictive template is an option for everyone who creates a Rancher-provisioned cluster. + +**Result:** All Rancher users, except for administrators, are required to use a template when creating a cluster. Everyone has access to the restrictive template, but only advanced users have permission to use the more permissive template. The basic users are more restricted, while advanced users have more freedom when configuring their Kubernetes clusters. + +## Updating Templates and Clusters Created with Them + +Let's say an organization has a template that requires clusters to use Kubernetes v1.14. However, as time goes on, the administrators change their minds. They decide they want users to be able to upgrade their clusters to use newer versions of Kubernetes. + +In this organization, many clusters were created with a template that requires Kubernetes v1.14. Because the template does not allow that setting to be overridden, the users who created the cluster cannot directly edit that setting. + +The template owner has several options for allowing the cluster creators to upgrade Kubernetes on their clusters: + +- **Specify Kubernetes v1.15 on the template:** The template owner can create a new template revision that specifies Kubernetes v1.15. Then the owner of each cluster that uses that template can upgrade their cluster to a new revision of the template. This template upgrade allows the cluster creator to upgrade Kubernetes to v1.15 on their cluster. +- **Allow any Kubernetes version on the template:** When creating a template revision, the template owner can also mark the the Kubernetes version as **Allow User Override** using the switch near that setting on the Rancher UI. This will allow clusters that upgrade to this template revision to use any version of Kubernetes. +- **Allow the latest minor Kubernetes version on the template:** The template owner can also create a template revision in which the Kubernetes version is defined as **Latest v1.14 (Allows patch version upgrades)**. This means clusters that use that revision will be able to get patch version upgrades, but major version upgrades will not be allowed. + +## Allowing Other Users to Control and Share a Template + +Let's say Alice is a Rancher administrator. She owns an RKE template that reflects her organization's agreed-upon best practices for creating a cluster. + +Bob is an advanced user who can make informed decisions about cluster configuration. Alice trusts Bob to create new revisions of her template as the best practices get updated over time. Therefore, she decides to make Bob an owner of the template. + +To share ownership of the template with Bob, Alice [adds Bob as an owner of her template.](access-or-share-templates.md#sharing-ownership-of-templates) + +The result is that as a template owner, Bob is in charge of version control for that template. Bob can now do all of the following: + +- [Revise the template](manage-rke1-templates.md#updating-a-template) when the best practices change +- [Disable outdated revisions](manage-rke1-templates.md#disabling-a-template-revision) of the template so that no new clusters can be created with it +- [Delete the whole template](manage-rke1-templates.md#deleting-a-template) if the organization wants to go in a different direction +- [Set a certain revision as default](manage-rke1-templates.md#setting-a-template-revision-as-default) when users create a cluster with it. End users of the template will still be able to choose which revision they want to create the cluster with. +- [Share the template](access-or-share-templates.md) with specific users, make the template available to all Rancher users, or share ownership of the template with another user. \ No newline at end of file diff --git a/versioned_docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/infrastructure.md b/versioned_docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/infrastructure.md new file mode 100644 index 00000000000..65ccff89e06 --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/infrastructure.md @@ -0,0 +1,70 @@ +--- +title: RKE Templates and Infrastructure +--- + + + + + +In Rancher, RKE templates are used to provision Kubernetes and define Rancher settings, while node templates are used to provision nodes. + +Therefore, even if RKE template enforcement is turned on, the end user still has flexibility when picking the underlying hardware when creating a Rancher cluster. The end users of an RKE template can still choose an infrastructure provider and the nodes they want to use. + +If you want to standardize the hardware in your clusters, use RKE templates conjunction with node templates or with a server provisioning tool such as Terraform. + +### Node Templates + +[Node templates](../../../../reference-guides/user-settings/manage-node-templates.md) are responsible for node configuration and node provisioning in Rancher. From your user profile, you can set up node templates to define which templates are used in each of your node pools. With node pools enabled, you can make sure you have the required number of nodes in each node pool, and ensure that all nodes in the pool are the same. + +### Terraform + +Terraform is a server provisioning tool. It uses infrastructure-as-code that lets you create almost every aspect of your infrastructure with Terraform configuration files. It can automate the process of server provisioning in a way that is self-documenting and easy to track in version control. + +This section focuses on how to use Terraform with the [Rancher 2 Terraform provider](https://www.terraform.io/docs/providers/rancher2/), which is a recommended option to standardize the hardware for your Kubernetes clusters. If you use the Rancher Terraform provider to provision hardware, and then use an RKE template to provision a Kubernetes cluster on that hardware, you can quickly create a comprehensive, production-ready cluster. + +Terraform allows you to: + +- Define almost any kind of infrastructure-as-code, including servers, databases, load balancers, monitoring, firewall settings, and SSL certificates +- Codify infrastructure across many platforms, including Rancher and major cloud providers +- Commit infrastructure-as-code to version control +- Easily repeat configuration and setup of infrastructure +- Incorporate infrastructure changes into standard development practices +- Prevent configuration drift, in which some servers become configured differently than others + +## How Does Terraform Work? + +Terraform is written in files with the extension `.tf`. It is written in HashiCorp Configuration Language, which is a declarative language that lets you define the infrastructure you want in your cluster, the cloud provider you are using, and your credentials for the provider. Then Terraform makes API calls to the provider in order to efficiently create that infrastructure. + +To create a Rancher-provisioned cluster with Terraform, go to your Terraform configuration file and define the provider as Rancher 2. You can set up your Rancher 2 provider with a Rancher API key. Note: The API key has the same permissions and access level as the user it is associated with. + +Then Terraform calls the Rancher API to provision your infrastructure, and Rancher calls the infrastructure provider. As an example, if you wanted to use Rancher to provision infrastructure on AWS, you would provide both your Rancher API key and your AWS credentials in the Terraform configuration file or in environment variables so that they could be used to provision the infrastructure. + +When you need to make changes to your infrastructure, instead of manually updating the servers, you can make changes in the Terraform configuration files. Then those files can be committed to version control, validated, and reviewed as necessary. Then when you run `terraform apply`, the changes would be deployed. + +## Tips for Working with Terraform + +- There are examples of how to provide most aspects of a cluster in the [documentation for the Rancher 2 provider.](https://www.terraform.io/docs/providers/rancher2/) + +- In the Terraform settings, you can install Docker Machine by using the Docker Machine node driver. + +- You can also modify auth in the Terraform provider. + +- You can reverse engineer how to do define a setting in Terraform by changing the setting in Rancher, then going back and checking your Terraform state file to see how it maps to the current state of your infrastructure. + +## Tip for Creating CIS Benchmark Compliant Clusters + +This section describes one way that you can make security and compliance-related config files standard in your clusters. + +When you create a [CIS benchmark compliant cluster,](../../../../reference-guides/rancher-security/rancher-security.md) you have an encryption config file and an audit log config file. + +Your infrastructure provisioning system can write those files to disk. Then in your RKE template, you would specify where those files will be, then add your encryption config file and audit log config file as extra mounts to the `kube-api-server`. + +Then you would make sure that the `kube-api-server` flag in your RKE template uses your CIS-compliant config files. + +In this way, you can create flags that comply with the CIS benchmark. + +## Resources + +- [Terraform documentation](https://www.terraform.io/docs/) +- [Rancher2 Terraform provider documentation](https://www.terraform.io/docs/providers/rancher2/) +- [The RanchCast - Episode 1: Rancher 2 Terraform Provider](https://youtu.be/YNCq-prI8-8): In this demo, Director of Community Jason van Brackel walks through using the Rancher 2 Terraform Provider to provision nodes and create a custom cluster. \ No newline at end of file diff --git a/versioned_docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/manage-rke1-templates.md b/versioned_docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/manage-rke1-templates.md new file mode 100644 index 00000000000..d729fababc1 --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/manage-rke1-templates.md @@ -0,0 +1,167 @@ +--- +title: Creating and Revising RKE Templates +--- + + + + + + + +This section describes how to manage RKE templates and revisions. You an create, share, update, and delete templates from the **Cluster Management** view under **RKE1 Configuration > RKE Templates**. + +Template updates are handled through a revision system. When template owners want to change or update a template, they create a new revision of the template. Individual revisions cannot be edited. However, if you want to prevent a revision from being used to create a new cluster, you can disable it. + +Template revisions can be used in two ways: to create a new cluster, or to upgrade a cluster that was created with an earlier version of the template. The template creator can choose a default revision, but when end users create a cluster, they can choose any template and any template revision that is available to them. After the cluster is created from a specific revision, it cannot change to another template, but the cluster can be upgraded to a newer available revision of the same template. + +The template owner has full control over template revisions, and can create new revisions to update the template, delete or disable revisions that should not be used to create clusters, and choose which template revision is the default. + + +### Prerequisites + +You can create RKE templates if you have the **Create RKE Templates** permission, which can be [given by an administrator.](creator-permissions.md) + +You can revise, share, and delete a template if you are an owner of the template. For details on how to become an owner of a template, refer to [the documentation on sharing template ownership.](access-or-share-templates.md#sharing-ownership-of-templates) + +### Creating a Template + +1. In the upper left corner, click **☰ > Cluster Management**. +1. Click **RKE1 configuration > Node Templates**. +1. Click **Add Template**. +1. Provide a name for the template. An auto-generated name is already provided for the template' first version, which is created along with this template. +1. Optional: Share the template with other users or groups by [adding them as members.](access-or-share-templates.md#sharing-templates-with-specific-users-or-groups) You can also make the template public to share with everyone in the Rancher setup. +1. Then follow the form on screen to save the cluster configuration parameters as part of the template's revision. The revision can be marked as default for this template. + +**Result:** An RKE template with one revision is configured. You can use this RKE template revision later when you [provision a Rancher-launched cluster](../../launch-kubernetes-with-rancher/launch-kubernetes-with-rancher.md). After a cluster is managed by an RKE template, it cannot be disconnected and the option to uncheck **Use an existing RKE Template and Revision** will be unavailable. + +### Updating a Template + +When you update an RKE template, you are creating a revision of the existing template. Clusters that were created with an older version of the template can be updated to match the new revision. + +You can't edit individual revisions. Since you can't edit individual revisions of a template, in order to prevent a revision from being used, you can [disable it.](#disabling-a-template-revision) + +When new template revisions are created, clusters using an older revision of the template are unaffected. + +1. In the upper left corner, click **☰ > Cluster Management**. +1. In the left navigation menu, click **RKE1 Configuration > RKE Templates**. +1. Go to the template that you want to edit and click the **⋮ > Edit**. +1. Edit the required information and click **Save**. +1. Optional: You can change the default revision of this template and also change who it is shared with. + +**Result:** The template is updated. To apply it to a cluster using an older version of the template, refer to the section on [upgrading a cluster to use a new revision of a template.](#upgrading-a-cluster-to-use-a-new-template-revision) + +### Deleting a Template + +When you no longer use an RKE template for any of your clusters, you can delete it. + +1. In the upper left corner, click **☰ > Cluster Management**. +1. Click **RKE1 configuration > RKE Templates**. +1. Go to the RKE template that you want to delete and click the **⋮ > Delete**. +1. Confirm the deletion. + +**Result:** The template is deleted. + +### Creating a Revision Based on the Default Revision + +You can clone the default template revision and quickly update its settings rather than creating a new revision from scratch. Cloning templates saves you the hassle of re-entering the access keys and other parameters needed for cluster creation. + +1. In the upper left corner, click **☰ > Cluster Management**. +1. In the left navigation menu, click **RKE1 Configuration > RKE Templates**. +1. Go to the RKE template that you want to clone and click the **⋮ > New Revision from Default**. +1. Complete the rest of the form to create a new revision. + +**Result:** The RKE template revision is cloned and configured. + +### Creating a Revision Based on a Cloned Revision + +When creating new RKE template revisions from your user settings, you can clone an existing revision and quickly update its settings rather than creating a new one from scratch. Cloning template revisions saves you the hassle of re-entering the cluster parameters. + +1. In the upper left corner, click **☰ > Cluster Management**. +1. Under **RKE1 configuration**, click **RKE Templates**. +1. Go to the template revision you want to clone. Then select **⋮ > Clone Revision**. +1. Complete the rest of the form. + +**Result:** The RKE template revision is cloned and configured. You can use the RKE template revision later when you provision a cluster. Any existing cluster using this RKE template can be upgraded to this new revision. + +### Disabling a Template Revision + +When you no longer want an RKE template revision to be used for creating new clusters, you can disable it. A disabled revision can be re-enabled. + +You can disable the revision if it is not being used by any cluster. + +1. In the upper left corner, click **☰ > Cluster Management**. +1. In the left navigation menu, click **RKE1 Configuration > RKE Templates**. +1. Go to the template revision you want to disable. Then select **⋮ > Disable**. + +**Result:** The RKE template revision cannot be used to create a new cluster. + +### Re-enabling a Disabled Template Revision + +If you decide that a disabled RKE template revision should be used to create new clusters, you can re-enable it. + +1. In the upper left corner, click **☰ > Cluster Management**. +1. Under **RKE1 configuration**, click **RKE Templates**. +1. Go to the template revision you want to re-enable. Then select **⋮ > Enable**. + +**Result:** The RKE template revision can be used to create a new cluster. + +### Setting a Template Revision as Default + +When end users create a cluster using an RKE template, they can choose which revision to create the cluster with. You can configure which revision is used by default. + +To set an RKE template revision as default, + +1. In the upper left corner, click **☰ > Cluster Management**. +1. In the left navigation menu, click **RKE1 Configuration > RKE templates**. +1. Go to the RKE template revision that should be default and click the **⋮ > Set as Default**. + +**Result:** The RKE template revision will be used as the default option when clusters are created with the template. + +### Deleting a Template Revision + +You can delete all revisions of a template except for the default revision. + +To permanently delete a revision, + +1. In the upper left corner, click **☰ > Cluster Management**. +1. In the left navigation menu, click **RKE1 Configuration > RKE templates**. +1. Go to the RKE template revision that should be deleted and click the **⋮ > Delete**. + +**Result:** The RKE template revision is deleted. + +### Upgrading a Cluster to Use a New Template Revision + +:::note + +This section assumes that you already have a cluster that [has an RKE template applied.](apply-templates.md) + +This section also assumes that you have [updated the template that the cluster is using](#updating-a-template) so that a new template revision is available. + +::: + +To upgrade a cluster to use a new template revision, + +1. In the upper left corner, click **☰ > Cluster Management**. +1. Go to the cluster that you want to upgrade and click **⋮ > Edit Config**. +1. In the **Cluster Options** section, click the dropdown menu for the template revision, then select the new template revision. +1. Click **Save**. + +**Result:** The cluster is upgraded to use the settings defined in the new template revision. + +### Exporting a Running Cluster to a New RKE Template and Revision + +You can save an existing cluster's settings as an RKE template. + +This exports the cluster's settings as a new RKE template, and also binds the cluster to that template. The result is that the cluster can only be changed if the [template is updated,](#updating-a-template) and the cluster is upgraded to [use a newer version of the template](#upgrading-a-cluster-to-use-a-new-template-revision). + +To convert an existing cluster to use an RKE template, + +1. In the upper left corner, click **☰ > Cluster Management**. +1. Go to the cluster that will be converted to use an RKE template and **⋮ > Save as RKE Template**. +1. Enter a name for the RKE template in the form that appears, and click **Create**. + +**Results:** + +- A new RKE template is created. +- The cluster is converted to use the new template. +- New clusters can be [created from the new template and revision.](apply-templates.md#creating-a-cluster-from-an-rke-template) \ No newline at end of file diff --git a/versioned_docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/override-template-settings.md b/versioned_docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/override-template-settings.md new file mode 100644 index 00000000000..67c6a50edd8 --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/override-template-settings.md @@ -0,0 +1,18 @@ +--- +title: Overriding Template Settings +--- + + + + + +When a user creates an RKE template, each setting in the template has a switch in the Rancher UI that indicates if users can override the setting. This switch marks those settings as **Allow User Override**. + +After a cluster is created with a template, end users can't update any of the settings defined in the template unless the template owner marked them as **Allow User Override**. However, if the template is [updated to a new revision](manage-rke1-templates.md) that changes the settings or allows end users to change them, the cluster can be upgraded to a new revision of the template and the changes in the new revision will be applied to the cluster. + +When any parameter is set as **Allow User Override** on the RKE template, it means that end users have to fill out those fields during cluster creation and they can edit those settings afterward at any time. + +The **Allow User Override** model of the RKE template is useful for situations such as: + +- Administrators know that some settings will need the flexibility to be frequently updated over time +- End users will need to enter their own access keys or secret keys, for example, cloud credentials or credentials for backup snapshots \ No newline at end of file diff --git a/versioned_docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/authentication-config/authentication-config.md b/versioned_docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/authentication-config/authentication-config.md new file mode 100644 index 00000000000..a96c26dccd4 --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/authentication-config/authentication-config.md @@ -0,0 +1,153 @@ +--- +title: Configuring Authentication +weight: 10 +--- + + + + + +One of the key features that Rancher adds to Kubernetes is centralized user authentication. This feature allows your users to use one set of credentials to authenticate with any of your Kubernetes clusters. + +This centralized user authentication is accomplished using the Rancher authentication proxy, which is installed along with the rest of Rancher. This proxy authenticates your users and forwards their requests to your Kubernetes clusters using a service account. + +:::warning + +The account used to enable the external provider will be granted admin permissions. If you use a test account or non-admin account, that account will still be granted admin-level permissions. See [External Authentication Configuration and Principal Users](#external-authentication-configuration-and-principal-users) to understand why. + +::: + +## External vs. Local Authentication + +The Rancher authentication proxy integrates with the following external authentication services. + +| Auth Service | +|------------------------------------------------------------------------------------------------------------------------| +| [Microsoft Active Directory](configure-active-directory.md) | +| [GitHub](configure-github.md) | +| [Microsoft Azure AD](configure-azure-ad.md) | +| [FreeIPA](configure-freeipa.md) | +| [OpenLDAP](../configure-openldap/configure-openldap.md) | +| [Microsoft AD FS](../configure-microsoft-ad-federation-service-saml/configure-microsoft-ad-federation-service-saml.md) | +| [PingIdentity](configure-pingidentity.md) | +| [Keycloak (OIDC)](configure-keycloak-oidc.md) | +| [Keycloak (SAML)](configure-keycloak-saml.md) | +| [Okta](configure-okta-saml.md) | +| [Google OAuth](configure-google-oauth.md) | +| [Shibboleth](../configure-shibboleth-saml/configure-shibboleth-saml.md) | +| [Generic (OIDC)](configure-generic-oidc.md) | + +However, Rancher also provides [local authentication](create-local-users.md). + +In most cases, you should use an external authentication service over local authentication, 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 your external authentication provider is unavailable or undergoing maintenance. + +## Users and Groups + +:::note + +- Local authentication does not support creating or managing groups. +- After an external authentication provider is configured, note that local Rancher scoped administrative users only display resources such as users and groups that they are a member of in the respective authentication provider. + +::: + +Rancher relies on users and groups to determine who is allowed to log in to Rancher and which resources they can access. When authenticating with an external provider, groups are provided from the external provider based on the user. These users and groups are given specific roles to resources like clusters, projects, and global DNS providers and entries. When you give access to a group, all users who are a member of that group in the authentication provider will be able to access the resource with the permissions that you've specified. For more information on roles and permissions, see [Role Based Access Control](../manage-role-based-access-control-rbac/manage-role-based-access-control-rbac.md). + +For more information, see [Users and Groups](manage-users-and-groups.md) + +## Scope of Rancher Authorization + +After you configure Rancher to allow sign on using an external authentication service, you should configure who should be allowed to log in and use Rancher. The following options are available: + +| Access Level | Description | +|----------------------------------------------|-------------| +| Allow any valid Users | _Any_ user in the authorization service can access Rancher. We generally discourage use of this setting! | +| Allow members of Clusters, Projects, plus Authorized Users and Organizations | Any user in the authorization service and any group added as a **Cluster Member** or **Project Member** can log in to Rancher. Additionally, any user in the authentication service or group you add to the **Authorized Users and Organizations** list may log in to Rancher. | +| Restrict access to only Authorized Users and Organizations | Only users in the authentication service or groups added to the Authorized Users and Organizations can log in to Rancher. | + +:::warning + +Only trusted admin-level users should have access to the local cluster, which manages all of the other clusters in a Rancher instance. Rancher is directly installed on the local cluster, and Rancher's management features allow admins on the local cluster to provision, modify, connect to, and view details about downstream clusters. Since the local cluster is key to a Rancher instance's architecture, inappropriate access carries security risks. + +::: + +To set the Rancher access level for users in the authorization service, follow these steps: + +1. In the upper left corner, click **☰ > Users & Authentication**. +1. In the left navigation bar, click **Auth Provider**. +1. After setting up the configuration details for an auth provider, use the **Site Access** options to configure the scope of user authorization. The table above explains the access level for each option. +1. Optional: If you choose an option other than **Allow any valid Users,** you can add users to the list of authorized users and organizations by searching for them in the text field that appears. +1. Click **Save**. + +**Result:** The Rancher access configuration settings are applied. + +:::note SAML Provider Caveats + +- Users and groups aren't validated when you assign permissions to them in Rancher. +- When adding users, the exact user IDs (i.e. `UID Field`) must be entered correctly. As you type the user ID, there will be no search for other user IDs that may match. +- When adding groups, you must select the group from the drop-down that is next to the text box. Rancher assumes that any input from the text box is a user. +- The group drop-down shows only the groups that you are a member of. However, if you have Administrator permissions or Restricted Administrator permissions, you can join a group that you are not a member of. + +::: + +## External Authentication Configuration and Principal Users + +Configuring external authentication requires: + +- A local user assigned the administrator role, called hereafter the _local principal_. +- An external user that can authenticate with your external authentication service, called hereafter the _external principal_. + +The configuration of external authentication also affects how principal users are managed within Rancher. Specifically, when a user account enables an external provider, it is granted admin-level permissions. This is because the local principal and external principal share the same user ID and access rights. + +The following instructions demonstrate these effects: + +1. Sign into Rancher as the local principal and complete configuration of external authentication. + + ![Sign In](/img/sign-in.png) + +2. Rancher associates the external principal with the local principal. These two users share the local principal's user ID. + + ![Principal ID Sharing](/img/principal-ID.png) + +3. After you complete configuration, Rancher automatically signs out the local principal. + + ![Sign Out Local Principal](/img/sign-out-local.png) + +4. Then, Rancher automatically signs you back in as the external principal. + + ![Sign In External Principal](/img/sign-in-external.png) + +5. Because the external principal and the local principal share an ID, no unique object for the external principal displays on the Users page. + + ![Sign In External Principal](/img/users-page.png) + +6. The external principal and the local principal share the same access rights. + +:::note Reconfiguring a previously set up auth provider + +If you need to reconfigure or disable then re-enable a provider that had been previously set up, ensure that the user who attempts to do so +is logged in to Rancher as an external user, not the local admin. + +::: + +## Disabling An Auth Provider + +When you disable an auth provider, Rancher deletes all resources associated with it, such as: +- Secrets. +- Global role bindings. +- Cluster role template bindings. +- Project role template bindings. +- External users associated with the provider, but who never logged in as local users to Rancher. + +As this operation may lead to a loss of many resources, you may want to add a safeguard on the provider. To ensure that this cleanup process doesn't run when the auth provider is disabled, add a special annotation to the corresponding auth config. + +For example, to add a safeguard to the Azure AD provider, annotate the `azuread` authconfig object: + +`kubectl annotate --overwrite authconfig azuread management.cattle.io/auth-provider-cleanup='user-locked'` + +Rancher won't perform cleanup until you set the annotation to `unlocked`. + +### Running Resource Cleanup Manually + +Rancher might retain resources from a previously disabled auth provider configuration in the local cluster, even after you configure another auth provider. For example, if you used Provider A, then disabled it and started using Provider B, when you upgrade to a new version of Rancher, you can manually trigger cleanup on resources configured by Provider A. + +To manually trigger cleanup for a disabled auth provider, add the `management.cattle.io/auth-provider-cleanup` annotation with the `unlocked` value to its auth config. diff --git a/versioned_docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/authentication-config/configure-active-directory.md b/versioned_docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/authentication-config/configure-active-directory.md new file mode 100644 index 00000000000..3c789d640d8 --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/authentication-config/configure-active-directory.md @@ -0,0 +1,223 @@ +--- +title: Configure Active Directory (AD) +--- + + + + + +If your organization uses Microsoft Active Directory as central user repository, you can configure Rancher to communicate with an Active Directory server to authenticate users. This allows Rancher admins to control access to clusters and projects based on users and groups managed externally in the Active Directory, while allowing end-users to authenticate with their AD credentials when logging in to the Rancher UI. + +Rancher uses LDAP to communicate with the Active Directory server. The authentication flow for Active Directory is therefore the same as for the [OpenLDAP authentication](../configure-openldap/configure-openldap.md) integration. + +:::note + +Before you start, please familiarise yourself with the concepts of [External Authentication Configuration and Principal Users](authentication-config.md#external-authentication-configuration-and-principal-users). + +::: + +## Prerequisites + +You'll need to create or obtain from your AD administrator a new AD user to use as service account for Rancher. This user must have sufficient permissions to perform LDAP searches and read attributes of users and groups under your AD domain. + +Usually a (non-admin) **Domain User** account should be used for this purpose, as by default such user has read-only privileges for most objects in the domain partition. + +Note however, that in some locked-down Active Directory configurations this default behaviour may not apply. In such case you will need to ensure that the service account user has at least **Read** and **List Content** permissions granted either on the Base OU (enclosing users and groups) or globally for the domain. + +:::note Using TLS? + +- If the certificate used by the AD server is self-signed or not from a recognized certificate authority, make sure have at hand the CA certificate (concatenated with any intermediate certificates) in PEM format. You will have to paste in this certificate during the configuration so that Rancher is able to validate the certificate chain. + +- Upon an upgrade to v2.6.0, authenticating via Rancher against an active directory using TLS can fail if the certificates on the AD server do not support SAN attributes. This is a check enabled by default in Go v1.15. + + - The error received is "Error creating SSL connection: LDAP Result Code 200 "Network Error": x509: certificate relies on legacy Common Name field, use SANs or temporarily enable Common Name matching with GODEBUG=x509ignoreCN=0". + + - To resolve the error, update or replace the certificates on the AD server with new ones that support the SAN attribute. Alternatively, this error can be ignored by setting `GODEBUG=x509ignoreCN=0` as an environment variable to Rancher server container. + +::: + +## Configuration Steps +### Open Active Directory Configuration + +1. Log into the Rancher UI using the initial local `admin` account. +1. In the top left corner, click **☰ > Users & Authentication**. +1. In the left navigation menu, click **Auth Provider**. +1. Click **ActiveDirectory**. The **Authentication Provider: ActiveDirectory** form will be displayed. +1. Fill out the form. For help, refer to the details on configuration options below. +1. Click **Enable**. + +### Configure Active Directory Server Settings + +In the section titled `1. Configure an Active Directory server`, complete the fields with the information specific to your Active Directory server. Please refer to the following table for detailed information on the required values for each parameter. + +:::note + +If you are unsure about the correct values to enter in the user/group Search Base field, please refer to [Identify Search Base and Schema using ldapsearch](#annex-identify-search-base-and-schema-using-ldapsearch). + +::: + +**Table 1: AD Server parameters** + +| Parameter | Description | +|:--|:--| +| Hostname | Specify the hostname or IP address of the AD server | +| Port | Specify the port at which the Active Directory server is listening for connections. Unencrypted LDAP normally uses the standard port of 389, while LDAPS uses port 636.| +| TLS | Check this box to enable LDAP over SSL/TLS (commonly known as LDAPS).| +| Server Connection Timeout | The duration in number of seconds that Rancher waits before considering the AD server unreachable. | +| Service Account Username | Enter the username of an AD account with read-only access to your domain partition (see [Prerequisites](#prerequisites)). The username can be entered in NetBIOS format (e.g. "DOMAIN\serviceaccount") or UPN format (e.g. "serviceaccount@domain.com"). | +| Service Account Password | The password for the service account. | +| Default Login Domain | When you configure this field with the NetBIOS name of your AD domain, usernames entered without a domain (e.g. "jdoe") will automatically be converted to a slashed, NetBIOS logon (e.g. "LOGIN_DOMAIN\jdoe") when binding to the AD server. If your users authenticate with the UPN (e.g. "jdoe@acme.com") as username then this field **must** be left empty. | +| User Search Base | The Distinguished Name of the node in your directory tree from which to start searching for user objects. All users must be descendents of this base DN. For example: "ou=people,dc=acme,dc=com".| +| Group Search Base | If your groups live under a different node than the one configured under `User Search Base` you will need to provide the Distinguished Name here. Otherwise leave it empty. For example: "ou=groups,dc=acme,dc=com".| + +--- + +### Configure User/Group Schema + +In the section titled `2. Customize Schema` you must provide Rancher with a correct mapping of user and group attributes corresponding to the schema used in your directory. + +Rancher uses LDAP queries to search for and retrieve information about users and groups within the Active Directory. The attribute mappings configured in this section are used to construct search filters and resolve group membership. It is therefore paramount that the provided settings reflect the reality of your AD domain. + +:::note + +If you are unfamiliar with the schema used in your Active Directory domain, please refer to [Identify Search Base and Schema using ldapsearch](#annex-identify-search-base-and-schema-using-ldapsearch) to determine the correct configuration values. + +::: + +#### User Schema + +The table below details the parameters for the user schema section configuration. + +**Table 2: User schema configuration parameters** + +| Parameter | Description | +|:--|:--| +| Object Class | The name of the object class used for user objects in your domain. If defined, only specify the name of the object class - *don't* include it in an LDAP wrapper such as &(objectClass=xxxx) | +| Username Attribute | The user attribute whose value is suitable as a display name. | +| Login Attribute | The attribute whose value matches the username part of credentials entered by your users when logging in to Rancher. If your users authenticate with their UPN (e.g. "jdoe@acme.com") as username then this field must normally be set to `userPrincipalName`. Otherwise for the old, NetBIOS-style logon names (e.g. "jdoe") it's usually `sAMAccountName`. | +| User Member Attribute | The attribute containing the groups that a user is a member of. | +| Search Attribute | When a user enters text to add users or groups in the UI, Rancher queries the AD server and attempts to match users by the attributes provided in this setting. Multiple attributes can be specified by separating them with the pipe ("\|") symbol. To match UPN usernames (e.g. jdoe@acme.com) you should usually set the value of this field to `userPrincipalName`. | +| Search Filter | This filter gets applied to the list of users that is searched when Rancher attempts to add users to a site access list or tries to add members to clusters or projects. For example, a user search filter could be (|(memberOf=CN=group1,CN=Users,DC=testad,DC=rancher,DC=io)(memberOf=CN=group2,CN=Users,DC=testad,DC=rancher,DC=io)). Note: If the search filter does not use [valid AD search syntax,](https://docs.microsoft.com/en-us/windows/win32/adsi/search-filter-syntax) the list of users will be empty. | +| User Enabled Attribute | The attribute containing an integer value representing a bitwise enumeration of user account flags. Rancher uses this to determine if a user account is disabled. You should normally leave this set to the AD standard `userAccountControl`. | +| Disabled Status Bitmask | This is the value of the `User Enabled Attribute` designating a disabled user account. You should normally leave this set to the default value of "2" as specified in the Microsoft Active Directory schema (see [here](https://docs.microsoft.com/en-us/windows/desktop/adschema/a-useraccountcontrol#remarks)). | + +--- + +#### Group Schema + +The table below details the parameters for the group schema configuration. + +**Table 3: Group schema configuration parameters** + +| Parameter | Description | +|:--|:--| +| Object Class | The name of the object class used for group objects in your domain. If defined, only specify the name of the object class - *don't* include it in an LDAP wrapper such as &(objectClass=xxxx) | +| Name Attribute | The group attribute whose value is suitable for a display name. | +| Group Member User Attribute | The name of the **user attribute** whose format matches the group members in the `Group Member Mapping Attribute`. | +| Group Member Mapping Attribute | The name of the group attribute containing the members of a group. | +| Search Attribute | Attribute used to construct search filters when adding groups to clusters or projects. See description of user schema `Search Attribute`. | +| Search Filter | This filter gets applied to the list of groups that is searched when Rancher attempts to add groups to a site access list or tries to add groups to clusters or projects. For example, a group search filter could be (|(cn=group1)(cn=group2)). Note: If the search filter does not use [valid AD search syntax,](https://docs.microsoft.com/en-us/windows/win32/adsi/search-filter-syntax) the list of groups will be empty. | +| Group DN Attribute | The name of the group attribute whose format matches the values in the user attribute describing a the user's memberships. See `User Member Attribute`. | +| Nested Group Membership | This settings defines whether Rancher should resolve nested group memberships. Use only if your organization makes use of these nested memberships (i.e., you have groups that contain other groups as members. We advise avoiding nested groups when possible to avoid potential performance issues when there is a large amount of nested memberships). | + +--- + +### Test Authentication + +Once you have completed the configuration, proceed by testing the connection to the AD server **using your AD admin account**. If the test is successful, authentication with the configured Active Directory will be enabled implicitly with the account you test with set as admin. + +:::note + +The AD user pertaining to the credentials entered in this step will be mapped to the local principal account and assigned administrator privileges in Rancher. You should therefore make a conscious decision on which AD account you use to perform this step. + +::: + +1. Enter the **username** and **password** for the AD account that should be mapped to the local principal account. +2. Click **Authenticate with Active Directory** to finalise the setup. + +**Result:** + +- Active Directory authentication has been enabled. +- You have been signed into Rancher as administrator using the provided AD credentials. + +:::note + +You will still be able to login using the locally configured `admin` account and password in case of a disruption of LDAP services. + +::: + +## Annex: Identify Search Base and Schema using ldapsearch + +In order to successfully configure AD authentication it is crucial that you provide the correct configuration pertaining to the hierarchy and schema of your AD server. + +The [`ldapsearch`](https://manpages.ubuntu.com/manpages/noble/en/man1/ldapsearch.1.html) tool allows you to query your AD server to learn about the schema used for user and group objects. + +For the purpose of the example commands provided below we will assume: + +- The Active Directory server has a hostname of `ad.acme.com` +- The server is listening for unencrypted connections on port `389` +- The Active Directory domain is `acme` +- You have a valid AD account with the username `jdoe` and password `secret` + +### Identify Search Base + +First we will use `ldapsearch` to identify the Distinguished Name (DN) of the parent node(s) for users and groups: + +``` +$ ldapsearch -x -D "acme\jdoe" -w "secret" -p 389 \ +-h ad.acme.com -b "dc=acme,dc=com" -s sub "sAMAccountName=jdoe" +``` + +This command performs an LDAP search with the search base set to the domain root (`-b "dc=acme,dc=com"`) and a filter targeting the user account (`sAMAccountNam=jdoe`), returning the attributes for said user: + +![](/img/ldapsearch-user.png) + +Since in this case the user's DN is `CN=John Doe,CN=Users,DC=acme,DC=com` [5], we should configure the **User Search Base** with the parent node DN `CN=Users,DC=acme,DC=com`. + +Similarly, based on the DN of the group referenced in the **memberOf** attribute [4], the correct value for the **Group Search Base** would be the parent node of that value, i.e., `OU=Groups,DC=acme,DC=com`. + +### Identify User Schema + +The output of the above `ldapsearch` query also allows to determine the correct values to use in the user schema configuration: + +- `Object Class`: **person** [1] +- `Username Attribute`: **name** [2] +- `Login Attribute`: **sAMAccountName** [3] +- `User Member Attribute`: **memberOf** [4] + +:::note + +If the AD users in our organization were to authenticate with their UPN (e.g. jdoe@acme.com) instead of the short logon name, then we would have to set the `Login Attribute` to **userPrincipalName** instead. + +::: + +We'll also set the `Search Attribute` parameter to **sAMAccountName|name**. That way users can be added to clusters/projects in the Rancher UI either by entering their username or full name. + +### Identify Group Schema + +Next, we'll query one of the groups associated with this user, in this case `CN=examplegroup,OU=Groups,DC=acme,DC=com`: + +``` +$ ldapsearch -x -D "acme\jdoe" -w "secret" -p 389 \ +-h ad.acme.com -b "ou=groups,dc=acme,dc=com" \ +-s sub "CN=examplegroup" +``` + +This command will inform us on the attributes used for group objects: + +![](/img/ldapsearch-group.png) + +Again, this allows us to determine the correct values to enter in the group schema configuration: + +- `Object Class`: **group** [1] +- `Name Attribute`: **name** [2] +- `Group Member Mapping Attribute`: **member** [3] +- `Search Attribute`: **sAMAccountName** [4] + +Looking at the value of the **member** attribute, we can see that it contains the DN of the referenced user. This corresponds to the **distinguishedName** attribute in our user object. Accordingly will have to set the value of the `Group Member User Attribute` parameter to this attribute. + +In the same way, we can observe that the value in the **memberOf** attribute in the user object corresponds to the **distinguishedName** [5] of the group. We therefore need to set the value for the `Group DN Attribute` parameter to this attribute. + +## Annex: Troubleshooting + +If you are experiencing issues while testing the connection to the Active Directory server, first double-check the credentials entered for the service account as well as the search base configuration. You may also inspect the Rancher logs to help pinpointing the problem cause. Debug logs may contain more detailed information about the error. Please refer to [How can I enable debug logging](../../../../faq/technical-items.md#how-can-i-enable-debug-logging) in this documentation. diff --git a/versioned_docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/authentication-config/configure-amazon-cognito.md b/versioned_docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/authentication-config/configure-amazon-cognito.md new file mode 100644 index 00000000000..91ac8b6b51c --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/authentication-config/configure-amazon-cognito.md @@ -0,0 +1,64 @@ +--- +title: Configure Amazon Cognito +description: Create an Amazon Cognito user pool and configure Rancher to work with Amazon Cognito. Your users can then sign into Rancher using their login from Amazon Cognito. +--- + + + + + +If your organization uses Amazon Cognito for user authentication, you can configure Rancher to allow login using Amazon Cognito credentials. The following instructions describe how to configure Rancher to work with Amazon Cognito: + +## Prerequisites + +- In Rancher: + - Amazon Cognito is disabled. + +:::note +Consult the Amazon Cognito [documentation](https://aws.amazon.com/cognito/getting-started/) to configure the user pool. +::: + +- In Amazon Cognito: + - Create a new user pool or use an existing one. + - In the `App client` settings, set the redirect URL to `https://yourRancherHostURL/verify-auth`. Replace `yourRancherHostURL` with the actual hostname of your Rancher instance (e.g., https://rancher.example.com/verify-auth). + +## Configuring Amazon Cognito in Rancher + +1. In the upper left corner of the Rancher UI, click **☰ > Users & Authentication**. +1. In the left navigation bar, click **Auth Provider**. +1. Select **Amazon Cognito**. +1. Complete the **Configure an Amazon Cognito account** form. For help with filling the form, see the [configuration reference](#configuration-reference). +1. Click **Enable**. + + Rancher will redirect you to the Amazon Cognito login page. Enter your Amazon Cognito credentials to validate your Rancher configuration. + + :::note + + You may need to disable your popup blocker to see the Amazon Cognito login page. + + ::: + +**Result:** Rancher is configured to work with your Amazon Cognito using the OIDC protocol. Your users can now sign into Rancher using their Amazon Cognito logins. + +:::note +User and group search is not supported for Amazon Cognito. When assigning permissions to a Project or Cluster, you must manually enter the UserID generated by Cognito +if the user has not yet logged in to Rancher. However, if the user has previously logged in, you can assign permissions using their username or email address. +::: + +## Configuration Reference + +| Field | Description | +| ------------------------- |-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| Client ID | The Client ID of your Amazon Cognito App Client. | +| Client Secret | The generated Secret of your Amazon Cognito App Client. | +| Issuer | The Issuer URL of your Amazon Cognito App Client. It follows the format `https://cognito-idp.{region}.amazonaws.com/{userPoolId}`, and can be found in the App Client settings page. Rancher uses the Issuer URL to fetch all of the required URLs. | + +## Troubleshooting + +### 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) + + \ No newline at end of file diff --git a/versioned_docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/authentication-config/configure-azure-ad.md b/versioned_docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/authentication-config/configure-azure-ad.md new file mode 100644 index 00000000000..a7f84745885 --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/authentication-config/configure-azure-ad.md @@ -0,0 +1,384 @@ +--- +title: Configure Azure AD +--- + + + + + +## Microsoft Graph API + +Microsoft Graph API is now the flow through which you will set up Azure AD. The below sections will assist [new users](#new-user-setup) in configuring Azure AD with a new instance as well as assist existing Azure app owners in [migrating to the new flow](#migrating-from-azure-ad-graph-api-to-microsoft-graph-api). + +The Microsoft Graph API flow in Rancher is constantly evolving. We recommend that you use the latest patched version of 2.7, as it is still in active development and will continue to receive new features and improvements. + +### New User Setup + +If you have an instance of Active Directory (AD) hosted in Azure, you can configure Rancher to allow your users to log in using their AD accounts. Configuration of Azure AD external authentication requires you to make configurations in both Azure and Rancher. + +:::note Notes + +- Azure AD integration only supports Service Provider initiated logins. +- Most of this procedure takes place from the [Microsoft Azure Portal](https://portal.azure.com/). + +::: + +#### Azure Active Directory Configuration Outline + +Configuring Rancher to allow your users to authenticate with their Azure AD accounts involves multiple procedures. Review the outline below before getting started. + +:::tip + +Before you start, open two browser tabs: one for Rancher, and one for the Azure portal. This will help with copying and pasting configuration values from the portal to Rancher. + +::: + +#### 1. Register Rancher with Azure + +Before enabling Azure AD within Rancher, you must register Rancher with Azure. + +1. Log in to [Microsoft Azure](https://portal.azure.com/) as an administrative user. Configuration in future steps requires administrative access rights. + +1. Use search to open the **App registrations** service. + +1. Click **New registration** and complete the form. + + ![New App Registration](/img/new-app-registration.png) + + 1. Enter a **Name** (something like `Rancher`). + + 1. From **Supported account types**, select "Accounts in this organizational directory only (AzureADTest only - Single tenant)" This corresponds to the legacy app registration options. + + :::note + + In the updated Azure portal, Redirect URIs are synonymous with Reply URLs. In order to use Azure AD with Rancher, you must whitelist Rancher with Azure (previously done through Reply URLs). Therefore, you must ensure to fill in the Redirect URI with your Rancher server URL, to include the verification path as listed below. + + ::: + + 1. In the [**Redirect URI**](https://docs.microsoft.com/en-us/azure/active-directory/develop/reply-url) section, make sure **Web** is selected from the dropdown and enter the URL of your Rancher Server in the text box next to the dropdown. This Rancher server URL should be appended with the verification path: `/verify-auth-azure`. + + :::tip + + You can find your personalized Azure Redirect URI (reply URL) in Rancher on the Azure AD Authentication page (Global View > Authentication > Web). + + ::: + + 1. Click **Register**. + +:::note + +It can take up to five minutes for this change to take affect, so don't be alarmed if you can't authenticate immediately after Azure AD configuration. + +::: + +#### 2. Create a new client secret + +From the Azure portal, create a client secret. Rancher will use this key to authenticate with Azure AD. + +1. Use search to open **App registrations** services. Then open the entry for Rancher that you created in the last procedure. + + ![Open Rancher Registration](/img/open-rancher-app-reg.png) + +1. From the navigation pane, click **Certificates & secrets**. + +1. Click **New client secret**. + ![Create new client secret](/img/new-client-secret.png) +1. Enter a **Description** (something like `Rancher`). +1. Select the duration from the options under **Expires**. This drop-down menu sets the expiration date for the key. Shorter durations are more secure, but require you to create a new key more frequently. +Note that users won't be able to log in to Rancher if it detects that the application secret has expired. To avoid this problem, rotate the secret in Azure and update it in Rancher before it expires. +1. Click **Add** (you don't need to enter a value—it will automatically populate after you save). + + +1. You'll enter this key into the Rancher UI later as your **Application Secret**. Since you won't be able to access the key value again within the Azure UI, keep this window open for the rest of the setup process. + +#### 3. Set Required Permissions for Rancher + +Next, set API permissions for Rancher within Azure. + +:::caution + +Ensure that you set Application permissions, and *not* Delegated permissions. Otherwise, you won't be able to login to Azure AD. + +::: + +1. From the navigation pane on, select **API permissions**. + +1. Click **Add a permission**. + +1. From the Microsoft Graph API, select the following **Application Permissions**: `Directory.Read.All` + + ![Select API Permissions](/img/api-permissions.png) + +1. Return to **API permissions** in the nav bar. From there, click **Grant admin consent**. Then click **Yes**. The app's permissions should look like the following: + +![Open Required Permissions](/img/select-req-permissions.png) + +:::note + +Rancher doesn't validate the permissions you grant to the app in Azure. You're free to try any permissions you want, as long as they allow Rancher to work with AD users and groups. + +Specifically, Rancher needs permissions that allow the following actions: +- Get a user. +- List all users. +- List groups of which a given user is a member. +- Get a group. +- List all groups. + +Rancher performs these actions either to log in a user or to run a user/group search. Keep in mind that the permissions must be of type `Application`. + +Here are a few examples of permission combinations that satisfy Rancher's needs: +- `Directory.Read.All` +- `User.Read.All` and `GroupMember.Read.All` +- `User.Read.All` and `Group.Read.All` + +::: + +#### 4. Allow Public Client Flows + +To login from Rancher CLI you must allow public client flows: + +1. From the left navigation menu, select **Authentication**. + +1. Under **Advanced Settings**, select **Yes** on the toggle next to **Allow public client flows**. + + ![Allow Public Client Flows](/img/azure-public-client-flows.png) + +#### 5. Copy Azure Application Data + +![Application ID](/img/app-configuration.png) + +1. Obtain your Rancher **Tenant ID**. + + 1. Use search to open **App registrations**. + + 1. Find the entry you created for Rancher. + + 1. Copy the **Directory ID** and paste it into Rancher as your **Tenant ID**. + +1. Obtain your Rancher **Application (Client) ID**. + + 1. If you aren't already there, use search to open **App registrations**. + + 1. In **Overview**, find the entry you created for Rancher. + + 1. Copy the **Application (Client) ID** and paste it into Rancher as your **Application ID**. + +1. In most cases, your endpoint options will either be [Standard](#global) or [China](#china). For either of these options, you only need to enter the **Tenant ID**, **Application ID**, and **Application Secret**. + +![Standard Endpoint Options](/img/tenant-application-id-secret.png) + +**For Custom Endpoints:** + +:::caution + +Custom Endpoints are not tested or fully supported by Rancher. + +::: + +You'll also need to manually enter the Graph, Token, and Auth Endpoints. + +- From **App registrations**, click **Endpoints**: + +![Click Endpoints](/img/endpoints.png) + +- The following endpoints will be your Rancher endpoint values. Make sure to use the v1 version of these endpoints: + - **Microsoft Graph API endpoint** (Graph Endpoint) + - **OAuth 2.0 token endpoint (v1)** (Token Endpoint) + - **OAuth 2.0 authorization endpoint (v1)** (Auth Endpoint) + +#### 6. Configure Azure AD in Rancher + +To complete configuration, enter information about your AD instance in the Rancher UI. + +1. Log into Rancher. + +1. In the top left corner, click **☰ > Users & Authentication**. + +1. In the left navigation menu, click **Auth Provider**. + +1. Click **AzureAD**. + +1. Complete the **Configure Azure AD Account** form using the information you copied while completing [Copy Azure Application Data](#5-copy-azure-application-data). + + :::caution + + The Azure AD account will be granted administrator privileges, since its details will be mapped to the Rancher local principal account. Make sure that this level of privilege is appropriate before you continue. + + ::: + + **For Standard or China Endpoints:** + + The following table maps the values you copied in the Azure portal to the fields in Rancher: + + | Rancher Field | Azure Value | + | ------------------ | ------------------------------------- | + | Tenant ID | Directory ID | + | Application ID | Application ID | + | Application Secret | Key Value | + | Endpoint | https://login.microsoftonline.com/ | + + **For Custom Endpoints:** + + The following table maps your custom config values to Rancher fields: + + | Rancher Field | Azure Value | + | ------------------ | ------------------------------------- | + | Graph Endpoint | Microsoft Graph API Endpoint | + | Token Endpoint | OAuth 2.0 Token Endpoint | + | Auth Endpoint | OAuth 2.0 Authorization Endpoint | + + **Important:** When entering the Graph Endpoint in a custom config, remove the tenant ID from the URL: + + https://graph.microsoft.com/abb5adde-bee8-4821-8b03-e63efdc7701c + +1. (Optional) In Rancher v2.9.0 and later, you can filter users' group memberships in Azure AD to reduce the amount of log data generated. See steps 4–5 of [Filtering Users by Azure AD Auth Group Memberships](#filtering-users-by-azure-ad-auth-group-memberships) for full instructions. + +1. Click **Enable**. + +**Result:** Azure Active Directory authentication is configured. + +#### (Optional) Configure Authentication with Multiple Rancher Domains + +If you have multiple Rancher domains, it's not possible to configure multiple redirect URIs through the Rancher UI. The Azure AD configuration file, `azuread`, only allows one redirect URI by default. You must manually edit `azuread` to set the redirect URI as needed for any other domains. If you don't manually edit `azuread`, then upon a successful login attempt to any domain, Rancher automatically redirects the user to the **Redirect URI** value you set when you registered the app in [Step 1. Register Rancher with Azure](#1-register-rancher-with-azure). + +### Migrating from Azure AD Graph API to Microsoft Graph API + +Since the [Azure AD Graph API](https://docs.microsoft.com/en-us/graph/migrate-azure-ad-graph-overview) is deprecated and slated to retire in June 2023, admins should update their Azure AD App to use the [Microsoft Graph API](https://docs.microsoft.com/en-us/graph/use-the-api) in Rancher. +This needs to be done well in advance of the endpoint being retired. +If Rancher is still configured to use the Azure AD Graph API when it is retired, users may not be able to log into Rancher using Azure AD. + +#### Updating Endpoints in the Rancher UI + +:::caution + +Admins should create a [Rancher backup](../../../new-user-guides/backup-restore-and-disaster-recovery/back-up-rancher.md) before they commit to the endpoint migration described below. + +::: + +1. [Update](#3-set-required-permissions-for-rancher) the permissions of your Azure AD app registration. This is critical. + +1. Log into Rancher. + +1. In the Rancher UI homepage, make note of the banner at the top of screen that advises users to update their Azure AD authentication. Click on the link provided to do so. + + ![Rancher UI Banner](/img/rancher-ui-azure-update.png) + +1. To complete the move to the new Microsoft Graph API, click **Update Endpoint**. + + **Note:** Ensure that your Azure app has a [new set of permissions](#3-set-required-permissions-for-rancher) before starting the update. + + ![Update Endpoint](/img/rancher-button-to-update.png) + +1. When you receive the pop-up warning message, click **Update**. + + ![Azure Update Pop-up](/img/azure-update-popup.png) + +1. Refer to the [tables](#global) below for the full list of endpoint changes that Rancher performs. Admins do not need to do this manually. + +#### Air-Gapped Environments + +In air-gapped environments, admins should ensure that their endpoints are whitelisted (see note on [Step 3.2 of Register Rancher with Azure](#1-register-rancher-with-azure)) since the Graph Endpoint URL is changing. + +#### Rolling Back the Migration + +If you need to roll back your migration, please note the following: + +1. Admins are encouraged to use the proper restore process if they want to go back. Please see [backup docs](../../../new-user-guides/backup-restore-and-disaster-recovery/back-up-rancher.md), [restore docs](../../../new-user-guides/backup-restore-and-disaster-recovery/restore-rancher.md), and [examples](../../../../reference-guides/backup-restore-configuration/examples.md) for reference. + +1. Azure app owners who want to rotate the Application Secret will need to also rotate it in Rancher as Rancher does not automatically update the Application Secret when it is changed in Azure. In Rancher, note that it is stored in a Kubernetes secret called `azureadconfig-applicationsecret` which is in the `cattle-global-data` namespace. + +:::caution + +If you upgrade to Rancher v2.7.0+ with an existing Azure AD setup, and choose to disable the auth provider, you won't be able to restore the previous setup. You also won't be able to set up Azure AD using the old flow. You'll need to re-register with the new auth flow. Since Rancher now uses the Graph API, users need set up the [proper permissions in the Azure portal](#3-set-required-permissions-for-rancher). + +::: + + +#### Global: + +Rancher Field | Deprecated Endpoints +---------------- | ------------------------------------------------------------- +Auth Endpoint | https://login.microsoftonline.com/{tenantID}/oauth2/authorize +Endpoint | https://login.microsoftonline.com/ +Graph Endpoint | https://graph.windows.net/ +Token Endpoint | https://login.microsoftonline.com/{tenantID}/oauth2/token + +Rancher Field | New Endpoints +---------------- | ------------------------------------------------------------------ +Auth Endpoint | https://login.microsoftonline.com/{tenantID}/oauth2/v2.0/authorize +Endpoint | https://login.microsoftonline.com/ +Graph Endpoint | https://graph.microsoft.com +Token Endpoint | https://login.microsoftonline.com/{tenantID}/oauth2/v2.0/token + +#### China: + +Rancher Field | Deprecated Endpoints +---------------- | ---------------------------------------------------------- +Auth Endpoint | https://login.chinacloudapi.cn/{tenantID}/oauth2/authorize +Endpoint | https://login.chinacloudapi.cn/ +Graph Endpoint | https://graph.chinacloudapi.cn/ +Token Endpoint | https://login.chinacloudapi.cn/{tenantID}/oauth2/token + +Rancher Field | New Endpoints +---------------- | ------------------------------------------------------------------------- +Auth Endpoint | https://login.partner.microsoftonline.cn/{tenantID}/oauth2/v2.0/authorize +Endpoint | https://login.partner.microsoftonline.cn/ +Graph Endpoint | https://microsoftgraph.chinacloudapi.cn +Token Endpoint | https://login.partner.microsoftonline.cn/{tenantID}/oauth2/v2.0/token + +## Filtering Users by Azure AD Auth Group Memberships + +In Rancher v2.9.0 and later, you can filter users' group memberships from Azure AD to reduce the amount of log data generated. If you did not filter group memberships during initial setup, you can still add filters on an existing Azure AD configuration. + +:::warning + +Filtering out a user group membership affects more than just logging. + +Since the filter prevents Rancher from seeing that the user belongs to an excluded group, it also does not see any permissions from that group. This means that excluding a group from the filter can have the side effect of denying users permissions they should have. + +::: + +1. In Rancher, in the top left corner, click **☰ > Users & Authentication**. + +1. In the left navigation menu, click **Auth Provider**. + +1. Click **AzureAD**. + +1. Click the checkbox next to **Limit users by group membership**. + +1. Enter an [OData filter clause](https://learn.microsoft.com/en-us/odata/concepts/queryoptions-overview#filter) into the **Group Membership Filter** field. For example, if you want to limit logging to group memberships whose name starts with `test`, click the checkbox and enter `startswith(displayName,'test')`. + +![Adding a group membership filter to Azure AD](/img/auth-setup-azure-ad-filter.png) + +## Deprecated Azure AD Graph API + +>**Important:** +> +>- The [Azure AD Graph API](https://docs.microsoft.com/en-us/graph/migrate-azure-ad-graph-overview) is deprecated and will be retired by Microsoft at any time after June 30, 2023, without advance notice. We will update our docs to advise the community when it is retired. Rancher now uses the [Microsoft Graph API](https://docs.microsoft.com/en-us/graph/use-the-api) as the new flow to set up Azure AD as the external auth provider. +> +> +>- If you're a new user, or wish to migrate, refer to the new flow instructions for Rancher v2.7.0+. +> +> +>- 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. diff --git a/versioned_docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/authentication-config/configure-freeipa.md b/versioned_docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/authentication-config/configure-freeipa.md new file mode 100644 index 00000000000..1b1526bca7d --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/authentication-config/configure-freeipa.md @@ -0,0 +1,64 @@ +--- +title: Configure FreeIPA +--- + + + + + +If your organization uses FreeIPA for user authentication, you can configure Rancher to allow your users to login using their FreeIPA credentials. + +:::note Prerequisites: + +- You must have a [FreeIPA Server](https://www.freeipa.org/) configured. +- Create a service account in FreeIPA with `read-only` access. Rancher uses this account to verify group membership when a user makes a request using an API key. +- Read [External Authentication Configuration and Principal Users](authentication-config.md#external-authentication-configuration-and-principal-users). + +::: + +1. Sign into Rancher using a local user assigned the `administrator` role (i.e., the _local principal_). +1. In the top left corner, click **☰ > Users & Authentication**. +1. In the left navigation menu, click **Auth Provider**. +1. Click **FreeIPA**. +1. Complete the **Configure an FreeIPA server** form. + + You may need to log in to your domain controller to find the information requested in the form. + + :::note Using TLS? + + If the certificate is self-signed or not from a recognized certificate authority, make sure you provide the complete chain. That chain is needed to verify the server's certificate. + + ::: + + :::note User Search Base vs. Group Search Base + + Search base allows Rancher to search for users and groups that are in your FreeIPA. These fields are only for search bases and not for search filters. + + * If your users and groups are in the same search base, complete only the User Search Base. + * If your groups are in a different search base, you can optionally complete the Group Search Base. This field is dedicated to searching groups, but is not required. + + ::: + +1. If your FreeIPA deviates from the standard AD schema, complete the **Customize Schema** form to match it. Otherwise, skip this step. + + :::note Search Attribute + + The Search Attribute field defaults with three specific values: `uid|sn|givenName`. After FreeIPA is configured, when a user enters text to add users or groups, Rancher automatically queries the FreeIPA server and attempts to match fields by user id, last name, or first name. Rancher specifically searches for users/groups that begin with the text entered in the search field. + + The default field value `uid|sn|givenName`, but you can configure this field to a subset of these fields. The pipe (`|`) between the fields separates these fields. + + * `uid`: User ID + * `sn`: Last Name + * `givenName`: First Name + + With this search attribute, Rancher creates search filters for users and groups, but you *cannot* add your own search filters in this field. + + ::: + +1. Enter your FreeIPA username and password in **Authenticate with FreeIPA** to confirm that Rancher is configured to use FreeIPA authentication. +1. Click **Enable**. + +**Result:** + +- FreeIPA authentication is configured. +- You are signed into Rancher with your FreeIPA account (i.e., the _external principal_). diff --git a/versioned_docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/authentication-config/configure-generic-oidc.md b/versioned_docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/authentication-config/configure-generic-oidc.md new file mode 100644 index 00000000000..4b9685729d0 --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/authentication-config/configure-generic-oidc.md @@ -0,0 +1,162 @@ +--- +title: Configure Generic OIDC +description: Create an OpenID Connect (OIDC) client and configure Rancher to work with your authentication provider. Your users can then sign into Rancher using their login from the authentication provider. +--- + + + + + +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 + +### Identity Provider + +In Rancher, Generic OIDC is disabled. + +:::note + +Consult the documentation for your specific IdP to complete the listed prerequisites. + +::: + +#### OIDC Client + +In your IdP, create a new client with the settings below: + + Setting | Value + ------------|------------ + `Client ID` | (e.g. `rancher`) + `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. + +:::note + +The `groups` and `full_group_path` claims generated by the Groups and Group Path mappers, which you create within the OIDC client in your Identity Provider, should be JSON arrays, e.g. `"groups":["admins","devs","qa"]` and `"full_group_path":["/admins","/devs","/qa"]`. + +::: + + 1. Create a new `Groups Mapper` 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` + + 1. Create a new `Client Audience` with the settings below: + + Setting | Value + ------------|------------ + `Name` | `Client Audience` + `Mapper Type` | `Audience` + `Included Client Audience` | `CLIENT_NAME` + `Add to access token` | `ON` + + 1. Create a new `Groups Path` with the settings below. + + Setting | Value + ------------|------------ + `Name` | `Group Path` + `Mapper Type` | `Group Membership` + `Token Claim Name` | `full_group_path` + `Full group path` | `ON` + `Add to user info` | `ON` + +:::warning + +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. + +::: + +## Configuring Generic OIDC in Rancher + +1. In the upper left corner of the Rancher UI, click **☰ > Users & Authentication**. +1. In the left navigation bar, click **Auth Provider**. +1. Select **Generic OIDC**. +1. Complete the **Configure an OIDC account** form. For help with filling the form, see the [configuration reference](#configuration-reference). +1. Click **Enable**. + + Rancher will redirect you to the IdP login page. Enter your IdP credentials to validate your Rancher Keycloak configuration. + + :::note + + You may need to disable your popup blocker to see the IdP login page. + + ::: + +**Result:** Rancher is configured to work with your provider using the OIDC protocol. Your users can now sign into Rancher using their IdP logins. + +### 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 | +| ------------------------- |----------------------------------------------------------------------------------------------------------------------------------------------------| +| Client ID | The Client ID of your OIDC client. | +| Client Secret | The generated Secret of your OIDC client. | +| Private Key/Certificate | A key/certificate pair to create a secure shell between Rancher and your IdP. Required if HTTPS/SSL is enabled on your OIDC server. | +| Endpoints | Choose whether to use the generated values for the Rancher URL, Issue, and Auth Endpoint fields or to provide manual overrides if incorrect. | +| 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. + +All Generic OIDC related log entries are prepended with either `[generic oidc]` or `[oidc]`. + +### You are not redirected to your authentication provider + +If you fill out the **Configure a Generic OIDC account** form and click on **Enable**, and you are not redirected to your IdP, verify your OIDC client configuration. + +### The generated `Issuer` and `Auth Endpoint` are incorrect + +If the `Issuer` and `Auth Endpoint` are generated incorrectly, open the **Configure an OIDC account** form, change **Endpoints** to `Specify (advanced)` and override the `Issuer` value. + +### 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) + + diff --git a/versioned_docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/authentication-config/configure-github-app.md b/versioned_docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/authentication-config/configure-github-app.md new file mode 100644 index 00000000000..5734108f396 --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/authentication-config/configure-github-app.md @@ -0,0 +1,84 @@ +--- +title: Configure GitHub App +--- + + + + + +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. diff --git a/versioned_docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/authentication-config/configure-github.md b/versioned_docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/authentication-config/configure-github.md new file mode 100644 index 00000000000..c36d087ab5d --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/authentication-config/configure-github.md @@ -0,0 +1,60 @@ +--- +title: Configure GitHub +--- + + + + + +In environments using GitHub, you can configure Rancher to allow sign on using GitHub credentials. + +:::note Prerequisites: + +Read [External Authentication Configuration and Principal Users](authentication-config.md#external-authentication-configuration-and-principal-users). + +::: + +1. Sign into Rancher using a local user assigned the `administrator` role (i.e., the _local principal_). +1. In the top left corner, click **☰ > Users & Authentication**. +1. In the left navigation menu, click **Auth Provider**. +1. Click **GitHub**. +1. Follow the directions displayed to set up a GitHub Application. Rancher redirects you to GitHub to complete registration. + + :::note What's an Authorization Callback URL? + + The Authorization Callback URL is the URL where users go to begin using your application (i.e. the splash screen). + + When you use external authentication, authentication does not actually take place in your application. Instead, authentication takes place externally (in this case, GitHub). After this external authentication completes successfully, the Authorization Callback URL is the location where the user re-enters your application. + + ::: + +1. From GitHub, copy the **Client ID** and **Client Secret**. Paste them into Rancher. + + :::note Where do I find the Client ID and Client Secret? + + From GitHub, select Settings > Developer Settings > OAuth Apps. The Client ID and Client Secret are displayed prominently. + + ::: + +1. Click **Authenticate with GitHub**. + +1. Use the **Site Access** options to configure the scope of user authorization. + + - **Allow any valid Users** + + _Any_ GitHub user can access Rancher. We generally discourage use of this setting! + + - **Allow members of Clusters, Projects, plus Authorized Users and Organizations** + + Any GitHub user or group added as a **Cluster Member** or **Project Member** can log in to Rancher. Additionally, any GitHub user or group you add to the **Authorized Users and Organizations** list may log in to Rancher. + + - **Restrict access to only Authorized Users and Organizations** + + Only GitHub users or groups added to the Authorized Users and Organizations can log in to Rancher. +
+1. Click **Enable**. + +**Result:** + +- GitHub authentication is configured. +- You are signed into Rancher with your GitHub account (i.e., the _external principal_). diff --git a/versioned_docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/authentication-config/configure-google-oauth.md b/versioned_docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/authentication-config/configure-google-oauth.md new file mode 100644 index 00000000000..23b5084b594 --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/authentication-config/configure-google-oauth.md @@ -0,0 +1,115 @@ +--- +title: Configure Google OAuth +--- + + + + + +If your organization uses G Suite for user authentication, you can configure Rancher to allow your users to log in using their G Suite credentials. + +Only admins of the G Suite domain have access to the Admin SDK. Therefore, only G Suite admins can configure Google OAuth for Rancher. + +Within Rancher, only administrators or users with the **Manage Authentication** [global role](../../authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/global-permissions.md) can configure authentication. + +## Prerequisites + +- You must have a [G Suite admin account](https://admin.google.com) configured. +- G Suite requires a [top private domain FQDN](https://github.com/google/guava/wiki/InternetDomainNameExplained#public-suffixes-and-private-domains) as an authorized domain. One way to get an FQDN is by creating an A-record in Route53 for your Rancher server. You do not need to update your Rancher Server URL setting with that record, because there could be clusters using that URL. +- You must have the Admin SDK API enabled for your G Suite domain. You can enable it using the steps on [this page.](https://support.google.com/a/answer/60757?hl=en) + +After the Admin SDK API is enabled, your G Suite domain's API screen should look like this: +![Enable Admin APIs](/img/Google-Enable-APIs-Screen.png) + +## Setting up G Suite for OAuth with Rancher + +Before you can set up Google OAuth in Rancher, you need to log in to your G Suite account and do the following: + +1. [Add Rancher as an authorized domain in G Suite](#1-adding-rancher-as-an-authorized-domain) +1. [Generate OAuth2 credentials for the Rancher server](#2-creating-oauth2-credentials-for-the-rancher-server) +1. [Create service account credentials for the Rancher server](#3-creating-service-account-credentials) +1. [Register the service account key as an OAuth Client](#4-register-the-service-account-key-as-an-oauth-client) + +### 1. Adding Rancher as an Authorized Domain + +1. Click [here](https://console.developers.google.com/apis/credentials) to go to credentials page of your Google domain. +1. Select your project and click **OAuth consent screen**. +![OAuth Consent Screen](/img/Google-OAuth-consent-screen-tab.png) +1. Go to **Authorized Domains** and enter the top private domain of your Rancher server URL in the list. The top private domain is the rightmost superdomain. So for example, www.foo.co.uk a top private domain of foo.co.uk. For more information on top-level domains, refer to [this article.](https://github.com/google/guava/wiki/InternetDomainNameExplained#public-suffixes-and-private-domains) +1. Go to **Scopes for Google APIs** and make sure **email,** **profile** and **openid** are enabled. + +**Result:** Rancher has been added as an authorized domain for the Admin SDK API. + +### 2. Creating OAuth2 Credentials for the Rancher Server + +1. Go to the Google API console, select your project, and go to the [credentials page.](https://console.developers.google.com/apis/credentials) +![Credentials](/img/Google-Credentials-tab.png) +1. On the **Create Credentials** dropdown, select **OAuth client ID**. +1. Click **Web application**. +1. Provide a name. +1. Fill out the **Authorized JavaScript origins** and **Authorized redirect URIs**. Note: The Rancher UI page for setting up Google OAuth (available from the Global view under **Security > Authentication > Google**) provides you the exact links to enter for this step. + - Under **Authorized JavaScript origins,** enter your Rancher server URL. + - Under **Authorized redirect URIs,** enter your Rancher server URL appended with the path `verify-auth`. For example, if your URI is `https://rancherServer`, you will enter `https://rancherServer/verify-auth`. +1. Click on **Create**. +1. After the credential is created, you will see a screen with a list of your credentials. Choose the credential you just created, and in that row on rightmost side, click **Download JSON**. Save the file so that you can provide these credentials to Rancher. + +**Result:** Your OAuth credentials have been successfully created. + +### 3. Creating Service Account Credentials +Since the Google Admin SDK is available only to admins, regular users cannot use it to retrieve profiles of other users or their groups. Regular users cannot even retrieve their own groups. + +Since Rancher provides group-based membership access, we require the users to be able to get their own groups, and look up other users and groups when needed. + +As a workaround to get this capability, G Suite recommends creating a service account and delegating authority of your G Suite domain to that service account. + +This section describes how to: + +- Create a service account +- Create a key for the service account and download the credentials as JSON + +1. Click [here](https://console.developers.google.com/iam-admin/serviceaccounts) and select your project for which you generated OAuth credentials. +1. Click on **Create Service Account**. +1. Enter a name and click **Create**. +![Service account creation Step 1](/img/Google-svc-acc-step1.png) +1. Don't provide any roles on the **Service account permissions** page and click **Continue** +![Service account creation Step 2](/img/Google-svc-acc-step2.png) +1. Click on **Create Key** and select the JSON option. Download the JSON file and save it so that you can provide it as the service account credentials to Rancher. +![Service account creation Step 3](/img/Google-svc-acc-step3-key-creation.png) + +**Result:** Your service account is created. + +### 4. Register the Service Account Key as an OAuth Client + +You will need to grant some permissions to the service account you created in the last step. Rancher requires you to grant only read-only permissions for users and groups. + +Using the Unique ID of the service account key, register it as an Oauth Client using the following steps: + +1. Get the Unique ID of the key you just created. If it's not displayed in the list of keys right next to the one you created, you will have to enable it. To enable it, click **Unique ID** and click **OK**. This will add a **Unique ID** column to the list of service account keys. Save the one listed for the service account you created. NOTE: This is a numeric key, not to be confused with the alphanumeric field **Key ID**. + + ![Service account Unique ID](/img/Google-Select-UniqueID-column.png) +1. Go to the [**Domain-wide Delegation** page.](https://admin.google.com/ac/owl/domainwidedelegation) +1. Add the Unique ID obtained in the previous step in the **Client Name** field. +1. In the **One or More API Scopes** field, add the following scopes: + ``` + openid,profile,email,https://www.googleapis.com/auth/admin.directory.user.readonly,https://www.googleapis.com/auth/admin.directory.group.readonly + ``` +1. Click **Authorize**. + +**Result:** The service account is registered as an OAuth client in your G Suite account. + +## Configuring Google OAuth in Rancher + +1. Sign into Rancher using a local user assigned the [administrator](../../authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/global-permissions.md) role. This user is also called the local principal. +1. In the top left corner, click **☰ > Users & Authentication**. +1. In the left navigation menu, click **Auth Provider**. +1. Click **Google**. The instructions in the UI cover the steps to set up authentication with Google OAuth. + 1. Admin Email: Provide the email of an administrator account from your GSuite setup. In order to perform user and group lookups, google apis require an administrator's email in conjunction with the service account key. + 1. Domain: Provide the domain on which you have configured GSuite. Provide the exact domain and not any aliases. + 1. Nested Group Membership: Check this box to enable nested group memberships. Rancher admins can disable this at any time after configuring auth. + - **Step One** is about adding Rancher as an authorized domain, which we already covered in [this section.](#1-adding-rancher-as-an-authorized-domain) + - For **Step Two,** provide the OAuth credentials JSON that you downloaded after completing [this section.](#2-creating-oauth2-credentials-for-the-rancher-server) You can upload the file or paste the contents into the **OAuth Credentials** field. + - For **Step Three,** provide the service account credentials JSON that downloaded at the end of [this section.](#3-creating-service-account-credentials) The credentials will only work if you successfully [registered the service account key](#4-register-the-service-account-key-as-an-oauth-client) as an OAuth client in your G Suite account. +1. Click **Authenticate with Google**. +1. Click **Enable**. + +**Result:** Google authentication is successfully configured. diff --git a/versioned_docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/authentication-config/configure-keycloak-oidc.md b/versioned_docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/authentication-config/configure-keycloak-oidc.md new file mode 100644 index 00000000000..646bf3ee8b6 --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/authentication-config/configure-keycloak-oidc.md @@ -0,0 +1,209 @@ +--- +title: Configure Keycloak (OIDC) +description: Create a Keycloak OpenID Connect (OIDC) client and configure Rancher to work with Keycloak. By the end your users will be able to sign into Rancher using their Keycloak logins +--- + + + + + +If your organization uses [Keycloak Identity Provider (IdP)](https://www.keycloak.org) for user authentication, you can configure Rancher to allow your users to log in using their IdP credentials. Rancher supports integration with Keycloak using the OpenID Connect (OIDC) protocol and the SAML protocol. Both implementations are functionally equivalent when used with Rancher. This page describes the process to configure Rancher to work with Keycloak using the OIDC protocol. + +If you prefer to use Keycloak with the SAML protocol instead, refer to [this page](configure-keycloak-saml.md). + +If you have an existing configuration using the SAML protocol and want to switch to the OIDC protocol, refer to [this section](#migrating-from-saml-to-oidc). + +## Prerequisites + +- On Rancher, Keycloak (SAML) is disabled. +- You must have a [Keycloak IdP Server](https://www.keycloak.org/guides#getting-started) configured. +- Follow the [Keycloak documentation](https://www.keycloak.org/docs/latest/server_admin/#proc-creating-oidc-client_server_administration_guide) to create a new OIDC client with the settings below. + + | Setting | Value | + | ------------|------------| + | `Client ID` | <client-id> (e.g. `rancher`) | + | `Name` | <client-name> (e.g. `rancher`) | + | `Client type` | `OpenID Connect` | + | `Client authentication` | `ON` | + | `Valid Redirect URI` | `https://yourRancherHostURL/verify-auth` | + +- In the new OIDC client, create [Mappers](https://www.keycloak.org/docs/latest/server_admin/#_protocol-mappers) to expose the users fields. + 1. In the navigation menu, click **Clients**. + 1. Click the **Clients list** tab. + 1. Find and click the client you created. + 1. Click the **Client scopes** tab. + 1. Find and click the link labeled `-dedicated`. For example, if you named your client `rancher`, look for the link named `rancher-dedicated`. + 1. Click the **Mappers** tab. + 1. Click **Configure a new mapper**. If you already have existing mappers configured, click the arrow next to **Add mapper** and select **By configuration**. Repeat this process and create these mappers: + - From the mappings table, select **Group Membership** and configure a new "Groups Mapper" with the settings below. For settings that are not mentioned, use the default value. + + | Setting | Value | + | ------------|------------| + | `Name` | `Groups Mapper` | + | `Mapper Type` | `Group Membership` | + | `Token Claim Name` | `groups` | + | `Full group path` | `OFF` | + | `Add to ID token` | `OFF` | + | `Add to access token` | `OFF` | + | `Add to user info` | `ON` | + + - From the mappings table, select **Audience** and configure a new "Client Audience" with the settings below. For settings that are not mentioned, use the default value. + + | Setting | Value | + | ------------|------------| + | `Name` | `Client Audience` | + | `Mapper Type` | `Audience` | + | `Included Client Audience` | <client-name> | + | `Add to ID token` | `OFF` | + | `Add to access token` | `ON` | + + - From the mappings table, select **Group Membership** and configure a new "Groups Path" with the settings below. For settings that are not mentioned, use the default value. + + | Setting | Value | + | ------------|------------| + | `Name` | `Group Path` | + | `Mapper Type` | `Group Membership` | + | `Token Claim Name` | `full_group_path` | + | `Full group path` | `ON` | + | `Add to ID token` | `ON` | + | `Add to access token` | `ON` | + | `Add to user info` | `ON` | + +- Add the following role mappings to all users or groups that need to query the Keycloak users. + + + + +1. In the navigation menu, click **Users**. +1. Click the user you want to add role mappings to. +1. Click the **Role mapping** tab. +1. Click **Assign role**. +1. Select the following roles: + - query-users + - query-groups + - view-users +1. Click **Assign**. + + + + +1. In the navigation menu, click **Groups**. +1. Click the group you want to add role mappings to. +1. Click the **Role mapping** tab. +1. Click **Assign role**. +1. Select the following roles: + - query-users + - query-groups + - view-users +1. Click **Assign**. + + + + +## Configuring Keycloak in Rancher + +1. In the Rancher UI, click **☰ > Users & Authentication**. +1. In the left navigation bar, click **Auth Provider**. +1. Select **Keycloak (OIDC)**. +1. Complete the **Configure a Keycloak OIDC account** form. For help with filling the form, see the [configuration reference](#configuration-reference). + + :::note + + When configuring the **Endpoints** section using the **Generate** option, Rancher includes `/auth` as part of the context path in the **Issuer** and **Auth Endpoint** fields, which is only valid for Keycloak 16 or older. You must configure endpoints using the **Specify** option for [Keycloak 17](https://www.keycloak.org/docs/latest/release_notes/index.html#keycloak-17-0-0) and newer, which have [migrated to Quarkus](https://www.keycloak.org/migration/migrating-to-quarkus). + + ::: + +1. After you complete the **Configure a Keycloak OIDC account** form, click **Enable**. + + Rancher redirects you to the IdP login page. Enter credentials that authenticate with Keycloak IdP to validate your Rancher Keycloak configuration. + + :::note + + You may need to disable your popup blocker to see the IdP login page. + + ::: + +**Result:** Rancher is configured to work with Keycloak using the OIDC protocol. Your users can now sign in to Rancher using their Keycloak logins. + +:::note SAML Provider Caveats + +- Users and groups aren't validated when you assign permissions to them in Rancher. +- When adding users, the exact user IDs (i.e. `UID Field`) must be entered correctly. As you type the user ID, there will be no search for other user IDs that may match. +- When adding groups, you must select the group from the drop-down that is next to the text box. Rancher assumes that any input from the text box is a user. +- The group drop-down shows only the groups that you are a member of. However, if you have Administrator permissions or Restricted Administrator permissions, you can join a group that you are not a member of. + +::: + +## Configuration Reference + +| Field | Description | +| ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Client ID | The `Client ID` of your Keycloak client. | +| Client Secret | The generated `Secret` of your Keycloak client. In the Keycloak console, select **Clients**, select the client you created, select the **Credentials** tab and copy the value of the `Secret` field. | +| Private Key / Certificate | A key/certificate pair to create a secure shell between Rancher and your IdP. Required if HTTPS/SSL is enabled on your Keycloak server. | +| Endpoints | Choose whether to use the generated values for the `Rancher URL`, `Issue`, and `Auth Endpoint` fields or to provide manual overrides if incorrect. | +| Keycloak URL | The URL for your Keycloak server. | +| Keycloak Realm | The name of the realm in which the Keycloak client was created in. | +| Rancher URL | The URL for your Rancher Server. | +| Issuer | The URL of your IdP. | +| Auth Endpoint | The URL where users are redirected to authenticate. | + +## Migrating from SAML to OIDC + +This section describes the process to transition from using Rancher with Keycloak (SAML) to Keycloak (OIDC). + +1. Reconfigure Keycloak. + 1. Configure a new `OpenID Connect` client according to the [Prerequisites](#prerequisites). Ensure the same `Valid Redirect URIs` are set. + 1. Configure mappers for the new client according to the [Prerequisites](#prerequisites). +1. Before configuring Rancher to use Keycloak (OIDC), Keycloak (SAML) must be first disabled. + 1. In the Rancher UI, click **☰ > Users & Authentication**. + 1. In the left navigation bar, click **Auth Provider**. + 1. Select **Keycloak (SAML)**. + 1. Click **Disable**. +1. Follow the steps in [Configuring Keycloak in Rancher](#configuring-keycloak-in-rancher). + +:::caution + +After configuration is completed, Rancher user permissions need to be reapplied as they are not automatically migrated. + +::: + +## Annex: Troubleshooting + +If you are experiencing issues while testing the connection to the Keycloak server, first double-check the configuration options of your OIDC client. You may 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. + +All Keycloak related log entries are prepended with either `[generic oidc]` or `[keycloak oidc]`. + +### You are not redirected to Keycloak + +When you fill the **Configure a Keycloak OIDC account** form and click **Enable**, you are not redirected to your IdP. + +Verify your Keycloak client configuration. + +### The generated `Issuer` and `Auth Endpoint` are incorrect + +On the **Configure a Keycloak OIDC account** form, change **Endpoints** to `Specify (advanced)` and override the `Issuer` and `Auth Endpoint` values. To find the values, go to the Keycloak console and select **Realm Settings**, select the **General** tab, and click **OpenID Endpoint Configuration**. The JSON output displays values for `issuer` and `authorization_endpoint`. + +### Keycloak Error: "Invalid grant_type" + +In some cases, this error message may be misleading and is caused by setting the `Valid Redirect URI` incorrectly. + +### Unable to See Groups When Assigning Global Roles + +If you use a user that is not part of any groups for initial setup, then you cannot search for groups when trying to assign a global role. +To resolve this, you can either: + +1. Manually edit the `authconfig/keycloakoidc` object to enable group search. + + 1. On the Rancher server: + ```bash + kubectl edit authconfigs.management.cattle.io keycloakoidc + ``` + 2. Set `groupSearchEnabled: true`. + 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) + + \ No newline at end of file diff --git a/versioned_docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/authentication-config/configure-keycloak-saml.md b/versioned_docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/authentication-config/configure-keycloak-saml.md new file mode 100644 index 00000000000..8eaf0a28eb1 --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/authentication-config/configure-keycloak-saml.md @@ -0,0 +1,198 @@ +--- +title: Configure Keycloak (SAML) +description: Create a Keycloak SAML client and configure Rancher to work with Keycloak. By the end your users will be able to sign into Rancher using their Keycloak logins +--- + + + + + +If your organization uses Keycloak Identity Provider (IdP) for user authentication, you can configure Rancher to allow your users to log in using their IdP credentials. + +## Prerequisites + +- You must have a [Keycloak IdP Server](https://www.keycloak.org/guides#getting-started) configured. +- In Keycloak, create a [new SAML client](https://www.keycloak.org/docs/latest/server_admin/#saml-clients), with the settings below. See the [Keycloak documentation](https://www.keycloak.org/docs/latest/server_admin/#saml-clients) for help. + + Setting | Value + ------------|------------ + `Sign Documents` | `ON` 1 + `Sign Assertions` | `ON` 1 + All other `ON/OFF` Settings | `OFF` + `Client ID` | Either `https://yourRancherHostURL/v1-saml/keycloak/saml/metadata` or the value configured in the `Entry ID Field` of the Rancher Keycloak configuration2 + `Client Name` | (e.g. `rancher`) + `Client Protocol` | `SAML` + `Valid Redirect URI` | `https://yourRancherHostURL/v1-saml/keycloak/saml/acs` + + >1: Optionally, you can enable either one or both of these settings. + >2: Rancher SAML metadata won't be generated until a SAML provider is configured and saved. + + ![](/img/keycloak/keycloak-saml-client-configuration.png) + +- In the new SAML client, create Mappers to expose the users fields + - Add all "Builtin Protocol Mappers" + ![](/img/keycloak/keycloak-saml-client-builtin-mappers.png) + - Create a new "Group list" mapper to map the member attribute to a user's groups + ![](/img/keycloak/keycloak-saml-client-group-mapper.png) + +## Getting the IDP Metadata + + + + +To get the IDP metadata, export a `metadata.xml` file from your Keycloak client. +From the **Installation** tab, choose the **SAML Metadata IDPSSODescriptor** format option and download your file. + + + + +1. From the **Configure** section, click the **Realm Settings** tab. +1. Click the **General** tab. +1. From the **Endpoints** field, click **SAML 2.0 Identity Provider Metadata**. + +Verify the IDP metadata contains the following attributes: + +``` +xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" +xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion" +xmlns:ds="http://www.w3.org/2000/09/xmldsig#" +``` + +Some browsers, such as Firefox, may render/process the document such that the contents appear to have been modified, and some attributes appear to be missing. In this situation, use the raw response data that can be found using your browser. + +The following is an example process for Firefox, but will vary slightly for other browsers: + +1. Press **F12** to access the developer console. +1. Click the **Network** tab. +1. From the table, click the row containing `descriptor`. +1. From the details pane, click the **Response** tab. +1. Copy the raw response data. + +The XML obtained contains `EntitiesDescriptor` as the root element. Rancher expects the root element to be `EntityDescriptor` rather than `EntitiesDescriptor`. So before passing this XML to Rancher, follow these steps to adjust it: + +1. Copy all the attributes from `EntitiesDescriptor` to the `EntityDescriptor` that are not present. +1. Remove the `` tag from the beginning. +1. Remove the `` from the end of the xml. + +You are left with something similar as the example below: + +``` + +.... + +``` + + + + +1. From the **Configure** section, click the **Realm Settings** tab. +1. Click the **General** tab. +1. From the **Endpoints** field, click **SAML 2.0 Identity Provider Metadata**. + +Verify the IDP metadata contains the following attributes: + +``` +xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" +xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion" +xmlns:ds="http://www.w3.org/2000/09/xmldsig#" +``` + +Some browsers, such as Firefox, may render/process the document such that the contents appear to have been modified, and some attributes appear to be missing. In this situation, use the raw response data that can be found using your browser. + +The following is an example process for Firefox, but will vary slightly for other browsers: + +1. Press **F12** to access the developer console. +1. Click the **Network** tab. +1. From the table, click the row containing `descriptor`. +1. From the details pane, click the **Response** tab. +1. Copy the raw response data. + + + + +## Configuring Keycloak in Rancher + + +1. In the top left corner, click **☰ > Users & Authentication**. +1. In the left navigation menu, click **Auth Provider**. +1. Click **Keycloak SAML**. +1. Complete the **Configure Keycloak Account** form. For help with filling the form, see the [configuration reference](#configuration-reference). +1. After you complete the **Configure a Keycloak Account** form, click **Enable**. + + Rancher redirects you to the IdP login page. Enter credentials that authenticate with Keycloak IdP to validate your Rancher Keycloak configuration. + + :::note + + You may have to disable your popup blocker to see the IdP login page. + + ::: + +**Result:** Rancher is configured to work with Keycloak. Your users can now sign into Rancher using their Keycloak logins. + +:::note SAML Provider Caveats: + +- SAML Protocol does not support search or lookup for users or groups. Therefore, there is no validation on users or groups when adding them to Rancher. +- When adding users, the exact user IDs (i.e. `UID Field`) must be entered correctly. As you type the user ID, there will be no search for other user IDs that may match. +- When adding groups, you must select the group from the drop-down that is next to the text box. Rancher assumes that any input from the text box is a user. +- The group drop-down shows only the groups that you are a member of. You will not be able to add groups that you are not a member of. + +::: + +## Configuration Reference + +| Field | Description | +| ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Display Name Field | The attribute that contains the display name of users.

Example: `givenName` | +| User Name Field | The attribute that contains the user name/given name.

Example: `email` | +| UID Field | An attribute that is unique to every user.

Example: `email` | +| Groups Field | Make entries for managing group memberships.

Example: `member` | +| Entity ID Field | The ID that needs to be configured as a client ID in the Keycloak client.

Default: `https://yourRancherHostURL/v1-saml/keycloak/saml/metadata` | +| Rancher API Host | The URL for your Rancher Server. | +| Private Key / Certificate | A key/certificate pair to create a secure shell between Rancher and your IdP. | +| IDP-metadata | The `metadata.xml` file that you exported from your IdP server. | + +:::tip + +You can generate a key/certificate pair using an openssl command. For example: + +openssl req -x509 -sha256 -nodes -days 365 -newkey rsa:2048 -keyout myservice.key -out myservice.cert + +::: + +## Annex: Troubleshooting + +If you are experiencing issues while testing the connection to the Keycloak server, first double-check the configuration option of your SAML client. You may also inspect the Rancher logs to help pinpointing the problem cause. Debug logs may contain more detailed information about the error. Please refer to [How can I enable debug logging](../../../../faq/technical-items.md#how-can-i-enable-debug-logging) in this documentation. + +### You are not redirected to Keycloak + +When you click on **Authenticate with Keycloak**, you are not redirected to your IdP. + + * Verify your Keycloak client configuration. + * Make sure `Force Post Binding` is set to `OFF`. + + +### Forbidden message displayed after IdP login + +You are correctly redirected to your IdP login page and you are able to enter your credentials, however you get a `Forbidden` message afterwards. + + * Check the Rancher debug log. + * If the log displays `ERROR: either the Response or Assertion must be signed`, make sure either `Sign Documents` or `Sign assertions` is set to `ON` in your Keycloak client. + +### HTTP 502 when trying to access /v1-saml/keycloak/saml/metadata + +This is usually due to the metadata not being created until a SAML provider is configured. +Try configuring and saving keycloak as your SAML provider and then accessing the metadata. + +### Keycloak Error: "We're sorry, failed to process response" + + * Check your Keycloak log. + * If the log displays `failed: org.keycloak.common.VerificationException: Client does not have a public key`, set `Encrypt Assertions` to `OFF` in your Keycloak client. + +### Keycloak Error: "We're sorry, invalid requester" + + * Check your Keycloak log. + * If the log displays `request validation failed: org.keycloak.common.VerificationException: SigAlg was null`, set `Client Signature Required` to `OFF` in your Keycloak client. + +## Configuring SAML Single Logout (SLO) + + diff --git a/versioned_docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/authentication-config/configure-okta-saml.md b/versioned_docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/authentication-config/configure-okta-saml.md new file mode 100644 index 00000000000..b16d92780dc --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/authentication-config/configure-okta-saml.md @@ -0,0 +1,114 @@ +--- +title: Configure Okta (SAML) +--- + + + + + +If your organization uses Okta Identity Provider (IdP) for user authentication, you can configure Rancher to allow your users to log in using their IdP credentials. + +:::note + +Okta integration only supports Service Provider initiated logins. + +::: +## Prerequisites + +In Okta, create a SAML Application with the settings below. See the [Okta documentation](https://developer.okta.com/standards/SAML/setting_up_a_saml_application_in_okta) for help. + +Setting | Value +------------|------------ +`Single Sign on URL` | `https://yourRancherHostURL/v1-saml/okta/saml/acs` +`Audience URI (SP Entity ID)` | `https://yourRancherHostURL/v1-saml/okta/saml/metadata` + +## Configuring Okta in Rancher + +You can integrate Okta with Rancher, so that authenticated users can access Rancher resources through their group permissions. Okta returns a SAML assertion that authenticates a user, including which groups a user belongs to. + +1. In the top left corner, click **☰ > Users & Authentication**. +1. In the left navigation menu, click **Auth Provider**. +1. Click **Okta**. +1. Complete the **Configure Okta Account** form. The examples below describe how you can map Okta attributes from attribute statements to fields within Rancher. + + | Field | Description | + | ------------------------- | ----------------------------------------------------------------------------- | + | Display Name Field | The attribute name from an attribute statement that contains the display name of users. | + | User Name Field | The attribute name from an attribute statement that contains the user name/given name. | + | UID Field | The attribute name from an attribute statement that is unique to every user. | + | Groups Field | The attribute name in a group attribute statement that exposes your groups. | + | Rancher API Host | The URL for your Rancher Server. | + | Private Key / Certificate | A key/certificate pair used for Assertion Encryption. | + | Metadata XML | The `Identity Provider metadata` file that you find in the application `Sign On` section. | + + :::tip + + You can generate a key/certificate pair using an openssl command. For example: + + ``` + openssl req -x509 -sha256 -nodes -days 365 -newkey rsa:2048 -keyout myservice.key -out myservice.crt + ``` + + ::: + +1. After you complete the **Configure Okta Account** form, click **Enable**. + + Rancher redirects you to the IdP login page. Enter credentials that authenticate with Okta IdP to validate your Rancher Okta configuration. + + :::note + + If nothing seems to happen, it's likely because your browser blocked the pop-up. Make sure you disable the pop-up blocker for your rancher domain and whitelist it in any other extensions you might utilize. + + ::: + +**Result:** Rancher is configured to work with Okta. Your users can now sign into Rancher using their Okta logins. + +:::note SAML Provider Caveats + +If you configure Okta without OpenLDAP, you won't be able to search for or directly lookup users or groups. This brings several caveats: + +- Users and groups aren't validated when you assign permissions to them in Rancher. +- When adding users, the exact user IDs (i.e. `UID Field`) must be entered correctly. As you type the user ID, there will be no search for other user IDs that may match. +- When adding groups, you must select the group from the drop-down that is next to the text box. Rancher assumes that any input from the text box is a user. +- The group drop-down shows only the groups that you are a member of. However, if you have Administrator permissions or restricted Administrator permissions, you can join a group that you are not a member of. + +::: + +## Okta with OpenLDAP search + +You can add an OpenLDAP backend to assist with user and group search. Rancher will display additional users and groups from the OpenLDAP service. This allows assigning permissions to groups that the logged-in user is not already a member of. + +### OpenLDAP Prerequisites + +If you use Okta as your IdP, you can [set up an LDAP interface](https://help.okta.com/en-us/Content/Topics/Directory/LDAP-interface-main.htm) for Rancher to use. You can also configure an external OpenLDAP server. + +You must configure Rancher with a LDAP bind account (aka service account) so that you can search and retrieve LDAP entries for users and groups that should have access. Don't use an administrator account or personal account as an LDAP bind account. [Create](https://help.okta.com/en-us/Content/Topics/users-groups-profiles/usgp-add-users.htm) a dedicated account in OpenLDAP, with read-only access to users and groups under the configured searchbase. + +:::warning Security Considerations + +The OpenLDAP service account is used for all searches. Rancher users will see users and groups that the OpenLDAP service account can view, regardless of their individual SAML permissions. + +::: + + +> **Using TLS?** +> +> If the certificate used by the OpenLDAP server is self-signed or from an unrecognized certificate authority, Rancher needs the CA certificate (concatenated with any intermediate certificates) in PEM format. Provide this certificate during the configuration so that Rancher can validate the certificate chain. + +### Configure OpenLDAP in Rancher + +[Configure the settings](../configure-openldap/openldap-config-reference.md) for the OpenLDAP server, groups and users. Note that nested group membership isn't available. + +> Before you proceed with the configuration, please familiarise yourself with [external authentication configuration and principal users](authentication-config.md#external-authentication-configuration-and-principal-users). + +1. Sign into Rancher using a local user assigned the [administrator](https://ranchermanager.docs.rancher.com/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/global-permissions) role (i.e., the _local principal_). +1. In the top left corner, click **☰ > Users & Authentication**. +1. In the left navigation menu, click **Auth Provider**. +1. Click **Okta** or, if SAML is already configured, **Edit Config** +1. Under **User and Group Search**, check **Configure an OpenLDAP server** + +If you experience issues when you test the connection to the OpenLDAP server, ensure that you entered the credentials for the service account and configured the search base correctly. Inspecting the Rancher logs can help pinpoint the root cause. Debug logs may contain more detailed information about the error. Please refer to [How can I enable debug logging](../../../../faq/technical-items.md#how-can-i-enable-debug-logging) for more information. + +## Configuring SAML Single Logout (SLO) + + diff --git a/versioned_docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/authentication-config/configure-pingidentity.md b/versioned_docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/authentication-config/configure-pingidentity.md new file mode 100644 index 00000000000..fb778648405 --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/authentication-config/configure-pingidentity.md @@ -0,0 +1,70 @@ +--- +title: Configure PingIdentity (SAML) +--- + + + + + +If your organization uses Ping Identity Provider (IdP) for user authentication, you can configure Rancher to allow your users to log in using their IdP credentials. + +>**Prerequisites:** +> +>- You must have a [Ping IdP Server](https://www.pingidentity.com/) configured. +>- Following are the Rancher Service Provider URLs needed for configuration: +Metadata URL: `https:///v1-saml/ping/saml/metadata` +Assertion Consumer Service (ACS) URL: `https:///v1-saml/ping/saml/acs` +Note that these URLs will not return valid data until the authentication configuration is saved in Rancher. +>- Export a `metadata.xml` file from your IdP Server. For more information, see the [PingIdentity documentation](https://documentation.pingidentity.com/pingfederate/pf83/index.shtml#concept_exportingMetadata.html). + +1. In the top left corner, click **☰ > Users & Authentication**. +1. In the left navigation menu, click **Auth Provider**. +1. Click **Ping Identity**. +1. Complete the **Configure a Ping Account** form. Ping IdP lets you specify what data store you want to use. You can either add a database or use an existing ldap server. For example, if you select your Active Directory (AD) server, the examples below describe how you can map AD attributes to fields within Rancher. + + 1. **Display Name Field**: Enter the AD attribute that contains the display name of users (example: `displayName`). + + 1. **User Name Field**: Enter the AD attribute that contains the user name/given name (example: `givenName`). + + 1. **UID Field**: Enter an AD attribute that is unique to every user (example: `sAMAccountName`, `distinguishedName`). + + 1. **Groups Field**: Make entries for managing group memberships (example: `memberOf`). + + 1. **Entity ID Field** (optional): The published, protocol-dependent, unique identifier of your partner. This ID defines your organization as the entity operating the server for SAML 2.0 transactions. This ID may have been obtained out-of-band or via a SAML metadata file. + + 1. **Rancher API Host**: Enter the URL for your Rancher Server. + + 1. **Private Key** and **Certificate**: This is a key-certificate pair to create a secure shell between Rancher and your IdP. + + You can generate one using an openssl command. For example: + + ``` + openssl req -x509 -newkey rsa:2048 -keyout myservice.key -out myservice.cert -days 365 -nodes -subj "/CN=myservice.example.com" + ``` + 1. **IDP-metadata**: The `metadata.xml` file that you [exported from your IdP server](https://documentation.pingidentity.com/pingfederate/pf83/index.shtml#concept_exportingMetadata.html). + + +1. After you complete the **Configure Ping Account** form, click **Enable**. + + Rancher redirects you to the IdP login page. Enter credentials that authenticate with Ping IdP to validate your Rancher PingIdentity configuration. + + :::note + + You may have to disable your popup blocker to see the IdP login page. + + ::: + +**Result:** Rancher is configured to work with PingIdentity. Your users can now sign into Rancher using their PingIdentity logins. + +:::note SAML Provider Caveats + +- Users and groups aren't validated when you assign permissions to them in Rancher. +- When adding users, the exact user IDs (i.e. `UID Field`) must be entered correctly. As you type the user ID, there will be no search for other user IDs that may match. +- When adding groups, you must select the group from the drop-down that is next to the text box. Rancher assumes that any input from the text box is a user. +- The group drop-down shows only the groups that you are a member of. However, if you have Administrator permissions or restricted Administrator permissions, you can join a group that you are not a member of. + +::: + +## Configuring SAML Single Logout (SLO) + + diff --git a/versioned_docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/authentication-config/create-local-users.md b/versioned_docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/authentication-config/create-local-users.md new file mode 100644 index 00000000000..801ed84068b --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/authentication-config/create-local-users.md @@ -0,0 +1,19 @@ +--- +title: Local Authentication +--- + + + + + +Local authentication is the default until you configure an external authentication provider. Rancher stores user account information, such as usernames and passwords, locally. By default, the `admin` user that logs in to Rancher for the first time is a local user. + +## Adding Local Users + +Regardless of whether you use external authentication, you should create a few local authentication users so that you can continue using Rancher if your external authentication service encounters issues. + +1. In the top left corner, click **☰ > Users & Authentication**. +1. In the left navigation menu, click **Users**. +1. Click **Create**. +1. Complete the **Add User** form. +1. Click **Create**. diff --git a/versioned_docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/authentication-config/manage-users-and-groups.md b/versioned_docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/authentication-config/manage-users-and-groups.md new file mode 100644 index 00000000000..3050e3ee2c4 --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/authentication-config/manage-users-and-groups.md @@ -0,0 +1,89 @@ +--- +title: Users and Groups +--- + + + + + +Rancher relies on users and groups to determine who is allowed to log in to Rancher and which resources they can access. When you configure an external authentication provider, users from that provider will be able to log in to your Rancher server. When a user logs in, the authentication provider will supply your Rancher server with a list of groups to which the user belongs. + +Access to clusters, projects, and global DNS providers and entries can be controlled by adding either individual users or groups to these resources. When you add a group to a resource, all users who are members of that group in the authentication provider, will be able to access the resource with the permissions that you've specified for the group. For more information on roles and permissions, see [Role Based Access Control](../manage-role-based-access-control-rbac/manage-role-based-access-control-rbac.md). + +## Managing Members + +When adding a user or group to a resource, you can search for users or groups by beginning to type their name. The Rancher server will query the authentication provider to find users and groups that match what you've entered. Searching is limited to the authentication provider that you are currently logged in with. For example, if you've enabled GitHub authentication but are logged in using a [local](create-local-users.md) user account, you will not be able to search for GitHub users or groups. + +All users, whether they are local users or from an authentication provider, can be viewed and managed. In the upper left corner, click **☰ > Users & Authentication**. In the left navigation bar, click **Users**. + +:::note SAML Provider Caveats + +- Users and groups aren't validated when you assign permissions to them in Rancher. +- When adding users, the exact user IDs (i.e. `UID Field`) must be entered correctly. As you type the user ID, there will be no search for other user IDs that may match. +- When adding groups, you must select the group from the drop-down that is next to the text box. Rancher assumes that any input from the text box is a user. +- The group drop-down shows only the groups that you are a member of. However, if you have Administrator permissions or restricted Administrator permissions, you can join a group that you are not a member of. + +::: + +## User Information + +Rancher maintains information about each user that logs in through an authentication provider. This information includes whether the user is allowed to access your Rancher server and the list of groups that the user belongs to. Rancher keeps this user information so that the CLI, API, and kubectl can accurately reflect the access that the user has based on their group membership in the authentication provider. + +Whenever a user logs in to the UI using an authentication provider, Rancher automatically updates this user information. + +### Automatically Refreshing User Information + +Rancher will periodically refresh the user information even before a user logs in through the UI. You can control how often Rancher performs this refresh. + +Two settings control this behavior: + +- **`auth-user-info-max-age-seconds`** + + This setting controls how old a user's information can be before Rancher refreshes it. If a user makes an API call (either directly or by using the Rancher CLI or kubectl) and the time since the user's last refresh is greater than this setting, then Rancher will trigger a refresh. This setting defaults to `3600` seconds, i.e. 1 hour. + +- **`auth-user-info-resync-cron`** + + This setting controls a recurring schedule for resyncing authentication provider information for all users. Regardless of whether a user has logged in or used the API recently, this will cause the user to be refreshed at the specified interval. This setting defaults to `0 0 * * *`, i.e. once a day at midnight. See the [Cron documentation](https://en.wikipedia.org/wiki/Cron) for more information on valid values for this setting. + +To change these settings, + +1. In the upper left corner, click **☰ > Global Settings**. +1. Go to the setting you want to configure and click **⋮ > Edit Setting**. + +:::note + +Since SAML does not support user lookup, SAML-based authentication providers do not support periodically refreshing user information. User information will only be refreshed when the user logs into the Rancher UI. + +::: +### Manually Refreshing User Information + +If you are not sure the last time Rancher performed an automatic refresh of user information, you can perform a manual refresh of all users. + +1. In the upper left corner, click **☰ > Users & Authentication**. +1. On the **Users** page, click on **Refresh Group Memberships**. + +**Results:** Rancher refreshes the user information for all users. Requesting this refresh will update which users can access Rancher as well as all the groups that each user belongs to. + +:::note + +Since SAML does not support user lookup, SAML-based authentication providers do not support the ability to manually refresh user information. User information will only be refreshed when the user logs into the Rancher UI. + +::: + +## Minimum Password Length + +By default, user passwords must be at least 12 characters long. However, you can customize the password length requirement: + +1. In the upper left corner, click **☰ > Global Settings**. +1. Go to **`password-min-length`** and click **⋮ > Edit Setting**. +1. Enter an integer value between 2 and 256, and click **Save**. + +## Session Length + +The default length (TTL) of each user session is adjustable. The default session length is 16 hours. + +1. In the upper left corner, click **☰ > Global Settings**. +1. Go to **`auth-user-session-ttl-minutes`** and click **⋮ > Edit Setting**. +1. Enter the amount of time in minutes a session length should last and click **Save**. + +**Result:** Users are automatically logged out of Rancher after the set number of minutes. diff --git a/versioned_docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/authentication-permissions-and-global-configuration.md b/versioned_docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/authentication-permissions-and-global-configuration.md new file mode 100644 index 00000000000..89a7f88fb37 --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/authentication-permissions-and-global-configuration.md @@ -0,0 +1,88 @@ +--- +title: Authentication, Permissions and Global Settings +--- + + + + + +After installation, the [system administrator](manage-role-based-access-control-rbac/global-permissions.md) should configure Rancher to configure authentication, authorization, security, default settings, security policies, drivers and global DNS entries. + +## First Log In + +After you log into Rancher for the first time, Rancher will prompt you for a **Rancher Server URL**. You should set the URL to the main entry point to the Rancher Server. When a load balancer sits in front a Rancher Server cluster, the URL should resolve to the load balancer. The system will automatically try to infer the Rancher Server URL from the IP address or host name of the host running the Rancher Server. This is only correct if you are running a single node Rancher Server installation. In most cases, therefore, you need to set the Rancher Server URL to the correct value yourself. + +:::danger + +After you set the Rancher Server URL, we do not support updating it. Set the URL with extreme care. + +::: + +## Authentication + +One of the key features that Rancher adds to Kubernetes is centralized user authentication. This feature allows to set up local users and/or connect to an external authentication provider. By connecting to an external authentication provider, you can leverage that provider's user and groups. + +For more information how authentication works and how to configure each provider, see [Authentication](authentication-config/authentication-config.md). + +## Authorization + +Within Rancher, each person authenticates as a _user_, which is a login that grants you access to Rancher. Once the user logs in to Rancher, their _authorization_, or their access rights within the system, is determined by the user's role. Rancher provides built-in roles to allow you to easily configure a user's permissions to resources, but Rancher also provides the ability to customize the roles for each Kubernetes resource. + +For more information how authorization works and how to customize roles, see [Roles Based Access Control (RBAC)](manage-role-based-access-control-rbac/manage-role-based-access-control-rbac.md). + +## User Retention + +In Rancher v2.8.5 and later, you can enable user retention. This feature automatically removes inactive users after a configurable period of time. + +The user retention feature is disabled by default. + +For more information, see [Enabling User Retention](../../advanced-user-guides/enable-user-retention.md). + +## Provisioning Drivers + +Drivers in Rancher allow you to manage which providers can be used to provision [hosted Kubernetes clusters](../kubernetes-clusters-in-rancher-setup/set-up-clusters-from-hosted-kubernetes-providers/set-up-clusters-from-hosted-kubernetes-providers.md) or [nodes in an infrastructure provider](../launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/use-new-nodes-in-an-infra-provider.md) to allow Rancher to deploy and manage Kubernetes. + +For more information, see [Provisioning Drivers](about-provisioning-drivers/about-provisioning-drivers.md). + +## Adding Kubernetes Versions into Rancher + +With this feature, you can upgrade to the latest version of Kubernetes as soon as it is released, without upgrading Rancher. This feature allows you to easily upgrade Kubernetes patch versions (i.e. `v1.15.X`), but not intended to upgrade Kubernetes minor versions (i.e. `v1.X.0`) as Kubernetes tends to deprecate or add APIs between minor versions. + +The information that Rancher uses to provision [RKE clusters](../launch-kubernetes-with-rancher/launch-kubernetes-with-rancher.md) is now located in the Rancher Kubernetes Metadata. For details on metadata configuration and how to change the Kubernetes version used for provisioning RKE clusters, see [Rancher Kubernetes Metadata.](../../../getting-started/installation-and-upgrade/upgrade-kubernetes-without-upgrading-rancher.md) + +Rancher Kubernetes Metadata contains Kubernetes version information which Rancher uses to provision [RKE clusters](../launch-kubernetes-with-rancher/launch-kubernetes-with-rancher.md). + +For more information on how metadata works and how to configure metadata config, see [Rancher Kubernetes Metadata](../../../getting-started/installation-and-upgrade/upgrade-kubernetes-without-upgrading-rancher.md). + +## Global Settings + +Options that control certain global-level Rancher settings are available from the top navigation bar. + +Click **☰** in the top left corner, then select **Global Settings**, to view and configure the following settings: + +- **Settings**: Various Rancher defaults, such as the minimum length for a user's password (`password-min-length`). You should be cautious when modifying these settings, as invalid values may break your Rancher installation. +- **Feature Flags**: Rancher features that can be toggled on or off. Some of these flags are for [experimental features](#enabling-experimental-features). +- **Banners**: Elements you can add to fixed locations on the portal. For example, you can use these options to [set a custom banner](custom-branding.md#fixed-banners) for users when they login to Rancher. +- **Branding**: Rancher UI design elements that you can [customize](custom-branding.md). You can add a custom logo or favicon, and modify UI colors. +- **Performance**: Performance settings for the Rancher UI, such as incremental resource loading. +- **Home Links**: Links displayed on the Rancher UI **Home** page. You can modify visibility for the default links or add your own links. + +### Enabling Experimental Features + +Rancher includes some features that are experimental and/or disabled by default. Feature flags allow you to enable these features. For more information, refer to the section about [feature flags.](../../advanced-user-guides/enable-experimental-features/enable-experimental-features.md) + +### Global Configuration + +**Global Configuration** options aren't visible unless you activate the **legacy** [feature flag](../../advanced-user-guides/enable-experimental-features/enable-experimental-features.md). The **legacy** flag is disabled by default on fresh Rancher installs of v2.6 and later. If you upgrade from an earlier Rancher version, or activate the **legacy** feature flag on Rancher v2.6 and later, **Global Configuration** is available from the top navigation menu: + +1. Click **☰** in the top left corner. +1. Select **Global Configuration** from the **Legacy Apps**. + +The following features are available under **Global Configuration**: + +- **Catalogs** +- **Global DNS Entries** +- **Global DNS Providers** + +As these are legacy features, please see the Rancher v2.0—v2.4 docs on [catalogs](https://github.com/rancher/rancher-docs/tree/main/archived_docs/en/version-2.0-2.4/how-to-guides/new-user-guides/helm-charts-in-rancher/helm-charts-in-rancher.md), [global DNS entries](https://github.com/rancher/rancher-docs/tree/main/archived_docs/en/version-2.0-2.4/how-to-guides/new-user-guides/helm-charts-in-rancher/globaldns.md#adding-a-global-dns-entry), and [global DNS providers](https://github.com/rancher/rancher-docs/tree/main/archived_docs/en/version-2.0-2.4/how-to-guides/new-user-guides/helm-charts-in-rancher/globaldns.md#editing-a-global-dns-provider) for more details. + diff --git a/versioned_docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/configure-microsoft-ad-federation-service-saml/configure-microsoft-ad-federation-service-saml.md b/versioned_docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/configure-microsoft-ad-federation-service-saml/configure-microsoft-ad-federation-service-saml.md new file mode 100644 index 00000000000..80ad4da646e --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/configure-microsoft-ad-federation-service-saml/configure-microsoft-ad-federation-service-saml.md @@ -0,0 +1,40 @@ +--- +title: Configuring Microsoft Active Directory Federation Service (SAML) +--- + + + + + +If your organization uses Microsoft Active Directory Federation Services (AD FS) for user authentication, you can configure Rancher to allow your users to log in using their AD FS credentials. + +## Prerequisites + +You must have Rancher installed. + +- Obtain your Rancher Server URL. During AD FS configuration, substitute this URL for the `` placeholder. +- You must have a global administrator account on your Rancher installation. + +You must have a [Microsoft AD FS Server](https://docs.microsoft.com/en-us/windows-server/identity/active-directory-federation-services) configured. + +- Obtain your AD FS Server IP/DNS name. During AD FS configuration, substitute this IP/DNS name for the `` placeholder. +- You must have access to add [Relying Party Trusts](https://docs.microsoft.com/en-us/windows-server/identity/ad-fs/operations/create-a-relying-party-trust) on your AD FS Server. + +## Setup Outline + +Setting up Microsoft AD FS with Rancher Server requires configuring AD FS on your Active Directory server, and configuring Rancher to utilize your AD FS server. The following pages serve as guides for setting up Microsoft AD FS authentication on your Rancher installation. + +- [1. Configuring Microsoft AD FS for Rancher](configure-ms-adfs-for-rancher.md) +- [2. Configuring Rancher for Microsoft AD FS](configure-rancher-for-ms-adfs.md) + +:::note SAML Provider Caveats + +- Users and groups aren't validated when you assign permissions to them in Rancher. +- When adding users, the exact user IDs (i.e. `UID Field`) must be entered correctly. As you type the user ID, there will be no search for other user IDs that may match. +- When adding groups, you must select the group from the drop-down that is next to the text box. Rancher assumes that any input from the text box is a user. +- The group drop-down shows only the groups that you are a member of. However, if you have Administrator permissions or restricted Administrator permissions, you can join a group that you are not a member of. + +::: + + +### [Next: Configuring Microsoft AD FS for Rancher](configure-ms-adfs-for-rancher.md) diff --git a/versioned_docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/configure-microsoft-ad-federation-service-saml/configure-ms-adfs-for-rancher.md b/versioned_docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/configure-microsoft-ad-federation-service-saml/configure-ms-adfs-for-rancher.md new file mode 100644 index 00000000000..925c82951d9 --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/configure-microsoft-ad-federation-service-saml/configure-ms-adfs-for-rancher.md @@ -0,0 +1,86 @@ +--- +title: 1. Configuring Microsoft AD FS for Rancher +--- + + + + + +Before you configure Rancher to support Active Directory Federation Service (AD FS), you must add Rancher as a [relying party trust](https://docs.microsoft.com/en-us/windows-server/identity/ad-fs/technical-reference/understanding-key-ad-fs-concepts) in AD FS. + +1. Log into your AD server as an administrative user. + +1. Open the **AD FS Management** console. Select **Add Relying Party Trust..**. from the **Actions** menu and click **Start**. + + ![](/img/adfs/adfs-overview.png) + +1. Select **Enter data about the relying party manually** as the option for obtaining data about the relying party. + + ![](/img/adfs/adfs-add-rpt-2.png) + +1. Enter your desired **Display name** for your Relying Party Trust. For example, `Rancher`. + + ![](/img/adfs/adfs-add-rpt-3.png) + +1. Select **AD FS profile** as the configuration profile for your relying party trust. + + ![](/img/adfs/adfs-add-rpt-4.png) + +1. Leave the **optional token encryption certificate** empty, as Rancher AD FS will not be using one. + + ![](/img/adfs/adfs-add-rpt-5.png) + +1. Select **Enable support for the SAML 2.0 WebSSO protocol** + and enter `https:///v1-saml/adfs/saml/acs` for the service URL. + + ![](/img/adfs/adfs-add-rpt-6.png) + +1. Add `https:///v1-saml/adfs/saml/metadata` as the **Relying party trust identifier**. + + ![](/img/adfs/adfs-add-rpt-7.png) + +1. This tutorial will not cover multi-factor authentication; please refer to the [Microsoft documentation](https://docs.microsoft.com/en-us/windows-server/identity/ad-fs/operations/configure-additional-authentication-methods-for-ad-fs) if you would like to configure multi-factor authentication. + + ![](/img/adfs/adfs-add-rpt-8.png) + +1. From **Choose Issuance Authorization RUles**, you may select either of the options available according to use case. However, for the purposes of this guide, select **Permit all users to access this relying party**. + + ![](/img/adfs/adfs-add-rpt-9.png) + +1. After reviewing your settings, select **Next** to add the relying party trust. + + ![](/img/adfs/adfs-add-rpt-10.png) + + +1. Select **Open the Edit Claim Rules..**. and click **Close**. + + ![](/img/adfs/adfs-add-rpt-11.png) + +1. On the **Issuance Transform Rules** tab, click **Add Rule..**.. + + ![](/img/adfs/adfs-edit-cr.png) + +1. Select **Send LDAP Attributes as Claims** as the **Claim rule template**. + + ![](/img/adfs/adfs-add-tcr-1.png) + +1. Set the **Claim rule name** to your desired name (for example, `Rancher Attributes`) and select **Active Directory** as the **Attribute store**. Create the following mapping to reflect the table below: + + | LDAP Attribute | Outgoing Claim Type | + | -------------------------------------------- | ------------------- | + | Given-Name | Given Name | + | User-Principal-Name | UPN | + | Token-Groups - Qualified by Long Domain Name | Group | + | SAM-Account-Name | Name | +
+ + ![](/img/adfs/adfs-add-tcr-2.png) + +1. Download the `federationmetadata.xml` from your AD server at: +``` +https:///federationmetadata/2007-06/federationmetadata.xml +``` + +**Result:** You've added Rancher as a relying trust party. Now you can configure Rancher to leverage AD. + +### [Next: Configuring Rancher for Microsoft AD FS](configure-rancher-for-ms-adfs.md) diff --git a/versioned_docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/configure-microsoft-ad-federation-service-saml/configure-rancher-for-ms-adfs.md b/versioned_docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/configure-microsoft-ad-federation-service-saml/configure-rancher-for-ms-adfs.md new file mode 100644 index 00000000000..b2785bd83f0 --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/configure-microsoft-ad-federation-service-saml/configure-rancher-for-ms-adfs.md @@ -0,0 +1,57 @@ +--- +title: 2. Configuring Rancher for Microsoft AD FS +--- + + + + + +After you complete [Configuring Microsoft AD FS for Rancher](configure-ms-adfs-for-rancher.md), enter your Active Directory Federation Service (AD FS) information into Rancher so that AD FS users can authenticate with Rancher. + +:::note Important Notes For Configuring Your ADFS Server: + +- The SAML 2.0 WebSSO Protocol Service URL is: `https:///v1-saml/adfs/saml/acs` +- The Relying Party Trust identifier URL is: `https:///v1-saml/adfs/saml/metadata` +- You must export the `federationmetadata.xml` file from your AD FS server. This can be found at: `https:///federationmetadata/2007-06/federationmetadata.xml` + +::: + +1. In the top left corner, click **☰ > Users & Authentication**. +1. In the left navigation menu, click **Auth Provider**. +1. Click **ADFS**. +1. Complete the **Configure AD FS Account** form. Microsoft AD FS lets you specify an existing Active Directory (AD) server. The [configuration section below](#configuration) describe how you can map AD attributes to fields within Rancher. +1. After you complete the **Configure AD FS Account** form, click **Enable**. + + Rancher redirects you to the AD FS login page. Enter credentials that authenticate with Microsoft AD FS to validate your Rancher AD FS configuration. + + :::note + + You may have to disable your popup blocker to see the AD FS login page. + + ::: + +**Result:** Rancher is configured to work with MS FS. Your users can now sign into Rancher using their MS FS logins. + +## Configuration + +| Field | Description | +|---------------------------|-----------------| +| Display Name Field | The AD attribute that contains the display name of users.

Example: `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name` | +| User Name Field | The AD attribute that contains the user name/given name.

Example: `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname` | +| UID Field | An AD attribute that is unique to every user.

Example: `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn` | +| Groups Field | Make entries for managing group memberships.

Example: `http://schemas.xmlsoap.org/claims/Group` | +| Rancher API Host | The URL for your Rancher Server. | +| Private Key / Certificate | This is a key-certificate pair to create a secure shell between Rancher and your AD FS. Ensure you set the Common Name (CN) to your Rancher Server URL.

[Certificate creation command](#example-certificate-creation-command) | +| Metadata XML | The `federationmetadata.xml` file exported from your AD FS server.

You can find this file at `https:///federationmetadata/2007-06/federationmetadata.xml`. | + +### Example Certificate Creation Command + +You can generate a certificate using an openssl command. For example: + +``` +openssl req -x509 -newkey rsa:2048 -keyout myservice.key -out myservice.cert -days 365 -nodes -subj "/CN=myservice.example.com" +``` + +## Configuring SAML Single Logout (SLO) + + diff --git a/versioned_docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/configure-openldap/configure-openldap.md b/versioned_docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/configure-openldap/configure-openldap.md new file mode 100644 index 00000000000..e7d4c5724a4 --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/configure-openldap/configure-openldap.md @@ -0,0 +1,56 @@ +--- +title: Configuring OpenLDAP +--- + + + + + +If your organization uses LDAP for user authentication, you can configure Rancher to communicate with an OpenLDAP server to authenticate users. This allows Rancher admins to control access to clusters and projects based on users and groups managed externally in the organisation's central user repository, while allowing end-users to authenticate with their LDAP credentials when logging in to the Rancher UI. + +## Prerequisites + +Rancher must be configured with a LDAP bind account (aka service account) to search and retrieve LDAP entries pertaining to users and groups that should have access. It is recommended to not use an administrator account or personal account for this purpose and instead create a dedicated account in OpenLDAP with read-only access to users and groups under the configured search base (see below). + +> **Using TLS?** +> +> If the certificate used by the OpenLDAP server is self-signed or not from a recognised certificate authority, make sure have at hand the CA certificate (concatenated with any intermediate certificates) in PEM format. You will have to paste in this certificate during the configuration so that Rancher is able to validate the certificate chain. + +## Configure OpenLDAP in Rancher + +Configure the settings for the OpenLDAP server, groups and users. For help filling out each field, refer to the [configuration reference.](openldap-config-reference.md) + +> Before you proceed with the configuration, please familiarise yourself with the concepts of [External Authentication Configuration and Principal Users](../authentication-config/authentication-config.md#external-authentication-configuration-and-principal-users). + +1. In the top left corner, click **☰ > Users & Authentication**. +1. In the left navigation menu, click **Auth Provider**. +1. Click **OpenLDAP**. Fill out the **Configure an OpenLDAP server** form. +1. Click **Enable**. + +### Test Authentication + +Once you have completed the configuration, proceed by testing the connection to the OpenLDAP server. Authentication with OpenLDAP will be enabled implicitly if the test is successful. + +:::note + +The OpenLDAP user pertaining to the credentials entered in this step will be mapped to the local principal account and assigned administrator privileges in Rancher. You should therefore make a conscious decision on which LDAP account you use to perform this step. + +::: + +1. Enter the **username** and **password** for the OpenLDAP account that should be mapped to the local principal account. +2. Click **Authenticate With OpenLDAP** to test the OpenLDAP connection and finalise the setup. + +**Result:** + +- OpenLDAP authentication is configured. +- The LDAP user pertaining to the entered credentials is mapped to the local principal (administrative) account. + +:::note + +You will still be able to login using the locally configured `admin` account and password in case of a disruption of LDAP services. + +::: + +## Annex: Troubleshooting + +If you are experiencing issues while testing the connection to the OpenLDAP server, first double-check the credentials entered for the service account as well as the search base configuration. You may also inspect the Rancher logs to help pinpointing the problem cause. Debug logs may contain more detailed information about the error. Please refer to [How can I enable debug logging](../../../../faq/technical-items.md#how-can-i-enable-debug-logging) in this documentation. diff --git a/versioned_docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/configure-openldap/openldap-config-reference.md b/versioned_docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/configure-openldap/openldap-config-reference.md new file mode 100644 index 00000000000..54d62bb9dd1 --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/configure-openldap/openldap-config-reference.md @@ -0,0 +1,82 @@ +--- +title: OpenLDAP Configuration Reference +--- + + + + + +For further details on configuring OpenLDAP authentication, refer to the [official documentation.](https://www.openldap.org/doc/) + +> Before you proceed with the configuration, please familiarize yourself with the concepts of [External Authentication Configuration and Principal Users](../authentication-config/authentication-config.md#external-authentication-configuration-and-principal-users). + + +## Background: OpenLDAP Authentication Flow + +1. When a user attempts to login with LDAP credentials, Rancher creates an initial bind to the LDAP server using a service account with permissions to search the directory and read user/group attributes. +2. Rancher then searches the directory for the user by using a search filter based on the provided username and configured attribute mappings. +3. Once the user has been found, they are authenticated with another LDAP bind request using the user's DN and provided password. +4. Once authentication succeeded, Rancher then resolves the group memberships both from the membership attribute in the user's object and by performing a group search based on the configured user mapping attribute. + +## OpenLDAP Server Configuration + +You will need to enter the address, port, and protocol to connect to your OpenLDAP server. `389` is the standard port for insecure traffic, `636` for TLS traffic. + +> **Using TLS?** +> +> If the certificate used by the OpenLDAP server is self-signed or not from a recognized certificate authority, make sure have at hand the CA certificate (concatenated with any intermediate certificates) in PEM format. You will have to paste in this certificate during the configuration so that Rancher is able to validate the certificate chain. + +If you are in doubt about the correct values to enter in the user/group Search Base configuration fields, consult your LDAP administrator or refer to the section [Identify Search Base and Schema using ldapsearch](../../../../how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/authentication-config/configure-active-directory.md#annex-identify-search-base-and-schema-using-ldapsearch) in the Active Directory authentication documentation. + +
OpenLDAP Server Parameters
+ +| Parameter | Description | +|:--|:--| +| Hostname | Specify the hostname or IP address of the OpenLDAP server | +| Port | Specify the port at which the OpenLDAP server is listening for connections. Unencrypted LDAP normally uses the standard port of 389, while LDAPS uses port 636.| +| TLS | Check this box to enable LDAP over SSL/TLS (commonly known as LDAPS). You will also need to paste in the CA certificate if the server uses a self-signed/enterprise-signed certificate. | +| Server Connection Timeout | The duration in number of seconds that Rancher waits before considering the server unreachable. | +| Service Account Distinguished Name | Enter the Distinguished Name (DN) of the user that should be used to bind, search and retrieve LDAP entries. | +| Service Account Password | The password for the service account. | +| User Search Base | Enter the Distinguished Name of the node in your directory tree from which to start searching for user objects. All users must be descendents of this base DN. For example: "ou=people,dc=acme,dc=com".| +| Group Search Base | If your groups live under a different node than the one configured under `User Search Base` you will need to provide the Distinguished Name here. Otherwise leave this field empty. For example: "ou=groups,dc=acme,dc=com".| + +## User/Group Schema Configuration + +If your OpenLDAP directory deviates from the standard OpenLDAP schema, you must complete the **Customize Schema** section to match it. + +Note that the attribute mappings configured in this section are used by Rancher to construct search filters and resolve group membership. It is therefore always recommended to verify that the configuration here matches the schema used in your OpenLDAP. + +If you are unfamiliar with the user/group schema used in the OpenLDAP server, consult your LDAP administrator or refer to the section [Identify Search Base and Schema using ldapsearch](../../../../how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/authentication-config/configure-active-directory.md#annex-identify-search-base-and-schema-using-ldapsearch) in the Active Directory authentication documentation. + +### User Schema Configuration + +The table below details the parameters for the user schema configuration. + +
User Schema Configuration Parameters
+ +| Parameter | Description | +|:--|:--| +| Object Class | The name of the object class used for user objects in your domain. If defined, only specify the name of the object class - *don't* include it in an LDAP wrapper such as &(objectClass=xxxx) | +| Username Attribute | The user attribute whose value is suitable as a display name. | +| Login Attribute | The attribute whose value matches the username part of credentials entered by your users when logging in to Rancher. This is typically `uid`. | +| User Member Attribute | The user attribute containing the Distinguished Name of groups a user is member of. Usually this is one of `memberOf` or `isMemberOf`. | +| Search Attribute | When a user enters text to add users or groups in the UI, Rancher queries the LDAP server and attempts to match users by the attributes provided in this setting. Multiple attributes can be specified by separating them with the pipe ("\|") symbol. | +| User Enabled Attribute | If the schema of your OpenLDAP server supports a user attribute whose value can be evaluated to determine if the account is disabled or locked, enter the name of that attribute. The default OpenLDAP schema does not support this and the field should usually be left empty. | +| Disabled Status Bitmask | This is the value for a disabled/locked user account. The parameter is ignored if `User Enabled Attribute` is empty. | + +### Group Schema Configuration + +The table below details the parameters for the group schema configuration. + +
Group Schema Configuration Parameters
+ +| Parameter | Description | +|:--|:--| +| Object Class | The name of the object class used for group entries in your domain. If defined, only specify the name of the object class - *don't* include it in an LDAP wrapper such as &(objectClass=xxxx) | +| Name Attribute | The group attribute whose value is suitable for a display name. | +| Group Member User Attribute | The name of the **user attribute** whose format matches the group members in the `Group Member Mapping Attribute`. | +| Group Member Mapping Attribute | The name of the group attribute containing the members of a group. | +| Search Attribute | Attribute used to construct search filters when adding groups to clusters or projects in the UI. See description of user schema `Search Attribute`. | +| Group DN Attribute | The name of the group attribute whose format matches the values in the user's group membership attribute. See `User Member Attribute`. | +| Nested Group Membership | This settings defines whether Rancher should resolve nested group memberships. Use only if your organization makes use of these nested memberships (ie. you have groups that contain other groups as members). This option is disabled if you are using Shibboleth. | \ No newline at end of file diff --git a/versioned_docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/configure-shibboleth-saml/about-group-permissions.md b/versioned_docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/configure-shibboleth-saml/about-group-permissions.md new file mode 100644 index 00000000000..a51b1328cd0 --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/configure-shibboleth-saml/about-group-permissions.md @@ -0,0 +1,32 @@ +--- +title: Group Permissions with Shibboleth and OpenLDAP +--- + + + + + +Because Shibboleth is a SAML provider, it doesn't support searching for groups. While a Shibboleth integration can validate user credentials, it can't be used to assign permissions to groups in Rancher without additional configuration. + +One solution to this problem is to configure an OpenLDAP identity provider. With an OpenLDAP back end for Shibboleth, you will be able to search for groups in Rancher and assign them to resources such as clusters, projects, or namespaces from the Rancher UI. + +### Terminology + +- **Shibboleth** is a single sign-on log-in system for computer networks and the Internet. It allows people to sign in using just one identity to various systems. It validates user credentials, but does not, on its own, handle group memberships. +- **SAML:** Security Assertion Markup Language, an open standard for exchanging authentication and authorization data between an identity provider and a service provider. +- **OpenLDAP:** a free, open-source implementation of the Lightweight Directory Access Protocol (LDAP). It is used to manage an organization’s computers and users. OpenLDAP is useful for Rancher users because it supports groups. In Rancher, it is possible to assign permissions to groups so that they can access resources such as clusters, projects, or namespaces, as long as the groups already exist in the identity provider. +- **IdP or IDP:** An identity provider. OpenLDAP is an example of an identity provider. + +### Adding OpenLDAP Group Permissions to Rancher Resources + +The diagram below illustrates how members of an OpenLDAP group can access resources in Rancher that the group has permissions for. + +For example, a cluster owner could add an OpenLDAP group to a cluster so that they have permissions view most cluster level resources and create new projects. Then the OpenLDAP group members will have access to the cluster as soon as they log in to Rancher. + +In this scenario, OpenLDAP allows the cluster owner to search for groups when assigning persmissions. Without OpenLDAP, the functionality to search for groups would not be supported. + +When a member of the OpenLDAP group logs in to Rancher, she is redirected to Shibboleth and enters her username and password. + +Shibboleth validates her credentials, and retrieves user attributes from OpenLDAP, including groups. Then Shibboleth sends a SAML assertion to Rancher including the user attributes. Rancher uses the group data so that she can access all of the resources and permissions that her groups have permissions for. + +![Adding OpenLDAP Group Permissions to Rancher Resources](/img/shibboleth-with-openldap-groups.svg) diff --git a/versioned_docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/configure-shibboleth-saml/configure-shibboleth-saml.md b/versioned_docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/configure-shibboleth-saml/configure-shibboleth-saml.md new file mode 100644 index 00000000000..5c7c8bc26df --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/configure-shibboleth-saml/configure-shibboleth-saml.md @@ -0,0 +1,112 @@ +--- +title: Configuring Shibboleth (SAML) +--- + + + + + +If your organization uses Shibboleth Identity Provider (IdP) for user authentication, you can configure Rancher to allow your users to log in to Rancher using their Shibboleth credentials. + +In this configuration, when Rancher users log in, they will be redirected to the Shibboleth IdP to enter their credentials. After authentication, they will be redirected back to the Rancher UI. + +If you also configure OpenLDAP as the back end to Shibboleth, it will return a SAML assertion to Rancher with user attributes that include groups. Then the authenticated user will be able to access resources in Rancher that their groups have permissions for. + +> The instructions in this section assume that you understand how Rancher, Shibboleth, and OpenLDAP work together. For a more detailed explanation of how it works, refer to [this page.](about-group-permissions.md) + + +## Setting up Shibboleth in Rancher + +### Shibboleth Prerequisites +> +>- You must have a Shibboleth IdP Server configured. +>- Following are the Rancher Service Provider URLs needed for configuration: +Metadata URL: `https:///v1-saml/shibboleth/saml/metadata` +Assertion Consumer Service (ACS) URL: `https:///v1-saml/shibboleth/saml/acs` +>- Export a `metadata.xml` file from your IdP Server. For more information, see the [Shibboleth documentation.](https://wiki.shibboleth.net/confluence/display/SP3/Home) + +### Configure Shibboleth in Rancher + +If your organization uses Shibboleth for user authentication, you can configure Rancher to allow your users to log in using their IdP credentials. + +1. In the top left corner, click **☰ > Users & Authentication**. +1. In the left navigation menu, click **Auth Provider**. +1. Click **Shibboleth**. +1. Complete the **Configure Shibboleth Account** form. Shibboleth IdP lets you specify what data store you want to use. You can either add a database or use an existing ldap server. For example, if you select your Active Directory (AD) server, the examples below describe how you can map AD attributes to fields within Rancher. + + 1. **Display Name Field**: Enter the AD attribute that contains the display name of users (example: `displayName`). + + 1. **User Name Field**: Enter the AD attribute that contains the user name/given name (example: `givenName`). + + 1. **UID Field**: Enter an AD attribute that is unique to every user (example: `sAMAccountName`, `distinguishedName`). + + 1. **Groups Field**: Make entries for managing group memberships (example: `memberOf`). + + 1. **Rancher API Host**: Enter the URL for your Rancher Server. + + 1. **Private Key** and **Certificate**: This is a key-certificate pair to create a secure shell between Rancher and your IdP. + + You can generate one using an openssl command. For example: + + ``` + openssl req -x509 -newkey rsa:2048 -keyout myservice.key -out myservice.cert -days 365 -nodes -subj "/CN=myservice.example.com" + ``` + 1. **IDP-metadata**: The `metadata.xml` file that you exported from your IdP server. + + +1. After you complete the **Configure Shibboleth Account** form, click **Enable**. + + Rancher redirects you to the IdP login page. Enter credentials that authenticate with Shibboleth IdP to validate your Rancher Shibboleth configuration. + + :::note + + You may have to disable your popup blocker to see the IdP login page. + + ::: + +**Result:** Rancher is configured to work with Shibboleth. Your users can now sign into Rancher using their Shibboleth logins. + +:::note SAML Provider Caveats + +If you configure Shibboleth without OpenLDAP, the following caveats apply due to the fact that SAML Protocol does not support search or lookup for users or groups. + +- There is no validation on users or groups when assigning permissions to them in Rancher. +- When adding users, the exact user IDs (i.e. UID Field) must be entered correctly. As you type the user ID, there will be no search for other user IDs that may match. +- When adding groups, you must select the group from the drop-down that is next to the text box. Rancher assumes that any input from the text box is a user. +- The group drop-down shows only the groups that you are a member of. However, if you have Administrator permissions or restricted Administrator permissions, you can join a group that you are not a member of. + +To enable searching for groups when assigning permissions in Rancher, you will need to configure a back end for the SAML provider that supports groups, such as OpenLDAP. + +::: + +### Configuring SAML Single Logout (SLO) + + + +## Setting up OpenLDAP in Rancher + +If you also configure OpenLDAP as the back end to Shibboleth, it will return a SAML assertion to Rancher with user attributes that include groups. Then authenticated users will be able to access resources in Rancher that their groups have permissions for. + +### OpenLDAP Prerequisites + +Rancher must be configured with a LDAP bind account (aka service account) to search and retrieve LDAP entries pertaining to users and groups that should have access. It is recommended to not use an administrator account or personal account for this purpose and instead create a dedicated account in OpenLDAP with read-only access to users and groups under the configured search base (see below). + +> **Using TLS?** +> +> If the certificate used by the OpenLDAP server is self-signed or not from a recognized certificate authority, make sure have at hand the CA certificate (concatenated with any intermediate certificates) in PEM format. You will have to paste in this certificate during the configuration so that Rancher is able to validate the certificate chain. + +### Configure OpenLDAP in Rancher + +Configure the settings for the OpenLDAP server, groups and users. For help filling out each field, refer to the [configuration reference.](../configure-openldap/openldap-config-reference.md) Note that nested group membership is not available for Shibboleth. + +> Before you proceed with the configuration, please familiarise yourself with the concepts of [External Authentication Configuration and Principal Users](../authentication-config/authentication-config.md#external-authentication-configuration-and-principal-users). + +1. Log into the Rancher UI using the initial local `admin` account. +1. In the top left corner, click **☰ > Users & Authentication**. +1. In the left navigation menu, click **Auth Provider**. +1. Click **Shibboleth** or, if SAML is already configured, **Edit Config** +1. Under **User and Group Search**, check **Configure an OpenLDAP server** + +## Troubleshooting + +If you are experiencing issues while testing the connection to the OpenLDAP server, first double-check the credentials entered for the service account as well as the search base configuration. You may also inspect the Rancher logs to help pinpointing the problem cause. Debug logs may contain more detailed information about the error. Please refer to [How can I enable debug logging](../../../../faq/technical-items.md#how-can-i-enable-debug-logging) in this documentation. \ No newline at end of file diff --git a/versioned_docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/custom-branding.md b/versioned_docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/custom-branding.md new file mode 100644 index 00000000000..120c587b0a2 --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/custom-branding.md @@ -0,0 +1,196 @@ +--- +title: Custom Branding +--- + + + + + +## Prerequisite + +You will need to have at least cluster member permissions. + +## Brand Configuration + +To configure the brand settings, + +1. Click **☰ > Global settings**. +2. Click **Branding**. + +### Private Label Company Name + +This option replaces "Rancher" with the value you provide in most places. Files that need to have Rancher in the name, such as `rancher-compose.yml`, won't be changed. + +### Support Links + +Use a url address to send new "File an Issue" reports instead of sending users to the GitHub issues page. Optionally show Rancher community support links. + +### Logo + +Upload light and dark logos to replace the Rancher logo in the top-level navigation header. + +### Primary Color + +You can override the primary color used throughout the UI with a custom color of your choice. + +### Fixed Banners + +Display a custom fixed banner in the header, footer, or both. + +To configure banner settings, + +1. Click **☰ > Global settings**. +2. Click **Banners**. + +## Custom Navigation Links + +In this section, you'll learn how to configure the links in the left navigation bar of the **Cluster Dashboard**. To get to the cluster dashboard, + +1. In the upper left corner, click **☰ > Cluster Management**. +1. On the **Clusters** page, go to the cluster where you want custom navigation links and click **Explore**. + +It can be useful to add a link for quick access to services installed on a cluster. For example, you could add a link to the Kiali UI for clusters with Istio installed, or you could add a link to the Grafana UI for clusters with Rancher monitoring installed. + +The custom links don't affect who has access to each service. + +Links can be created at the top level and multiple links can be grouped together. + +### Adding a Custom Navigation Link + +:::note Prerequisite: + +You will need to have at least cluster member or project member permissions. + +::: + +1. Click **☰ > Cluster Management**. +1. On the **Clusters** page, go to the cluster where you would like to add custom navigation links and click **Explore**. +2. In the top navigation menu, click **🔍 (Resource Search)**. +3. Type **Nav** and click **Nav Links**. +4. Click **Create from YAML**. +5. The simplest way to create a navigation link is to add these fields: + + name: linkname + toURL: https://example.com + + For more details on setting up links, including optional fields, see [Link Configuration.](#link-configuration) +6. Click **Create**. + +## Link Configuration + +### `name` + +Display name for the link. Required. + +### `group` + +Name of a group of links that expands when clicked. + +Optional. If not provided, the link appears standalone. + +Groups are displayed separately from standalone links, as shown below: + +![Screenshot of group and standalone link](/img/grouped-vs-standalone-links.png) + +### `iconSrc` + +Icon source in in base64 format. + +Below is an example of the Grafana logo in base64 format: + +``` +data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAMgAAADICAYAAACtWK6eAAAgAElEQVR4Aey9d5xkZZn3zb/P+3mffZ9nDcDAzHTuqs49PZEhCBhBJc10nO7pHKbD9PR07p5AWlEEZM2ioph3dXGNqLgCxhVBRIYRmNy5cjqnTlWdqu/7ue5zTk+DiNIsCn4suOacrjrxvq/fle/7PofX+ycDZNT/pIAUaUUmaRBKp8FMQ1L9qL6S4+VYUikIeuBrn+LppiuJNG/BvHYd7HbhbXLBZ/dB8AkwFokCHsAH6Kb8IxTHJIyBHwgDMTBT6h7yWAmb1L3sxyEjfxkYxDDQMa0nWV0vyE2slwZ5JtUO8v5JUhgk0EkRw5TnUg9sgJm03lsezkyTIU0C2VrNJU2WsdtTPVQyAmYU4mGIhDESaULAcSG5RjwJEQ8YsxgEOZoOcSxjvXsyKM8nL24QJ4UmF5TnlL7IWLure/G/3lnn/PVu9SrdaQVApO3/CCAZAYjNSLIVBrD/VMwSnsf4/B38ofWthFu3krhhPZmaLJZuyEY7vJPIV++AwEnImJwJ66qTFcMLSswkGWKkiKqtMIICwB890zL/2lwoHGLYnCIMtMqP3Md5N7mMDRDTBkhKAURAqNBs3TOdspjWERgrmkYuJbQMEPUeKdAEIBrIuSIKEiZ+B0ShADz7W/Tjv8TMLOIjybxcJwNJOUgAkjHQSFoAkedMWn2g7rXKV/9rnfZ3DRCRjgoN0ik2A0nDLgMkbYD3aU7dPcRT7ZfhadmEVldA/IZ1RN6TRahxO8f37CTyxU/B4pySvOlYHNM0sZhQRKgwTRrRWALOZc0lWksoY30n0lPkuMBCPYCcKn/Ic632Iy/ivNvy+4k2EOAamDbJ/rIKFYEhx74AWPIWcpRhv8dyu5mQTEEkmUYTjSsaMBWDiA9mjsF/foWTH76Z33zqEL6jD5IgRkTeR64valfOQQSL6My0Ap/c32qvlNJgq339v8Z5fzcAkcayBKrFkNIBCiDOD/Lj8jG2iZWOwvGHefxQNY+3beHk7grCDS7067JhRwn6dZX4d72L3zVei/6Vz0HYB/EQJINKawRTQXVP+UfYQEjdRphITBlTNIrFqBopIsqcsZnaQYww0iv5yA1XkuJ+eRJREStJvrMFhnO8A5S09ewCDoMkCQUw67KxOMQMCBkpkok4JIIQnYGf3k/s7mlO7N3Fw7VX8J2Ot3Pi/rvBXMLMJKxbx+UR5L4CEJ0IKYUbeV0xAUXDZVSrvZIGeHXPff0DRDGE9PRZPhGec8jhBWcr30uXCWEG4Xf/wW+H38ajXVUcaS7GX+dGvyYX6jeQvL6MZO1lzFx7Mc81XkPyM3eC/xlIz5LJzBIz/bbUtUyKZaksUtPUIS06wzK/LGluM6jwrVg9wkCvECDOe51lE2kL5w2drdU+Ths5bSBbMacsVMtGtKDFug5+5Q00Iw2JFOhhmD0C3/goS6M1HKvfiqfxMo7t3MLv2i7F97nDoJ+BpG45IXLysgYRgIhvJPeRu4QVibZ7LX/+rgDiNLTT58IADjM4rPI8HyXpgYc+yXODF3G0ZyPPtZSxUFeM/9p8MrUVJK4rIX5NMfEdm1jauZ1j7Vfj/exNcPoRSB2HxIICiHI+Hb4U00mYSWkP4RAhHTKiUexggfCEPJDiUOepX/5W3tN5R9m3PpZZJ6bdWbJ+kWPkto51JyaVxbBnpYtcT35XwFDXt8Ee8cJ//wj9X6c40fF2TtZU4qspJV5bidawCU/HxWgfHoTwccuhl4srE0saRnwQwwaIZQKa+BH6B0CcfnvVttIBK8jmFId5zjKEmA+WhJTIkeoYYxY+t5/FtmJ8zeUEWzdypqmM07VFhGpK0W9wYVyXh15dQLxnG/NdF/NE00V4PzgAv/0OLB5RbyWKQD2CML5wV1KMbIlmCSgkapQEkcLCNPJ72mJAsdXl+Vb7cRh+mcnlQvKl0IomUfs2mOT28rwCaiErgiW+hXWOaBSnzRSw4/Mw/wR87zN4xht55vqNzNxQQXj3VoyWzRjX5ZPcWUigrozozU0QeMbSNAnIyA0EcaQRE1N8EPWn0hoSDxSSRnntfl73GkTMAsvXsDnCYZAXMERc2dei2i0HVnWMdpro4etYuv58orUujLatLLZsZKapkqXaYqINRZi7XWQ63ASacwh2lhPtvZwjdVs4M94ETz4M8ajFjI5TLlsJLavwsu0GCA84JpX4uEAAVHBYGHa1H3lVuZaQxXgvAIh86QDFDqu+ECDSIstS3AGWnCdmUnwRjv4Y/XMHON51OSerSwjv2kCqdRta81ZiDZWwqwjq8onWFKIfrIPQs5CIKl/ekJvZDyagFJJbWKFuiQFLePwfJtZq+//PnieNLc64lUuwTYoXMITwZowMgbSu3EIjE8NMiKMdhmd/zlzrRjJ12UQb3IQaKojUbiRUW8VSQynzjQV4mtfjbz6fSNN5hBvXsrjbzXzTZjz1V/Bs0/Xw0A9g7qRy3E3DRzARUJpKni0ZSljpEUkcCEBsQR3BYIEIC2mxw+WBV/dx3v950TP5UshpBxskqURG+cvCjtImwqyyDYZ9pDPiMKfR4hHQY5aJdPIIPPg1jrS/nZndW/E0lRJodBHY5SbYUEq4biOx2goi16+D1iLCO/PwDL0HfvdD5X9JFNwXP+vjyL2UMJDnUs8kRpzkjv4BkNX1/l9wlmiOhHL4RIbaDrA0vs0UwifSMVEkuSWJsyTxRACMIKSi8Nj3WWyphLr16PWFaPVlGDs3ou2swldXpgCy0LoWT+t5RJreqEASaMpRDGLs2E6w+u2c7mkgcM/t8IdHID2PSZAQUaJmSrkAypgXXrClaTIj5kZcRXXiKlH4ygAibXA2Yme3wUqAJDMWWDJgGEmiWgzDFL1hCRcjHkWP+kgaPkgHQUyqIz8l+fHDzLa/i0DdVrTaUmL1LsINBTZIignXVRCpK8W3cx3Jdjehnfl4970bHnsA0rpi/QWxLqUf7SiZ2pd/BBPio0kQQyVO/4LO/hsd8ro2sYQxRPYJSJSZJYwhHSBkWoJUABJRqTLRM0m08KKlPYwgiR99kZOdlRi71pOuKSS90wJIrLqK2M4yZTaEGy0N4ml9M96W89Hqs0lVu0nt2Ii+YztPv8XF8ZZ3EPrkAfj9dyF50gaJhscwEP5U0twGrZlKkEhKwDNkZ7gV27yC7ndUxYtfwkymMZMp5L7KF0pJNj2OmYiR0MMkRWsIoyY8MPsYia/fyZmxGzjdsInAjjKM6nIS1aUKJOH6UgK7LAo2FBPc5WKh9kJiYoJWF7I08G5SP7sfMrryLuZsYCjZJYlFp39EWKhIn4TBVy8gXvyN/2e/fd0DREoY4sqvsEo8lHQSCSV8Z5c8RDJJxAeRUKvmm4FEGDQ/S1+6k2NdG4g1ZWPWFJLZWUZi5wbiOypJXF9GfIcbrT6HYNNaPC0X4G2+AF0BxEVqZ7k6NvRuN96dGzjR+VZOva+LyMNfgOizYrwQJkIkY1qmhcMcSZGccTJmCF0XJ/UVAESuuRytOssY8rWjSGVf12MYsbDKyYh0z4SXyIQWIB60hIU2D7/6FjN37uVo56XMNpQSqXdj1LpIVBdj1JSi1WwgUrtBaQ4xscTc8u7O40z9hYTa3UR2uvD2vpPIA/dBJooXmLOfQwkIx7SS13X6RwIY/wDI2Y77n94TDWKVMCQtP0Q6QRpfJJRsJXyfgWhaoCFaJk5SACKM4ZnlxIemOd2+mWhTnvJB4nUlmDsqMK8vVwDRdxYr0yLSkEekIYfwrhyCjXkqmajVFlvMc0M++k43vh2lnKzfxqmpRrRvfRwWHlPVW7G0D40YyaSBGRVJLV66xSWmZPIV96yyZRQSnIy9JRDkK7m6NIES1CIYMgkykv0W3yvug+giaB7LnDrxK1LfvYeT040cqdvEUm0JdFRhtpbhr84mXF9MuL4crWYjevVG9JoKYhIKbypgsTmH0w3rCLcWkbjBTbD9SrxfuxvSfnyYLDmvpQIXKzSpoFceVJlX/9AgTjP9j2/FsYyRVKQcdWlr4QrHIzQhYUIsbSq7Py2Z8/CC0h4cO8rRw3uZb9mKvstFZJdoixISO8tJ3lCuTKxItUjSYiVNtTqXAotyVBtd6ju91gWNLpI7skheV4BevYHFhks4PnA9S/feQup3D4B+0o7WxIjrYUxdEogWs4j584o+DkCk3kku9YJIlTjikZROUsIGKfEvvJDyg+EB3wkSj3yD2dt7OTnwdk7UbySwq4pE0wYiNYUEavOJNJfiF5OqoVw55HpNOUICEKVBmgo4U7+OsBR2Xu8itvsyFu65GVIegsRUpkN1hiRNRVvY7+3UellZ9FfYBq+oAf/8ya9rE0sAItlZAclLAUTLpIkmJfQoUZoASNLrsV/x9Gg3vqaLSNcWkagtQq8rUY6nxPT9tWXKUQ/WVygJKlJUnFIHMFKSEqvPg+4K0rU5pG7IgdpSkjdUMn/NBmbarmLu1n7MR/4NPE8qkMTQCKSlhtcSnlIoqyTpn++nFz9CACKaUsiWyqI9RD5ICkLyDhF0YmYYQ1+CmJhVi7BwlNPf+zK/PtBGtPsSwlefy+w7z1P+RazrYhYbN3K6upTFunIFDvE35H0jDQVKMKg2qCtV2mWxJksFOHivi2TdxczdNQqJWaKZABKtIxO2KhZsh1we09JuVtWxFaJ/8dd7LXz7ugaINLb4FpZ/YYd5RZ07XJK0SoESaZOY5icj9dcSvZLy7Ie/y+mBBsINW0nXlJKsKVEAEfva11CCTyI0dWUogNRV2FEbkZ6lSoKKjR6pd5FoLMLcVUSqzkXyhgL09+ShS/a9fjvB7qs5PlJP8vufhugzKjEmxp4wsDyiVIorS8PGibP/oowhP4oIdrbOvi2V5VfHtLJyDhLhk5yPbmmN2Ax4j5L61bc58pGDPDTcyFNd78SoLoTq9dBUjL67grn6ck5Ul3GmpgJPQxXB+nLCDW4VwXLMSzG7YrVWW/h2ZqHX5cF1hcTrt+G5bS/EThNP+YjKmwowklEwJWJllZo4Cl4EnHqdF33h18aXr2uAqCa0TQtpaKvCVuobjGVTS3zAuCHJvCCYAZICEM2DcecowV0X2aZDKbo4ohLOFC2xTGJarKA66xjruGIideUqbyI5AUvTyPluxBwzatzqev66TXj73g2fvRWOPQpxj2KaU1qIZ2NhO5ttMbcw+LJ5btsjmYyE44QEHBKIcLZytDU2Q5KOkmqRrELELsBPZOKQDkPKC8YMnPkl+r/fydHhnfy+YRvzjdtJtl+GUVNMosaFVudW7y2ACDRUqPdR4Kh3tKZoEREK8t5WG4mppTfkE63OVu8c7ryMk/vq4fhvVeInYJorhJVIAyvULhUN8p6veXQAr2+ACCrEvLATcAlV8xNUA4WUHo+DRDWTCRnLEADTgxxDeAbz5naSNWXLwBCmf7kkibJw7VYCddvwN2zE21iKv9GlnHkV7arJg8ZKaLmUeP8NxO+cgF9+T4VUpZJ1MR1TCbuzDvXZ6FPaCYvKOzpaQrbCWYoEKOJbpfASZyEVYTERJGRKUFukdRik1mzpaXjk6yzePcLxve9ltmkbkboK0tUlZKrd6LVnGd5h/L90K8IgUZdPpCbb8km6L2W2fycc+ZXKhQTkOaV/RGWIv5XRVd9IxbAChy3cXhu64sWf4u8OIHGkFF23OiYOetQkrQoHxbySMYE6zD5FdLzOju8XK5NJpOHLJqVdJPy5Udnq3sZiPLsL8O7OIdyYrULEyVo3qcbNeOsv4Wjj2zl2yyCZn/4nhE6qkXppCSRImZZpkRPkUmkLqWdaaTeJ8xJNk4mYZMIp0mHNMhkTS6rM3Kpt8oG5CN4j8Mwj+L54JzOHezjW/HbmqrcSq5YQtovUNdkY165Hr7W1ggpGSEDiLycBiFGbpwAigsHTtZ2Z/hvg1z9WWjKsRk39AyAvDr2/xrciXYWBVmiQuCqjtgFiQDRkmSLL5obk1Z98mKW+d2PsLEHCtS8bGDaYRONIIk2rLVcOqwzTXWjJY6ElB//ubKVJQjuyiVaLlN7CfMOlHG27iuMHOkh842Nw9BcQ84IeAc2maBhiMuYiCJEgEm3j2afh6FNw5En4/eOkn3iUzOO/hsd+Bk88BI//CJ78L3juF3Div+G3P8T4z3vwfewQj7VdzTONV6roWrLxIlXGn7khH65bR2ZHNhKJezmgWHmsACReY2kQ365Cljq3MrPnGvjJf6j8SlTU4PM0iDUGRHyjf2iQvyZARHur6Ig4wFGVEFQdk4BYWPS8HCCOokhXP+Eff4XZjiuIVxe9IoCIeZLaKTa85bB7mwqYb81jti1HgUQ0iUR+gtflEb2uGKPhIoJNlzHbdDmefTtI3L4HfnUf/Pwe+OHd8B+3wudGMT7cQ/C23XhursV7Yw3ew9V4DlzP4tS1LIy/h7nRq5nd/w7m9l1FaLgeT88OllquI9xRjdm/G/qbibVdz2LNFczVXsJ8/RYWaivw1rgxGlywuwh25UN1tkoGrmT6l7MvANGr84hU5+JpzGexfSMz3e+Cb34GdC9xGaIrALESMsrekuG/UtHwD4D8DQAiDS9DPsVZd0I6CTFLRJJJNEUAEjnJwlc+yJmWi/4HAOLG3OkiVS0h3wKVPJtvKWCmLQ/Zirnlr8kjurOA5A1ukteXkthZgV5bRbhhM77GSuYb3cwJsHa7WGh2sdTsxtPqwt/qVhRocRNsLiDYlE+gMQ9/Qw6++vV469bhq87FaN5GtHoLwasriF1VBddeDDVXQt1boe5StOrNxHZVqfox784cwrXryezOh0YpmblQDTF+OaBYeawARNuZvwyQhfYK5trfCl+4EyLzmKrU3/ZDRE5lZEShjLBcAZC/Bp+8gnu8/n0Q24GV9heAWMM4ZRyG3TGSaLYdRFI+mP8tpz48ohKEEmmSTrZCti9/K5EfAUequkAlEcUOX2h2M9viZr65GE9TMUvX55KQ7HRtKZnrCkm8NwdzRyHpWpcybxJdm9G6thDr3EqkfSPR1irCzZWEdlcQ3F2Kt86Ft64An02B2gKVxJNEnqIGF776QjUSMlBfonI2oZoygjfIwK9CNfhL8jvplgqSzUWEG7Lw1a5hqfZNeOrWqPCtFcaVUO7LI2m72I48wjtzWGrMYb6tlPnWizE/cRiC4mNJlMQ2g6WfVFhXQs82QETtv8Y/r2+ASOPakRALICKh7LCW9YX6XUq9JcRI0gfHH+H0+9rxNm9RodhXChAJkUrNkoAssEtAUcrC7nI8jRX4d1UQra9QtUzmDS7YUQA78mBnNunq9aTq85h/73pmr8ln/rpCFm9w4a0uIVgrSbhyIg1lBGqKCFbLAC6poC2y/SUr6y8l+r7GXPxt+QQ6ixR5W4tZairEU5uPrzqPeEOxer5kvYtUc5Eqq5mvXcOJujczs+tCAo0FLxsYDpCk7aLXWwBZbMpisa2IxeatpP51BHzPWZM7SD8ICRgUIOz+Wf77tY2Q1z9A7Ia2+kEST45TbneMjHKNZ0gbGsTm4dff4Ll9V+HdVUFkR54aKBWuc7EakkFWMaGaIsK1JWpUnb+uEl99FYHaKjWuRKJGcSlf2VGiRt4ZNdnEa9cRq19DtH6dun+0RiqHy4jWlqhtrKYEi4rUtbWaIixyEa92Ea8pVNtoXT6epizmWtcx15JlUy4Lu3PxNeYTqi8kVluIVmNRTLROg5yTy1xLLvPNuYhzHWhwrYqkzVKitXbmEel2M9ucQ6BlI6cHr4VnfmbNpyUdY/uIFhRWRFVe29hQT/d3ARDBiAMQ9VYKNHZ9kgKIOIoJ0Bbgh59kpu9ygo1lRHfmvyKAWKCywBGqKyNUW6lAEarZpPyC2M5NaIoq0apLFLOG6yVnsA7f7jX4G9cpYMZqyrBIgCH7Jep4BYrqEhscAhKXTWcB4m/MwrN7Hb6mdch+qEEKDHMRMGi1+QpMAhABijyvgMG3y4WnsVCRf5XgkOvI9TKNlerawW4XpxsvVLVbZ/a8Ax7/nnLUpWOk9spRIhZabCH2D4C8+i3gaGoLILYaV2aX3QkSaZTaCylBic3BFw7i6d5MrEkYNl+Vi0id0epIRtcVWyPspCSjbgOxmo3Eajaj79yKXr3ZcpKlTFyNpXCrEvHFlmzm29YiWzlfEncWSb2X7MvWrv1a3p7NaIs5p0LT9S60+jwStdnKbEPqwa4VyoNrC1QBYXqHW5mSco5VmWuFtSUCJyFu+V7GdayG5Fx2b1ZmnL87n5O7zlNaa777Cvjp1yC2ZJm4diBL+mi5ImA5+/nq88grucPrXoM42kPgIPtn292ydSURJ9l09aPvGJHbWwm3lxFvLlYRHLHjpZJ3NRRqLCLYWKK0kfgL4m9odVUqShWv2YReu4loXZUayhtoKsHb7GapJZ+FtlwW2rNYaslV58t50Xo53yJ1rYYSIg0lRO1tZFcRFp191uguqX/KJ1mXT6Y6H3bkg+Q4ri+EGwphhxuzxi7ErC9S1crisCdqyzCry1TwQMbdhxrdqyI5l8aNGLtK8HbmcqrxXPRdBYR6r4AHP2dVDcuQAztXKH1k9Y/s2QLslXDvX+Hcvz+ALKsSVd+gZsuURLoCyPHH8Ey8B6PFhdkiYz0KiO0qItq4Ogo3FRFqKlYUbSwmtqsUvaGUeH05upSIN5QTbiwluLsYX0sRvhYXntYCfK15ioLNecQaXarcXkruHbK+KyDWWIDeKMesoKZcYjbJOJbw7gKCzS517aVWF/PtFkmoWL6X90vWF6mK5UxNMUIpSXDWW88qzx3aXbQqiu0qJlVTqTSIpyub2eY3k2krIrnvbfDtj1rjTaQWzh4DvwwQmfFFjc957YPkdQ0QR3sIJqSplQax2l6VlMiUm6rOT6KKaQj88gGWBq+E1nwyLUVEanPQmtzEmopXRZHdxUR2uxXJdYTijdY21uQm3Owm0FqIt80if2uh+jvcXIjWlE+8KR+tSfbPUmx3IbHd+RYJgGyKNOcRacl5PjXnWfdoKWapvZjZzmJOdbs52eNmpsvNggyFbZH3c5PY5casd5NqKCbRUEx8V4kyM+Udws2rIzFT9etLlgGy0HYedBeT2Xcl+hduBn1WFVeenWLIcRb/AZC/gvKzAOGAYxkgdhRRaq5UqbeNIhFaz/3nF/ANXKoAQoubUHWWYh6HyVezFYYWZtd259lkMXGoNQd/Ww6ejhyWOmWbR6A1TzF+QrLYdYVkJMrU5CYkz/I8soAk4LIoX4Vy/W15rKRQSz7xxmJl4lgMbwFWQCFg9LQXstRhkewLUOU3Aa7zrrK/WlJ+3LVFGA1leLuzWGw/HzpdJHsu4rRUCcwfeXGAqBGVMsJTek0lSP4q/LKam7yGNYg03AtImH0l2X9KM4udq5xASzjZVq8M2LF/MBIcue9u/AOXQ0chtOYS3HkuWnMBEdEmq6Boi4toSwFaS766jlxL9iOt+QTb8vF15CKmh5C3M5tgezZ6cy5mYz7UCxWo84JtBTyfXATank++dhe+9gLObgsIt7owmmQ8SolNRSTFZNttPVegvQBvRwGLXfksdMlWzrfuFWktUM8uzy/7kRbXi9AL26WESMsKai7FU+0i1FaqAOJrPRfackk2l3F85Fr43Q9UTZb0i5hZ0keqS6WPVg7DVUEV6UyJBzsduAI49kzyZ7veCuf/NQD2NweIemm7ASwbyW5FaShFYh8JOWMhbFTY2DH0FKFYnEBaJmawf9OTEI1DPIVKEkpnhDw8dfdBwmPXIqFW/7X/C63h/6J3FBDrKH4F5LbPLUVrq0Br20CsfQORjgrCnaUEu9wEevII9uQQ6c5C78wi1ZYDLXkgJlPTeQR3WxRqXkOweR3B3VmEmnMJiXllP1u0qwShSFcZEdnvLkXvKiXVWUK6vRizrYhUq4u4Ddjobjk/l+DuHIIt2YRa8wi35RNtK0BvdxHvcBPvLCTTX0Zqj7UfFaEhxyvKJbS7AL2t1KZy9LYK9NYNyxTs3MCZvnJO9RcR6F6P2boGGtbArlx8HZt5Yu+74blHIHpazSujy8yWUuErGJCpkJYk9C6DWVIQS9jDcmWAlcxbJgdYCRQVJl4xQbhUTJiq5k7mPZaLvXqfvz1AnBj5WfFgN4wARIAhWmAFQBylImLJljwpE8JpmXTZBoiIKl2mNMkQlepYmazg+GMcOdSJv/cdBGtz0Rr/mVjLG9A684h0Fq+Kwp3FBLtKCXQJEEoJd5YT6Sgn1lFqkwBPAOQm1ulC63Ap5jTaC0i0uZBttD2HyDIJE+cqRhZmDreKlrA0RailUDndgd2FquZLEnzeXXnonUXqurF2l2J+0QYWMCxm1zrc6nfZxtoLcY6LthUSEQ3TkoO3JQtfS5YCUrglj1hrAUabm1R7MYlWtyKjrRi9vRit3Xq3SEcp/p5iTvWXcKbfRbgzF7NlPTQK5aK1lnFqz0Wc/FAXxq+/BimZ4ySKaWhktKQFDBlyvDLEJdEUGXkY91ujEJVQtPIoAgM51NIvUq4SVmR98/cMEOHpleCQ/WU9LA6FTUqb2ClZOcYGhxxtJFLEjJTS2nYLKmUkQzp1meTTnIOf/RvHB65Fb96OUZ2P2VeAv20Nka4CIp3uVZGAwtu9AU9PBd49bvx7cgj3XECs+3z0rgswOrIsBmupING8WRUW6i1b0No2Kk0T7thAcM8lBHovw997Ef6erfh6qvB1leHvKsLfUUi8v1xRYk8ZiT0VJLorMbo2kOisIt6xAb13I9G+DUR6qwjvqSDUU0mop5xgdwXB7jKWWouQ6Ja3vQRfRzGBrnL1e3jPBoL9Vcz3livy9pap4/WOEhKtxdaUq40F0JxHujWHVJul/cI96/H3rmexfy3evvWEOwrR2oqItZURtSncXkKoo4iFnjKe6d3MiffVE/7OR+HMb0Am7ktrpE2ZsClD1ATNnsPMshIMezoima9LhuxafS7yUMAhW+vj8IYwwtH2mK0AACAASURBVKv3+ZtrkBf6FC8KDtU0KxpiBaDiCQMhmR9agUa2KUvaxJUenwf9d6S+cjNL3ZdD6zaodcPQRubb1qsSiWhXEashMXVC3WUEe0oI7ikk2JtFqG8N0T3nE+9eQ7IzC7O1ALO5HHP3ZhK7t6G1bCfcth1/5za8ndsI9V9OsO8tCij+nm0Eujfh79qAv70Uf0cx3uZ8fM35BHbnK5NHImDK92kW/8ClGFGAtJIsX8XyN8I9xaykUHcRDgX2lLDQVcRiVyn+7lJlthldZUpzpFvdpFsKSLflYrZnk+jMQutZR6j3Qnz9F7K0d41633SzG5rE9NpIoHMjiz0bWNhTgWdPsSU0ess51V7BM3vfhudTY/D7H0JK1qAKq8k2ZhI6c8kUkUzGsrClRF40iZhYQmI9KCjZUUpHOFqqxP7y7xkg8m4OwysOFyDI2zsSwop2yOwXzmErtzK6Wf5W/5j2HAEx0FOaWhIMjsLv72Pp5huItGyAzougqRRz31Zm2wsJdYttvzqA6J2FinnS7VkkOnPRugqXr6V1WXZ9ol2kbw6pVrH93Yjd7unaxkzPW5jv2U5kTxnx7gLiXUWWuSQmTGs5sdZKoi2WTyO+jfgClrlUgN6Vi96VTbxrHVrHhWida5ZJNNdKCrW8iXDrm4m0nUus43x1XLz7QoyetaR6sqC3CPaUwZ5i6Cki2eNSzxPtzifcnUeoJ5/Qntw/okhPrvJj2LUBdm0m0bJBaadZ8UkGyjk9UM7inlLlR9FZgtnmxtNejveDTfDYVyEzq2Zc8WCySEZNESTTM1n9qEqwQeYSUHPAyJgFMaDtyQGFPeRPoRVy89WAyd9egyyDwgGGAwirLFqcMGuCaqfe6vlbOdoBiClDVMW3k/GrMsWPcZzQo5/lzGc6ebarglBjIXRuhLYK4n2bWOouI9xTSqy7eFUU73JBe7aiTHuBkrzJ9kqMjg3EOyuJdxUrHyfWlaUcdHHU/T1uPD3lLPRsxttdgdaejdl+gTJhku35JDrcGJ2l6nytu4pY9xYi3VsI7dlCsG8zgf6N+Pduwje4Ed9QFWe6rNzH6Z4SzuwpZqa3jJneEoRRZ/tKWdi7gYW9FcwPVDLXX6a+l9/P7CllsdtNqrecdFcRiY5Com15hNoLCHQVEuotItxfQrC3yNrfU0S0pwi9u0iBOdlZRLqtlExzJWZLFVpHJYEeuUclswMVLPaVEepxk27NgqYLQbY9JSwObufY+xsJPHQvxI+rhT/DagWqJFEzoeYPVh0qnSrLRygUSKeqjrU6X76WiMzfP0DssJ74Fyu0howXsIBhgUN8CecIZyu2qFAsmSSeThNPmWoOWjVBmRGGM0/AL77KsX9t46n9F3O6w0203QWdpdBdTqijhEhvJdGeYtXx0vkvl2KKWYpJdhSTaSuGllKbykm3laN3lePtKWa+z83sgIv5/jy8vVmEe9aS6DxfASO9ex1mSzbptnzMrnxSfS4Sg0XEhyuIjFUxt7eS0/u3cmb87cwcvJ75W1tZ+mA/3rtGmf/INOZ370V/4F7iP7gP44efJ/ngl0j9+IuY//UV0j/5Mvz062qrP/B5fP/xUc588Q6euecmnvzIAf5wRz8nJt/J3P4tnOyt4GRnKTMdxfh6KtH3biWz/2IFVKOjklS79U7yXplWi8SJj3bnEugtZKm3ksU9W/D2bCXSWYnZng9ta6BnHVrdPyEROnPsYkKjb+NY18WEpnfCN2+HM/9F2jyhpmoVq0F8SS1h8b70tQjHsyCRCejsUYoCDvHa/741iAMQx5yytgIQmQjO+k/A8XyAOOCQBtRUOtCad1eNGpRZA71HSXzn4xw9UM+xfVfyXFsZsaHNJPZWqmiS0Vem6qBifWWEbcn4csEhx4v2CfVsINwtGqOcVHupKrVQ5RYSnu0uxttTynxfKbP9xcz3F+DvzVJOvNnxz5jt5xHtKFQOdaC3iuC+LQRGLsY/fQWLN76D2Vuvgf84AN+9HX5yLzz2HXjuUVg6DiEZHSnj1kPWeHZdVqKVCNCfIRn7LueF/OA/BY/+O/z4bmJfmWLu7g5OHtzByeGrmN/7Nvx9VxDu3I7esZVU20YyrZXQWm4JgdZiUh0u5YcsDmSz2F+EV4IEXRXEO0rItOVC6zqMhjcqX0zrkQBBKaHujST7Loaei1jq3U7gK1Okn/0OJGfUNEWJpEnAgGDaWqBKcGCFciWaac/Q6Mx9JoygzIdXw7iyrvk3NrEEIHYo9wU+h0gOAUYsqas1ti2QpNXU/VpcxzBkjiWZORD8yTAZAUZiFk79HP2rt3D64E4W979DRYciPZuI9FQR2VNBuLeEUL+bUH8h4b5CIr1uIr3Fq6JwbxmhgYsI7NtOaGgL4X0VBAeK8PVk42lfy1LzGrQ9Vpg30laI1llEvLcUY28xWl8eS31uToxdzLGb3sviv7ahf3EafvBJ+M234blfw+yzEPFDLAq6zPUlQ4nFiXVyRLIvs+OtklKylqBMYC1zZy2A/1l4+mFS3/8c/k8eYPHWDuZGriW4753oA5eS7tsCPRXQ6YaOPOjMJT5USnS/1F/lYu5dT7L3QrSutfhac5nfXajMQ61rE2ZHBbQXQ1shtBdidhYjkbRj+7ZjfGUcnvsRhE+QNmJqfi9ZWkfm+1KznCnr24CUzOIijrvARozrV//zGgGIo0EsA8oBh4BCZpaV5Q3ipoFuRLEmfLYYJGnGmUv41YqzSgL9/rtEPjPK7ORVeIYuITl2GWLHG50Wad0bCPWV4B9w49+bq8gCyWoBUkJo72Z8e7fgFZ9gpJLAeAWBURf+gWx8XRdi9rthsBIGt2Ds3YZv8BIWxt6B933VLH1sD8YPP0ryv78Gxx4C/x9AZlrXRDNEIBg5G/wXv1XW+FieVtQywxWLCAOthjIQ0ZJoyYwValeTLAgYF8H3DMz9Gn79NTJfO8zcjdfybO9G5nsr0PZvwhypwtxXQbK3HGOPi8SeCzH6ziW+91wi+9bhHShmsbeKQM+laB1vISPRw5YKCyAdORh7soj05ZIa2Yxn5C2EPjEIR36gZoGUyR7mE7AohpcpARd5P5lXQISpRjIZQktbK7682lOXvgYAskIa2supiea0oCLbNEY6QVQLocl0OCr0JwkliWzEVJ4jkzoGj99P7GNDLAxchlcy2AMlxPaVou8pJdlVCe0bSXdUofWWEtjrYnF/LovD2QT3uoj2Fa2aRFJG9pSgDVcR2l+JZ28xnoECtJEiOLABvS9XZdElJzAz9nY8HxtSfgKnnrKWbwuKiSTTg9raQGL/GV2tgmUtj+CYmxZWBCDin0oCWvalrVb7EQmsEttSki5zc6mtRAXl6iLDpdjwGOiPw6lvk3j4Q8x+dg9P3nw1j49cwrHeKlLid7WXkt5bTniomDP7cjk5uJ6FoXxi+ysxujeT7LiEZNtbSXRcjtazmUi/i+DQm4kOvgm616vk5cz+K1n8zCippx8EM6T632OkCMQzhGPidwhARAoY6EkfYdOrVl5XczKvtgH+gvP+tgBRkQp7PT+pwzkbrX0+QJKamhldqVgjjBlcsObXTcv6GsfxPPYFTt3ejm/gbZh9WzD7iwkN5OIbyEbrc5HsLoH2ckWJnlIFioXhXIReKUCMgVJCnYUsteYQ6HRhDFVhjm9BG97AQn8R0ZveQuTO64l/aQR+/jmYewIkiGAzpRIEUhKehFjcJBo3iCY04qZGAs2eBURmApGAhQWI/8mtU8Yhgb9oKkM4lSSc0YgisSUfCRaAU8AxQDTcb0g8803+8O338+Rd7cr8MnsvJdS3nfl+GW5bxtxgEYGhIuJD5eji8HdvJdJzGYHeS/AObMSzz4V3+M1E972BVOMboK8cfeRijo69g2c/PUbm2YfU9EwChlQiSTQSJ67ZdXWyTHVGpuQOqxls/r5LTQQgCiRnnS0l1VZoEGEGNQuGWndcJK3M0O6B6DzEjhH41Sc59slWZgcuJdWzFfZUoHVmsbh3HeEDLqKDOaR686FD7GY3qT3FRAfceIfcLO13E9orf6+OIgOl+PaUEeqtwOgpJdNdCj3lsHczxtTb8PzLTvj5p+H4g5A4LXljtU6JP5ViMawzGwgRNDQFCN1MIsuzyfuKNWGaGSsq5xTwKfPCWbZM5hqWBXGseiWnGVe3XVn45wRJ4qRFi2WiJNJBYkkfkZRHMWWcKBphvJlFwv6nmP/mR/D+6xBnRq9lrutSol2byfRvxezfRKyvAt9gBYv7y5gbKWVuxM3ScD6+/XmE9uUR788j05YNXW6SQ5vxT17Oczdew4l79pF54n5IzEBKSoV04ppOMmXlwtIk1eJ7ii9e5TDW316DOAARBWIXLQqTiGRVklJpFjHD7BIEWedCZicJncH87bd47Jb3MDu+lVTfRugsJ9GWh6f9As4MrcN/MJ/ovrWk+9ZCVxZ05ZDszVcACQ6KJikj8goBstTlVgDR+qvQ+jajD10Od7TC9z8Kz8oquIvq2WViackfz6QzLKUFKhLUzBCKB4kmIyQyoiXOJkOV7y02j+NbSORGrbEh64s4AJGrnHVWpSkdLfyXbOXiGbWIj5irTjLOWqJN1i6MabJMnMwSLzPoy8TYsGgmmU0nmFeGWIq0/wQceRi+fQ/6HYOE915NqGWLKtgUcza4rxDvcBaLYxewNHoBvuF1BPflERkoUwCS+jTJvxgD5SQnt7M0spWjo5exdO8gPHW/NfF2Okg6k0A3TeIpazHSjCwrZ8gqodY7v1r//u0B4jDACwCiwCHS1JnNXCIYRggML/hP4v31jzh272HmhreSEQ3R6YIOF+E9LuYHCzgxms2Z4QuI71sD/edC77nQvwZtMJfwYAnC0JIs1KSj9hatirS9LpjcgD5UxPzQJvx3NsGDn4b5p8CIKZQLvrUURAzQhcdVT6ZVLZKmiZ0vDJ5W852bmRSptEhHK/n5ohpBhIhNZ5ljZSO+jH2ZyC0WISMr28rAfclkv4gfGE0k8IdlASA7ky2HxSGyFLAEl0j5yAI8+RDpL91B+OYmYvsvJj3ottp+4J/IDP4TqcE3EB9cp9o6vHeTigDOdJYQGChH31tKRLL2XbkEhysJvO89nP54Jzz9HYgdVwBWII2nSciO4DlqC5BXCx0yu7u8qwVCJyehQgbqO8dRtjpVDnT8BZHo9okrStXVdV7498t+eOlgub5M/iYmlTT+HERmQJ8Bz+8JPvh5fvPhcZ44cAPcciUMCkByoN+NNlLG3LCL40NZzA+vUwDJDJyLUHLvGqL7cgnvKyLeV0Wytwqjv4j4gMvqtMESooNFimKDLrS9BcQHLBIQRQdLCA+WEdpnkX9ISr3LiN1VAz+5C+Z+CvE5VWQnTq/Id6nkliWRRQEobSDOpvRwRhxhXUlwicwlUjpGUkNPxRFzSyI5MuRLcmEOOf3hbJf7ZYXHptruL/1bhI+Ej6XUPGaQihsqfK4nU8iiQ/KEihclepZIk1RIF7SnIJqBeFqZPoYCV8oSCoFZePS7ZD49RnjyCuJ788kMnAf9b1JgSQ2st9p7oJLA3q3M79uOZ/92fH3l+NrWo7WdR2ZvLsbERmYPvgX/v43CyR9BJqiESzSWsCbhcBpFAdriWcWTTjvL1uFRtSti56yGtnj+zzPnOdIIEuZLRHzWRMpGkIweJRQHX8Jad0KTq0lvSLw9IYVkMjm0tVCNDGlVK4DZW8GQREaU8ycxBzt8n5Sl+WxGERvbuaSEcWUFc7VMmJQTqHU8vJCYA/0EBJ6EmZ/CE1+HH3yI1OeG8XygnpMT7+TkwEai+0tIDuaTHCwkPlRIdL+L0IiL4GghoZF8tOFc4vuzFen7c4kOW8doQyUqY53oySLZl4e+v5zo+EZi4xuIjZYQGxJgZMFQLum9uUT6i1jqK2F+oJyF4U0EDmxn7rZrmPv6nYR++6AFYDH/TA0jFkXTk6TsUv5lIbTcYbYQULkfQ6U6rVUUrVYQplT9smIrESvhCetazvmy1LSMo7BzI85WKjdtyiSd1W1F4NjHiaZQJHMi2ReWrf2gspF7Oc8hW/lbfSQULLNgJERD6giYxPSSY6TfVWjNG4Hjz8ETD+O9o5fZ4Svw7CmFsUoV2ZP2jPesx9hfgXffpfgmrsI79lY8feWkutfAwAUwlEVsbw6nRyvQ75+CpafsnE8aM2pYkb+krpZ6ULP5y4vI/QUrK7MG0lRKP69MPC+/qv1Sf3pzjrycNL6KMZuy4IosmSXrOFg2pyzMIq6gxdEyCCmo1vjLxCIktJgFBFuxpFMmYhsSF3tCA01UtzSmbkkXZxZzZ/bymAf96E+JHvkRoce/jf8XX2PpwXtY+vYdeP79MIEvj3Lqrnrmb78e7/veReCmywkf2kZ0spLoWCmx0SKL4YXpV0H6UCHJvhxM0RLDZUTHNxCcqCI4WkpoqIDI3vUw7ibRn6Wknj6xhfmRbfxh/3ZCH2uFR7+szD1JWjqfRCJBLBZD0zQljZ3vX3wrvWnZ/zJ+XiJVKxnTAYnDoMK4Vu/rloMumeWUQSadIiMqSqSVSB9RVbL5c1slzUTQ2bafLXUdPpNnEZKntLFjD2Kzw+xqQRxL0zjaRiaxFPmZ8SVhdhGO/Abzm59k7uYmTvZvwz9YRmaiBEbzVHLRN1BFYPhyAiOXEhnaBMMlMFkEY9kk+y9Q/ey9/Rq0733YWutEVqtKGKTj0ioy1WzMjmbZAHEALw8u+zZABB4yq7z4U897nxfvmOVvzxEAyMupj7Lzg6QTIaJxHa9usBCPs2RohBMBjKQPM+0V11I9WIogaWbI8BzwDKSPgnEEor+DwOPgeRROPgJP/wh+9Z8gSwR/+cNkPn4Lidsnid/aS+TA9cSm30ls+h1Ep68gOnUZkaltxKY2E5ssJzRWQHgsh/D4WiJj5xMZfxORsf9DZOz/IzL6RqIj2asChwBK2+9SmeDEUBnJkSLi48X4xzewOFbJ4nAxS4NuVQ+VGK2AkQLM0VICt1xF9L4x+O13rYnolJMr89IliMfjpFIpMlK6ncmofadpX3wrjCzhSyHLbBXmdCT4SuZUHa0Uhy3BJR8kmfCMwMoKdr7YViw6iY4JU8jvcm2HrCSb46BLyMAyQZbVuxxonWidZONOvhKRICR5KusJFCdawJRdeXjh4XgKluYxHrqfUx8Z4pnxK5kbLCYxlAWj64n2riXen0+mJ59kr5vwyDYiBy4iPOrC07de8cLMyEV4b3sP/PgOCB612wuloSWJLIsiSTDheRpkBQqsuj4Bk5AVKZRXUzLkxTtm+dtzfAYE4qBpcUjIEgGiQXyoiZ5lXTtZjEXq95NnVHUskT9A6Aj4nwLvf5M59XUyz34W44kPE3zkfSx8e5JTX+jj+CdaOHlXPSduuZaZm65h6dA1BKbeTXT83ehjV5EYfhfsv4K0lB60rrOofS10rCXTfSFmz/kkxLEeW09mYh2pqTUkp8/DOPBm9ANvInbwjcQOnE90NIfYiGt1NOzGGKtSlBgrQRsrwj9RwcJ4BXOj5cwNl+Ef30RkfBOJySrSH7gavvMvajkzlctIWhJbgBGJRBRAlltWBJiYpC/1UWgQ6b1CggtzvZBWMqpjPigT12JKh4dfbCsOdixpoKVSyq8xMk4pqMXcsqSoQUwZuSJd5Vbq/nIxYXKH5L5iItt8L5aHkPxsiWo7BJ0W/8qW5vJ4coK0kyyc+uzPCX39Vv5w8F0cE59utABz34UwKIGUtUqTL+zfyqmxS5gbrWRufwmBqYsIT28jNl1B5K6rMR7+FETFz4OIWPzqGawckWJ4555yXxsBFkAERJJ0PeuHOL+/VBedE08lEScrbUSs9fOiJyzJ/8y34NHPwoN3wPdvg/tvIfXlQ0TvGWPpQwPMvL+ThVvqWRi9FN/wJvwjm/GNbVQMFZjYiH9qE/6pjYQObyZwuArfwUoWD5QyN1nEmYkCTo/msTCUA6NlsK8Y9hXBYBH0F5Lqz1cx8uhArpLy0RE3oVE3ofEiAlPF+KdL8B8sJ3SgVEmaVwKQ1HgF8fEqgpOb8E5swDfhxjPhZmZqA3OTGwlOVOKd3Er0I+3w8/vAd8Raa1ySe7bzqurCEgkr4ma3tmiUaFTc9D/zkU50ACGdqrhcfAMxfSSDbPsJDvfLMSIsbV9PggGJjJVDEfloaRFHq5hKeyjZmZHsQep5f8tKHWFSyh6I2KFcuc3zJPELASIxhhf4RkozpXTSMlow4YOMU0Wlq+XvTPFX0mIO+sHzFNGHP8cfPt7PsQNXkh7Khv1vhulcMjeWEzq4lYWJS5mfuBzPgSuUsIrfUoV5sBD/SCGhuxvgN99S682L5SPPIs8szaIwYfu/0qwWCXjEz3PIEir2j3+mc+Ac9VKiNdIRCBwn9N9f59i9+znz/muIve8KEoc2Yx7YTHzqEiITbyE49jb8I1cSGroMfe8WGK6CoVIYKoEhqTsqJL0vj8S+XLShLEJDa/HvX4t/bC2+qfV4D67Hd2M2gZtzid5UQGK8EEaKyIyWYI6VKDMmNVZOcqxSRTK00SoiYxsJj2wiNLoF/8hWvCNb8I5sVcCMjJagjbpXTfGxMiLj5XgnqlicLMc/6cY37cJ7eAPew1uZP7Ad874BePJ7EJoDQypKlz0Ba3KOdFqZVIq3bPPKMbNeqgfOduJyb2LNdCdOthTnOSTOtQUMcYSFKcR6ERNHysPjCYmAxe0QsZSKOBGbF9864WQtIwCxAjGOLyq3UcyzUhLb9xZQOiFm59klEKFAmohjGCFMQxYp8trl60FSpoDFHs8hyU0zCAkv0T/8kvl/uw3/eBXpobXo0wXoN1eg37gR7/gmTo9eyszEJSyNFhCbyiE5uZ7wcA7+qYuJfX4M89nHl4fjOs8ijynkyBILOKI1rECI1WK2KeYIJTn5JT7npPynSIdnIBmA8Ck8D3+e37x/J8+OFmMeLoDRN8LIG0mOZhMdLyI0uYHQpER7yjAmpPAvm8DeLCKDOWj78zFGXSQnXKQni8hMuUmM5dqUTWIsG2M0i8ToOoyRtcRG1xM56CZ4qJjAwRKC08X4J4vwjxcTGCkjMFKhIkcS3ZDx0+GBzeiD2zGGLiO1/0qSIxersG5srJDVUGSsSDnkgZES/KMFeMfy8EwXEjjsJnmzm+htF6F9dRKe+xnEJaMLft3qbmlXMyVh2hSmaSpSOZuXaOwX/mR1rGPDixx27CdhfWdfutkyfWTPAYcDEHVN5b+IDyN5ColWSeTKIJOMk9AiJPUoqXjMmjBBQrLyezqpQC3Xs3wJxyKRu8i9rXs6v8tWgUcBR7SaDV47IJYwIW5CTGaXkSy8MsAkT7IEyNqQHtLxBTJSjStMLNp39jm0f59Ev+sqZqc3sTRRijblUn6nRK/OjJah7V9LYug8jLE8olOleCY3MHvr1cS+eYe1arDSThaopT3l6eV9HLJmQHkBQBzwy/bPAURlZePyItKwUcK/e4AnPtzOsclyuNUF+/8X7P9/SIydS2wyj/DBUsKHK4gfLiFxuJTgeAH+cReBCTehCTeRiSKi4y70CTfx8UIFltR4AamxfMyRPFJDOST3ZZMaXI+2fz3esRwWpnJZmipQzOmbLiI4XUJ0qhxtagPahPgIm0iObiY1shVz+CIYvkRRemSbKgpcDTjknPC4G+9IMZ4RFwHJ8I5egH86i9BNbqLv38T83deC/7dqzUDhKbF5fRlL4lpdIZ2dUqaVOOcrASKgEd/kpT/SQ1bnOSsvWdEWcTytDLbjBJ/VWfYKthkJKftAPw3h58D3NMz9Fk78itQfHiH++x8TfeKHJJ9+CPOZn6rv1e/+oxA7AfHTYMxb0UUpo3cYXkwhO6sugBVj7awTLuFKu6hSwsiqzN72n+xKY9FEEviRtXZ1Ff4JQnqRdPy0BZC0rFNoB4bk9aNPwX99kOMf2MGxye0EDlWg31RM+MZStEMu0vvXwPCFpCbdyg9ZHC9jZnIz0Q/VkfrG+6wlLdSzW0EOAbGAYzmqpt7BgYsEQ+zkohz4lwBE5a1slS0Pju7H+8h9PHf7e5mfKCA2/Ab0oX8iPHIBwSkXnuly5ibK8E+Xod20geBUGcGpCkWhyQqEIpNliqITJQjFbNLHixGSaJFFbvSJfPTJvGWKT+SzTOOFygQTMywxJtrITVJotFiR/C1AjE0Wroqik26lrbxKjWeRPHgh8Yl/JvIvJfDgYdCetMpaZGJ4ex1ykaSW0HEkvLTyS38EPLpujWER08v5SA4jri2RSPqUByDgEEhJ5wqjiQcTjmtkpP5MCjNTpyH0Gzj2Tfjlx0g/cCOBTzQS/WgN4bt34L/rOjwfeA/zt13F7C3v4Mwtb+fY9GWcOHwFc7e+E9+d16J9tJbUZ3bDfR3w5X2qnJ2nH4KFp60aNwmjSoLWtH3S9JI1mMk4qRK1GVl70IgSNNJEpTRAluU1ksrmk5GAQUAMLClVl9IaaTe1aKdjZknEzp6pRDGoVEZEn4Hf34/vi8OceP+78N6yidShtaT2/2+Sg2/CHF5HeiKPuPieN27Ff+M2jOkNykcJf+cTVhY/EcaMSvGqNf3TYjyCpoSM5YNYsEla95YucwDidMaf2J4jLyDk5DvEZDCO/YLFL45wfHoL4YlczIn1JCfy0cZF/ZUpM0tCsGJmCRhCU2VEJmxgONtlkJQRnRCywLJyG5sQoLjPgmA8n4RNFkjyiE+cBY/Yos+jyTxik/kvCQ5R2S9F/uFcQuM5hCbWEphah3nXBnigD05/H+ILymwRwSFttBwOtxX4yymWE5CIMy+RLdEulo8i/kJSMVw4GkI3pHpXACg9KEwXAP8JMid+jv6rL+K7/zBzn2rm1O3v5PTN21g4UI55axXcVAaHy0kdLCI5VUR8sgB9rIDYmGSkXepv0ebaeN7y97GRPPxjpfhueQ/zd7TgvWeU2P13wi++Bsd/CsGnWewSOQAAIABJREFUrahl4jikjoM5Axlh+6gan+PLZPALMGI6BMOkQgaiMB1eEpDMZ2TuEqvd5L2U1lUmoJPIdELWsrLvKTVoau7rh/j9wUtYGvg/MPZPcFMuifG1aENr0MfzCB3cRHi6HCZySB7exKm7u+Hx74MmGnEJUrIMuEwimCaUljCEFbZQ7SlWkoDT0RxnZdWfgAeoRKG8lLyIkPrI6Lxf3Mfs+68ndnAzTBXDaCEM5sCgC0bKYX8pZl8+KQmPThYRn7C22qSzLVLfy29/mkrQJsrRJiptKle5j9hkKdHpEsIHilRFbuigi9DBAgKH8vEfzrUpm8ChXGLTBS8JgJcChzBScjKb6NhavBPZ+O66nPSDN8HSTyB5gozhU1BQhpI0pmpQm3ntBJ/V2k7D/fFWolkCCgGIbJ19OVKYRq4dk7XSRTWpS8cgeAaO/hfmw/eyeO8w3o8147ntXSxOb2RJqgRGckiM55GeyleCy5i0BIs+nqtsdW0sh/hoLrLlcCncWAIHizEPujGnXDjHByeLmb3xLZw4fCUz0xfhnd6Cfsul8OHr4EsD8K33wZmfQeiYmi5GTC0pwg8SJYIMWJIKWystYbstjnqVOfsIJayRJSJYxMhRIJE2VOZZ1Brbk05jZsScFDEUJn3mlyx8dRrPwU1oI2tI35hN4uA64pNr0cfFhy0iNV4E09nKxD86fSVz98mIxAdAgVnK8wXESfyGGHp2vylgiI8mZDvqf9xdf/TNOVa1pl37lcpYGVnJpi88hv6Nmwh94N1KnaWH1sPgBTAsodkC2F+golWm+Bc2JScKEDImz5IwoZA2ZZEw9DJNFdmAqLSy41PlyvcIT5cSXgGQ8IECwgfzCR3KJXQo26b1hA9m/1mA6NNu/hQZ0wVwcxHBiRw8H3gLPHirFeJOLZJJBkiZcdWxwruKeUX6qQiRdKZjqyvD9I8a1vlC8iOiORz/RLYCFkVSniP952BOxpk/8wsSD3wC/z19LP3L1fimNiFCJzNZCFP5MJUH03lwoAAOFpAczyE+kWMx/VQeyelCktP5pA64SB0oIDFVsPy3hErTh4rIHHYr0Ji3lBG4uRLfjeVEDxRgjGeTHlkLYtIe2IL/pqsI3TuM/zsfRzvykLUwJ34y+EixoMaLCOOr9hHGl3yORN5kdsSkTsaQ3IP1+/OOU+UqkuiU8K+pJsEU40hpaIl0Lf0GfvAvRD70LuZG1pO8OZ/MbRXKWtCGs2HKBYfEesjDe/PFPHvL1YTvPwCen4J5EtIe9ERImaeqH6R9paHl+eTeapIQK8Ln9NOf2p6jXkYShAkdMx5VJM46yVk48QCeL/Vx5raLmBk+j8jUGzBvXoN2+Hy8h9YSuTGflHTYuE0TeTCRp+xFczJP/SYdJIwoYTztQAGxgxZFDhUgFDvgPksHC9EOCBWgH8jDmM4jMZ1DaipLkTm1HqH01FpF5lSWurZ1jnPu87f6QRcvRfFDbvzvu4zQNw/D4qNKikXSCbwJqYsS7rWljlOEqVryLwfICxteTCtHm6hybcl1BL2YR39J8PufZunTQyze9l6CUxswhBluzIcDa2HiPBg9F/avIbN/HYmRXKUlBBzxqWzVVsmDeaQOFZK+sZDMTUVkbnKp743pHLWV4+JTuep4fVLOuwB97P8lMfW/SRw4n8RNBRg3V2Hcsp34TZeh3XQ5wUOXMX/wck697z0sfWEvyUfvBd8vgTNqftyQDNu1eU/5LhLmjS9ZVdcyMExK9O2aNAGSEgiqUSypEIj6kJiXaFJxaSxTSIYzHIHffZngnVeRvHUzocMb8U4XEz6YS+qmfNKHRBMWwPu3MH9oI8++/53Ef/JBMJ6EzDwyGjMptWdyTUGpyDYFEvlHqgYkAGFVD7ywj1b+fQ4pAYc4ZGEy8TAyDkBFtERCmrPEfvkZTt1Ty7ED2YRuPI/UbRcQuvHNzNy4Dv9tJYqRxYESElA4JMBJKHo+QFaCRMAifys6mId2MG8ZGNKpFjhyMCdzSCvKgoksGLdIvhPwvRRA/n/e3gO6ruu689b62swksS1ZYhFI9F4JgBSpFpdxquM4TuI4zngmseOZzKRMkkkmK7YlkUTvAEH0QoIA2FQs23KXYjuO4xa5SLIkq8vsRH29l9+3/vvcB0KyLUfkzGCtg/vKfe/du/f+73b22UcA+GlD2biLLXcQvffvXNOAxJLNtCrQlEYT482tMq2z4T14BJZ2FISMq5tp+hMfK+4QMF7xlwzAc18i8+URLs7+Oc93/ibnD9yB/0CTaX8+tgP+7kb4nze4499tJfP3BaQ+VkHi7hpi+2sJfqyUwN2FBO8uIbS/mMiBcqItZUQPVhBrLScukLRVEGuptOc65t6PHyyEljeTPfgm4i03E2wpZf1gLWsHGlm/R9a8nszBRuJ3KdOnJQT1vNT5qyyf+Esy/zIHF75pzTKcKlHZiwJ8zXOsQUxLE/TcZZfMs/KsiYDiwJIhkgkSS0eJe3OiTq8nHG3TF+HRY8RnPsgLd+3j/D2NRLtqibeVEd9fDa31cLDMUvLP3r2Lp0beR+KJU5A556JGscbhwf2gQKLrsdIUxSeql35t/l1nlWWZhMuZJxLmOMjUKS4x5q/8kMgX+swFibdUQlsJyXuKWLm7hrXWZvwHawgdrLQROVCJRnT/lRG7pwo3aoypYuyVUUXi7ioS98ikv2rodRubz68jcXcdybvcMCG5p+Y1LUT8YA0/bSy338nlEx+DJ78IMZXSLBGO+S17pOktBZqiw4YLYb6ry17JZ47napdeIfU//kRxh4oXFY/oT2BZWVkh9NSXiB95L/RWE7pnB/67dhBuKSPRXUeso45AazXLd5Wwur+SYGsdkY5dxDp2EWmrJXSgytzOtf1lFospPlNMpqPvYBm+gxV2zL2v5/6WcgKtVQTbKgm11xDqrGWltYLltjKbvF1rKcR/sIDAgZ2EDuwkcqCQ5b/dRuxAFfTshZ7biO/fbe5w4uBt+A69h8Sj04TOPALhZ7117EpbuwIAzY3YxKJueqOCO7cAK2OrK6XJ1YQhHlGdX2xjnkeTj6aok0skHr2XlZkPstZ1p5tMPFhF9GA1mdZy+Nib4WAeq+31fL/jLTx2/G8Jq/5PYLVCtE0+3gZABA7FKWGviu3HeZZ75Tp/yN1QOu1KTsRCmbt1FeXqiUozH/88q0f+C6udd5Bsryd9sIrwXXVu7uNgDb7WSnwtVfhaagwwAk3wYJUxUYCJSfhfIfB1JO5qMGF/NUB07mZQRQWAe2Sp6ojsbyB6T8OmY50BUlozdLDcgdPOd6DRb4dbq4m0ViNwJw6WE28pJ9xaZ77rM92/R+Kxh12aUKXqcR/B0DqBVNqyesvqGu/R44olcbZapDFxlzR4SsjccM+i67H9STCSKbLWmCFmWRbOP84LDx/l8dEPsL5/O9x1HRz4t2Rb30yybQfR9lLCHbUEOxpZ72hmtXMPa+1NJgTrrVWst5ThaynCBLqjkvWOatbaq/C1ubHeVk5uBDqr0PB3VNr7662VaKy1CBiVnG2t5XxHLcudVQS7y4h17iTevo1YyxYi+7eSaCsmcHc+vr8vspQ8B13GjL8vx/+3pTx5cB/Pz3+I0LcnYPnrNuchDS3ayL5KX28EyoYT5ZVkc1RZmySuiT4VXmqZg601d+ltNbSOJNLus5EL8J1jrE7+By7cs4fQQSmJeoKysAe2kr3rBuhvYqnnTr7R8hYufL7TpY7Da+4idCGObRvunmZpsqb+XmXVc3zzjtcJDLoZVw9qmXd3aznG68sTARKPf5zHR97PSx23EOtugP0lcFcByZYqp9F0we27CHgj2F5PpK3GzHuypYy0xsEKktLoLbtsDiXS2kS8tda5AXIFNkYN8dYfH5pA0vkbx7Yqou3FRDoKCXYWE2qvInGwieSBZvt8qKOCpdZSIr01JNuLyLTuINmxgzP3lPPs4T8h/O0vuDb7tt5bvrKIdWXWWs82GGwEExLcMACozGI15NJQXgmIKKg158FU0vbCSMdyRVspiKzC9+7n8tQfcv5gFYGOmwn2bCXYcxOhru1EOgWOYosFRKf0gVrSB+pJHqwl0eJoGekoJtSZT7B7B76efNa7K1jvqmG9qwrfxqgg0PmTxuZzquwzq91VrHZX4OsuJdhVSLRjB4n2PJLteaTbdpBsyzeQyE1ztN9FtKXZSkKiLU1mXaQYz/XcwYXjf0zyiaOQesqcVFkE0UmeZUpC5imSZEa9zlQR7pSznaS5l2zcQCWrLbmU6Pm1nkWPkkvw1KcIHvvPLB/cQ/hgLQw1EW8vhJ5yaKm1xESwpZhLfXtIffEeiDwJkRDZtRgRrb7wem35jLFayeb3MiSvQsWmp7ZgShdyBSBrriGARfwuKWGB1vJTXPiHQzw19E4utdVDWxns30HmYKkJtsy+QCGA+Dp2EeioNYGNtpcZgdMtpQgoidYqoq31hFqbCbU1GbiiEvSrGe1lRDrzCXXtINBVTLCjinjLKwHi76/h/P6bCR7YQranEH9bHi9338rlz47DyiWX1dhEkNf1UAwPu10qxcdg0jWyE4OV4wqq4Zssh+q3tCXyN+9nfeqP8Xc2Q+cW6L/BgLHeU4yvu5hgZymR9jKibRUOJC1VZq1NsYh2baXEPYUQ6nRKQdbB11lLoKPGhmggxaDvsdFRahZJVkm8yA29F+oo2wBSsLOMiM7tKCTRnm/AEDiSbYXud9sqTOFJCfram1lv32v8o10ZpUJz5852N/PS7Hu4/PB+ki9/BmIvuSJFT6/YOvtE1lZPJtTAIhs0bFyxzq4qV+DQkECvqdOKiCsARV6C7x8jevQPWWm5Bd+BagLt5QQPFpFRVq+1Cva/mfWPXk94+l3wvWMQugShhLUz1QLnFa30FGpl1mJa3++h9qcwfsOC2Ps2kSJz57Wdt2rVlNXykF6Di9/g/MJf8lLb7SQ6a6GlwPLUsg7S/rIYwXYxS2C5ApB4WymJVoHDnScLIOsRad1FtK3m6sBh1qPMNJ40b7CjglC7rEu95celcQW61FA9F+/eynrrVoLdJbzcUs3K/B/Dy/9sltHSfj+FOP+ql0XfpDCgYj0tNHMzuaYBVfekVObqM2T+aZqzh3+f8wf3EO+phwFljPJItlQ469DqrlfCHegsM42+3l1qR1+XE2RZSCmieIvucZdZy2irrPEuu29peN23rLpAJeXFwWJQMH5AI3/T2GHvyVLLXdH3ihfio7JZOX4Zz9pUSLiZv/WeEqwnoc8drLCM5lJrOc8dqOCp7lu5cOrPiH57DvzPeVbatTbS3jnmlJAgquSQVUCahnbk1ky7uWAu/ltVWbspa7li6mTztLlbvpk/4kd3NxHpamTlYzutRCjTWQWtO4jdvZPVrn28NPZBOPeoldEIDz6to1e1SQ4gWuJqrsBP5/R1uhxZHPsTsy01JofNXWhErT9jEYfg+EUyXz/GhfEPsNzZRORgMdnWEmgpIdVWRqK9nGhHtfnPCgDDHdVEOyqJdZSTaK90o63aiBpra8BGey2x9uqrGx3l5jPHOguIttdZABdrq7PvT7bWWnYj2V1JrLcUf28BL7SW8MLgu+BbRyH2sosHbG4jR4DXd8zRWRv4JBPSd45msWQIdX20tjzrPyTw5RFeGHgnZ/dXE+2uhqF6/N3VXPhoIamWBrIHGu1owtZRTaizEn93OWu9Zaz1lrPWU4m/q5ZgZwOh9mairbegIDlxcB+Jlt0kWptJtjSSbGkg1VJHVu6H5joOVMKBcpsz4ECJc4v3F4GNAns9c7Bh4zs2f0/C6FhHzPhT6/FVvNX1uRHsrMXfXkegrY5Ie4XxOXCwiMsHyjjXfRsvj70P/5cOk9I2bEnFGBmLm0MpBeqebHoAkQCbrFrHlpAp+JxLJKoaLa29rEpTnod/WWB56kOsdr2V1YNVrHeWEuoqIbq/kExbPdGefTyx/y2saf1I+Ix9uRZ+ZjX772UlfxY49LPXuWpHl4qzqzKnW0hxacxQJkI8mySrzmJqjLz8FMmHB3l54Je4IC0lgBwsgBb5+CUeSCoJd3pDgOmsNALHBBIDiKuWzT2+FoAkOneS6Cgi1tpMrHU3UWNoJQJIpqXatEl2oJKLPSU83Xcrvi8M2T2QuAgpr0jz9eFi42wx1NyBTMra0rhIUAyIeKnOF7n8xT7OzPwel9oriXfsINtdQLgtn4utNSx37SHc3kiitYGcQG4+CuzR9gbCNhoJdjTj79iNr/MWfB37CLbfYvctcCRa3RBIHFAcWDIH67DRUmvAEXjcqCZ7sI7sgWYyB1T7tM+GyjcSLfre3UTbmu367Pc7aj2elhPtLCPaWUKoqxxfbyPB3iYHkLt3krpru1ksxSyXWhv5Yfcvc+nBj8JLD7vFd7h17FpLY4pZRPQeO4B4JfGeJZa7agAhSSq86rqvyN3yPQ/fu48LYx/kcvcdrPcXEuzdYUWvvv3NZHpvY7XvLTx39I9IvPAZNx8jFNr+h2tuojYHyg2O/viD61wkL6Z6pkRXrce6IOKEslpxBiGVsvojbrHQi1/iwvE/4+Xe20mq4rc1H1oLoa2YdHspSdPsFUS6qgh31diIdNYQ66wh3lFFsqOCdJsb+ny8Q69fxeisINlZaL+Xat1NsnUPkc46Yp1VpNrqoKXGViKGW4t5oaeWix//b7CkAsSwt1xWMx6yllf3J3qHbLbdBfZJdSuRo61KhMuPE/nnKX44/C6WDu0h1qfrvJHowZsIthbh67mF4ODb8HfvJty5y1K48fZ6Um31ZFtUHqIcvzumW3eRbNM5TQS6drPevZvVnj2s9zQR76izCcF0Ww2p9hq772R7nWUb9X3x9l02Yu1NvHok25rg4G44sAe07ufgXlIttxJvvZVI+62EO/YS7thDuLOJcFed8TPWVU68q5h4Vz6R7mJLgvh76o23sbsLSH30ZtifDy3FxPYXs9JWw/Pdt/PywodJPn7CGuhp8ZTcHO2zmrMcOtqfqollRWwSz4FDHR8jiaRrqCehlnyqgjd+iew3Frk4+X6ebdnGxfYtpjwCrXeQ6GgmPngrz/btZfWLH4Nz33OVy+qpFl8hop3Jchm23G//hON1Lpz0lkjqKjWsVMXlq0PeSjMtLU5Z0VAYwi8T+5djnJn9AKHOJmgthjYBpJBsezGpjmLineVEuioIddcQ6qqzISJLeAUgAcmBqcJe0+uvd8QNIKWk2itwQtREpLPeQCIhsaCtQynREi7M/hbZpxe9+EqqX9ZDSdxrAYgaFsQ2Mi7GOJWOX36O5FcmuDj2XlZ7dxEfLCbRl0eo4yYC7fnE+htI9N9GsGsfa917We/eY3TUHEe6VcBW4FvhuUflcLAcWitMGYmGEkh9r7+nhnRHPrRth/Y8aN9JuqNwE/2dggp0y6XbZUOg0ljrabLfNDAeEBh3kVWCo203sfY9BoxQp65rt513BSClxLsKSXXuJNmVz/KBbfjaipECTHU0uMLJllrMpTuQB4MV+A7czPP7izk/9154TIHzC+ojxLpfcyE5C5GTfEmpBND8IZsLUTtWvysYNqsTVY1XDlnhs6S+Ps6PRu/kTEcJgf47ifW9zVnezkp8PWVcPHwnwS90w+XHbFWj1qRoN6t/JUAkIF6K0wq6nN3R78tPVMQvXzDnM2ZDPrde/fJ3OHf/3Sz33EmqvYp0e7mBQwBJdxSTVEamq9wAEuiuQ0wSUGRVBJBsuwOTgPR6gbH5fFkk+31p0LY608ahrl2mWdNtVXCokXDvHmKf/xisP+Z8YNMUihY1HbgRgf0E/fHaL4lGIrI/rZy+Z3mjQVJfe4DlsT9iuaWRbG859OWRHMonNlxOeKCBgK6vvYlE5257LOENdeWArRKRGgeSlgpXaqJyk7ZSUh2lxEXX7lJCPToWQsdWaL8B2m+0x9mOPBNeaXk7r7uCQE+VgUmA2jzCXVVk25QidQAUvaRYBFRZDSm/QJfGrldYkGRnManOfJJdO8kOlRnoV/aXEm5vJttzJ3TeCm210FHkZeu2kurbwaWeal6eei/+r4zD0nPWTUV0Ew0tHthoLqHn8mpUzRG1OrbcBIR6GKtNlarP7XNKKCWeg0eHeHn4VzjX2kS4u5FYdx3J7nIYKuXiR29ibeJd8Ox9toZGa22UZRQ4za17DTZfl7swd3ruY1dWk+kiNPRlTpSEbK+kIPoMkfkP4ZPpb62GgXrSncpW7STdXUqsq5RQdxUCiLSejuHuCmNytiMfjVhHGeHO8qsaSgCkuhqtvit2oIB0Z4XNxay1NhLurCfZowRAJckj74FnPmlBuXzai+pkbskI3ZX5k69Bop/+lughJ031SM56aFL1q5wb/nNSg78BPU3QkU+m62bCfSWs99ey3ttMuKuZTFsDaNXigTxC7TuMVom+GpJ9TcS7mwm2NrC+v8YeJ7oaSHdVkeosJNN+M5n2G8h0/Dy0/zy03QBtN5Jpu4lMxzZSHZrr2WlaPiZXqLuEaGcR4bYdBFu2ET6wlcjBrTYRmGrdBl159p2a95C7muqrRNcR7Kpktb3ceGZ866rZcLGk/OQl6PxYdz7hnmIDeKBzL+H2O4m13UpaZSDyKto10/3/km7/OeL9hVzuv4VzY79H5stjth+I5E9S5/jgLIr60qXkQtkut5I397oBwnNyVAakoaJEsqrdet7iy5WhO4n3lZEarLbro7MADlWS6Skhcuo/WlcU/d6lgN+aWPxsgEg+7Cx9TDiVCLl8tK039laKCekK6LM57Cn1pqzCPw4RmX4vSwoauxtJ99aQ6Sol011MqrfMABHoqWG9VyCpI9RdgRgn10Aj1lFyVeAwUHVUk+7Za5mWRPsO0t3FRLt3E+y5lWDfLgK9Daz17IaH/hYuPm7VnBJoFUSL2BllM67hT59e9poMWhXrxSfJPjRIeOB3Sbfshu46aC8i0V1CoK+a9b4GfL3NRDsbnYZtKyPdmUei52biPQWEZRm6a1jvrGe5vZHLrY3Ehn+RcP8tbib8wA4C+28k1no9dL8RBncQ6akk0NNowbK/bzf+3lvw9d1CoG8vgf49BHsaCPfUkuiuId1dTqazyEBLWx60bSF04I1Eu24i2b+D1EAB0d4CAp078XUU4tOkZLfc5Arjo1zmWKcUXLl5AbJmod5iAr0CUj0BuWQdil/2uoqL9lLo2k6m5Q2k2n+BdO92/B2lXGrfRWL29+Gro1bek0jEyCTlp7j2RLYNQyJFRk0Kvepbiagstv501NmSVFecouW/wIUfwmf/gtWeUtZbtsOhCtBE4oGtZFpuIDhxJ0vfOkI4eMHm8TW/8rMBol8zJSqAyCf3AiRVYOY60lg1pkCTm573Yhah/OI34B86OT/8W5xr20usrxH6q8n2FMFgGdGeMoK9lfj6am3ocbSnhHRXgQ1ZGRH+qob83r59pHoarYgy3p1Hoq+ZyNAd+AaaOdfTxNLEb9rkkm1Kk4b1jNv5QgBJZLwNQD3Cv96DeLLkbZlH/DzZR4aJDP0WdN9maxfoqUPaP6R4oW+XgTba00CyS8CpIdtZSaq/iPhgAdGBIhM2X5c3M97TZMK+2r3bQO6XsA80ERxsIDBYjb+vlIt9jVw++iHOHP0fNs4e+2vOzf01F4/9FctH/4K1o39CYOYPCYz9Dv6+X8anyb2DSgTUgaohhhoI9exgvXc7Po2ePAI9eYR68wn3FRDtKzZeiYcacVn/rkobic5qIt3VxtP1vnoCvfVEuutJdNaT6qgl1VlNQuf2VeDvyDfQxfpLCHcVsX73zcRbS4iOvxOe/gSsv+S2V1PK3eaO0taFUzsebHg43ky7BFp013DuWYqQukSav5uBHz3I+vHfZFUKoDMP5NJ/JI9Y+82sDNTy4vT7SDz9oMm5Xw2wfwbTr7MzDEa6misWxC5MwNmwMLn3BZKUazOpb9e65pcfZuXev+OZjrey0tVEqq+ajPzjoRLiPUWEe8vw9TliCiCRnjJS3QU24t1lRLsrr2pEumuJ9ewhOdBMrCePcOcW4v01RIf3cXloN88PvoXApz8CF9R0IYlaNkW9mEoaKPKvXzfzE8mo2zf3QAHlS//A2ux/InigzhV03pVHtqeGUE+TaXRpdwEl0V1FuqvSwKGj6p/8A+VEhmoID1YT7K8k0FdBeLCO8OEm/MO3sHJoHxcHbuPs0Nu5OPluAif/mNRn/ob0l/tg+XFYfdEbL8CqxnOw8jQsfx9e/BI8fi98aZDU6f9JaPwD+Pp/g/WOt7PWuY+zHRWc7ytldagS36EKAkNlhAdLLLGQGiol0V3gjRLEK4HE8auacHc9a32NrPU3EOytJdpdQaqrhHRnCQkpvZ5KQkNNLHXXsNRZRWigllRfubl0tLyJTF8Nl+Y/TPrpT0HqsqvgCF22tqZG282pYC3BSIdMLC3es5WCScLErIe1lbLY9N2L8MMp0vO/xtpHt0KPJlQriQ/UstZfy/nOBlKf/4htnaFCSc86/ET+6kUvBtFD11XDlZyYSXHoNYBonkSi4LLSKhE25Jnd0z5350k9usjzY3/AGWVAuivIdBdAXz7JXmmiUoL9VajsQ8dIXzmJ3kKSPYXEesuJyqpczeipMdMeHdxFsDuP9Y43E+0vwD9UxdnhvTw/+3vw9AMQPKPmUWSEDrOGyj5lbYbW7uOnkudnveFlW8IvEvxcK0tDbzd3KttyI3Tnk+gpJ9DfjG/AuTvR3l0ke6vMH870FhHvreJSSx3LvXsJDu4lNCRNXMx69834+rfhGypgbayWlZk7WT/1BwQ/9zGS356H5/4Zln8EIc0uez6HbmTzkIq1Xsra3FPNHc65FPczD8PXjhH+ZA/rp/6Wx9ru4OXBO1mbejuh6bcQOiw3rdw0vcAhPmZ6dprCS/YUb/BL9W3BvgazjP7+BuOfeJru2Umydyex3mLjdXBkn9VGXehsZqWnkWg4+/l8AAAgAElEQVR/FdnefOi5AQYK+VF7E2v3/xU892mIvuB6Msd91g4sF/ua/pYFSav61lkPFxXHrdG3XLJkWP2lBR25Pefg0UGCw2/D39ZoMd/64K2s9zeR6CojPfsr8MRJW1hl2bLXYPN1OQTphzcPez2XSVCmwIYKykT5K2ZOKTerk1n6Lv7PHOTy8C+ZH20A6dlOujfP5gCkGX0DNfgHqgj1a3a7mERvsZngWF8VVzOiskrdtUSG6vF1F+Lr2kp0cAvLvTfzo7HbWfrsRyHwDKgSQK37NVQ5l3VrloNZr1r0NQj0mm8py6LdWZ/7JC9O/h5Lw7eSHa0g1v4GGMoj1ZdPuL/WQKKYINTXbPeZ7Csk1b/d/P611hJLYEQE8v4qVjuLudRZyNJABcvje0k++B/gKx+BZ4+D//uuMZs1lfO692hNkDwMrU60NqNXeCO8RCPy5dWxRn661v6sQfSitwfhN4h8vp31U/+VsyPv5kzf21jpv5XwQJNZg2iLXJSd0J1Htnsn6Z4C45sUnK412F9DpLeOWE+V8TLRt5NY/3aiA3kEB4rxidejt7M2eDuXuvey1NnEuiaQ5V733ES2P8+U6bnOvayc+jN4+XOg5hCJgDU9F0A0TOIsw5rT+HpFHo1iFK2CxeKVVDrrMlsCidrePjrKub63s9631yo/ZMEZqiMy2Ezsof8Boe+49SuvwWRvHkT9ZF13buvMbh/QBag8YNXrqKElkl4DM9PC7hJXVEem89We9NkHSN37QWKDzdBbAN0qENxOoreA4EC5EUxEE1hkVQSSWF/FVYFDgBJAZJUiI40OeAMFxIffyMXuX+D8kXfAD+bNLEuRpiVU2nBFBYQJVUzJiniW8DUI9JpvqT5t7Z9JfPYj/HDoHVwYv43wdA3BwZvIDLwJDm0l3V9gbl9gYB/rg/vwDzUQGSoiPaQg+9+Q7f6/oP/nYXArkd4iVnsaWBv5VaKn/pLUI0Nw6VFYeR4CWqUXcQrSEw8THGUU1fFEbYDMRVYFhGuCLQ6aK6ljNkMsk7BCwbSWxKpTSuwiBB+3lXvh+z/CxdH3szr4a0SGfpFkT70VKtK5Ezq3G0hkSTThGeovxT9QaYou21WMMkWyHAKGf2gn64cKWD0kt62KwKFmwkP7iA7eRrB3N6tdtaz0VLA2WEZwsNDiVK0/We65lewX7rGl3lK4ygpq2wjZhNwwS2LzI86TMWWtxtsJFc+rQthlu9RoxXVb+RHhz/xPwlNvs0VW9NWTGHkLl/puJTX7a/C9Qbdy9jWY/GMA2VjgYggV0QWQNWclcl3APTdFDFjSmgkz7apYfQ6+0odv8teJDtaS7M0j03ezaVIBISyNMqhjGbF+N+KyJgOVXM0xMlhNeLiO2FgjoUNVxEeKyYy9mbNdN/Hi8T+CpW9btaYW7jjbHCezvmSbZ+bW4hvRN/Vr3WxF7b1cHOatRReznGCKMVqWPI9v+le5MHQna6O3EhirIDqyg0D3z8Ooywzp/oKDjQQGmwgYQIpJHfoFGLoO+q9zQBnaYe9dGn03a/ffBd/9NFx+CdS+VJtYumpw85py+UYrJldvrOQFSC07PuGaiGpBqbSvRElDQMlp5Ki2184kSce1BuYyRF6Ey9+Fby5wee5veLHrnSy330aqvxm6S6Bnh41M3w5iA4UWo4QGHf/oLoLuQpL9+YSH8vENF7J6uIjVw2X4hlx5vWJEhu8ge2gfkcEmUxKrY3VGKwZ2wGCxxSO+sV8n/vVJp2yzKfwh3cUVi3gFIKKAZ02sY13MmtWFBRPNk0QduKx+68JDxD7xYWJDt8LoHQRGf8lcPsYa4BMfgOQLr/BMc/x3nlWK69zPu5jDXUAOTnpNFyEYeBOJVz7t+YLq46Qafq+Vik5dfp7ww/2cHXsHofE6ksMFMFwMh+rJ9lcbIeP9+SQGK0gMVJE4VEnsUOVVHquJDCgoryYyWkh2ugRmKjnbu5tL37qXpLZgyAm4lTXrfpRk8NYh6Fb1unZa8jSVYd1r2qbHJlXm2kZtn75lEq77i0qlg0+yNPMrpMbrjPkM7CEzWGpZqdBgCb7BcvyHqu0Y6S+0ib1wa4mluePDNxDr+39gVtm+Yla6dnFp6vdJf/soqD9yKkTCr7okL7ZQutMrstNLEnaR2/iXm3U2fgm+Wrh65aO5r9h8NF4bcVyhpTbPsS0rLr1A5GunWZn7c1b63krmUJNNtikFnBgoIDZURHyohPShMjhcTXKwjsRgnfEgNFJKcLTERvhwqfE0018HfQ3QI6+ikdSAOzc4Uk5wtIjo0M0k+7ZDbyGx/jpWFn8bnj1mnktOHjPaPiOrqUFHDyW7tMAvpcV8Of6+KkRw9xeG2LPw0oNcuv8veHbg7Vwc3kd4uBr63kx48hYuP3GvWZ71RIalQNqslegkmU/FVgSQq/9TQB+3jSmTLqsl+QtFyTz1CEsP/gXnx24lMFxKWqa0Twvsy8n2FZAa2ElS5d6DHkCGy22WWTPNr2sckqtWTWSwnPj4DtKTO2Gshosjv8nFpx4l4CmZjXy1uR6qLXOiZcLn5dklVnpVR7lfAr1ZCiX2JI3am5tLXLJmz0JT2LJ3genbYLQYBhpNAOgrJSH/e6iapUN1rIzsYn2onFh/Hpkel3ZUGjw+mkf40E0wVE5q8DbiJz4M35kDdT5Mhm22WNfvmOUlAxTzKC70wKzrdYJwdTzUd+s7AllYkfepG9YXqhXt9+8n+sm/4/LAW0iN7iNzuIZY906ivfkWZ6WGS1lu3070UB3hQw2EDlcTGiknNFJCeKSE2HAJqcFyS/nTWwc9DeiYGagmcajczgmNFhAbzSc5tMMSOqn+Utan9xH+yt/C0jddBa8tB9e+NRc9d9/F4bpMgcSuVyDRCxvE0Au6mSiZ6Hnr65V85jTPzP8hL/TfYpk6+m9k7VAVz365i0T2slUeBsIZ2yrFyuGzKbJJ37UCRH58VN2RHCNFcU3uBF+C70xzfvY9LA3X45f57Soi2VNKpr/EtGxSbtZguRHrdYFiM4g8gMgnjo/l20gdqiJ0/EPEL71o/aZMw9iEjoRIvvmrAKL3tDegJyy6BblfapBpANF0rZUFrZJkBbc7t9ImPlLfmMU3uQ9Gi2BAmrIe+svRvfkP1bA8Usf6WL2lT02w+opgaBccbiA6VoJvpIz1Q7eROPmf4bE5iD1j20/okgJagOix2dSkFfFpnY4uxpvI3SwTV4MRTQLr67z14i6DKfdFTRdegDMPE/9cK6Hp9xHpaoYele5UkBwsZKW/gKWhYqLDlabUoodL0ZDl0BBPk0OVBohsfy301ZoHkRrMnV9CdKSAzHgR6ZECkoMlluZeGmnkR3O/SeCbYxBTwzq/xZGZ5IoJbA4I4pOWnOeebxw9OrhmDHGS2hE5ex7ijxH6p27OzvwmlwcaifQVsDJUxeOL7ye7/AVXaRyJWB4jJYUopyiTuVaAgPabCKXFMKFWKk8r6Fbh4jeJfKGFy7O/wuWhSlY6dxLuKSQ9VGNDLlZ8qIzkcAXxw1c5hquI9FZZajQxXkBoZIelSnnkHtsJS6tdnYvi9Y81i/cqgJjr5dYnyJNyNNdzJ4TZHECiasK8ip+EbdiiJg+XH/gYvom9ZEeKwbRlFQxUkRysxne4hpXRWoLTjYQOK41dQLa3FA7vIjVcz9qhCi6O30Lw/j+F7y+4HrWpVeu4KBHVzyp2MJAat+ROKJvo/G9dp4RkQ2leLUD0dfZF+iX9oiaLFXsG3A6za98j85VDBMd/l8TQbWQPNRDpL7YYI3K03uK+9HA+qeFikgLGSBkx8XO4iuShGlLG7yrSQxoVHr/L7DzFjAIH46UWQ64N1bI03MgLg7dx4fR/gR/e56p/CZNKh60DpQXmuHUlWrPuGCYllxvuJUcb9R9Tlx7F0IqzHib7T21cnvkNLvXWszLSzGMje0l8tx2C33W7pwVd11VVIgmA1+hiOQaqeEyz7M5HVDcJBZbL8NKX8D30V1yafSsX+vIJDOSTGd5FZqjBxSCHSkkOlxE/fJXDA4jqnGITBQRGCvGP3Q6PTdtKPtMwopRUssBiluHVAHGvb86USPu4lpVeYki3lnAdyjUxZfe59G1emv0g/pE9pA8JIIUwUAoDNSQ1nzFax/p4DdHZBmLjtbZoS6U3HK61DNDZwTrOzv82PPMA+J51lkPdTuKwnAGVUQokuq5XWJBNbta1AiQHsmgsQcKv5MXKxv7rcl8StlOvD0JPw2NHuXzs/ZzpaSR4uIHUzC0kJ6tJH94OwzeRHd5pdDCFN1xDXMmT4ToDilOApcQPbx5lBqjE4E7S45WsjdZxabiB9dE9LA81szKhXmV/CuvfMIumWbqgJnvNgiYIxZIEtPmoaTSl7jUEkisAEX2Up0yoF0D8AiSfg0ufI/bFuzk3/m5e7N/NC4criXzyt+Hl+yB0zpltTR0pJLOJQmPA1f0zAstMW38usVN7QwRA2wpr5ZbM2+MnWP/EBzk/Usn6cB6ZkV2khxotQBcxEyPl1zAqbeIpKndtogDfZDnB+d+Cs582S2baN+eOGu2037cAolvPaU73MAcQ90xkFUu89I+2G7ZOWZeJmZZdgR/cy5nx38F/uJnkIQXaO2CokKyC1uFGgnKtJqoJTVSRnKwl0VdtFQbpkRqWBqo4N/F2/A/fDckX0W5VyZTbi1zrps8m4Ly3gaqzICLw/3oLovtTuiIUD5MIr0My6LZ1SyZtbkEC5hcvZU1SzxF+bJYfHf+PnBt5C6HRvTBZC4e3wMj1cPhmGC4iPVxpFjIx3EB0pJ7oaDWRsTIi40VEx4qIjxWRGCkznqcOlxMfLCIxVsHSeB3nDzcQHN1Damw38ZFaLkrZPTEBseeNF/6E5ntjqOmDwBHJlUIYODyQbEpQiHaK2BJqdapFbNotLfgkvPhpgp89wA8G38HFsRpWj94GT6gJ9osbKT9tuKZK9mu2IMKBJqiypu/E3iiJeNQaNlou2vc80X/q5vyRJtbH8yzjkz7UQHywhuRIHYmRSuKj5Vc19FnNzCoTFh3PJ3Cknuin/gR834JUzK7LLIdTJUbkDYAYup2PoocCiAmjnlga2+u6pzcCApTmGi7YnkwkzhD+UgerU79O4NAuEkPFZIa3wKE80oPSms0EJxrwT1WxcqiA5Fg1GZVZDNSRGG/g0kgTq/d9EF76lKVmtVgzqOF13VjKuhovPdflGJsNIF6ud1PnFfe+g/Xr/S9L6U+qC7oSxk77EtdKJm9vMz1MaxdbpTUElDMknrufyx//c/xj/x6mmmBkC4y+EQ5vM4BkDlUj/uYAEh6rJDhRQnCygOBkvgPJaAmpw5WkDlfbMThcweXxKi6N1jgXeawRFKMNlrL2iT+Giw/bfiYCSMTbFTkmoklvmdVQsC4o5LIyjpfGOq0jyRFJezqGzkLoOXj+YZYf+ihnJ27n/NSd8MQshF6EkLrVO6Wv/Mw1AySkCgDjjITIbylUlZL7c/6BOpp/7xTnjt/B6tQ2UhPSMLVunmS0kfg1AiQ2ICJXG0D8c3uIPHIXxJ81Kyba/WsAousXMe0+vM+oTseCVs1S+5VilHU8R1pBY+QF1j/xF0SPvIPAUJ2lPpPDbyZ1eItpz9jIbkKTuwhMV3OpZ5tpS1kWWc7k9G4uz7yV4MMHIKGgXLu0OsuuBgXy/kU6m7fIXVCuosEL0MVvfUYjx/vXCw6dL1Bo+zaXtXOFBrZE3wiSJOpXax53LYpMNB2npt688HFin/pzVoabLDGSHruJzIjc5zIyh2o3AaSW4EQ5vqkifNP5BKbyCU8UEM8BZLiWzESzxWMrY2WsjpVZZTCHqmC6kMxoAWfHb4UfztoqwFA8ixbwqVWpFzo6gOi6cgDxKj1yPF2JqHWQRyvpAK1n0vp47Wf/wuf5wcRv89z078Czn4DIefArRPBCh/8VABEBjY8miRIqEdxlRmVZzJu5+AOWHnwna7PbiI8VkB1zmiI62kRsrIbYePlVjcRoFYw2GUAyR8pZOnorPLvgUoK2/NW7OF2gN/t/xYJ4cYn3+gZAdK4pU1ebZmWllni/DFllRCKw8n3WTn+A6HgzsdFdJEcryIxvsZEYrSEy1oR/0lkQuRdyKZK9FWRHmgjP7GP9vt+HMw9BTFsKXJkMywm96OcEXxci5lsazfnZnqXLzYM42l8NPLzPbNDFeRf6Xl2Hl7qzZuY5QKrmyWbr0y+Q/eExzp1+PxfEg+N1ZKdrLHhnpJHMcAMRrSuZqCM0WY5/upj12QJ8MwWEpgqJjZeSHqkwDyIyupvg+C5CU8XEJgqRC8pwBRzeCqNbCY5Xc2bud2H9Sbt/TYMabHVRqo4wLSiKeRbEAOLmgXQfup/cJKnOMsKqIkTLrtWX4IXPwsuftyXSBC+5LKzR2GUyr9mC6EeNSTltbZNsTgvq4izRvvQjVj71btaObUXZJgEkeGgXIk70WgAyVgEjDUZUAWR54S2e2xIgq15KuYvTtW0IgtwFuSqvBIi0qLkZ3mdkPdTcOKNcu24ivQTZFcgmrEo2ePp3iY9XkhitMx86PbGF5MQWYmMVhMZ34RNAJmtsXiAzVkFmsJzsaCOBI3cQ+NyfweVvubZDpvlEqNyfLjYXdG4Gh3MfROsc40XfawGIZEyf1y1vFiRl8DSZakLnJThU7xTXHmuWRVsmtfYtVr8zzMr9v41vdg/B8SZSU3tgtJn0oVo313GoiNBkqQeQQtZnigkKCALIaDnJkRpCY7cYQCQX6fE8A05mRHzdbgBJjxWyMv1Wkt9dtNWAiiC1qYEtqLK9F0Q3j2YbINHzV96XQKI72pBV3ZdcrrWXwH8G1IVRnek9vidto4fAtbpYLh0qAhuVxUOvRFkmWV6rcXN9hfXPvIfgwjbSE8UwXk9guN6IGpuoJj5RcVUjOV5pAMmM1pIWQE7/GsmLX7OLyajn0WaAiB4mCDmAvLKuTEG5neEdBBYtEEvZPuhx0iq3kfOTUYDwfSKn30VqopDkWC26jtTkzSSnthKbLCM0VYt/ahcBjaEimKgETZiONeA79g4y39TWYS9dabG0YSFUfKdgfNOw9xw4JNC6vBxANhhu4vD6/+m7xCMNPXb/5SpruCSFZNC0bjpDMqJ9Gl3NV1Z7eYQeI/Hdfl4+8uucGb2T5Pw7SE40kzpUQXa0DH/fNqJTJQRmSvDNluGbrSA0XWE0yoyVkRqrJDTRbO5oZmIHjG/DvS6LXEh2fAeM7SQy2cT5U/8NVtRVft21LY2onsxZCtHFgcRztSxod5edo9VmK2LnC0O54SlPR1vJtFqnrhPj8rUBxE2oOR92g3Oe3Akg8qWNm/41Ap97D+GF7WQnq2G8Gd9IHb6pOqKTlVcFDoFKgpk9XG8WKX2kEt8nf5ek7wemDV1libeQRoTwgKvSGGvRLSJ66lcHWQsTEB1EZ7OEWmvu2h9pP1jLM4m6y08Qu/dXyU7m2TXEx6tJTu4gPrWN6HQhgekKA0hoopFAfxHYPZeQGq9hfUFroxdd5xO7rlyGKpel2lw57SYFxUn9bE7bO0Y6cXbCYRLyuv9JeLwCDvt+A6atu5CFdb+nCnJHpjjp+JrbxXajFiFkmw1d/Mzf8dzku1mefgexid3IYjJWSPzQNuKTRYSnyvBPV9sITVUSmxAAikiNlxGdqCc6UUt2PB/GbyY1XkR8ooz4RIkpICYKyEzV8OKht8D3pyFzxs2Qp5MkE25qM4dho8iGS6pXHY2kSGQhddQ92/2IcJ5M5N7XOe48RVtrpFi6doDEbPGit6xOv+RZkZxmMuD4zhL6zDuJzefB2G4Yu4P18SrWj1QSmS4nPnV1IzVRZQBhvJaUtNMX/iOpxHmb6jKOW5m3R5GfBBBHQyPYhkshCnrpdVcjKosjpyxiwaxpnaUnSdz3yzC5xZIOiYkaElNFxGfyCB/JI3CkGP9Mk9X6hAcqYKoSJnaSmq5m7eR74dIjZj0sRjNGea7Uj1kOd4GbgaHHV0AhhF39Xw4gpsjEOE3yqu5J5bCebtEuUcpxpQmTZp1Map2stxGnlWQkLpF+/iFevPeveGb47QSndsOUXKRtMJVvHkNsqsomTAPTTYSn64hPVpKdKLKhpE1istImCxFoJouIyw3zZILpMpit57JKWj75XyDwLbd5qZKLXqcTiZ0DcS5m87J9KhfxQOKx1cTxCv3c5/SegJGznTG0DEJrT66x1EQWRGJj+5YKGDmYZlxgJLNmV7T6FIGH3k78iCaVfhFGf5n16Qp8CyWEZ0qvASCVZIbrYKLBABL/yp+g7rjatsCIEPfUn2dBHCFkQVSyobUhTric0Hno1sEDSMx2kEgQsSSn61huMeHK0yTueztMv5nURDnxyRoSk6XEZnYSnNuCf26nA8jEPhKH60ECMLGV7JEqC+7xPWrmXfS5wlhdjOcimJZxVkOv/jhzJQhe4G6IvTqQODdSFlKiIffOS9/oorziA4UdcjWdIxYkk9GcTRS1EHVLYiWlZ1n/+gTPTP8WgZk9MFsGozfC7E4k9FIgKgwMTu4jPNVIfLKK7EQBTOTZMauYZLzKKZupAmIzBUSmK4lN1pCcqoIj9eZl+KZ/EZ5ZsK6Y4q+WO0sRS+w8Vjq6mKLRO1dcRd2SznG8lkA4emfScVKag9K0ne5JsZadp+RJ+NosiH4i7NUt2VoRXamG139VP2SLlC79M74H9hGd2goDvwoj78Z/pBL/qXzCs8XXBBAFhEzuMoBkvv6X5hKpKMQAoopbj9l64bUB4gmJBxB9TABxu0gkCXo70Cq2Y/kZDyBvIjVZagCRFRRjg3M34p/bbgAJTtxOdnw3jJfD2BthoYr1+z4EgadsT8L17BXmOsY5Qde163lOs+X0ziuEwFuC6kovrg4gBrLkZbfc1eusLtdYbtcGeFXMqeBVrVWTMdsXPpnN2PqSUEaWRWCKwvkv4//8X+Of20tmpgCmboLJmwwgqnaOjN+K6BGe3G0AscLSyS0wsQ3GC0iMNxKbaDQaxmbzDCCRqTqbcE3N1MNMoZXs8MW/h7Xv2e9e2HStopX9SXFYSY7WyXi1axZPuSSMc8oEeDFaMx1K3/vNauo2teWH9iYRraUYrimLJeK4qlepm9QVjnp5Z110JrgK5z6P73QzkfGtMPjvYfRdBI9UET5ZRHS2hMR0xVUNaRdNFqand6G6oPQ3/952JpIFMYFTJZ4eSOF6LpbsnWnMTVksCaRbn+y5il54ogU4mqXQ5JQ2rzQmCCArT+N78L2EjpQRmakmOlNNcrqE5MwO4nM3EDl6M6HpZqITt8FMswlJcuwGEieauPTgn0LwaaKRDD51c93kG4spulwNPdbviY25c/SaZdqkgZQ8sGXQYrbe0U16msG0gycvGy/pwjedY0pUM2JaA67da3WPrqGF6KfH9jXWKTIO4bDtcaLYTtfn9nF3v2yZvfgZeHKeS/O/juIM5gvIjr4BpnaQnKogOtVEdHIviYm9JCbrSczuID0rEG2HiWKSE7uITzYRnykheiTfaBs8Us3KWBXRiWqYyLe6r8SJ34LlLxKN+FHxT27OSBRw9/cqgJgVcTQSONxw0xHO/njrnTIpuw31IVGJl+PDNRYrOoaI6B7hRXRx1cOKbVGWUlnGAmtzjXCsGCb3kZ64g9hMA7HZSpKzVab9FUO83pE8UmHfEZlrwH/irfDUIeuWKIFywuTRzNMIrqAy559urmLdJFtecJoTTgmC7iORWkcVpbZ4LPUCgX8Z4fuTv8ZLU00Ej1TAfBEcuxlmbyQ5sZ3YaAPp0SY4vMOC+fhiHWcW38aTn/rvEH8SUhHXpdSzwB7ZbNmAkVPVCd61KMMmbaYNZ3Rebuge3TZwcicEGC91vQkLDmy50hmvXkkf3PgSCZRgqHPcy3qmx/Zn37mJxxuAE82SxBKCk1Zpxmzb7PVHOjl/5JdJzVeTmLmR+PxNxOa3E58rJj1db/FndnIvoYVCQovbSR0phekqmKqxuZTkbA2RuQr8i4WsHy/EN1tCbKqSzFgJmdlaLszW4//a39iW1NpuIncbjre6MV19LprwvAJzEV1Bbe7WdZZS+y5oFoCuKI/NeuaaLIgxRBpG6BPh9E+/5S2V1LwnqQvwgzn8RwWQQjIzDTabnJzSsYbUNQAkfrSC8NFSfAsNrJ78JXhyzNYY54TCBEgaT4v/jLEyDXK7LE11BUSbCtxyBLxCeImJAljtuXfR7X+XfpHVJz/J149+mOen9xI6Wgzz2+HYFpjZ7vzqsToYb4DRfDJT+QQWannp1Nt47KE/Bf8/u7XQlkN1gqlr1hANbWwIonxht5+eSz++2qpIGwog7p7sS/RFHr/d/UiQ9D06Ry6Tlh97aJCMXPWfmO0t9xXvEwkyT36OCyc/RPBYI/GFbYSO30R48SaSx7aTnVFscgeM324AWDu5ndhcmQHDgvHpCpIz9YTnalg7kc/ayTz8R4tIzAggFaRmarg4V8rKlz4A4ccM2LonKQ9XO6fr+UlDVBCdHaB067KQOopUr/V3bQCRiJmZ1yo9XaT3i0Z/IVZFbpccQObqYD6P9Gwt8dldJGaqScyWkzxSdtUjfrTMABKY9wDy1Ajax0TXIZJoCByvBZDNbol47ATKASr3Hc790szrZZArkT5D4uzX+N6J/86FiWYS09vJLNxIdnEr6aNlpGeqbGUjM7Wg1YbTVQSPbmflvjqee+B9ZF7+uPWINV7mfkSCugFUWQyXTFBCQWlpCYGbzPQUkWcldK9OezpQXLlx933ufrQOxgmSA5IHEr2pm77qP31BiHD4svsa9d4JvET4iy2sCiAndxJazCO8kGcAYaYURm83gAQWClk/uZXYXCnpmQr0ngDkAFJr1mP9xA6CR4vJHK0iO15OarqSpWNFnP3UO0mc+bR5C8o+ilqiwZWkb26idTNxHUAcPa7oh591+9cOEAt0AsvFCHwAACAASURBVF4a0HNQDSDy9TU7uWTNE/xz1bC4hdTRSuJHaokdKSF2tIjUXBmpo+VXNRJz5Q4gC3WsnnobPHXYNSfecE2c16FGFFcsiLp7iICe9hCFPOHMvZYja+5oK9ekb5JrrtgtcxF8T/PiQ/fgn2qG6ZuIL9xA9MR2YvMVpI7Vw9EaOFoP07eQmakjOPMGIvflc+H0W4g92g8KjqXCcppckm4AcRZDOzA5cAgoEgBPlj1gGBA8cus67R5ymkFKVOd54NHnlbJWulpAM8DbZJpnZtypV/FfQpnAH1hxIFWAHPHBE/dy+fg+Qid3ElwsIbJQQlru50wJjN1mbnZkoYDAyW3E54tMqXCkBFVDJI7WETlWR+B4CYHjRUSPlsJRxSBlpKdKWDtWxEsnbmftu4fdQigVx+aUYY5GdvOeW5h77FVK5EiU+8z/ZoCIE8p7aFLFZ8Q3ThpAVFK2Cl4M4jtWCYs3GCBiR6uIzu0kOpdH4liJA4mA8jpHYq7MCBicr2P91C/C04OWI7/iu3vh0StcLKUynWCIWBuC5Qle7rM5cNhRfXWk7lMh0kG5WW59gf8bo6Rnb4GZm2wSdP3kTgKnikicqAbFXEf2wuxe0keqic38HKkTb8Z/ooLgwx+G4DNYxzNxSmT0LkYa0c055DSj6zbzyuvU5KJLY+r6DPy6fu8ynel00uLcCvUOUBCudkculnHrXTwUXQU0ch+JRuOEoxGi6q6iOjW1Vlp5nNVP/QbLxwsILFYSPVZO5uhOmCmCsVtgcg/RhZ2ET2whPr+T9FGBxAEl7gEkuFBOcLEMeQkGkKkyMlPFBOcKeWmunkuP/A3EvmcWLCfsuv0NgdeDVw97yVkS0cVInruRn3K8RgsizrrOJwnW3Eo7/arlkj2AJNetSZdvvhxOXI+EOjJXRfjYzYTnt5GcLyZ9rPyqRvJYuQeQWnynboOne627R07IjWCeT29CJMmR9XAGJCeTzq/yAGJafJMF0mSe+i0ZktIxsjGf279Cu+I+/0k4/jY4VkDweAHLp3fiv/dm4qdK4KiAcxvZI3tIzZaRnXsTyfl/R+z4Vvwf/yV45iFYWbkCDuOsxF0mxeXvjcE5wc8hVs+lqY3usjLuE3aJuuHceXbzkhH53SmbrwqT0tq8jbkrJSDsZ3+KcPxrXg4EEpYWjWT8ZLNhL610kdS3/orLp+vwHa8nNl8FitNmS2GiCaZ3kVjIJ3piK8mFPNLz+aTnC0nOl5I4Vkd0vp7IQhXRhQrzOCw+mSknO11kivXisUouffJ9cP5+U845gOjWc5jYeJB7IXf0LInTjD9bQfwvAEiALGvE8RkjctpL5lwzkWgfusfvZW2+0gASP1ZOeK6K0PzNhBa2kFhwhBFxXvc4Vk7sSCnh+Wr8p/bC0x1uUcyGL38l4HXC4Pnem+JZ08yirATqp4FEk2WpjCtcTGsWUdYkAr7vwIPvg5O7CJ0sY+X0DgL3XU/slGKtW0hO3E5qtpH4bDGczCMy8/+ROnG9CU30kTY4q/0qvASHSaMuwAuk9VDXJR2UG7lrtDe0TZlK9zyA6PP6jM7JBV5Zl/uXACkolc3JDfUEU4pep1/1nzqze1NNccFO/bb0Q9EAnJth+aFfZvXELgeQI+UwXQGTdTBTRXp+J4njW0kubietGGUhn8R8KbH5GgNIdL6GxLEqMrOVruTkaDnM5BM7utOs0tp9byf5WDdwecPF+tcCxBFKZ2uIaD/97xoBoh/QlHzAupuIEcZMS/OK8VrXHDKA+I5Vw/EbiM9VWpYiOJ9HaH7btQFEBD1SQuRYNcFTzfB0K6TPmxrZUBgeWFyFqjfP8WqAmEBtAoho5lkefY/ejicypHNd9bJpsmqynDxD8rN/Dff/EqHT1ayf2kbw3jcSO7mV+Gw9sfFbSM40EZ0qgvsLWZ/8v0mduhHfXBmB0x+A5z/t9loxRomWHjhela7dDN7cfclF0CdeARAxW7PhueGVWogvSn1LdnNDDpyjyWsLyE8XHUejXN9oS0OnI07m1Jwv+lVWHv5Dlk7tIrpQDrM1lso1kBwpJDOfR1JJjQUHElmU2EIpUVmO+ToDSvJYFdmjFdYBhvlSOLKTxNGdxE+UEzrZSOSrfw7ZM0YH0ws/yYJ4vNywKAYIj9b/+wGiX48Ty4RYT/qNWQbnhJo56JKV+QmR+fYCsZO7SR65gfBMuQVhMd3kwg4SC8XmZsnVev2j1Fyz1Ik6/MdryHzzv9uiJk3+iiAJW5TuzK6yOJbl8LSxCb64bzNfV5ILRj9PCnPCuPlohNbn9GJqDZa/QuJz/5W1kzUkPr6D0OIbCc/dQPZkDSzuIT27l+RcvblWodNvImiZnRpiR29nae79pH74WQhdtM4dmpHOxCOkUgnDhG4jlFaoriDbyZ6oamlgZay9+Sa954ot5ZopFrgyg6wO9loguBJO4Yu7NKeyYQnNxMuGaH/FTMZGNpu1phGvCYrNb+bcVytHcXM1Ya3I04XFniHx/S7OLNYRO14Es41WxY2s6dFtJI9uIXnsJtKLWwwoscWdRI4XE1msMJAkjtWQnquCuTKYK7KJR+YLyS6UkjleRvJEGZfu/RVY/66xIpFME405axzTfSZc4bW9uZmBUj5KUGyY5ddWENdoQUzCiGcS1oI+Z0HEn1AsSkp9YONr8Ogs8ePNJKevJzpTQXxxF4lTNQTnCzyAyM0SQF7vsZjssQoyJ2os+E1/408grd1rnQCr2lMEEjDcDPoVCyJBs4kiESznkohWr9I4r6Cthwu9Zn8qsfA/D49PEPjEW/EvbiN5agepE3nEFgvJnqgnfWS3ASR0Mg/fvVtZO1VOaLEGZitIHLmdcw/8BclnP2kd/qzDeWydYGgdXzyCL6vlrqou04y+A4mu29DjTa/ruQO/nCclTLyOJBbHZAhFde+OJFpfZDeogFrd1JVlzAgkVw8Q0ctau3qxTiBqUmA9gONPHuPsqSZiJ/JhugkmG+FoPtn5LaSOaW7kJjILW8yKRI/nEzpeTOh4KZHFcmQ9MnPlFt9xbAcs7iS7WAiLVbBYAcdvZv30bbD0Vbu7dCpBQp0WBPtEBtWpWkX3qxmoC/4/CRAZCi29EFnECAFTfRuCwSDx8GXX3PnRw8QXmkhMXE9itpTMyWbS9zYRPFpCbKHYAjbFIjKzr+coUDFfSWaxitDJEmJf/U9uua2shGbPdbTyAjkUShp4KterYVRcYieKkhqmXTwUGKmvIOLVdDaQ6PxYABUfJr/631iaqyB5qhTuKyZ8bCeZE5WmBcXs4IlSVk+Vs3KqjpAYfGQrHMnn/HQTa5/9Y/jBGCz/o9sLnCTBDJyNWR5QuUDWSVviN6kYSF0y5CuZPCgF7FkOA0cOIK57pLXv9DS9aVNtkJk8A2vfIqG9XdIqQLxKgIg80jkxZ3k00+JPu6JOKZ3Ui1/k4ifuIHpyB8zsghlNFheY1UgJJPNbPIBsJ7pYSPBEsQ1ZEiVgsnPFsLATjm8nfSKP1PFi0ov1MC93fQvhU03wo4ecxUyGScmdV0ugZBrNwUrvbeZbjqWeuvCsiGmNK2+96tE1WxBrTOilUS2TIqaF427f8PQyxB6Df2kltdBAavx6kmq1eV8z3L+X4NEy4oslJBcLrmqkFmR6nUaJnCok8MhvQ+AJd/+qp/EQq5lm5W9+HCAyyR5IcsccRV9FKD3NvbX5aCDMLMOzR1i7/zfwK7g8WWL3FZ8vILOQj64zdLyW9ZMNrJ1qIHq8DI69CY69gfjCDpYWGrh477sIf+0gXPoyiG4qlMzmaqOyrKvlaTpMUn2e1FZJpR1S3RvaMGdBZEW0j4abuNVOssJTStZUiQVtDbD+T0S+P8xL2l8ktXL1ABHwFJtph9e0RSH4iFoiQG4gS4+z8vl3EjldADPVcHQXmYUiEioxOb7NgMLCNjKLO4ieKDElFzpVQPREAZn5Emc9FreRPbGFxGmXHUwu7IGFBlh8s3khsafnIbPutHJc27ElkTVRvJhbcGhu6Sb+/R8FiMmV/H1ZEYFDWw2oc7hptYtw+eMkv/6nZBY12XM96aN58EADPHALIU0aCiDH869qpBYLYEGFcaXETu1k9TO/CivfdvcvcJg/Yo1trC731QDR5JmbgZX4vwoor3j+E9DiEdw8CpWB+n5A6ls9nJ+/Df9CGdn76okc2UbmxPWkjm8lutBAaGGvAcVcjoU3wOK/IXP852w+QDHM2ifehf/Lf0/iBydh5QnH9HQuThCYZadlOhRnBLxq1Zya1A2LAa73sJ7p7KglGFQ2HHYZvsSj8OQQlz71+zzzwIcgffaaAGLOfjwqBFpdmCJRVQObcQudIfyP/4nwac2GF8HxalKL5cidSp/aTnrxBgwgSvkeLyNwqoTA6R1ET95MZqEA5nfAyTeTPn0Dkfu3E7q3jMTx22H+Fli8kezJKgL/Mux6XqmJtxoWqrIjE7e19IpBJQI5UdBjBxbRUu6F3vnfaUGkJfT9qkpVoy0pMRWvZdVHVcszn2XlsTYCj7wbTpbB9PVkj94I95fDx/cQPVZN4ngpqRMFVzXSx51Pmj1WQvz0Di4++Fay5796RUHYvcv9CFi7HgtkJTWeiyWAKA5xhHMpUWdRRLhXj80AcoDR7UtDxzQ5Jq1+8R9Z+9yHCdx3KzxYR3zuTWRP/QLpk1vMgibmbyG1WEXqxE7Sp64nffrnSJ1+I4lTNxK7txj/6V1cPvGLXLrv9wl/tRWefdAqf4mqe7sAoXuR6GkyUW6jHO1NfN6It5TCzcHFuRpypUg9C+cWWP38B7h8qonAI38AqeevHiD6cbl8aW14rmVVMes8qcXJcnYkC4lv/iXhU+Wkj26HUyU2iRo9XkH6vjxTHizkWWwRO1FJ8HQ5wfvyiNy7jezxnbCoz7yJ5H1vIPjAVgL3VxLVvNP87bBwo8nU0lfarMsMGVUmqLGGytxjqLFXPOEqEF7NSSlKDVeaYkLykzXgtXY1MZ8jnbGsogxHPCIOnQdeIBl8maUXP8sTX/gAlx/aC6eLYe4GMnM/D/fmw8ebiS/UGkASJwq4mmEAOV4Nx4qI33szZ+69lcTL/+BkW0DYAIhm+VUOc6UOX6DQXI3iEEdAN8MqojnC6VUv5bWhbXKkdmARQMICiAJmE9RlePE42X/4ANmPF8Dpf+uAcCKPrCzdXA3MVZJdLCB83434HthC7BPVhE5W2ERj/HQhiVOFRBaKiJ9qJv3J98BjnfDsKbj4bQircYRL2arzoqINSxbqXnVpnjHR01xaN6wgOp0iE3yJ1I8+ZZWwZxabid5fAI99ANJPXj1AFIOpEljzHxpErOOI1uPo+lTgmf3ufoKnakgeeyM8kE/8RD2h4/VkH1CM9iYEEHkAkRNVBE6XE7h/O5F7t5A9ngeL2+D0z5P4+C/g/8QWfA9UEznxKzD/Vpi/CY6Xcf5zH3HN4DLnXZeS/5+99wCvK7vuey+HBexEryQI9jKcrhLLlhRFUYrlOLFjRYmduDyX51jOs2PHzy+2FSdOHMe27Eh2JCeO7TiSZoYVBAESIFhBdICoLGCvYEXH7fee8sv33/scEBwNZ4ag9OaT7MtvcV/ce8655+y9/qvttdfWPimKEmn9TkZCxGrSQC4GvrICFyFI3hUgQc/qgUKNoFZkR/3x3p/5zp6nxFgJEa2nMWkG3g3w+0kPH+Rq62/Q9+bL3Nu7GjQgXyvA+4vl8GYF7H2FzNd2PBNAHGkQOcL/ew3ZXWUMv/4iXN4T2OjGQw8yYZXwJ6n7iOctQEJwSAmGAJEm0bO9Ez0CiNZsG7lu1JBWil2G/t9hatcLUFNBamcpmTdWY8D81XXwlxvwv7aO6d2rGd9bSaz6BSbf2GzylvzqCqguwH9zqZWuezbh7PsY3pGfgP4/hLuHIXnZaESbfBgkmYWKZbbVYMZPs3j3IN5L+vrr3G/+Ja7v/hRX/mIb6Vr11S+aiolzdtJNBFAMoHX00hvTJuImD2pC/aF0mL4vMfn6R0h+dSXUFJHauY2YUnH2VuK/XmCjU1/dgNUgG4jvKie1s8Q45Xy9BH9XLpm9uUxXlzG1dwupNz6K/7W/AV8thTe2cefAL8Jkn82yVgV4E8lThzikJLUDs0qjKWGouZ/3Cg6dG1FKulmPrQ7VQ4V8IR4wyzoVU5ddp/yfADPqGMMWWjgfOMNG2GoBzg0YP0i29xe5Vf0Sk3VFZGqWwe4iUDRj52rYuQHvzZdxRbu24O5eP2ealk9TvRn2V5KQ3d/4y5A6C9nbSqNDm6rIbZVE1eOFzyAnUo8a4j1sTY+GBz2xtUfpfHlbijKNKe6uPsjEYLIbzvxH4oe/l7Fdm4ntrSSzbzXe3rW4O9eTfXMLqV3Pk9i9nWT1RpLVlST3lhDfk0ty7zKy1ctwDuTi1JYQ21/JWPU27u77EMO1f5/Rpp8ideY/wJ3/CeMHIN4N0SsQGzPBEeOiyOSTuZHthZt/SLL9hxmv/zATh17l9u5XuPS1DxNv1sKtertPn32cp/9fnRbyCbIcVJrVztZLYpsgwnAz0T0/QqZ6De6BxWRqVxPbWYH7xhp4vQp2rjf84O7ahLN7A+7uKkPsqsLQ7tW4e1bj7Kkis2cD7s7n8XZugzcrcXa+yoM9Pws3DgfFHMaIE2XKi5NUiXYDYPGt5sBsJFOC0pimM/f+zo8dUYRnBiB62BAkRgJoMY11euxcQdghYg2hNGvX6MjgNQDRhu7tOKd/k9G672GqutyCozoHdufDLgFkA7z5PO7OF3F37kAdM1eAqENjr6/F27ce9pfh7NxItu5HYKIR3CtkmWQKz6h7yRITZVOniYLGasp37qQnfasu0nUFQJXFlDa1/TAJY21w7U94eOQHGa3/AGP7q5jcW0Jq7xq8vZtgz0uw+wXYtwl33xqye8rJ7Com9WYuyTdXkti5koTs75oy4nvLGNtZxv3X13D/jY2M73uFaP3HSDV+H+7Rn8A98StkW36fdMefEe38KhMtX2Hi5K8TO/rPyTZ+GK++Cu9gCfGaNdza9SpXq/8JsbN/CpnLgTnypCd8D58bgOjBh4F7xoQROyjEapK0bvUxtednSO5fS6ZuIdmDhcR2FeMKHPJLJSx3rZ8TJXe9xujuH4aLX7fzX0wHAtEnrXQgSSyFMs2CMIX5Y0E0U3wdKAMB5R1ej4d5jRgN5gTCuQFdaDaZC4ZXDxlCnSHtcRku/1eGD34vt9/YTqx6E44xr4pgT67VIm9uw3vzRZxdz+Ps3mKkhrNnPXOi3RvI7N5GRtJmf4H5reje74NbO8G5Y6I+kvCKqsxokFByCCDmed+hd97tq/BainKmPDzVtVXXCDlmYdZNkre+yoPun+PSgRe5truA2IEiOFQJ+7QKcT18bQN8bRN8XZNfWyxpnuSrG+z3e7fDni2wax3+m3Luy3Dk4O4rxzlQydiu1Yzs38BI/YuMHHmVh0df4cHhrYzUljCxbxmxNyL4e5ea4yd27uBuzQ8ycfr38cds1XSL6Hd70Hf4Xs9rQs1Wg0hzPAKIA7d6mNr706Rq1pOpW0TmUCHx3SV4byg/7dkAkt69g5E9fwuv9z9C9Kzpc5Ut0+/LjEopcBIKRFum26xR8iXcQ0Vg+PnJzxeZYX7zRpe2mmHGHwnBYa4RRnoeuSjupBbxqlTMLbzLf8ndY/+Y4dpXmTrwMun9L+Lu3o6/ewPsLYU95fi7tuLu3kF2z1Yy+zbi7t0wd9oj0+pVUm+sxd+/HKe6kLGd3w1n/hhSDw2zChgCiRk0PUPIwCbi8+SOeU/f6Fq6sCjj4afTpNJZEloKaraukFq5Rfx+Dfd7/jW3Gz/JWN1WsjUVsEtOZoExFYxW3bUZdj0PO1+ANxTnfwG+qkVmz5tiD3x9E7y5DnZXwp4y2FcK1SVk9xeTqCliqjaPsbqlTNTnEDu8AKdxHhyeD/ueg+oiMw5Te/8uifbfgtFmM4v+XqI479oPBiD6TzPzY2/RIA7c7mZq708agGTrlpA5VPw4QHYpJL5hTpTZu5XJ/a8wffJHYVg75Gr9kd3xV0ZVLJMwOLAYkJYL54qCWgUCybsCRAfp+YxtoAtYBycEiMn7MULRLuSxSxxtRXdjxEdVCmIYRvfzoOknuLhnB6N1W3GPvIpb+xLerpfwd76Av3uz6QR37zoy1etIVW80lN0ngKybGwkgNR+0E0v7c0jvX8bIzhdItfwaTN6dCecKJNZJD8KiQce8S9+8K2/Y5w9imhKdXoqEN8GoO8KIM82Yp0rAQmIC4lfg+k7iLf83o9UvMbVzMfHdEZyGlWQO5ZOpKzLmlHyV7M4qk2vkfG0L3td3wNdfwn/dkv5Of3ULib/cQPx/rYc9r8Gul3B2bia+s5LpXcXE9xXg7s+D/dLcq6H6Faj/AWj7DbhVD9mHZng10uqKZ3qpE01HWic91CAS3CbfY7iV6L4fJ1OzCad2BdlDZSR2l+FrScCbmwxPeHvWMRcSH8Xrt/Cw9ruh5/dg+oKZb1AQS+WKNNFqx143Ewh/41dbnjf3+C5MEDGDrPNNjdhAe+hPhbi1LmKmGohmozWfoOWfds2RERfJcXjQSKbvl7hT/z3c2rve2NvZui0QAuTN1/B3voK7ZyvZ6jWkasqJ799gHNTMMwFkI96+l40GcaoXk6pZzET1ZkYbfgLuXLRYN4l0EixKD1e0JeAKo0H0xzO8dLrsN8kVk+ikvpEdPMUUUSbNAiXbl7avJuBBA5z5fxk/9ho39y5j5GABD2vzeLg/l4f78pjYV0S8uoJMzQao3YovU2zvVti7w5AmIOWoOm9ux1M0aOfL8OYOM7ckXyZRXczk3gLGdxUz+vpaxt/4AG79j0L/H8Gdk6AFX1m7F59qQH3zACJPzFaqFytagCThbhPR6h8xAHHrVpE9VE5sT5kJVjwrQLL71pKuX8+DvVtIHFZ29Fdh/ApMJMzWcvIPZT2ofJMBiHwSw7wWIIGcfEcGiFgnRikLIhtINxGeIIIoiaDQWMasGNTKQaVsWDVmBv1hO5z+PA8PfZwHNZuYrN1IbH8Vmeq1ULcdf8/zsOtV/F0fxNnzItmaNaRqy4gfWE+iZiPZ/etxqqvmSBvJ7txKdvc6MvuWkqhZSrxhHXdqvheuttjZKj2AAYPmQSatsDMC4R375T1+6eE7SbxsAleFkM3MvECiPlL8TJVGAuFlR8ok8ZHpxbn9RUZO/xhjJ/8eE43fxcO6l7i/bxOj1WuJ1a3Bb6yE42tIV6/A2bfMkLdvJX51oBkOlMEBTaSthF1L8WqeI1kfYeJohAfHl3P/2HpuH/448bZfhbO74e51u1+3wKx5PUWkg4Vj7/Fh3/Yw48eZb3Rhm4elrBYjiBTRu9dAouYzFiC1BTj1FcT3lpvADLs2wt71+Puq5kTim/SBDUzv20h0/wtwSnuu1MDEPTN3qTuysA3sYIFDKiUYFv35LgqEiPHwTY2lIIw7S2uE6tKGxkIG088Gxyrdu//3SDR8L8NvbuDhntWk6jbi12+GgxvgwEb8vZsMSLzdL+PsfYF0TRWJ2jXEa6sMZfdX4eyvtAB52rZ6vdUee6pI7c0nXrOC9LE13K7+EFzYA9H4jEulaTWl/tkZ1PfQM2/LDo9/aFfraalQnKnsJAnHrs03PyqzypTCCUJd6rZQQWu2lxtAD9z8czj728Ta/hX3Gz7D7eq/yZ3qVxk9sI3pQ+tIHV5Dur6EVF0+yZpckjX5ZA8U49aVwcE1UF2Jt7+CWG0po42rGWnZzlj/p5i69C9JXP0CRLshqRBwIE7VamCVGiSz/BlfhsH0nzFd5BrbyxspqjX892tIHPh+sgc249YWBQApMwAxvocBSGUAkKdrFb1M7Nlorh3bnUviwA4499swNWhuQjETC5AgvPgNAJGn8s5WRMSIEhMKCyWt1UIWHCrXrIJpGVw/Y2qymlTd7Ah+8gZMH+b+wU+QqN1MsuZF0vt34NSsw62pxN+/FqrXQfVGQ17NetyazWRqXiB14HmSB6tIHlqDW7sW74Co6m1bt2atud7bt2vN6j1qN+HUrCVzsIL08RLuHtjCaOMvwd0ztockQJgmyR0eRm+RNqkINrbwLPyh/g75TuVJVWjBqi3lJgWaI5BYxsWzCtrwpz42zGX2c7wNYwNw6yjZ83/B9On/xFjL5xg98c+41/ApHjR8jJGGv8FYwwcZa3iNcVH9Bxk/9D1EG/4xsaM/Q6Ll10gP/BHO1Wq7tcLUdUjIaQ2KgolHdE+iQIOa33+WDtClpJ3N9SQ0fbPxpX7CAuQBXPwTotWfNP4R9atNQCG2rwRqt8C+DbB/PdSshZqqp2/3byaz60VczYMdWkaqeinj1R+Bi182m+RIu92Pxon6Lqr270xmbPqBKS3rEc3Kong3gISdFhhkOkErD2xVjRgJN246wfrwStWYAO8q7tgBJgd/gYn6DWTqCnD2b8WpfhF3/6YAHAJIJdSsgQMVeLUVZGvXk6l5idSBl0geXEvqUBlu7ZoAGCFQHm8Ftnei7G519nrky6TqqsicLOZhXQXjDZ+BK/tgUqvbNGJavz3CpDOM1k+LO73A/Jorj6jrHgHEbjFtfkyTqmLIwC80bWDs6yfDuROda8ZH32mFT3oSErfsjrfRdpg+Qvbqn+Fc+zL+tS/CtS/Atd+Ha79r6eofwd39JgeMBwMwph2SMvam9NshKAJA6Oc0vtKidjZZUcm5v3SuwZveCCkz/l7wXM4wXPg9YjUfNRVdLEAKie8vhroNVoDOAEMgeUravxktmzA+Wl0O1D5H4kAVbudPwugpM5OvqKI2/jGRaPGBOt8YQFlSbuI9AEQjpo40QFJ+ihxxrfO9h8MYWSWhqbNlQ0tAph7AZD0T5/8frh1+nujhlbgHF+PuX4e7bwf+vu341QJJJf6BEqgrwj9YhFe3Gq92A86BHWRrt5M9WIlzsNx+iNxyWgAAIABJREFUXleJ9wRyDqzmSeTWrMZTuLNmrVG1ybqNOKdKGT9cyOjBD+F1fR7GtB2b/CsFGSZJ8ZCoP4JWnRkp9wwcolOtpp2xWiy36QsxvbhnFpMaHAS40TgJINNmpl+bwqiCvNXWnjbpEYWJgEpTl6bJToEzYZfpOqopO4HvTpF1EmZDmWzaMRntM4drvPSjgeYSKFRjK8U0CcZNa1cizg0keszw8ULNFMpbA5jsFTjz6yRrP0hS0bRDFcRri+xc0EFN7lbBgSr82so5ETVKen0Z9m2DmuVwKIfsoVwmG14mPvAbJsUGd1ZIVzyuLcudJI6XfU8r8iNGus0ARPlKIzgMGzLLddQLAocy47Sr6EQP8b7Pc+Poa9xtzCd1eAkcXAZyGvfLnHoeb/8WozG8ukL8Q3kBQKrwajcFtM4C4z0ARBrmSSStRE2ZAWNszwYSBy1Aoo25jNRUMnXkH8GNg5AYMdJEjnMKpSOMkxBoxDx6vmd46XQTCg9MDRPnEEOK9JkJENif0s/ZteTKIrabKkSJMUXMGIBy6xUWNqFJreEIuU9t+F4caC9kri0MKJCmIVKuqOZfdJ7Bls4xzyetoXI/KvIQI8UkCSMs5DPpgnN76dLKhlYxa7PMOdAguj1T8Do5iN/zOdIHXzKpNn5dGfHaAkPGfzqwZk7ACAHFgXVwQDlvyu3Kx9+/FL9+KWM1hYwc/bv4V/8bZIZnKQBFZWM4fswsNdbYvNsrYkSg6SOpW0VfBJAHRnuYkpZCnVFNHkzfhPN/wp2Df4fhA4VkmwvIHsrHqyvGq8vHqy3Fq9mIe2Ajbl0x7sFc/Pp8/EPlJmTJgW1QVwEHpWLLg/dr8A8+mdzaCp5EBiC1miRcS6x6PbH6KtInS4keWcF47UpGa1+CPjltKlOpNAPVhRKDxNEaZpM79W499I7fiwMlOZTNaplY2lYRIpn+0i6PAhzKeQu9dHW4zpVWGwm09YiJss3YR8pk0DWFlpCkyeV5aofXjLaHU4DACxxRa9EZ5jSo1Y3rBFWdUXBC46qJvOngnuzl3wOPPLEHZK4pwqm0DpNmMwMQDy8zZdKO0m0/TKZ+G87+CqgtJXEw35B3sAxqy22gQcGGuVDdWji0CQ5uxtldQWpXHv6hXBIHcxmv28B002fhYYOZ95GNZarSe6rTr37ROAWq9YlPqF1u1aPGvLILi6yJpTmDQLJIa5g9z4fh0k4mjv4YD/dvJ3E4F5oEDqnIdVZLHMpDD+4cKsOpV0ivALe+HP+gkL4NDmyGulI4mA91AUgOVrwjQIxpJvPsbUiShAPrze/L6Y83VBI/WkyscQWx+kVM1FUwffKfw/B+8GQ6iv0yaJcpMYZjp7vfoXve7St1tFIVVSvLmlSKlivmod+ypL4ctyWQjFEVLJZWv2vQXG31NULWH8fxdJ1gIZRSVVRqXNmgIam0p8iohwwyxaQTQs2T9rWKzsNxHLOXeNrXdpcqxyRgKEQvsMjcnLm5Z9KgFiBBxUbFdmcAksVT5GzsKNMnvx+ncaPxQ2Vyi3mTh1aZ3DAOCiASmHMFSAXUr4H6dXj7NpLctcYIaw4Xkj5YxKiiWmd/C8aVOTBNwneY9jX6Fhi++PpdJETESixZw7bOklSmBtYkmylOrm18YsMwXM10288b2z7VsA4aC6FOam0HXs2Lxodw6nNxGueTPTKfbEMe2UOrceu24tdug9qNIMRLatQWQ22eBcrBclxFs55AzsHVPIkETmoEuk1kG9cSP1LK1KE84oeX4xxdQOpIIQ/qP0ri7Bcg8cDIApkk0pMaXLNB57t00DtDRKiQJpBmUB+K9F5kxH3wffDeJNAFzKnTgnXT0jTqcwk0Mbg2qElnYmTMfoCPrqfUEOEqBJ/RFvoj9CNVFE9FGHx5M3ESZvmrZmVmfFOrNnQ74a3q/Dm+LEDSpPwk2cCn0z2ZxVyJh/j3DzF65JM4R6qMteDVFBpwpBpW4R4shEMSls8AEAMwCdtSOLQDr+5F3AProaES6guJ7i8n3vSPyF79Y9zUJZR4orCvFLIBhgSQ1Q5P7IGIzaGRhLOTPDpZp5n13Or41Bjc3k+i++eZOPZxEkd34BxbS7ZhJXHlPx3YbgDi1FXh1OeRPTLPkgBysAq3bpsh/+BajMSQ31BbasBlNIkBSEUAkG9sLTjKA5A83kqrULsODm3AO1ZF8shqJmuKiB/Kh5OL8JpWcL9uPZMdPwsT/Qb1inzLsJEv4D1m2AfqVoB5K5lONGp2piPDQ+wH4jJBT9pEqyHU6u9gSwIdPDv5U1wUAEQ8rbQIs2RZZpmksOeazUMdXwaU9vASqWio/tnx0TjJjDNRGXn8Kd9qGhNREUDSZgY5hK05XvehC+iPbwJALJ95qJBENp0x2knmi5ZQuLHbcGcfIw0fgSMSjJX4e0vJ1JWQqi8kVZ9PtrHImN/+IQuSp20NPx1YhX+gAI6+CMc/aMx7o5GOFuDUrWKiYQuJgZ/FGzthxkQjpa4y5rUZUv1n1wBJAIVkgaP9QdwL4N03kkn9LItapL1nTOdPNOIP/hzRxh1m0so7+SLJk5t5cHIZd48uJN24Gk8MWl+J11CGd7jAkt7rs0PrLdUL1astqUPqywKqwGuowKtfPYe2DBoKoKEEt76KbP0WMod2kG1YT/bYQjInIsRPFDJxXFt3/RkkboIW9gdCdzKrFGhxipg5ULe2v6ykNe8FHKlSda3pUYMfKylDDa3P9b06LaTg+BBJT2hnO/LhIRZ04Y2Eg/Z4oqh+X8eb/3SoOXn2OXYBmO5CNHP8o0NmfWh/8an/12+q+0yKm2z7MaLcI+3fhvR1HrT/LtOHP2yiV1RvsNGmA9vM+ERPFDB9MpdsY4kZd/GG+OBpWuor4FCZvf6hqhleM583LsM9ugSvpYzx4x/GH/oSxIcgOYyTiptKPNFE0G3BpkrihTAlySwBIU3ELJF1Y6YCRMyz4FDI0Umrds8AXPk8tH836YNL4NBiOLKZ5PGtPGjK5cGp5WSOluI3rJk7HV6NP1dqLIYjK/AbC/AaNuIdegHn0Es4DRtxji0ne2IBiWPLiB/fQbrj5+DmPltWx1UMHKKeCg1I6UokBAAJOT/g70c5ajJ1JH5tp4aHGSZ9as76DjlBYAtki8cUSYZJowW3Kit0nJHWf0288RU4pIRJpZVshwPbcQ5vYPJUIZPNeZZ/5jj+NJRDQymmrV+L3yBSmk4x/tHleMeW4p0sJN30Aqn2H4crfwqxQcjGSacgqjVVZjwVvbVmaTj/p4CKQBIxYy7fL6mCW5YFHH8YEtUw/pskWz9K9nAZ1ETMRIx1qDYYcyZ1fA1O4zOAQw9jOqcc//AcSB0RAqR+qwWIwCGt1liKc6SYeH0BiRObud/wYaZO/yKkZGrFSCWSJnPK5mfJeQ0UxGMiV3+IA2ymqhWXdnLNdux3CKPP9TFkqpj6COqTSZL+/UCI3CF2/Q8Ybf00ySNbLUBq1oGobi1OYznRk8VMNRWSlYCdy9gfLofDxXA4DznlHLIpTv7hUrwjefhH8gwPZA9vxm1+jQdHNnO/9R+Zbau1dimbcEwdcw28xlK+t5YxK/iufwqLi8x6EBN5kWUQ6uJUL/7Ir+Fe/hST9ZW4tQVQuxRqta5Ys+Mb4dB6aNxgESsmD5n9ads5do7pVAOQPPzGQryGDTgNmw1gDUAa1uEcXke8roTEkUruH67iYcvfgzt/AdnL4GgpsawMJRfK1LKZy+E8hkWMNIY0jAASgkQdJdH51y8xlqpqJh2bnJlOaxJTxfmGGOn/UUabt5I5oiiTQvqiUuM8e0cKiZ8oJnailOyROQjGkGdkQTSugsY8oz28hnV4jeV44gsB5fBa3MPbcI5v537jSm4c3Ub6whdtpRhV59dgy4IOMtY1stYHF1gUrPKIRLlPQkvtLYxAD/mwlvTQDzPduo2E0tYP7oD656FuG+zfDvuVyr4eDlaCNMiRCvy5tjr3SNmcicYyOFKCf6QE92gJ7pE1uI3r8Ru24TdsIXmwlOThIlKtFUy2v8h474/C2C6zTUJoVdn5ChsMmq1AbM0s63Q+8s6kUWRu6ci/2kDRVECcaSY91X1Ut2gtfBRGD/Kg5UNMnVqFe7QIDhdBQyE05MORlfjHckkfLzOJpe4zjL/GnSOFcCQXjq3AP1qIf3ijGXsatsDh9XBsDenGQmInyhk9uZV77Z+G+18CX0JSmylZB01NCBALEssPkYdcYJrbJlpialqNNeFc+vdEOz7CZGMp2cMb4ejLcOQDcPAFqN0OhzbbUJom/BpD5g4Z/Wnb8Py5tBVwuMoA1D2+EufECpxjZThH1hvJIYBogU5aczany0h2r+P28RdJX/lVu5FmQuvtbUc8Aomteh7+bftPjrK80TCEIa2iCNU3IV/821gRaeJ1iklGmcTsMSQOmxyAi/+esRNVJE8shKO50JgPjSuNv2gY+ViuHaejFbhH5zLu4TkCSBEcXYl/IgfxgNu4EbfhRfz6HdCwEY7bbA+/ZS2pjm3cPL6O6NA/hWSdWQVrXIxZ4XaBwwQFA20SGeE8ca7hch9nopn4lV9lsvtjTDVVkjieS+p4Hl5TKeljVcTq15I6vBZOrYNTRbhHlsOxYjhaCkfL59jq3DnSkUo4vBWOrMM7uRS3aRHuiSLco2vxjmyynzeU4B/Nh5Z8Uq0FPDhRznjH98L1P4eoainZ2sICgt3yTHudaDsHK1FCoEhaKnxpTS2p578GiGbRJ5hmTCaqOEuK9eGfE2/7hNEQcpQ5mmfp+HI4sRKOFbwNz8xx/MV75nqr8E6swj1RgHusEq9RAvwFOLwJGpfhH1sEp8rJNK/l4ckiRjtewb/xKyYbnawmZAMtEqxAFEBCikS5RUZrE9whssP/i8nuTzF2tJh4YwE0lxA/lkPs5BLGGldy9+AqJo8V4Xeuga5csicW4R2f9cAhWN5rO1dghOeFAGncYDuoaRFOkzRJEd7R1SBqLIKThWQOLyJ+dAmp1jU8PPYSMc2NxNpmOkeTXjaLQLPOsRl1GwJFALKhP4FExQCCGXGZpn9FX7LTJ0iaYnFW7I7BvX/DpMyeYyU2BG8kfAHeiZW4J1fhHRMYVsORUjgSCte5AqQIjq2C46vwjhfhHi+1dGw13pEN0LgWrYOnKRfv6ApSR1eRbClnpKmKye6PwvgfgDKOBRAZA8EiwVCLCCSRTDZqioulbuxntOVzJJtfhpMlODUqCFBEtG4BY4efY+T4Ukab8phoKSTenofTtRg6l+E15eKfKMY/XvK2LSdKzfXettV3z0LHK+HIFji6BY5X4jcV4LUuNERTnr22BuJoARxfin8yl8zJKmInX2Sy6XsYPqnatNfMwiY/JSfclkBS/ELLUdVRIoHEmlryOYI5Eb0VfYcDJJlM4rrGw5gRA0plUbE59Uk438h0FG7W4PR+F7GGCN6BFXB0HWgW/dhqOzanivCPr4Nj66zFIRAdfxYeKIETeXCyAP9EFd7JKmPteKfyMON/UsK7HATKk0vh1EqyJzcRP7WFyY4S7rV/GGInbE2xVAIv7ZqJWo23lOG0r1ysWILszS7GOn6V0caPkT2sybw8qF8LTdugZQ20l5LtLCPRUUa8o5hE6yrSzYtwTi0OAFJowXHiG1uBjZOS4m/X6rOA3glIOubtvj8hLbEBjm6CYxvwmkpw2ubjtEfwmxcbyYGcRCPFVhnV7h3bSPbEVuLN6xhp+Qjc/e8Q7wHtXJuJ4SY8m2wYzLiGGkSmlmETASLAyaPZtxne+Y57k1UF+VkvgSOVSpHJZMxkm9GsWpE60YV76TdJd1bhHo9Ag6JLSknaEoxNqVmK4J3YYAEipj1WBCeeYfwNXxSYa4QA0XIHp2UlfstCaM6xADy22gLpRAH+8U2kT1UR75rHWOdquP3FIMviAXhR9LwSjgKIwB9h/C7x7v/O2PHvMrOOnFA4Ls+mghypgJPr4dQGaN0E7evw2yugvQRayuCUkFlkpIPfNJdW54RUErx/760BzbEqK6mOS3qU4LTm4LRF8Noi0LwQjss5FEgqbMqDgHSykmzLSqbaS7nb8Qmc2/8Zkn2QiJuisr7WUwWJd9bcUgasXU6qyKARnValfMdrkFnYMFojnU4jraLWJHuqH5K38O/9IdG+v028qQhOSVrLzKqAxu2g9KSmSpymciPlpe2NVDcAeYbxF0CkgY6X4mvsT5WSPbXaZJmLB/zWCDTJTy4H45NughOr8ZpXku6MMNWZS7Tvx+HO18HrM9u5+dkJ4umMqYov6yHC6HmiLb/JyPHV0LMYWjT5kgtHFkDjAlAlioPFpOvLSB8pIXN8hbH3OVYGRyugqdR2hjpkTlQMp+ZI+u3ja+DYWjhRgd9cjNu6Cqd9MW5HBNrmQdMSOFYIjZq3kaapNOrXb1tAqnMxd04UMNb1d+HG/4DoDSs2BBAzy6p1G9q9V6T3wfJSM2nyV8PECgGi7dlkakmDhCaWieIlJ01KefLSZxlrryB6LA9OFUCr+KECjm6DYy/gN63DbS6DpjI4KbOq2FLTHMdePKPxP1Fh6VQxbnMxmZZSMq35OO0L8NvnQctiOKmMi+ct6bdbF+F2Rkh0LmOi9WOkz/0bmHzd1ghQqkx6ykasDUCifcT6/h13W9cy0TmPZPNyaFkCp8VgEWhZhH8qzyDUbcrHPbUQ9+RCM/egORBOlUFLwZOpOR/eieYEqgCM6tzjZdb8kt3ZnIfTIhVbGHRQBP/UAjiuUKMiGpIgCj4shrbncDqeI9a8gPGmtaS7fgzu7oLkHe1nYBas+07UOO42/UCTR3Yy0ZhYf0V8kLCwtVqB5LGXKqmPt8Dl32SyZzvjrYtJyKIwTFgIHRqbdXBiI37TGiPANEacWgUnCi3jPuv4Gx9WwKvAbS4l07aCdMcy0vKTW/OgdbH9vaObQdSkiOYi/LbnSLevINYmf+Rv41xWTed9wEV8Z8xsnaDxjpC+Cnd3M33lJ5m88Alig99Dov9lol1FjJzIIdO5AbdtB27LDvzW9fgdi6H9OWjRepBiKykkLZ5E7wQefddcNHc6Jd9GpOvkGpC6LavJtpbjti/Ha8+xdujJXDhaaemkgCSALIT2+dC6ALelkHTLh/H6fgZG3gDnnNlsJjl536TFS3M8CveGVpU+lX0upHznvkKN8VZH3Txx5oZZJ+/2fpqp9nyi7QtJN5eQPVlmwdBRbiKhSHM0yyzPh9YlVgCfyoemkrmPvfjmlPwXgbAcmlbjtZSQ6VxKunM5mbYysq1l0Cq+yIWT5ZbEJ61LoXUlbls+XncZE80bmOz6Xrj/e+B2KlZt19QYJ13FAlLjuNNncSaPQ3QPzv0vMXH+3zLe86+Y6vgcsbafJtn8z0m3fJxM1woy3REyHRGy0jDtK6BVKvUJpE55Ij0jQKSZZO/KzhRYTpXjtpTbzmkrwW0rwD+10n5/cjmcXAUGIOqkJQFp0EqMepY0yV74LEx+GZIDZKeUOvFoD0aBRGkpZnvrmXV8Asp37is0q6RBwpc+m5qaInG/iWj3D+C0VxqJnWpbbswbmTlO8xoj0WlbDm3q65XQovcSSvOtQNOYPZOAVPBGjC8AFuC15ZLpyCfZWUC6XQCRv1EZgFPAXGjvwQjmcgMoTq8g1Z7PWPsHmTr3L2F8f1CIW7V9IaI1I1pPnFbRQVMoSTVWr4FzEbyLMNIM9w7BzTfg8m+RufgPiJ17kYnezYx3bCTd+jJOy6s4LS/itm7DbduI37YaX458Rz62g4TYgNRJLeqs3MD0eitIZLIV4bWtxGtbjteabx7EPuhqa8pJKrQKeJIOS+CUACJptBq3tYxsW4mRHnrvyR4WSKQ1TikmLpNPYNY9rIQuResK8ZoWku5YQqy3itjQ98OD/2krhodhLNXaDXK3lOCoORNVC58Jos947gJMSKEdFrLWW9vw+0fM99YjvvFvHTv7+sERb7F+vvG8Wcfp2JCMFgwnPYPU/mBdhCZHwyW11gOTxozhJm8yMdzC5MUv8PDoFtzWZdBZQKYtj3RrLm5HCdmWSpInCvDalwSaejm0CiALLZnx19iHJLBIy4iK8FpFBUbKu225hvnFC9ac17EKEgXgMD7PcmM1CCDpjiIyhgfK8Zqr7LHmd2X5iBdK4FQVXrP4NA+vp5ypzud50PV9pG79PtBrsibcdErp7rM6y3SyOkFBrqQtja9dUc1S0HG0nx3eADgdkGmD1Ammu3+HVOevkez4HIn2Hyba/kmibS8Saysn0bYMvzcHTs+DLmkbRZbmwcn5cCwHjkj654LUrbRBSwlKCXAUVj49n2xPhGRbDpm2cpyWl8k0bSPVtIx0i663AnpLwNiZYvhi/NZSQ15bMV6bfe+3hWZgqOH0d/CZAhIKNhzXdZZC53y8vgWk+0pJnP4E453K/r0KsYytjKCZI8OeWr6kPKQkqewkjjONp6WyBjBxfD+K40Uxc0yGmR9lAAdsOhMrDhfoaKJy9lA89kf4hTHnwvFREFKMHVxKuAmPe1Ib4nF2kCGtPdqDfdqVm5SeJp0cIZoeYcofNxOBYyZbz8wMmN3DmK4hdeHfMNr0UTJtimzm4bcJDCEVojHw2wrx21fhy8poywtoFbSJgvFoXmV8RxMRba7Ab60w45/pLCTVvYrk6aUkexaTOr2ITPdSnI5VZmy9lg34LeusCdW2xJjTbscSAxIDKAnW1gBIBnShQC2E5lJoroDmdbintnGvbjX3jlYy2vMhRs78E+LDvwsZ1TEYeRuAPKFzTeKjQp8qjZX2SKdc/MQUZJWuMQSJdhivgTtfxr/6a2Qv/ATZc/+QB03PM9a0jqlTFSSay0g3y4kuNSFlMTRdq/E6y030IXGqmERTKanWPLI9C/AGFpLpWoXftQE6PoDb+hLptkJSbYtwupbC6VVmYASCuRD6fWO/llrV27nQBid6l+L2rCfd9Sm48QV4cBQS9yFjCiqZ6Q8rQlwyaKGQdiHRbubSKAk8L2FLkqrqvUkPDpg3QIedtbf1qbRG3G4oGWiRsP9DZp7dmu/0gUAi1faWRV76Ssc8FkV4y0rJ8HohSJJBKSEJQbN92SiOPxqUBkrywFHdSNcsozXrPKL7cK/8IomeD5HUOLYXBmNQ8NStAY20T+uKwDKwgi3bUUyqq4Dk6RUGHMmeBaR6FpDpXozTucIAT/NzApPAkO1YOousJnHb5WMoB68YTpdCt3itFDpk2ZSYuT3a1kLXazjN20l2ljPds5oH3duZOP9ZmPg6+L08vj/II/H2De9kXphCG9peN+uS0QaJaS3JUpEBbUg/aXdl1TpqLdNNaOuvq7ao2d1quPUVvKufJzX0fxEd/D7G+j7CWM8Oome2MN27jrG29Yw2lTHZstSEX+nLh4FKaFday0Y4vRm6NuO0bTKZuYnOJWROL8KXGddeNDdqk6ottoMjqdaeCx1F0FmB172WdO9Wov0fxLn+4zD9v8A7axfOyMIxeTvSIirZM2FaUw5ADKjvQ69erfg5OEcdqzRqFQ5QqoYFR3hAwMxvZeKQmdXqOuHfBhCBRjG5YdIooU04u9Uxb0M6X1pR92h8qmEy3CLBXVOlS1eQTDC/qe2nJ0+QvfILTHa/xlR7LunORfid6rP8OZLOlXmWAxJOXTn4nctxO3NxO/Mtda00n9G5HDpWgpjemNgy11YabZPqqCDVWUqqU8DKM0I1073MaJx01xIe0VLrQ3etItOVZzQe/VXQVwI9EdLdEaY7lzLR/Tzu5Z+H+J+/O0AEjJBCgGgPakfFBVzHbHWVcFLGoTECVuMQMofpYY2N6uA8hPQgJI5A9HX86S/jTf4W0Zs/TvTqP2bq/A8x2fdJpk9vJdFdQbZD4FhrHT1FyLoK8bvKcNu3km7fQrxbEmaZ6UTaCwOAzKHVtY26z8NeZzV0VOJ1VZDpLWaqbwWT59YRv/YDMPoFSPWCmEUZJ1qVSNqYIZOoBI9vhIhhKPVByKN6L0YTQwZvw69kYs0s6Q21TQgQtSEYZrch0+ozk1EcACNYjz5jIpu5YJliYUJIYDrPmNCPcmm0Pj/JQ6a4yzSjpsCBWQKh8Uw8hFvVpPp/gWjnh4h2FpLuysE5LYZeOUdw5Btw6Xy/axm+wBEAxABOQk8CrK3IRkhbQodeJpL8xxzr/LeXmCCB07Eap6MCp7MEp6sQpyufbHcusZYc4go/ty0h2b6UlELAinLJMjGgWwYdEdxmmfMR3IEI8Z4iJrv+Jt7Fn353gMzUGnjrxlOqwOFbASTrW6TiZSFpd1UzZZ/FgEemmeeEeymo5pO83jH8dDskD8LUXnjwP+Dar+Ke/Qzprg+Sbi0j0zwfpyVCtjWC07aEbMdqMt2bSfZUkTxdjttVbBxEOiX5C3jqVuAyWiiUgrpeMV5XAU7PCtKDOUwN5jAyWMjEhe8iO/xvYbIBEhNGEIj39cyBR2Aqk5jl66GgCJk5ZPqA58OPH/Mhws42TC/zaRbjP/Ze380qHxSCT79hflzw0x3J5HvkG1ng6MZ0QmCO6TIKZHqPjtaZGipzmPacvPtnuAN/n2RrCamWZZaxThfA6aDPu/JgDmT6uLsUp6sct7PcmNq0r4Y2BWPWQnOQOd6kQMoaE8o1Gl9zKc2Knsq3CfwZ+Zptpfbc1rXQKv8kIJlSum57CX5HIZ78mI4VZsrCO6G5sgiJpgjxtgjZMxGifUsZ73wJZ+gH3h0g0haimbELNEooCbWb6Zg/kwQeBD89s/zd1uNQ7SbPTN0nHEhqP/UEJGKgTUgd1XkyVUDugXcJEi0w8jrc/E9w9V8YU8fpXkCyPUKiPUK6vYRM90bSfevJ9K3F7Q6BIXA8JWlQu1daEsA6iq0W6cjF61xKtlt+0HxSg88xPfgco70FjPZ+F6kLKox9GOIjNgYc+g1GSfhknCzxRIppVZcPlnTObi13iptnuQvSBobpW/u1AAAgAElEQVTBw0iSmFwSX+wqCqW/PhdApHmCc2bODZjecLaAIAqON5GpxwMBOl3Va6TgtUZf1T5mLC79XvYc2cu/Ded/EPrXQvcC6BDlQFe+te3nAIwQTJ7ModMFZE4X48gX7VDe3xpoXWNzAAWQpg3QpOUVa6BZ5rAm/wSMFdAus2uJpfaV0C5zW2NYZq/TVgkdG6FjA7Svx2+rxGkuI3WqhGRTEfGTinZuxu3cQra3nNRgKfGBKsb7XyN16Sdg/D+/O0A0UaS4dzijOns2VR0cDqM6Vqu8tVN2nAfEuE2Cm6S4Tdps7jhhlLhklzHZxAeu3Wdc+1QYZ1bF0hRvFnomJmCyBy7+PAy9QmZgAfFuAaSMbNdG3L5S/L58/O58mCudXgH986FP6l3Om6RMkYm6eJ0RXEXe+nLw+paT6VtJ7HQhk53rifV+DIZ+Dq5+Be6dhrG7kBizRd/MRpEJprwkDzOquWs1jPJ6JArUZ9Zx12KtoPxpaD4ZgIQH6Q91jCgAkzk3+D441jr5ykLW/Iwt56/fMBQIs3AjJNO+xWrzFVTw0wYoRvkId6lpstNv4D78Wcb7N+D0F0LfGji9Gjplii4BZXP3LA8ETC50Pz35PcvIDkQMub0r8but9raCShpB0UUBpgI6ZGYvg57n8PsieL05NkLasxB65sPpoO3VeNoxpW8x9OVCfwl+/zr8/m3Q9xp+/3dB/8dxej8DF34Xd+jLcPO/woMvkb31X0nf/EtTYhfn3nsHSAgSI/Vm/acCcyILHMFFal2p45pPuYNnViuqHcFjHOkWVQT0Xc9YWcbq0vyC4QchJli4p+IYIknqG79AamgLsf4ckt0FuKfL8HuKoEca4OkHJjxHA8Tgc/j98w3QvM5S/I4AIB3zcZXL02s1TLYzD6e7FG9gLe7AJjI9zxNt+YTdj+LqmzB2DNyztqIHWnSl1XYm99HssiugCCTCgl0LHdQoDRjdcrTtWBvynV3uZ5Yror4K+svCR9saq2qkStbY2YoQVo8BIzxvFkCM/2PGSoWwo5CagOlrZO/tYfziP+Nezxrigwtx+iK2n00EqBDkd3QrfC9aMecx8HtW4PblkO1fhNe7BL9nCfSE11WrlKcV+KdzcXsKSfWWEOtbw1R/FRP9m5ns20ayZysp0entJHu2E+/ZQaz3RaZ7X2Gq50Okzv0d0kM/gHv5x+DmL8Dd34SRL8DEV2ByP4xfIHvnEkQvgn/Njp+CTupETRTO4vU5vBUyZMTOIv09Q2FUJTQVQps4XLoqyRdIOyP9BLBAaEolhYffbyZ55WeZPqsiYItwJSVkTyoPTCZWz6q5Ue9y/L7F+P05RlPQuxxkW0ubGCqC7lXQLSCWQPdq6KrE75FEkgRbSeJUFdnOT8LQ5+D+VyDeaje1N7UxrPYI/TOjZV3XhMiduEs2ljUVFNPOFBlPJULF6KpwKVJwVaVoRCqXak2gpI8xV5Ne0JpAlN0YT6asjpMuMUVrfG2HbPfsMAWmFa71M2Qczd/ESKfDQndX7bzWw68Qv/gjTPR+gMmuzcS7V5s5oWz/KpyBHDzzzHm2j06vhNPqrzn2vcasu5xsy3YTmfT7lsPZCJyP4A3KUY4w2RkhdSFC8sJSYhe3Ebv4aaYv/Sumr/4Hpm7+B6K3fpvYtf9C4voXyd7+U3iwEyZk+nZCesguqXVGzF4hpjq+CnVoBaFK+GjORwWFJbFMirYV7D7jQSEP64c9I0AEs3BCUVPy+kFbKcIgcLbpICfG2MQCi25GIAm26TXhTlUWETPYpEBpFqPydfhkGu/OHuKX/qlxmJNKpOyQk7jeDpak/BzJ712FGRxjaklNSzqWQKfs10roEkgEkIKABMjlMBCx1CtToxS371WcMz+Ie+XX4OHXINkO/k18Rs0KxaSXJOlmTd1ps/4o0BxZL0nW1NC1GyGEhctsETNVXFHFS81oPwqKGbAEGkmgC0ldpe8eeR2BSacKHdkkmeQkWWkJV7pNY3AP6IP4Trw7nyd1/h+QHqjC61sJfUUwUIHTU066v4jk2RxSZxeSHViO17fKAuNZwBEAhK4PQOfL+D0FeAPzcM5FSJ2PED0zj9GBFSRvvED85qeJ3/4lUvf/B9mxo/iJPvDOABfsgjd3GNwR+1wh0wcaYCaiqh0lAtktv8vUT9beQmHcyFS/j5tKxyr7E/Zx5Bsmld46yfSOf+suQi9Erf7WyIcOp1UP8jmkKozvEah4fWTUh0BkTpF5oOrrsrJkuz8we1joigZX02M4t/6EyfNVTPVG8HsXwflSAwwx+JxI4JA2kLlm7NWF0KsJSGmRSujURFJpICVzQJqrV8eEtNisrNQMb6p7Gan+IjLnN+Fc+wT+7Z/CHf7PkD4JqSugOSP5zDJJg6Wd5tlCFaruMCnlvgmfy9FPOtrfS7P2tuC2ClUn3/Jv0plmyomZIngJ3xZTNf2tPhUJWWHgylTxiEL6ISRuQ6KD2J3PE7v+A8TOvkqmrwp61tgMhe4VZl5C/ldqYBWxMwXEzq4ieXYx2QEJBYEkz7TSpHMhc43+EhhcA4MbcPrKiPYuY2KwgOjlV0ne+imI1sPEdZiSbyrhK6tDGla1q4JAhfrQc021+2wmTiodJZGeJpqaCjYLst0gDn0raQysHBf/2cqKj8xVlR41vRj25tO2spPtTHCYKhEqDdMGdm94E2pnkwFJeEJQh0gAiZJkmltEGTaAMbeoJxs5TfL6DzN1tojU4AI4vwA0WP3LoF8O91O2koS9hdBTDL35oL/NZ7n2MzMLq+/0uX7nORiYB/0LoHeFOTbVtYBk7zwy/RGcs/Pwzi3COZtHZnAj8b6Pw93fgIf/G6ZaIH0zcOS1eUvW1OD1ZDNJBejBxcxhZwVDoWohUspWfEibqD69FnBpjYpMMn1jB9lEGnWNUEmbCIFCh5q3eQDuZUi2wsguYtf+iPGhX+Th4HczMbiGeO9yXK0HklaQ+dS1yKTe+P0ryAzkkzhTSvxsMalzS3DOLLL9HfbXXNv+JXjdETi3DC5WkT2zgdHTVYye+QjZe78M6Xq7kWKgIhXpVoFvdVnMc4m5jonAKZ9Q2M9mfLPSMZNNkHaiyHQN657ZfrLWibpodldbGaUIn0o8CYA2amgrKz4DQGzKxONMbwAgtRXSrJvRoiO7tkKFEe6ZTTWN3hNIBKYA4eoPYVll/RNmB4yslYKxEbMpZOrazzBxMY/xM2LK56B/SQCOubSLoE+OpsKYMtnKLEgGnoPBSHBtgUHREIFQQFF0ZAX+wDK8C4twLi4ge24h7uCSQJLmQW8xfs8asn1byJ79CM7lz+Ld/XUY/7pNy3HugqJ2GqnZYi3U7eFnihQnbAVDL+0bU0m5X9o2IasJSwFJnR5eR+CwHWjb2ChM9cCD1+H2b5C69hmmL36IyaF1TA+VkDxbQuZMAU7vIrPKLq3VmFps1rsAzhZBr8zHMpz+YgMUZyAXd2AZDEg4LXjUP6Zv1D9PQQOLyZ6O4A5GyAxFSFwoIXrxk2Tu/DokjoP/wFTz1opeJ4UpF6qa0Yp6ahMgU+ZUyHgrxxsmnFENto8MCtRZYehbroFsrVC6BBZN+L2ZdFXp0W8FQGZpCv1+KOGsWpR61IYuD5BDZMwsHSB//y1jLR4xm904U2aDeFIqqHoPRvYyeePT3DuziszZlTCwdI60BAYWghzEnnLoqYRe2d5LrcMop3FwCd5gLt5AkSEGVsLgUhhcjndmCdmhRTiXFsOlfLhQCufLYKDISGLNEDunl5DoXs5EVyljp19kcvAfkrr6y3D/yza12u8B9xw4lyGj4toPQflRiRTE3EfgERNkpU60h7N8Ny17jEImjukXTS5pdZ9209I+h8mzkFQm9p/DzX9n0vhj/a8x1VNMtH8B6XMRGFK4VH2QB2dXwJnnyPZFSPdE8Pol2eXbCSRltu0rAFH/SnMsZ2z/mD5RvzwtDS6BcxHivRHGTkeIDr0AD38dsifBVdjcagWlnaeUca6ijYGbq02BTJhTfaF+MTRr7/JQwDwGFplockQUPAoA8tj3gVkq4ATHRd5G/s9i7/DsJ7UhGnU3eh8au0Jq8LL6y3L/W9+H0k+XD7SIjb9oNyYb01fJRy+TxpeZoH23tVdf7AqJe/uYvvxLJBXbVkfPhfqXW80gp3Qgx4R8zaCfmR8AYyXeQB7uQBHuQImlwQLcMyvxzi7EPbuQZJ9MkGI4VwEXVsOFcjhTjNujXKXlMFiC119CuqeIeHehSWNI9pfinFtL8uJ2Jm/8LcZv/xDT93+S9Oj/B9NfhMROSJ+ATD8412xCaHYEU9hPrcwlkXcrAFcbJPeTnfxjEg9+hanhzzJ57buZurKVyaFyEufzyJ5bhX9mFQzkQ48icuUm58wsk+4shDOFcGkV/pUcspeso5wxgQgFLpbbYEWnzivARPsG50PQTwwoaDEHOpODfz5CvC+HidOvkLn4CzDRaKteah2OapYZ5ah6AFpeoK0lFPtXHyjJUoEGmUWWFMOTESVBrKkEV6onVABv5T39Lf4LNUjY6jOT8mN5O9Aguo2QW5+21U1Ir4tC2M4Cy+z8ovAm1M7GXPi5btpcR4FRXctmz5pGE4jZuO21dJLM5D0y9w8x1vd9JAfXkRkswT2z3A7aGZlHOVYTDIpJl+KdEc0C0oDMseXQK6koiRh5pDXOKtS43IJDgAgoa9o88zvuufkGIJwXcFS1cRVRrSfpzCGl+ZUzBTBURqYnD29A70vgSjFcWW4kt8yK6b4Ik5dzGL2Sz/iVtUxce4mpqx8nevUHiV/5KWKXfxnvzn/Bu/0l3Nt/gnvrT8ne/jMyt//MhDWzw3/M9LXfYPL6zzNx7UcYu/JJRi5t4eHFlYwMqdxAhNGBCNGBiIkOcUFh1FwYkLbcAF3roXuNiQhmOpeQ6FtI9sIS3GuL8a9H4FLE9ouWLGi+qUuRw1zokwZdaISE6degj42Qmq3N1e/qx8GVVgsP6rdX2n7vk+ZaTrwvzwQI0hc/B7e/DmMXIWHNJpM5bgAi01xb1N0K9pdX1oXdnFOTnOH+KWFrLRWBJvSPQ/4OzKgQLGL1t5LhQZkzOkfFq81LR+k1l1bnhNz+1l8L7CZdOryp2a0On/23uQd7YzN3Hn4fPokBXPgAw8Qe/jfunP8h7g++SOJSMdmhYGCv5sKFIvzBfOM0Z8+tIHt+Kd65pXBGJlng0A/KtJBJtQDOzTetf24R/tml+GeXPUbezN9Lsccstt+fWYEvmvl+1nmPfW7Ps781D//8PJyh+WSHFpAdWkxmaBmZ83lkzhaTOVNBZnAdqcGNpAY3kxrcSmpgu6HkYNhuJXlmM/Gz60meW0PyfCmpoVVkhhaTvTCf7IUIzoUI3lDESGr7fIvs8+q5B6VRVoHpg2Wmb7xzi3HOL8I7vwDf9IeOXwyDmlQNyPTXYnO8NJP61j+72PbhwCIQnVEfLsYZWk7qfB6pc6U4Z8vgrLSVwsjSTCXcaf0oYxd/Bab2WG2onXy1D6MsoWCLd+tiaApAQQlpEjnRllcfTarKyVbQSK2lGR6a4WvDYI/+C3krbB99M4OcZ5wHeeyK78Mfk2TSzTy8818YufpZoldfJHrWJpxxYQWcL8Y7U0j2bKFhnNTQMpzzGkgNYuC3nBWTv090TqCcZ+xw2eJzITGxf07MPFeyjDyXPpDAyJ7LI3s23wgII2gGF4EijGd1P4vInFtC4twK4mfzyZ4rsZpUWqx/vqm1Nn7mXzI9/HVIdmH3qlG6keVPhaslLi1ANBckTaKoXbBNYCBfv5WM920OEEmSGzjJg2Qe/g7pW59lerCS6e75NtJyvgD3bBHOuRLSQ/lkLyzHHVpow8NnckB0LgfOv1+ke3nOzB7PrdW5CnfrOnOlZ3j2czJp7YSiWbszKA2x/LE+VUg4O5hDdnAhvo6/WAgX8412muqvxB/5HfyYIlZK9VAoOmXTxGUkBJFNa5/IDxE47D6Nssol+L/Vr29zgMjXUSRMdmsjjH2BzOVPm5VhSUWmhlbinCsykit7vojs0ErcC2IoSevn4OxCOCfGegYmeaZz9du6HzH6XCiYC5ozOJ7x2c/Jj5A2CEAyWIF7Lh/3/DLcoRz8oQX4Z+bBWaslvbPPkT6zgtT5CjJXXiB54zPgVQPnbA6UP24mVJ1k1gaRAh9aGiPc0MZuSRGA4/8HhHybA0TLSpQHFofMXRvWfPgfyVz4W8QHC3AuLsW5UIBzvtSQO7QKLs7DOqvz4Px8OL8ILryPJI32rHRhIcyZnuHZBUwBQNGsc4vh/AqcoWIyFwpxLy6Ciza3yrSXrB80PbiUiaEPkb3972HyEDAUVBEZA2cSJxkjGU+YZd2O6xt/QuB45HAHfu3b+g3ffH3ybQ0Q9VEyyBq3AbQHkKiD4Z8mfqGM9JX5ZC6uMoMmkLhDeXbQNHBy5gUQMef7CpBFAUDm2M4ZGCGongEgQ4H/pPki9eeF+TgXVpG5mGcBoiiY+vpqBK5F8C+tJHbhg8Su/zKMd9mJUi3ZVl6eF8XNREmnEqb2bzqbQbvnWsfbAsR6JIFtFcaDvsVa5NseIJkw3V7uiJYxpgfgweeJXqkgcT1C5tJynKFC3POleOdnA2TeI8n9zEwWMtvTtrOYc2ixBerTtu/bvetZA2AYcFgweJciuJfmmwwDo60FjqsREzb2br8Gd34fJs7a1BpZyCYY5Zg9610nY0ubellcX4ZVOF0QtoH20DlyQtT+NUCerDbVN4pwKK0lE7VFOUwh5YdfYPL6ahK3IqQvLzKawztXDAKIBtVoEJk2YsqnZepv9vHSHIvnRkbzfbPv52muJ60R9Kf69DGah3dpHt61CPGLS5m8uJXM8Ocg3mUHLVwVocltOeOhoDM8H4ZsBQyFtNTOWkH51wB5MihmfxMCRGsjTDxQc5XOBKS/xtjtSkavRshcXYB3cSWcL7STZBpEqf4LS/AvrMC/mIN/acH7RIvs719cgj8n0r0vep/uXX22CG4sw72cg2f8uQVwcQlcXoh/KULsfITJC0VMX/t7ZLQvYKzT1uCSz+hlTI0CZTYrSjV7rtgu5HoLOKQuNOAijXdIsxniW/D+29zEUjzcIe27NpVewsZVbtJeRu+s5+H1COnr8+CSIlrSHsvh0jy4PM/Yw97lVfiXF5sB1aC+L3Rpsb2HS0ufukU5YJdz3p/7vrwQ70oO8cs5pK6thGv5cKUALmqCdjnOhRyiQ2vI3v8XpB9+hezEOUgZO9gWkvAn8bLKywusgEDGWQyEk8WB5ngrOEKQqP0Wv77NAaKYuGZYlbvl4GeVyKe850OM3N3G6M0QIDKllsIFMVMErszDubyK7JU8vCuL8a/Mf59oocl9EqMJqE/bKm/Kv6JrPAvN/dmz1+YzdT1CbHgp7s0KuFJhtfKFUvwrH8e9qYrpbZAew/fs/IWiUWaxljuFrw2LvgEgdgnFjGllEfNIY4RFML7FwAgv/20NEClnVTPMKn6ueirelF0qljnF6L0PMHYrggaRSznW11CI93IE/6qK2q8kbQAiJps7kzzrud5VK4kFjqemq88CDJ37bM+tvo3fWcz0neVMX80jeqGY5MX1cOP7YOSLEDsNWWUdWjNK/qIAYUBiFnBoCfAjDTLznQ1JfqPfEVhZOk6LpRT+tcgJ2fmb336bA8TD99K4qupoikQoy1MiqZ+Je59i4lYOzjXZxEpHj1jtEURU0tdXkL6+yiTmce053he6ugD/2iLcOZLO5apowbPRHJ9ffZu6XcbEjXxGrkcYv1lK+s6/gIk3ID5uI1WBby1RpjWAqqWmajZmnLQc4zGAyDmXnSxnUl58wP86XuCYmVlXzq6WI2vlvQb8W/f69gaIOtBRRpvWWA/bNdYSKpnrTN39DNO3i3CursLY6gLIFRuPd29ESN1YQuLmCsOc7ws4rj2Hb2gB7vUFFiRzaN8vcKjP3KsrSF5ea9Lqo3eex5n6p5B5E3zt92gDUI7WcHguGT9lSNEqJSEaVaLIVYAVtdb8CjPDNQEcHKcvtRRmJjdLK/VjM6b1tw4ez1zV5Ft5a+/h2gKIBI4q0JlU6LvBwDwgevcnid3egHe1CC4vseBQTP5GBO9WhMRwDonbS3FvLAQ58u8LzYfr8/FuiBbOoV0I156Rruse5vj8V3Nxr+yAG/8ERv4Akk1mrYakuoYl5vlmWWzKyZr14mZfu0BDSFPITJL8F+m91gLNFMkzi5ZmAWSWtlFJpYTZy16ZvZKI37rXt78Gyfi2IIJZTKNUaYFmgqm7v8T07VfIXiuxTBTM5gog7q0IyeH5hrybFjT6/BGJYcQ4Ak9Ilpm5MW/WcW85R98F5z1i+Hl4TzxH54fnBNc357/H999wXd3bbGafHwBoCVxdakkmp55p9rla+xHchwVreB2dn2OvoWMM5cD1HNRv2WtFMPxD8FD+Rp9d3aiSs6aMaYqEaoR4abP2/tEiJIFAzrnW1atVnlWoPULzSu1jDsfbahBpkb82sd5ROEj2hLULg8VVEiiph7jRL5Gd+H4SwyW4dyJwOwK3xAg5cHMZ7vB8nLsR0Hez6XYE//ZC/FvLcG8tnyH97d/KgdvPwXDE0h0da8m9GcG58RzpazmkruaQuLqI+JUFZG8vIDs8D2c4gnMngjdsSeeZ+7n5HNycPze6FcG/E8G9Z1u9N/cWXts8rwCRC0ZQlMD1fNBz6BkeO34+7u0cnGHRQtzh5+zz3iiAaysMOPxrEdwruTg38snciTA9vB7YbXaHxZ0GN2N3AJgpMiGtELzMG9lMoc7Qd/Z7e0w4saHv9X7Wef+nvXMNte266vg65+xzzj7Pe+7Nuff03pt3G1objG1ME7W9IpVQCTVSqpZUKkZMiSik2pp+CKgfzAcpVBFbNdoiFB/UQCBSIaCxRaGlEUKj1UaTe85+v9+P9V4/+c+51r773ua2+ZDmZF+yYbDW2WudNedce/zHGHOOMcfQDenqlT21pSNMVpP5e7P/eQ2Pi61BjLpo2fyFenN6twKI1yAYfgGv+wCj8gFBykAGJIe7cLhHUlw2zDVj9pTpzffFVcssxQ3C4gaRoXUiAUf/V7IMaRhMIBOVVgxDhUeb+IfbeEebuEdr+KVlw0xBeQ4gApWYV9pLx1ekZSjM0woUrqDisgG/gB6lNGN68/xlOBRAduHidRYcR1skxRU79jmA6DuBIyht4JUFEgsYLp6Bl09YgBw6hC/t4R+ewa+t06v+KPCNWVraLD3t/PE15NVjedSCA0RBbG0SJfkUQLIZn9cmGn+JsP8rDCoHeLWUoSVZ5wEiUBxtw+EpC5qjbZLChmEgaZ2M6SSZDSikPTIm1bmeV1mGSg7Ka1DKQ3ELSlvEpTxROWe0lJ5zuXRfsYx7tGo1wByDZ22a9tUHUUm0bLSeQJqRwBsW9ggLu/Z6phHNuASOdduOjuqrKAW3GY/uS7/XM/W8oLx+OUAO94y3XCBOjhyiQwmNMwT1c4waHzTlyuYBceX5sXD1a9jowgNEkaAJw0srI9IickxNvkwyfJhh5Rx+PZXyxSU4OgFHJ43Ej8s5OHwLXLzJHgsnoZg31y4zu8pLICqtXKJiDor6O2OyHJRWobgOZdEqSWWZuOIQV+fMOPWhoBCNbShsEpdXCGvWTAqrVx6XiCpLhFUdVwirK5cdo3KeqLBvSIBUW7N+q39qR6Q2pS10vWr7Y8ZeEqgtaOLSGmF5E7+Sx6+uEVbWDMiTw004WjX3xUUHX1TZJ27eRdB+xGQ3VMK7q9FryKvH8qhrACADU/4sVLmRTIOoypVqjkw/ybBy/rsBUjhBXF5CTBEfnic+vIm4cNL8PQNCYQcO9y1wdCxsg5hODJWZJjqXmXSZqSTQrBmQJBULkkQAEXOKStI8q1DYgKNdKJwkKl5HXLiOqHiSuHiCqLRDLO90OY8YWeBQfzXXENiiWnrUuUBS2jb3azy2jysWFCnzZyDIwGPGXs4ZcGZjEcAMQKpr+FVpPgFkjeRIgmDJ9F3j8CoOXv0MtD8Cg88DxauCQ6BZ9M+CA0TqYmQAIoetqvVaM0t5tP4VvN9nVLmZoGElp2XOXSjuoh87ruaIi6dJCgck5S0SmUoymaQBCqfg6ACOzkJhH4oblrkFDgMQSdVV4osOiZaOj7R8rIntBklph6SyTVzbJK6vkEiDZSSwGI0iIOVtO4XTcHTatqN2i3tQ3IGS2pQ2kgknU+6SFphpA2mfWo64sk5S3ki119y92f9Iu5W27DjLW8QpeM1zypqPbRFVdghqqwS1HFFV4F414zL3qJ26w7Tu4LbOQ+dRGP9zmsl/0WFw9f4vPEC0dq4sF0EYm4TEBiDBANxvgv8ZhtVb8RsOSU2MLem9C5LQ6Q8e1WQGrVqGETBKYsydOQYVYFKmFrPpXPMMAefoPMHhJkEhT1DcJSjvE1UPiOpvIWyeIWrv4TVX8VoOQdtS3HKImw5JMwWNeZ6kdEoFmWnSMK90FHA1n0iPpRxx3TECQMxrxqL5lsYqyjSXQCYAHp0nKZwnKe4bQOkdWNBdDSA5Qk329ZyWQ9R0GDUdJu3boPtn4B7aBGxX56+Fv7LgALGhCcqDpGTP0iIGICai97/A/3OGldssQIzUFhMKAFsWIA2HSFRPtUl5awYgM58QIPR/lzGbJvGnSApniUoHTKs7TGu7TGvXM629E7f2Ptz6B/DqP4vfuJ9h6f0My+9lXHkX49oPMandilu/Aa9+lrB+ykr8kky3V0tWc2VzHb+2wbSxjltfNeOUttSYYgkFM/fSsvSOAXRydKMBiLRmXNkgrl7SNJdpkPqy1SBVh1CTeD2n5eA3Hfoth3H73baisetjizIuPA6uOoCFB4h2nYmU7yJK4nQeotpuSjL2JOPq7YQtB2RmVVahvA2VzRlAdM1I9NoqSXUTypv2PgFDjNFO/7eYJzw8QVg4RVw5CXrZgg4AAAtoSURBVO1NktEq3bbDoJ/HG78L/Acg/AxET0P0gu1DUAXvJZh+E8ZfgcET0H2cpPVJks4DJK0fgc710DpH3NwnrO/h17bwqmu41WW8umx+B6/x3TSt5Um6dzOu30W3dJpBZQWv48DQgZEDfS3drpKUdqFyGqpnoLZPXN4lKGziyjko8NeXobpDUjtB1FgjauZIGjk7fr23ngNdh2HNodtycMf3wvg/bKzVnMviqly2wBcWHCByKcndZGM7zTZNpThX2Luv3K1fYVK7IwWImECTZwEkTyIp23TMtVAmT32JpLYC1ZRpxDiipv7OQ/mAuHQ9fuU00/oWk7ZDv+vQ7p+mN76bIHwQ+CPgqxBXLfMoM2ZGZiuEijMewvQ5m5zZ+xuYPgbex8F9CNwHYfIxkvFHiEcfJhrdz7DxfobNCwxb72XY+rHLqf4zMHiUuPfbBIMP4vVvZ9o9ybTtGLNO4Pc1udcSdG0DGinVNohKm4SFHMjUayxBfZu4sUvcXCdurUBTpPELaBlAlui0tnHHD8BEmeJTjb3AAPh+XV98gJgANoFEOkSe3DSpq+KzkmcZ1d5NIKmqH7y6DtUtqK0bE0TAkLQUGUbINI00R00T9h2oHED5RpLqzfiNc0xaJ+h3lul2HarNk/T6v8Zw9DmI/xH4lg2YNHn6bbIVw0RZaQOFsmq/ihIuKwI5Ua5ZBVkeXkEXbTkwlQTzXgTvf9KjzkWqN/J/4L4I4+fBfxaSv4LwEdz+Bbr1M3SqDoOqw7TmmFU8CQOjDVtL0MpBbQ2qcyCob84BRPdYs8ocew5xZ4lBbYtu++1Mp58CL417e1ODfD+MHd/1zDeo1V3l3FNu1kRhpAohVV3j+BvG/Ai7S9CUFM1DbRsa6ySadIrqW0SSrGIgMYWOAkhVK0L7UD5PVLkBt3aGcWufQfeAweAWBoMfptv7RfzpU/iT75AombRSYipUNTH1XAh8peyPbck1PyJRhgl5+udJ4eAaQLZMHdnVOFVDMqtyuq65laK/rzjOIgdUU8/klnoK3MeYdO6jU7uJTjXHpOnga5wyFWe0DNIS+jsDQiNP3Ngmaq0TtZcu3avrPYewk6PfOE2v89P43mchTOv4Lf5K7vdk4IXWIBlAxDeKH1X5MlOlT3HRRv0/z6R+D1FvGdrr1sSo70Azbxggbmsyu2fImFIZQBrSNntQvc7Y5V4jz6jt0Ovs0u/dyWT0q0STJ0imXzf17xJhMiviog2NgUK8lSAwxo083GiKH3oEQWTvU6oi5eFWOq8AVB5bKf7NMbT15ZXuX3Xm9RyVZ1ZMplFEc0cpJBNBYMKYhKgaRP8O7ufwex9l1Lwdt3OCsOsQSYvOAJKedx3Ivm+tkbS2iNt54s6y/V7XDUBWCDp5hs23Mug+SBT+A9A3+zNM+9+TxRb74jUEEC33XgmQbzNt/ARxfwU6eWhuQmPbAqTjkHQEkG2o71oTbAYQzTs2jV0uDeO39ph0rmc6uIA3fgS8v4egOB93Zwq8yKpTni5PlY5izYtk9qkYp6JOxzY1v8K2Vc5R6wjTtE55Visv3RCUKhS7IGeUi4LzsgC9YC7LoA0X97VXQgGwZhVPCRFeAO8JGD5E3LsLBmegl7NMn40xM7kEGoGklSNpbbwyQDrrBJ0NRq07mPQfI4m+ZnZwqp/XuALJsrsvJsqNBpltotEOs4HdU6BfTltEoheZNt9HPJREzENrywKktW5XZnoOSVvmRg5km18pYVs5osZJovZ7oKeUNV8A7zkIW2memjTwVB2RRSdGjxLCWKtq6o9KgGXFgurEtEzcWKLiLaaSZEzsTYi9MYk/MWSrsGpvvW/J7ItIH64G5klGZTRmjGtSH6kP1nyTSvoOeE9C52EY/DgMdu2YBRBjQq5BffWSpmivQnuDpLNB0l0xq1ZaudJ7STqb+J0dxq27mfY/C8l/ktAzuzmUSf1a/iy+BplJ3WzDjSoHmdJUEB/Rb96HPxRzbEB7DVoyr1ZIeg7RwCHpWk0ibWKo6xB3HWNSuK0bGFcvEDQ/AcOnIaxdmj+oqJFKHqkSkeFKa+jZdTUFUSqZRB8vruFTMRSmZecS7Z8XghPXFoFRIRjZW7Fr615okm9SqgagIhmKo8lIdpUSganZOGIYdEyZumy/t9EiMi81B4vK0Pw76PwOcfcCQec0QTN1LMr7LoAIBKIUIFq+pnNJgFjBsYHbyzPs3sN08NeQaGGhk9by07iv3c9CA0RAMOE+EmLSGjqa8lppYQma+NGniZO7jEc7C/kwXmzXIZSvYOLA2B4j18FzHSbuHsPBXXRbvwxodep/LcOKKWecqMYyu0bnGYlZdG73O1hO1n0Z6SGXwDQ7NzPwbD/qFUcB/pXIlAHQ8oTmX5bsttW0CfVV5L4Mk7/EG/wS7vBtuON1omkOvHW8wSphb90KjqY07J4xtYKuJubWl8JwnUnPYTB8D/CMWYyIgxrE3VQ4vAmQN+wbmAEkE+RGoqcOQwZMkj8k4l6C3qaVlNmk1F3DFUCCJZg6uAP5Ndbo925hNLmPIPhd4lCZxwvWrMmePzO89YVE9fFJUJk3mulYcNgkBjo3XbQYtQARSLxvEbt/QeB+FHf6TsajLYajJcbjNYLhBnRWQaZnW9p225il8UDaJQ+DTaaDJUbjnySOv27BqoDQWJrw+Mb/ejDlYmuQbJIoZsgY+DKAjHD5Y+B+kuGe9TDL6dVeIh6fYNhdI/KW8CcO49Eqo94dTFufhsHTELycMoCYQMtOWWNiCGkDgUNHXTiejwWIACESWNJIm6yrpm/qZ5r1JX4egi8RTn7DLFO3uuuM/FWCqQMCgzzm/TUQYCZ5GG9D6xR0zuIODphMfoFQBUfN+5apl6YsOZ7hvy6tLjRAZHWIKYz5MbNabLoY41tgyjT+PAk/TzLcTwGi5cwNgv4NdJtnGfZPMRnfSOz/FISPgvcv4CoaODVPDP8LfQKD3OFyjeuo744PHJY7sjiCOXCkczKZWppIJ5RT56Wck/JdfBvcv8V1H2Ls3s3QO4fnrs8BxCEZrRBNNmC8B63T0LqFYHAn/vS3CIKL1m+TCST9CNfw55oAiPmNMvEp71qWewmPSfBF4vhjBL2zYPwh20T1A/zunXRq9zDs30sw+TgEXwSesxNQ1S9XbXIpjxkOBAyFr6RfqtHjxkfaB5mZOrUaRWDRUvDYACSmSmKqwk7AV7HxLgT/DclTwOOMph/And5KMsgZEzToOfgDB3+cIx5uQ/skNG8j6X+I2PtT/KBpMi3JspL/xzT8JkDemG9ATJFVHJrZF2ZZNPVOyzoPv0wS/Tpe+3oSrWI194kb74DRzzHuChh/AsE/QfCSRYRQEcuZEZo0v+a5BggyVQQO1dhOwaHvdX5cH7UtzWnUqLqiRGpKhdMzWUOSNHtIGA8J/AmhOzXLyoQaR9XsJ/emjxO5H4bRLdBfwu87TAcOk5FDMNIqV564+TYYPAzBk3hB2zgtzWt+EyDH9cu/unYlMTVFNdktLFpsPIYWgQzTyAR5BpJH8btvNev5tG+G3gWIPwHTL0DUtNaTvG3hBCLtb1fohkgJ6dKJuJ4vEijm6dV19Qdzl/ohJpWWM1pEDskyCSUSswwbGLdJpKGFIUE0IIx7JhvlDPj+C2ZbANMPwehGgvEy3sRhqlU+1yHpO8Stm2D0KYifwY2qxtgMtYqctvuDGdwb46kLbmLNAyQtMGEcaRlA9JL/Dfg9wt7boasVmnfA+D7gD4BnLf9rSiFGk3POVDxSphTFVknKyqxKJ+kCXSaxj1t7aGjqg6ZGM0kuR+nLJLyUAiSe1d2QqIgZEtEhSnzj+Y+MM1UhKl8F/zfBvYPE3cL3HfzQIQwdkoEins/B+DHga0ySkpmeyRUj18yxatDXAUP/Dzulf7mPSc8LAAAAAElFTkSuQmCC +``` + +### `annotation` + +A Kubernetes annotation for the NavLink custom resource. + +### `label` + +A Kubernetes label for the NavLink custom resource. + +### `sideLabel` + +Label that appears in the left navigation bar + +### `target` + +Sets the target property of the link's anchor tag (``), which (depending on browsers) determines if it opens in a new window or in an existing tab. + +The default value is `_self`, which opens the link on the current tab. To open the link in a new window or tab, set the target to `_blank`. + +For more information about the target property, see [this page.](https://www.w3schools.com/tags/att_a_target.asp) + +### `toService` + +Has five fields that are constructed to create a URL like the following: `https:///k8s/clusters//k8s/namespace//service/::/proxy/` + +For example, a link to a monitoring service can be set up as follows: + +- name: `rancher-monitoring-grafana` +- namespace: `cattle-monitoring-system` +- path: `proxy/?orgId=1` +- port: `"80"` +- scheme: `http` + +It is required to provide either the `toService` directive or the `toURL` directive. + +### `toUrl` + +Can be any link, even to links outside of the cluster. + +It is required to provide either the `toService` directive or the `toURL` directive. + +## Link Examples + +### Example of Link with `toUrl` + +This example NavLink YAML shows an example of configuring a NavLink to a Grafana dashboard: + +```yaml +apiVersion: ui.cattle.io/v1 +kind: NavLink +metadata: + name: grafana +spec: + group: "Monitoring Dashboards" + toURL: https:///api/v1/namespaces/cattle-monitoring-system/services/http:rancher-monitoring-grafana:80/proxy/?orgId=1 +``` + +Adding the above YAML results in a link to Grafana being created, as shown in the following screenshot: + +![Screenshot of Grafana Link](/img/example-grafana-link.png) + +### Example of Link with `toService` + +This example YAML shows an example of `toService` used for the link target: + +```yaml +apiVersion: ui.cattle.io/v1 +kind: NavLink +metadata: + annotations: + key: annotation + labels: + key: label + name: navlinkname +spec: + description: This is a description field # Optional. + group: "group1" # Optional. If not provided, the links appear standalone. + iconSrc: data:image/jpeg;base64,[icon source string is clipped for brevity] + label: This is a label # Optional. + sideLabel: A side label. # Optional. + target: _blank #Optional. _blank opens the link in a new tab or window. + toService: # toService or #toUrl needs to be provided. + name: rancher-monitoring-grafana + namespace: cattle-monitoring-system + path: proxy/?orgId=1 + port: "80" + scheme: http +``` + +Adding the `toService` parameters above results in a link to Grafana being created, as shown in the following screenshot: + +![Screenshot of Grafana Link](/img/example-service-link.png) + diff --git a/versioned_docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/global-default-private-registry.md b/versioned_docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/global-default-private-registry.md new file mode 100644 index 00000000000..b9847ee8d9f --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/global-default-private-registry.md @@ -0,0 +1,73 @@ +--- +title: Configuring a Global Default Private Registry +--- + + + + + +:::note +This page describes how to configure a global default private registry from the Rancher UI, after Rancher is already installed. + +For instructions on how to set up a private registry during Rancher installation, refer to the [air-gapped installation guide](../../../getting-started/installation-and-upgrade/other-installation-methods/air-gapped-helm-cli-install/air-gapped-helm-cli-install.md). + +::: + +A private registry is a private, consistent, and centralized source of truth for the container images in your clusters. You can use a private container image registry to share custom base images within your organization. + +There are two main ways to set up a private registry in Rancher: + +* Set up a global default registry through the **Settings** tab in the global view. +* Set up a private registry in the advanced options under cluster-level settings. + +The global default registry is intended to be used in air-gapped setups, for registries that don't require credentials. The cluster-level private registry is intended to be used in setups where the private registry requires credentials. + +## Set a Private Registry with No Credentials as the Default Registry + +1. Log into Rancher and configure the default administrator password. +1. Select **☰ > Global Settings**. +1. Go to `system-default-registry` and choose **⋮ > Edit Setting**. +1. Enter your registry's hostname and port (e.g. `registry.yourdomain.com:port`). Do not prefix the text with `http://` or `https://`. + +**Result:** Rancher pulls system images from your private registry. + +### Namespaced Private Registry with RKE2 Downstream Clusters + +Most private registries should work, by default, with RKE2 downstream clusters. + +However, you'll need to do some additional steps if you're trying to set a namespaced private registry whose URL is formated like this: `website/subdomain:portnumber`. + +1. Select **☰ > Cluster Management**. +1. Find the RKE2 cluster in the list and click **⋮ >Edit Config**. +1. From the **Cluster config** menu, select **Registries**. +1. In the **Registries** pane, select the **Configure advanced containerd mirroring and registry authentication options** option. +1. In the text fields under **Mirrors**, enter the **Registry Hostname** and **Mirror Endpoints**. +1. Click **Save**. +1. Repeat as necessary for each downstream RKE2 cluster. + +## Configure a Private Registry with Credentials when Creating a Cluster + +There is no global way to set up a private registry with authorization for every Rancher-provisioned cluster. Therefore, if you want a Rancher-provisioned cluster to pull images from a private registry that requires credentials, you'll have to pass the registry credentials through the advanced cluster options every time you create a new cluster. + +Since the private registry cannot be configured after the cluster is created, you'll need to perform these steps during initial cluster setup. + +1. Select **☰ > Cluster Management**. +1. On the **Clusters** page, click **Create**. +1. Choose a cluster type. +1. In the **Cluster Configuration** go to the **Registries** tab. +1. Check the box next to **Enable cluster scoped container registry for Rancher system container images**. +1. Enter the registry hostname. +1. Under **Authentication** select **Create a HTTP Basic Auth Secret** and fill in the credential fields. +1. Click **Create**. + +**Result:** The new cluster pulls images from the private registry. + +### Working with Private Registry Credentials + +When working with private registries, it is important to ensure that any secrets created for these registries are properly backed up. When you add a private registry credential secret through the Rancher GUI and select **Create a HTTP Basic Auth Secret**, the secret is included in backup operations using Rancher Backups. + +However, if you create a credential secret outside of the Rancher GUI, such as by using kubectl or Terraform, you must add the `fleet.cattle.io/managed=true` label to indicate that the secret should be included in backups created by Rancher Backups. + +For example, if you have a custom private registry named "my-private-registry" and create a secret called "my-reg-creds" for it, apply the `fleet.cattle.io/managed=true` label to this secret. This ensures that your backup process captures the secret, providing easy restoration if needed. + +By following this guidance, you can ensure that all of your private registry credentials are backed up and easily accessible in the event of a restore or migration. diff --git a/versioned_docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/jwt-authentication.md b/versioned_docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/jwt-authentication.md new file mode 100644 index 00000000000..7bfe5a19bbe --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/jwt-authentication.md @@ -0,0 +1,17 @@ +--- +title: JSON Web Token (JWT) Authentication +--- + + + + +Many 3rd party integrations available for Kubernetes, such as GitLab and HashiCorp Vault, involve giving an external process access to the Kubernetes API using a native Kubernetes Service Account token for authentication. + +In Rancher v2.9.0 and later, service accounts on downstream clusters can now authenticate through a JSON web token (JWT) using the Rancher authentication proxy. In Rancher versions earlier than v2.9.0, only Rancher-issued tokens were supported. + +To enable this feature, follow these steps: + +1. In the upper left corner, click **☰ > Cluster Management**. +1. Click **Advanced** to open the dropdown menu. +1. Select **JWT Authentication**. +1. Click the checkbox for the cluster you want to enable JWT authentication for, and click **Enable**. Alternatively, you can click **⋮** > **Enable**. diff --git a/versioned_docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/cluster-and-project-roles.md b/versioned_docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/cluster-and-project-roles.md new file mode 100644 index 00000000000..8d4c6dd8ad9 --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/cluster-and-project-roles.md @@ -0,0 +1,274 @@ +--- +title: Cluster and Project Roles +--- + + + + + +Cluster and project roles define user authorization inside a cluster or project. + +To manage these roles, + +1. Click **☰ > Users & Authentication**. +1. In the left navigation bar, click **Role Templates** and go to the **Cluster** or **Project/Namespaces** tab. + +### Membership and Role Assignment + +The projects and clusters accessible to non-administrative users is determined by _membership_. Membership is a list of users who have access to a specific cluster or project based on the roles they were assigned in that cluster or project. Each cluster and project includes a tab that a user with the appropriate permissions can use to manage membership. + +When you create a cluster or project, Rancher automatically assigns you as the `Owner` for it. Users assigned the `Owner` role can assign other users roles in the cluster or project. + +:::note + +Non-administrative users cannot access any existing projects/clusters by default. A user with appropriate permissions (typically the owner) must explicitly assign the project and cluster membership. + +::: + +### Cluster Roles + +_Cluster roles_ are roles that you can assign to users, granting them access to a cluster. There are two primary cluster roles: `Owner` and `Member`. + +- **Cluster Owner:** + + These users have full control over the cluster and all resources in it. + +- **Cluster Member:** + + These users can view most cluster level resources and create new projects. + +#### Custom Cluster Roles + +Rancher lets you assign _custom cluster roles_ to a standard user instead of the typical `Owner` or `Member` roles. These roles can be either a built-in custom cluster role or one defined by a Rancher administrator. They are convenient for defining narrow or specialized access for a standard user within a cluster. See the table below for a list of built-in custom cluster roles. + +#### Cluster Role Reference + +The following table lists each built-in custom cluster role available and whether that level of access is included in the default cluster-level permissions, `Cluster Owner` and `Cluster Member`. + +| Built-in Cluster Role | Owner | Member | +| ---------------------------------- | ------------- | --------------------------------- | +| Create Projects | ✓ | ✓ | +| Manage Cluster Backups             | ✓ | | +| Manage Cluster Catalogs | ✓ | | +| Manage Cluster Members | ✓ | | +| Manage Nodes [(see table below)](#Manage-Nodes-Permissions)| ✓ | | +| Manage Storage | ✓ | | +| View All Projects | ✓ | | +| View Cluster Catalogs | ✓ | ✓ | +| View Cluster Members | ✓ | ✓ | +| View Nodes | ✓ | ✓ | + +#### Manage Nodes Permissions + +The following table lists the permissions available for the `Manage Nodes` role in RKE and RKE2. + +| Manage Nodes Permissions | RKE | RKE2 | +|-----------------------------|-------- |--------- | +| SSH Access | ✓ | ✓ | +| Delete Nodes | ✓ | ✓ | +| Scale Clusters Up and Down | ✓ | * | +***In RKE2, you must have permission to edit a cluster to be able to scale clusters up and down.** +
+ +For details on how each cluster role can access Kubernetes resources, you can look them up in the Rancher UI: + +1. In the upper left corner, click **☰ > Users & Authentication**. +1. In the left navigation bar, click **Role Templates**. +1. Click the **Cluster** tab. +1. Click the name of an individual role. The table shows all of the operations and resources that are permitted by the role. + +:::note + +When viewing the resources associated with default roles created by Rancher, if there are multiple Kubernetes API resources on one line item, the resource will have `(Custom)` appended to it. These are not custom resources but just an indication that there are multiple Kubernetes API resources as one resource. + +::: + +### Giving a Custom Cluster Role to a Cluster Member + +After an administrator [sets up a custom cluster role,](custom-roles.md) cluster owners and admins can then assign those roles to cluster members. + +To assign a custom role to a new cluster member, you can use the Rancher UI. To modify the permissions of an existing member, you will need to use the Rancher API view. + +To assign the role to a new cluster member, + + + + +1. Click **☰ > Cluster Management**. +1. Go to the cluster where you want to assign a role to a member and click **Explore**. +1. Click **RBAC > Cluster Members**. +1. Click **Add**. +1. In the **Cluster Permissions** section, choose the custom cluster role that should be assigned to the member. +1. Click **Create**. + + + + +1. Click **☰ > Cluster Management**. +1. Go to the cluster where you want to assign a role to a member and click **Explore**. +1. Click **Cluster > Cluster Members**. +1. Click **Add**. +1. In the **Cluster Permissions** section, choose the custom cluster role that should be assigned to the member. +1. Click **Create**. + + + + +**Result:** The member has the assigned role. + +To assign any custom role to an existing cluster member, + +1. Click **☰ > Users & Authentication**. +1. Go to the member you want to give the role to. Click the **⋮ > Edit Config**. +1. If you have added custom roles, they will show in the **Custom** section. Choose the role you want to assign to the member. +1. Click **Save**. + +**Result:** The member has the assigned role. + +### Project Roles + +_Project roles_ are roles that can be used to grant users access to a project. There are three primary project roles: `Owner`, `Member`, and `Read Only`. + +- **Project Owner:** + + These users have full control over the project and all resources in it. + +- **Project Member:** + + These users can manage project-scoped resources like namespaces and workloads, but cannot manage other project members. + +:::note + +By default, the Rancher role of `project-member` inherits from the `Kubernetes-edit` role, and the `project-owner` role inherits from the `Kubernetes-admin` role. As such, both `project-member` and `project-owner` roles will allow for namespace management, including the ability to create and delete namespaces. + +::: + +- **Read Only:** + + These users can view everything in the project but cannot create, update, or delete anything. + +:::danger + +Users assigned the `Owner` or `Member` role for a project automatically inherit the `namespace creation` role. However, this role is a [Kubernetes ClusterRole](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#role-and-clusterrole), meaning its scope extends to all projects in the cluster. Therefore, users explicitly assigned the `owner` or `member` role for a project can create namespaces in other projects they're assigned to, even with only the `Read Only` role assigned. + +::: + +#### Custom Project Roles + +Rancher lets you assign _custom project roles_ to a standard user instead of the typical `Owner`, `Member`, or `Read Only` roles. These roles can be either a built-in custom project role or one defined by a Rancher administrator. They are convenient for defining narrow or specialized access for a standard user within a project. See the table below for a list of built-in custom project roles. + +#### Project Role Reference + +The following table lists each built-in custom project role available in Rancher and whether it is also granted by the `Owner`, `Member`, or `Read Only` role. + +| Built-in Project Role | Owner | Member | Read Only | +| ---------------------------------- | ------------- | ----------------------------- | ------------- | +| Manage Project Members | ✓ | | | +| Create Namespaces | ✓ | ✓ | | +| Manage Config Maps | ✓ | ✓ | | +| Manage Ingress | ✓ | ✓ | | +| Manage Project Catalogs | ✓ | | | +| Manage Secrets | ✓ | ✓ | | +| Manage Service Accounts | ✓ | ✓ | | +| Manage Services | ✓ | ✓ | | +| Manage Volumes | ✓ | ✓ | | +| Manage Workloads | ✓ | ✓ | | +| View Secrets | ✓ | ✓ | | +| View Config Maps | ✓ | ✓ | ✓ | +| View Ingress | ✓ | ✓ | ✓ | +| View Project Members | ✓ | ✓ | ✓ | +| View Project Catalogs | ✓ | ✓ | ✓ | +| View Service Accounts | ✓ | ✓ | ✓ | +| View Services | ✓ | ✓ | ✓ | +| View Volumes | ✓ | ✓ | ✓ | +| View Workloads | ✓ | ✓ | ✓ | + +:::note Notes: + +- Each project role listed above, including `Owner`, `Member`, and `Read Only`, is comprised of multiple rules granting access to various resources. You can view the roles and their rules on the Global > Security > Roles page. +- When viewing the resources associated with default roles created by Rancher, if there are multiple Kubernetes API resources on one line item, the resource will have `(Custom)` appended to it. These are not custom resources but just an indication that there are multiple Kubernetes API resources as one resource. +- The `Manage Project Members` role allows the project owner to manage any members of the project **and** grant them any project scoped role regardless of their access to the project resources. Be cautious when assigning this role out individually. + +::: + +### Defining Custom Roles +As previously mentioned, custom roles can be defined for use at the cluster or project level. The context field defines whether the role will appear on the cluster member page, project member page, or both. + +When defining a custom role, you can grant access to specific resources or specify roles from which the custom role should inherit. A custom role can be made up of a combination of specific grants and inherited roles. All grants are additive. This means that defining a narrower grant for a specific resource **will not** override a broader grant defined in a role that the custom role is inheriting from. + +#### UpdatePSA For Project Level + +About defining custom roles, you can grant permission to a user to create or update *PSA* policies when defining namespaces within projects. + +To do so, you can use the following `RoleTemplate` to be applied on the cluster: + +```yaml +apiVersion: management.cattle.io/v3 +builtin: false +context: project +description: '' +displayName: Manage PSA Labels +external: false +hidden: false +kind: RoleTemplate +metadata: + name: namespaces-psa +rules: + - apiGroups: + - management.cattle.io + resources: + - projects + verbs: + - updatepsa +``` + +When creating a new project (from the **Members** tab), click **Add** to add the user and select **Custom** > **Create Namespaces** (to allow the user to create namespaces). Then click **Add** again and select `UpdatePSA` project role template from the list of **Project Permissions**. + +### Default Cluster and Project Roles + +By default, when a standard user creates a new cluster or project, they are automatically assigned an ownership role: either [cluster owner](#cluster-roles) or [project owner](#project-roles). However, in some organizations, these roles may overextend administrative access. In this use case, you can change the default role to something more restrictive, such as a set of individual roles or a custom role. + +There are two methods for changing default cluster/project roles: + +- **Assign Custom Roles**: Create a [custom role](custom-roles.md) for either your [cluster](#custom-cluster-roles) or [project](#custom-project-roles), and then set the custom role as default. + +- **Assign Individual Roles**: Configure multiple [cluster](#cluster-role-reference)/[project](#project-role-reference) roles as default for assignment to the creating user. + + For example, instead of assigning a role that inherits other roles (such as `cluster owner`), you can choose a mix of individual roles (such as `manage nodes` and `manage storage`). + +:::note + +- Although you can [lock](locked-roles.md) a default role, the system still assigns the role to users who create a cluster/project. +- Only users that create clusters/projects inherit their roles. Users added to the cluster/project membership afterward must be explicitly assigned their roles. + +::: + +### Configuring Default Roles for Cluster and Project Creators + +You can change the cluster or project role(s) that are automatically assigned to the creating user. + +1. In the upper left corner, click **☰ > Users & Authentication**. +1. In the left navigation bar, click **Role Templates**. +1. Click the **Cluster** or **Project/Namespaces** tab. +1. Find the custom or individual role that you want to use as default. Then edit the role by selecting **⋮ > Edit Config**. +1. In the **Cluster Creator Default** or **Project Creator Default** section, enable the role as the default. +1. Click **Save**. + +**Result:** The default roles are configured based on your changes. Roles assigned to cluster/project creators display a check in the **Cluster/Project Creator Default** column. + +If you want to remove a default role, edit the permission and select **No** from the default roles option. + +### Cluster Membership Revocation Behavior + +When you revoke the cluster membership for a standard user that's explicitly assigned membership to both the cluster _and_ a project within the cluster, that standard user [loses their cluster roles](#cluster-roles) but [retains their project roles](#project-roles). In other words, although you have revoked the user's permissions to access the cluster and its nodes, the standard user can still: + +- Access the projects they hold membership in. +- Exercise any [individual project roles](#project-role-reference) they are assigned. + +If you want to completely revoke a user's access within a cluster, revoke both their cluster and project memberships. + +### External `RoleTemplate` Behavior + +In Rancher v2.9.0 and later, external `RoleTemplate` objects can only be created if the backing `ClusterRole` exists in the local cluster or the `ExternalRules` is set in your configuration. + +For context, the backing `ClusterRole` holds cluster rules and privileges, and shares the same `metadata.name` used in the `RoleTemplate` in your respective cluster referenced by the `ClusterRoleTemplateBinding/ProjectRoleTemplateBinding`. Additionally, note that `escalate` permissions on `RoleTemplates` are required to create external `RoleTemplates` with `ExternalRules`. diff --git a/versioned_docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/custom-roles.md b/versioned_docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/custom-roles.md new file mode 100644 index 00000000000..7f44a211cf4 --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/custom-roles.md @@ -0,0 +1,124 @@ +--- +title: Custom Roles +--- + + + + + +Within Rancher, _roles_ determine what actions a user can make within a cluster or project. + +Note that _roles_ are different from _permissions_, which determine what clusters and projects you can access. + +:::danger + +It is possible for a custom role to enable privilege escalation. For details, see [this section.](#privilege-escalation) + +::: + + +## Prerequisites + +To complete the tasks on this page, one of the following permissions are required: + + - [Administrator Global Permissions](global-permissions.md). + - [Custom Global Permissions](global-permissions.md#custom-global-permissions) with the [Manage Roles](global-permissions.md) role assigned. + +## Creating A Custom Role + +While Rancher comes out-of-the-box with a set of default user roles, you can also create default custom roles to provide users with very specific permissions within Rancher. + +The steps to add custom roles differ depending on the version of Rancher. + +1. In the upper left corner, click **☰ > Users & Authentication**. +1. In the left navigation bar, click **Role Templates**. +1. Select a tab to determine the scope of the role you're adding. The tabs are: + + - **Global:** The role is valid for allowing members to manage global scoped resources. + - **Cluster:** The role is valid for assignment when adding/managing members to clusters. + - **Project/Namespaces:** The role is valid for assignment when adding/managing members to projects or namespaces. + +1. Click **Create Global Role,** **Create Cluster Role** or **Create Project/Namespaces Role,** depending on the scope. +1. Enter a **Name** for the role. +1. Optional: Choose the **Cluster/Project Creator Default** option to assign this role to a user when they create a new cluster or project. Using this feature, you can expand or restrict the default roles for cluster/project creators. + + > Out of the box, the Cluster Creator Default and the Project Creator Default roles are `Cluster Owner` and `Project Owner` respectively. + +1. Use the **Grant Resources** options to assign individual [Kubernetes API endpoints](https://kubernetes.io/docs/reference/) to the role. + + > When viewing the resources associated with default roles created by Rancher, if there are multiple Kubernetes API resources on one line item, the resource will have `(Custom)` appended to it. These are not custom resources but just an indication that there are multiple Kubernetes API resources as one resource. + + > The Resource text field provides a method to search for pre-defined Kubernetes API resources, or enter a custom resource name for the grant. The pre-defined or `(Custom)` resource must be selected from the dropdown, after entering a resource name into this field. + + You can also choose the individual cURL methods (`Create`, `Delete`, `Get`, etc.) available for use with each endpoint you assign. + +1. Use the **Inherit from** options to assign individual Rancher roles to your custom roles. Note: When a custom role inherits from a parent role, the parent role cannot be deleted until the child role is deleted. + +1. Click **Create**. + +## Creating a Custom Role that Inherits from Another Role + +If you have a group of individuals that need the same level of access in Rancher, it can save time to create a custom role in which all of the rules from another role, such as the administrator role, are copied into a new role. This allows you to only configure the variations between the existing role and the new role. + +The custom role can then be assigned to a user or group so that the role takes effect the first time the user or users sign into Rancher. + +To create a custom role based on an existing role, + +1. In the upper left corner, click **☰ > Users & Authentication**. +1. In the left navigation bar, click **Role Templates**. +1. Click the **Cluster** or **Project/Namespaces** tab. Click **Create Cluster Role** or **Create Project/Namespaces Role** depending on the scope. Note: Only cluster roles and project/namespace roles can inherit from another role. +1. Enter a name for the role. +1. In the **Inherit From** tab, select the role(s) that the custom role will inherit permissions from. +1. In the **Grant Resources** tab, select the Kubernetes resource operations that will be enabled for users with the custom role. + + > The Resource text field provides a method to search for pre-defined Kubernetes API resources, or enter a custom resource name for the grant. The pre-defined or `(Custom)` resource must be selected from the dropdown, after entering a resource name into this field. +1. Optional: Assign the role as default. +1. Click **Create**. + +## Deleting a Custom Role + +When deleting a custom role, all global role bindings with this custom role are deleted. + +If a user is only assigned one custom role, and the role is deleted, the user would lose access to Rancher. For the user to regain access, an administrator would need to edit the user and apply new global permissions. + +Custom roles can be deleted, but built-in roles cannot be deleted. + +To delete a custom role, + +1. In the upper left corner, click **☰ > Users & Authentication**. +1. In the left navigation bar, click **Role Templates**. +2. Go to the custom global role that should be deleted and click **⋮ (…) > Delete**. +3. Click **Delete**. + +## Assigning a Custom Role to a Group + +If you have a group of individuals that need the same level of access in Rancher, it can save time to create a custom role. When the role is assigned to a group, the users in the group have the appropriate level of access the first time they sign into Rancher. + +When a user in the group logs in, they get the built-in Standard User global role by default. They will also get the permissions assigned to their groups. + +If a user is removed from the external authentication provider group, they would lose their permissions from the custom role that was assigned to the group. They would continue to have their individual Standard User role. + +:::note Prerequisites: + +You can only assign a global role to a group if: + +* You have set up an [external authentication provider](../authentication-config/authentication-config.md#external-vs-local-authentication) +* The external authentication provider supports [user groups](../../authentication-permissions-and-global-configuration/authentication-config/manage-users-and-groups.md) +* You have already set up at least one user group with the authentication provider + +::: + +To assign a custom role to a group, follow these steps: + +1. In the upper left corner, click **☰ > Users & Authentication**. +1. In the left navigation bar, click **Groups**. +1. Go to the existing group that will be assigned the custom role and click **⋮ > Edit Config**. +1. If you have created roles, they will show in the **Custom** section. Choose any custom role that will be assigned to the group. +1. Optional: In the **Global Permissions** or **Built-in** sections, select any additional permissions that the group should have. +1. Click **Save.**. + +**Result:** The custom role will take effect when the users in the group log into Rancher. + +## Privilege Escalation + +The `Configure Catalogs` custom permission is powerful and should be used with caution. When an admin assigns the `Configure Catalogs` permission to a standard user, it could result in privilege escalation in which the user could give themselves admin access to Rancher provisioned clusters. Anyone with this permission should be considered equivalent to an admin. \ No newline at end of file diff --git a/versioned_docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/global-permissions.md b/versioned_docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/global-permissions.md new file mode 100644 index 00000000000..724dcc7e410 --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/global-permissions.md @@ -0,0 +1,296 @@ +--- +title: Global Permissions +--- + + + + + + + +_Permissions_ are individual access rights that you can assign when selecting a custom permission for a user. + +Global Permissions define user authorization outside the scope of any particular cluster. Out-of-the-box, there are four default global permissions: `Administrator`, `Standard User` and `User-base`. + +- **Administrator:** These users have full control over the entire Rancher system and all clusters within it. + +- **Standard User:** These users can create new clusters and use them. Standard users can also assign other users permissions to their clusters. + +- **User-Base:** User-Base users have login-access only. + +You cannot update or delete the built-in Global Permissions. + +## Global Permission Assignment + +Global permissions for local users are assigned differently than users who log in to Rancher using external authentication. + +### Global Permissions for New Local Users + +When you create a new local user, you assign them a global permission as you complete the **Add User** form. + +To see the default permissions for new users, + +1. In the upper left corner, click **☰ > Users & Authentication**. +1. In the left navigation bar, click **Role Templates**. +1. The **Role Templates** page has tabs for roles grouped by scope. Each table lists the roles in that scope. In the **Global** tab, in the **New User Default** column, the permissions given to new users by default are indicated with a checkmark. + +You can [change the default global permissions to meet your needs.](#configuring-default-global-permissions) + +### Global Permissions for Users with External Authentication + +When a user logs into Rancher using an external authentication provider for the first time, they are automatically assigned the **New User Default** global permissions. By default, Rancher assigns the **Standard User** permission for new users. + +To see the default permissions for new users, + +1. In the upper left corner, click **☰ > Users & Authentication**. +1. In the left navigation bar, click **Role Templates**. +1. The **Role Templates** page has tabs for roles grouped by scope. Each table lists the roles in that scope. In the **New User Default** column on each page, the permissions given to new users by default are indicated with a checkmark. + +You can [change the default permissions to meet your needs.](#configuring-default-global-permissions) + +Permissions can be [assigned](#configuring-global-permissions-for-individual-users) to an individual user. + +You can [assign a role to everyone in the group at the same time](#configuring-global-permissions-for-groups) if the external authentication provider supports groups. + +## Custom Global Permissions + +Using custom permissions is convenient for providing users with narrow or specialized access to Rancher. + +When a user from an [external authentication source](../authentication-config/authentication-config.md) signs into Rancher for the first time, they're automatically assigned a set of global permissions (hereafter, permissions). By default, after a user logs in for the first time, they are created as a user and assigned the default `user` permission. The standard `user` permission allows users to login and create clusters. + +However, in some organizations, these permissions may extend too much access. Rather than assigning users the default global permissions of `Administrator` or `Standard User`, you can assign them a more restrictive set of custom global permissions. + +The default roles, Administrator and Standard User, each come with multiple global permissions built into them. The Administrator role includes all global permissions, while the default user role includes three global permissions: Create Clusters, Use Catalog Templates, and User Base, which is equivalent to the minimum permission to log in to Rancher. In other words, the custom global permissions are modularized so that if you want to change the default user role permissions, you can choose which subset of global permissions are included in the new default user role. + +Administrators can enforce custom global permissions in multiple ways: + +- [Creating custom global roles](#custom-globalroles). +- [Changing the default permissions for new users](#configuring-default-global-permissions). +- [Configuring global permissions for individual users](#configuring-global-permissions-for-individual-users). +- [Configuring global permissions for groups](#configuring-global-permissions-for-groups). + +### Combining Built-in GlobalRoles + +Rancher provides several GlobalRoles which grant granular permissions for certain common use cases. +The following table lists each built-in global permission and whether it is included in the default global permissions, `Administrator`, `Standard User` and `User-Base`. + +| Custom Global Permission | Administrator | Standard User | User-Base | +| ---------------------------------- | ------------- | ------------- |-----------| +| Create Clusters | ✓ | ✓ | | +| Create RKE Templates | ✓ | ✓ | | +| Manage Authentication | ✓ | | | +| Manage Catalogs | ✓ | | | +| Manage Cluster Drivers | ✓ | | | +| Manage Node Drivers | ✓ | | | +| Manage PodSecurityPolicy Templates | ✓ | | | +| Manage Roles | ✓ | | | +| Manage Settings | ✓ | | | +| Manage Users | ✓ | | | +| Use Catalog Templates | ✓ | ✓ | | +| User-Base (Basic log-in access) | ✓ | ✓ | | + +For details on which Kubernetes resources correspond to each global permission, + +1. In the upper left corner, click **☰ > Users & Authentication**. +1. In the left navigation bar, click **Role Templates**. +1. If you click the name of an individual role, a table shows all of the operations and resources that are permitted by the role. + +:::note Notes: + +- Each permission listed above is comprised of multiple individual permissions not listed in the Rancher UI. For a full list of these permissions and the rules they are comprised of, access through the API at `/v3/globalRoles`. +- When viewing the resources associated with default roles created by Rancher, if there are multiple Kubernetes API resources on one line item, the resource will have `(Custom)` appended to it. These are not custom resources but just an indication that there are multiple Kubernetes API resources as one resource. + +::: + +:::danger + +The built-in GlobalRole `Manage Users` allows users to create, modify and delete other users within the Rancher environment. While this permission may be necessary for administrative workflows in trusted environments, granting it to non-trusted or lower-privileged users, such as standard users, poses a serious security risk and may result in privilege escalation. + +::: + +### Custom GlobalRoles + +You can create custom GlobalRoles to satisfy use cases not directly addressed by built-in GlobalRoles. + +Create custom GlobalRoles through the UI or through automation (such as the Rancher Kubernetes API). You can specify the same type of rules as the rules for upstream roles and clusterRoles. + +See the list [Global Resources](global-resources.md) for relevant resources. + +#### Escalate and Bind verbs + +When giving permissions on GlobalRoles, keep in mind that Rancher respects the `escalate` and `bind` verbs, in a similar fashion to [Kubernetes](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#restrictions-on-role-creation-or-update). + +Both of these verbs, which are given on the GlobalRoles resource, can grant users the permission to bypass Rancher's privilege escalation checks. This potentially allows users to become admins. Since this represents a serious security risk, `bind` and `escalate` should be distributed to users with great caution. + +The `escalate` verb allows users to change a GlobalRole and add any permission, even if the users doesn't have the permissions in the current GlobalRole or the new version of the GlobalRole. + +The `bind` verb allows users to create a GlobalRoleBinding to the specified GlobalRole, even if they do not have the permissions in the GlobalRole. + +:::danger + +The wildcard verb `*` also includes the `bind` and `escalate` verbs. This means that giving `*` on GlobalRoles to a user also gives them both `escalate` and `bind`. + +::: + +##### Custom GlobalRole Examples + +To grant permission to escalate only the `test-gr` GlobalRole: + +```yaml +rules: +- apiGroups: + - 'management.cattle.io' + resources: + - 'globalroles' + resourceNames: + - 'test-gr' + verbs: + - 'escalate' +``` + +To grant permission to escalate all GlobalRoles: + +```yaml +rules: +- apiGroups: + - 'management.cattle.io' + resources: + - 'globalroles' + verbs: + - 'escalate' +``` + +To grant permission to create bindings (which bypass escalation checks) to only the `test-gr` GlobalRole: + +```yaml +rules: +- apiGroups: + - 'management.cattle.io' + resources: + - 'globalroles' + resourceNames: + - 'test-gr' + verbs: + - 'bind' +- apiGroups: + - 'management.cattle.io' + resources: + - 'globalrolebindings' + verbs: + - 'create' +``` + +Granting `*` permissions (which includes both `escalate` and `bind`): + +```yaml +rules: +- apiGroups: + - 'management.cattle.io' + resources: + - 'globalroles' + verbs: + - '*' +``` + +#### GlobalRole Permissions on Downstream Clusters + +GlobalRoles can grant one or more RoleTemplates on every downstream cluster through the `inheritedClusterRoles` field. Values in this field must refer to a RoleTemplate which exists and has a `context` of Cluster. + +With this field, users gain the specified permissions on all current or future downstream clusters. For example, consider the following GlobalRole: + +```yaml +apiVersion: management.cattle.io/v3 +kind: GlobalRole +displayName: All Downstream Owner +metadata: + name: all-downstream-owner +inheritedClusterRoles: +- cluster-owner +``` + +Any user with this permission will be a cluster-owner on all downstream clusters. If a new cluster is added, regardless of type, the user will be an owner on that cluster as well. + +:::danger + +Using this field on [default GlobalRoles](#configuring-default-global-permissions) may result in users gaining excessive permissions. + +::: + +### Configuring Default Global Permissions + +If you want to restrict the default permissions for new users, you can remove the `user` permission as default role and then assign multiple individual permissions as default instead. Conversely, you can also add administrative permissions on top of a set of other standard permissions. + +:::note + +Default roles are only assigned to users added from an external authentication provider. For local users, you must explicitly assign global permissions when adding a user to Rancher. You can customize these global permissions when adding the user. + +::: + +To change the default global permissions that are assigned to external users upon their first log in, follow these steps: + +1. In the upper left corner, click **☰ > Users & Authentication**. +1. In the left navigation bar, click **Role Templates**. On the **Role Templates** page, make sure the **Global** tab is selected. +1. Find the permissions set that you want to add or remove as a default. Then edit the permission by selecting **⋮ > Edit Config**. +1. If you want to add the permission as a default, Select **Yes: Default role for new users** and then click **Save**. If you want to remove a default permission, edit the permission and select **No**. + +**Result:** The default global permissions are configured based on your changes. Permissions assigned to new users display a check in the **New User Default** column. + +### Configuring Global Permissions for Individual Users + +To configure permission for a user, + +1. In the upper left corner, click **☰ > Users & Authentication**. +1. In the left navigation bar, click **Users**. +1. Go to the user whose access level you want to change and click **⋮ > Edit Config**. +1. In the **Global Permissions** and **Built-in** sections, check the boxes for each permission you want the user to have. If you have created roles from the **Role Templates** page, they will appear in the **Custom** section and you can choose from them as well. +1. Click **Save**. + +**Result:** The user's global permissions have been updated. + +### Configuring Global Permissions for Groups + +If you have a group of individuals that need the same level of access in Rancher, it can save time to assign permissions to the entire group at once, so that the users in the group have the appropriate level of access the first time they sign into Rancher. + +After you assign a custom global role to a group, the custom global role will be assigned to a user in the group when they log in to Rancher. + +For existing users, the new permissions will take effect when the users log out of Rancher and back in again, or when an administrator [refreshes the group memberships.](#refreshing-group-memberships) + +For new users, the new permissions take effect when the users log in to Rancher for the first time. New users from this group will receive the permissions from the custom global role in addition to the **New User Default** global permissions. By default, the **New User Default** permissions are equivalent to the **Standard User** global role, but the default permissions can be [configured.](#configuring-default-global-permissions) + +If a user is removed from the external authentication provider group, they would lose their permissions from the custom global role that was assigned to the group. They would continue to have any remaining roles that were assigned to them, which would typically include the roles marked as **New User Default**. Rancher will remove the permissions that are associated with the group when the user logs out, or when an administrator [refreshes group memberships,](#refreshing-group-memberships) whichever comes first. + +:::note Prerequisites: + +You can only assign a global role to a group if: + +* You have set up an [external authentication provider](../authentication-config/authentication-config.md#external-vs-local-authentication) +* The external authentication provider supports [user groups](../authentication-config/manage-users-and-groups.md) +* You have already set up at least one user group with the authentication provider + +::: + +To assign a custom global role to a group, follow these steps: + +1. In the upper left corner, click **☰ > Users & Authentication**. +1. In the left navigation bar, click **Groups**. +1. Go to the group you want to assign a custom global role to and click **⋮ > Edit Config**. +1. In the **Global Permissions,** **Custom,** and/or **Built-in** sections, select the permissions that the group should have. +1. Click **Create**. + +**Result:** The custom global role will take effect when the users in the group log into Rancher. + +### Refreshing Group Memberships + +When an administrator updates the global permissions for a group, the changes take effect for individual group members after they log out of Rancher and log in again. + +To make the changes take effect immediately, an administrator or cluster owner can refresh group memberships. + +An administrator might also want to refresh group memberships if a user is removed from a group in the external authentication service. In that case, the refresh makes Rancher aware that the user was removed from the group. + +To refresh group memberships, + +1. In the upper left corner, click **☰ > Users & Authentication**. +1. In the left navigation bar, click **Users**. +1. Click **Refresh Group Memberships**. + +**Result:** Any changes to the group members' permissions will take effect. diff --git a/versioned_docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/global-resources.md b/versioned_docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/global-resources.md new file mode 100644 index 00000000000..e72bb00b8f7 --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/global-resources.md @@ -0,0 +1,44 @@ +--- +title: Global Resources +--- + + + + + +Global Resources are non-namespaced resources provided by Rancher. Users who are +cluster-owners/project-owners do not have access to several of these by +default. For example principals and roletemplates. + +The resources are documented here to support administrators creating and/or +modifying custom sets of permissions with finding the minimum set of permissions +needed for a particular task in the dashboard. + +As an example, to use the cluster/project permissions pages of the dashboard +requires permissions on principals to search/display a readable name for users, +and on roleTemplates, to see a list of usable roleTemplates as well as to +display a readable name for the role. + +Please see the list below to determine what permissions you may need when creating a least-privilege user. + +| Group | Resource | Purpose | +| -------------------- | ------------------------------ | --------------------------------------------------------------------------- | +| auditlog.cattle.io | auditpolicies | Specification of log filers, redactions, verbosity | +| catalog.cattle.io | clusterrepos | Helm chart repository location and credentials | +| ext.cattle.io | groupmembershiprefreshrequests | Creation triggers refresh of group membership for specific or all users | +| ext.cattle.io | kubeconfigs | Kubeconfig file for access to remote clusters | +| ext.cattle.io | passwordchangerequests | Creation triggers update of the referenced User's password | +| ext.cattle.io | selfusers | Get delivers User making the request | +| ext.cattle.io | tokens | Raw API key. See Kubeconfig for wrapped API keys | +| management.cattle.io | authconfigs | Configuration of external auth service providers | +| management.cattle.io | clusters | Remote cluster management | +| management.cattle.io | features | Feature controlling rancher behaviour | +| management.cattle.io | globalrolebindings | Binding of user/group to a global role | +| management.cattle.io | globalroles | Custom role for global permissions (applied local and remote) | +| management.cattle.io | nodedrivers | Configuration of driver to provision clusters with a cloud service provider | +| management.cattle.io | roletemplates | Template for custom roles managing project- or cluster-specific permissions | +| management.cattle.io | settings | Setting controlling Rancher behaviour | +| management.cattle.io | tokens | Raw API key, old style. | +| management.cattle.io | userattributes | Additional information about a managed User | +| management.cattle.io | users | User known to and managed by Rancher | +| telemetry.cattle.io | secretrequests | Request creation of a secret with arbitrary name, in any namespace | diff --git a/versioned_docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/locked-roles.md b/versioned_docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/locked-roles.md new file mode 100644 index 00000000000..9cf6df0225f --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/locked-roles.md @@ -0,0 +1,42 @@ +--- +title: Locked Roles +--- + + + + + +You can set roles to a status of `locked`. Locking roles prevent them from being assigned to users in the future. + +Locked roles: + +- Cannot be assigned to users that don't already have it assigned. +- Are not listed in the **Member Roles** drop-down when you are adding a user to a cluster or project. +- Do not affect users assigned the role before you lock the role. These users retain access that the role provides. + + **Example:** let's say your organization creates an internal policy that users assigned to a cluster are prohibited from creating new projects. It's your job to enforce this policy. + + To enforce it, before you add new users to the cluster, you should lock the following roles: `Cluster Owner`, `Cluster Member`, and `Create Projects`. Then you could create a new custom role that includes the same permissions as a __Cluster Member__, except the ability to create projects. Then, you use this new custom role when adding users to a cluster. + +Roles can be locked by the following users: + +- Any user assigned the `Administrator` global permission. +- Any user assigned the `Custom Users` permission, along with the `Manage Roles` role. + + +## Locking/Unlocking Roles + +If you want to prevent a role from being assigned to users, you can set it to a status of `locked`. + +You can lock roles in two contexts: + +- When you're [adding a custom role](custom-roles.md). +- When you editing an existing role (see below). + +Cluster roles and project/namespace roles can be locked, but global roles cannot. + +1. In the upper left corner, click **☰ > Users & Authentication**. +1. In the left navigation bar, click **Role Templates**. +1. Go to the **Cluster** tab or the **Project/Namespaces** tab. +1. From the role that you want to lock (or unlock), select **⋮ > Edit Config**. +1. From the **Locked** option, choose the **Yes** or **No** radio button. Then click **Save**. diff --git a/versioned_docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/manage-role-based-access-control-rbac.md b/versioned_docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/manage-role-based-access-control-rbac.md new file mode 100644 index 00000000000..d6a6d8d8f76 --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/manage-role-based-access-control-rbac.md @@ -0,0 +1,29 @@ +--- +title: Managing Role-Based Access Control (RBAC) +--- + + + + + +Within Rancher, each person authenticates as a _user_, which is a login that grants you access to Rancher. As mentioned in [Authentication](../authentication-config/authentication-config.md), users can either be local or external. + +After you configure external authentication, the users that display on the **Users** page changes. + +- If you are logged in as a local user, only local users display. + +- If you are logged in as an external user, both external and local users display. + +## Users and Roles + +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.md): + + Define user authorization outside the scope of any particular cluster. + +- [Cluster and Project Roles](cluster-and-project-roles.md): + + 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. diff --git a/versioned_docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/notification-center.md b/versioned_docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/notification-center.md new file mode 100644 index 00000000000..0c049f2076b --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/notification-center.md @@ -0,0 +1,23 @@ +--- +title: Notification Center +--- + + + + + +## What is the Notification Center? + +The Notification Center, located in the upper-right corner of your Rancher dashboard and marked by a bell icon, is your central hub for staying informed about various events within Rancher. + +Notifications are categorized by severity and type: + +* **Error** indicates a high-severity issue. +* **Warning** indicates a medium-severity concern. +* **Information** provides general updates of lower severity. +* **Task** shows that a process or action is currently in progress. +* **Success** confirms that a process or action has completed successfully. + +For example, you might receive a notification when a new version of Rancher is available, or a direct link to the Rancher Release Notes. + +You can easily browse through your notifications using the up and down arrow keys. Certain notifications may also include an associated action, allowing you to respond immediately. diff --git a/versioned_docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/pod-security-standards.md b/versioned_docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/pod-security-standards.md new file mode 100644 index 00000000000..333fbfd1bfd --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/pod-security-standards.md @@ -0,0 +1,22 @@ +--- +title: Pod Security Standards (PSS) & Pod Security Admission (PSA) +--- + + + + + +[Pod Security Standards (PSS)](https://kubernetes.io/docs/concepts/security/pod-security-standards/) and [Pod Security Admission (PSA)](https://kubernetes.io/docs/concepts/security/pod-security-admission/) define security restrictions for a broad set of workloads. +They became available and were turned on by default in Kubernetes v1.23, and replace [Pod Security Policies (PSP)](https://kubernetes.io/docs/concepts/security/pod-security-policy/) in Kubernetes v1.25 and above. + +PSS define security levels for workloads. PSAs describe requirements for pod security contexts and related fields. PSAs reference PSS levels to define security restrictions. + +## Pod Security Admission Configuration Templates + +Rancher offers PSA configuration templates. These are pre-defined security configurations that you can apply to a cluster. Rancher admins (or those with the right permissions) can [create, manage, and edit](./psa-config-templates.md) PSA templates. + +### Rancher on PSA-restricted Clusters + +Rancher system namespaces are also affected by the restrictive security policies described by PSA templates. You need to exempt Rancher's system namespaces after you assign the template, or else the cluster won't operate correctly. See [Pod Security Admission (PSA) Configuration Templates](./psa-config-templates.md#exempting-required-rancher-namespaces) for more details. + +For a complete file which has all the exemptions you need to run Rancher, please refer to this [sample Admission Configuration](../../../reference-guides/rancher-security/psa-restricted-exemptions.md). diff --git a/versioned_docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/psa-config-templates.md b/versioned_docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/psa-config-templates.md new file mode 100644 index 00000000000..e924a4cfffa --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/psa-config-templates.md @@ -0,0 +1,148 @@ +--- +title: Pod Security Admission (PSA) Configuration Templates +--- + + + + + +[Pod Security admission (PSA)](./pod-security-standards.md) configuration templates are a Rancher custom-defined resource (CRD), available in Rancher v2.7.2 and above. The templates provide pre-defined security configurations that you can apply to a cluster: + +:::info important +The policies shipped by default in Rancher aim to provide a trade-off between security and convenience. If a more strict policy configuration is needed, users are able to craft such policies themselves based on their specific requirements. In the case Rancher policies are preferred, you will need to deploy admission controllers that block the creation of any [exempted namespaces](#exempting-required-rancher-namespaces) that won't be used within your environments. +::: + +- `rancher-privileged`: The most permissive configuration. It doesn't restrict the behavior of any pods. This allows for known privilege escalations. This policy has no exemptions. +- `rancher-restricted`: A heavily restricted configuration that follows current best practices for hardening pods. You must make [namespace-level exemptions](./pod-security-standards.md#rancher-on-psa-restricted-clusters) for Rancher components. + +## Assign a Pod Security Admissions (PSA) Configuration Template + +You can assign a PSA template at the same time that you create a downstream cluster. You can also add a template by configuring an existing cluster. + +### Assign a Template During Cluster Creation + + + +1. In the upper left corner, click **☰ > Cluster Management**. +1. On the **Clusters** page, click the **Create** button. +1. Select a provider. +1. On the **Cluster: Create** page, go to **Basics > Security**. +1. In the **Pod Security Admission Configuration Template** dropdown menu, select the template you want to assign. +1. Click **Create**. + +### Assign a Template to an Existing Cluster + +1. In the upper left corner, click **☰ > Cluster Management**. +1. Find the cluster you want to update in the **Clusters** table, and click the **⋮**. +1. Select **Edit Config** . +1. In the **Pod Security Admission Configuration Template** dropdown menu, select the template you want to assign. +1. Click **Save**. + + + + + +1. In the upper left corner, click **☰ > Cluster Management**. +1. On the **Clusters** page, click the **Create** button. +1. Select a provider. +1. On the **Add Cluster** page, under **Cluster Options**, click **Advanced Options**. +1. In the **Pod Security Admission Configuration Template** dropdown menu, select the template you want to assign. +1. Click **Create**. + +### Assign a Template to an Existing Cluster + +1. In the upper left corner, click **☰ > Cluster Management**. +1. Find the cluster you want to update in the **Clusters** table, and click the **⋮**. +1. Select **Edit Config**. +1. On the **Edit Cluster** page, go to **Cluster Options > Advanced Options**. +1. In the **Pod Security Admission Configuration Template**, select the template you want to assign. +1. Click **Save**. + + + + +## Add or Edit a Pod Security Admissions (PSA) Configuration Template + +If you have administrator privileges, you can customize security restrictions and permissions by creating additional PSA templates, or by editing existing templates. + +:::caution +If you edit an existing PSA template while it is still in use, changes will be applied to all clusters that have been assigned to that template. +::: + +1. In the upper left corner, click **☰ > Cluster Management**. +1. Click **Advanced** to open the dropdown menu. +1. Select **Pod Security Admissions**. +1. Find the template you want to modify, and click the **⋮**. +1. Select **Edit Config** to edit the template. +1. When you're done editing the configuration, click **Save**. + +### Allow Non-Admin Users to Manage PSA Templates + +If you want to allow other users to manage templates, you can bind that user to a role that grants all verbs (`"*"`) on `management.cattle.io/podsecurityadmissionconfigurationtemplates`. + +:::caution +Any user that is bound to the above permission will be able to change the restriction levels on _all_ managed clusters which use a given PSA template, including ones that they have no permissions on. +::: + +## Exempting Required Rancher Namespaces + +When you run Rancher on a Kubernetes cluster that enforces a restrictive security policy by default, you'll need to [exempt the following namespaces](#exempting-namespaces), otherwise the policy might prevent Rancher system pods from running properly. + +- `calico-apiserver` +- `calico-system` +- `cattle-alerting` +- `cattle-csp-adapter-system` +- `cattle-elemental-system` +- `cattle-epinio-system` +- `cattle-externalip-system` +- `cattle-fleet-local-system` +- `cattle-fleet-system` +- `cattle-gatekeeper-system` +- `cattle-global-data` +- `cattle-global-nt` +- `cattle-impersonation-system` +- `cattle-istio` +- `cattle-istio-system` +- `cattle-logging` +- `cattle-logging-system` +- `cattle-monitoring-system` +- `cattle-neuvector-system` +- `cattle-prometheus` +- `cattle-provisioning-capi-system` +- `cattle-resources-system` +- `cattle-sriov-system` +- `cattle-system` +- `cattle-ui-plugin-system` +- `cattle-windows-gmsa-system` +- `cert-manager` +- `cis-operator-system` +- `fleet-default` +- `fleet-local` +- `ingress-nginx` +- `istio-system` +- `kube-node-lease` +- `kube-public` +- `kube-system` +- `longhorn-system` +- `rancher-alerting-drivers` +- `security-scan` +- `sr-operator-system` +- `tigera-operator` + +Rancher, some Rancher owned charts, and RKE2 and K3s distributions all use these namespaces. A subset of the listed namespaces are already exempt in the built-in Rancher `rancher-restricted` policy, for use in downstream clusters. For a complete template which has all the exemptions you need to run Rancher, please refer to this [sample Admission Configuration](../../../reference-guides/rancher-security/psa-restricted-exemptions.md). + +## Exempting Namespaces + +If you assign the `rancher-restricted` template to a cluster, by default the restrictions are applied across the entire cluster at the namespace level. To exempt certain namespaces from this highly restricted policy, do the following: + +1. In the upper left corner, click **☰ > Cluster Management**. +1. Click **Advanced** to open the dropdown menu. +1. Select **Pod Security Admissions**. +1. Find the template you want to modify, and click the **⋮**. +1. Select **Edit Config**. +1. Click the **Namespaces** checkbox under **Exemptions** to edit the **Namespaces** field. +1. When you're done exempting namespaces, click **Save**. + +:::note +You need to update the target cluster to make the new template take effect in that cluster. An update can be triggered by editing and saving the cluster without changing values. +::: diff --git a/versioned_docs/version-2.14/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/back-up-docker-installed-rancher.md b/versioned_docs/version-2.14/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/back-up-docker-installed-rancher.md new file mode 100644 index 00000000000..2f0d0f2c9b7 --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/back-up-docker-installed-rancher.md @@ -0,0 +1,78 @@ +--- +title: Backing up Rancher Installed with Docker +--- + + + + + +After completing your Docker installation of Rancher, we recommend creating backups of it on a regular basis. Having a recent backup will let you recover quickly from an unexpected disaster. + +## Before You Start + +During the creation of your backup, you'll enter a series of commands, replacing placeholders with data from your environment. These placeholders are denoted with angled brackets and all capital letters (``). Here's an example of a command with a placeholder: + +``` +docker run --name busybox-backup- --volumes-from rancher-data- -v $PWD:/backup busybox tar pzcvf /backup/rancher-data-backup--.tar.gz /var/lib/rancher +``` + +In this command, `` is a placeholder for the date that the data container and backup were created. `9-27-18` for example. + +Cross reference the image and reference table below to learn how to obtain this placeholder data. Write down or copy this information before starting the [procedure below](#creating-a-backup). + +Terminal docker ps Command, Displaying Where to Find <RANCHER_CONTAINER_TAG> and <RANCHER_CONTAINER_NAME> + +![Placeholder Reference](/img/placeholder-ref.png) + +| Placeholder | Example | Description | +| -------------------------- | -------------------------- | --------------------------------------------------------- | +| `` | `v2.0.5` | The rancher/rancher image you pulled for initial install. | +| `` | `festive_mestorf` | The name of your Rancher container. | +| `` | `v2.0.5` | The version of Rancher that you're creating a backup for. | +| `` | `9-27-18` | The date that the data container or backup was created. | +
+ +You can obtain `` and `` by logging into your Rancher Server by remote connection and entering the command to view the containers that are running: `docker ps`. You can also view containers that are stopped with `docker ps -a`. Use these commands for help anytime while creating backups. + +## Creating a Backup + +This procedure creates a backup that you can restore if Rancher encounters a disaster scenario. + + +1. Using a remote Terminal connection, log into the node running your Rancher Server. + +1. Stop the container currently running Rancher Server. Replace `` with the name of your Rancher container. + + ``` + docker stop + ``` +1. Use the command below, replacing each placeholder, to create a data container from the Rancher container that you just stopped. + + ``` + docker create --volumes-from --name rancher-data- rancher/rancher: + ``` + +1. From the data container that you just created (rancher-data-<DATE>), create a backup tarball (rancher-data-backup-<RANCHER_VERSION>-<DATE>.tar.gz). Use the following command, replacing each placeholder: + + ``` + docker run --name busybox-backup- --volumes-from rancher-data- -v $PWD:/backup:z busybox tar pzcvf /backup/rancher-data-backup--.tar.gz /var/lib/rancher + ``` + + **Step Result:** A stream of commands runs on the screen. + +1. Enter the `ls` command to confirm that the backup tarball was created. It will have a name similar to `rancher-data-backup--.tar.gz`. + +1. Move your backup tarball to a safe location external to your Rancher Server. Then delete the `rancher-data-` and `busybox-backup-` containers from your Rancher Server. + + ``` + docker rm rancher-data- + docker rm busybox-backup- + ``` + +1. Restart Rancher Server. Replace `` with the name of your Rancher container: + + ``` + docker start + ``` + +**Result:** A backup tarball of your Rancher Server data is created. See [Restoring Backups: Docker Installs](restore-docker-installed-rancher.md) if you need to restore backup data. diff --git a/versioned_docs/version-2.14/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/back-up-rancher-launched-kubernetes-clusters.md b/versioned_docs/version-2.14/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/back-up-rancher-launched-kubernetes-clusters.md new file mode 100644 index 00000000000..08d8e96c8bd --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/back-up-rancher-launched-kubernetes-clusters.md @@ -0,0 +1,311 @@ +--- +title: Backing up a Cluster +--- + + + + + +In the Rancher UI, etcd backup and recovery for [Rancher launched Kubernetes clusters](../launch-kubernetes-with-rancher/launch-kubernetes-with-rancher.md) can be easily performed. + +Rancher recommends configuring recurrent `etcd` snapshots for all production clusters. Additionally, one-time snapshots can be taken as well. + +Snapshots of the etcd database are taken and saved either [locally onto the etcd nodes](#local-backup-target) or to a [S3 compatible target](#s3-backup-target). The advantages of configuring S3 is that if all etcd nodes are lost, your snapshot is saved remotely and can be used to restore the cluster. + +## How Snapshots Work + +### Snapshot Components + + + + +When Rancher creates a snapshot, it includes three components: + +- The cluster data in etcd +- The Kubernetes version +- The cluster configuration in the form of the `cluster.yml` + +Because the Kubernetes version is now included in the snapshot, it is possible to restore a cluster to a prior Kubernetes version. + + + + +Rancher delegates snapshot creation to the downstream Kubernetes engine. When the Kubernetes engine creates a snapshot, it includes three components: + +- The cluster data in etcd +- The Kubernetes version +- The cluster configuration + +Because the Kubernetes version is included in the snapshot, it is possible to restore a cluster to a prior Kubernetes version while also restoring an etcd snapshot. + + + + +The multiple components of the snapshot allow you to select from the following options if you need to restore a cluster from a snapshot: + +- **Restore just the etcd contents:** This restore is similar to restoring to snapshots in Rancher before v2.4.0. +- **Restore etcd and Kubernetes version:** This option should be used if a Kubernetes upgrade is the reason that your cluster is failing, and you haven't made any cluster configuration changes. +- **Restore etcd, Kubernetes versions and cluster configuration:** This option should be used if you changed both the Kubernetes version and cluster configuration when upgrading. + +It is always recommended to take a new snapshot before performing any configuration changes or upgrades. + + +### Generating the Snapshot from etcd Nodes + + + + +For each etcd node in the cluster, the etcd cluster health is checked. If the node reports that the etcd cluster is healthy, a snapshot is created from it and optionally uploaded to S3. + +The snapshot is stored in `/opt/rke/etcd-snapshots`. If the directory is configured on the nodes as a shared mount, it will be overwritten. On S3, the snapshot will always be from the last node that uploads it, as all etcd nodes upload it and the last will remain. + +In the case when multiple etcd nodes exist, any created snapshot is created after the cluster has been health checked, so it can be considered a valid snapshot of the data in the etcd cluster. + + + + +Snapshots are enabled by default. + +The snapshot directory defaults to `/var/lib/rancher//server/db/snapshots`, where `` is either `rke2` or `k3s`. + +In RKE2, snapshots are stored on each etcd node. If you have multiple etcd or etcd + control-plane nodes, you will have multiple copies of local etcd snapshots. + + + + +### Snapshot Naming Conventions + + + + +The name of the snapshot is auto-generated. The `--name` option can be used to override the name of the snapshot when creating one-time snapshots with the RKE CLI. + +When Rancher creates a snapshot of an RKE cluster, the snapshot name is based on the type (whether the snapshot is manual or recurring) and the target (whether the snapshot is saved locally or uploaded to S3). The naming convention is as follows: + +- `m` stands for manual +- `r` stands for recurring +- `l` stands for local +- `s` stands for S3 + +Some example snapshot names are: + +- c-9dmxz-rl-8b2cx +- c-9dmxz-ml-kr56m +- c-9dmxz-ms-t6bjb +- c-9dmxz-rs-8gxc8 + + + + +The name of the snapshot is auto-generated. The `--name` option can be used to override the base name of the snapshot when creating one-time snapshots with the RKE2 or K3s CLI. + +When Rancher creates a snapshot of an RKE2 or K3s cluster, the snapshot name is based on the type (whether the snapshot is manual or recurring) and the target (whether the snapshot is saved locally or uploaded to S3). The naming convention is as follows: + +`--` + +``: is the base name set by `--name` and can be one of the the following + +- `etcd-snapshot` is prepended on recurring snapshots +- `on-demand` is prepended on manual, on-demand snapshots + +``: Node is the name of the node that the snapshot was taken on. + +`` is a unix-time stamp of the snapshot creation date. + +Some example snapshot names are: + +- `on-demand-my-super-rancher-k8s-node1-1652288934` +- `on-demand-my-super-rancher-k8s-node2-1652288936` +- `etcd-snapshot-my-super-rancher-k8s-node1-1652289945` +- `etcd-snapshot-my-super-rancher-k8s-node2-1652289948` + + + + +### How Restoring from a Snapshot Works + + + + +On restore, the following process is used: + +1. The snapshot is retrieved from S3, if S3 is configured. +2. The snapshot is unzipped (if zipped). +3. One of the etcd nodes in the cluster serves that snapshot file to the other nodes. +4. The other etcd nodes download the snapshot and validate the checksum so that they all use the same snapshot for the restore. +5. The cluster is restored and post-restore actions will be done in the cluster. + + + + +On restore, Rancher delivers a few sets of plans to perform a restoration. A set of phases are used, namely: + +- Started +- Shutdown +- Restore +- RestartCluster +- Finished + +If the etcd snapshot restore fails, the phase will be set to `Failed`. + +1. The etcd snapshot restore request is received, and depending on `restoreRKEConfig`, the cluster configuration/kubernetes version are reconciled. +1. The phase is set to `Started`. +1. The phase is set to `Shutdown`, and the entire cluster is shut down using plans that run the distribution `killall.sh` script. A new init node is elected. If the snapshot being restored is a local snapshot, the node that the snapshot resides on will be selected as the init node. If the snapshot is being restored from S3, the existing init node will be used. +1. The phase is set to `Restore`, and the init node has the snapshot restored onto it. +1. The phase is set to `RestartCluster`, and the cluster is restarted/rejoined to the new init node that has the freshly restored snapshot information. +1. The phase is set to `Finished`, and the cluster is deemed successfully restored. The `cattle-cluster-agent` will reconnect, and the cluster will finish reconciliation. + + + + +## Configuring Recurring Snapshots + + + + +Select how often you want recurring snapshots to be taken as well as how many snapshots to keep. The amount of time is measured in hours. With timestamped snapshots, the user has the ability to do a point-in-time recovery. + +By default, [Rancher launched Kubernetes clusters](../launch-kubernetes-with-rancher/launch-kubernetes-with-rancher.md) are configured to take recurring snapshots (saved to local disk). To protect against local disk failure, using the [S3 Target](#s3-backup-target) or replicating the path on disk is advised. + +During cluster provisioning or editing the cluster, the configuration for snapshots can be found in the advanced section for **Cluster Options**. Click on **Show advanced options**. + +In the **Advanced Cluster Options** section, there are several options available to configure: + +| Option | Description | Default Value| +| --- | ---| --- | +| etcd Snapshot Backup Target | Select where you want the snapshots to be saved. Options are either local or in S3 | local| +|Recurring etcd Snapshot Enabled| Enable/Disable recurring snapshots | Yes| +| Recurring etcd Snapshot Creation Period | Time in hours between recurring snapshots| 12 hours | +| Recurring etcd Snapshot Retention Count | Number of snapshots to retain| 6 | + + + + +Set the schedule for how you want recurring snapshots to be taken as well as how many snapshots to keep. The schedule is conventional cron format. The retention policy dictates the number of snapshots matching a name to keep per node. + +By default, [Rancher launched Kubernetes clusters](../launch-kubernetes-with-rancher/launch-kubernetes-with-rancher.md) are configured to take recurring snapshots (saved to local disk) every 5 hours starting at 12 AM. To protect against local disk failure, using the [S3 Target](#s3-backup-target) or replicating the path on disk is advised. + +During cluster provisioning or editing the cluster, the configuration for snapshots can be found under **Cluster Configuration**. Click on **etcd**. + +| Option | Description | Default Value| +| --- | ---| --- | +| Recurring etcd Snapshot Enabled | Enable/Disable recurring snapshots | Yes | +| Recurring etcd Snapshot Creation Period | Cron schedule for recurring snapshot | `0 */5 * * *` | +| Recurring etcd Snapshot Retention Count | Number of snapshots to retain | 5 | + + + + +## One-Time Snapshots + + + + +In addition to recurring snapshots, you may want to take a "one-time" snapshot. For example, before upgrading the Kubernetes version of a cluster it's best to backup the state of the cluster to protect against upgrade failure. + +1. In the upper left corner, click **☰ > Cluster Management**. +1. On the **Clusters** page, navigate to the cluster where you want to take a one-time snapshot. +1. Click **⋮ > Take Snapshot**. + + + + +In addition to recurring snapshots, you may want to take a "one-time" snapshot. For example, before upgrading the Kubernetes version of a cluster it's best to backup the state of the cluster to protect against upgrade failure. + +1. In the upper left corner, click **☰ > Cluster Management**. +1. On the **Clusters** page, navigate to the cluster where you want to take a one-time snapshot. +1. Navigate to the `Snapshots` tab and click `Snapshot Now` + +### How Taking One-Time Snapshots Works + +On one-time snapshot creation, the Rancher delivers a few sets of plans to perform snapshot creation. A set of phases are used, namely: + +- Started +- RestartCluster +- Finished + +If the etcd snapshot creation fails, the phase will be set to `Failed`. + +1. The etcd snapshot creation request is received. +1. The phase is set to `Started`. All etcd nodes in the cluster receive a plan to create an etcd snapshot, per the cluster configuration. +1. The phase is set to `RestartCluster`, and the plans on every etcd node are reset to the original plan for the etcd nodes. +1. The phase is set to `Finished`. + + + + +**Result:** Based on your [snapshot backup target](#snapshot-backup-targets), a one-time snapshot will be taken and saved in the selected backup target. + +## Snapshot Backup Targets + +Rancher supports two different backup targets: + +- [Local Target](#local-backup-target) +- [S3 Target](#s3-backup-target) + +### Local Backup Target + + + + +By default, the `local` backup target is selected. The benefits of this option is that there is no external configuration. Snapshots are automatically saved locally to the etcd nodes in the [Rancher launched Kubernetes clusters](../launch-kubernetes-with-rancher/launch-kubernetes-with-rancher.md) in `/opt/rke/etcd-snapshots`. All recurring snapshots are taken at configured intervals. The downside of using the `local` backup target is that if there is a total disaster and _all_ etcd nodes are lost, there is no ability to restore the cluster. + + + + +By default, the `local` backup target is selected. The benefits of this option is that there is no external configuration. Snapshots are automatically saved locally to the etcd nodes in the [Rancher launched Kubernetes clusters](../launch-kubernetes-with-rancher/launch-kubernetes-with-rancher.md) in `/var/lib/rancher//server/db/snapshots` where `` is either `k3s` or `rke2`. All recurring snapshots are taken per the cron schedule. The downside of using the `local` backup target is that if there is a total disaster and _all_ etcd nodes are lost, there is no ability to restore the cluster. + + + + +### S3 Backup Target + +We recommend that you use the `S3` backup target. It lets you store snapshots externally, on an S3 compatible backend. Since the snapshots aren't stored locally, you can still restore the cluster even if you lose all etcd nodes. + +Although the `S3` target offers advantages over local backup, it does require extra configuration. + +:::caution + +If you use an S3 backup target, make sure that every cluster has its own bucket or folder. Rancher populates snapshot information from any available snapshot listed in the S3 bucket or folder configured for that cluster. + +::: + +| Option | Description | Required| +|---|---|---| +|S3 Bucket Name| Name of S3 bucket to store backups| *| +|S3 Region|S3 region for the backup bucket| | +|S3 Region Endpoint|S3 regions endpoint for the backup bucket|* | +|S3 Access Key|S3 access key with permission to access the backup bucket|*| +|S3 Secret Key|S3 secret key with permission to access the backup bucket|*| +| Custom CA Certificate | A custom certificate used to access private S3 backends || + +### Using a custom CA certificate for S3 + +The backup snapshot can be stored on a custom `S3` backup like [minio](https://min.io/). If the S3 back end uses a self-signed or custom certificate, provide a custom certificate using the `Custom CA Certificate` option to connect to the S3 backend. + +### IAM Support for Storing Snapshots in S3 + +The `S3` backup target supports using IAM authentication to AWS API in addition to using API credentials. An IAM role gives temporary permissions that an application can use when making API calls to S3 storage. To use IAM authentication, the following requirements must be met: + +- The cluster etcd nodes must have an instance role that has read/write access to the designated backup bucket. +- The cluster etcd nodes must have network access to the specified S3 endpoint. +- The Rancher Server worker node(s) must have an instance role that has read/write to the designated backup bucket. +- The Rancher Server worker node(s) must have network access to the specified S3 endpoint. + + To give an application access to S3, refer to the AWS documentation on [Using an IAM Role to Grant Permissions to Applications Running on Amazon EC2 Instances.](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use_switch-role-ec2.html) + +## Viewing Available Snapshots + +The list of all available snapshots for the cluster is available in the Rancher UI. + +1. In the upper left corner, click **☰ > Cluster Management**. +1. In the **Clusters** page, go to the cluster where you want to view the snapshots and click its name. +1. Click the **Snapshots** tab to view the list of saved snapshots. These snapshots include a timestamp of when they were created. + +## Safe Timestamps (RKE) + +Snapshot files are timestamped to simplify processing the files using external tools and scripts, but in some S3 compatible backends, these timestamps were unusable. + +The option `safe_timestamp` is added to support compatible file names. When this flag is set to `true`, all special characters in the snapshot filename timestamp are replaced. + +This option is not available directly in the UI, and is only available through the `Edit as Yaml` interface. diff --git a/versioned_docs/version-2.14/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/back-up-rancher.md b/versioned_docs/version-2.14/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/back-up-rancher.md new file mode 100644 index 00000000000..2edb0398c8c --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/back-up-rancher.md @@ -0,0 +1,96 @@ +--- +title: Backing up Rancher +--- + + + + + +In this section, you'll learn how to back up Rancher running on any Kubernetes cluster. To backup Rancher installed with Docker, refer the instructions for [single node backups](back-up-docker-installed-rancher.md) + +The backup-restore operator needs to be installed in the local cluster, and only backs up the Rancher app. The backup and restore operations are performed only in the local Kubernetes cluster. + +Note that the rancher-backup operator version 2.x.x is for Rancher v2.6.x. + +:::caution + +When restoring a backup into a new Rancher setup, the version of the new setup should be the same as the one where the backup is made. The Kubernetes version should also be considered when restoring a backup, since the supported apiVersion in the cluster and in the backup file could be different. + +::: + +### Prerequisites + +The Rancher version must be v2.5.0 and up. + +Refer [here](migrate-rancher-to-new-cluster.md#2-restore-from-backup-using-a-restore-custom-resource) for help on restoring an existing backup file into a v1.22 cluster in Rancher v2.6.3. + +### 1. Install the Rancher Backup operator + +The backup storage location is an operator-level setting, so it needs to be configured when the Rancher Backups application is installed or upgraded. + +Backups are created as .tar.gz files. These files can be pushed to S3 or Minio, or they can be stored in a persistent volume. + +1. In the upper left corner, click **☰ > Cluster Management**. +1. On the **Clusters** page, go to the `local` cluster and click **Explore**. The `local` cluster runs the Rancher server. +1. Click **Apps > Charts**. +1. Click **Rancher Backups**. +1. Click **Install**. +1. Configure the default storage location. For help, refer to the [storage configuration section.](../../../reference-guides/backup-restore-configuration/storage-configuration.md) +1. Click **Install**. + +:::note + +There is a known issue in Fleet that occurs after performing a restoration using the backup-restore-operator: Secrets used for clientSecretName and helmSecretName are not included in Fleet gitrepos. Refer [here](../../../integrations-in-rancher/fleet/overview.md#troubleshooting) for a workaround. + +::: + +### 2. Perform a Backup + +To perform a backup, a custom resource of type Backup must be created. + +1. In the upper left corner, click **☰ > Cluster Management**. +1. On the **Clusters** page, go to the `local` cluster and click **Explore**. +1. In the left navigation bar, click **Rancher Backups > Backups**. +1. Click **Create**. +1. Create the Backup with the form, or with the YAML editor. +1. For configuring the Backup details using the form, click **Create** and refer to the [configuration reference](../../../reference-guides/backup-restore-configuration/backup-configuration.md) and to the [examples.](../../../reference-guides/backup-restore-configuration/examples.md#backup) +1. For using the YAML editor, we can click **Create > Create from YAML**. Enter the Backup YAML. This example Backup custom resource would create encrypted recurring backups in S3. The app uses the `credentialSecretNamespace` value to determine where to look for the S3 backup secret: + + ```yaml + apiVersion: resources.cattle.io/v1 + kind: Backup + metadata: + name: s3-recurring-backup + spec: + storageLocation: + s3: + credentialSecretName: s3-creds + credentialSecretNamespace: default + bucketName: rancher-backups + folder: rancher + region: us-west-2 + endpoint: s3.us-west-2.amazonaws.com + resourceSetName: rancher-resource-set-full + encryptionConfigSecretName: encryptionconfig + schedule: "@every 1h" + retentionCount: 10 + ``` + + :::note + + When creating the Backup resource using YAML editor, the `resourceSetName` must be set to `rancher-resource-set-full` or `rancher-resource-set-basic`. + + ::: + + For help configuring the Backup, refer to the [configuration reference](../../../reference-guides/backup-restore-configuration/backup-configuration.md) and to the [examples.](../../../reference-guides/backup-restore-configuration/examples.md#backup) + + :::caution + + The `rancher-backup` operator doesn't save the EncryptionConfiguration file. The contents of the EncryptionConfiguration file must be saved when an encrypted backup is created, and the same file must be used when restoring from this backup. + + ::: + +1. Click **Create**. + +**Result:** The backup file is created in the storage location configured in the Backup custom resource. The name of this file is used when performing a restore. + diff --git a/versioned_docs/version-2.14/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/back-up-restore-usage-guide.md b/versioned_docs/version-2.14/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/back-up-restore-usage-guide.md new file mode 100644 index 00000000000..528453584b1 --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/back-up-restore-usage-guide.md @@ -0,0 +1,162 @@ +--- +title: Backup Restore Usage Guide +--- + + + + + +The Rancher Backups chart is our solution for disaster recovery and migration. This chart allows you to take backups of your Kubernetes resources and save them to a variety of persistent storage locations. + +This chart is a very simple tool which has its hands in many different areas of the Rancher ecosystem. As a result, edge cases have arisen which lead to undocumented functionality. The purpose of this document is to highlight the proper and defined usage for Rancher Backups, as well as discussing some of these edge cases we’ve run into. + +## Functionality Overview + +### Backup + +The operator collects all the resources captured by the resourceSet in the chart as in-memory unstructured objects. After the resources have been collected, a compressed tar file of the resources are saved as a collection of manifests in JSON and then uploaded to a user-defined object store. This backup can be put on a repeating schedule and can also be encrypted. This encryption option is important since some of the resources are sensitive and the values are stored in plaintext without encryption. + +See the [Backup Configuration documentation](../../../reference-guides/backup-restore-configuration/backup-configuration.md) for more information about the options, including encryption, to configure a backup. + +:::note + +As noted in the [Backing up Rancher documentation](./back-up-rancher.md), you must manually save the encryption configuration file contents since the operator will **not** back it up. + +::: + +### Restore + +There are two main restore scenarios, restoring to a cluster with Rancher running and restoring to a fresh cluster. You can only restore to a cluster with Rancher running if it's the same cluster the backup was taken from and the [`prune` option](../../../reference-guides/backup-restore-configuration/restore-configuration.md#prune-during-restore) is enabled during the restore. A restore has similar inputs as a backup. It requires a backup filename, the encryptionConfigSecret name, and the storage location. + +Resources are restored in this order: + +1. Custom Resource Definitions (CRDs) +2. Cluster-scoped resources +3. Namespaced resources + +See the [Restore Configuration documentation](../../../reference-guides/backup-restore-configuration/restore-configuration.md) for more information about the options to configure a restore. + +### Resource Sets + +The resourceSet determines which resources the backup-restore-operator collects in a backup. It's a set of ResourceSelectors, which define the selection requirements using key/value matching, regular expression matching, or the Kubernetes client labelSelector. + +These are the different fields available for a resourceSelector: + +- apiVersion +- excludeKinds +- excludeResourceNameRegexp +- kinds +- kindsRegexp +- labelSelectors +- namespaceRegexp +- namespaces +- resourceNameRegexp +- resourceNames + +The Rancher Backups chart contains a [default resourceSet](https://github.com/rancher/backup-restore-operator/tree/release/v3.0/charts/rancher-backup/files/default-resourceset-contents), which is a combination of YAML files that are appended to one large resourceSet when the chart is installed. The file order does not matter. The resourceSets may differ between versions. + +:::caution + +If you wish to make edits to the resourceSet please edit it **before** installing the chart. + +::: + +## Proper Usage + +This section outlines the guidelines for the proper usage of the Rancher Backups chart according to its use case. + +### All Cases + +- Rancher Backups must be installed on the local cluster. + - Note: Rancher Backups does not handle any cluster other than the one it is installed on to. It may restore cluster resources that are on the local cluster but will not communicate with the downstream clusters or back them up. +- The Rancher version being restored to must match the Rancher version from backup. +- The Kubernetes version should be be considered since you may be restoring outdated resources (resources deprecated from the version of Kubernetes you are restoring to). + +### Backups + +- Some user generated resources will not be backed up unless they can are captured by the default resourceSet or the resourceSet was altered to capture them. + - We provide a label `resources.cattle.io/backup:true` that when added to a secret in any namespace, will result in it being backed up. +- Backups are non-mutating +- Backups are only of the local cluster + +### Restores + +- A restore refers to restoring a backup to the same cluster it was taken from. This can be with Rancher installed (**prune must be enabled**) or with it not installed (no special instructions). +- One thing to note when restoring is that you may find yourself needing to “wipe” the cluster of any Rancher resources. This can be done by deploying the [Rancher cleanup script](https://github.com/rancher/rancher-cleanup) as a job to the cluster. This allows you to install Rancher Backups again and restore to a completely fresh cluster. + - Make sure to use kubectl to deploy the scripts. + +### Migrations + +Migration have some more nuance since we are restoring to a different cluster. These are a few things to remember that are commonly missed or forgotten. + +- The Rancher domain must be the same when migrating. This means your previous cluster’s domain name must now point to the new cluster. +- Rancher should **not** be running already on the cluster you are migrating to. This can cause many issues with Rancher backups and certain Rancher services as well. +- Install the **same** version of Rancher from the backup **after** the backup has been restored. +- If you choose to provision the new cluster on a different Kubernetes version know that this can cause a wide variety of unsupported behaviors because the Kubernetes API available may be different from the one you took a backup from. This can lead to deprecated resources being restored which will cause issues. +- You should **not** perform any upgrades during a migration. + +## Edge Cases and Improper Usage + +Below are some examples of some **incorrect** uses or expectations of Rancher Backups. + +### Upgrades + +- Using Rancher backups for upgrading Rancher versions is not a valid use case. The recommended procedure is to take a backup of the current version, then upgrade your Rancher instance using [these instructions](../../../getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/upgrades.md), and then taking **another** backup after the upgrade is complete. This way if the upgrade fails you have a backup to restore to, and the second backup will be valid to restore to the upgraded Rancher version. +- Using Rancher backups for upgrading Kubernetes versions is not a valid use case either. Because the Kubernetes API and available resources are tied to the version, upgrading using backup restore can lead to issues with misaligned sets of resources which may be deprecated, unsupported, or updated. How to upgrade your cluster version will depend on how it was provisioned however the same format as above is recommended (backup, upgrade, backup). + +### ResourceSet + +- Because of evolving resources and services from various teams, developers should take note if new resources need to be added to or removed from the default resourceSet. +- Rancher backups only backs up what is captured by the default resourceSets (unless edited). We have added a specific label for user created secrets that will back up a secret of any name and namespace that has said label (see [Proper Usage on Backups](#backups)). + +### Downstream Clusters + +- Rancher Backups **only** backs up Kubernetes resources on the local cluster. This means downstream clusters are **not** touched or backed up other than their presence in resources in the local cluster. The updating and communication of downstream clusters falls upon the rancher-agent and rancher-webhook. + +### Restoring Deleted Resources + +- Some resources have external results produced, such as provisioning a downstream cluster. Deleting a downstream cluster and restoring the cluster resource on the local cluster does **not** cause Rancher to reprovision said cluster. Depending on the resource, restoring may not fully bring back the resource to an available state. +- The corner case of "restoring a deleted cluster" is **not** a supported feature. When it comes to downstream clusters, whether provisioned or imported, deleting them causes a series of cleanup tasks which doesn't allow the user to restore the deleted clusters. Provisioned clusters will have their nodes and Rancher-related provisioning resources destroyed, and imported clusters will likely have their Rancher agents and other resources/services related to registration with a local cluster destroyed. + +:::caution + +Trying to delete and restore a downstream cluster can lead to a variety of issues with Rancher, Rancher Backups, rancher-webhook, Fleet, and more. It is not recommended to do this. + +::: + +### Fleet, Harvester, and Other Services + +Other services, which are backed up by Rancher Backups, often change and evolve. As this happens, their resources and backup needs may change as well. Some resources may not need to be backed up and some may not be backed up at all. It is important for teams to consider this in their development process and assess whether their related resourceSets are correctly capturing the proper set of resources for their services to be restored correctly. + +## Monitoring backups and restores + +Rancher offers out-of-the box monitoring features for the Backup Operator. They are disabled by default but can be easily enabled when deploying the operator Helm Chart. + +### Metrics + +Metrics can be enabled by setting `monitoring.metrics.enabled: true` and `monitoring.serviceMonitor.enabled: true` in the Helm Chart values. When enabled, the Operator exports the following metrics. Note that *rancher-monitoring* needs to be previously installed for the metrics to be properly exported. + +| **Metric Name** | **Description** | +|----------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------| +| `rancher_backup_info` | Details on a specific Rancher Backup CR (labels: `name`, `status`, `resourceSetName`, `retentionCount`, `backupType`, `filename`, `storageLocation`, `nextSnapshot`, `lastSnapshot`). Type *GaugeVec*. | +| `rancher_backup_count` | Number of existing Rancher Backup CRs. Type *Gauge*. | +| `rancher_backups_attempted_total` | Total number of Rancher Backups processed by the Operator (labels: `name`). Type *CounterVec*. | +| `rancher_backups_failed_total` | Total number of failed Rancher Backups processed by this operator (labels: `name`). Type *CounterVec*. | +| `rancher_backup_duration_seconds` | Duration of each backup processed by the Operator in seconds (labels: `name`). Type *HistogramVec*, buckets can be customized by the user. | +| `rancher_backup_last_processed_timestamp_seconds` | Unix time of when the last Backup was processed (in seconds) (labels: `name`). Type *GaugeVec*. | +| `rancher_restore_info` | Details on a specific Rancher Restore CR (labels: `name`, `status`, `fileName`, `prune`, `storageLocation`, `restoreTime`). Type *GaugeVec*. | +| `rancher_restore_count` | Number of existing Rancher Restore CRs. Type *Gauge*. | + +### Alerting + +Only one alert is provided by default, 'BackupFailed', which warns users when a Backup fails to be processed by the Operator. It can be enabled by setting `monitoring.prometheusRules.defaultAlert.enabled: true`. + +Users can also deploy their own alerting rules by setting `monitoring.prometheusRules.customRules.enabled: true` and defining them under `monitoring.prometheusRules.customRules.rules`. + +### Dashboards + +Rancher also provides Grafana dashboards to help monitor the Backup Operator health. These, however, can only be deployed by the *rancher-monitoring* Helm Chart. To do so `rancherBackupMonitoring.dashboards.enabled: true` needs to be set. + +## Conclusion + +Rancher Backups is a very useful tool, however it is somewhat limited in its scope and intended purposes. In order to avoid possible difficulties, it is important to follow the specific procedures described to ensure the proper operation of the chart. diff --git a/versioned_docs/version-2.14/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/backup-restore-and-disaster-recovery.md b/versioned_docs/version-2.14/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/backup-restore-and-disaster-recovery.md new file mode 100644 index 00000000000..c3b26afd434 --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/backup-restore-and-disaster-recovery.md @@ -0,0 +1,100 @@ +--- +title: Backup, Restore, and Disaster Recovery +keywords: [rancher backup restore, rancher backup and restore, backup restore rancher, rancher backup and restore rancher] +--- + + + + + +In this section, you'll learn how to create backups of Rancher, how to restore Rancher from backup, and how to migrate Rancher to a new Kubernetes cluster. + +The `rancher-backup` operator is used to backup and restore Rancher on any Kubernetes cluster. This application is a Helm chart, and it can be deployed through the Rancher **Apps** page, or by using the Helm CLI. The `rancher-backup` Helm chart is [here.](https://github.com/rancher/charts/tree/release-v2.6/charts/rancher-backup) + +The backup-restore operator needs to be installed in the local cluster, and only backs up the Rancher app. The backup and restore operations are performed only in the local Kubernetes cluster. + + +## Backup and Restore for Rancher installed with Docker + +For Rancher installed with Docker, refer to [this page](back-up-docker-installed-rancher.md) to perform backups and [this page](restore-docker-installed-rancher.md) to perform restores. + +## How Backups and Restores Work + +The `rancher-backup` operator introduces three custom resources: Backups, Restores, and ResourceSets. The following cluster-scoped custom resource definitions are added to the cluster: + +- `backups.resources.cattle.io` +- `resourcesets.resources.cattle.io` +- `restores.resources.cattle.io` + +The ResourceSet defines which Kubernetes resources need to be backed up. The ResourceSet is not available to be configured in the Rancher UI because the values required to back up Rancher are predefined. This ResourceSet should not be modified. + +When a Backup custom resource is created, the `rancher-backup` operator calls the `kube-apiserver` to get the resources in the ResourceSet that the Backup custom resource refers to. + +The operator then creates the backup file in the .tar.gz format and stores it in the location configured in the Backup resource. + +When a Restore custom resource is created, the operator accesses the backup .tar.gz file specified by the Restore, and restores the application from that file. + +The Backup and Restore custom resources can be created in the Rancher UI, or by using `kubectl apply`. + +:::note + +Refer [here](migrate-rancher-to-new-cluster.md#2-restore-from-backup-using-a-restore-custom-resource) for help on restoring an existing backup file into a v1.22 cluster in Rancher v2.6.3. + +::: + +## Installing the rancher-backup Operator + +The `rancher-backup` operator can be installed from the Rancher UI, or with the Helm CLI. In both cases, the `rancher-backup` Helm chart is installed on the Kubernetes cluster running the Rancher server. It is a cluster-admin only feature and available only for the **local** cluster. (*If you do not see `rancher-backup` in the Rancher UI, you may have selected the wrong cluster.*) + +:::note + +There is a known issue in Fleet that occurs after performing a restoration using the backup-restore-operator: Secrets used for clientSecretName and helmSecretName are not included in Fleet gitrepos. Refer [Fleet Troubleshooting](../../../integrations-in-rancher/fleet/overview.md#troubleshooting) for a workaround. + +::: + +### Installing rancher-backup with the Rancher UI + +1. In the upper left corner, click **☰ > Cluster Management**. +1. On the **Clusters** page, go to the `local` cluster and click **Explore**. +1. In the left navigation bar, **Apps > Charts**. +1. Click **Rancher Backups**. +1. Click **Install**. +1. Optional: Configure the default storage location. For help, refer to the [configuration section.](../../../reference-guides/backup-restore-configuration/storage-configuration.md) +1. Click **Install**. + +**Result:** The `rancher-backup` operator is installed. + +From the **Cluster Dashboard,** you can see the `rancher-backup` operator listed under **Deployments**. + +To configure the backup app in Rancher, go to the left navigation menu and click **Rancher Backups**. + +### RBAC + +Only the rancher admins and the local cluster’s cluster-owner can: + +* Install the Chart +* See the navigation links for Backup and Restore CRDs +* Perform a backup or restore by creating a Backup CR and Restore CR respectively +* List backups/restores performed so far + +## Backing up Rancher + +A backup is performed by creating a Backup custom resource. For a tutorial, refer to [this page.](back-up-rancher.md) + +## Restoring Rancher + +A restore is performed by creating a Restore custom resource. For a tutorial, refer to [this page.](restore-rancher.md) + +## Migrating Rancher to a New Cluster + +A migration is performed by following [these steps.](migrate-rancher-to-new-cluster.md) + +## Default Storage Location Configuration + +Configure a default storage location for your backups. There are various configuration options, such as specifying an S3-compatible object store as the location for individual backups or choosing an existing `StorageClass` during installation of the `backup-restore-operator` Helm chart. You also have the option to override the configured storage location with each backup, but are limited to using an S3-compatible or Minio object store. + +For information on configuring these options, refer to [this page.](../../../reference-guides/backup-restore-configuration/storage-configuration.md) + +### Example YAML File: Rancher Backup Helm Chart + +The example [values.yaml file](../../../reference-guides/backup-restore-configuration/storage-configuration.md#example-yaml-file-rancher-backup-helm-chart) can be used to configure the `backup-restore-operator` when the Helm CLI is used to install it. diff --git a/versioned_docs/version-2.14/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/migrate-rancher-to-new-cluster.md b/versioned_docs/version-2.14/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/migrate-rancher-to-new-cluster.md new file mode 100644 index 00000000000..69697316d5d --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/migrate-rancher-to-new-cluster.md @@ -0,0 +1,245 @@ +--- +title: Migrating Rancher to a New Cluster +--- + + + + + +If you are migrating Rancher to a new Kubernetes cluster, you don't need to install Rancher on the new cluster first. If Rancher is restored to a new cluster with Rancher already installed, it can cause problems. + +### Prerequisites + +These instructions assume that you have [created a backup](back-up-rancher.md) and already installed a new Kubernetes cluster where Rancher will be deployed. The backup is specific to the Rancher application and can only migrate the Rancher application. + +:::caution + +You must use the same hostname that was set as the server URL in the original cluster. If you don't, downstream clusters will show as unavailable in the cluster management page of the UI, and you won't be able to click inside the cluster or on the cluster's **Explore** button. + +::: + +Rancher version must be v2.5.0 and up + +Rancher can be installed on any Kubernetes cluster, including hosted Kubernetes clusters such as Amazon EKS clusters. For help installing Kubernetes, refer to the documentation of the Kubernetes distribution. A Rancher-created Kubernetes distributions such as, but not limited to, [RKE](https://rke.docs.rancher.com/installation) or [K3s](https://docs.k3s.io/installation) may also be used. + +Since Rancher can be installed on any Kubernetes cluster, you can use this backup and restore method to migrate Rancher from one Kubernetes cluster to any other Kubernetes cluster. This method *only* migrates Rancher-related resources and won't affect other applications on the cluster. Refer to the [support matrix](https://www.suse.com/lifecycle/) to identify which Kubernetes cluster types and versions are supported for your Rancher version. + +### 1. Install the rancher-backup Helm chart + +Install the [`rancher-backup chart`](https://github.com/rancher/backup-restore-operator/tags): + + 1. Add the Helm repository: + + ```bash + helm repo add rancher-charts https://charts.rancher.io + helm repo update + ``` + + 1. Set a `CHART_VERSION` variable, selecting a `rancher-backup` chart version compatible with your version of Rancher. See the [support matrix](https://www.suse.com/suse-rancher/support-matrix/all-supported-versions), within the **Rancher Apps / Cluster Tools** section, to see which `rancher-backup` versions are supported: + + ```bash + CHART_VERSION= + ``` + + 1. Install the charts: + + ```bash + helm install rancher-backup-crd rancher-charts/rancher-backup-crd -n cattle-resources-system --create-namespace --version $CHART_VERSION + helm install rancher-backup rancher-charts/rancher-backup -n cattle-resources-system --version $CHART_VERSION + ``` + + :::note + + The above assumes an environment with outbound connectivity to Docker Hub. + + For an **air-gapped environment**, use the following Helm values to pull the `backup-restore-operator` and `kubectl` images from your private registry when you install the rancher-backup Helm chart. + + ```bash + --set image.repository=/rancher/backup-restore-operator --set global.kubectl.repository=/rancher/kubectl + ``` + + If the host running the Helm commands is **also air-gapped and cannot reach charts.rancher.io**, download the charts on a non-air-gapped host and then install them from local files on the air-gapped host. + + On a non-air-gapped host: + + ```bash + helm repo add rancher-charts https://charts.rancher.io + helm repo update + helm fetch rancher-charts/rancher-backup-crd --version $CHART_VERSION + helm fetch rancher-charts/rancher-backup --version $CHART_VERSION + ``` + + Copy the `rancher-backup-crd-.tgz` and `rancher-backup-.tgz` files to the air-gapped host, then use them to install the charts: + + ```bash + helm install rancher-backup-crd ./rancher-backup-crd-.tgz -n cattle-resources-system --create-namespace + helm install rancher-backup ./rancher-backup-.tgz -n cattle-resources-system --set image.repository=/rancher/backup-restore-operator --set global.kubectl.repository=/rancher/kubectl + ``` + + ::: + +### 2. Restore from backup using a Restore custom resource + +1. When using S3 object storage as the backup source for a restore that requires credentials, create a `Secret` object in this cluster to add the S3 credentials. The secret data must have two keys - `accessKey`, and `secretKey`, that contain the S3 credentials. + + The secret can be created in any namespace, this example uses the default namespace. + + ```bash + kubectl create secret generic s3-creds \ + --from-literal=accessKey= \ + --from-literal=secretKey= + ``` + + :::note + + Add your access key and secret key as values for `accessKey` and `secretKey` in the command above. + + ::: + +1. Create a `Restore` object: + + During a migration, `prune` must be set to `false`. See the example below: + + ```yaml + # restore-migration.yaml + apiVersion: resources.cattle.io/v1 + kind: Restore + metadata: + name: restore-migration + spec: + backupFilename: backup-b0450532-cee1-4aa1-a881-f5f48a007b1c-2020-09-15T07-27-09Z.tar.gz + // highlight-next-line + prune: false + // highlight-next-line + encryptionConfigSecretName: encryptionconfig + storageLocation: + s3: + credentialSecretName: s3-creds + credentialSecretNamespace: default + bucketName: backup-test + folder: ecm1 + region: us-west-2 + endpoint: s3.us-west-2.amazonaws.com + ``` + + :::note Important + + The field `encryptionConfigSecretName` should be used only if your backup was created with encryption enabled. + + If this applies, provide the name of the `Secret` object containing the encryption config file. If you only have the encryption config file, but don't have the secret created in this cluster, use the following steps to create the secret: + + 1. Create an [encryption configuration file](../../../reference-guides/backup-restore-configuration/backup-configuration.md#encryption) + 1. The command below uses a file named `encryption-provider-config.yaml`, with the `--from-file` flag. Run the below once the `EncryptionConfiguration` is saved in a file called `encryption-provider-config.yaml`: + + ```bash + kubectl create secret generic encryptionconfig \ + --from-file=./encryption-provider-config.yaml \ + -n cattle-resources-system + ``` + + ::: + +1. Apply the manifest, and monitor the Restore status: + 1. Apply the `Restore` object resource: + + ```bash + kubectl apply -f restore-migration.yaml + ``` + + 1. Watch the Restore status: + ```bash + kubectl get restore + ``` + + 1. Watch the restoration logs: + ```bash + kubectl logs -n cattle-resources-system --tail 100 -f -l app.kubernetes.io/instance=rancher-backup + ``` + + 1. Once the Restore resource has the status `Completed`, you can continue the cert-manager and Rancher installation. + +:::note Important: + +When migrating Rancher between any two different Kubernetes distributions (e.g. from K3s to RKE2), the object representing the local cluster has to be modified to allow Rancher to detect the new distribution. After the restoration is completed, and **before** bringing up Rancher on the new cluster, edit the local cluster object: + +```bash +kubectl edit clusters.management.cattle.io local +``` + +1. Change the value of `status.driver` to `imported`. +1. Remove `status.provider`. +1. Remove the entire `status.version` map. +1. Remove the label with the key `provider.cattle.io` in `metadata.labels`. +1. Remove the annotation with the key `management.cattle.io/current-cluster-controllers-version` in `metadata.annotations`. +1. Remove the entire `spec.rke2Config` or `spec.k3sConfig` map, if present. +1. Save the changes. + +Note that removing `spec.rke2Config` or `spec.k3sConfig` will erase your distribution-specific upgrade configuration for the local cluster. It can be [reconfigured](../../../getting-started/installation-and-upgrade/upgrade-and-roll-back-kubernetes.md) if the new distribution is configurable for the local cluster. + +::: + +### 3. Install cert-manager + +Follow the steps to [install cert-manager](../../../getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/install-upgrade-on-a-kubernetes-cluster.md#4-install-cert-manager) in the documentation about installing cert-manager on Kubernetes. + +### 4. Bring up Rancher with Helm + +Use the same version of Helm to install Rancher, that was used on the first cluster. + + +```bash +helm install rancher rancher-latest/rancher \ + --namespace cattle-system \ + --set hostname= \ + --version x.y.z +``` + +:::note + +If the original Rancher environment is running, you can collect the current values with a kubeconfig for the original environment: + +```bash +helm get values rancher -n cattle-system -o yaml > rancher-values.yaml +``` + +These values can be reused using the `rancher-values.yaml` file. Be sure to switch the kubeconfig to the new Rancher environment. + +```bash +helm install rancher rancher-latest/rancher -n cattle-system -f rancher-values.yaml --version x.y.z +``` + +::: + +### 5. Redirect Traffic to the New Cluster + +After migration completes, update your DNS records and any load balancers, so that traffic is routed correctly to the migrated cluster. Remember that you must use the same hostname that was set as the server URL in the original cluster. + +Full instructions on how to redirect traffic to the migrated cluster differ based on your specific environment. Refer to your hosting provider's documentation for more details. + +### 6. Scale Down the Original Rancher Instance + +After redirecting traffic to the new Rancher environment, **scale the original Rancher instance to 0 replicas** so it no longer contacts your managed clusters. + +Leaving the old server up can cause agents to keep contacting the original `server-url`, which often leaves clusters stuck in **Updating** in the new environment. + +```bash +kubectl scale deployment rancher -n cattle-system --replicas=0 +``` + +If you originally ran Rancher in Docker: + +```bash +docker stop +``` + +:::note + +If you wish to keep the original Rancher environment running, you can also restart the cattle-cluster-agent pods on each cluster connected to your Rancher environment. + +```bash +kubectl rollout restart deployment cattle-cluster-agent -n cattle-system +``` + +This triggers a rolling restart of the agent so it re-establishes the connection to the new Rancher environment. + +::: diff --git a/versioned_docs/version-2.14/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/restore-docker-installed-rancher.md b/versioned_docs/version-2.14/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/restore-docker-installed-rancher.md new file mode 100644 index 00000000000..a7479ec95cb --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/restore-docker-installed-rancher.md @@ -0,0 +1,76 @@ +--- +title: Restoring Backups—Docker Installs +--- + + + + + +If you encounter a disaster scenario, you can restore your Rancher Server to your most recent backup. + +## Before You Start + +During restore of your backup, you'll enter a series of commands, filling placeholders with data from your environment. These placeholders are denoted with angled brackets and all capital letters (``). Here's an example of a command with a placeholder: + +``` +docker run --volumes-from -v $PWD:/backup \ +busybox sh -c "rm /var/lib/rancher/* -rf && \ +tar pzxvf /backup/rancher-data-backup--" +``` + +In this command, `` and `-` are environment variables for your Rancher deployment. + +Cross reference the image and reference table below to learn how to obtain this placeholder data. Write down or copy this information before starting the procedure below. + +Terminal docker ps Command, Displaying Where to Find <RANCHER_CONTAINER_TAG> and <RANCHER_CONTAINER_NAME> + +![Placeholder Reference](/img/placeholder-ref.png) + +| Placeholder | Example | Description | +| -------------------------- | -------------------------- | --------------------------------------------------------- | +| `` | `v2.0.5` | The rancher/rancher image you pulled for initial install. | +| `` | `festive_mestorf` | The name of your Rancher container. | +| `` | `v2.0.5` | The version number for your Rancher backup. | +| `` | `9-27-18` | The date that the data container or backup was created. | +
+ +You can obtain `` and `` by logging into your Rancher Server by remote connection and entering the command to view the containers that are running: `docker ps`. You can also view containers that are stopped using a different command: `docker ps -a`. Use these commands for help anytime during while creating backups. + +## Restoring Backups + +Using a [backup](back-up-docker-installed-rancher.md) that you created earlier, restore Rancher to its last known healthy state. + +1. Using a remote Terminal connection, log into the node running your Rancher Server. + +1. Stop the container currently running Rancher Server. Replace `` with the name of your Rancher container: + + ``` + docker stop + ``` +1. Move the backup tarball that you created during completion of [Creating Backups—Docker Installs](back-up-docker-installed-rancher.md) onto your Rancher Server. Change to the directory that you moved it to. Enter `dir` to confirm that it's there. + + If you followed the naming convention we suggested in [Creating Backups—Docker Installs](back-up-docker-installed-rancher.md), it will have a name similar to `rancher-data-backup--.tar.gz`. + +1. Enter the following command to delete your current state data and replace it with your backup data, replacing the placeholders. Don't forget to close the quotes. + + :::danger + + This command deletes all current state data from your Rancher Server container. Any changes saved after your backup tarball was created will be lost. + + ::: + + ``` + docker run --volumes-from -v $PWD:/backup \ + busybox sh -c "rm /var/lib/rancher/* -rf && \ + tar pzxvf /backup/rancher-data-backup--.tar.gz" + ``` + + **Step Result:** A series of commands should run. + +1. Restart your Rancher Server container, replacing the placeholder. It will restart using your backup data. + + ``` + docker start + ``` + +1. Wait a few moments and then open Rancher in a web browser. Confirm that the restore succeeded and that your data is restored. diff --git a/versioned_docs/version-2.14/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/restore-rancher-launched-kubernetes-clusters-from-backup.md b/versioned_docs/version-2.14/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/restore-rancher-launched-kubernetes-clusters-from-backup.md new file mode 100644 index 00000000000..87cf3dfeefc --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/restore-rancher-launched-kubernetes-clusters-from-backup.md @@ -0,0 +1,99 @@ +--- +title: Restoring a Cluster from Backup +--- + + + + + +Etcd backup and recovery for [Rancher launched Kubernetes clusters](../launch-kubernetes-with-rancher/launch-kubernetes-with-rancher.md) can be easily performed. Snapshots of the etcd database are taken and saved either locally onto the etcd nodes or to a S3 compatible target. The advantages of configuring S3 is that if all etcd nodes are lost, your snapshot is saved remotely and can be used to restore the cluster. + +Rancher recommends enabling the [ability to set up recurring snapshots of etcd](back-up-rancher-launched-kubernetes-clusters.md#configuring-recurring-snapshots), but [one-time snapshots](back-up-rancher-launched-kubernetes-clusters.md#one-time-snapshots) can easily be taken as well. Rancher allows restore from [saved snapshots](#restoring-a-cluster-from-a-snapshot). + +Clusters can also be restored to a prior Kubernetes version and cluster configuration. + +## Viewing Available Snapshots + +The list of all available snapshots for the cluster is available. + +1. In the upper left corner, click **☰ > Cluster Management**. +1. In the **Clusters** page, go to the cluster where you want to view the snapshots and click the name of the cluster. +1. Click the **Snapshots** tab. The listed snapshots include a timestamp of when they were created. + +## Restoring a Cluster from a Snapshot + +If your Kubernetes cluster is broken, you can restore the cluster from a snapshot. + +Snapshots are composed of the cluster data in etcd, the Kubernetes version, and the cluster configuration in the `cluster.yml.` These components allow you to select from the following options when restoring a cluster from a snapshot: + +- **Restore just the etcd contents:** This restore is similar to restoring to snapshots in Rancher before v2.4.0. +- **Restore etcd and Kubernetes version:** This option should be used if a Kubernetes upgrade is the reason that your cluster is failing, and you haven't made any cluster configuration changes. +- **Restore etcd, Kubernetes versions and cluster configuration:** This option should be used if you changed both the Kubernetes version and cluster configuration when upgrading. + +When rolling back to a prior Kubernetes version, the [upgrade strategy options](../../../getting-started/installation-and-upgrade/upgrade-and-roll-back-kubernetes.md#configuring-the-upgrade-strategy) are ignored. Worker nodes are not cordoned or drained before being reverted to the older Kubernetes version, so that an unhealthy cluster can be more quickly restored to a healthy state. + +:::note Prerequisite: + +To restore snapshots from S3, the cluster needs to be configured to [take recurring snapshots on S3.](back-up-rancher-launched-kubernetes-clusters.md#configuring-recurring-snapshots) + +::: + +1. In the upper left corner, click **☰ > Cluster Management**. +1. In the **Clusters** page, go to the cluster where you want to view the snapshots and click the name of the cluster. +1. Click the **Snapshots** tab to view the list of saved snapshots. +1. Go to the snapshot you want to restore and click **⋮ > Restore**. +1. Select a **Restore Type**. +1. Click **Restore**. + +**Result:** The cluster will go into `updating` state and the process of restoring the `etcd` nodes from the snapshot will start. The cluster is restored when it returns to an `active` state. + +## Restoring a Cluster From a Snapshot When the controlplane/etcd Are Completely Unavailable + +In a disaster recovery scenario, the control plane and etcd nodes managed by Rancher in a downstream cluster may no longer be available or functioning. The cluster can be rebuilt by adding control plane and etcd nodes again, followed by restoring from an available snapshot. + +If you have a complete cluster failure, you must remove all etcd nodes/machines from your cluster before you can add a "new" etcd node for restore. + +:::note + +If you are using [local snapshots](./back-up-rancher-launched-kubernetes-clusters.md#local-backup-target), it is **VERY** important that you ensure you back up the corresponding snapshot you want to restore from the `/var/lib/rancher//server/db/snapshots/` folder on the etcd node you are going to be removing. You can copy the snapshot onto your new node in the `/var/lib/rancher//server/db/snapshots/` folder. Furthermore, if using local snapshots and restoring to a new node, restoration cannot be done via the UI as of now. + +::: + +1. Remove all etcd nodes from your cluster. + + 1. In the upper left corner, click **☰ > Cluster Management**. + 1. In the **Clusters** page, go to the cluster where you want to remove nodes. + 1. In the **Machines** tab, click **⋮ > Delete** on each node you want to delete. Initially, you will see the nodes hang in a `deleting` state, but once all etcd nodes are deleting, they will be removed together. This is due to the fact that Rancher sees all etcd nodes deleting and proceeds to "short circuit" the etcd safe-removal logic. + +1. After all etcd nodes are removed, add the new etcd node that you are planning to restore from. Assign the new node the role of `all` (etcd, controlplane, and worker). + + - If the node was previously in a cluster, [clean the node](../manage-clusters/clean-cluster-nodes.md#cleaning-up-nodes) first. + - For custom clusters, go to the **Registration** tab and check the box for `etcd, controlplane, and worker`. Then copy and run the registration command on your node. + - For node driver clusters, a new node is provisioned automatically. + + At this point, Rancher will indicate that restoration from etcd snapshot is required. + +1. Restore from an etcd snapshot. + + :::note + As the etcd node is a clean node, you may need to manually create the `/var/lib/rancher//server/db/snapshots/` path. + ::: + + - For S3 snapshots, restore using the UI. + 1. Click the **Snapshots** tab to view the list of saved snapshots. + 1. Go to the snapshot you want to restore and click **⋮ > Restore**. + 1. Select a **Restore Type**. + 1. Click **Restore**. + - For local snapshots, restore using the UI is **not** available. + 1. In the upper right corner, click **⋮ > Edit YAML**. + 1. The example YAML below can be added under your `rkeConfig` to configure the etcd restore: + + ```yaml + ... + rkeConfig: + etcdSnapshotRestore: + name: # This field is required. Refers to the filename of the associated etcdsnapshot object. + ... + ``` + +1. After restoration is successful, you can scale your etcd nodes back up to the desired redundancy. diff --git a/versioned_docs/version-2.14/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/restore-rancher.md b/versioned_docs/version-2.14/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/restore-rancher.md new file mode 100644 index 00000000000..f4ee9c4e203 --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/restore-rancher.md @@ -0,0 +1,92 @@ +--- +title: Restoring Rancher +--- + + + + + +This page outlines how to perform a restore with Rancher. + +Follow the instructions from this page when: +- The running Rancher instance is at the same version as when the backup was made. +- The upstream (local) cluster is the same as where the backup was made. + +:::note Important + +While restoring Rancher on the same setup, the operator will scale down the Rancher deployment when restore starts, and it will scale back up the deployment once restore completes. Rancher will be unavailable during the restore. + +::: + +:::note Warning for Fleet users +You must consider how to handle Kubernetes API server availability and paused GitRepos when restoring a Rancher setup +that is running Fleet workloads. See the [Fleet +documentation](http://fleet.rancher.io/gitrepo-add#backing-up-and-restoring) for more details. +::: + +:::tip + +* Follow those steps to [migrate Rancher](migrate-rancher-to-new-cluster.md). +* If you need to restore Rancher to a previous version after an upgrade, see the [rollback documentation](../../../getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/rollbacks.md). + +::: + +## Create the Restore Custom Resource + +A restore is performed by creating a Restore custom resource. + +1. In the upper left corner, click **☰ > Cluster Management**. +1. On the **Clusters** page, go to the `local` cluster and click **Explore**. The `local` cluster runs the Rancher server. +1. In the left navigation bar, click **Rancher Backups > Restores**. +1. Click **Create**. +1. Create the Restore with the form, or with YAML. For creating the Restore resource using form, refer to the [configuration reference](../../../reference-guides/backup-restore-configuration/restore-configuration.md) and to the [examples.](../../../reference-guides/backup-restore-configuration/examples.md) +1. For using the YAML editor, we can click **Create > Create from YAML**. Enter the Restore YAML. + + ```yaml + apiVersion: resources.cattle.io/v1 + kind: Restore + metadata: + name: restore-migration + spec: + backupFilename: backup-b0450532-cee1-4aa1-a881-f5f48a007b1c-2020-09-15T07-27-09Z.tar.gz + encryptionConfigSecretName: encryptionconfig + storageLocation: + s3: + credentialSecretName: s3-creds + credentialSecretNamespace: default + bucketName: rancher-backups + folder: rancher + region: us-west-2 + endpoint: s3.us-west-2.amazonaws.com + ``` + + For help configuring the Restore, refer to the [configuration reference](../../../reference-guides/backup-restore-configuration/restore-configuration.md) and to the [examples.](../../../reference-guides/backup-restore-configuration/examples.md) + +1. Click **Create**. + +**Result:** The rancher-operator scales down the rancher deployment during restore, and scales it back up once the restore completes. The resources are restored in this order: + +1. Custom Resource Definitions (CRDs) +2. Cluster-scoped resources +3. Namespaced resources + +## Logs + +To check how the restore is progressing, you can check the logs of the operator. Run this command to follow the logs: + +``` +kubectl logs -n cattle-resources-system -l app.kubernetes.io/name=rancher-backup -f +``` + +## Cleanup + +If you created the restore resource with kubectl, remove the resource to prevent a naming conflict with future restores. + +## Known Issues +In some cases, after restoring the backup, Rancher logs will show errors similar to the following: +``` +2021/10/05 21:30:45 [ERROR] error syncing 'c-89d82/m-4067aa68dd78': handler rke-worker-upgrader: clusters.management.cattle.io "c-89d82" not found, requeuing +``` +This happens because one of the resources that was just restored has finalizers, but the related resources have been deleted so the handler cannot find it. + +To eliminate the errors, we need to find and delete the resource that causes the error. See more information [here](https://github.com/rancher/rancher/issues/35050#issuecomment-937968556) diff --git a/versioned_docs/version-2.14/how-to-guides/new-user-guides/helm-charts-in-rancher/create-apps.md b/versioned_docs/version-2.14/how-to-guides/new-user-guides/helm-charts-in-rancher/create-apps.md new file mode 100644 index 00000000000..380bc196eb6 --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/new-user-guides/helm-charts-in-rancher/create-apps.md @@ -0,0 +1,135 @@ +--- +title: Creating Apps +--- + + + + + +:::tip + +For a complete walkthrough of developing charts, see the [Chart Template Developer's Guide](https://helm.sh/docs/chart_template_guide/) in the official Helm documentation. + +::: + +## Chart Types + +Rancher supports two different types of charts: Helm charts and Rancher charts. + +### Helm Charts + +Native Helm charts include an application along with other software required to run it. When deploying native Helm charts, you can provide the chart's parameter values in a YAML editor. + +### Rancher Charts + +Rancher charts are native Helm charts with two files that enhance user experience: `app-readme.md` and `questions.yaml`. Read more about them in [Additional Files for Rancher Charts.](#additional-files-for-rancher-charts) + +Rancher charts add simplified chart descriptions and configuration forms to make the application deployment easy. Rancher users do not need to read through the entire list of Helm variables to understand how to launch an application. + +## Chart Directory Structure + +You can provide Helm Charts in a standard, HTTP based Helm Repository. For more information see the [Chart Repository Guide](https://helm.sh/docs/topics/chart_repository) in the official Helm documentation. + +Alternatively you can organize your charts in a Git Repository and directly add this to the App Marketplace. + +The following table demonstrates the directory structure for a Git repository. The `charts` directory is the top level directory under the repository base. Adding the repository to Rancher will expose all charts contained within it. The `questions.yaml`, `README.md`, and `requirements.yml` files are specific to Rancher charts, but are optional for chart customization. + +``` +/ + │ + ├── charts/ + │ ├── / # This directory name will be surfaced in the Rancher UI as the chart name + │ │ ├── / # Each directory at this level provides different app versions that will be selectable within the chart in the Rancher UI + │ │ │ ├── Chart.yaml # Required Helm chart information file. + │ │ │ ├── questions.yaml # Form questions displayed within the Rancher UI. Questions display in Configuration Options.* + │ │ │ ├── README.md # Optional: Helm Readme file displayed within Rancher UI. This text displays in Detailed Descriptions. + │ │ │ ├── requirements.yml # Optional: YAML file listing dependencies for the chart. + │ │ │ ├── values.yml # Default configuration values for the chart. + │ │ │ ├── templates/ # Directory containing templates that, when combined with values.yml, generates Kubernetes YAML. +``` + +## Additional Files for Rancher Charts + +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. + +- `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 a values YAML config, which is more difficult. The following images display the difference between a Rancher chart (which includes `questions.yml`) and a native Helm chart (which does not). + +
Rancher Chart with questions.yml (top) vs. Helm Chart without (bottom)
+ + ![questions.yml](/img/rancher-app-2.6.png) + ![values.yaml](/img/helm-app-2.6.png) + + +### Chart.yaml +#### Annotations + +Rancher supports additional annotations that you can add to the `Chart.yaml` file. These annotations allow you to define application dependencies or configure additional UI defaults: + +| Annotation | Description | Example | +| --------------------------------- | ----------- | ------- | +| catalog.cattle.io/auto-install | If set, will install the specified chart in the specified version before installing this chart | other-chart-name=1.0.0 | +| catalog.cattle.io/display-name | A display name that should be displayed in the App Marketplace instead of the chart name | Display Name of Chart | +| catalog.cattle.io/namespace | A fixed namespace where the chart should be deployed in. If set, this can't be changed by the user | fixed-namespace | +| catalog.cattle.io/release-name | A fixed release name for the Helm installation. If set, this can't be changed by the user | fixed-release-name | +| catalog.cattle.io/requests-cpu | Total amount of CPU that should be unreserved in the cluster. If less CPU is available, a warning will be shown | 2000m | +| catalog.cattle.io/requests-memory | Total amount of memory that should be unreserved in the cluster. If less memory is available, a warning will be shown | 2Gi | +| catalog.cattle.io/os | Restricts the OS where this chart can be installed. Possible values: `linux`, `windows`. Default: no restriction | linux | + +### Keywords + +With the `keywords` option in the `Chart.yaml` file it is possible to provide a list of categories for sorting your application in the Rancher UI, like `infrastructure`, `monitoring` and more. + +### questions.yml + +Inside the `questions.yml`, most of the content will be around the questions to ask the end user, but there are some additional fields that can be set in this file. + +### Min/Max Rancher versions + +For each chart, you can add the minimum and/or maximum Rancher version, which determines whether or not this chart is available to be deployed from Rancher. + +:::note + +Even though Rancher release versions are prefixed with a `v`, there is *no* prefix for the release version when using this option. + +::: + +``` +rancher_min_version: 2.3.0 +rancher_max_version: 2.3.99 +``` + +### Question Variable Reference + +This reference contains variables that you can use in `questions.yml` nested under `questions:`. + +| 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, multiline, boolean, int, enum, password, storageclass, hostname, pvc, secret and cloudcredential).| +| required | bool | false | Define if the variable is required or not (true \| false)| +| default | string | false | Specify the default value. Only used if there is no corresponding value in the `values.yml` file. | +| 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 value. | +| max | int | false | Max integer value. | +| options | []string | false | Specify the options when the variable type is `enum`, for example: options:
- "ClusterIP"
- "NodePort"
- "LoadBalancer"| +| valid_chars | string | false | Regular expression for input chars validation. | +| invalid_chars | string | false | Regular expression for invalid input chars validation.| +| subquestions | []subquestion | false| Add an array of subquestions.| +| show_if | string | false | Show current variable if conditional variable is true. For example `show_if: "serviceType=Nodeport"` | +| show\_subquestion_if | string | false | Show subquestions if is true or equal to one of the options. for example `show_subquestion_if: "true"`| + +:::note + +`subquestions[]` cannot contain `subquestions` or `show_subquestions_if` keys, but all other keys in the above table are supported. + +::: diff --git a/versioned_docs/version-2.14/how-to-guides/new-user-guides/helm-charts-in-rancher/helm-charts-in-rancher.md b/versioned_docs/version-2.14/how-to-guides/new-user-guides/helm-charts-in-rancher/helm-charts-in-rancher.md new file mode 100644 index 00000000000..6754c04a747 --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/new-user-guides/helm-charts-in-rancher/helm-charts-in-rancher.md @@ -0,0 +1,278 @@ +--- +title: Helm Charts and Apps +--- + + + + + +In this section, you'll learn how to manage Helm chart repositories and apps in Rancher. + +## How Helm Charts Work in Rancher + +Helm chart repositories in Rancher are managed using **Apps**. + +Rancher uses a catalog-like system to import bundles of charts from repositories and then uses those charts to either deploy custom Kubernetes applications or Rancher's tools such as Monitoring or Istio. Rancher tools come as pre-loaded repositories which deploy as standalone Helm charts. Any additional repositories are only added to the current cluster. + +### Catalogs, Apps, and the Rancher UI + +[Rancher v2.4 and earlier](https://github.com/rancher/rancher-docs/tree/main/archived_docs/en/version-2.0-2.4/how-to-guides/new-user-guides/helm-charts-in-rancher/helm-charts-in-rancher.md), repositories of ready-to-deploy applications were called "catalogs". These repositories were managed through the **Catalogs** section of the UI. + +Rancher v2.5 replaced the former catalog system with a new **Apps & Marketplace** feature. + +Since Rancher v2.6.5, the **Apps & Marketplace** feature is named **Apps** in the UI. + +### Versioning Scheme + +The Rancher feature charts versioning scheme is centered around the major version of the charts and the `+up` annotation for upstream charts, where applicable. + +**Major Version:** The major versions of feature charts are tied to particular minor versions of Rancher. When you upgrade to a new Rancher minor version, you should ensure that all of your feature charts are also upgraded to the correct release line for the chart. + +**Charts based on upstream:** When you upgrade, make sure that the upstream chart version is compatible with your Rancher version. The `+up` annotation for the chart indicates which upstream version the Rancher chart is tracking. For example, `100.x.x+up16.6.0` for Monitoring tracks upstream kube-prometheus-stack `16.6.0` with some additional Rancher patches. + +When upgrading Rancher versions, don't downgrade the version of the chart that you are using. For example, if you are using a version of Monitoring that is later than `16.6.0` in Rancher v2.5, you shouldn't upgrade to `100.x.x+up16.6.0`. Instead, you should upgrade to the appropriate version in the next release. + +#### Prerelease Versions + +Prereleases adhere to [the specification](https://semver.org/#spec-item-9) defined by [Semantic Versioning 2.0.0](https://semver.org/). For example, a Helm chart with a version of `0.1.3-dev.12ab4f` is considered a prerelease. Prerelease versions are not displayed by default and must be configured to do so. + +To display prerelease versions: + +1. Click on your user avatar in the upper right corner. +1. Click **Preferences**. +1. Under **Helm Charts**, select **Include Prerelease Versions**. + +## Access Charts + +The **Charts** page contains all Rancher, Partner, and Custom charts. You can filter charts by selecting the left-most dropdown menu: + +* Rancher tools such as Logging or Monitoring are listed under the **Rancher** label. +* Partner charts are under the **Partners** label. +* Custom charts are listed under the name of their respective repository. + +All three types of charts are deployed and managed in the same way. + +:::note + +Apps managed by the Cluster Manager (the global view in the legacy Rancher UI) continue to be managed only by the Cluster Manager, and apps managed with **Apps** in the new UI must be managed only by **Apps**. + +::: + +To access the **Charts** page: + +1. Click **☰ > Cluster Management**. +1. Find the name of the cluster whose charts you want to access. Click **Explore** at the end of the cluster's row. +1. In the left navigation menu on the **Cluster Dashboard**, click **Apps > Charts**. + +## Manage Repositories + +The **Repositories** page lists your Helm repositories. These include traditional Helm endpoints which have an index.yaml, and Git repositories that are cloned and point to a specific branch. To use custom charts, add your repository here. After you add a repository, you can access custom charts in the **Charts** page, listed under the name of the repository. + +To access the **Repositories** page: + +1. Click **☰ > Cluster Management**. +1. Find the name of the cluster whose repositories you want to access. Click **Explore** at the end of the cluster's row. +1. In the left navigation menu on the **Cluster Dashboard**, click **Apps > Repositories**. + +### Add Custom Git Repositories + +To add a custom Git repository that contains your Helm charts or cluster template definitions: + +1. Click **☰ > Cluster Management**. +1. Find the name of the cluster whose repositories you want to access. Click **Explore** at the end of the cluster's row. +1. In the left navigation menu on the **Cluster Dashboard**, click **Apps > Repositories**. +1. Click **Create**. +1. Select the target, **Git repository containing Helm chart...**. +1. You must enter a name and a Git repository URL. The other fields, including the description, are optional. Enter an alternative branch name if you don't want to pull from whichever branch the repo owner has set as the default. Usually, the default branch is named either `main` or `master`. +1. Click **Create** to add the repository. + +After you add a chart repository to Rancher, it becomes available immediately. + +### Add Custom Helm Chart Repositories + +You can add your own Helm chart repositories to serve chart packages to Rancher. You can use any HTTP server, as long as the server can respond to GET requests and serve YAML files and tar archives. + +For more information on Helm chart repositories, see the [official Helm docs](https://helm.sh/docs/topics/chart_repository/). + +To add a custom Helm chart repository to Rancher: + +1. Click **☰ > Cluster Management**. +1. Find the name of the cluster whose repositories you want to access. Click **Explore** at the end of the cluster's row. +1. In the left navigation menu on the **Cluster Dashboard**, click **Apps > Repositories**. +1. Click **Create**. +1. Select the target, **http(s) URL to an index generated by Helm**. +1. Enter a repo name and the index URL address of the chart repository. +1. Click **Create** to add the repository. + +### Add Private Git/Helm Chart Repositories + +You can add private Git or Helm chart repositories with SSH key credentials or an HTTP basic auth secret, such as a username and password. + +### Add a Private CA to Repositories + +To add a private CA to Helm chart repositories, you must add a base64 encoded copy of the CA certificate in DER format to the `spec.caBundle field` of the chart repo, such as `openssl x509 -outform der -in ca.pem | base64 -w0`. Instructions are the same for both Git-based and HTTP-based repositories: + +1. Click **☰**. Under **Explore Cluster** in the left navigation menu, select a cluster. +1. In the left navigation menu on the **Cluster Dashboard**, click **Apps > Repositories**. +1. Find the row associated with the Git-based or HTTP-based repository you want to add a private CA to, and click **⋮ > Edit YAML**. +1. Set the `caBundle` value, as in the following example: + + ```yaml + [...] + spec: + caBundle: + MIIFXzCCA0egAwIBAgIUWNy8WrvSkgNzV0zdWRP79j9cVcEwDQYJKoZIhvcNAQELBQAwPzELMAkGA1UEBhMCVVMxCzAJBgNVBAgMAkNBMRQwEgYDVQQKDAtNeU9yZywgSW5jLjENMAsGA1UEAwwEcm9vdDAeFw0yMTEyMTQwODMyMTdaFw0yNDEwMDMwODMyMT + ... + nDxZ/tNXt/WPJr/PgEB3hQdInDWYMg7vGO0Oz00G5kWg0sJ0ZTSoA10ZwdjIdGEeKlj1NlPyAqpQ+uDnmx6DW+zqfYtLnc/g6GuLLVPamraqN+gyU8CHwAWPNjZonFN9Vpg0PIk1I2zuOc4EHifoTAXSpnjfzfyAxCaZsnTptimlPFJJqAMj+FfDArGmr4= + [...] + ``` + +:::note Helm chart repositories with authentication + +The Repo.Spec contains a `disableSameOriginCheck` value. This value allows you to bypass the same origin checks, sending the repository Authentication information as a Basic Auth Header with all API calls. This is not recommended but can be used as a temporary solution in cases of non-standard Helm chart repositories, such as those that have redirects to a different origin URL. + +To use this feature for an existing Helm chart repository, follow previous steps up to edit the YAML. On the `spec` portion of the YAML file, add `disableSameOriginCheck` and set it to `true`. + +```yaml +[...] +spec: + disableSameOriginCheck: true +[...] +``` + +::: + +### Add Custom OCI Chart Repositories + +Helm v3 introduced storing Helm charts as [Open Container Initiative (OCI)](https://opencontainers.org/about/overview/) artifacts in container registries. With Rancher v2.9.0, you can add [OCI-based Helm chart repositories](https://helm.sh/docs/topics/registries/) alongside HTTP-based and Git-based repositories. This means you can deploy apps that are stored as OCI artifacts. For more information, see [Using OCI Helm Chart Repositories](./oci-repositories.md). + +### Helm Compatibility + +Only Helm 3 compatible charts are supported. + +### Refresh Chart Repositories + +The **Refresh** button can be used to sync changes from selected Helm chart repositories on the **Repositories** page. + +To refresh a chart repository: + +1. Click **☰ > Cluster Management**. +1. Find the name of the cluster whose repositories you want to access. Click **Explore** at the end of the cluster's row. +1. In the left navigation menu on the **Cluster Dashboard**, click **Apps > Repositories**. +1. Use the toggle next to the **State** field to select all repositories, or toggle specified chart repositories to sync changes. +1. Click **Refresh**. +1. The **⋮** at the end of each chart repository row also includes a **Refresh** option, which can be clicked to refresh the respective repository. + +Non-Airgap Rancher installations upon refresh will reflect any chart repository changes immediately and you will see the **State** field for updated repositories move from `In Progress` to `Active` once the action is completed. + +Airgap installations where Rancher is configured to use the packaged copy of Helm system charts ([`useBundledSystemChart=true`](../../../getting-started/installation-and-upgrade/other-installation-methods/air-gapped-helm-cli-install/install-rancher-ha.md#helm-chart-options-for-air-gap-installations)) will only refer to the [system-chart](https://github.com/rancher/system-charts) repository that comes bundled and will not be able to be refreshed or synced. + +#### Refresh Interval + +Rancher v2.10.0 adds the `refreshInterval` field to the `ClusterRepo` CRD. The default value is 3600 seconds, meaning that Rancher syncs each Helm repository every 3600 seconds. + +To modify the refresh interval of a chart repository: + +1. Click **☰ > Cluster Management**. +1. Find the name of the cluster whose repositories you want to access. Click **Explore** at the end of the cluster's row. +1. In the left navigation menu on the **Cluster Dashboard**, click **Apps > Repositories**. +1. Find the repository you want to modify, and click **⋮ > Edit YAML**. +1. Set the **refreshInterval** field under **Spec** to the desired value in seconds. +1. Click **Save**. + +### Enable/Disable Helm Chart Repositories + +Rancher v2.10.0 adds the ability to enable and disable Helm repositories. Helm repositories are enabled by default. + +To disable a chart repository: + +1. Click **☰ > Cluster Management**. +1. Find the name of the cluster whose repositories you want to access. Click **Explore** at the end of the cluster's row. +1. In the left navigation menu on the **Cluster Dashboard**, click **Apps > Repositories**. +1. Find the repository you want to disable, and click **⋮ > Edit YAML**. +1. Set the **Enabled** field under **Spec** to **false**. +1. Click **Save**. +1. When you disable a repository, updates are disabled and new changes to the clusterRepo are not applied. + +To enable a chart repository: + +1. Click **☰ > Cluster Management**. +1. Find the name of the cluster whose repositories you want to access. Click **Explore** at the end of the cluster's row. +1. In the left navigation menu on the **Cluster Dashboard**, click **Apps > Repositories**. +1. Find the repository you want to disable, and click **⋮ > Edit YAML**. +1. Set the **Enabled** field under **Spec** to **true**. +1. Click **Save**. + +## Deploy and Upgrade Charts + +To install and deploy a chart: + +1. Click **☰ > Cluster Management**. +1. Find the name of the cluster whose repositories you want to access. Click **Explore** at the end of the cluster's row. +1. In the left navigation menu on the **Cluster Dashboard**, click **Apps > Charts**. +1. Select a chart, and click **Install**. + +Rancher and Partner charts may have extra configurations available through custom pages or questions.yaml files. However, all chart installations can modify the values.yaml and other basic settings. After you click **Install**, a Helm operation job is deployed, and the console for the job is displayed. + +To view all recent changes, click **Apps > Recent Operations** in the left navigation menu. From there you can view the calls, conditions, events, and logs. + +After installing a chart, you can view it by clicking **Apps > Installed Apps** in the left navigation menu. You can upgrade or delete the installation, and see further details. Upgrading uses the same forms and values as you saw during initial installation. + +Most Rancher tools have additional pages located in the toolbar below the **Apps** section to help manage and use the features. These pages include links to dashboards, forms to easily add Custom Resources, and additional information. + +:::caution + +If you are upgrading your chart using **Customize Helm options before upgrade**, and your chart contains immutable fields, using the `--force` option may result in errors. This is because some objects in Kubernetes can't be changed after they're created. To prevent this error: + + * Use the default upgrade option (i.e don't use `--force`). + * Uninstall the existing chart and install the upgraded chart. + * Delete the resources with immutable fields from the cluster before performing a forced upgrade. + +::: + +### Legacy Apps + +The upgrade button isn't available for legacy apps on the **Apps > Installed Apps** page. + +If you want to upgrade an installed legacy app, the [legacy feature flag](../../advanced-user-guides/enable-experimental-features/enable-experimental-features.md) must be turned on. This flag is automatically turned on if you had a legacy app already running before you upgraded Rancher. + +1. Enable the [legacy feature flag](../../advanced-user-guides/enable-experimental-features/enable-experimental-features.md), if it isn't enabled already. +1. Click **☰ > Cluster Management**. +1. Find the name of the cluster whose apps you want to access. Click **Explore** at the end of the cluster's row. +1. Click **Legacy > Project > Apps**. + +If you don't see **Apps** listed under **Legacy > Project**, click the project/namespace search bar in the top navigation and select the relevant project from the dropdown menu. + +To upgrade legacy multi-cluster apps: + +1. Click **☰**. +1. Under **Legacy Apps**, click **Multi-cluster Apps**. + +### Chart-Specific Information + +#### sriov Chart Deprecation and Migration + +The `sriov` (SR-IOV network operator) chart from the Rancher Charts repository is deprecated and will be removed in Rancher v2.10. Please migrate to the `sriov-network-operator` chart from the SUSE Edge repository (https://github.com/suse-edge/charts) instead. + +To migrate, follow these steps: + +1. Add the SUSE Edge repository to your cluster by following the steps in [Add Custom Git Repositories](#add-custom-git-repositories). +1. For the **Git Repo URL** field, enter `https://github.com/suse-edge/charts`. +1. Click **Create**. +1. In the left navigation menu on the **Cluster Dashboard**, click **Apps > Charts**. +1. Find the `sriov-network-operator` chart and click on it. +1. Click **Install**. +1. In the **Name** field, enter the same name you used for your existing `sriov` chart installation. +1. Click **Next**. +1. Click **Install**. + +**Result:** Rancher redirects to the **Installed Apps** page where your existing installation enters the **Updating** state. The migration is complete when it enters the **Deployed** state. + +## Limitations + +- Dashboard apps or Rancher feature charts can't be installed using the Rancher CLI. + +- When determining the most recent version to display for the **Upgradable** column on the **Apps > Installed Apps** page, rather than only considering versions of the Helm chart from the repository it was installed from, Rancher considers versions of the Helm chart from all repositories on the cluster. + + For example, suppose you install `cert-manager` v1.13.0 from repository A, where v1.14.0 is now the most recent version available. In this case, you expect **Upgradable** to display v1.14.0. However, if the cluster also has access to repository B where v1.15.0 of `cert-manager` is available, then **Upgradable** displays v1.15.0 even though the original installation used repository A. + diff --git a/versioned_docs/version-2.14/how-to-guides/new-user-guides/helm-charts-in-rancher/oci-repositories.md b/versioned_docs/version-2.14/how-to-guides/new-user-guides/helm-charts-in-rancher/oci-repositories.md new file mode 100644 index 00000000000..1ccf43e4a89 --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/new-user-guides/helm-charts-in-rancher/oci-repositories.md @@ -0,0 +1,109 @@ +--- +title: Using OCI-Based Helm Chart Repositories +--- + + + + + +Helm v3 introduced storing Helm charts as [Open Container Initiative (OCI)](https://opencontainers.org/about/overview/) artifacts in container registries. With Rancher v2.9.0, you can add [OCI-based Helm chart repositories](https://helm.sh/docs/topics/registries/) alongside HTTP-based and Git-based repositories. This means that you can deploy apps that are stored as OCI artifacts. + +## Add an OCI-Based Helm Chart Repository + +To add an OCI-based Helm chart repository through the Rancher UI: + +1. Click **☰ > Cluster Management**. +2. Find the name of the cluster whose repositories you want to access. Click **Explore** at the end of the cluster's row. +3. In the left navigation bar, select **Apps > Repositories**. +4. Click **Create**. +5. Enter a **Name** for the registry. Select **OCI Repository** as the target. +6. Enter the **OCI Repository Host URL** for the registry. The registry endpoint must not contain anything besides OCI Helm Chart artifacts. The artifacts should all have unique names. If you attempt to add an endpoint that contains any other kinds of files or artifacts, the OCI repository will not be added. + + :::note + + You can use the **OCI URL** field to fine-tune how many charts from the registry are available for installation on Rancher. More generic endpoints target more charts, as the following examples demonstrate: + + - `oci://`: Every chart in the registry becomes available for installation, regardless of namespace or tag. + - `oci:///`: Every chart in the specified namespace within the registry becomes available for installation. + - `oci:////`: Only the specified chart and any associated tags or versions of that chart become available for installation. + - `oci:////:`: Only the chart with the specified tag becomes available for installation. + + ::: + +7. Set up authentication. Select **Basicauth** from the authentication field and enter a username and password as required. Otherwise, create or select an **Authentication** secret. See [Authentication](#authentication-for-oci-based-helm-chart-repositories) for a full description. +8. (optional) Enter a base64 encoded DER certificate in the **CA Cert Bundle** field. This field is for cases where you have a private OCI-based Helm chart repository and need Rancher to trust its certificates. +9. (optional) To allow insecure connections without performing an SSL check, select **Skip TLS Verification**. To force Rancher to use HTTP instead of HTTPS to send requests to the repository, select **Insecure Plain Http**. +10. (optional) If your repository has a rate limiting policy and may respond with status code `429 Too Many Requests`, you may want to fill out the fields under **Exponential Back Off**: + - **Min Wait**: The minimum duration in seconds that Rancher should wait before retrying. The default is 1 second. + - **Max Wait**: The maximum duration in seconds that Rancher should wait before retrying. The default is 5 second. + - **Max Number of Retries**: The default is 5 retries. + + Once these values are set, Rancher responds to the `429` status code by staggering requests based on the minimum and maximum wait values. The wait time between retries increases exponentially, until Rancher has sent the maximum number of retries set. See [Rate Limiting](#rate-limiting-of-oci-based-helm-chart-repositories) for more details. +11. Add any labels and annotations. +12. Click **Create**. + +It may take some time for the OCI repository to activate. This is particularly true if the OCI endpoint contains multiple namespaces. + +## Authentication for OCI-Based Helm Chart Repositories + +Rancher supports BasicAuth for OCI registries. You must create a [**BasicAuth** Kubernetes secret](https://kubernetes.io/docs/concepts/configuration/secret/#basic-authentication-secret). You can also [create the secret through the Rancher UI](../kubernetes-resources-setup/secrets.md). + + +The CRD that is linked to the OCI-based Helm repository is `ClusterRepo`. + +## View Helm Charts in OCI-Based Helm Chart Repositories + +To view Helm charts in the OCI-based Helm chart repository after it achieves an `Active` state: + +1. Click **☰**. Under **Explore Cluster** in the left navigation menu, select a cluster. +1. Click **Apps > Charts**. +1. Select the OCI-based Helm chart repository from the dropdown. + +## Refresh an OCI-Based Helm Chart Repository + +Rancher automatically refreshes the OCI-based Helm chart repository every 6 hours. + +If you need to update immediately, you can [perform a manual refresh](./helm-charts-in-rancher.md#refresh-chart-repositories). + +## Update an OCI-Based Helm Chart Repository Configuration + +1. Click **☰ > Cluster Management**. +1. Find the name of the cluster whose repositories you want to access. Click **Explore** at the end of the cluster's row. +1. In the left navigation bar, select **Apps > Repositories**. +1. Find the row associated with the OCI-based Helm chart repository, and click **⋮**. +1. From the submenu, select **Edit Config**. + +## Delete an OCI-Based Helm Chart Repository + +1. Click **☰ > Cluster Management**. +1. Find the name of the cluster whose repositories you want to access. Click **Explore** at the end of the cluster's row. +1. In the left navigation bar, select **Apps > Repositories**. +1. Select the row associated with the OCI-based Helm chart repository, and click **Delete**. + +## Size Limitations of OCI-Based Helm Chart Repositories in Rancher + +Due to security concerns, there are limitations on how large of a Helm chart you can deploy through an OCI-based repository, and how much metadata you can use to describe the Helm charts within a single OCI endpoint. + +Rancher can deploy OCI Helm charts up to 20 MB in size. + +## Rate Limiting of OCI-Based Helm Chart Repositories + +Different OCI registries implement rate limiting in different ways. + +Most servers return a `Retry-After` header, indicating how long to wait before rate limiting is lifted. + +Docker Hub returns a `429` status code when it completes all allocated requests. It also returns a `RateLimit-Remaining` header which describes the rate limiting policy. + +Rancher currently checks for the `Retry-After` header. It also handles Docker Hub-style responses (status code `429` and the `RateLimit-Remaining` header) and automatically waits before making a new request. When handling `Retry-After` or Docker Hub-style responses, Rancher ignores `ExponentialBackOff` values. + +If you have an OCI-based Helm chart repository which doesn't implement the `Retry-After` or `RateLimit-Remaining` headers, and think you may be rate-limited at some point, fill out the fields under **Exponential Back Off** when you add the repository. + +For example, if you have an OCI-based Helm chart repository that doesn't return a `Retry-After` header, but you know that the server allows 50 requests in 24 hours, you can provide Rancher a **Min Wait** value of **86400** seconds, a **Max Wait** value of **90000** seconds, and a **Max Number of Retries** value of **1**. Then, if Rancher gets rate limited by the server, Rancher will wait for 24 hours before trying again. The request should succeed as Rancher hasn't sent any other requests in the previous 24 hours. + +## Troubleshooting OCI-based Helm Registries + +- To enhance logging information, [enable the debug option](../../../troubleshooting/other-troubleshooting-tips/logging.md#kubernetes-install) while deploying Rancher. + +- If there is any discrepancy between the repository contents and Rancher, you should refresh the cluster repository as a first resort. If the discrepancy persists, delete the OCI-based Helm chart repository from Rancher and add it again. Deleting the repository won't delete any Helm charts that are already installed. + +- Apps installed through OCI-based Helm chart repositories are subject to a known issue with how Rancher displays upgradeable version information. See the [Limitations](./helm-charts-in-rancher.md#limitations) section of **Helm Charts and Apps** for more details. diff --git a/versioned_docs/version-2.14/how-to-guides/new-user-guides/infrastructure-setup/amazon-elb-load-balancer.md b/versioned_docs/version-2.14/how-to-guides/new-user-guides/infrastructure-setup/amazon-elb-load-balancer.md new file mode 100644 index 00000000000..f0157a3f6e0 --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/new-user-guides/infrastructure-setup/amazon-elb-load-balancer.md @@ -0,0 +1,179 @@ +--- +title: Setting up Amazon ELB Network Load Balancer +--- + + + + + +This how-to guide describes how to set up a Network Load Balancer (NLB) in Amazon's EC2 service that will direct traffic to multiple instances on EC2. + +These examples show the load balancer being configured to direct traffic to three Rancher server nodes. If Rancher is installed on an RKE Kubernetes cluster, three nodes are required. If Rancher is installed on a K3s Kubernetes cluster, only two nodes are required. + +This tutorial is about one possible way to set up your load balancer, not the only way. Other types of load balancers, such as a Classic Load Balancer or Application Load Balancer, could also direct traffic to the Rancher server nodes. + +Rancher only supports using the Amazon NLB when terminating traffic in `tcp` mode for port 443 rather than `tls` mode. This is due to the fact that the NLB does not inject the correct headers into requests when terminated at the NLB. This means that if you want to use certificates managed by the Amazon Certificate Manager (ACM), you should use an ALB. + + + +## Requirements + +These instructions assume you have already created Linux instances in EC2. The load balancer will direct traffic to these nodes. + +## 1. Create Target Groups + +Begin by creating two target groups for the **TCP** protocol, one with TCP port 443 and one regarding TCP port 80 (providing redirect to TCP port 443). You'll add your Linux nodes to these groups. + +Your first NLB configuration step is to create two target groups. Technically, only port 443 is needed to access Rancher, but it's convenient to add a listener for port 80, because traffic to port 80 will be automatically redirected to port 443. + +Regardless of whether an NGINX Ingress or Traefik Ingress controller is used, the Ingress should redirect traffic from port 80 to port 443. + +1. Log into the [Amazon AWS Console](https://console.aws.amazon.com/ec2/) to get started. Make sure to select the **Region** where your EC2 instances (Linux nodes) are created. +1. Select **Services** and choose **EC2**, find the section **Load Balancing** and open **Target Groups**. +1. Click **Create target group** to create the first target group, regarding TCP port 443. + +:::note + +Health checks are handled differently based on the Ingress. For details, refer to [this section.](#health-check-paths-for-nginx-ingress-and-traefik-ingresses) + +::: + +#### Target Group (TCP port 443) + +Configure the first target group according to the table below. + +| Option | Setting | +|-------------------|-------------------| +| Target Group Name | `rancher-tcp-443` | +| Target type | `instance` | +| Protocol | `TCP` | +| Port | `443` | +| VPC | Choose your VPC | + +Health check settings: + +| Option | Setting | +|---------------------|-----------------| +| Protocol | TCP | +| Port | `override`,`80` | +| Healthy threshold | `3` | +| Unhealthy threshold | `3` | +| Timeout | `6 seconds` | +| Interval | `10 seconds` | + +Click **Create target group** to create the second target group, regarding TCP port 80. + +#### Target Group (TCP port 80) + +Configure the second target group according to the table below. + +| Option | Setting | +|-------------------|------------------| +| Target Group Name | `rancher-tcp-80` | +| Target type | `instance` | +| Protocol | `TCP` | +| Port | `80` | +| VPC | Choose your VPC | + + +Health check settings: + +| Option |Setting | +|---------------------|----------------| +| Protocol | TCP | +| Port | `traffic port` | +| Healthy threshold | `3` | +| Unhealthy threshold | `3` | +| Timeout | `6 seconds` | +| Interval | `10 seconds` | + +## 2. Register Targets + +Next, add your Linux nodes to both target groups. + +Select the target group named **rancher-tcp-443**, click the tab **Targets** and choose **Edit**. + +![](/img/ha/nlb/edit-targetgroup-443.png) + +Select the instances (Linux nodes) you want to add, and click **Add to registered**. + +*** +**Screenshot Add targets to target group TCP port 443**
+ +![](/img/ha/nlb/add-targets-targetgroup-443.png) + +*** +**Screenshot Added targets to target group TCP port 443**
+ +![](/img/ha/nlb/added-targets-targetgroup-443.png) + +When the instances are added, click **Save** on the bottom right of the screen. + +Repeat those steps, replacing **rancher-tcp-443** with **rancher-tcp-80**. The same instances need to be added as targets to this target group. + +## 3. Create Your NLB + +Use Amazon's Wizard to create a Network Load Balancer. As part of this process, you'll add the target groups you created in [1. Create Target Groups](#1-create-target-groups). + +1. From your web browser, navigate to the [Amazon EC2 Console](https://console.aws.amazon.com/ec2/). + +2. From the navigation pane, choose **LOAD BALANCING** > **Load Balancers**. + +3. Click **Create Load Balancer**. + +4. Choose **Network Load Balancer** and click **Create**. Then complete each form. + +- [Step 1: Configure Load Balancer](#step-1-configure-load-balancer) +- [Step 2: Configure Routing](#step-2-configure-routing) +- [Step 3: Register Targets](#step-3-register-targets) +- [Step 4: Review](#step-4-review) + +### Step 1: Configure Load Balancer + +Set the following fields in the form: + +- **Name:** `rancher` +- **Scheme:** `internal` or `internet-facing`. The scheme that you choose for your NLB is dependent on the configuration of your instances and VPC. If your instances do not have public IPs associated with them, or you will only be accessing Rancher internally, you should set your NLB Scheme to `internal` rather than `internet-facing`. +- **Listeners:** The Load Balancer Protocol should be `TCP` and the corresponding Load Balancer Port should be set to `443`. +- **Availability Zones:** Select Your **VPC** and **Availability Zones**. + +### Step 2: Configure Routing + +1. From the **Target Group** drop-down, choose **Existing target group**. +1. From the **Name** drop-down, choose `rancher-tcp-443`. +1. Open **Advanced health check settings**, and configure **Interval** to `10 seconds`. + +### Step 3: Register Targets + +Since you registered your targets earlier, all you have to do is click **Next: Review**. + +### Step 4: Review + +Look over the load balancer details and click **Create** when you're satisfied. + +After AWS creates the NLB, click **Close**. + +## 4. Add listener to NLB for TCP port 80 + +1. Select your newly created NLB and select the **Listeners** tab. + +2. Click **Add listener**. + +3. Use `TCP`:`80` as **Protocol** : **Port** + +4. Click **Add action** and choose **Forward to..**. + +5. From the **Forward to** drop-down, choose `rancher-tcp-80`. + +6. Click **Save** in the top right of the screen. + +## Health Check Paths for NGINX Ingress and Traefik Ingresses + +K3s and RKE Kubernetes clusters handle health checks differently because they use different Ingresses by default. + +For RKE Kubernetes clusters, NGINX Ingress is used by default, whereas for K3s Kubernetes clusters, Traefik is the default Ingress. + +- **Traefik:** The health check path is `/ping`. By default `/ping` is always matched (regardless of Host), and a response from [Traefik itself](https://docs.traefik.io/operations/ping/) is always served. +- **NGINX Ingress:** The default backend of the NGINX Ingress controller has a `/healthz` endpoint. By default `/healthz` is always matched (regardless of Host), and a response from [`ingress-nginx` itself](https://github.com/kubernetes/ingress-nginx/blob/0cbe783f43a9313c9c26136e888324b1ee91a72f/charts/ingress-nginx/values.yaml#L212) is always served. + +To simulate an accurate health check, it is a best practice to use the Host header (Rancher hostname) combined with `/ping` or `/healthz` (for K3s or for RKE clusters, respectively) wherever possible, to get a response from the Rancher Pods, not the Ingress. diff --git a/versioned_docs/version-2.14/how-to-guides/new-user-guides/infrastructure-setup/ha-k3s-kubernetes-cluster.md b/versioned_docs/version-2.14/how-to-guides/new-user-guides/infrastructure-setup/ha-k3s-kubernetes-cluster.md new file mode 100644 index 00000000000..7c7d1b10a15 --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/new-user-guides/infrastructure-setup/ha-k3s-kubernetes-cluster.md @@ -0,0 +1,77 @@ +--- +title: Setting up Infrastructure for a High Availability K3s Kubernetes Cluster +--- + + + + + +This tutorial is intended to help you provision the underlying infrastructure for a Rancher management server. + +The recommended infrastructure for the Rancher-only Kubernetes cluster differs depending on whether Rancher will be installed on a K3s Kubernetes cluster, an RKE Kubernetes cluster, or a single Docker container. + +For more information about each installation option, refer to [this page.](../../../getting-started/installation-and-upgrade/installation-and-upgrade.md) + +:::note Important: + +These nodes must be in the same region. You may place these servers in separate availability zones (datacenter). + +::: + +To install the Rancher management server on a high-availability K3s cluster, we recommend setting up the following infrastructure: + +- **Two Linux nodes,** typically virtual machines, in the infrastructure provider of your choice. +- **An external database** to store the cluster data. We recommend MySQL. +- **A load balancer** to direct traffic to the two nodes. +- **A DNS record** to map a URL to the load balancer. This will become the Rancher server URL, and downstream Kubernetes clusters will need to reach it. + +### 1. Set up Linux Nodes + +Make sure that your nodes fulfill the general installation requirements for [OS, container runtime, hardware, and networking.](../../../getting-started/installation-and-upgrade/installation-requirements/installation-requirements.md) + +For an example of one way to set up Linux nodes, refer to this [tutorial](nodes-in-amazon-ec2.md) for setting up nodes as instances in Amazon EC2. + +### 2. Set up External Datastore + +The ability to run Kubernetes using a datastore other than etcd sets K3s apart from other Kubernetes distributions. This feature provides flexibility to Kubernetes operators. The available options allow you to select a datastore that best fits your use case. + +For a high-availability K3s installation, you will need to set a [MySQL](https://www.mysql.com/) external database. Rancher has been tested on K3s Kubernetes clusters using MySQL version 5.7 as the datastore. + +When you install Kubernetes using the K3s installation script, you will pass in details for K3s to connect to the database. + +For an example of one way to set up the MySQL database, refer to this [tutorial](mysql-database-in-amazon-rds.md) for setting up MySQL on Amazon's RDS service. + +For the complete list of options that are available for configuring a K3s cluster datastore, refer to the [K3s documentation.](https://rancher.com/docs/k3s/latest/en/installation/datastore/) + +### 3. Set up the Load Balancer + +You will also need to set up a load balancer to direct traffic to the Rancher replica on both nodes. That will prevent an outage of any single node from taking down communications to the Rancher management server. + +When Kubernetes gets set up in a later step, the K3s tool will deploy a Traefik Ingress controller. This controller will listen on ports 80 and 443 of the worker nodes, answering traffic destined for specific hostnames. + +When Rancher is installed (also in a later step), the Rancher system creates an Ingress resource. That Ingress tells the Traefik Ingress controller to listen for traffic destined for the Rancher hostname. The Traefik Ingress controller, when receiving traffic destined for the Rancher hostname, will forward that traffic to the running Rancher pods in the cluster. + +For your implementation, consider if you want or need to use a Layer-4 or Layer-7 load balancer: + +- **A layer-4 load balancer** is the simpler of the two choices, in which you are forwarding TCP traffic to your nodes. We recommend configuring your load balancer as a Layer 4 balancer, forwarding traffic to ports TCP/80 and TCP/443 to the Rancher management cluster nodes. The Ingress controller on the cluster will redirect HTTP traffic to HTTPS and terminate SSL/TLS on port TCP/443. The Ingress controller will forward traffic to port TCP/80 to the Ingress pod in the Rancher deployment. +- **A layer-7 load balancer** is a bit more complicated but can offer features that you may want. For instance, a layer-7 load balancer is capable of handling TLS termination at the load balancer, as opposed to Rancher doing TLS termination itself. This can be beneficial if you want to centralize your TLS termination in your infrastructure. Layer-7 load balancing also offers the capability for your load balancer to make decisions based on HTTP attributes such as cookies, etc. that a layer-4 load balancer is not able to concern itself with. If you decide to terminate the SSL/TLS traffic on a layer-7 load balancer, you will need to use the `--set tls=external` option when installing Rancher in a later step. For more information, refer to the [Rancher Helm chart options.](../../../getting-started/installation-and-upgrade/installation-references/helm-chart-options.md#external-tls-termination) + +For an example showing how to set up an NGINX load balancer, refer to [this page.](nginx-load-balancer.md) + +For a how-to guide for setting up an Amazon ELB Network Load Balancer, refer to [this page.](amazon-elb-load-balancer.md) + +:::caution + +Do not use this load balancer (i.e, the `local` cluster Ingress) to load balance applications other than Rancher following installation. Sharing this Ingress with other applications may result in websocket errors to Rancher following Ingress configuration reloads for other apps. We recommend dedicating the `local` cluster to Rancher and no other applications. + +::: + +### 4. Set up the DNS Record + +Once you have set up your load balancer, you will need to create a DNS record to send traffic to this load balancer. + +Depending on your environment, this may be an A record pointing to the load balancer IP, or it may be a CNAME pointing to the load balancer hostname. In either case, make sure this record is the hostname that you intend Rancher to respond on. + +You will need to specify this hostname in a later step when you install Rancher, and it is not possible to change it later. Make sure that your decision is a final one. + +For a how-to guide for setting up a DNS record to route domain traffic to an Amazon ELB load balancer, refer to the [official AWS documentation.](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/routing-to-elb-load-balancer) diff --git a/versioned_docs/version-2.14/how-to-guides/new-user-guides/infrastructure-setup/ha-rke1-kubernetes-cluster.md b/versioned_docs/version-2.14/how-to-guides/new-user-guides/infrastructure-setup/ha-rke1-kubernetes-cluster.md new file mode 100644 index 00000000000..a2e638b9073 --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/new-user-guides/infrastructure-setup/ha-rke1-kubernetes-cluster.md @@ -0,0 +1,70 @@ +--- +title: Setting up Infrastructure for a High Availability RKE Kubernetes Cluster +--- + + + + + + + +This tutorial is intended to help you create a high-availability RKE cluster that can be used to install a Rancher server. + +:::note Important: + +These nodes must be in the same region. You may place these servers in separate availability zones (datacenter). + +::: + +To install the Rancher management server on a high-availability RKE cluster, we recommend setting up the following infrastructure: + +- **Three Linux nodes,** typically virtual machines, in an infrastructure provider such as Amazon's EC2, Google Compute Engine, or vSphere. +- **A load balancer** to direct front-end traffic to the three nodes. +- **A DNS record** to map a URL to the load balancer. This will become the Rancher server URL, and downstream Kubernetes clusters will need to reach it. + +These nodes must be in the same region/data center. You may place these servers in separate availability zones. + +### Why three nodes? + +In an RKE cluster, Rancher server data is stored on etcd. This etcd database runs on all three nodes. + +The etcd database requires an odd number of nodes so that it can always elect a leader with a majority of the etcd cluster. If the etcd database cannot elect a leader, etcd can suffer from [split brain](https://www.quora.com/What-is-split-brain-in-distributed-systems), requiring the cluster to be restored from backup. If one of the three etcd nodes fails, the two remaining nodes can elect a leader because they have the majority of the total number of etcd nodes. + +### 1. Set up Linux Nodes + +Make sure that your nodes fulfill the general installation requirements for [OS, container runtime, hardware, and networking.](../../../getting-started/installation-and-upgrade/installation-requirements/installation-requirements.md) + +For an example of one way to set up Linux nodes, refer to this [tutorial](nodes-in-amazon-ec2.md) for setting up nodes as instances in Amazon EC2. + +### 2. Set up the Load Balancer + +You will also need to set up a load balancer to direct traffic to the Rancher replica on any of the three nodes. That will prevent an outage of any single node from taking down communications to the Rancher management server. + +When Kubernetes gets set up in a later step, the RKE tool will deploy an NGINX Ingress controller. This controller will listen on ports 80 and 443 of the worker nodes, answering traffic destined for specific hostnames. + +When Rancher is installed (also in a later step), the Rancher system creates an Ingress resource. That Ingress tells the NGINX Ingress controller to listen for traffic destined for the Rancher hostname. The NGINX Ingress controller, when receiving traffic destined for the Rancher hostname, will forward that traffic to the running Rancher pods in the cluster. + +For your implementation, consider if you want or need to use a Layer-4 or Layer-7 load balancer: + +- **A layer-4 load balancer** is the simpler of the two choices, in which you are forwarding TCP traffic to your nodes. We recommend configuring your load balancer as a Layer 4 balancer, forwarding traffic to ports TCP/80 and TCP/443 to the Rancher management cluster nodes. The Ingress controller on the cluster will redirect HTTP traffic to HTTPS and terminate SSL/TLS on port TCP/443. The Ingress controller will forward traffic to port TCP/80 to the Ingress pod in the Rancher deployment. +- **A layer-7 load balancer** is a bit more complicated but can offer features that you may want. For instance, a layer-7 load balancer is capable of handling TLS termination at the load balancer, as opposed to Rancher doing TLS termination itself. This can be beneficial if you want to centralize your TLS termination in your infrastructure. Layer-7 load balancing also offers the capability for your load balancer to make decisions based on HTTP attributes such as cookies, etc. that a layer-4 load balancer is not able to concern itself with. If you decide to terminate the SSL/TLS traffic on a layer-7 load balancer, you will need to use the `--set tls=external` option when installing Rancher in a later step. For more information, refer to the [Rancher Helm chart options.](../../../getting-started/installation-and-upgrade/installation-references/helm-chart-options.md#external-tls-termination) + +For an example showing how to set up an NGINX load balancer, refer to [this page.](nginx-load-balancer.md) + +For a how-to guide for setting up an Amazon ELB Network Load Balancer, refer to [this page.](amazon-elb-load-balancer.md) + +:::caution + +Do not use this load balancer (i.e, the `local` cluster Ingress) to load balance applications other than Rancher following installation. Sharing this Ingress with other applications may result in websocket errors to Rancher following Ingress configuration reloads for other apps. We recommend dedicating the `local` cluster to Rancher and no other applications. + +::: + +### 3. Set up the DNS Record + +Once you have set up your load balancer, you will need to create a DNS record to send traffic to this load balancer. + +Depending on your environment, this may be an A record pointing to the LB IP, or it may be a CNAME pointing to the load balancer hostname. In either case, make sure this record is the hostname that you intend Rancher to respond on. + +You will need to specify this hostname in a later step when you install Rancher, and it is not possible to change it later. Make sure that your decision is a final one. + +For a how-to guide for setting up a DNS record to route domain traffic to an Amazon ELB load balancer, refer to the [official AWS documentation.](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/routing-to-elb-load-balancer) diff --git a/versioned_docs/version-2.14/how-to-guides/new-user-guides/infrastructure-setup/ha-rke2-kubernetes-cluster.md b/versioned_docs/version-2.14/how-to-guides/new-user-guides/infrastructure-setup/ha-rke2-kubernetes-cluster.md new file mode 100644 index 00000000000..7442579f3bb --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/new-user-guides/infrastructure-setup/ha-rke2-kubernetes-cluster.md @@ -0,0 +1,62 @@ +--- +title: Setting up Infrastructure for a High Availability RKE2 Kubernetes Cluster +--- + + + + + +This tutorial is intended to help you provision the underlying infrastructure for a Rancher management server. + +The recommended infrastructure for the Rancher-only Kubernetes cluster differs depending on whether Rancher will be installed on a RKE2 Kubernetes cluster, an RKE Kubernetes cluster, or a single Docker container. + +:::note Important: + +These nodes must be in the same region. You may place these servers in separate availability zones (datacenter). + +::: + +To install the Rancher management server on a high-availability RKE2 cluster, we recommend setting up the following infrastructure: + +- **Three Linux nodes,** typically virtual machines, in the infrastructure provider of your choice. +- **A load balancer** to direct traffic to the nodes. +- **A DNS record** to map a URL to the load balancer. This will become the Rancher server URL, and downstream Kubernetes clusters will need to reach it. + +### 1. Set up Linux Nodes + +Make sure that your nodes fulfill the general installation requirements for [OS, container runtime, hardware, and networking.](../../../getting-started/installation-and-upgrade/installation-requirements/installation-requirements.md) + +For an example of one way to set up Linux nodes, refer to this [tutorial](nodes-in-amazon-ec2.md) for setting up nodes as instances in Amazon EC2. + +### 2. Set up the Load Balancer + +You will also need to set up a load balancer to direct traffic to the Rancher replica on all nodes. That will prevent an outage of any single node from taking down communications to the Rancher management server. + +When Kubernetes gets set up in a later step, the RKE2 tool will deploy an Nginx Ingress controller. This controller will listen on ports 80 and 443 of the worker nodes, answering traffic destined for specific hostnames. + +When Rancher is installed (also in a later step), the Rancher system creates an Ingress resource. That Ingress tells the Nginx Ingress controller to listen for traffic destined for the Rancher hostname. The Nginx Ingress controller, when receiving traffic destined for the Rancher hostname, will forward that traffic to the running Rancher pods in the cluster. + +For your implementation, consider if you want or need to use a Layer-4 or Layer-7 load balancer: + +- **A layer-4 load balancer** is the simpler of the two choices, in which you are forwarding TCP traffic to your nodes. We recommend configuring your load balancer as a Layer 4 balancer, forwarding traffic to ports TCP/80 and TCP/443 to the Rancher management cluster nodes. The Ingress controller on the cluster will redirect HTTP traffic to HTTPS and terminate SSL/TLS on port TCP/443. The Ingress controller will forward traffic to port TCP/80 to the Ingress pod in the Rancher deployment. +- **A layer-7 load balancer** is a bit more complicated but can offer features that you may want. For instance, a layer-7 load balancer is capable of handling TLS termination at the load balancer, as opposed to Rancher doing TLS termination itself. This can be beneficial if you want to centralize your TLS termination in your infrastructure. Layer-7 load balancing also offers the capability for your load balancer to make decisions based on HTTP attributes such as cookies, etc. that a layer-4 load balancer is not able to concern itself with. If you decide to terminate the SSL/TLS traffic on a layer-7 load balancer, you will need to use the `--set tls=external` option when installing Rancher in a later step. For more information, refer to the [Rancher Helm chart options.](../../../getting-started/installation-and-upgrade/installation-references/helm-chart-options.md#external-tls-termination) + +For an example showing how to set up an NGINX load balancer, refer to [this page.](nginx-load-balancer.md) + +For a how-to guide for setting up an Amazon ELB Network Load Balancer, refer to [this page.](amazon-elb-load-balancer.md) + +:::caution + +Do not use this load balancer (i.e, the `local` cluster Ingress) to load balance applications other than Rancher following installation. Sharing this Ingress with other applications may result in websocket errors to Rancher following Ingress configuration reloads for other apps. We recommend dedicating the `local` cluster to Rancher and no other applications. + +::: + +### 3. Set up the DNS Record + +Once you have set up your load balancer, you will need to create a DNS record to send traffic to this load balancer. + +Depending on your environment, this may be an A record pointing to the load balancer IP, or it may be a CNAME pointing to the load balancer hostname. In either case, make sure this record is the hostname that you intend Rancher to respond on. + +You will need to specify this hostname in a later step when you install Rancher, and it is not possible to change it later. Make sure that your decision is a final one. + +For a how-to guide for setting up a DNS record to route domain traffic to an Amazon ELB load balancer, refer to the [official AWS documentation.](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/routing-to-elb-load-balancer) diff --git a/versioned_docs/version-2.14/how-to-guides/new-user-guides/infrastructure-setup/infrastructure-setup.md b/versioned_docs/version-2.14/how-to-guides/new-user-guides/infrastructure-setup/infrastructure-setup.md new file mode 100644 index 00000000000..19ee80b9594 --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/new-user-guides/infrastructure-setup/infrastructure-setup.md @@ -0,0 +1,13 @@ +--- +title: Infrastructure Setup +--- + + + + + +Don't have infrastructure for your Kubernetes cluster? Try one of these tutorials. + +To set up infrastructure for a high-availability K3s Kubernetes cluster with an external database, refer to [this page.](ha-k3s-kubernetes-cluster.md) + +To set up infrastructure for a high-availability RKE Kubernetes cluster, refer to [this page.](ha-rke1-kubernetes-cluster.md) diff --git a/versioned_docs/version-2.14/how-to-guides/new-user-guides/infrastructure-setup/mysql-database-in-amazon-rds.md b/versioned_docs/version-2.14/how-to-guides/new-user-guides/infrastructure-setup/mysql-database-in-amazon-rds.md new file mode 100644 index 00000000000..1d6646dd737 --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/new-user-guides/infrastructure-setup/mysql-database-in-amazon-rds.md @@ -0,0 +1,38 @@ +--- +title: Setting up a MySQL Database in Amazon RDS +--- + + + + + +This tutorial describes how to set up a MySQL database in Amazon's Relational Database Service (RDS). + +This database can later be used as an external datastore for a high-availability K3s Kubernetes cluster. + +1. Log into the [Amazon AWS RDS Console](https://console.aws.amazon.com/rds/) to get started. Make sure to select the **Region** where your EC2 instances (Linux nodes) are created. +1. In the left panel, click **Databases**. +1. Click **Create database**. +1. In the **Engine type** section, click **MySQL**. +1. In the **Version** section, choose **MySQL 5.7.22**. +1. In **Settings** section, under **Credentials Settings,** enter a master password for the **admin** master username. Confirm the password. +1. Expand the **Additional configuration** section. In the **Initial database name** field, enter a name. The name can have only letters, numbers, and underscores. This name will be used to connect to the database. +1. Click **Create database**. + +You'll need to capture the following information about the new database so that the K3s Kubernetes cluster can connect to it. + +To see this information in the Amazon RDS console, click **Databases,** and click the name of the database that you created. + +- **Username:** Use the admin username. +- **Password:** Use the admin password. +- **Hostname:** Use the **Endpoint** as the hostname. The endpoint is available in the **Connectivity & security** section. +- **Port:** The port should be 3306 by default. You can confirm it in the **Connectivity & security** section. +- **Database name:** Confirm the name by going to the **Configuration** tab. The name is listed under **DB name**. + +This information will be used to connect to the database in the following format: + +``` +mysql://username:password@tcp(hostname:3306)/database-name +``` + +For more information on configuring the datastore for K3s, refer to the [K3s documentation.](https://rancher.com/docs/k3s/latest/en/installation/datastore/) diff --git a/versioned_docs/version-2.14/how-to-guides/new-user-guides/infrastructure-setup/nginx-load-balancer.md b/versioned_docs/version-2.14/how-to-guides/new-user-guides/infrastructure-setup/nginx-load-balancer.md new file mode 100644 index 00000000000..0d065627669 --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/new-user-guides/infrastructure-setup/nginx-load-balancer.md @@ -0,0 +1,105 @@ +--- +title: Setting up an NGINX Load Balancer +--- + + + + + +NGINX will be configured as Layer 4 load balancer (TCP) that forwards connections to one of your Rancher nodes. + +In this configuration, the load balancer is positioned in front of your nodes. The load balancer can be any host capable of running NGINX. + +:::note + +Do not use one of your Rancher nodes as the load balancer. + +::: + +> These examples show the load balancer being configured to direct traffic to three Rancher server nodes. If Rancher is installed on an RKE Kubernetes cluster, three nodes are required. If Rancher is installed on a K3s Kubernetes cluster, only two nodes are required. + +## Install NGINX + +Start by installing NGINX on the node you want to use as a load balancer. NGINX has packages available for all known operating systems. The versions tested are `1.14` and `1.15`. For help installing NGINX, refer to their [install documentation](https://www.nginx.com/resources/wiki/start/topics/tutorials/install/). + +The `stream` module is required, which is present when using the official NGINX packages. Please refer to your OS documentation on how to install and enable the NGINX `stream` module on your operating system. + +## Create NGINX Configuration + +After installing NGINX, you need to update the NGINX configuration file, `nginx.conf`, with the IP addresses for your nodes. + +1. Copy and paste the code sample below into your favorite text editor. Save it as `nginx.conf`. + +2. From `nginx.conf`, replace both occurrences (port 80 and port 443) of ``, ``, and `` with the IPs of your nodes. + + :::note + + See [NGINX Documentation: TCP and UDP Load Balancing](https://docs.nginx.com/nginx/admin-guide/load-balancer/tcp-udp-load-balancer/) for all configuration options. + + ::: + +
Example NGINX config
+ + ``` + worker_processes 4; + worker_rlimit_nofile 40000; + + events { + worker_connections 8192; + } + + stream { + upstream rancher_servers_http { + least_conn; + server :80 max_fails=3 fail_timeout=5s; + server :80 max_fails=3 fail_timeout=5s; + server :80 max_fails=3 fail_timeout=5s; + } + server { + listen 80; + proxy_pass rancher_servers_http; + } + + } + + http { + + upstream rancher_servers_https { + least_conn; + server :443 max_fails=3 fail_timeout=5s; + server :443 max_fails=3 fail_timeout=5s; + server :443 max_fails=3 fail_timeout=5s; + } + server { + listen 443 ssl; + ssl_certificate /path/to/tls.crt; + ssl_certificate_key /path/to/key.key; + location / { + proxy_pass https://rancher_servers_https; + proxy_set_header Host ; + proxy_ssl_server_name on; + proxy_ssl_name + } + } + } + ``` + + +3. Save `nginx.conf` to your load balancer at the following path: `/etc/nginx/nginx.conf`. + +4. Load the updates to your NGINX configuration by running the following command: + + ``` + # nginx -s reload + ``` + +## Option - Run NGINX as Docker container + +Instead of installing NGINX as a package on the operating system, you can rather run it as a Docker container. Save the edited **Example NGINX config** as `/etc/nginx.conf` and run the following command to launch the NGINX container: + +``` +docker run -d --restart=unless-stopped \ + -p 80:80 -p 443:443 \ + -v /etc/nginx.conf:/etc/nginx/nginx.conf \ + nginx:1.14 +``` diff --git a/versioned_docs/version-2.14/how-to-guides/new-user-guides/infrastructure-setup/nodes-in-amazon-ec2.md b/versioned_docs/version-2.14/how-to-guides/new-user-guides/infrastructure-setup/nodes-in-amazon-ec2.md new file mode 100644 index 00000000000..bcc1337121a --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/new-user-guides/infrastructure-setup/nodes-in-amazon-ec2.md @@ -0,0 +1,78 @@ +--- +title: Setting up Nodes in Amazon EC2 +--- + + + + + +In this tutorial, you will learn one way to set up Linux nodes for the Rancher management server. These nodes will fulfill the node requirements for [OS, Docker, hardware, and networking.](../../../getting-started/installation-and-upgrade/installation-requirements/installation-requirements.md) + +If the Rancher server will be installed on an RKE Kubernetes cluster, you should provision three instances. + +If the Rancher server will be installed on a K3s Kubernetes cluster, you only need to provision two instances. + +If the Rancher server is installed in a single Docker container, you only need one instance. + +### 1. Optional Preparation + +- **Create IAM role:** To allow Rancher to manipulate AWS resources, such as provisioning new storage or new nodes, you will need to configure Amazon as a cloud provider. There are several things you'll need to do to set up the cloud provider on EC2, but part of this process is setting up an IAM role for the Rancher server nodes. For the full details on setting up the cloud provider, refer to this [page.](../kubernetes-clusters-in-rancher-setup/set-up-cloud-providers/set-up-cloud-providers.md) +- **Create security group:** We also recommend setting up a security group for the Rancher nodes that complies with the [port requirements for Rancher nodes.](../../../getting-started/installation-and-upgrade/installation-requirements/installation-requirements.md#port-requirements) + +### 2. Provision Instances + +1. Log into the [Amazon AWS EC2 Console](https://console.aws.amazon.com/ec2/) to get started. Make sure to take note of the **Region** where your EC2 instances (Linux nodes) are created, because all of the infrastructure for the Rancher management server should be in the same region. +1. In the left panel, click **Instances**. +1. Click **Launch Instance**. +1. In the section called **Step 1: Choose an Amazon Machine Image (AMI),** we will use Ubuntu 18.04 as the Linux OS, using `ami-0d1cd67c26f5fca19 (64-bit x86)`. Go to the Ubuntu AMI and click **Select**. +1. In the **Step 2: Choose an Instance Type** section, select the `t2.medium` type. +1. Click **Next: Configure Instance Details**. +1. In the **Number of instances** field, enter the number of instances. A high-availability K3s cluster requires only two instances, while a high-availability RKE cluster requires three instances. +1. Optional: If you created an IAM role for Rancher to manipulate AWS resources, select the new IAM role in the **IAM role** field. +1. Click **Next: Add Storage,** **Next: Add Tags,** and **Next: Configure Security Group**. +1. In **Step 6: Configure Security Group,** select a security group that complies with the [port requirements](../../../getting-started/installation-and-upgrade/installation-requirements/installation-requirements.md#port-requirements) for Rancher nodes. +1. Click **Review and Launch**. +1. Click **Launch**. +1. Choose a new or existing key pair that you will use to connect to your instance later. If you are using an existing key pair, make sure you already have access to the private key. +1. Click **Launch Instances**. + + +**Result:** You have created Rancher nodes that satisfy the requirements for OS, hardware, and networking. + +:::note + +If the nodes are being used for an RKE Kubernetes cluster, install Docker on each node in the next step. For a K3s Kubernetes cluster, the nodes are now ready to install K3s. + +::: + +### 3. Install Docker and Create User for RKE Kubernetes Cluster Nodes + +1. From the [AWS EC2 console,](https://console.aws.amazon.com/ec2/) click **Instances** in the left panel. +1. Go to the instance that you want to install Docker on. Select the instance and click **Actions > Connect**. +1. Connect to the instance by following the instructions on the screen that appears. Copy the Public DNS of the instance. An example command to SSH into the instance is as follows: +``` +sudo ssh -i [path-to-private-key] ubuntu@[public-DNS-of-instance] +``` +1. Run the following command on the instance to install Docker with one of Rancher's installation scripts: +``` +curl https://releases.rancher.com/install-docker/18.09.sh | sh +``` +1. When you are connected to the instance, run the following command on the instance to create a user: +``` +sudo usermod -aG docker ubuntu +``` +1. Repeat these steps so that Docker is installed on each node that will eventually run the Rancher management server. + +:::tip + +To find out whether a script is available for installing a certain Docker version, refer to this [GitHub repository,](https://github.com/rancher/install-docker) which contains all of Rancher’s Docker installation scripts. + +::: + +**Result:** You have set up Rancher server nodes that fulfill all the node requirements for OS, Docker, hardware and networking. + +### Next Steps for RKE Kubernetes Cluster Nodes + +If you are going to install an RKE cluster on the new nodes, take note of the **IPv4 Public IP** and **Private IP** of each node. This information can be found on the **Description** tab for each node after it is created. The public and private IP will be used to populate the `address` and `internal_address` of each node in the RKE cluster configuration file, `rancher-cluster.yml`. + +RKE will also need access to the private key to connect to each node. Therefore, you might want to take note of the path to your private keys to connect to the nodes, which can also be included in the `rancher-cluster.yml` under the `ssh_key_path` directive for each node. diff --git a/versioned_docs/version-2.14/how-to-guides/new-user-guides/kubernetes-cluster-setup/high-availability-installs.md b/versioned_docs/version-2.14/how-to-guides/new-user-guides/kubernetes-cluster-setup/high-availability-installs.md new file mode 100644 index 00000000000..7c17df3ed14 --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/new-user-guides/kubernetes-cluster-setup/high-availability-installs.md @@ -0,0 +1,27 @@ +--- +title: About High-availability Installations +--- + + + + + +We recommend using Helm, a Kubernetes package manager, to install Rancher on a dedicated Kubernetes cluster. This is called a high-availability Kubernetes installation because increased availability is achieved by running Rancher on multiple nodes. + +In a standard installation, Kubernetes is first installed on three nodes that are hosted in an infrastructure provider such as Amazon's EC2 or Google Compute Engine. + +Then Helm is used to install Rancher on top of the Kubernetes cluster. Helm uses Rancher's Helm chart to install a replica of Rancher on each of the three nodes in the Kubernetes cluster. We recommend using a load balancer to direct traffic to each replica of Rancher in the cluster, in order to increase Rancher's availability. + +The Rancher server data is stored on etcd. This etcd database also runs on all three nodes, and requires an odd number of nodes so that it can always elect a leader with a majority of the etcd cluster. If the etcd database cannot elect a leader, etcd can fail, requiring the cluster to be restored from backup. + +For information on how Rancher works, regardless of the installation method, refer to the [architecture section.](../../../reference-guides/rancher-manager-architecture/rancher-manager-architecture.md) + +### Recommended Architecture + +- DNS for Rancher should resolve to a layer 4 load balancer +- The Load Balancer should forward port TCP/80 and TCP/443 to all 3 nodes in the Kubernetes cluster. +- The Ingress controller will redirect HTTP to HTTPS and terminate SSL/TLS on port TCP/443. +- The Ingress controller will forward traffic to port TCP/80 on the pod in the Rancher deployment. + +![High-availability Kubernetes Installation of Rancher](/img/ha/rancher2ha.svg) +Kubernetes Rancher install with Layer 4 load balancer (TCP), depicting SSL termination at ingress controllers diff --git a/versioned_docs/version-2.14/how-to-guides/new-user-guides/kubernetes-cluster-setup/k3s-for-rancher.md b/versioned_docs/version-2.14/how-to-guides/new-user-guides/kubernetes-cluster-setup/k3s-for-rancher.md new file mode 100644 index 00000000000..16bf5703c58 --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/new-user-guides/kubernetes-cluster-setup/k3s-for-rancher.md @@ -0,0 +1,140 @@ +--- +title: Setting up a High-availability K3s Kubernetes Cluster for Rancher +--- + + + + + +This section describes how to install a Kubernetes cluster according to the [best practices for the Rancher server environment.](../../../reference-guides/rancher-manager-architecture/architecture-recommendations.md#environment-for-kubernetes-installations) + +For systems without direct internet access, refer to the air gap installation instructions. + +:::tip Single-node Installation Tip: + +In a single-node Kubernetes cluster, the Rancher server does not have high availability, which is important for running Rancher in production. However, installing Rancher on a single-node cluster can be useful if you want to save resources by using a single node in the short term, while preserving a high-availability migration path. + +To set up a single-node K3s cluster, run the Rancher server installation command on just one node instead of two nodes. + +In both single-node setups, Rancher can be installed with Helm on the Kubernetes cluster in the same way that it would be installed on any other cluster. + +::: + +## Prerequisites + +These instructions assume you have set up two nodes, a load balancer, a DNS record, and an external MySQL database as described in [this section.](../infrastructure-setup/ha-k3s-kubernetes-cluster.md) + +Rancher needs to be installed on a supported Kubernetes version. To find out which versions of Kubernetes are supported for your Rancher version, refer to the [Rancher Support Matrix](https://rancher.com/support-maintenance-terms/). + +To specify the K3s (Kubernetes) version, use the INSTALL_K3S_VERSION (e.g., `INSTALL_K3S_VERSION="v1.24.10+k3s1"`) environment variable when running the K3s installation script. + +## Installing Kubernetes + +### 1. Install Kubernetes and Set up the K3s Server + +When running the command to start the K3s Kubernetes API server, you will pass in an option to use the external datastore that you set up earlier. + +1. Connect to one of the Linux nodes that you have prepared to run the Rancher server. +1. On the Linux node, run this command to start the K3s server and connect it to the external datastore: + ``` + curl -sfL https://get.k3s.io | INSTALL_K3S_VERSION= sh -s - server \ + --datastore-endpoint="" + ``` + + Where `` is the connection URI for your datastore. For example, `mysql://username:password@tcp(hostname:3306)/database-name` if you're using MySQL. Valid datastores include etcd, MySQL, PostgreSQL, or SQLite (default). + + :::note + + The datastore endpoint can also be passed in using the environment variable `$K3S_DATASTORE_ENDPOINT`. + + ::: + +1. Get main server node token: + ``` + cat /var/lib/rancher/k3s/server/token + ``` + +1. Run command on your second K3s server node: + ``` + curl -sfL https://get.k3s.io | INSTALL_K3S_VERSION= sh -s - server \ + --datastore-endpoint="" \ + --token "" + ``` + +### 2. Confirm that K3s is Running + +To confirm that K3s has been set up successfully, run the following command on either of the K3s server nodes: +``` +sudo k3s kubectl get nodes +``` + +Then you should see two nodes with the master role: +``` +ubuntu@ip-172-31-60-194:~$ sudo k3s kubectl get nodes +NAME STATUS ROLES AGE VERSION +ip-172-31-60-194 Ready master 44m v1.17.2+k3s1 +ip-172-31-63-88 Ready master 6m8s v1.17.2+k3s1 +``` + +Then test the health of the cluster pods: +``` +sudo k3s kubectl get pods --all-namespaces +``` + +**Result:** You have successfully set up a K3s Kubernetes cluster. + +### 3. Save and Start Using the kubeconfig File + +When you installed K3s on each Rancher server node, a `kubeconfig` file was created on the node at `/etc/rancher/k3s/k3s.yaml`. This file contains credentials for full access to the cluster, and you should save this file in a secure location. + +To use this `kubeconfig` file, + +1. Install [kubectl,](https://kubernetes.io/docs/tasks/tools/install-kubectl/#install-kubectl) a Kubernetes command-line tool. +2. Copy the file at `/etc/rancher/k3s/k3s.yaml` and save it to the directory `~/.kube/config` on your local machine. +3. In the kubeconfig file, the `server` directive is defined as localhost. Configure the server as the DNS of your load balancer, referring to port 6443. (The Kubernetes API server will be reached at port 6443, while the Rancher server will be reached at ports 80 and 443.) Here is an example `k3s.yaml`: + +```yml +apiVersion: v1 +clusters: +- cluster: + certificate-authority-data: [CERTIFICATE-DATA] + server: [LOAD-BALANCER-DNS]:6443 # Edit this line + name: default +contexts: +- context: + cluster: default + user: default + name: default +current-context: default +kind: Config +preferences: {} +users: +- name: default + user: + password: [PASSWORD] + username: admin +``` + +**Result:** You can now use `kubectl` to manage your K3s cluster. If you have more than one kubeconfig file, you can specify which one you want to use by passing in the path to the file when using `kubectl`: + +``` +kubectl --kubeconfig ~/.kube/config/k3s.yaml get pods --all-namespaces +``` + +For more information about the `kubeconfig` file, refer to the [K3s documentation](https://rancher.com/docs/k3s/latest/en/cluster-access/) or the [official Kubernetes documentation](https://kubernetes.io/docs/concepts/configuration/organize-cluster-access-kubeconfig/) about organizing cluster access using `kubeconfig` files. + +### 4. Check the Health of Your Cluster Pods + +Now that you have set up the `kubeconfig` file, you can use `kubectl` to access the cluster from your local machine. + +Check that all the required pods and containers are healthy are ready to continue: + +``` +ubuntu@ip-172-31-60-194:~$ sudo kubectl get pods --all-namespaces +NAMESPACE NAME READY STATUS RESTARTS AGE +kube-system metrics-server-6d684c7b5-bw59k 1/1 Running 0 8d +kube-system local-path-provisioner-58fb86bdfd-fmkvd 1/1 Running 0 8d +kube-system coredns-d798c9dd-ljjnf 1/1 Running 0 8d +``` + +**Result:** You have confirmed that you can access the cluster with `kubectl` and the K3s cluster is running successfully. Now the Rancher management server can be installed on the cluster. diff --git a/versioned_docs/version-2.14/how-to-guides/new-user-guides/kubernetes-cluster-setup/kubernetes-cluster-setup.md b/versioned_docs/version-2.14/how-to-guides/new-user-guides/kubernetes-cluster-setup/kubernetes-cluster-setup.md new file mode 100644 index 00000000000..05267457f70 --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/new-user-guides/kubernetes-cluster-setup/kubernetes-cluster-setup.md @@ -0,0 +1,13 @@ +--- +title: Setting up a Kubernetes Cluster for Rancher Server +--- + + + + + +Don't have a Kubernetes cluster? Try one of these tutorials. + +This section contains information on how to install a Kubernetes cluster that the Rancher server can be installed on. + +Rancher can run on any Kubernetes cluster. diff --git a/versioned_docs/version-2.14/how-to-guides/new-user-guides/kubernetes-cluster-setup/rke2-for-rancher.md b/versioned_docs/version-2.14/how-to-guides/new-user-guides/kubernetes-cluster-setup/rke2-for-rancher.md new file mode 100644 index 00000000000..7a743f731a2 --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/new-user-guides/kubernetes-cluster-setup/rke2-for-rancher.md @@ -0,0 +1,169 @@ +--- +title: Setting up a High-availability RKE2 Kubernetes Cluster for Rancher +--- + + + + + +This section describes how to install a Kubernetes cluster according to the [best practices for the Rancher server environment.](../../../reference-guides/rancher-manager-architecture/architecture-recommendations.md#environment-for-kubernetes-installations) + +## Prerequisites + +These instructions assume you have set up three nodes, a load balancer, and a DNS record, as described in [this section.](../infrastructure-setup/ha-rke2-kubernetes-cluster.md) + +Note that in order for RKE2 to work correctly with the load balancer, you need to set up two listeners: one for the supervisor on port 9345, and one for the Kubernetes API on port 6443. + +Rancher needs to be installed on a supported Kubernetes version. To find out which versions of Kubernetes are supported for your Rancher version, refer to the [support maintenance terms.](https://rancher.com/support-maintenance-terms/) To specify the RKE2 version, use the INSTALL_RKE2_VERSION environment variable when running the RKE2 installation script. + +## Installing Kubernetes + +### 1. Install Kubernetes and Set up the RKE2 Server + +RKE2 server runs with embedded etcd so you will not need to set up an external datastore to run in HA mode. + +On the first node, you should set up the configuration file with your own pre-shared secret as the token. The token argument can be set on startup. + +If you do not specify a pre-shared secret, RKE2 will generate one and place it at /var/lib/rancher/rke2/server/node-token. + +To avoid certificate errors with the fixed registration address, you should launch the server with the tls-san parameter set. This option adds an additional hostname or IP as a Subject Alternative Name in the server's TLS cert, and it can be specified as a list if you would like to access via both the IP and the hostname. + +First, you must create the directory where the RKE2 config file is going to be placed: + +``` +mkdir -p /etc/rancher/rke2/ +``` + +Next, create the RKE2 config file at `/etc/rancher/rke2/config.yaml` using the following example: + +``` +token: my-shared-secret +tls-san: + - my-kubernetes-domain.com + - another-kubernetes-domain.com +``` +After that, you need to run the install command and enable and start rke2: + +``` +curl -sfL https://get.rke2.io | sh - +systemctl enable rke2-server.service +systemctl start rke2-server.service +``` +1. To join the rest of the nodes, you need to configure each additional node with the same shared token or the one generated automatically. Here is an example of the configuration file: + + token: my-shared-secret + server: https://:9345 + tls-san: + - my-kubernetes-domain.com + - another-kubernetes-domain.com +After that, you need to run the installer and enable, then start, rke2: + + curl -sfL https://get.rke2.io | sh - + systemctl enable rke2-server.service + systemctl start rke2-server.service + + +1. Repeat the same command on your third RKE2 server node. + +### 2. Confirm that RKE2 is Running + +Once you've launched the rke2 server process on all server nodes, ensure that the cluster has come up properly with + +``` +/var/lib/rancher/rke2/bin/kubectl \ + --kubeconfig /etc/rancher/rke2/rke2.yaml get nodes +You should see your server nodes in the Ready state. +``` + +Then test the health of the cluster pods: +``` +/var/lib/rancher/rke2/bin/kubectl \ + --kubeconfig /etc/rancher/rke2/rke2.yaml get pods --all-namespaces +``` + +**Result:** You have successfully set up a RKE2 Kubernetes cluster. + +### 3. Save and Start Using the kubeconfig File + +When you installed RKE2 on each Rancher server node, a `kubeconfig` file was created on the node at `/etc/rancher/rke2/rke2.yaml`. This file contains credentials for full access to the cluster, and you should save this file in a secure location. + +To use this `kubeconfig` file, + +1. Install [kubectl,](https://kubernetes.io/docs/tasks/tools/install-kubectl/#install-kubectl) a Kubernetes command-line tool. +2. Copy the file at `/etc/rancher/rke2/rke2.yaml` and save it to the directory `~/.kube/config` on your local machine. +3. In the kubeconfig file, the `server` directive is defined as localhost. Configure the server as the DNS of your control-plane load balancer, on port 6443. (The RKE2 Kubernetes API Server uses port 6443, while the Rancher server will be served via the NGINX Ingress on ports 80 and 443.) Here is an example `rke2.yaml`: + +```yml +apiVersion: v1 +clusters: +- cluster: + certificate-authority-data: [CERTIFICATE-DATA] + server: [LOAD-BALANCER-DNS]:6443 # Edit this line + name: default +contexts: +- context: + cluster: default + user: default + name: default +current-context: default +kind: Config +preferences: {} +users: +- name: default + user: + password: [PASSWORD] + username: admin +``` + +**Result:** You can now use `kubectl` to manage your RKE2 cluster. If you have more than one kubeconfig file, you can specify which one you want to use by passing in the path to the file when using `kubectl`: + +``` +kubectl --kubeconfig ~/.kube/config/rke2.yaml get pods --all-namespaces +``` + +For more information about the `kubeconfig` file, refer to the [RKE2 documentation](https://docs.rke2.io/cluster_access) or the [official Kubernetes documentation](https://kubernetes.io/docs/concepts/configuration/organize-cluster-access-kubeconfig/) about organizing cluster access using `kubeconfig` files. + +### 4. Check the Health of Your Cluster Pods + +Now that you have set up the `kubeconfig` file, you can use `kubectl` to access the cluster from your local machine. + +Check that all the required pods and containers are healthy are ready to continue: + +``` +/var/lib/rancher/rke2/bin/kubectl --kubeconfig /etc/rancher/rke2/rke2.yaml get pods -A +NAMESPACE NAME READY STATUS RESTARTS AGE +kube-system cloud-controller-manager-rke2-server-1 1/1 Running 0 2m28s +kube-system cloud-controller-manager-rke2-server-2 1/1 Running 0 61s +kube-system cloud-controller-manager-rke2-server-3 1/1 Running 0 49s +kube-system etcd-rke2-server-1 1/1 Running 0 2m13s +kube-system etcd-rke2-server-2 1/1 Running 0 87s +kube-system etcd-rke2-server-3 1/1 Running 0 56s +kube-system helm-install-rke2-canal-hs6sx 0/1 Completed 0 2m17s +kube-system helm-install-rke2-coredns-xmzm8 0/1 Completed 0 2m17s +kube-system helm-install-rke2-ingress-nginx-flwnl 0/1 Completed 0 2m17s +kube-system helm-install-rke2-metrics-server-7sggn 0/1 Completed 0 2m17s +kube-system kube-apiserver-rke2-server-1 1/1 Running 0 116s +kube-system kube-apiserver-rke2-server-2 1/1 Running 0 66s +kube-system kube-apiserver-rke2-server-3 1/1 Running 0 48s +kube-system kube-controller-manager-rke2-server-1 1/1 Running 0 2m30s +kube-system kube-controller-manager-rke2-server-2 1/1 Running 0 57s +kube-system kube-controller-manager-rke2-server-3 1/1 Running 0 42s +kube-system kube-proxy-rke2-server-1 1/1 Running 0 2m25s +kube-system kube-proxy-rke2-server-2 1/1 Running 0 59s +kube-system kube-proxy-rke2-server-3 1/1 Running 0 85s +kube-system kube-scheduler-rke2-server-1 1/1 Running 0 2m30s +kube-system kube-scheduler-rke2-server-2 1/1 Running 0 57s +kube-system kube-scheduler-rke2-server-3 1/1 Running 0 42s +kube-system rke2-canal-b9lvm 2/2 Running 0 91s +kube-system rke2-canal-khwp2 2/2 Running 0 2m5s +kube-system rke2-canal-swfmq 2/2 Running 0 105s +kube-system rke2-coredns-rke2-coredns-547d5499cb-6tvwb 1/1 Running 0 92s +kube-system rke2-coredns-rke2-coredns-547d5499cb-rdttj 1/1 Running 0 2m8s +kube-system rke2-coredns-rke2-coredns-autoscaler-65c9bb465d-85sq5 1/1 Running 0 2m8s +kube-system rke2-ingress-nginx-controller-69qxc 1/1 Running 0 52s +kube-system rke2-ingress-nginx-controller-7hprp 1/1 Running 0 52s +kube-system rke2-ingress-nginx-controller-x658h 1/1 Running 0 52s +kube-system rke2-metrics-server-6564db4569-vdfkn 1/1 Running 0 66s +``` + +**Result:** You have confirmed that you can access the cluster with `kubectl` and the RKE2 cluster is running successfully. Now the Rancher management server can be installed on the cluster. diff --git a/versioned_docs/version-2.14/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/checklist-for-production-ready-clusters/checklist-for-production-ready-clusters.md b/versioned_docs/version-2.14/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/checklist-for-production-ready-clusters/checklist-for-production-ready-clusters.md new file mode 100644 index 00000000000..374e402d4b4 --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/checklist-for-production-ready-clusters/checklist-for-production-ready-clusters.md @@ -0,0 +1,53 @@ +--- +title: Checklist for Production-Ready Clusters +--- + + + + + +In this section, we recommend best practices for creating the production-ready Kubernetes clusters that will run your apps and services. + +For a list of requirements for your cluster, including the requirements for OS/Docker, hardware, and networking, refer to the section on [node requirements.](../node-requirements-for-rancher-managed-clusters.md) + +This is a shortlist of best practices that we strongly recommend for all production clusters. + +For a full list of all the best practices that we recommend, refer to the [best practices section.](../../../../reference-guides/best-practices/best-practices.md) + +### Node Requirements + +* Make sure your nodes fulfill all of the [node requirements,](../node-requirements-for-rancher-managed-clusters.md) including the port requirements. + +### Back up etcd + +* Enable etcd snapshots. Verify that snapshots are being created, and run a disaster recovery scenario to verify the snapshots are valid. etcd is the location where the state of your cluster is stored, and losing etcd data means losing your cluster. Make sure you configure recurring snapshots of etcd for your cluster(s), and make sure the snapshots are stored externally (off the node) as well. + +### Cluster Architecture + +* Nodes should have one of the following role configurations: + * `etcd` + * `controlplane` + * `etcd` and `controlplane` + * `worker` (the `worker` role should not be used or added on nodes with the `etcd` or `controlplane` role) +* Have at least three nodes with the role `etcd` to survive losing one node. Increase this count for higher node fault toleration, and spread them across (availability) zones to provide even better fault tolerance. +* Assign two or more nodes the `controlplane` role for master component high availability. +* Assign two or more nodes the `worker` role for workload rescheduling upon node failure. + +For more information on what each role is used for, refer to the [section on roles for nodes in Kubernetes.](roles-for-nodes-in-kubernetes.md) + +For more information about the +number of nodes for each Kubernetes role, refer to the section on [recommended architecture.](../../../../reference-guides/rancher-manager-architecture/architecture-recommendations.md) + +### Logging and Monitoring + +* Configure alerts/notifiers for Kubernetes components (System Service). +* Configure logging for cluster analysis and post-mortems. + +### Reliability + +* Perform load tests on your cluster to verify that its hardware can support your workloads. + +### Networking + +* Minimize network latency. Rancher recommends minimizing latency between the etcd nodes. The default setting for `heartbeat-interval` is `500`, and the default setting for `election-timeout` is `5000`. These [settings for etcd tuning](https://etcd.io/docs/v3.5/tuning/) allow etcd to run in most networks (except really high latency networks). +* Cluster nodes should be located within a single region. Most cloud providers provide multiple availability zones within a region, which can be used to create higher availability for your cluster. Using multiple availability zones is fine for nodes with any role. If you are using [Kubernetes Cloud Provider](../set-up-cloud-providers/set-up-cloud-providers.md) resources, consult the documentation for any restrictions (i.e. zone storage restrictions). diff --git a/versioned_docs/version-2.14/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/checklist-for-production-ready-clusters/recommended-cluster-architecture.md b/versioned_docs/version-2.14/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/checklist-for-production-ready-clusters/recommended-cluster-architecture.md new file mode 100644 index 00000000000..8d4f7932f4c --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/checklist-for-production-ready-clusters/recommended-cluster-architecture.md @@ -0,0 +1,77 @@ +--- +title: Recommended Cluster Architecture +--- + + + + + +There are three roles that can be assigned to nodes: `etcd`, `controlplane` and `worker`. + +## Separating Worker Nodes from Nodes with Other Roles + +When designing your cluster(s), you have two options: + +* Use dedicated nodes for each role. This ensures resource availability for the components needed for the specified role. It also strictly isolates network traffic between each of the roles according to the [port requirements](../node-requirements-for-rancher-managed-clusters.md#networking-requirements). +* Assign the `etcd` and `controlplane` roles to the same nodes. These nodes must meet the hardware requirements for both roles. + +In either case, the `worker` role should not be used or added to nodes with the `etcd` or `controlplane` role. + +Therefore, each node should have one of the following role configurations: + + * `etcd` + * `controlplane` + * Both `etcd` and `controlplane` + * `worker` + +## Recommended Number of Nodes with Each Role + +The cluster should have: + +- At least three nodes with the role `etcd` to survive losing one node. Increase this count for higher node fault toleration, and spread them across (availability) zones to provide even better fault tolerance. +- At least two nodes with the role `controlplane` for master component high availability. +- At least two nodes with the role `worker` for workload rescheduling upon node failure. + +For more information on what each role is used for, refer to the [section on roles for nodes in Kubernetes.](roles-for-nodes-in-kubernetes.md) + + +### Number of Controlplane Nodes + +Adding more than one node with the `controlplane` role makes every master component highly available. + +### Number of etcd Nodes + +The number of nodes that you can lose at once while maintaining cluster availability is determined by the number of nodes assigned the `etcd` role. For a cluster with n members, the minimum is (n/2)+1. Therefore, we recommend creating an `etcd` node in 3 different availability zones within a region to survive the loss of one availability zone. If you use only two zones, you can only survive the loss of the zone where you don't lose the majority of nodes. + +| Nodes with `etcd` role | Majority | Failure Tolerance | +|--------------|------------|-------------------| +| 1 | 1 | 0 | +| 2 | 2 | 0 | +| 3 | 2 | **1** | +| 4 | 3 | 1 | +| 5 | 3 | **2** | +| 6 | 4 | 2 | +| 7 | 4 | **3** | +| 8 | 5 | 3 | +| 9 | 5 | **4** | + +References: + +* [Official etcd documentation on optimal etcd cluster size](https://etcd.io/docs/v3.5/faq/#what-is-failure-tolerance) +* [Official Kubernetes documentation on operating etcd clusters for Kubernetes](https://kubernetes.io/docs/tasks/administer-cluster/configure-upgrade-etcd/) + +### Number of Worker Nodes + +Adding more than one node with the `worker` role will make sure your workloads can be rescheduled if a node fails. + +### Why Production Requirements are Different for the Rancher Cluster and the Clusters Running Your Applications + +You may have noticed that our [Kubernetes Install](../../../../getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/install-upgrade-on-a-kubernetes-cluster.md) instructions do not meet our definition of a production-ready cluster, as there are no dedicated nodes for the `worker` role. However, for your Rancher installation, this three node cluster is valid, because: + +* It allows one `etcd` node failure. +* It maintains multiple instances of the master components by having multiple `controlplane` nodes. +* No other workloads than Rancher itself should be created on this cluster. + +## References + +* [Kubernetes: Master Components](https://kubernetes.io/docs/concepts/overview/components/#master-components) diff --git a/versioned_docs/version-2.14/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/checklist-for-production-ready-clusters/roles-for-nodes-in-kubernetes.md b/versioned_docs/version-2.14/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/checklist-for-production-ready-clusters/roles-for-nodes-in-kubernetes.md new file mode 100644 index 00000000000..1c627844659 --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/checklist-for-production-ready-clusters/roles-for-nodes-in-kubernetes.md @@ -0,0 +1,54 @@ +--- +title: Roles for Nodes in Kubernetes +--- + + + + + +This section describes the roles for etcd nodes, controlplane nodes, and worker nodes in Kubernetes, and how the roles work together in a cluster. + +This diagram is applicable to Kubernetes clusters [launched with Rancher using RKE.](../../launch-kubernetes-with-rancher/launch-kubernetes-with-rancher.md). + +![Cluster diagram](/img/clusterdiagram.svg)
+Lines show the traffic flow between components. Colors are used purely for visual aid + +## etcd + +Nodes with the `etcd` role run etcd, which is a consistent and highly available key value store used as Kubernetes’ backing store for all cluster data. etcd replicates the data to each node. + +:::note + +Nodes with the `etcd` role are shown as `Unschedulable` in the UI, meaning no pods will be scheduled to these nodes by default. + +::: + +## controlplane + +Nodes with the `controlplane` role run the Kubernetes master components (excluding `etcd`, as it's a separate role). See [Kubernetes: Master Components](https://kubernetes.io/docs/concepts/overview/components/#master-components) for a detailed list of components. + +:::note + +Nodes with the `controlplane` role are shown as `Unschedulable` in the UI, meaning no pods will be scheduled to these nodes by default. + +::: + +### kube-apiserver + +The Kubernetes API server (`kube-apiserver`) scales horizontally. Each node with the role `controlplane` will be added to the NGINX proxy on the nodes with components that need to access the Kubernetes API server. This means that if a node becomes unreachable, the local NGINX proxy on the node will forward the request to another Kubernetes API server in the list. + +### kube-controller-manager + +The Kubernetes controller manager uses leader election using an endpoint in Kubernetes. One instance of the `kube-controller-manager` will create an entry in the Kubernetes endpoints and updates that entry in a configured interval. Other instances will see an active leader and wait for that entry to expire (for example, when a node is unresponsive). + +### kube-scheduler + +The Kubernetes scheduler uses leader election using an endpoint in Kubernetes. One instance of the `kube-scheduler` will create an entry in the Kubernetes endpoints and updates that entry in a configured interval. Other instances will see an active leader and wait for that entry to expire (for example, when a node is unresponsive). + +## worker + +Nodes with the `worker` role run the Kubernetes node components. See [Kubernetes: Node Components](https://kubernetes.io/docs/concepts/overview/components/#node-components) for a detailed list of components. + +## References + +* [Kubernetes: Node Components](https://kubernetes.io/docs/concepts/overview/components/#node-components) \ No newline at end of file diff --git a/versioned_docs/version-2.14/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/kubernetes-clusters-in-rancher-setup.md b/versioned_docs/version-2.14/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/kubernetes-clusters-in-rancher-setup.md new file mode 100644 index 00000000000..4f6c5a33ea0 --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/kubernetes-clusters-in-rancher-setup.md @@ -0,0 +1,80 @@ +--- +title: Kubernetes Clusters in Rancher Setup +description: Provisioning Kubernetes Clusters +--- + + + + + +Rancher simplifies the creation of clusters by allowing you to create them through the Rancher UI rather than more complex alternatives. Rancher provides multiple options for launching a cluster. Use the option that best fits your use case. + +This section assumes a basic familiarity with Docker and Kubernetes. For a brief explanation of how Kubernetes components work together, refer to the [concepts](../../../reference-guides/kubernetes-concepts.md) page. + +For a conceptual overview of how the Rancher server provisions clusters and what tools it uses to provision them, refer to the [architecture](../../../reference-guides/rancher-manager-architecture/rancher-manager-architecture.md) page. + + + +### Cluster Management Capabilities by Cluster Type + +The following table summarizes the options and settings available for each cluster type: + +import ClusterCapabilitiesTable from '../../../shared-files/_cluster-capabilities-table.md'; + + + +## Setting up Clusters in a Hosted Kubernetes Provider + +In this scenario, Rancher does not provision Kubernetes because it is installed by providers such as Google Kubernetes Engine (GKE), Amazon Elastic Container Service for Kubernetes, or Azure Kubernetes Service. + +If you use a Kubernetes provider such as Google GKE, Rancher integrates with its cloud APIs, allowing you to create and manage role-based access control for the hosted cluster from the Rancher UI. + +For more information, refer to the section on [hosted Kubernetes clusters.](set-up-clusters-from-hosted-kubernetes-providers/set-up-clusters-from-hosted-kubernetes-providers.md) + +## Launching Kubernetes with Rancher + +Rancher uses the [Rancher Kubernetes Engine (RKE)](https://rancher.com/docs/rke/latest/en/) as a library when provisioning Kubernetes on your own nodes. RKE is Rancher’s own lightweight Kubernetes installer. + +In RKE clusters, Rancher manages the deployment of Kubernetes. These clusters can be deployed on any bare metal server, cloud provider, or virtualization platform. + +These nodes can be dynamically provisioned through Rancher's UI, which calls [Docker Machine](https://github.com/docker/docs/blob/vnext-engine/machine/overview.md) to launch nodes on various cloud providers. + +If you already have a node that you want to add to an RKE cluster, you can add it to the cluster by running a Rancher agent container on it. + +For more information, refer to the section on [RKE clusters.](../launch-kubernetes-with-rancher/launch-kubernetes-with-rancher.md) + +### Launching Kubernetes and Provisioning Nodes in an Infrastructure Provider + +Rancher can dynamically provision nodes in infrastructure providers such as Amazon EC2, DigitalOcean, Azure, or vSphere, then install Kubernetes on them. + +Using Rancher, you can create pools of nodes based on a [node template](../launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/use-new-nodes-in-an-infra-provider.md#node-templates). This template defines the parameters used to launch nodes in your cloud providers. + +One benefit of using nodes hosted by an infrastructure provider is that if a node loses connectivity with the cluster, Rancher can automatically replace it, thus maintaining the expected cluster configuration. + +The cloud providers available for creating a node template are decided based on the [node drivers](../launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/use-new-nodes-in-an-infra-provider.md#node-drivers) active in the Rancher UI. + +For more information, refer to the section on [nodes hosted by an infrastructure provider](../launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/use-new-nodes-in-an-infra-provider.md) + +### Launching Kubernetes on Existing Custom Nodes + +When setting up this type of cluster, Rancher installs Kubernetes on existing [custom nodes,](../../../reference-guides/cluster-configuration/rancher-server-configuration/use-existing-nodes/use-existing-nodes.md) which creates a custom cluster. + +You can bring any nodes you want to Rancher and use them to create a cluster. + +These nodes include on-prem bare metal servers, cloud-hosted virtual machines, or on-prem virtual machines. + +## Registering Existing Clusters + +The cluster registration feature replaces the feature to import clusters. + +Registering EKS clusters now provides additional benefits. For the most part, registered EKS clusters and EKS clusters created in Rancher are treated the same way in the Rancher UI, except for deletion. + +When you delete an EKS cluster that was created in Rancher, the cluster is destroyed. When you delete an EKS cluster that was registered in Rancher, it is disconnected from the Rancher server, but it still exists and you can still access it in the same way you did before it was registered in Rancher. + +For more information, see [this page.](register-existing-clusters.md) + +## Programmatically Creating Clusters + +The most common way to programmatically deploy Kubernetes clusters through Rancher is by using the Rancher2 Terraform provider. The documentation for creating clusters with Terraform is [here.](https://registry.terraform.io/providers/rancher/rancher2/latest/docs/resources/cluster) + +EKS, GKE, AKS clusters and RKE clusters can be created or imported with Terraform. diff --git a/versioned_docs/version-2.14/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/migrate-to-an-out-of-tree-cloud-provider/migrate-to-out-of-tree-amazon.md b/versioned_docs/version-2.14/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/migrate-to-an-out-of-tree-cloud-provider/migrate-to-out-of-tree-amazon.md new file mode 100644 index 00000000000..0ce4e450f6b --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/migrate-to-an-out-of-tree-cloud-provider/migrate-to-out-of-tree-amazon.md @@ -0,0 +1,194 @@ +--- +title: Migrating Amazon In-tree to Out-of-tree +--- + + + + + +Kubernetes is moving away from maintaining cloud providers in-tree. In Kubernetes v1.27 and later, the in-tree cloud providers have been removed. The Rancher UI allows you to upgrade to Kubernetes v1.27 when you migrate from an in-tree to out-of-tree provider. + +However, if you're performing a manual migration, existing clusters must upgrade to Kubernetes v1.27 after you migrate in order to remain functional. + +To migrate from the in-tree cloud provider to the out-of-tree AWS cloud provider, you must stop the existing cluster's kube controller manager and install the AWS cloud controller manager. There are many ways to do this. Refer to the official AWS documentation on the [external cloud controller manager](https://cloud-provider-aws.sigs.k8s.io/getting_started/) for details. + +If it's acceptable to have some downtime during migration, follow the instructions to [set up an external cloud provider](../set-up-cloud-providers/amazon.md#using-the-out-of-tree-aws-cloud-provider). These instructions outline how to configure the out-of-tree cloud provider for a newly provisioned cluster. During set up, there will be some downtime, as there is a time gap between when the old cloud provider stops running and when the new cloud provider starts to run. + +If your setup can't tolerate any control plane downtime, you must enable leader migration. This facilitates a smooth transition from the controllers in the kube controller manager to their counterparts in the cloud controller manager. Refer to the official AWS documentation on [Using leader migration](https://cloud-provider-aws.sigs.k8s.io/getting_started/) for more details. + +:::note Important: +The Kubernetes [cloud controller migration documentation](https://kubernetes.io/docs/tasks/administer-cluster/controller-manager-leader-migration/#before-you-begin) states that it's possible to migrate with the same Kubernetes version, but assumes that the migration is part of a Kubernetes upgrade. Refer to the Kubernetes documentation on [migrating to use the cloud controller manager](https://kubernetes.io/docs/tasks/administer-cluster/controller-manager-leader-migration/) to see if you need to customize your setup before migrating. Confirm your [migration configuration values](https://kubernetes.io/docs/tasks/administer-cluster/controller-manager-leader-migration/#default-configuration). If your cloud provider provides an implementation of the Node IPAM controller, you also need to [migrate the IPAM controller](https://kubernetes.io/docs/tasks/administer-cluster/controller-manager-leader-migration/#node-ipam-controller-migration). +::: + + + + +1. Update the cluster config to enable leader migration: + +```yaml +spec: + rkeConfig: + machineSelectorConfig: + - config: + kube-controller-manager-arg: + - enable-leader-migration + machineLabelSelector: + matchExpressions: + - key: rke.cattle.io/control-plane-role + operator: In + values: + - 'true' +``` + +Note that the cloud provider is still `aws` at this step: + +```yaml +spec: + rkeConfig: + machineGlobalConfig: + cloud-provider-name: aws +``` + +2. Cordon control plane nodes so that AWS cloud controller pods run on nodes only after upgrading to the external cloud provider: + +```shell +kubectl cordon -l "node-role.kubernetes.io/control-plane=true" +``` + +3. To install the AWS cloud controller manager with leader migration enabled, follow Steps 1-3 for [deploying the cloud controller manager chart](../set-up-cloud-providers/amazon.md#using-the-out-of-tree-aws-cloud-provider). From Kubernetes 1.22 onwards, the kube-controller-manager will utilize a default configuration which will satisfy the controller-to-manager migration. Update container args of the `aws-cloud-controller-manager` under `spec.rkeConfig.additionalManifest` to enable leader migration: + +```shell +- '--enable-leader-migration=true' +``` + +4. Install the chart and confirm that the Daemonset `aws-cloud-controller-manager` successfully deployed: + +```shell +kubectl rollout status daemonset -n kube-system aws-cloud-controller-manager +``` + +5. Update the provisioning cluster to change the cloud provider and remove leader migration args from the kube controller. +If upgrading the Kubernetes version, set the Kubernetes version as well in the `spec.kubernetesVersion` section of the cluster YAML file + +:::note Important + +Only remove `cloud-provider-name: aws` if not relying on the rke2 supervisor to correctly set the providerID. + +::: + +Remove `enable-leader-migration` if you don't want it enabled in your cluster: + +```yaml +spec: + rkeConfig: + machineGlobalConfig: + cloud-provider-name: external +``` + +Remove `enable-leader-migration` from: + +```yaml +spec: + rkeConfig: + machineSelectorConfig: + - config: + kube-controller-manager-arg: + - enable-leader-migration + machineLabelSelector: + matchExpressions: + - key: rke.cattle.io/control-plane-role + operator: In + values: + - 'true' +``` + +:::tip +You can also disable leader migration after the upgrade, as leader migration is no longer required due to only one cloud-controller-manager and can be removed. +Upgrade the chart and remove the following section from the container arguments: + +```yaml +- --enable-leader-migration=true +``` +::: + +Verify the cloud controller manager update was successfully rolled out with the following command: + +```shell +kubectl rollout status daemonset -n kube-system aws-cloud-controller-manager +``` + +6. The cloud provider is responsible for setting the ProviderID of the node. Check if all nodes are initialized with the ProviderID: + +```shell +kubectl describe nodes | grep "ProviderID" +``` + + + + + +1. Update the cluster config to enable leader migration in `cluster.yml`: + +```yaml +services: + kube-controller: + extra_args: + enable-leader-migration: "true" +``` + +Note that the cloud provider is still `aws` at this step: + +```yaml +cloud_provider: + name: aws +``` + +2. Cordon the control plane nodes, so that AWS cloud controller pods run on nodes only after upgrading to the external cloud provider: + +```shell +kubectl cordon -l "node-role.kubernetes.io/controlplane=true" +``` + +3. To install the AWS cloud controller manager, you must enable leader migration and follow the same steps as when installing AWS on a new cluster. To enable leader migration, add the following to the container arguments in step 7 while following the [steps to install the chart](../set-up-cloud-providers/amazon.md#helm-chart-installation-from-ui): + +```yaml +- '--enable-leader-migration=true' +``` + +4. Confirm that the chart is installed but that the new pods aren't running yet due to cordoned controlplane nodes. After updating the cluster in the next step, RKE will upgrade and uncordon each node, and schedule `aws-controller-manager` pods. + +5. Update `cluster.yml` to change the cloud provider and remove the leader migration arguments from the kube-controller. + + Selecting **External Amazon (out-of-tree)** sets `--cloud-provider=external` and lets you enable `useInstanceMetadataHostname`. You must enable `useInstanceMetadataHostname` for node-driver clusters and for custom clusters if not you don't provide a custom node name via `--node-name`. Enabling `useInstanceMetadataHostname` will query ec2 metadata service and set `/hostname` as `hostname-override` for `kubelet` and `kube-proxy`: + +```yaml +rancher_kubernetes_engine_config: + cloud_provider: + name: external-aws + useInstanceMetadataHostname: true/false +``` + + Remove `enable-leader-migration` if you don't want it enabled in your cluster: + + ```yaml + services: + kube-controller: + extra_args: + enable-leader-migration: "true" + ``` + +:::tip +You can also disable leader migration after you finish the migration. Upgrade the chart and remove the following section from the container arguments: + +```yaml +- --enable-leader-migration=true +``` +::: + +6. If you're upgrading the cluster's Kubernetes version, set the Kubernetes version as well. + +7. Update the cluster. The `aws-cloud-controller-manager` pods should now be running. + + + + diff --git a/versioned_docs/version-2.14/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/migrate-to-an-out-of-tree-cloud-provider/migrate-to-out-of-tree-azure.md b/versioned_docs/version-2.14/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/migrate-to-an-out-of-tree-cloud-provider/migrate-to-out-of-tree-azure.md new file mode 100644 index 00000000000..9f77591a582 --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/migrate-to-an-out-of-tree-cloud-provider/migrate-to-out-of-tree-azure.md @@ -0,0 +1,211 @@ +--- +title: Migrating Azure In-tree to Out-of-tree +--- + + + + + +Kubernetes is moving away from maintaining cloud providers in-tree. + +Starting with Kubernetes 1.29, in-tree cloud providers have been disabled. You must disable `DisableCloudProviders` and `DisableKubeletCloudCredentialProvider` to use the in-tree Azure cloud provider or migrate from in-tree cloud provider to out-of-tree provider. You can disable the required feature gates by setting `feature-gates=DisableCloudProviders=false` as an additional argument for the cluster's Kubelet, Controller Manager, and API Server in the advanced cluster configuration. Additionally, set `DisableKubeletCloudCredentialProvider=false` in the Kubelet's arguments to enable in-tree functionality for authenticating to Azure container registries for image pull credentials. See [upstream docs](https://github.com/kubernetes/kubernetes/pull/117503) for more details. + +In Kubernetes v1.30 and later, the in-tree cloud providers have been removed. Rancher allows you to upgrade to Kubernetes v1.30 when you migrate from an in-tree to out-of-tree provider. + +To migrate from the in-tree cloud provider to the out-of-tree Azure cloud provider, you must stop the existing cluster's kube controller manager and install the Azure cloud controller manager. + +If it's acceptable to have some downtime during migration, follow the instructions to [set up an external cloud provider](../set-up-cloud-providers/azure.md#using-the-out-of-tree-azure-cloud-provider). These instructions outline how to configure the out-of-tree cloud provider for a newly provisioned cluster. During set up, there will be some downtime, as there is a time gap between when the old cloud provider stops running and when the new cloud provider starts to run. + +If your setup can't tolerate any control plane downtime, you must enable leader migration. This facilitates a smooth transition from the controllers in the kube controller manager to their counterparts in the cloud controller manager. + +:::note Important: +The Kubernetes [cloud controller migration documentation](https://kubernetes.io/docs/tasks/administer-cluster/controller-manager-leader-migration/#before-you-begin) states that it's possible to migrate with the same Kubernetes version, but assumes that the migration is part of a Kubernetes upgrade. Refer to the Kubernetes documentation on [migrating to use the cloud controller manager](https://kubernetes.io/docs/tasks/administer-cluster/controller-manager-leader-migration/) to see if you need to customize your setup before migrating. Confirm your [migration configuration values](https://kubernetes.io/docs/tasks/administer-cluster/controller-manager-leader-migration/#default-configuration). If your cloud provider provides an implementation of the Node IPAM controller, you also need to [migrate the IPAM controller](https://kubernetes.io/docs/tasks/administer-cluster/controller-manager-leader-migration/#node-ipam-controller-migration). + +Starting with Kubernetes v1.26, in-tree persistent volume types `kubernetes.io/azure-disk` and `kubernetes.io/azure-file` are deprecated and no longer supported. There are no plans to remove these drivers following their deprecation, however you should migrate to the corresponding CSI drivers, `disk.csi.azure.com` and `file.csi.azure.com`. To review the migration options for your storage classes and upgrade your cluster to use Azure Disks and Azure Files CSI drivers, see [Migrate from in-tree to CSI drivers](https://learn.microsoft.com/en-us/azure/aks/csi-migrate-in-tree-volumes). +::: + + + + +1. Update the cluster config to enable leader migration: + +```yaml +spec: + rkeConfig: + machineSelectorConfig: + - config: + kube-controller-manager-arg: + - enable-leader-migration + machineLabelSelector: + matchExpressions: + - key: rke.cattle.io/control-plane-role + operator: In + values: + - 'true' +``` + +Note that the cloud provider is still `azure` at this step: + +```yaml +spec: + rkeConfig: + machineGlobalConfig: + cloud-provider-name: azure +``` + +2. Cordon control plane nodes so that Azure cloud controller pods run on nodes only after upgrading to the external cloud provider: + +```shell +kubectl cordon -l "node-role.kubernetes.io/control-plane=true" +``` + +3. To deploy the Azure cloud controller manager, use any of the available options: +- UI: Follow steps 1-10 of [Helm chart installation from UI](../set-up-cloud-providers/azure.md#helm-chart-installation-from-ui) to install the cloud controller manager chart. +- CLI: Follow steps 1-4 of [Helm chart installation from CLI](../set-up-cloud-providers/azure.md#helm-chart-installation-from-cli). +- Update the cluster's additional manifest: Follow steps 2-3 to [install the cloud controller manager chart](../set-up-cloud-providers/azure.md#using-the-out-of-tree-azure-cloud-provider). + +Confirm that the chart is installed but that the new pods aren't running yet due to cordoned controlplane nodes. + +4. To enable leader migration, add `--enable-leader-migration` to the container arguments of `cloud-controller-manager`: + +```shell +kubectl -n kube-system patch deployment cloud-controller-manager \ +--type=json \ +-p='[{"op": "add", "path": "/spec/template/spec/containers/0/args/-", "value": "--enable-leader-migration"}]' +``` + +5. Update the provisioning cluster to change the cloud provider and remove leader migration args from the kube controller manager. + If upgrading the Kubernetes version, set the Kubernetes version as well in the `spec.kubernetesVersion` section of the cluster YAML file. + +```yaml +spec: + rkeConfig: + machineGlobalConfig: + cloud-provider-name: external +``` + +Remove `enable-leader-migration` from the kube controller manager: + +```yaml +spec: + rkeConfig: + machineSelectorConfig: + - config: + kube-controller-manager-arg: + - enable-leader-migration + machineLabelSelector: + matchExpressions: + - key: rke.cattle.io/control-plane-role + operator: In + values: + - 'true' +``` + +6. Uncordon control plane nodes so that Azure cloud controller pods now run on nodes: + +```shell +kubectl uncordon -l "node-role.kubernetes.io/control-plane=true" +``` + +7. Update the cluster. The `cloud-controller-manager` pods should now be running. + +```shell +kubectl rollout status deployment -n kube-system cloud-controller-manager +kubectl rollout status daemonset -n kube-system cloud-node-manager +``` + +8. The cloud provider is responsible for setting the ProviderID of the node. Check if all nodes are initialized with the ProviderID: + +```shell +kubectl describe nodes | grep "ProviderID" +``` + +9. (Optional) You can also disable leader migration after the upgrade, as leader migration is not required with only one cloud-controller-manager. + Update the `cloud-controller-manager` deployment to remove leader migration from the container arguments: + +```yaml +- --enable-leader-migration=true +``` + + + + + +1. Update the cluster config to enable leader migration in `cluster.yml`: + +```yaml +services: + kube-controller: + extra_args: + enable-leader-migration: "true" +``` + +Note that the cloud provider is still `azure` at this step: + +```yaml +cloud_provider: + name: azure +``` + +2. Cordon the control plane nodes, so that Azure cloud controller pods run on nodes only after upgrading to the external cloud provider: + +```shell +kubectl cordon -l "node-role.kubernetes.io/controlplane=true" +``` + +3. To install the Azure cloud controller manager, follow the same steps as when installing Azure cloud provider on a new cluster: +- UI: Follow steps 1-10 of [Helm chart installation from UI](../set-up-cloud-providers/azure.md#helm-chart-installation-from-ui) to install the cloud controller manager chart. +- CLI: Follow steps 1-4 of [Helm chart installation from CLI](../set-up-cloud-providers/azure.md#helm-chart-installation-from-cli) to install the cloud controller manager chart. + +4. Confirm that the chart is installed but that the new pods aren't running yet due to cordoned controlplane nodes. After updating the cluster in the next step, RKE will upgrade and uncordon each node, and schedule `cloud-controller-manager` pods. + +5. To enable leader migration, add `--enable-leader-migration` to the container arguments of `cloud-controller-manager`: + +```shell +kubectl -n kube-system patch deployment cloud-controller-manager \ +--type=json \ +-p='[{"op": "add", "path": "/spec/template/spec/containers/0/args/-", "value": "--enable-leader-migration"}]' +``` + +6. Update `cluster.yml` to change the cloud provider to `external` and remove the leader migration arguments from the kube-controller. + +```yaml +rancher_kubernetes_engine_config: + cloud_provider: + name: external +``` + +Remove `enable-leader-migration` if you don't want it enabled in your cluster: + +```yaml +services: + kube-controller: + extra_args: + enable-leader-migration: "true" +``` + +7. If you're upgrading the cluster's Kubernetes version, set the Kubernetes version as well. + +8. Update the cluster. The `cloud-controller-manager` pods should now be running. + +```shell +kubectl rollout status deployment -n kube-system cloud-controller-manager +kubectl rollout status daemonset -n kube-system cloud-node-manager +``` + +9. The cloud provider is responsible for setting the ProviderID of the node. Verify that all nodes are initialized with the ProviderID: + +```shell +kubectl describe nodes | grep "ProviderID" +``` + +10. (Optional) You can also disable leader migration after the upgrade, as leader migration is not required with only one cloud-controller-manager. + Update the `cloud-controller-manager` deployment to remove leader migration from the container arguments: + +```yaml +- --enable-leader-migration=true +``` + + + + diff --git a/versioned_docs/version-2.14/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/migrate-to-an-out-of-tree-cloud-provider/migrate-to-out-of-tree-vsphere.md b/versioned_docs/version-2.14/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/migrate-to-an-out-of-tree-cloud-provider/migrate-to-out-of-tree-vsphere.md new file mode 100644 index 00000000000..df230919675 --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/migrate-to-an-out-of-tree-cloud-provider/migrate-to-out-of-tree-vsphere.md @@ -0,0 +1,112 @@ +--- +title: Migrating VMware vSphere In-tree to Out-of-tree +--- + + + + + +Kubernetes is moving away from maintaining cloud providers in-tree. VMware vSphere has an out-of-tree cloud provider that can be used by installing the vSphere cloud provider and cloud storage plugins. + +This page covers how to migrate from the in-tree vSphere cloud provider to out-of-tree, and manage the existing VMs post migration. + +It follows the steps provided in the official [vSphere migration documentation](https://vsphere-csi-driver.sigs.k8s.io/features/vsphere_csi_migration.html) and provides the steps to be performed in Rancher. + +### Cloud-config Format Limitation + +Existing volumes that were provisioned using the following cloud-config format won't get migrated due to an existing bug in vSphere Cloud Storage Interface (CSI). + +If the cloud-config has this format for datastore and resource pool path, vsphere CSI driver cannot recognize it: + +```yaml +default-datastore: /datastore/ +resourcepool-path: "/host//Resources/" +``` + +Volumes provisioned with the in-tree provider using the following format will get migrated correctly: + +```yaml +default-datastore: +resourcepool-path: "/Resources/" +``` + +Upstream bug: https://github.com/kubernetes-sigs/vsphere-csi-driver/issues/628 + +Rancher issue tracking this bug: https://github.com/rancher/rancher/issues/31105 + +## Prerequisites + +- vSphere CSI Migration requires vSphere 7.0u1. In order to be able to manage existing in-tree vSphere volumes, upgrade vSphere to 7.0u1. +- The Kubernetes version must be 1.19 or higher. + +## Migration + +### 1. Install the CPI plugin + +Before installing CPI, we need to taint all nodes with `node.cloudprovider.kubernetes.io/uninitialized=true:NoSchedule`. + +This can be done by running the following commands: + +``` +curl -O https://raw.githubusercontent.com/rancher/helm3-charts/56b622f519728378abeddfe95074f1b87ab73b1e/charts/vsphere-cpi/taints.sh +``` + +Or: + +``` +wget https://raw.githubusercontent.com/rancher/helm3-charts/56b622f519728378abeddfe95074f1b87ab73b1e/charts/vsphere-cpi/taints.sh +chmod +x taints.sh +./taints.sh +``` + +Once all nodes are tainted by the running the script, launch the Helm vSphere CPI chart. + +1. Click **☰ > Cluster Management**. +1. Go to the cluster where the vSphere CPI chart will be installed and click **Explore**. +1. Click **Apps > Charts**. +1. Click **vSphere CPI**. +1. Click **Install**. +1. Fill out the required vCenter details and click **Install**. + +vSphere CPI initializes all nodes with ProviderID, which is needed by the vSphere CSI driver. + +Check if all nodes are initialized with the ProviderID with the following command: + +``` +kubectl describe nodes | grep "ProviderID" +``` + +### 2. Install the CSI driver + +1. Click **☰ > Cluster Management**. +1. Go to the cluster where the vSphere CSI chart will be installed and click **Explore**. +1. Click **Apps > Charts**. +1. Click **vSphere CSI**. +1. Click **Install**. +1. Fill out the required vCenter details and click **Install**. +1. Check **Customize Helm options before install** and click **Next**. +1. On the **Features** tab, check **Enable CSI Migration**. +1. Optionally, go to the **Storage** tab and set up a datastore. This chart creates a StorageClass with the `csi.vsphere.vmware.com` as the provisioner. You can provide the URL of the datastore to be used for CSI volume provisioning while creating this StorageClass. The datastore URL can be found in the vSphere client by selecting the datastore and going to the Summary tab. Fill out the details for the StorageClass. +1. Click **Install**. + +### 3. Edit the cluster to enable CSI migration feature flags + +1. While editing the cluster, if the Kubernetes version is less than 1.19, select Kubernetes version 1.19 or higher from the **Kubernetes Version** dropdown. +2. For enabling feature flags, click on "Edit as YAML", and add the following under kube-controller and kubelet: + + ```yaml + extra_args: + feature-gates: "CSIMigration=true,CSIMigrationvSphere=true" + ``` + +### 4. Drain worker nodes + +Worker nodes must be drained during the upgrade before changing the kubelet and kube-controller-manager args. + + +1. Click **☰ > Cluster Management**. +1. Go to the cluster where you will drain worker nodes and click **⋮ > Edit Config**. +1. In the **Advanced Options** section, set the field **Maximum Worker Nodes Unavailable** to 1. +1. To drain the nodes during upgrade, select **Drain Nodes > Yes**. +1. Set **Force** and **Delete Local Data** to **true**. +1. Click **Save** to upgrade the cluster. diff --git a/versioned_docs/version-2.14/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/node-requirements-for-rancher-managed-clusters.md b/versioned_docs/version-2.14/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/node-requirements-for-rancher-managed-clusters.md new file mode 100644 index 00000000000..9438d0dc8db --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/node-requirements-for-rancher-managed-clusters.md @@ -0,0 +1,145 @@ +--- +title: Node Requirements for Rancher Managed Clusters +--- + + + + + +This page describes the requirements for the Rancher managed Kubernetes clusters where your apps and services will be installed. These downstream clusters should be separate from the three-node cluster running Rancher. + +:::note + +If Rancher is installed on a high-availability Kubernetes cluster, the Rancher server three-node cluster and downstream clusters have different requirements. For Rancher installation requirements, refer to the node requirements in the [installation section.](../../../getting-started/installation-and-upgrade/installation-requirements/installation-requirements.md) + +::: + +## Operating Systems and Container Runtime Requirements + +Rancher should work with any modern Linux distribution and any modern Docker version. Linux is required for the etcd and controlplane nodes of all downstream clusters. Worker nodes may run Linux or [Windows Server.](#windows-nodes) + +For details on which OS and Docker versions were tested with each Rancher version, refer to the [support maintenance terms.](https://rancher.com/support-maintenance-terms/) + +All supported operating systems are 64-bit x86. + +If you plan to use ARM64, see [Running on ARM64 (Experimental).](../../advanced-user-guides/enable-experimental-features/rancher-on-arm64.md) + +For information on how to install Docker, refer to the official [Docker documentation.](https://docs.docker.com/) + +### Oracle Linux and RHEL Derived Linux Nodes + +Some distributions of Linux derived from RHEL, including Oracle Linux, may have default firewall rules that block communication with Helm. We recommend disabling firewalld. For Kubernetes 1.19, firewalld must be turned off. + +:::note + +In RHEL 8.4, two extra services are included on the NetworkManager: `nm-cloud-setup.service` and `nm-cloud-setup.timer`. These services add a routing table that interferes with the CNI plugin's configuration. If these services are enabled, you must disable them using the command below, and then reboot the node to restore connectivity: + + ``` + systemctl disable nm-cloud-setup.service nm-cloud-setup.timer + reboot + ``` + +::: + +### SUSE Linux Nodes + +SUSE Linux may have a firewall that blocks all ports by default. In that situation, follow [these steps](../../../getting-started/installation-and-upgrade/installation-requirements/port-requirements.md#opening-suse-linux-ports) to open the ports needed for adding a host to a custom cluster. + +### Flatcar Container Linux Nodes + +When [Launching Kubernetes with Rancher](../launch-kubernetes-with-rancher/launch-kubernetes-with-rancher.md) using Flatcar Container Linux nodes, it is required to use the following configuration in the [Cluster Config File](../../../reference-guides/cluster-configuration/rancher-server-configuration/rke1-cluster-configuration.md#rke-cluster-config-file-reference) + + + + +```yaml +rancher_kubernetes_engine_config: + network: + plugin: canal + options: + canal_flex_volume_plugin_dir: /opt/kubernetes/kubelet-plugins/volume/exec/nodeagent~uds + flannel_backend_type: vxlan + + services: + kube-controller: + extra_args: + flex-volume-plugin-dir: /opt/kubernetes/kubelet-plugins/volume/exec/ +``` + + + + +```yaml +rancher_kubernetes_engine_config: + network: + plugin: calico + options: + calico_flex_volume_plugin_dir: /opt/kubernetes/kubelet-plugins/volume/exec/nodeagent~uds + flannel_backend_type: vxlan + + services: + kube-controller: + extra_args: + flex-volume-plugin-dir: /opt/kubernetes/kubelet-plugins/volume/exec/ +``` + + + + +It is also required to enable the Docker service, you can enable the Docker service using the following command: + +``` +systemctl enable docker.service +``` + +The Docker service is enabled automatically when using [Node Drivers](../authentication-permissions-and-global-configuration/about-provisioning-drivers/about-provisioning-drivers.md#node-drivers). + +### Windows Nodes + +Nodes with Windows Server must run Docker Enterprise Edition. + +Windows nodes can be used for worker nodes only. See [Configuring Custom Clusters for Windows](use-windows-clusters/use-windows-clusters.md) + +## Hardware Requirements + +The hardware requirements for nodes with the `worker` role mostly depend on your workloads. The minimum to run the Kubernetes node components is 1 CPU (core) and 1GB of memory. + +Regarding CPU and memory, it is recommended that the different planes of Kubernetes clusters (etcd, controlplane, and workers) should be hosted on different nodes so that they can scale separately from each other. + +For hardware recommendations for large Kubernetes clusters, refer to the official Kubernetes documentation on [building large clusters.](https://kubernetes.io/docs/setup/best-practices/cluster-large/) + +For hardware recommendations for etcd clusters in production, refer to the official [etcd documentation.](https://etcd.io/docs/v3.5/op-guide/hardware/) + +## Networking Requirements + +For a production cluster, we recommend that you restrict traffic by opening only the ports defined in the port requirements below. + +The ports required to be open are different depending on how the user cluster is launched. Each of the sections below list the ports that need to be opened for different [cluster creation options](kubernetes-clusters-in-rancher-setup.md). + +For a breakdown of the port requirements for etcd nodes, controlplane nodes, and worker nodes in a Kubernetes cluster, refer to the [port requirements for the Rancher Kubernetes Engine.](https://rancher.com/docs/rke/latest/en/os/#ports) + +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. + +::: + +## Optional: Security Considerations + +If you want to provision a Kubernetes cluster that is compliant with the CIS (Center for Internet Security) Kubernetes Benchmark, we recommend to following our hardening guide to configure your nodes before installing Kubernetes. + +For more information on the hardening guide and details on which version of the guide corresponds to your Rancher and Kubernetes versions, refer to the [security section.](../../../reference-guides/rancher-security/rancher-security.md#rancher-hardening-guide) diff --git a/versioned_docs/version-2.14/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/register-existing-clusters.md b/versioned_docs/version-2.14/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/register-existing-clusters.md new file mode 100644 index 00000000000..f8fdc984308 --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/register-existing-clusters.md @@ -0,0 +1,334 @@ +--- +title: Registering Existing Clusters +--- + + + + + +The cluster registration feature replaced the feature to import clusters. + +The control that Rancher has to manage a registered cluster depends on the type of cluster. For details, see [Management Capabilities for Registered Clusters.](#management-capabilities-for-registered-clusters) + + +## Prerequisites + +### Kubernetes Node Roles + +Registered RKE Kubernetes clusters must have all three node roles - etcd, controlplane and worker. A cluster with only controlplane components cannot be registered in Rancher. + +For more information on RKE node roles, see the [best practices.](checklist-for-production-ready-clusters/checklist-for-production-ready-clusters.md#cluster-architecture) + +### Permissions + +To register a cluster in Rancher, you must have `cluster-admin` privileges within that cluster. If you don't, grant these privileges to your user by running: + +```plain +kubectl create clusterrolebinding cluster-admin-binding \ + --clusterrole cluster-admin \ + --user [USER_ACCOUNT] +``` + +Since, by default, Google Kubernetes Engine (GKE) doesn't grant the `cluster-admin` role, you must run these commands on GKE clusters before you can register them. To learn more about role-based access control for GKE, please see [the official Google documentation](https://cloud.google.com/kubernetes-engine/docs/how-to/role-based-access-control). + +### Elastic Kubernetes Service (EKS), Azure Kubernetes Service (AKS), and Google Kubernetes Engine (GKE) + +To successfully import or provision EKS, AKS, and GKE clusters from Rancher, the cluster must have at least one managed node group. + +AKS clusters can only be imported if local accounts are enabled. If a cluster is configured to use Microsoft Entra ID for authentication, Rancher will not be able to import the cluster and report an error. + +EKS Anywhere clusters can be imported/registered into Rancher with an API address and credentials, as with any downstream cluster. EKS Anywhere clusters are treated as imported clusters and do not have full lifecycle support from Rancher. + +GKE Autopilot clusters aren't supported. See [Compare GKE Autopilot and Standard](https://cloud.google.com/kubernetes-engine/docs/resources/autopilot-standard-feature-comparison) for more information about the differences between GKE modes. + +## Registering a Cluster + +1. Click **☰ > Cluster Management**. +2. On the **Clusters** page, **Import Existing**. +3. Choose the type of cluster. +4. Use **Member Roles** to configure user authorization for the cluster. Click **Add Member** to add users that can access the cluster. Use the **Role** drop-down to set permissions for each user. +5. If you are importing a generic Kubernetes cluster in Rancher, perform the following steps for setup: + 1. Click **Agent Environment Variables** under **Cluster Options** to set environment variables for [rancher cluster agent](../launch-kubernetes-with-rancher/about-rancher-agents.md). The environment variables can be set using key value pairs. If rancher agent requires use of proxy to communicate with Rancher server, `HTTP_PROXY`, `HTTPS_PROXY` and `NO_PROXY` environment variables can be set using agent environment variables. + 1. Enable Project Network Isolation to ensure the cluster supports Kubernetes `NetworkPolicy` resources. Users can select the **Project Network Isolation** option under the **Advanced Options** dropdown to do so. + 1. [Configure the version management feature for imported RKE2 and K3s clusters](#configuring-version-management-for-rke2-and-k3s-clusters). +6. Click **Create**. +7. The prerequisite for `cluster-admin` privileges is shown (see **Prerequisites** above), including an example command to fulfil the prerequisite. +8. Copy the `kubectl` command to your clipboard and run it on a node where kubeconfig is configured to point to the cluster you want to import. If you are unsure it is configured correctly, run `kubectl get nodes` to verify before running the command shown in Rancher. +9. If you are using self-signed certificates, you will receive the message `certificate signed by unknown authority`. To work around this validation, copy the command starting with `curl` displayed in Rancher to your clipboard. Then run the command on a node where kubeconfig is configured to point to the cluster you want to import. +10. When you finish running the command(s) on your node, click **Done**. + +:::important + +The `NO_PROXY` environment variable is not standardized, and the accepted format of the value can differ between applications. When configuring the `NO_PROXY` variable in Rancher, the value must adhere to the format expected by Golang. + +Specifically, the value should be a comma-delimited string which only contains IP addresses, CIDR notation, domain names, or special DNS labels (e.g. `*`). For a full description of the expected value format, refer to the [**upstream Golang documentation**](https://pkg.go.dev/golang.org/x/net/http/httpproxy#Config) + +::: + +**Result:** + +- Your cluster is registered and assigned a state of **Pending**. Rancher is deploying resources to manage your cluster. +- You can access your cluster after its state is updated to **Active**. +- **Active** clusters are assigned two Projects: `Default` (containing the namespace `default`) and `System` (containing the namespaces `cattle-system`, `ingress-nginx`, `kube-public` and `kube-system`, if present). + + +:::note + +You can not re-register a cluster that is currently active in a Rancher setup. + +::: + +### Configuring an Imported EKS, AKS or GKE Cluster with Terraform + +You should define **only** the minimum fields that Rancher requires when importing an EKS, AKS or GKE cluster with Terraform. This is important as Rancher will overwrite what was in the cluster configuration with any config that the user has provided. + +:::caution + +Even a small difference between the current cluster and a user-provided config could have unexpected results. + +::: + +The minimum config fields required by Rancher to import EKS clusters with Terraform using `eks_config_v2` are as follows: + +- cloud_credential_id +- name +- region +- imported (this field should always be set to `true` for imported clusters) + +Example YAML configuration for imported EKS clusters: + +``` +resource "rancher2_cluster" "my-eks-to-import" { + name = "my-eks-to-import" + description = "Terraform EKS Cluster" + eks_config_v2 { + cloud_credential_id = rancher2_cloud_credential.aws.id + name = var.aws_eks_name + region = var.aws_region + imported = true + } +} +``` + +You can find additional examples for other cloud providers in the [Rancher2 Terraform Provider documentation](https://registry.terraform.io/providers/rancher/rancher2/latest/docs/resources/cluster). + +## Management Capabilities for Registered Clusters + +The control that Rancher has to manage a registered cluster depends on the type of cluster. + +- [Features for All Registered Clusters](#features-for-all-registered-clusters) +- [Additional Features for Registered RKE2 and K3s Clusters](#additional-features-for-registered-rke2-and-k3s-clusters) +- [Additional Features for Registered EKS, AKS and GKE Clusters](#additional-features-for-registered-eks-aks-and-gke-clusters) + +### Features for All Registered Clusters + +After registering a cluster, the cluster owner can: + +- [Manage cluster access](../authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/cluster-and-project-roles.md) through role-based access control +- Enable [monitoring, alerts and notifiers](../../../integrations-in-rancher/monitoring-and-alerting/monitoring-and-alerting.md) +- Enable [logging](../../../integrations-in-rancher/logging/logging.md) +- Enable [Istio](../../../integrations-in-rancher/istio/istio.md) +- Manage projects and workloads + +### Additional Features for Registered RKE2 and K3s Clusters + +[K3s](https://rancher.com/docs/k3s/latest/en/) is a lightweight, fully compliant Kubernetes distribution for edge installations. + +[RKE2](https://docs.rke2.io) is Rancher's next-generation Kubernetes distribution for datacenter and cloud installations. + +When an RKE2 or K3s cluster is registered in Rancher, Rancher will recognize it. +The Rancher UI will expose features available to [all registered clusters](#features-for-all-registered-clusters), along with the following options for editing and upgrading the cluster: + +- Enable or disable [version management](#configuring-version-management-for-rke2-and-k3s-clusters) +- [Upgrade the Kubernetes version](../../../getting-started/installation-and-upgrade/upgrade-and-roll-back-kubernetes.md) when version management is enabled +- Configure the [upgrade strategy](#configuring-rke2-and-k3s-cluster-upgrades) when version management is enabled +- View a read-only version of the cluster’s configuration arguments and environment variables used to launch each node + +### Additional Features for Registered EKS, AKS, and GKE Clusters + +Rancher handles registered EKS, AKS, or GKE clusters similarly to clusters created in Rancher. However, Rancher doesn't destroy registered clusters when you delete them through the Rancher UI. + +When you create an EKS, AKS, or GKE cluster in Rancher, then delete it, Rancher destroys the cluster. When you delete a registered cluster through Rancher, the Rancher server _disconnects_ from the cluster. The cluster remains live, although it's no longer in Rancher. You can still access the deregistered cluster in the same way you did before you registered it. + +See [Cluster Management Capabilities by Cluster Type](kubernetes-clusters-in-rancher-setup.md) for more information about what features are available for managing registered clusters. + +## Configuring Version Management for RKE2 and K3s Clusters + +:::danger + +When version management is enabled for an imported cluster, upgrading it outside of Rancher may lead to unexpected consequences. + +::: + +The version management feature for imported RKE2 and K3s clusters can be configured using one of the following options: + +- **Global default** (default): Inherits behavior from the global **imported-cluster-version-management** setting. +- **True**: Enables version management, allowing users to control the Kubernetes version and upgrade strategy of the cluster through Rancher. +- **False**: Disables version management, enabling users to manage the cluster’s Kubernetes version independently, outside of Rancher. + +You can define the default behavior for newly created clusters or existing ones set to "Global default" by modifying the **imported-cluster-version-management** setting. + +Changes to the global **imported-cluster-version-management** setting take effect during the cluster’s next reconciliation cycle. + +:::note + +If version management is enabled for a cluster, Rancher will deploy the system-upgrade-controller app, along with the associated Plans and other required Kubernetes resources, to the cluster. +If version management is disabled, Rancher will remove these components from the cluster. + +::: + +## Configuring RKE2 and K3s Cluster Upgrades + +:::tip + +It is a Kubernetes best practice to back up the cluster before upgrading. When upgrading a high-availability K3s cluster with an external database, back up the database in whichever way is recommended by the relational database provider. + +::: + +The **concurrency** is the maximum number of nodes that are permitted to be unavailable during an upgrade. If number of unavailable nodes is larger than the **concurrency,** the upgrade will fail. If an upgrade fails, you may need to repair or remove failed nodes before the upgrade can succeed. + +- **Controlplane concurrency:** The maximum number of server nodes to upgrade at a single time; also the maximum unavailable server nodes +- **Worker concurrency:** The maximum number worker nodes to upgrade at the same time; also the maximum unavailable worker nodes + +In the RKE2 and K3s documentation, controlplane nodes are called server nodes. These nodes run the Kubernetes master, which maintains the desired state of the cluster. By default, these controlplane nodes have the capability to have workloads scheduled to them by default. + +Also in the RKE2 and K3s documentation, nodes with the worker role are called agent nodes. Any workloads or pods that are deployed in the cluster can be scheduled to these nodes by default. + +## Debug Logging and Troubleshooting for Registered RKE2 and K3s Clusters + +Nodes are upgraded by the system upgrade controller running in the downstream cluster. Based on the cluster configuration, Rancher deploys two [plans](https://github.com/rancher/system-upgrade-controller#example-upgrade-plan) to upgrade nodes: one for controlplane nodes and one for workers. The system upgrade controller follows the plans and upgrades the nodes. + +To enable debug logging on the system upgrade controller deployment, edit the [configmap](https://github.com/rancher/system-upgrade-controller/blob/50a4c8975543d75f1d76a8290001d87dc298bdb4/manifests/system-upgrade-controller.yaml#L32) to set the debug environment variable to true. Then restart the `system-upgrade-controller` pod. + +Logs created by the `system-upgrade-controller` can be viewed by running this command: + +``` +kubectl logs -n cattle-system system-upgrade-controller +``` + +The current status of the plans can be viewed with this command: + +``` +kubectl get plans -A -o yaml +``` + +:::tip + +If the cluster becomes stuck in upgrading, restart the `system-upgrade-controller`. + +::: + +To prevent issues when upgrading, the [Kubernetes upgrade best practices](https://kubernetes.io/docs/tasks/administer-cluster/kubeadm/kubeadm-upgrade/) should be followed. + +## Authorized Cluster Endpoint Support for RKE2 and K3s Clusters + +Rancher supports Authorized Cluster Endpoints (ACE) for registered RKE2 and K3s clusters. This support includes manual steps you will perform on the downstream cluster to enable the ACE. For additional information on the authorized cluster endpoint, click [here](../manage-clusters/access-clusters/authorized-cluster-endpoint.md). + +:::note Notes: + +- These steps only need to be performed on the control plane nodes of the downstream cluster. You must configure each control plane node individually. + +- The following steps will work on both RKE2 and K3s clusters registered in v2.6.x as well as those registered (or imported) from a previous version of Rancher with an upgrade to v2.6.x. + +- These steps will alter the configuration of the downstream RKE2 and K3s clusters and deploy the `kube-api-authn-webhook`. If a future implementation of the ACE requires an update to the `kube-api-authn-webhook`, then this would also have to be done manually. For more information on this webhook, click [here](../manage-clusters/access-clusters/authorized-cluster-endpoint.md#about-the-kube-api-auth-authentication-webhook). + +::: + +###### **Manual steps to be taken on the control plane of each downstream cluster to enable ACE:** + +1. Create a file at `/var/lib/rancher/{rke2,k3s}/kube-api-authn-webhook.yaml` with the following contents: + ```yaml + apiVersion: v1 + kind: Config + clusters: + - name: Default + cluster: + insecure-skip-tls-verify: true + server: http://127.0.0.1:6440/v1/authenticate + users: + - name: Default + user: + insecure-skip-tls-verify: true + current-context: webhook + contexts: + - name: webhook + context: + user: Default + cluster: Default + ``` + +2. Add the following to the config file (or create one if it doesn’t exist); note that the default location is `/etc/rancher/{rke2,k3s}/config.yaml`: + ```yaml + kube-apiserver-arg: + - authentication-token-webhook-config-file=/var/lib/rancher/{rke2,k3s}/kube-api-authn-webhook.yaml + ``` + +3. Run the following commands: + + sudo systemctl stop {rke2,k3s}-server + sudo systemctl start {rke2,k3s}-server + +4. Finally, you **must** go back to the Rancher UI and edit the imported cluster there to complete the ACE enablement. Click on **⋮ > Edit Config**, then click the **Networking** tab under Cluster Configuration. Finally, click the **Enabled** button for **Authorized Endpoint**. Once the ACE is enabled, you then have the option of entering a fully qualified domain name (FQDN) and certificate information. + +:::note + +The FQDN field is optional, and if one is entered, it should point to the downstream cluster. Certificate information is only needed if there is a load balancer in front of the downstream cluster that is using an untrusted certificate. If you have a valid certificate, then nothing needs to be added to the CA Certificates field. + +::: + +## Annotating Registered Clusters + +For all types of registered Kubernetes clusters except for RKE2 and K3s Kubernetes clusters, Rancher doesn't have any information about how the cluster is provisioned or configured. + +Therefore, when Rancher registers a cluster, it assumes that several capabilities are disabled by default. Rancher assumes this in order to avoid exposing UI options to the user even when the capabilities are not enabled in the registered cluster. + +However, if the cluster has a certain capability, such as the ability to use a pod security policy, a user of that cluster might still want to select pod security policies for the cluster in the Rancher UI. In order to do that, the user will need to manually indicate to Rancher that pod security policies are enabled for the cluster. + +By annotating a registered cluster, it is possible to indicate to Rancher that a cluster was given Ingress capabilities, or another capability, outside of Rancher. The following annotation indicates Ingress capabilities. Note that the values of non-primitive objects need to be JSON encoded, with quotations escaped. + +```json +"capabilities.cattle.io/ingressCapabilities": "[ + { + "customDefaultBackend":true, + "ingressProvider":"asdf" + } +]" +``` + +These capabilities can be annotated for the cluster: + +- `ingressCapabilities` +- `loadBalancerCapabilities` +- `nodePoolScalingSupported` +- `nodePortRange` +- `taintSupport` + +All the capabilities and their type definitions can be viewed in the Rancher API view, at `[Rancher Server URL]/v3/schemas/capabilities`. + +To annotate a registered cluster, + +1. Click **☰ > Cluster Management**. +2. On the **Clusters** page, go to the custom cluster you want to annotate and click **⋮ > Edit Config**. +3. Expand the **Labels & Annotations** section. +4. Click **Add Annotation**. +5. Add an annotation to the cluster with the format `capabilities/: ` where `value` is the cluster capability that will be overridden by the annotation. In this scenario, Rancher is not aware of any capabilities of the cluster until you add the annotation. +6. Click **Save**. + +**Result:** The annotation does not give the capabilities to the cluster, but it does indicate to Rancher that the cluster has those capabilities. + +## Troubleshooting + +This section lists some of the most common errors that may occur when importing a cluster and provides steps to troubleshoot them. + +### AKS + +- The following error may occur if local accounts are disabled in your cluster. + ```sh + Error: Getting static credential is not allowed because this cluster is set to disable local accounts. + ``` + + To resolve this issue, enable local accounts before attempting to [import the cluster](#registering-a-cluster) again. + + ```sh + az aks update --resource-group --name --enable-local-accounts + ``` diff --git a/versioned_docs/version-2.14/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-cloud-providers/amazon.md b/versioned_docs/version-2.14/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-cloud-providers/amazon.md new file mode 100644 index 00000000000..e48b8acb25e --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-cloud-providers/amazon.md @@ -0,0 +1,746 @@ +--- +title: Setting up the Amazon Cloud Provider +weight: 1 +--- + + + + + +:::note Important: + +In Kubernetes 1.27 and later, you must use an out-of-tree AWS cloud provider. In-tree cloud providers have been deprecated. The Amazon cloud provider has been removed completely, and won't work after an upgrade to Kubernetes 1.27. The steps listed below are still required to set up an Amazon cloud provider. You can [set up an out-of-tree cloud provider](#using-the-out-of-tree-aws-cloud-provider) after creating an IAM role and configuring the ClusterID. + +You can also [migrate from an in-tree to an out-of-tree AWS cloud provider](../migrate-to-an-out-of-tree-cloud-provider/migrate-to-out-of-tree-amazon.md) on Kubernetes 1.26 and earlier. All existing clusters must migrate prior to upgrading to v1.27 in order to stay functional. + +Starting with Kubernetes 1.23, you must deactivate the `CSIMigrationAWS` feature gate to use the in-tree AWS cloud provider. You can do this by setting `feature-gates=CSIMigrationAWS=false` as an additional argument for the cluster's Kubelet, Controller Manager, API Server and Scheduler in the advanced cluster configuration. + +::: + +When you use Amazon as a cloud provider, you can leverage the following capabilities: + +- **Load Balancers:** Launch an AWS Elastic Load Balancer (ELB) when you select `Layer-4 Load Balancer` in **Port Mapping** or when you launch a `Service` with `type: LoadBalancer`. +- **Persistent Volumes**: Use AWS Elastic Block Stores (EBS) for persistent volumes. + +See the [cloud-provider-aws README](https://kubernetes.github.io/cloud-provider-aws/) for more information about the Amazon cloud provider. + +To set up the Amazon cloud provider, + +1. [Create an IAM role and attach to the instances](#1-create-an-iam-role-and-attach-to-the-instances) +2. [Configure the ClusterID](#2-configure-the-clusterid) + +### 1. Create an IAM Role and attach to the instances + +All nodes added to the cluster must be able to interact with EC2 so that they can create and remove resources. You can enable this interaction by using an IAM role attached to the instance. See [Amazon documentation: Creating an IAM Role](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/iam-roles-for-amazon-ec2.html#create-iam-role) how to create an IAM role. There are two example policies: + +* The first policy is for the nodes with the `controlplane` role. These nodes have to be able to create/remove EC2 resources. The following IAM policy is an example, please remove any unneeded permissions for your use case. +* The second policy is for the nodes with the `etcd` or `worker` role. These nodes only have to be able to retrieve information from EC2. + +While creating an [Amazon EC2 cluster](../../launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/create-an-amazon-ec2-cluster.md), you must fill in the **IAM Instance Profile Name** (not ARN) of the created IAM role when creating the **Node Template**. + +While creating a [Custom cluster](../../../../reference-guides/cluster-configuration/rancher-server-configuration/use-existing-nodes/use-existing-nodes.md), you must manually attach the IAM role to the instance(s). + +IAM Policy for nodes with the `controlplane` role: + +```json +{ + "Version": "2012-10-17", + "Statement": [ + { + "Effect": "Allow", + "Action": [ + "autoscaling:DescribeAutoScalingGroups", + "autoscaling:DescribeLaunchConfigurations", + "autoscaling:DescribeTags", + "ec2:DescribeInstances", + "ec2:DescribeRegions", + "ec2:DescribeAvailabilityZones", + "ec2:DescribeRouteTables", + "ec2:DescribeSecurityGroups", + "ec2:DescribeSubnets", + "ec2:DescribeVolumes", + "ec2:CreateSecurityGroup", + "ec2:CreateTags", + "ec2:CreateVolume", + "ec2:ModifyInstanceAttribute", + "ec2:ModifyVolume", + "ec2:AttachVolume", + "ec2:AuthorizeSecurityGroupIngress", + "ec2:CreateRoute", + "ec2:DeleteRoute", + "ec2:DeleteSecurityGroup", + "ec2:DeleteVolume", + "ec2:DetachVolume", + "ec2:RevokeSecurityGroupIngress", + "ec2:DescribeVpcs", + "elasticloadbalancing:AddTags", + "elasticloadbalancing:AttachLoadBalancerToSubnets", + "elasticloadbalancing:ApplySecurityGroupsToLoadBalancer", + "elasticloadbalancing:CreateLoadBalancer", + "elasticloadbalancing:CreateLoadBalancerPolicy", + "elasticloadbalancing:CreateLoadBalancerListeners", + "elasticloadbalancing:ConfigureHealthCheck", + "elasticloadbalancing:DeleteLoadBalancer", + "elasticloadbalancing:DeleteLoadBalancerListeners", + "elasticloadbalancing:DescribeLoadBalancers", + "elasticloadbalancing:DescribeLoadBalancerAttributes", + "elasticloadbalancing:DetachLoadBalancerFromSubnets", + "elasticloadbalancing:DeregisterInstancesFromLoadBalancer", + "elasticloadbalancing:ModifyLoadBalancerAttributes", + "elasticloadbalancing:RegisterInstancesWithLoadBalancer", + "elasticloadbalancing:SetLoadBalancerPoliciesForBackendServer", + "elasticloadbalancing:AddTags", + "elasticloadbalancing:CreateListener", + "elasticloadbalancing:CreateTargetGroup", + "elasticloadbalancing:DeleteListener", + "elasticloadbalancing:DeleteTargetGroup", + "elasticloadbalancing:DescribeListeners", + "elasticloadbalancing:DescribeLoadBalancerPolicies", + "elasticloadbalancing:DescribeTargetGroups", + "elasticloadbalancing:DescribeTargetHealth", + "elasticloadbalancing:ModifyListener", + "elasticloadbalancing:ModifyTargetGroup", + "elasticloadbalancing:RegisterTargets", + "elasticloadbalancing:SetLoadBalancerPoliciesOfListener", + "iam:CreateServiceLinkedRole", + "kms:DescribeKey" + ], + "Resource": [ + "*" + ] + } + ] +} +``` + +IAM policy for nodes with the `etcd` or `worker` role: + +```json +{ + "Version": "2012-10-17", + "Statement": [ + { + "Effect": "Allow", + "Action": [ + "ec2:DescribeInstances", + "ec2:DescribeRegions", + "ec2:DescribeAvailabilityZones", + "ecr:GetAuthorizationToken", + "ecr:BatchCheckLayerAvailability", + "ecr:GetDownloadUrlForLayer", + "ecr:GetRepositoryPolicy", + "ecr:DescribeRepositories", + "ecr:ListImages", + "ecr:BatchGetImage" + ], + "Resource": "*" + } + ] +} +``` + +### 2. Configure the ClusterID + +The following resources need to tagged with a `ClusterID`: + +- **Nodes**: All hosts added in Rancher. +- **Subnet**: The subnet used for your cluster. +- **Security Group**: The security group used for your cluster. + +:::note + +Do not tag multiple security groups. Tagging multiple groups generates an error when creating an Elastic Load Balancer (ELB). + +::: + +When you create an [Amazon EC2 Cluster](../../launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/create-an-amazon-ec2-cluster.md), the `ClusterID` is automatically configured for the created nodes. Other resources still need to be manually tagged. + +Use the following tag: + +**Key** = `kubernetes.io/cluster/` **Value** = `owned` + +Setting the value of the tag to `owned` tells the cluster that all resources with this tag are owned and managed by this cluster. + +If you share resources between clusters, you can change the tag to: + +**Key** = `kubernetes.io/cluster/` **Value** = `shared`. + +The string value, ``, is the Kubernetes cluster's ID. + +:::note + +Do not tag a resource with multiple owned or shared tags. + +::: + +### Using Amazon Elastic Container Registry (ECR) + +The kubelet component has the ability to automatically obtain ECR credentials, when the IAM profile mentioned in [Create an IAM Role and attach to the instances](#1-create-an-iam-role-and-attach-to-the-instances) is attached to the instance(s). When using a Kubernetes version older than v1.15.0, the Amazon cloud provider needs be configured in the cluster. Starting with Kubernetes version v1.15.0, the kubelet can obtain ECR credentials without having the Amazon cloud provider configured in the cluster. + +### Using the Out-of-Tree AWS Cloud Provider + + + + +1. [Node name conventions and other prerequisites](https://cloud-provider-aws.sigs.k8s.io/prerequisites/) must be followed for the cloud provider to find the instance correctly. + +2. Rancher managed RKE2/K3s clusters don't support configuring `providerID`. However, the engine will set the node name correctly if the following configuration is set on the provisioning cluster object: + +```yaml +spec: + rkeConfig: + machineGlobalConfig: + cloud-provider-name: aws +``` + +This option will be passed to the configuration of the various Kubernetes components that run on the node, and must be overridden per component to prevent the in-tree provider from running unintentionally: + + +**Override on Etcd:** + +```yaml +spec: + rkeConfig: + machineSelectorConfig: + - config: + kubelet-arg: + - cloud-provider=external + machineLabelSelector: + matchExpressions: + - key: rke.cattle.io/etcd-role + operator: In + values: + - 'true' +``` + +**Override on Control Plane:** + +```yaml +spec: + rkeConfig: + machineSelectorConfig: + - config: + disable-cloud-controller: true + kube-apiserver-arg: + - cloud-provider=external + kube-controller-manager-arg: + - cloud-provider=external + kubelet-arg: + - cloud-provider=external + machineLabelSelector: + matchExpressions: + - key: rke.cattle.io/control-plane-role + operator: In + values: + - 'true' +``` + +**Override on Worker:** + +```yaml +spec: + rkeConfig: + machineSelectorConfig: + - config: + kubelet-arg: + - cloud-provider=external + machineLabelSelector: + matchExpressions: + - key: rke.cattle.io/worker-role + operator: In + values: + - 'true' +``` + +2. Select `Amazon` if relying on the above mechanism to set the provider ID. Otherwise, select **External (out-of-tree)** cloud provider, which sets `--cloud-provider=external` for Kubernetes components. + +3. Specify the `aws-cloud-controller-manager` Helm chart as an additional manifest to install: + +```yaml +spec: + rkeConfig: + additionalManifest: |- + apiVersion: helm.cattle.io/v1 + kind: HelmChart + metadata: + name: aws-cloud-controller-manager + namespace: kube-system + spec: + chart: aws-cloud-controller-manager + repo: https://kubernetes.github.io/cloud-provider-aws + targetNamespace: kube-system + bootstrap: true + valuesContent: |- + hostNetworking: true + nodeSelector: + node-role.kubernetes.io/control-plane: "true" + args: + - --configure-cloud-routes=false + - --v=5 + - --cloud-provider=aws +``` + + + + + +1. [Node name conventions and other prerequisites ](https://cloud-provider-aws.sigs.k8s.io/prerequisites/) must be followed so that the cloud provider can find the instance. Rancher provisioned clusters don't support configuring `providerID`. + +:::note + +If you use IP-based naming, the nodes must be named after the instance followed by the regional domain name (`ip-xxx-xxx-xxx-xxx.ec2..internal`). If you have a custom domain name set in the DHCP options, you must set `--hostname-override` on `kube-proxy` and `kubelet` to match this naming convention. + +::: + +To meet node naming conventions, Rancher allows setting `useInstanceMetadataHostname` when the `External Amazon` cloud provider is selected. Enabling `useInstanceMetadataHostname` will query ec2 metadata service and set `/hostname` as `hostname-override` for `kubelet` and `kube-proxy`: + +```yaml +rancher_kubernetes_engine_config: + cloud_provider: + name: external-aws + 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` 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. + +Selecting **External Amazon (out-of-tree)** sets `--cloud-provider=external` and enables `useInstanceMetadataHostname`. As mentioned in step 1, enabling `useInstanceMetadataHostname` will query the EC2 metadata service and set `http://169.254.169.254/latest/meta-data/hostname` as `hostname-override` for `kubelet` and `kube-proxy`. + +:::note + +You must disable `useInstanceMetadataHostname` when setting a custom node name for custom clusters via `node-name`. + +::: + +```yaml +rancher_kubernetes_engine_config: + cloud_provider: + name: external-aws + useInstanceMetadataHostname: true/false +``` + +Existing clusters that use an **External** cloud provider will set `--cloud-provider=external` for Kubernetes components but won't set the node name. + +3. Install the AWS cloud controller manager after the cluster finishes provisioning. Note that the cluster isn't successfully provisioned and nodes are still in an `uninitialized` state until you deploy the cloud controller manager. This can be done manually, or via [Helm charts in UI](#helm-chart-installation-from-ui). + +Refer to the offical AWS upstream documentation for the [cloud controller manager](https://kubernetes.github.io/cloud-provider-aws). + + + + +### Helm Chart Installation from CLI + + + + +Official upstream docs for [Helm chart installation](https://github.com/kubernetes/cloud-provider-aws/tree/master/charts/aws-cloud-controller-manager) can be found on GitHub. + +1. Add the Helm repository: + +```shell +helm repo add aws-cloud-controller-manager https://kubernetes.github.io/cloud-provider-aws +helm repo update +``` + +2. Create a `values.yaml` file with the following contents to override the default `values.yaml`: + +```yaml +# values.yaml +hostNetworking: true +tolerations: + - effect: NoSchedule + key: node.cloudprovider.kubernetes.io/uninitialized + value: 'true' + - effect: NoSchedule + value: 'true' + key: node-role.kubernetes.io/control-plane +nodeSelector: + node-role.kubernetes.io/control-plane: 'true' +args: + - --configure-cloud-routes=false + - --use-service-account-credentials=true + - --v=2 + - --cloud-provider=aws +clusterRoleRules: + - apiGroups: + - "" + resources: + - events + verbs: + - create + - patch + - update + - apiGroups: + - "" + resources: + - nodes + verbs: + - '*' + - apiGroups: + - "" + resources: + - nodes/status + verbs: + - patch + - apiGroups: + - "" + resources: + - services + verbs: + - list + - patch + - update + - watch + - apiGroups: + - "" + resources: + - services/status + verbs: + - list + - patch + - update + - watch + - apiGroups: + - '' + resources: + - serviceaccounts + verbs: + - create + - get + - apiGroups: + - "" + resources: + - persistentvolumes + verbs: + - get + - list + - update + - watch + - apiGroups: + - "" + resources: + - endpoints + verbs: + - create + - get + - list + - watch + - update + - apiGroups: + - coordination.k8s.io + resources: + - leases + verbs: + - create + - get + - list + - watch + - update + - apiGroups: + - "" + resources: + - serviceaccounts/token + verbs: + - create +``` + +3. Install the Helm chart: + +```shell +helm upgrade --install aws-cloud-controller-manager aws-cloud-controller-manager/aws-cloud-controller-manager --values values.yaml +``` + +Verify that the Helm chart installed successfully: + +```shell +helm status -n kube-system aws-cloud-controller-manager +``` + +4. (Optional) Verify that the cloud controller manager update succeeded: + +```shell +kubectl rollout status daemonset -n kube-system aws-cloud-controller-manager +``` + + + + + +Official upstream docs for [Helm chart installation](https://github.com/kubernetes/cloud-provider-aws/tree/master/charts/aws-cloud-controller-manager) can be found on GitHub. + +1. Add the Helm repository: + +```shell +helm repo add aws-cloud-controller-manager https://kubernetes.github.io/cloud-provider-aws +helm repo update +``` + +2. Create a `values.yaml` file with the following contents, to override the default `values.yaml`: + +```yaml +# values.yaml +hostNetworking: true +tolerations: + - effect: NoSchedule + key: node.cloudprovider.kubernetes.io/uninitialized + value: 'true' + - effect: NoSchedule + value: 'true' + key: node-role.kubernetes.io/controlplane +nodeSelector: + node-role.kubernetes.io/controlplane: 'true' +args: + - --configure-cloud-routes=false + - --use-service-account-credentials=true + - --v=2 + - --cloud-provider=aws +clusterRoleRules: + - apiGroups: + - "" + resources: + - events + verbs: + - create + - patch + - update + - apiGroups: + - "" + resources: + - nodes + verbs: + - '*' + - apiGroups: + - "" + resources: + - nodes/status + verbs: + - patch + - apiGroups: + - "" + resources: + - services + verbs: + - list + - patch + - update + - watch + - apiGroups: + - "" + resources: + - services/status + verbs: + - list + - patch + - update + - watch + - apiGroups: + - '' + resources: + - serviceaccounts + verbs: + - create + - get + - apiGroups: + - "" + resources: + - persistentvolumes + verbs: + - get + - list + - update + - watch + - apiGroups: + - "" + resources: + - endpoints + verbs: + - create + - get + - list + - watch + - update + - apiGroups: + - coordination.k8s.io + resources: + - leases + verbs: + - create + - get + - list + - watch + - update + - apiGroups: + - "" + resources: + - serviceaccounts/token + verbs: + - create +``` + +3. Install the Helm chart: + +```shell +helm upgrade --install aws-cloud-controller-manager -n kube-system aws-cloud-controller-manager/aws-cloud-controller-manager --values values.yaml +``` + +Verify that the Helm chart installed successfully: + +```shell +helm status -n kube-system aws-cloud-controller-manager +``` + +4. If present, edit the Daemonset to remove the default node selector `node-role.kubernetes.io/control-plane: ""`: + +```shell +kubectl edit daemonset aws-cloud-controller-manager -n kube-system +``` + +5. (Optional) Verify that the cloud controller manager update succeeded: + +```shell +kubectl rollout status daemonset -n kube-system aws-cloud-controller-manager +``` + + + + +### Helm Chart Installation from UI + + + + +1. Click **☰**, then select the name of the cluster from the left navigation. + +2. Select **Apps** > **Repositories**. + +3. Click the **Create** button. + +4. Enter `https://kubernetes.github.io/cloud-provider-aws` in the **Index URL** field. + +5. Select **Apps** > **Charts** from the left navigation and install **aws-cloud-controller-manager**. + +6. Select the namespace, `kube-system`, and enable **Customize Helm options before install**. + +7. Add the following container arguments: + +```yaml + - '--use-service-account-credentials=true' + - '--configure-cloud-routes=false' +``` + +8. Add `get` to `verbs` for `serviceaccounts` resources in `clusterRoleRules`. This allows the cloud controller manager to get service accounts upon startup. + +```yaml + - apiGroups: + - '' + resources: + - serviceaccounts + verbs: + - create + - get +``` + +9. Rancher-provisioned RKE2 nodes are tainted `node-role.kubernetes.io/control-plane`. Update tolerations and the nodeSelector: + +```yaml +tolerations: + - effect: NoSchedule + key: node.cloudprovider.kubernetes.io/uninitialized + value: 'true' + - effect: NoSchedule + value: 'true' + key: node-role.kubernetes.io/control-plane + +``` + +```yaml +nodeSelector: + node-role.kubernetes.io/control-plane: 'true' +``` + +:::note + +There's currently a [known issue](https://github.com/rancher/dashboard/issues/9249) where nodeSelector can't be updated from the Rancher UI. Continue installing the chart and then edit the Daemonset manually to set the `nodeSelector`: + +```yaml +nodeSelector: + node-role.kubernetes.io/control-plane: 'true' +``` + +::: + +10. Install the chart and confirm that the Daemonset `aws-cloud-controller-manager` is running. Verify `aws-cloud-controller-manager` pods are running in target namespace (`kube-system` unless modified in step 6). + + + + + +1. Click **☰**, then select the name of the cluster from the left navigation. + +2. Select **Apps** > **Repositories**. + +3. Click the **Create** button. + +4. Enter `https://kubernetes.github.io/cloud-provider-aws` in the **Index URL** field. + +5. Select **Apps** > **Charts** from the left navigation and install **aws-cloud-controller-manager**. + +6. Select the namespace, `kube-system`, and enable **Customize Helm options before install**. + +7. Add the following container arguments: + +```yaml + - '--use-service-account-credentials=true' + - '--configure-cloud-routes=false' +``` + +8. Add `get` to `verbs` for `serviceaccounts` resources in `clusterRoleRules`. This allows the cloud controller manager to get service accounts upon startup: + +```yaml + - apiGroups: + - '' + resources: + - serviceaccounts + verbs: + - create + - get +``` + +9. Rancher-provisioned RKE nodes are tainted `node-role.kubernetes.io/controlplane`. Update tolerations and the nodeSelector: + +```yaml +tolerations: + - effect: NoSchedule + key: node.cloudprovider.kubernetes.io/uninitialized + value: 'true' + - effect: NoSchedule + value: 'true' + key: node-role.kubernetes.io/controlplane + +``` + +```yaml +nodeSelector: + node-role.kubernetes.io/controlplane: 'true' +``` + +:::note + +There's currently a [known issue](https://github.com/rancher/dashboard/issues/9249) where `nodeSelector` can't be updated from the Rancher UI. Continue installing the chart and then Daemonset manually to set the `nodeSelector`: + +``` yaml +nodeSelector: + node-role.kubernetes.io/controlplane: 'true' +``` + +::: + +10. Install the chart and confirm that the Daemonset `aws-cloud-controller-manager` deploys successfully: + +```shell +kubectl rollout status deployment -n kube-system aws-cloud-controller-manager +``` + + + diff --git a/versioned_docs/version-2.14/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-cloud-providers/azure.md b/versioned_docs/version-2.14/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-cloud-providers/azure.md new file mode 100644 index 00000000000..3bb14c6fa41 --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-cloud-providers/azure.md @@ -0,0 +1,563 @@ +--- +title: Setting up the Azure Cloud Provider +--- + + + + + +:::note Important: + +In Kubernetes 1.30 and later, you must use an out-of-tree Azure cloud provider. The Azure cloud provider has been [removed completely](https://github.com/kubernetes/kubernetes/pull/122857), and won't work after an upgrade to Kubernetes 1.30. The steps listed below are still required to set up an Azure cloud provider. You can [set up an out-of-tree cloud provider](#using-the-out-of-tree-azure-cloud-provider) after completing the prerequisites for Azure. + +You can also [migrate from an in-tree to an out-of-tree Azure cloud provider](../migrate-to-an-out-of-tree-cloud-provider/migrate-to-out-of-tree-azure.md) on Kubernetes 1.29 and earlier. All existing clusters must migrate prior to upgrading to v1.30 in order to stay functional. + +Starting with Kubernetes 1.29, in-tree cloud providers have been disabled. You must set `DisableCloudProviders` and `DisableKubeletCloudCredentialProviders` feature gates to `false` to use the in-tree Azure cloud provider. You can do this by setting `feature-gates=DisableCloudProviders=false,DisableKubeletCloudCredentialProviders=false` as an additional argument for the cluster's Kubelet, Controller Manager, and API Server in the advanced cluster configuration. Setting `DisableKubeletCloudCredentialProviders=false` in the Kubelet, Controller Manager, and API Server arguments enables in-tree functionality for authenticating to Azure container registries for image pull credentials. See the [Kubernetes 1.29: Mandala release notes](https://kubernetes.io/blog/2023/12/13/kubernetes-v1-29-release/#in-tree-cloud-provider-integration-removal) and this [blog post](https://kubernetes.io/blog/2023/12/14/cloud-provider-integration-changes/#continue-using-in-tree-provider-code) for more details. + +Starting with Kubernetes version 1.26, in-tree persistent volume types `kubernetes.io/azure-disk` and `kubernetes.io/azure-file` are deprecated and will no longer be supported. For new clusters, [install the CSI drivers](#installing-csi-drivers), or migrate to the corresponding CSI drivers `disk.csi.azure.com` and `file.csi.azure.com` by following the [upstream migration documentation](https://learn.microsoft.com/en-us/azure/aks/csi-migrate-in-tree-volumes). +::: + +When using the `Azure` cloud provider, you can leverage the following capabilities: + +- **Load Balancers:** Launches an Azure Load Balancer within a specific Network Security Group. + +- **Persistent Volumes:** Supports using Azure Blob disks and Azure Managed Disks with standard and premium storage accounts. + +- **Network Storage:** Support Azure Files via CIFS mounts. + +The following account types are not supported for Azure Subscriptions: + +- Single tenant accounts (i.e. accounts with no subscriptions). +- Multi-subscription accounts. + +## Prerequisites for RKE and RKE2 + +To set up the Azure cloud provider for both RKE and RKE2, the following credentials need to be configured: + +1. [Set up the Azure Tenant ID](#1-set-up-the-azure-tenant-id) +2. [Set up the Azure Client ID and Azure Client Secret](#2-set-up-the-azure-client-id-and-azure-client-secret) +3. [Configure App Registration Permissions](#3-configure-app-registration-permissions) +4. [Set up Azure Network Security Group Name](#4-set-up-azure-network-security-group-name) + +### 1. Set up the Azure Tenant ID + +Visit [Azure portal](https://portal.azure.com), login and go to **Azure Active Directory** and select **Properties**. Your **Directory ID** is your **Tenant ID** (tenantID). + +If you want to use the Azure CLI, you can run the command `az account show` to get the information. + +### 2. Set up the Azure Client ID and Azure Client Secret + +Visit [Azure portal](https://portal.azure.com), login and follow the steps below to create an **App Registration** and the corresponding **Azure Client ID** (aadClientId) and **Azure Client Secret** (aadClientSecret). + +1. Select **Azure Active Directory**. +1. Select **App registrations**. +1. Select **New application registration**. +1. Choose a **Name**, select `Web app / API` as **Application Type** and a **Sign-on URL** which can be anything in this case. +1. Select **Create**. + +In the **App registrations** view, you should see your created App registration. The value shown in the column **APPLICATION ID** is what you need to use as **Azure Client ID**. + +The next step is to generate the **Azure Client Secret**: + +1. Open your created App registration. +1. In the **Settings** view, open **Keys**. +1. Enter a **Key description**, select an expiration time and select **Save**. +1. The generated value shown in the column **Value** is what you need to use as **Azure Client Secret**. This value will only be shown once. + +### 3. Configure App Registration Permissions + +The last thing you will need to do, is assign the appropriate permissions to your App registration. + +1. Go to **More services**, search for **Subscriptions** and open it. +1. Open **Access control (IAM)**. +1. Select **Add**. +1. For **Role**, select `Contributor`. +1. For **Select**, select your created App registration name. +1. Select **Save**. + +### 4. Set up Azure Network Security Group Name + +A custom Azure Network Security Group (securityGroupName) is needed to allow Azure Load Balancers to work. + +If you provision hosts using Rancher Machine Azure driver, you will need to edit them manually to assign them to this Network Security Group. + +You should already assign custom hosts to this Network Security Group during provisioning. + +Only hosts expected to be load balancer back ends need to be in this group. + +## RKE2 Cluster Set-up in Rancher + +:::note Important: +This section is valid only for creating clusters with the in-tree cloud provider. +::: + +1. Choose "Azure" from the Cloud Provider drop-down in the Cluster Configuration section. + +2. Supply the Cloud Provider Configuration. Note that Rancher automatically creates a new Network Security Group, Resource Group, Availability Set, Subnet, and Virtual Network. If you already have some or all of these created, you must specify them before creating the cluster. + * Click **Show Advanced** to view or edit these automatically generated names. Your Cloud Provider Configuration **must** match the fields in the **Machine Pools** section. If you have multiple pools, they must all use the same Resource Group, Availability Set, Subnet, Virtual Network, and Network Security Group. + * An example is provided below. Modify it as needed. + +
+ Example Cloud Provider Config + + ```yaml + { + "cloud":"AzurePublicCloud", + "tenantId": "YOUR TENANTID HERE", + "aadClientId": "YOUR AADCLIENTID HERE", + "aadClientSecret": "YOUR AADCLIENTSECRET HERE", + "subscriptionId": "YOUR SUBSCRIPTIONID HERE", + "resourceGroup": "docker-machine", + "location": "westus", + "subnetName": "docker-machine", + "securityGroupName": "rancher-managed-KA4jV9V2", + "securityGroupResourceGroup": "docker-machine", + "vnetName": "docker-machine-vnet", + "vnetResourceGroup": "docker-machine", + "primaryAvailabilitySetName": "docker-machine", + "routeTableResourceGroup": "docker-machine", + "cloudProviderBackoff": false, + "useManagedIdentityExtension": false, + "useInstanceMetadata": true + } + ``` + +
+ +3. Under the **Cluster Configuration > Advanced** section, click **Add** under **Additional Controller Manager Args** and add this flag: `--configure-cloud-routes=false` + +4. Click **Create** to submit the form and create the cluster. + +## Cloud Provider Configuration + +Rancher automatically creates a new Network Security Group, Resource Group, Availability Set, Subnet, and Virtual Network. If you already have some or all of these created, you will need to specify them before creating the cluster. You can check **RKE1 Node Templates** or **RKE2 Machine Pools** to view or edit these automatically generated names. + +**Refer to the full list of configuration options in the [upstream docs](https://cloud-provider-azure.sigs.k8s.io/install/configs/).** + +:::note +1. `useInstanceMetadata` must be set to `true` for the cloud provider to correctly configure `providerID`. +2. `excludeMasterFromStandardLB` must be set to `false` if you need to add nodes labeled `node-role.kubernetes.io/master` to the backend of the Azure Load Balancer (ALB). +3. `loadBalancerSku` can be set to `basic` or `standard`. Basic SKU will be deprecated in September 2025. Refer to the [Azure upstream docs](https://learn.microsoft.com/en-us/azure/virtual-network/ip-services/public-ip-basic-upgrade-guidance#basic-sku-vs-standard-sku) for more information. +::: + +Azure supports reading the cloud config from Kubernetes secrets. The secret is a serialized version of the azure.json file. When the secret is changed, the cloud controller manager reconstructs itself without restarting the pod. It is recommended for the Helm chart to read the Cloud Provider Config from the secret. + +Note that the chart reads the Cloud Provider Config from a given secret name in the `kube-system` namespace. Since Azure reads Kubernetes secrets, RBAC also needs to be configured. An example secret for the Cloud Provider Config is shown below. Modify it as needed and create the secret. + + ```yaml +# azure-cloud-config.yaml +apiVersion: v1 +kind: Secret +metadata: + name: azure-cloud-config + namespace: kube-system +type: Opaque +stringData: + cloud-config: |- + { + "cloud": "AzurePublicCloud", + "tenantId": "", + "subscriptionId": "", + "aadClientId": "", + "aadClientSecret": "", + "resourceGroup": "docker-machine", + "location": "westus", + "subnetName": "docker-machine", + "securityGroupName": "rancher-managed-kqmtsjgJ", + "securityGroupResourceGroup": "docker-machine", + "vnetName": "docker-machine-vnet", + "vnetResourceGroup": "docker-machine", + "primaryAvailabilitySetName": "docker-machine", + "routeTableResourceGroup": "docker-machine", + "cloudProviderBackoff": false, + "useManagedIdentityExtension": false, + "useInstanceMetadata": true, + "loadBalancerSku": "standard", + "excludeMasterFromStandardLB": false, + } + ``` + +## Using the Out-of-tree Azure Cloud Provider + + + + +1. Select **External** from the **Cloud Provider** drop-down in the **Cluster Configuration** section. + +2. Under **Cluster Configuration > Advanced**, click **Add** under **Additional Controller Manager Args** and add this flag: `--configure-cloud-routes=false`. + +3. Prepare the Cloud Provider Configuration to set it in the next step. Note that Rancher automatically creates a new Network Security Group, Resource Group, Availability Set, Subnet, and Virtual Network. If you already have some or all of these created, you must specify them before creating the cluster. + + Click **Show Advanced** to view or edit these automatically generated names. Your Cloud Provider Configuration **must** match the fields in the **Machine Pools** section. If you have multiple pools, they must all use the same Resource Group, Availability Set, Subnet, Virtual Network, and Network Security Group. + +4. Under **Cluster Configuration > Add-on Config**, add the cloud controller manager manifest shown below into **Additional Manifest**. +Note that this chart reads the Cloud Provider Config from the secret in the `kube-system` namespace. An example secret for the Cloud Provider Config is shown below; modify it as needed. Refer to the full list of configuration options in the [upstream docs](https://cloud-provider-azure.sigs.k8s.io/install/configs/). + + Alternatively, you can also install the cloud controller manager using the [Helm CLI](#helm-chart-installation-from-cli). + + ```yaml + apiVersion: helm.cattle.io/v1 + kind: HelmChart + metadata: + name: azure-cloud-controller-manager + namespace: kube-system + spec: + chart: cloud-provider-azure + repo: https://raw.githubusercontent.com/kubernetes-sigs/cloud-provider-azure/master/helm/repo + targetNamespace: kube-system + bootstrap: true + valuesContent: |- + infra: + clusterName: + cloudControllerManager: + cloudConfigSecretName: azure-cloud-config + cloudConfig: null + clusterCIDR: null + enableDynamicReloading: 'true' + nodeSelector: + node-role.kubernetes.io/control-plane: 'true' + allocateNodeCidrs: 'false' + hostNetworking: true + caCertDir: /etc/ssl + configureCloudRoutes: 'false' + enabled: true + tolerations: + - effect: NoSchedule + key: node-role.kubernetes.io/master + - effect: NoSchedule + key: node-role.kubernetes.io/control-plane + value: 'true' + - effect: NoSchedule + key: node.cloudprovider.kubernetes.io/uninitialized + value: 'true' + --- + apiVersion: v1 + kind: Secret + metadata: + name: azure-cloud-config + namespace: kube-system + type: Opaque + stringData: + cloud-config: |- + { + "cloud": "AzurePublicCloud", + "tenantId": "", + "subscriptionId": "", + "aadClientId": "", + "aadClientSecret": "", + "resourceGroup": "docker-machine", + "location": "westus", + "subnetName": "docker-machine", + "securityGroupName": "rancher-managed-kqmtsjgJ", + "securityGroupResourceGroup": "docker-machine", + "vnetName": "docker-machine-vnet", + "vnetResourceGroup": "docker-machine", + "primaryAvailabilitySetName": "docker-machine", + "routeTableResourceGroup": "docker-machine", + "cloudProviderBackoff": false, + "useManagedIdentityExtension": false, + "useInstanceMetadata": true, + "loadBalancerSku": "standard", + "excludeMasterFromStandardLB": false, + } + ``` + +5. Click **Create** to submit the form and create the cluster. + + + + + +1. Choose **External** from the **Cloud Provider** drop-down in the **Cluster Options** section. This sets `--cloud-provider=external` for Kubernetes components. + +2. Install the `cloud-provider-azure` chart after the cluster finishes provisioning. Note that the cluster is not successfully provisioned and nodes are still in an `uninitialized` state until you deploy the cloud controller manager. This can be done [manually using CLI](#helm-chart-installation-from-cli), or via [Helm charts in UI](#helm-chart-installation-from-ui). + +Refer to the [official Azure upstream documentation](https://cloud-provider-azure.sigs.k8s.io/install/azure-ccm/) for more details on deploying the Cloud Controller Manager. + + + + +### Helm Chart Installation from CLI + +Official upstream docs for [Helm chart installation](https://github.com/kubernetes-sigs/cloud-provider-azure/tree/master/helm/cloud-provider-azure) can be found on Github. + +1. Create a `azure-cloud-config` secret with the required [cloud provider config](#cloud-provider-configuration). + +```shell +kubectl apply -f azure-cloud-config.yaml +``` + +2. Add the Helm repository: + +```shell +helm repo add azure-cloud-controller-manager https://raw.githubusercontent.com/kubernetes-sigs/cloud-provider-azure/master/helm/repo +helm repo update +``` + +3. Create a `values.yaml` file with the following contents to override the default `values.yaml`: + + + + +```yaml +# values.yaml +infra: + clusterName: +cloudControllerManager: + cloudConfigSecretName: azure-cloud-config + cloudConfig: null + clusterCIDR: null + enableDynamicReloading: 'true' + configureCloudRoutes: 'false' + allocateNodeCidrs: 'false' + caCertDir: /etc/ssl + enabled: true + replicas: 1 + hostNetworking: true + nodeSelector: + node-role.kubernetes.io/control-plane: 'true' + tolerations: + - effect: NoSchedule + key: node-role.kubernetes.io/master + - effect: NoSchedule + key: node-role.kubernetes.io/control-plane + value: 'true' + - effect: NoSchedule + key: node.cloudprovider.kubernetes.io/uninitialized + value: 'true' +``` + + + + + +```yaml +# values.yaml +cloudControllerManager: + cloudConfigSecretName: azure-cloud-config + cloudConfig: null + clusterCIDR: null + enableDynamicReloading: 'true' + configureCloudRoutes: 'false' + allocateNodeCidrs: 'false' + caCertDir: /etc/ssl + enabled: true + replicas: 1 + hostNetworking: true + nodeSelector: + node-role.kubernetes.io/controlplane: 'true' + node-role.kubernetes.io/control-plane: null + tolerations: + - effect: NoSchedule + key: node-role.kubernetes.io/controlplane + value: 'true' + - effect: NoSchedule + key: node.cloudprovider.kubernetes.io/uninitialized + value: 'true' +infra: + clusterName: +``` + + + + +4. Install the Helm chart: + +```shell +helm upgrade --install cloud-provider-azure azure-cloud-controller-manager/cloud-provider-azure -n kube-system --values values.yaml +``` + +Verify that the Helm chart installed successfully: + +```shell +helm status cloud-provider-azure -n kube-system +``` + +5. (Optional) Verify that the cloud controller manager update succeeded: + +```shell +kubectl rollout status deployment -n kube-system cloud-controller-manager +kubectl rollout status daemonset -n kube-system cloud-node-manager +``` + +6. The cloud provider is responsible for setting the ProviderID of the node. Check if all nodes are initialized with the ProviderID: + +```shell +kubectl describe nodes | grep "ProviderID" +``` + +### Helm Chart Installation from UI + +1. Click **☰**, then select the name of the cluster from the left navigation. + +2. Select **Apps** > **Repositories**. + +3. Click the **Create** button. + +4. Enter `https://raw.githubusercontent.com/kubernetes-sigs/cloud-provider-azure/master/helm/repo` in the **Index URL** field. + +5. Select **Apps** > **Charts** from the left navigation and install **cloud-provider-azure** chart. + +6. Select the namespace, `kube-system`, and enable **Customize Helm options before install**. + +7. Replace `cloudConfig: /etc/kubernetes/azure.json` to read from the Cloud Config Secret and enable dynamic reloading: + +```yaml + cloudConfigSecretName: azure-cloud-config + enableDynamicReloading: 'true' +``` + +8. Update the following fields as required: + +```yaml + allocateNodeCidrs: 'false' + configureCloudRoutes: 'false' + clusterCIDR: null +``` + + + + +9. Rancher-provisioned RKE2 nodes have the selector `node-role.kubernetes.io/control-plane` set to `true`. Update the nodeSelector: +```yaml +nodeSelector: + node-role.kubernetes.io/control-plane: 'true' +``` + + + + +10. Rancher-provisioned RKE nodes are tainted `node-role.kubernetes.io/controlplane`. Update tolerations and the nodeSelector: + +```yaml +tolerations: + - effect: NoSchedule + key: node.cloudprovider.kubernetes.io/uninitialized + value: 'true' + - effect: NoSchedule + value: 'true' + key: node-role.kubernetes.io/controlplane +``` + +```yaml +nodeSelector: + node-role.kubernetes.io/controlplane: 'true' +``` + + + +11. Install the chart and confirm that the cloud controller and cloud node manager deployed successfully: + +```shell +kubectl rollout status deployment -n kube-system cloud-controller-manager +kubectl rollout status daemonset -n kube-system cloud-node-manager +``` + +12. The cloud provider is responsible for setting the ProviderID of the node. Check if all nodes are initialized with the ProviderID: + +```shell +kubectl describe nodes | grep "ProviderID" +``` + +### Installing CSI Drivers + +Install [Azure Disk CSI driver](https://github.com/kubernetes-sigs/azuredisk-csi-driver) or [Azure File CSI Driver](https://github.com/kubernetes-sigs/azurefile-csi-driver) to access [Azure Disk](https://azure.microsoft.com/en-us/services/storage/disks/) or [Azure File](https://azure.microsoft.com/en-us/services/storage/disks/) volumes respectively. + +The steps to install the Azure Disk CSI driver are shown below. You can install the Azure File CSI Driver in a similar manner by following the [helm installation documentation](https://github.com/kubernetes-sigs/azurefile-csi-driver/blob/master/charts/README.md). + +::: note Important: + +Clusters must be provisioned using `Managed Disk` to use Azure Disk. You can configure this when creating **RKE1 Node Templates** or **RKE2 Machine Pools*. + +::: + +Official upstream docs for [Helm chart installation](https://github.com/kubernetes-sigs/azuredisk-csi-driver/blob/master/charts/README.md) can be found on Github. + +1. Add and update the helm repository: + +```shell +helm repo add azuredisk-csi-driver https://raw.githubusercontent.com/kubernetes-sigs/azuredisk-csi-driver/master/charts +helm repo update azuredisk-csi-driver +``` + +1. Install the chart as shown below, updating the --version argument as needed. Refer to the full list of latest chart configurations in the [upstream docs](https://github.com/kubernetes-sigs/azuredisk-csi-driver/blob/master/charts/README.md#latest-chart-configuration). + +```shell +helm install azuredisk-csi-driver azuredisk-csi-driver/azuredisk-csi-driver --namespace kube-system --version v1.30.1 --set controller.cloudConfigSecretName=azure-cloud-config --set controller.cloudConfigSecretNamespace=kube-system --set controller.runOnControlPlane=true +``` + +2. (Optional) Verify that the azuredisk-csi-driver installation succeeded: + +```shell +kubectl --namespace=kube-system get pods --selector="app.kubernetes.io/name=azuredisk-csi-driver" --watch +``` + +3. Provision an example Storage Class: + +```shell +cat < + + + +To set up the in-tree VMware vSphere cloud provider, follow these steps while creating the vSphere cluster in Rancher: + +1. Set **Cloud Provider** option to `Custom` or `Custom (In-Tree)`. +1. Click on **Edit as YAML** +1. Insert the following structure to the pre-populated cluster YAML. This structure must be placed under `rancher_kubernetes_engine_config`. Note that the `name` *must* be set to `vsphere`. + + ```yaml + rancher_kubernetes_engine_config: + cloud_provider: + name: vsphere + vsphereCloudProvider: + [Insert provider configuration] + ``` + +Rancher uses RKE (the Rancher Kubernetes Engine) to provision Kubernetes clusters. Refer to the [vSphere configuration reference in the RKE documentation](https://rancher.com/docs/rke/latest/en/config-options/cloud-providers/vsphere/config-reference/) for details about the properties of the `vsphereCloudProvider` directive. diff --git a/versioned_docs/version-2.14/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-cloud-providers/configure-out-of-tree-vsphere.md b/versioned_docs/version-2.14/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-cloud-providers/configure-out-of-tree-vsphere.md new file mode 100644 index 00000000000..6e866abc971 --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-cloud-providers/configure-out-of-tree-vsphere.md @@ -0,0 +1,68 @@ +--- +title: Setting Up an Out-of-tree VMware vSphere Cloud Provider +--- + + + + + +Kubernetes is moving away from maintaining cloud providers in-tree. VMware vSphere has an out-of-tree cloud provider that can be used by installing the vSphere cloud provider and cloud storage plugins. + +This page covers how to install the Cloud Provider Interface (CPI) and Cloud Storage Interface (CSI) plugins after setting up a cluster. + +## Prerequisites + +The vSphere versions supported: + +* 6.7u3 +* 7.0u1 or higher. + +The Kubernetes version must be 1.19 or higher. + +Using the vSphere out-of-tree cloud provider requires Linux nodes and is not supported on Windows. + +## Installation + +The Cloud Provider Interface (CPI) should be installed first before installing the Cloud Storage Interface (CSI). + +### 1. Create a VMware vSphere cluster + +1. Click **☰ > Cluster Management**. +1. On the **Clusters** page, click **Create**. +1. Click **VMware vSphere** or **Custom**. +1. On the **Basics** tab in the **Cluster Configuration** section, set the **Cloud Provider** to **vSphere**. +1. In the **Add-On Config** tab, the vSphere Cloud Provider (CPI) and Storage Provider (CSI) options. +1. Finish creating your cluster. + +### 2. Install the CPI plugin + +1. Click **☰ > Cluster Management**. +1. Go to the cluster where the vSphere CPI plugin will be installed and click **Explore**. +1. Click **Apps > Charts**. +1. Click **vSphere CPI**. +1. Fill out the required vCenter details. +1. vSphere CPI initializes all nodes with ProviderID which is needed by the vSphere CSI driver. Check if all nodes are initialized with the ProviderID before installing CSI driver with the following command: + + ``` + kubectl describe nodes | grep "ProviderID" + ``` + +### 3. Installing the CSI plugin + +1. Click **☰ > Cluster Management**. +1. Go to the cluster where the vSphere CSI plugin will be installed and click **Explore**. +1. Click **Apps > Charts**. +1. Click **vSphere CSI**. +1. Click **Install**. +1. Fill out the required vCenter details. On the **Features** tab, set **Enable CSI Migration** to **false**. +3. On the **Storage** tab, fill out the details for the StorageClass. This chart creates a StorageClass with the `csi.vsphere.vmware.com` as the provisioner. +1. Click **Install**. + + +## Using the CSI driver for provisioning volumes + +The CSI chart by default creates a storageClass. + +If that option was not selected while launching the chart, create a storageClass with the `csi.vsphere.vmware.com` as the provisioner. + +All volumes provisioned using this StorageClass will get provisioned by the CSI driver. diff --git a/versioned_docs/version-2.14/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-cloud-providers/google-compute-engine.md b/versioned_docs/version-2.14/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-cloud-providers/google-compute-engine.md new file mode 100644 index 00000000000..11c20dcfd27 --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-cloud-providers/google-compute-engine.md @@ -0,0 +1,61 @@ +--- +title: Setting up the Google Compute Engine Cloud Provider +--- + + + + + +In this section, you'll learn how to enable the Google Compute Engine (GCE) cloud provider for custom clusters in Rancher. A custom cluster is one in which Rancher installs Kubernetes on existing nodes. + +The official Kubernetes documentation for the GCE cloud provider is [here.](https://github.com/kubernetes/website/blob/release-1.18/content/en/docs/concepts/cluster-administration/cloud-providers.md#gce) + +:::note Prerequisites: + +The service account of `Identity and API` access on GCE needs the `Computer Admin` permission. + +::: + +If you are using Calico, + +1. Click **☰ > Cluster Management**. +1. On the **Clusters** page, go to the custom cluster and click **⋮ > Edit YAML.* Enter the following configuration: + + ```yaml + rancher_kubernetes_engine_config: + cloud_provider: + name: gce + customCloudProvider: |- + [Global] + project-id= + network-name= + subnetwork-name= + node-instance-prefix= + node-tags= + network: + options: + calico_cloud_provider: "gce" + plugin: "calico" + ``` + +If you are using Canal or Flannel, + +1. Click **☰ > Cluster Management**. +1. On the **Clusters** page, go to the custom cluster and click **⋮ > Edit YAML.* Enter the following configuration: + + ```yaml + rancher_kubernetes_engine_config: + cloud_provider: + name: gce + customCloudProvider: |- + [Global] + project-id= + network-name= + subnetwork-name= + node-instance-prefix= + node-tags= + services: + kube_controller: + extra_args: + configure-cloud-routes: true # we need to allow the cloud provider configure the routes for the hosts + ``` \ No newline at end of file diff --git a/versioned_docs/version-2.14/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-cloud-providers/set-up-cloud-providers.md b/versioned_docs/version-2.14/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-cloud-providers/set-up-cloud-providers.md new file mode 100644 index 00000000000..4cf5e31ad8c --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-cloud-providers/set-up-cloud-providers.md @@ -0,0 +1,47 @@ +--- +title: Setting up Cloud Providers +--- + + + + + +A _cloud provider_ is a module in Kubernetes that provides an interface for managing nodes, load balancers, and networking routes. + +When a cloud provider is set up in Rancher, the Rancher server can automatically provision new nodes, load balancers or persistent storage devices when launching Kubernetes definitions, if the cloud provider you're using supports such automation. + +Your cluster will not provision correctly if you configure a cloud provider cluster of nodes that do not meet the prerequisites. + +By default, the **Cloud Provider** option is set to `None`. + +The following cloud providers can be enabled: + +* Amazon +* Azure +* GCE (Google Compute Engine) +* vSphere + +### Setting up the Amazon Cloud Provider + +For details on enabling the Amazon cloud provider, refer to [this page.](amazon.md) + +### Setting up the Azure Cloud Provider + +For details on enabling the Azure cloud provider, refer to [this page.](azure.md) + +### Setting up the GCE Cloud Provider + +For details on enabling the Google Compute Engine cloud provider, refer to [this page.](google-compute-engine.md) + +### Setting up the VMware vSphere Cloud Provider + +For details on enabling the vSphere cloud provider, refer to [in-tree vSphere config](configure-in-tree-vsphere.md) and [out-of-tree vSphere config](configure-out-of-tree-vsphere.md). + +### Setting up a Custom Cloud Provider + +The `Custom` cloud provider is available if you want to configure any Kubernetes cloud provider. + +For the custom cloud provider option, you can refer to the [RKE docs](https://rancher.com/docs/rke/latest/en/config-options/cloud-providers/) on how to edit the yaml file for your specific cloud provider. There are specific cloud providers that have more detailed configuration: + +* [vSphere](https://rke.docs.rancher.com/config-options/cloud-providers/vsphere) +* [OpenStack](https://rancher.com/docs/rke/latest/en/config-options/cloud-providers/openstack/) diff --git a/versioned_docs/version-2.14/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-clusters-from-hosted-kubernetes-providers/aks.md b/versioned_docs/version-2.14/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-clusters-from-hosted-kubernetes-providers/aks.md new file mode 100644 index 00000000000..362a673c023 --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-clusters-from-hosted-kubernetes-providers/aks.md @@ -0,0 +1,260 @@ +--- +title: Creating an AKS Cluster +--- + + + + + +You can use Rancher to create a cluster hosted in Microsoft Azure Kubernetes Service (AKS). + +## Prerequisites in Microsoft Azure + +:::caution + +Deploying to AKS will incur charges. + +::: + +To interact with Azure APIs, an AKS cluster requires an Azure Active Directory (AD) service principal. The service principal is needed to dynamically create and manage other Azure resources, and it provides credentials for your cluster to communicate with AKS. For more information about the service principal, refer to the [AKS documentation](https://docs.microsoft.com/en-us/azure/aks/kubernetes-service-principal). + +Before creating the service principal, you need to obtain the following information from the [Microsoft Azure Portal](https://portal.azure.com): + +- Subscription ID +- Client ID (also known as app ID) +- Client secret + +The below sections describe how to set up these prerequisites using either the Azure command line tool or the Azure portal. + +### Setting Up the Service Principal with the Azure Command Line Tool + +You must assign roles to the service principal so that it has communication privileges with the AKS API. It also needs access to create and list virtual networks. + +In the following example, the command creates the service principal and gives it the Contributor role. The Contributor role can manage anything on AKS but cannot give access to others. Note that you must provide `scopes` a full path to at least one Azure resource: + +``` +az ad sp create-for-rbac --role Contributor --scopes /subscriptions//resourceGroups/ +``` + +The result should show information about the new service principal: + +``` +{ + "appId": "xxxx--xxx", + "displayName": "", + "name": "http://", + "password": "", + "tenant": "" +} +``` + +The following creates a [Resource Group](https://learn.microsoft.com/en-us/azure/azure-resource-manager/management/manage-resource-groups-cli) to contain your Azure resources: + +``` +az group create --location --resource-group +``` + +### Setting Up the Service Principal from the Azure Portal + +Follow these instructions to set up a service principal and give it role-based access from the Azure Portal. + +1. Go to the Microsoft Azure Portal [home page](https://portal.azure.com). +1. Click **Azure Active Directory**. +1. Click **App registrations**. +1. Click **New registration**. +1. Enter a name for your service principal. +1. Optional: Choose which accounts can use the service principal. +1. Click **Register**. +1. You should now see the name of your service principal under **Azure Active Directory > App registrations**. +1. Click the name of your service principal. Take note of the application ID (also called app ID or client ID) so that you can use it when provisioning your AKS cluster. Then click **Certificates & secrets**. +1. Click **New client secret**. +1. Enter a short description, pick an expiration time, and click **Add**. Take note of the client secret so that you can use it when provisioning the AKS cluster. + +**Result:** You have created a service principal and you should be able to see it listed in the **Azure Active Directory** section under **App registrations**. You still need to give the service principal access to AKS. + +To give role-based access to your service principal, + +1. Click **All Services** in the left navigation bar. Then click **Subscriptions**. +1. Click the name of the subscription that you want to associate with your Kubernetes cluster. Take note of the subscription ID so that you can use it when provisioning your AKS cluster. +1. Click **Access Control (IAM)**. +1. In the **Add role assignment** section, click **Add**. +1. In the **Role** field, select a role that will have access to AKS. For example, you can use the **Contributor** role, which has permission to manage everything except for giving access to other users. +1. In the **Assign access to** field, select **Azure AD user, group, or service principal**. +1. In the **Select** field, select the name of your service principal and click **Save**. + +**Result:** Your service principal now has access to AKS. + +## Create the AKS Cloud Credentials + +1. In the Rancher UI, click **☰ > Cluster Management**. +1. Click **Cloud Credentials**. +1. Click **Create**. +1. Click **Azure**. +1. Fill out the form. For help with filling out the form, see the [configuration reference.](../../../../reference-guides/cluster-configuration/rancher-server-configuration/aks-cluster-configuration.md#cloud-credentials) +1. Click **Create**. + +## Create the AKS Cluster + +Use Rancher to set up and configure your Kubernetes cluster. + +1. Click **☰ > Cluster Management**. +1. In the **Clusters** section, click **Create**. +1. Click **Azure AKS**. +1. Fill out the form. For help with filling out the form, see the [configuration reference.](../../../../reference-guides/cluster-configuration/rancher-server-configuration/aks-cluster-configuration.md) +1. Click **Create**. + +**Result:** Your cluster is created and assigned a state of **Provisioning**. Rancher is standing up your cluster. + +You can access your cluster after its state is updated to **Active**. + +## Configure Role-based Access Control + +When provisioning an AKS cluster in the Rancher UI, RBAC is not configurable because it is required to be enabled. + +RBAC is required for AKS clusters that are registered or imported into Rancher. + +### Setting Up the Role Assignment to Service Principal with the Azure Command Line Tool + +Assign the Rancher AKSv2 role to the service principal with the Azure Command Line Tool: + +``` +az role assignment create \ +--assignee \ +--scope "/subscriptions//resourceGroups/" \ +--role "Rancher AKSv2" +``` + +## AKS Cluster Configuration Reference + +For more information about how to configure AKS clusters from the Rancher UI, see the [configuration reference.](../../../../reference-guides/cluster-configuration/rancher-server-configuration/aks-cluster-configuration.md) + +## Private Clusters + +Typically, AKS worker nodes do not get public IPs, regardless of whether the cluster is private. In a private cluster, the control plane does not have a public endpoint. + +Rancher can connect to a private AKS cluster in one of two ways. + +The first way to ensure that Rancher is running on the same [NAT](https://docs.microsoft.com/en-us/azure/virtual-network/nat-overview) as the AKS nodes. + +The second way is to run a command to register the cluster with Rancher. Once the cluster is provisioned, you can run the displayed command anywhere you can connect to the cluster’s Kubernetes API. This command is displayed in a pop-up when you provision an AKS cluster with a private API endpoint enabled. + +:::note + +Please be aware that when registering an existing AKS cluster, the cluster might take some time, possibly hours, to appear in the `Cluster To register` dropdown list. This outcome will be based on region. + +::: + +For more information about connecting to an AKS private cluster, see the [AKS documentation.](https://docs.microsoft.com/en-us/azure/aks/private-clusters#options-for-connecting-to-the-private-cluster) + +## Setting Up the Minimum Permission Role with the Azure Command Line Tool + +1. Create the Minimum Rancher AKSv2 Permission Role by running this command: + + ``` + cat >> rancher-azure.json << EOF + + { + "Name": "Rancher AKSv2", + "IsCustom": true, + "Description": "Everything needed by Rancher AKSv2 operator", + "Actions": [ + "Microsoft.Compute/disks/delete", + "Microsoft.Compute/disks/read", + "Microsoft.Compute/disks/write", + "Microsoft.Compute/diskEncryptionSets/read", + "Microsoft.Compute/locations/DiskOperations/read", + "Microsoft.Compute/locations/vmSizes/read", + "Microsoft.Compute/locations/operations/read", + "Microsoft.Compute/proximityPlacementGroups/write", + "Microsoft.Compute/snapshots/delete", + "Microsoft.Compute/snapshots/read", + "Microsoft.Compute/snapshots/write", + "Microsoft.Compute/virtualMachineScaleSets/manualUpgrade/action", + "Microsoft.Compute/virtualMachineScaleSets/delete", + "Microsoft.Compute/virtualMachineScaleSets/read", + "Microsoft.Compute/virtualMachineScaleSets/virtualMachines/networkInterfaces/read", + "Microsoft.Compute/virtualMachineScaleSets/virtualMachines/networkInterfaces/ipconfigurations/publicipaddresses/read", + "Microsoft.Compute/virtualMachineScaleSets/virtualmachines/instanceView/read", + "Microsoft.Compute/virtualMachineScaleSets/virtualMachines/read", + "Microsoft.Compute/virtualMachineScaleSets/virtualMachines/write", + "Microsoft.Compute/virtualMachineScaleSets/write", + "Microsoft.Compute/virtualMachines/read", + "Microsoft.Compute/virtualMachines/write", + "Microsoft.ContainerService/managedClusters/read", + "Microsoft.ContainerService/managedClusters/write", + "Microsoft.ContainerService/managedClusters/delete", + "Microsoft.ContainerService/managedClusters/accessProfiles/listCredential/action", + "Microsoft.ContainerService/managedClusters/agentPools/read", + "Microsoft.ContainerService/managedClusters/agentPools/write", + "Microsoft.ContainerService/managedClusters/agentPools/delete", + "Microsoft.ManagedIdentity/userAssignedIdentities/assign/action", + "Microsoft.Network/applicationGateways/read", + "Microsoft.Network/applicationGateways/write", + "Microsoft.Network/loadBalancers/write", + "Microsoft.Network/loadBalancers/backendAddressPools/join/action", + "Microsoft.Network/loadBalancers/delete", + "Microsoft.Network/loadBalancers/read", + "Microsoft.Network/networkInterfaces/join/action", + "Microsoft.Network/networkInterfaces/read", + "Microsoft.Network/networkInterfaces/write", + "Microsoft.Network/networkSecurityGroups/read", + "Microsoft.Network/networkSecurityGroups/write", + "Microsoft.Network/publicIPAddresses/delete", + "Microsoft.Network/publicIPAddresses/join/action", + "Microsoft.Network/publicIPAddresses/read", + "Microsoft.Network/publicIPAddresses/write", + "Microsoft.Network/publicIPPrefixes/join/action", + "Microsoft.Network/privatednszones/*", + "Microsoft.Network/routeTables/read", + "Microsoft.Network/routeTables/routes/delete", + "Microsoft.Network/routeTables/routes/read", + "Microsoft.Network/routeTables/routes/write", + "Microsoft.Network/routeTables/write", + "Microsoft.Network/virtualNetworks/read", + "Microsoft.Network/virtualNetworks/subnets/join/action", + "Microsoft.Network/virtualNetworks/subnets/read", + "Microsoft.Network/virtualNetworks/joinLoadBalancer/action", + "Microsoft.OperationalInsights/workspaces/sharedkeys/read", + "Microsoft.OperationalInsights/workspaces/read", + "Microsoft.OperationsManagement/solutions/write", + "Microsoft.OperationsManagement/solutions/read", + "Microsoft.Resources/subscriptions/resourcegroups/read", + "Microsoft.Resources/subscriptions/resourcegroups/write", + "Microsoft.Storage/operations/read", + "Microsoft.Storage/storageAccounts/listKeys/action", + "Microsoft.Storage/storageAccounts/delete", + "Microsoft.Storage/storageAccounts/read", + "Microsoft.Storage/storageAccounts/write" + ], + "NotActions": [], + "DataActions": [], + "NotDataActions": [], + "AssignableScopes": [ + "/subscriptions/SUBSCRIPTION_ID" + ] + } + EOF + ``` + +2. Apply the Rancher AKSv2 Role: + + ``` + az role definition create --role-definition rancher-azure.json + ``` + +3. Verify if the Rancher AKSv2 Role was created: + + ``` + az role definition list | grep "Rancher AKSv2" + ``` + +## Syncing + +The AKS provisioner can synchronize the state of an AKS cluster between Rancher and the provider. For an in-depth technical explanation of how this works, see [Syncing.](../../../../reference-guides/cluster-configuration/rancher-server-configuration/sync-clusters.md) + +For information on configuring the refresh interval, see [this section.](../../../../reference-guides/cluster-configuration/rancher-server-configuration/gke-cluster-configuration/gke-cluster-configuration.md#configuring-the-refresh-interval) + + +## Programmatically Creating AKS Clusters + +The most common way to programmatically deploy AKS clusters through Rancher is by using the Rancher2 Terraform provider. The documentation for creating clusters with Terraform is [here](https://registry.terraform.io/providers/rancher/rancher2/latest/docs/resources/cluster). diff --git a/versioned_docs/version-2.14/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-clusters-from-hosted-kubernetes-providers/eks.md b/versioned_docs/version-2.14/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-clusters-from-hosted-kubernetes-providers/eks.md new file mode 100644 index 00000000000..59a6efe3c1a --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-clusters-from-hosted-kubernetes-providers/eks.md @@ -0,0 +1,326 @@ +--- +title: Creating an EKS Cluster +--- + + + + + +Amazon EKS provides a managed control plane for your Kubernetes cluster. Amazon EKS runs the Kubernetes control plane instances across multiple Availability Zones to ensure high availability. Rancher provides an intuitive user interface for managing and deploying the Kubernetes clusters you run in Amazon EKS. With this guide, you will use Rancher to quickly and easily launch an Amazon EKS Kubernetes cluster in your AWS account. For more information on Amazon EKS, see this [documentation](https://docs.aws.amazon.com/eks/latest/userguide/what-is-eks.html). + + +## Prerequisites in Amazon Web Services + +:::caution + +Deploying to Amazon AWS will incur charges. For more information, refer to the [EKS pricing page](https://aws.amazon.com/eks/pricing/). + +::: + +To set up a cluster on EKS, you will need to set up an Amazon VPC (Virtual Private Cloud). You will also need to make sure that the account you will be using to create the EKS cluster has the appropriate [permissions.](#minimum-eks-permissions) For details, refer to the official guide on [Amazon EKS Prerequisites](https://docs.aws.amazon.com/eks/latest/userguide/getting-started-console.html#eks-prereqs). + +### Amazon VPC + +An Amazon VPC is required to launch the EKS cluster. The VPC enables you to launch AWS resources into a virtual network that you've defined. You can set one up yourself and provide it during cluster creation in Rancher. If you do not provide one during creation, Rancher will create one. For more information, refer to the [Tutorial: Creating a VPC with Public and Private Subnets for Your Amazon EKS Cluster](https://docs.aws.amazon.com/eks/latest/userguide/create-public-private-vpc.html). + +### IAM Policies + +Rancher needs access to your AWS account in order to provision and administer your Kubernetes clusters in Amazon EKS. You'll need to create a user for Rancher in your AWS account and define what that user can access. + +1. Create a user with programmatic access by following the steps [here](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users_create.html). + +2. Next, create an IAM policy that defines what this user has access to in your AWS account. It's important to only grant this user minimal access within your account. The minimum permissions required for an EKS cluster are listed [here.](#minimum-eks-permissions) Follow the steps [here](https://docs.aws.amazon.com/eks/latest/userguide/EKS_IAM_user_policies.html) to create an IAM policy and attach it to your user. + +3. Finally, follow the steps [here](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html#Using_CreateAccessKey) to create an access key and secret key for this user. + +:::note Important: + +It's important to regularly rotate your access and secret keys. See this [documentation](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html#rotating_access_keys_console) for more information. + +::: + +For more detailed information on IAM policies for EKS, refer to the official [documentation on Amazon EKS IAM Policies, Roles, and Permissions](https://docs.aws.amazon.com/eks/latest/userguide/IAM_policies.html). + + +## Create the EKS Cluster + +Use Rancher to set up and configure your Kubernetes cluster. + +1. Click **☰ > Cluster Management**. +1. On the **Clusters** page, click **Create**. +1. Choose **Amazon EKS**. +1. Enter a **Cluster Name**. +1. Use **Member Roles** to configure user authorization for the cluster. Click **Add Member** to add users that can access the cluster. Use the **Role** drop-down to set permissions for each user. +1. Fill out the rest of the form. For help, refer to the [configuration reference.](#eks-cluster-configuration-reference) +1. Click **Create**. + +**Result:** + +Your cluster is created and assigned a state of **Provisioning**. Rancher is standing up your cluster. + +You can access your cluster after its state is updated to **Active**. + +**Active** clusters are assigned two Projects: + +- `Default`, containing the `default` namespace +- `System`, containing the `cattle-system`, `ingress-nginx`, `kube-public`, and `kube-system` namespaces + +## EKS Cluster Configuration Reference + +For the full list of EKS cluster configuration options, see [this page.](../../../../reference-guides/cluster-configuration/rancher-server-configuration/eks-cluster-configuration.md) + +## Architecture + +The figure below illustrates the high-level architecture of Rancher 2.x. The figure depicts a Rancher Server installation that manages two Kubernetes clusters: one created by RKE and another created by EKS. + +
Managing Kubernetes Clusters through Rancher's Authentication Proxy
+ +![Architecture](/img/rancher-architecture-rancher-api-server.svg) + +## AWS Service Events + +To find information on any AWS Service events, please see [this page](https://status.aws.amazon.com/). + +## Security and Compliance + +By default only the IAM user or role that created a cluster has access to it. Attempting to access the cluster with any other user or role without additional configuration will lead to an error. In Rancher, this means using a credential that maps to a user or role that was not used to create the cluster will cause an unauthorized error. For example, an EKSCtl cluster will not register in Rancher unless the credentials used to register the cluster match the role or user used by EKSCtl. Additional users and roles can be authorized to access a cluster by being added to the aws-auth configmap in the kube-system namespace. For a more in-depth explanation and detailed instructions, please see this [documentation](https://aws.amazon.com/premiumsupport/knowledge-center/amazon-eks-cluster-access/). + +For more information on security and compliance with your Amazon EKS Kubernetes cluster, please see this [documentation](https://docs.aws.amazon.com/eks/latest/userguide/shared-responsibilty.html). + +## Tutorial + +This [tutorial](https://aws.amazon.com/blogs/opensource/managing-eks-clusters-rancher/) on the AWS Open Source Blog will walk you through how to set up an EKS cluster with Rancher, deploy a publicly accessible app to test the cluster, and deploy a sample project to track real-time geospatial data using a combination of other open-source software such as Grafana and InfluxDB. + +## Minimum EKS Permissions + +These are the minimum set of permissions necessary to access the full functionality of Rancher's EKS driver. These permissions allow Rancher to create the Service Role and Virtual Private Cloud (VPC) resources on the users' behalf, if necessary. + +:::note +In EKS v1.23 and above, you must use the out-of-tree drivers for EBS-backed volumes. You need [specific permissions](#ebs-csi-driver-addon-permissions) to enable this add-on. +::: + +Resource | Description +---------|------------ +EBS CSI Driver add-on | Provides permissions that allow Kubernetes to interact with EBS and configure the cluster to enable the add-on (required for EKS v1.23 and above). Rancher can install the add-on with the following [EBS CSI Driver addon Permissions](#ebs-csi-driver-addon-permissions). + + +Resource targeting uses `*` as the ARN of many of the resources created cannot be known before creating the EKS cluster in Rancher. + +```json +{ + "Version": "2012-10-17", + "Statement": [ + { + "Sid": "EC2Permissions", + "Effect": "Allow", + "Action": [ + "ec2:AuthorizeSecurityGroupEgress", + "ec2:AuthorizeSecurityGroupIngress", + "ec2:CreateKeyPair", + "ec2:CreateLaunchTemplate", + "ec2:CreateLaunchTemplateVersion", + "ec2:CreateSecurityGroup", + "ec2:CreateTags", + "ec2:DeleteKeyPair", + "ec2:DeleteLaunchTemplate", + "ec2:DeleteLaunchTemplateVersions", + "ec2:DeleteSecurityGroup", + "ec2:DeleteTags", + "ec2:DescribeAccountAttributes", + "ec2:DescribeAvailabilityZones", + "ec2:DescribeImages", + "ec2:DescribeInternetGateways", + "ec2:DescribeInstanceTypes", + "ec2:DescribeKeyPairs", + "ec2:DescribeLaunchTemplateVersions", + "ec2:DescribeLaunchTemplates", + "ec2:DescribeRegions", + "ec2:DescribeRouteTables", + "ec2:DescribeSecurityGroups", + "ec2:DescribeSubnets", + "ec2:DescribeTags", + "ec2:DescribeVpcs", + "ec2:RevokeSecurityGroupEgress", + "ec2:RevokeSecurityGroupIngress", + "ec2:RunInstances" + ], + "Resource": "*" + }, + { + "Sid": "CloudFormationPermissions", + "Effect": "Allow", + "Action": [ + "cloudformation:CreateStack", + "cloudformation:CreateStackSet", + "cloudformation:DeleteStack", + "cloudformation:DescribeStackResource", + "cloudformation:DescribeStackResources", + "cloudformation:DescribeStacks", + "cloudformation:ListStackResources", + "cloudformation:ListStacks" + ], + "Resource": "*" + }, + { + "Sid": "IAMPermissions", + "Effect": "Allow", + "Action": [ + "iam:AddRoleToInstanceProfile", + "iam:AttachRolePolicy", + "iam:CreateInstanceProfile", + "iam:CreateRole", + "iam:CreateServiceLinkedRole", + "iam:DeleteInstanceProfile", + "iam:DeleteRole", + "iam:DetachRolePolicy", + "iam:GetInstanceProfile", + "iam:GetRole", + "iam:ListAttachedRolePolicies", + "iam:ListInstanceProfiles", + "iam:ListInstanceProfilesForRole", + "iam:ListRoles", + "iam:ListRoleTags", + "iam:PassRole", + "iam:RemoveRoleFromInstanceProfile", + "iam:TagRole" + ], + "Resource": "*" + }, + { + "Sid": "KMSPermissions", + "Effect": "Allow", + "Action": "kms:ListKeys", + "Resource": "*" + }, + { + "Sid": "EKSPermissions", + "Effect": "Allow", + "Action": [ + "eks:CreateCluster", + "eks:CreateFargateProfile", + "eks:CreateNodegroup", + "eks:DeleteCluster", + "eks:DeleteFargateProfile", + "eks:DeleteNodegroup", + "eks:DescribeAddon", + "eks:DescribeCluster", + "eks:DescribeFargateProfile", + "eks:DescribeNodegroup", + "eks:DescribeUpdate", + "eks:ListClusters", + "eks:ListFargateProfiles", + "eks:ListNodegroups", + "eks:ListTagsForResource", + "eks:ListUpdates", + "eks:TagResource", + "eks:UntagResource", + "eks:UpdateClusterConfig", + "eks:UpdateClusterVersion", + "eks:UpdateNodegroupConfig", + "eks:UpdateNodegroupVersion" + ], + "Resource": "*" + }, + { + "Sid": "VPCPermissions", + "Effect": "Allow", + "Action": [ + "ec2:AssociateRouteTable", + "ec2:AttachInternetGateway", + "ec2:CreateInternetGateway", + "ec2:CreateRoute", + "ec2:CreateRouteTable", + "ec2:CreateSecurityGroup", + "ec2:CreateSubnet", + "ec2:CreateVpc", + "ec2:DeleteInternetGateway", + "ec2:DeleteRoute", + "ec2:DeleteRouteTable", + "ec2:DeleteSubnet", + "ec2:DeleteTags", + "ec2:DeleteVpc", + "ec2:DescribeVpcs", + "ec2:DetachInternetGateway", + "ec2:DisassociateRouteTable", + "ec2:ModifySubnetAttribute", + "ec2:ModifyVpcAttribute", + "ec2:ReplaceRoute" + ], + "Resource": "*" + } + ] +} +``` + +When you create an EKS cluster, Rancher creates a service role with the following trust policy: + +```json +{ + "Version": "2012-10-17", + "Statement": [ + { + "Action": "sts:AssumeRole", + "Principal": { + "Service": "eks.amazonaws.com" + }, + "Effect": "Allow", + "Sid": "" + } + ] +} +``` + +This role also has two role policy attachments with the following policies' ARNs: + +``` +arn:aws:iam::aws:policy/AmazonEKSClusterPolicy +arn:aws:iam::aws:policy/AmazonEKSServicePolicy +``` + +### EBS CSI Driver addon Permissions + +The following are the required permissions for installing the Amazon EBS CSI Driver add-on. + +```json +{ + "Version": "2012-10-17", + "Statement": [ + { + "Effect": "Allow", + "Action": [ + "eks:AssociateIdentityProviderConfig", + "eks:CreateAddon", + "eks:DeleteAddon", + "eks:DescribeAddonConfiguration", + "eks:DescribeAddonVersions", + "eks:DescribeIdentityProviderConfig", + "eks:ListAddons", + "eks:ListIdentityProviderConfigs", + "eks:UpdateAddon", + "iam:CreateOpenIDConnectProvider", + "iam:ListOpenIDConnectProviders", + "sts:AssumeRoleWithWebIdentity" + ], + "Resource": "*" + } + ] +} +``` + +## Syncing + +The EKS provisioner can synchronize the state of an EKS cluster between Rancher and the provider. For an in-depth technical explanation of how this works, see [Syncing.](../../../../reference-guides/cluster-configuration/rancher-server-configuration/sync-clusters.md) + +For information on configuring the refresh interval, refer to [this section.](../../../../reference-guides/cluster-configuration/rancher-server-configuration/eks-cluster-configuration.md#configuring-the-refresh-interval) + +## Troubleshooting + +If your changes were overwritten, it could be due to the way the cluster data is synced with EKS. Changes shouldn't be made to the cluster from another source, such as in the EKS console, and in Rancher within a five-minute span. For information on how this works and how to configure the refresh interval, refer to [Syncing.](#syncing) + +If an unauthorized error is returned while attempting to modify or register the cluster and the cluster was not created with the role or user that your credentials belong to, refer to [Security and Compliance.](#security-and-compliance) + +For any issues or troubleshooting details for your Amazon EKS Kubernetes cluster, please see this [documentation](https://docs.aws.amazon.com/eks/latest/userguide/troubleshooting.html). + +## Programmatically Creating EKS Clusters + +The most common way to programmatically deploy EKS clusters through Rancher is by using the Rancher2 Terraform provider. The documentation for creating clusters with Terraform is [here.](https://registry.terraform.io/providers/rancher/rancher2/latest/docs/resources/cluster) diff --git a/versioned_docs/version-2.14/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-clusters-from-hosted-kubernetes-providers/gke.md b/versioned_docs/version-2.14/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-clusters-from-hosted-kubernetes-providers/gke.md new file mode 100644 index 00000000000..287367362a8 --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-clusters-from-hosted-kubernetes-providers/gke.md @@ -0,0 +1,105 @@ +--- +title: Creating a GKE Cluster +--- + + + + + +## Prerequisites + +Some setup in Google Kubernetes Engine is required. + +### Service Account Token + +Create a service account using [Google Kubernetes Engine](https://console.cloud.google.com/projectselector/iam-admin/serviceaccounts). GKE uses this account to operate your cluster. Creating this account also generates a private key used for authentication. + +The service account requires the following roles: + +- **Compute Viewer:** `roles/compute.viewer` +- **Project Viewer:** `roles/viewer` +- **Kubernetes Engine Admin:** `roles/container.admin` +- **Service Account User:** `roles/iam.serviceAccountUser` + +[Google Documentation: Creating and Enabling Service Accounts](https://cloud.google.com/compute/docs/access/create-enable-service-accounts-for-instances) + +For help obtaining a private key for your service account, refer to the Google cloud documentation [here.](https://cloud.google.com/iam/docs/creating-managing-service-account-keys#creating_service_account_keys) You will need to save the key in JSON format. + +### Google Project ID + +Your cluster will need to be part of a Google Project. + +To create a new project, refer to the Google cloud documentation [here.](https://cloud.google.com/resource-manager/docs/creating-managing-projects#creating_a_project) + +To get the project ID of an existing project, refer to the Google cloud documentation [here.](https://cloud.google.com/resource-manager/docs/creating-managing-projects#identifying_projects) + +## Provisioning a GKE Cluster + +:::caution + +Deploying to GKE will incur charges. + +::: + +### 1. Create a Cloud Credential + +1. Click **☰ > Cluster Management**. +1. In the left navigation bar, click **Cloud Credentials**. +1. Click **Create**. +1. Enter a name for your Google cloud credentials. +1. In the **Service Account** text box, paste your service account private key JSON, or upload the JSON file. +1. Click **Create**. + +**Result:** You have created credentials that Rancher will use to provision the new GKE cluster. + +### 2. Create the GKE Cluster +Use Rancher to set up and configure your Kubernetes cluster. To successfully create a GKE cluster with Rancher, your GKE must be in Standard mode. GKE has two modes of operation when creating a Kubernetes cluster, Autopilot and Standard mode. The cluster configuration for Autopilot mode has restrictions on editing the kube-system namespace. However, Rancher needs to create resources in the kube-system namespace during installation. As a result, you will not be able to create a GKE cluster in Autopilot mode. For more information about the difference between GKE Autopilot mode and Standard mode, visit [Compare GKE Autopilot and Standard.](https://cloud.google.com/kubernetes-engine/docs/resources/autopilot-standard-feature-comparison) + + +1. Click **☰ > Cluster Management**. +1. On the **Clusters** page, click **Create**. +1. Click **Google GKE**. +1. Enter a **Cluster Name**. +1. Optional: Use **Member Roles** to configure user authorization for the cluster. Click **Add Member** to add users that can access the cluster. Use the **Role** drop-down to set permissions for each user. +1. Optional: Add Kubernetes [labels](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/) or [annotations](https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations/) to the cluster. +1. Enter your Google project ID and your Google cloud credentials. +1. Fill out the rest of the form. For help, refer to the [GKE cluster configuration reference.](../../../../reference-guides/cluster-configuration/rancher-server-configuration/gke-cluster-configuration/gke-cluster-configuration.md) +1. Click **Create**. + +**Result:** You have successfully deployed a GKE cluster. + +Your cluster is created and assigned a state of **Provisioning**. Rancher is standing up your cluster. + +You can access your cluster after its state is updated to **Active**. + +**Active** clusters are assigned two Projects: + +- `Default`, containing the `default` namespace +- `System`, containing the `cattle-system`, `ingress-nginx`, `kube-public`, and `kube-system` namespaces + +## Private Clusters + +Private GKE clusters are supported. Note: This advanced setup can require more steps during the cluster provisioning process. For details, see [this section.](../../../../reference-guides/cluster-configuration/rancher-server-configuration/gke-cluster-configuration/gke-private-clusters.md) + +## Configuration Reference + +For details on configuring GKE clusters in Rancher, see [this page.](../../../../reference-guides/cluster-configuration/rancher-server-configuration/gke-cluster-configuration/gke-cluster-configuration.md) +## Updating Kubernetes Version + +The Kubernetes version of a cluster can be upgraded to any version available in the region or zone for the GKE cluster. Upgrading the master Kubernetes version does not automatically upgrade worker nodes. Nodes can be upgraded independently. + +:::note + +GKE has removed basic authentication in 1.19+. In order to upgrade a cluster to 1.19+, basic authentication must be disabled in the Google Cloud. Otherwise, an error will appear in Rancher when an upgrade to 1.19+ is attempted. You can follow the [Google documentation](https://cloud.google.com/kubernetes-engine/docs/how-to/api-server-authentication#disabling_authentication_with_a_static_password). After this, the Kubernetes version can be updated to 1.19+ via Rancher. + +::: + +## Syncing + +The GKE provisioner can synchronize the state of a GKE cluster between Rancher and the provider. For an in-depth technical explanation of how this works, see [Syncing.](../../../../reference-guides/cluster-configuration/rancher-server-configuration/sync-clusters.md) + +For information on configuring the refresh interval, see [this section.](../../../../reference-guides/cluster-configuration/rancher-server-configuration/gke-cluster-configuration/gke-cluster-configuration.md#configuring-the-refresh-interval) + +## Programmatically Creating GKE Clusters + +The most common way to programmatically deploy GKE clusters through Rancher is by using the Rancher2 Terraform provider. The documentation for creating clusters with Terraform is [here.](https://registry.terraform.io/providers/rancher/rancher2/latest/docs/resources/cluster) diff --git a/versioned_docs/version-2.14/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-clusters-from-hosted-kubernetes-providers/set-up-clusters-from-hosted-kubernetes-providers.md b/versioned_docs/version-2.14/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-clusters-from-hosted-kubernetes-providers/set-up-clusters-from-hosted-kubernetes-providers.md new file mode 100644 index 00000000000..946906ae614 --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-clusters-from-hosted-kubernetes-providers/set-up-clusters-from-hosted-kubernetes-providers.md @@ -0,0 +1,27 @@ +--- +title: Setting up Clusters from Hosted Kubernetes Providers +--- + + + + + +In this scenario, Rancher does not provision Kubernetes because it is installed by providers such as Google Kubernetes Engine (GKE), Amazon Elastic Container Service for Kubernetes, or Azure Kubernetes Service. + +If you use a Kubernetes provider such as Google GKE, Rancher integrates with its cloud APIs, allowing you to create and manage role-based access control for the hosted cluster from the Rancher UI. + +In this use case, Rancher sends a request to a hosted provider using the provider's API. The provider then provisions and hosts the cluster for you. When the cluster finishes building, you can manage it from the Rancher UI along with clusters you've provisioned that are hosted on-prem or in an infrastructure provider. + +Rancher supports the following Kubernetes providers: + +- [Google GKE (Google Kubernetes Engine)](https://cloud.google.com/kubernetes-engine/) +- [Amazon EKS (Amazon Elastic Container Service for Kubernetes)](https://aws.amazon.com/eks/) +- [Microsoft AKS (Azure Kubernetes Service)](https://azure.microsoft.com/en-us/services/kubernetes-service/) + +## Hosted Kubernetes Provider Authentication + +When using Rancher to create a cluster hosted by a provider, you are prompted for authentication information. This information is required to access the provider's API. For more information on how to obtain this information, see the following procedures: + +- [Creating a GKE Cluster](gke.md) +- [Creating an EKS Cluster](eks.md) +- [Creating an AKS Cluster](aks.md) diff --git a/versioned_docs/version-2.14/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/use-windows-clusters/azure-storageclass-configuration.md b/versioned_docs/version-2.14/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/use-windows-clusters/azure-storageclass-configuration.md new file mode 100644 index 00000000000..735ff6472be --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/use-windows-clusters/azure-storageclass-configuration.md @@ -0,0 +1,45 @@ +--- +title: Configuring Storage Classes in Azure +--- + + + + + +If you are using Azure VMs for your nodes, you can use [Azure files](https://docs.microsoft.com/en-us/azure/aks/azure-files-dynamic-pv) as a StorageClass for the cluster. + +In order to have the Azure platform create the required storage resources, follow these steps: + +1. [Configure the Azure cloud provider.](../../kubernetes-clusters-in-rancher-setup/set-up-cloud-providers/azure.md) +1. Configure `kubectl` to connect to your cluster. +1. Copy the `ClusterRole` and `ClusterRoleBinding` manifest for the service account: + ```yml + --- + apiVersion: rbac.authorization.k8s.io/v1 + kind: ClusterRole + metadata: + name: system:azure-cloud-provider + rules: + - apiGroups: [''] + resources: ['secrets'] + verbs: ['get','create'] + --- + apiVersion: rbac.authorization.k8s.io/v1 + kind: ClusterRoleBinding + metadata: + name: system:azure-cloud-provider + roleRef: + kind: ClusterRole + apiGroup: rbac.authorization.k8s.io + name: system:azure-cloud-provider + subjects: + - kind: ServiceAccount + name: persistent-volume-binder + namespace: kube-system + ``` + +1. Create these in your cluster using one of the follow command. + + ``` + # kubectl create -f + ``` diff --git a/versioned_docs/version-2.14/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/use-windows-clusters/network-requirements-for-host-gateway.md b/versioned_docs/version-2.14/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/use-windows-clusters/network-requirements-for-host-gateway.md new file mode 100644 index 00000000000..65596651f3f --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/use-windows-clusters/network-requirements-for-host-gateway.md @@ -0,0 +1,40 @@ +--- +title: Networking Requirements for Host Gateway (L2bridge) +--- + + + + + +This section describes how to configure custom Windows clusters that are using *Host Gateway (L2bridge)* mode. + +### Disabling Private IP Address Checks + +If you are using *Host Gateway (L2bridge)* mode and hosting your nodes on any of the cloud services listed below, you must disable the private IP address checks for both your Linux or Windows hosts on startup. To disable this check for each node, follow the directions provided by each service below. + +Service | Directions to disable private IP address checks +--------|------------------------------------------------ +Amazon EC2 | [Disabling Source/Destination Checks](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_NAT_Instance.html#EIP_Disable_SrcDestCheck) +Google GCE | [Enabling IP Forwarding for Instances](https://cloud.google.com/vpc/docs/using-routes#canipforward) (By default, a VM cannot forward a packet originated by another VM) +Azure VM | [Enable or Disable IP Forwarding](https://docs.microsoft.com/en-us/azure/virtual-network/virtual-network-network-interface#enable-or-disable-ip-forwarding) + +### Cloud-hosted VM Routes Configuration + +If you are using the [**Host Gateway (L2bridge)**](https://github.com/coreos/flannel/blob/master/Documentation/backends.md#host-gw) backend of Flannel, all containers on the same node belong to a private subnet, and traffic routes from a subnet on one node to a subnet on another node through the host network. + +- When worker nodes are provisioned on AWS, virtualization clusters, or bare metal servers, make sure they belong to the same layer 2 subnet. If the nodes don't belong to the same layer 2 subnet, `host-gw` networking will not work. + +- When worker nodes are provisioned on GCE or Azure, they are not on the same layer 2 subnet. Nodes on GCE and Azure belong to a routable layer 3 network. Follow the instructions below to configure GCE and Azure so that the cloud network knows how to route the host subnets on each node. + +To configure host subnet routing on GCE or Azure, first run the following command to find out the host subnets on each worker node: + +```bash +kubectl get nodes -o custom-columns=nodeName:.metadata.name,nodeIP:status.addresses[0].address,routeDestination:.spec.podCIDR +``` + +Then follow the instructions for each cloud provider to configure routing rules for each node: + +Service | Instructions +--------|------------- +Google GCE | For GCE, add a static route for each node: [Adding a Static Route](https://cloud.google.com/vpc/docs/using-routes#addingroute). +Azure VM | For Azure, create a routing table: [Custom Routes: User-defined](https://docs.microsoft.com/en-us/azure/virtual-network/virtual-networks-udr-overview#user-defined). diff --git a/versioned_docs/version-2.14/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/use-windows-clusters/use-windows-clusters.md b/versioned_docs/version-2.14/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/use-windows-clusters/use-windows-clusters.md new file mode 100644 index 00000000000..0225b40c65e --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/use-windows-clusters/use-windows-clusters.md @@ -0,0 +1,249 @@ +--- +title: Launching Kubernetes on Windows Clusters +--- + + + + + +When provisioning a [custom cluster](../../../../reference-guides/cluster-configuration/rancher-server-configuration/use-existing-nodes/use-existing-nodes.md) Rancher uses RKE2 to install Kubernetes on your existing nodes. + +In a Windows cluster provisioned with Rancher, the cluster must contain both Linux and Windows nodes. The Kubernetes controlplane can only run on Linux nodes, and the Windows nodes can only have the worker role. Windows nodes can only be used for deploying workloads. + +For a summary of Kubernetes features supported in Windows, see the Kubernetes documentation on [supported functionality and limitations for using Kubernetes with Windows](https://kubernetes.io/docs/setup/production-environment/windows/intro-windows-in-kubernetes/#supported-functionality-and-limitations) or the [guide for scheduling Windows containers in Kubernetes](https://kubernetes.io/docs/setup/production-environment/windows/user-guide-windows-containers/). + +### RKE2 Features for Windows Clusters + +Listed below are the primary RKE2 features for Windows cluster provisioning: + +- Windows Containers with RKE2 powered by containerd +- Added provisioning of Windows RKE2 custom clusters directly from the Rancher UI +- Calico and Flannel CNI for Windows RKE2 custom clusters +- SAC releases of Windows Server (2004 and 20H2) are included in the technical preview + +:::note + +Rancher will allow Windows workload pods to deploy on both Windows and Linux worker nodes by default. When creating mixed clusters in RKE2, you must edit the `nodeSelector` in the chart to direct the pods to be placed onto a compatible Windows node. Refer to the [Kubernetes documentation](https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node/#nodeselector) for more information on how to use `nodeSelector` to assign pods to nodes. + +::: + +- HostProcess containers in Windows RKE2 are supported in Kubernetes v1.24.1 and up. See [the upstream documentation](https://kubernetes.io/docs/tasks/configure-pod-container/create-hostprocess-pod/) for more information. + +## General Requirements + +The general networking and operating system requirements for Windows nodes are the same as for other [Rancher installations](../../../../getting-started/installation-and-upgrade/installation-requirements/installation-requirements.md). + +### OS Requirements + +Our support for Windows Server and Windows containers match the Microsoft official lifecycle for LTSC (Long-Term Servicing Channel) and SAC (Semi-Annual Channel). + +For the support lifecycle dates for Windows Server, see the [Microsoft Documentation.](https://docs.microsoft.com/en-us/windows-server/get-started/windows-server-release-info) + +### Kubernetes Version + +For more information regarding Kubernetes component versions, see the [support matrices for RKE2 versions](https://www.suse.com/suse-rke2/support-matrix/all-supported-versions/). + +### Node Requirements + +The hosts in the cluster need to have at least: + +- 2 core CPUs +- 5 GB memory +- 50 GB disk space + +Rancher will not provision the node if the node does not meet these requirements. + +### Networking Requirements + +Before provisioning a new cluster, be sure that you have already installed Rancher on a device that accepts inbound network traffic. This is required in order for the cluster nodes to communicate with Rancher. If you have not already installed Rancher, please refer to the [installation documentation](../../../../getting-started/installation-and-upgrade/installation-and-upgrade.md) before proceeding with this guide. + +Rancher supports Windows using Calico and Flannel as network providers. + +If you are configuring DHCP options sets for an AWS virtual private cloud, note that in the `domain-name` option field, only one domain name can be specified. According to the DHCP options [documentation:](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_DHCP_Options.html) + +:::note + +Some Linux operating systems accept multiple domain names separated by spaces. However, other Linux operating systems and Windows treat the value as a single domain, which results in unexpected behavior. If your DHCP options set is associated with a VPC that has instances with multiple operating systems, specify only one domain name. + +::: + +### Rancher on VMware vSphere with ESXi 6.7u2 and above + +If you are using Rancher on VMware vSphere with ESXi 6.7u2 or later with Red Hat Enterprise Linux 8.3, CentOS 8.3, or SUSE Enterprise Linux 15 SP2 or later, it is necessary to disable the `vmxnet3` virtual network adapter hardware offloading feature. Failure to do so will result in all network connections between pods on different cluster nodes to fail with timeout errors. All connections from Windows pods to critical services running on Linux nodes, such as CoreDNS, will fail as well. It is also possible that external connections may fail. This issue is the result of Linux distributions enabling the hardware offloading feature in `vmxnet3` and a bug in the `vmxnet3` hardware offloading feature that results in the discarding of packets for guest overlay traffic. To address this issue, it is necessary disable the `vmxnet3` hardware offloading feature. This setting does not survive reboot, so it is necessary to disable on every boot. The recommended course of action is to create a systemd unit file at `/etc/systemd/system/disable_hw_offloading.service`, which disables the `vmxnet3` hardware offloading feature on boot. A sample systemd unit file which disables the `vmxnet3` hardware offloading feature is as follows. Note that `` must be customized to the host `vmxnet3` network interface, e.g., `ens192`: + +``` +[Unit] +Description=Disable vmxnet3 hardware offloading feature + +[Service] +Type=oneshot +ExecStart=ethtool -K tx-udp_tnl-segmentation off +ExecStart=ethtool -K tx-udp_tnl-csum-segmentation off +StandardOutput=journal + +[Install] +WantedBy=multi-user.target +``` +Then set the appropriate permissions on the systemd unit file: +``` +chmod 0644 /etc/systemd/system/disable_hw_offloading.service +``` +Finally, enable the systemd service: +``` +systemctl enable disable_hw_offloading.service +``` + +### Architecture Requirements + +The Kubernetes cluster management nodes (`etcd` and `controlplane`) must be run on Linux nodes. + +The `worker` nodes, which is where your workloads will be deployed on, will typically be Windows nodes, but there must be at least one `worker` node that is run on Linux in order to run the Rancher cluster agent, DNS, metrics server, and Ingress related containers. + +#### Recommended Architecture + +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 required, version 2022 recommended) | Worker | Run your Windows containers | + +### Container Requirements + +Windows requires that containers must be built on the same Windows Server version that they are being deployed on. Therefore, containers must be built on Windows Server core version 1809 or above. If you have existing containers built for an earlier Windows Server core version, they must be re-built on Windows Server core version 1809 or above. + +### Cloud Provider Specific Requirements + +If you set a Kubernetes cloud provider in your cluster, some additional steps are required. You may wish to setup a cloud provider to leverage capabilities to automatically provision storage, load balancers, or other infrastructure for your cluster. Refer to [this page](../set-up-cloud-providers/set-up-cloud-providers.md) for details on how to configure a cloud provider cluster of nodes that meet the prerequisites. + +If you are using the GCE (Google Compute Engine) cloud provider, you must do the following: + +- Enable the GCE cloud provider in the `cluster.yml` by following [these steps.](../set-up-cloud-providers/google-compute-engine.md) +- When provisioning the cluster in Rancher, choose **Custom cloud provider** as the cloud provider in the Rancher UI. + +## Tutorial: How to Create a Cluster with Windows Support + +This tutorial describes how to create a Rancher-provisioned cluster with the three nodes in the [recommended architecture.](#recommended-architecture) + +To set up a cluster with support for Windows nodes and containers, you will need to complete the tasks below. + +### 1. Provision Hosts + +To begin provisioning a cluster on existing nodes with Windows support, prepare your hosts. + +Your hosts can be: + +- Cloud-hosted VMs +- VMs from virtualization clusters +- Bare-metal servers + +You will provision three nodes: + +- 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, 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) + +### 2. Create the Cluster on Existing Nodes + +The instructions for creating a Windows cluster on existing nodes are very similar to the general [instructions for creating a custom cluster](../../../../reference-guides/cluster-configuration/rancher-server-configuration/use-existing-nodes/use-existing-nodes.md) with some Windows-specific requirements. + +1. In the upper left corner, click **☰ > Cluster Management**. +1. On the **Clusters** page, click **Create**. +1. Click **Custom**. +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 **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 system agent and allow Rancher to manage each node. + +#### Add Linux Master Node + +In this section, we fill out a form on the Rancher UI to get a custom command to install the Rancher agent on the Linux master node. Then we will copy the command and run it on our Linux master node to register the node in the cluster. + +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 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. + +**Results:** + +Your cluster is created and assigned a state of **Updating**. Rancher is standing up your cluster. + +It may take a few minutes for the node to register and appear under the **Machines** tab. + +You’ll be able to access the cluster once its state changes to **Active**. + +#### Add Linux Worker Node + +In this section, we run a command to register the Linux worker node to the cluster. + +After the initial provisioning of your cluster, your cluster only has a single Linux host. Add another Linux `worker` host to support the _Rancher cluster agent_, _Metrics server_, _DNS_ and _Ingress_ for your cluster. + +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**, 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. + +**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 + +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` | + +::: + +#### Add a Windows Worker Node + +In this section, we run a command to register the Windows worker node to the cluster. + +:::note +The registration command to add the Windows workers only appears after the cluster is running with Linux etcd, control plane, and worker nodes. +::: + +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**, 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 **PowerShell Console** as an Administrator. +1. Optional: Repeat these instructions if you want to add more Windows nodes to your 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 + +After creating your cluster, you can access it through the Rancher UI. As a best practice, we recommend setting up these alternate ways of accessing your cluster: + +- **Access your cluster with the kubectl CLI:** Follow [these steps](../../manage-clusters/access-clusters/use-kubectl-and-kubeconfig.md#accessing-clusters-with-kubectl-from-your-workstation) to access clusters with kubectl on your workstation. In this case, you will be authenticated through the Rancher server’s authentication proxy, then Rancher will connect you to the downstream cluster. This method lets you manage the cluster without the Rancher UI. +- **Access your cluster with the kubectl CLI, using the authorized cluster endpoint:** Follow [these steps](../../manage-clusters/access-clusters/use-kubectl-and-kubeconfig.md#authenticating-directly-with-a-downstream-cluster) to access your cluster with kubectl directly, without authenticating through the Rancher server. We recommend setting up this alternative method to access your cluster so that in case you can’t connect to Rancher, you can still access the cluster. + +## Configuration for Storage Classes in Azure + +If you are using Azure VMs for your nodes, you can use [Azure files](https://docs.microsoft.com/en-us/azure/aks/azure-files-dynamic-pv) as a StorageClass for the cluster. For details, refer to [this section.](azure-storageclass-configuration.md) diff --git a/versioned_docs/version-2.14/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/use-windows-clusters/windows-linux-cluster-feature-parity.md b/versioned_docs/version-2.14/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/use-windows-clusters/windows-linux-cluster-feature-parity.md new file mode 100644 index 00000000000..7999a11defc --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/use-windows-clusters/windows-linux-cluster-feature-parity.md @@ -0,0 +1,46 @@ +--- +title: Windows and Linux Cluster Feature Parity +--- + + + + + +Windows clusters do not share the same feature support as Linux clusters. + +The following chart describes the feature parity between Windows and Linux on Rancher: + +**Component** | **Linux** | **Windows** +--- | --- | --- +**Distributions** | | +RKE | Supported | Supported +RKE2 | Supported | Supported +K3S | Supported | Not Supported +EKS | Supported | Not Supported +GKE | Supported | Not Supported +AKS | Supported | Not Supported +**Rancher Components** | | +Server | Supported | Not Supported +Agent | Supported | Supported +Fleet | Supported | Supported +EKS Operator | Supported | Not Supported +AKS Operator | Not Supported | Not Supported +GKE Operator | Not Supported | Not Supported +Monitoring/Alerting v2 | Supported | Supported +Logging v2 | Supported | Supported +Istio | Supported | Not Supported +Catalog v2 | Supported | Not Supported +OPA | Supported | Not Supported +Longhorn | Supported | Not Supported +CIS Scans | Supported | Not Supported +Backup/Restore Operator | Supported | Not Supported +**CNI / Add-ons** | | +Flannel | Supported | Supported +Canal | Supported | Not Supported +Calico | Supported | Supported (RKE2 Only) +Cilium | Supported | Not Supported +Multus | Supported | Not Supported +Traefik | Supported | Not Supported +NGINX Ingress | Supported | Not Supported + +For updated information on feature support, you may visit [rancher/windows](https://github.com/rancher/windows) on GitHub. diff --git a/versioned_docs/version-2.14/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/use-windows-clusters/workload-migration-guidance.md b/versioned_docs/version-2.14/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/use-windows-clusters/workload-migration-guidance.md new file mode 100644 index 00000000000..66e8c274ee5 --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/use-windows-clusters/workload-migration-guidance.md @@ -0,0 +1,307 @@ +--- +title: RKE1 to RKE2 Windows Migration Guidance +--- + + + + + +**Caution:** The contents of this document are not covered under SLA by Rancher Support. Please proceed with caution. + +This document covers how end users can migrate their Windows workloads from RKE1 to RKE2. + +## RKE1 Windows Scheduling + +RKE1 Windows workload scheduling is based on taints and tolerations. + +Every Linux node in an RKE1 Windows cluster, regardless of the role assigned to it, will have have a default taint that prevents workloads to be scheduled on it unless the workload has a toleration configured. This is a major design feature for RKE1 Windows clusters which were designed to only run Windows workloads. + +- Default RKE1 Linux node `NoSchedule` taint: + +```yml +apiVersion: v1 +kind: Node +spec: + ... + taints: + - effect: NoSchedule + key: cattle.io/os + value: linux +``` +
+ +- RKE1 Linux `NoSchedule` toleration for workloads + +The following toleration would allow an end-user workload to schedule on any Linux node of an RKE1 Windows cluster. These tolerations are used for various core Rancher services and workloads. + +```yml +apiVersion: apps/v1 +kind: Deployment +spec: + ... + template: + ... + spec: + tolerations: + - effect: NoSchedule + key: cattle.io/os + operator: Equal + value: linux +``` +
+ +- Aligning with best practices, any end-user workloads being run on Linux nodes would be scheduled on those with the worker role only: + +```yml +apiVersion: apps/v1 +kind: Deployment +spec: + ... + template: + ... + spec: + tolerations: + - effect: NoSchedule + key: cattle.io/os + operator: Equal + value: linux + affinity: + nodeAffinity: + requiredDuringSchedulingIgnoredDuringExecution: + - preference: + matchExpressions: + - key: node-role.kubernetes.io/worker + operator: In + values: + - "true" + weight: 100 + ... +``` + +## RKE2 Windows Scheduling + +Based on feedback and requests for hybrid workload support, RKE2 Windows was designed to support both Linux and Windows workloads by default. RKE2 scheduling relies on node selectors by default. This is a marked change from RKE1 as taints and tolerations were not incorporated into RKE2. Node selectors were a critical part of RKE1 Windows clusters, which makes for an easy migration of your workloads. + +## Example Migrations + +### RKE1 to RKE2 Windows Workload + +- Pre-migration RKE1 Windows deployment: + +```yaml +apiVersion: apps/v1 +kind: Deployment +spec: + ... + template: + ... + spec: + affinity: + nodeAffinity: + requiredDuringSchedulingIgnoredDuringExecution: + nodeSelectorTerms: + - matchExpressions: + - key: kubernetes.io/os + operator: NotIn + values: + - linux +``` +
+ +- Migrated RKE2 Windows deployment using `NodeAffinity`: + +```yaml +apiVersion: apps/v1 +kind: Deployment +... +spec: + ... + template: + ... + spec: + ... + affinity: + nodeAffinity: + requiredDuringSchedulingIgnoredDuringExecution: + nodeSelectorTerms: + - matchExpressions: + - key: kubernetes.io/os + operator: In + values: + - windows +``` + +### RKE1 Windows Cluster Linux-Only Deployment + +>**Important:** When leveraging node selectors and node affinity, note the following: +> +>- If both `nodeSelector` and `nodeAffinity` are specified, both must be satisfied for the `Pod` to be scheduled onto a node. +>- If you specify multiple `matchExpressions` associated with a single `nodeSelectorTerms`, then the `Pod` can be scheduled onto a node only if all the `matchExpressions` are satisfied. + +
+ +- Pre-migration RKE1 Windows cluster Linux-only deployment targeting RKE1 Linux worker nodes: + +```yml +apiVersion: apps/v1 +kind: Deployment +spec: + ... + template: + ... + spec: + tolerations: + - effect: NoSchedule + key: cattle.io/os + operator: Equal + value: linux + affinity: + nodeAffinity: + requiredDuringSchedulingIgnoredDuringExecution: + - weight: 100 + preference: + matchExpressions: + - key: node-role.kubernetes.io/worker + operator: In + values: + - "true" + +``` +
+ +- Migrated RKE2 hybrid cluster Linux-only deployment targeting RKE2 Linux worker nodes using node selectors: + +```yml +apiVersion: apps/v1 +kind: Deployment +spec: + ... + template: + ... + spec: + nodeSelector: + kubernetes.io/os: "linux" + node-role.kubernetes.io/worker: "true" + ``` +
+ +- Migrated RKE2 hybrid cluster Linux-only deployment targeting RKE2 Linux worker nodes using node affinity: + + ```yaml + apiVersion: apps/v1 +kind: Deployment +spec: + ... + template: + ... + spec: + affinity: + nodeAffinity: + requiredDuringSchedulingIgnoredDuringExecution: + - weight: 100 + preference: + matchExpressions: + - key: node-role.kubernetes.io/worker + operator: In + values: + - "true" + nodeSelectorTerms: + - matchExpressions: + - key: kubernetes.io/os + operator: In + values: + - linux + ``` +## RKE1 Windows-Supported Windows Server Versions + +### Long-Term Servicing Channel (LTSC) + +- Windows Server 2019 LTSC ✅ Will reach Mainstream EOL on Jan 9, 2024 and Extended EOL on Jan 9, 2029 + +### Semi-Annual Channel (SAC) + +- Windows Server 20H2 SAC ❌ EOL Reached on Aug 9, 2022 +- Windows Server 2004 SAC ❌ EOL Reached on Dec 14, 2021 +- Windows Server 1909 SAC ❌ EOL Reached on May 11, 2021 +- Windows Server 1903 SAC ❌ EOL Reached on Dec 8, 2020 +- Windows Server 1809 SAC ❌ EOL Reached on Nov 10, 2020 + +## RKE2 Windows-Supported Windows Server Versions + +### Long-Term Servicing Channel in RKE2 + +- Windows Server 2019 LTSC ✅ Will reach Mainstream EOL on Jan 9, 2024 and Extended EOL on Jan 9, 2029 +- Windows Server 2022 LTSC ✅ Will reach Mainstream EOL on Oct 13, 2026 and Extended EOL on Oct 13, 2031 + +>**Note:** SAC is not supported in RKE2. + + +For more information, please see the following references: + +- [Windows Server SAC Lifecycle](https://docs.microsoft.com/en-us/lifecycle/products/windows-server) + +- [Windows Server 2022 LTSC Lifecycle](https://docs.microsoft.com/en-us/lifecycle/products/windows-server-2022) + +- [Windows Server 2019 LTSC Lifecycle](https://docs.microsoft.com/en-us/lifecycle/products/windows-server-2019) + + +## Kubernetes Version Support + +>**Note:** All versions listed below are SLA Supported per the [Rancher v2.6.7 Support Matrix](https://www.suse.com/suse-rancher/support-matrix/all-supported-versions/rancher-v2-6-7/). Any version not listed should be assumed as being EOL and not supported under SLA by SUSE. + +### Rancher 2.5 vs. Rancher 2.6 Support Matrix for Windows Clusters + +**RKE1 vs. RKE2 Windows cluster-supported Kubernetes versions:** + +| Kubernetes Versions | RKE1 | RKE2 | +|-------------- |:----: |:----: | +| 1.18 | ✓ | | +| 1.19 | ✓ | | +| 1.20 | ✓ | | +| 1.21 | ✓ | | +| 1.22 | ✓ | ✓ | +| 1.23 | | ✓ | +| 1.24 | | ✓ | +| 1.25+ | | ✓ | + + +### Rancher 2.5 vs. Rancher 2.6 Supported Kubernetes Versions for Provisioning RKE1 and RKE2 Windows Clusters + +| Rancher Versions | Kubernetes Versions | RKE1 | RKE2 | +|:-----------------------: |:------------------------: |:----: |:----: | +| 2.5 - RKE1 Provisioning | 1.18 1.19 1.20 | ✓ | | +| 2.6 - RKE1 Provisioning | 1.18 1.19 1.20 1.21 1.22 | ✓ | | +| 2.6 - RKE2 Provisioning | 1.22 1.23 1.24 1.25+ | | ✓ | + + +## Guiding Migrations of Workloads to RKE2 Windows + +Referencing the tables in [Rancher 2.5 vs. Rancher 2.6 Support Matrix for Windows Clusters](#rancher-25-vs-rancher-26-support-matrix-for-windows-clusters) and [Rancher 2.5 vs. Rancher 2.6 Supported Kubernetes Versions for Provisioning RKE1 and RKE2 Windows Clusters](#rancher-25-vs-rancher-26-supported-kubernetes-versions-for-provisioning-rke1-and-rke2-windows-clusters), you will find the overlap in Kubernetes versions between RKE1 and RKE2 occurs in 1.22. This will be the base version required to migrate RKE1 Windows workloads when following the Rancher recommended approach. + +### In-Place Upgrade of Rancher 2.5 + +1. Upgrade the Rancher version to v2.6.5+. +1. Upgrade the RKE1 Windows downstream cluster(s) to RKE1 v1.22 using the latest available patch version. +1. Provision a new RKE2 Windows downstream cluster using RKE2 v1.22 using the matching patch version that the RKE1 Windows cluster is at. +1. Begin the migration of the Windows workloads from RKE1 to RKE2 clusters. +1. Perform validation tests to ensure that there has been no functionality loss or change when migrating your application from RKE1 to RKE2. +1. After successful validation tests have occurred, you can opt to upgrade your RKE2 1.22.x cluster to a new minor version such as 1.23 or 1.24. + + +### Migrating Windows Workloads to a New Rancher Environment + +>**Important:** To perform either of the following options requires Rancher v2.6.5 or above. + +**When using matching Kubernetes patch versions for RKE1 and RKE2:** + +1. Provision a new RKE2 Windows downstream cluster using RKE2 v1.22 using the matching patch version that the RKE1 Windows cluster is at. +1. Begin the migration of the Windows workloads from RKE1 to RKE2 clusters. +1. Perform validation tests to ensure that there has been no functionality loss or change when migrating your application from RKE1 to RKE2. +1. After successful validation tests have occurred, you can opt to upgrade your RKE2 1.22.x cluster to a new minor version such as 1.23 or 1.24. + + +**When using a newer Kubernetes patch version for RKE2:** + +1. Provision a new RKE2 Windows downstream cluster using RKE2 v1.23 or v1.24. +1. Begin the migration of the Windows workloads from RKE1 to RKE2 clusters. +1. Perform validation tests to ensure that there has been no functionality loss or change when migrating your application from RKE1 to RKE2. \ No newline at end of file diff --git a/versioned_docs/version-2.14/how-to-guides/new-user-guides/kubernetes-resources-setup/configmaps.md b/versioned_docs/version-2.14/how-to-guides/new-user-guides/kubernetes-resources-setup/configmaps.md new file mode 100644 index 00000000000..097a4d26e34 --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/new-user-guides/kubernetes-resources-setup/configmaps.md @@ -0,0 +1,39 @@ +--- +title: ConfigMaps +--- + + + + + +While most types of Kubernetes secrets store sensitive information, [ConfigMaps](https://kubernetes.io/docs/tasks/configure-pod-container/configure-pod-configmap/) store general configuration information, such as a group of config files. Because ConfigMaps don't store sensitive information, they can be updated automatically, and therefore don't require their containers to be restarted following update (unlike most secret types, which require manual updates and a container restart to take effect). + +ConfigMaps accept key value pairs in common string formats, like config files or JSON blobs. After you upload a config map, any workload can reference it as either an environment variable or a volume mount. + +1. In the upper left corner, click **☰ > Cluster Management**. +1. Go to the cluster that has the workload that should reference a ConfigMap and click **Explore**. +1. In the left navigation bar, click **More Resources > Core > ConfigMaps**. +1. Click **Create**. +1. Enter a **Name** for the Config Map. + + :::note + + Kubernetes classifies ConfigMaps as [secrets](https://kubernetes.io/docs/concepts/configuration/secret/), and no two secrets in a project or namespace can have duplicate names. Therefore, to prevent conflicts, your ConfigMaps must have a unique name among the other certificates, registries, and secrets within your workspace. + + ::: + +1. Select the **Namespace** you want to add Config Map to. + +1. On the **Data** tab, add a key-value pair to your ConfigMap. Add as many values as you need. You can add multiple key value pairs to the ConfigMap by copying and pasting. Alternatively, use **Read from File** to add the data. Note: If you need to store sensitive data, [use a secret](secrets.md), not a ConfigMap. +1. Click **Create**. + +**Result:** Your ConfigMap is added to the namespace. You can view it in the Rancher UI from the **Resources > Config Maps** view. + +## What's Next? + +Now that you have a ConfigMap added to a namespace, you can add it to a workload that you deploy from the namespace of origin. You can use the ConfigMap to specify information for you application to consume, such as: + +- Application environment variables. +- Specifying parameters for a Volume mounted to the workload. + +For more information on adding ConfigMaps to a workload, see [Deploying Workloads](workloads-and-pods/deploy-workloads.md). diff --git a/versioned_docs/version-2.14/how-to-guides/new-user-guides/kubernetes-resources-setup/create-services.md b/versioned_docs/version-2.14/how-to-guides/new-user-guides/kubernetes-resources-setup/create-services.md new file mode 100644 index 00000000000..5415a75ca9c --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/new-user-guides/kubernetes-resources-setup/create-services.md @@ -0,0 +1,33 @@ +--- +title: Services +--- + + + + + +Pod configuration is managed by Deployments, StatefulSets and Daemonsets, whereas services direct traffic to pods using selectors. + +For every workload (with at least one port configured) created, a complementing Service Discovery entry is created. This Service Discovery entry enables DNS resolution for the workload's pods using the following naming convention: +`..svc.cluster.local`. + +You can create additional services so that a given namespace resolves with one or more external IP addresses, an external hostname, an alias to another DNS record, other workloads, or a set of pods that match a selector that you create. + +1. In the upper left corner, click **☰ > Cluster Management**. +1. Go to the cluster where you want to add a service and click **Explore**. +1. Click **Service Discovery > Services**. +1. Click **Create**. +1. Choose the type of service you want to create. +1. Select a **Namespace** from the drop-down list. +1. Enter a **Name** for the service. This name is used for DNS resolution. +1. Fill out the rest of the form. For help, refer to the upstream Kubernetes documentation about [services.](https://kubernetes.io/docs/concepts/services-networking/service/) +1. Click **Create**. + +**Result:** A new service is created. + +- You can view the record by from the project's **Service Discovery** tab. +- When you visit the new DNS name for the new record that you created (`..svc.cluster.local`), it resolves the chosen namespace. + +## Related Links + +- [Adding entries to Pod /etc/hosts with HostAliases](https://kubernetes.io/docs/concepts/services-networking/add-entries-to-pod-etc-hosts-with-host-aliases/) diff --git a/versioned_docs/version-2.14/how-to-guides/new-user-guides/kubernetes-resources-setup/encrypt-http-communication.md b/versioned_docs/version-2.14/how-to-guides/new-user-guides/kubernetes-resources-setup/encrypt-http-communication.md new file mode 100644 index 00000000000..27f41079923 --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/new-user-guides/kubernetes-resources-setup/encrypt-http-communication.md @@ -0,0 +1,42 @@ +--- +title: Encrypting HTTP Communication +description: Learn how to add an SSL (Secure Sockets Layer) certificate or TLS (Transport Layer Security) certificate +--- + + + + + +When you create an ingress within Rancher/Kubernetes, you must provide it with a secret that includes a TLS private key and certificate, which are used to encrypt and decrypt communications that come through the ingress. You can make certificates available for ingress use by adding the certificate to the ingress deployment. + +:::note Prerequisite: + +You must have a TLS private key and certificate available to upload. + +::: + +### 1. Create a Secret + + +1. In the upper left corner, click **☰ > Cluster Management**. +1. Go to the cluster where you want to deploy your ingress and click **More Resources > Core > Secrets**. +1. Click **Create**. +1. Click **TLS Certificate**. +1. Enter a name for the secret. Note: Your secret must have a unique name among the other certificates, registries, and secrets within your project/workspace. +1. In the **Private Key** field, either copy and paste your certificate's private key into the text box (include the header and footer), or click **Read from a file** to browse to the private key on your file system. If possible, we recommend using **Read from a file** to reduce likelihood of error. Note: Private key files end with an extension of `.key`. +1. In the **Certificate** field, either copy and paste your certificate into the text box (include the header and footer), or click **Read from a file** to browse to the certificate on your file system. If possible, we recommend using **Read from a file** to reduce likelihood of error. Note: Certificate files end with an extension of `.crt`. +1. Click **Create**. + +### 2. Add the Secret to an Ingress + +1. In the upper left corner, click **☰ > Cluster Management**. +1. Go to the cluster where you want to deploy your ingress and click **Service Discovery > Ingresses**. +1. Click **Create**. +1. Select the **Namespace** of the ingress. +1. Enter a **Name** for the ingress. +1. In the **Certificates** tab, select the secret containing your certificate and private key. +1. Click **Create**. + +## What's Next? + +Now you can add the certificate when launching an ingress within the current project or namespace. For more information, see [Adding Ingress](load-balancer-and-ingress-controller/add-ingresses.md). diff --git a/versioned_docs/version-2.14/how-to-guides/new-user-guides/kubernetes-resources-setup/horizontal-pod-autoscaler/about-hpas.md b/versioned_docs/version-2.14/how-to-guides/new-user-guides/kubernetes-resources-setup/horizontal-pod-autoscaler/about-hpas.md new file mode 100644 index 00000000000..18729cbca41 --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/new-user-guides/kubernetes-resources-setup/horizontal-pod-autoscaler/about-hpas.md @@ -0,0 +1,43 @@ +--- +title: Background Information on HPAs +--- + + + + + +The [Horizontal Pod Autoscaler](https://kubernetes.io/docs/tasks/run-application/horizontal-pod-autoscale/) (HPA) is a Kubernetes feature that allows you to configure your cluster to automatically scale the services it's running up or down. This section provides explanation on how HPA works with Kubernetes. + +## Why Use Horizontal Pod Autoscaler? + +Using HPA, you can automatically scale the number of pods within a replication controller, deployment, or replica set up or down. HPA automatically scales the number of pods that are running for maximum efficiency. Factors that affect the number of pods include: + +- A minimum and maximum number of pods allowed to run, as defined by the user. +- Observed CPU/memory use, as reported in resource metrics. +- Custom metrics provided by third-party metrics application like Prometheus, Datadog, etc. + +HPA improves your services by: + +- Releasing hardware resources that would otherwise be wasted by an excessive number of pods. +- Increase/decrease performance as needed to accomplish service level agreements. + +## How HPA Works + +![HPA Schema](/img/horizontal-pod-autoscaler.jpg) + +HPA is implemented as a control loop, with a period controlled by the `kube-controller-manager` flags below: + +Flag | Default | Description | +---------|----------|----------| + `--horizontal-pod-autoscaler-sync-period` | `30s` | How often HPA audits resource/custom metrics in a deployment. + `--horizontal-pod-autoscaler-downscale-delay` | `5m0s` | Following completion of a downscale operation, how long HPA must wait before launching another downscale operations. + `--horizontal-pod-autoscaler-upscale-delay` | `3m0s` | Following completion of an upscale operation, how long HPA must wait before launching another upscale operation. + + +For full documentation on HPA, refer to the [Kubernetes Documentation](https://kubernetes.io/docs/tasks/run-application/horizontal-pod-autoscale/). + +## Horizontal Pod Autoscaler API Objects + +HPA is an API resource in the Kubernetes `autoscaling` API group. The current stable version is `autoscaling/v1`, which only includes support for CPU autoscaling. To get additional support for scaling based on memory and custom metrics, use the beta version instead: `autoscaling/v2beta1`. + +For more information about the HPA API object, see the [HPA GitHub Readme](https://github.com/kubernetes/design-proposals-archive/blob/main/autoscaling/horizontal-pod-autoscaler.md#horizontalpodautoscaler-object). diff --git a/versioned_docs/version-2.14/how-to-guides/new-user-guides/kubernetes-resources-setup/horizontal-pod-autoscaler/horizontal-pod-autoscaler.md b/versioned_docs/version-2.14/how-to-guides/new-user-guides/kubernetes-resources-setup/horizontal-pod-autoscaler/horizontal-pod-autoscaler.md new file mode 100644 index 00000000000..bacdd796fce --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/new-user-guides/kubernetes-resources-setup/horizontal-pod-autoscaler/horizontal-pod-autoscaler.md @@ -0,0 +1,30 @@ +--- +title: Horizontal Pod Autoscaler +description: Learn about the horizontal pod autoscaler (HPA). How to manage HPAs and how to test them with a service deployment +--- + + + + + +The [Horizontal Pod Autoscaler](https://kubernetes.io/docs/tasks/run-application/horizontal-pod-autoscale/) (HPA) is a Kubernetes feature that allows you to configure your cluster to automatically scale the services it's running up or down. + +Rancher provides some additional features to help manage HPAs, depending on the version of Rancher. + +You can create, manage, and delete HPAs using the Rancher UI. It only supports HPA in the `autoscaling/v2beta2` API. + +## Managing HPAs + +The way that you manage HPAs is different based on your version of the Kubernetes API: + +- **For Kubernetes API version autoscaling/V2beta1:** This version of the Kubernetes API lets you autoscale your pods based on the CPU and memory utilization of your application. +- **For Kubernetes API Version autoscaling/V2beta2:** This version of the Kubernetes API lets you autoscale your pods based on CPU and memory utilization, in addition to custom metrics. + +You can create, manage, and delete HPAs using the Rancher UI. From the Rancher UI you can configure the HPA to scale based on CPU and memory utilization. For more information, refer to [Managing HPAs with the Rancher UI](manage-hpas-with-ui.md). To scale the HPA based on custom metrics, you still need to use `kubectl`. For more information, refer to [Configuring HPA to Scale Using Custom Metrics with Prometheus](manage-hpas-with-kubectl.md#configuring-hpa-to-scale-using-custom-metrics-with-prometheus). + +Clusters created in Rancher v2.0.7 and higher automatically have all the requirements needed (metrics-server and Kubernetes cluster configuration) to use HPA. +## Testing HPAs with a Service Deployment + +You can see your HPA's current number of replicas by going to your project and clicking **Resources > HPA**. For more information, refer to [Get HPA Metrics and Status](manage-hpas-with-ui.md). + +You can also use `kubectl` to get the status of HPAs that you test with your load testing tool. For more information, refer to [Testing HPAs with kubectl](test-hpas-with-kubectl.md). diff --git a/versioned_docs/version-2.14/how-to-guides/new-user-guides/kubernetes-resources-setup/horizontal-pod-autoscaler/manage-hpas-with-kubectl.md b/versioned_docs/version-2.14/how-to-guides/new-user-guides/kubernetes-resources-setup/horizontal-pod-autoscaler/manage-hpas-with-kubectl.md new file mode 100644 index 00000000000..573119909e8 --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/new-user-guides/kubernetes-resources-setup/horizontal-pod-autoscaler/manage-hpas-with-kubectl.md @@ -0,0 +1,208 @@ +--- +title: Managing HPAs with kubectl +--- + + + + + +This section describes HPA management with `kubectl`. This document has instructions for how to: + +- Create an HPA +- Get information on HPAs +- Delete an HPA +- Configure your HPAs to scale with CPU or memory utilization +- Configure your HPAs to scale using custom metrics, if you use a third-party tool such as Prometheus for metrics + + +You can create, view, and delete HPAs from the Rancher UI. You can also configure them to scale based on CPU or memory usage from the Rancher UI. For more information, refer to [Managing HPAs with the Rancher UI](./manage-hpas-with-ui.md). For scaling HPAs based on other metrics than CPU or memory, you still need `kubectl`. + +## Basic kubectl Command for Managing HPAs + +If you have an HPA manifest file, you can create, manage, and delete HPAs using `kubectl`: + +- Creating HPA + + - With manifest: `kubectl create -f ` + + - Without manifest (Just support CPU): `kubectl autoscale deployment hello-world --min=2 --max=5 --cpu-percent=50` + +- Getting HPA info + + - Basic: `kubectl get hpa hello-world` + + - Detailed description: `kubectl describe hpa hello-world` + +- Deleting HPA + + - `kubectl delete hpa hello-world` + +## HPA Manifest Definition Example + +The HPA manifest is the config file used for managing an HPA with `kubectl`. + +The following snippet demonstrates use of different directives in an HPA manifest. See the list below the sample to understand the purpose of each directive. + +```yml +apiVersion: autoscaling/v2beta1 +kind: HorizontalPodAutoscaler +metadata: + name: hello-world +spec: + scaleTargetRef: + apiVersion: extensions/v1beta1 + kind: Deployment + name: hello-world + minReplicas: 1 + maxReplicas: 10 + metrics: + - type: Resource + resource: + name: cpu + targetAverageUtilization: 50 + - type: Resource + resource: + name: memory + targetAverageValue: 100Mi +``` + + +Directive | Description +---------|----------| + `apiVersion: autoscaling/v2beta1` | The version of the Kubernetes `autoscaling` API group in use. This example manifest uses the beta version, so scaling by CPU and memory is enabled. | + `name: hello-world` | Indicates that HPA is performing autoscaling for the `hello-word` deployment. | + `minReplicas: 1` | Indicates that the minimum number of replicas running can't go below 1. | + `maxReplicas: 10` | Indicates the maximum number of replicas in the deployment can't go above 10. + `targetAverageUtilization: 50` | Indicates the deployment will scale pods up when the average running pod uses more than 50% of its requested CPU. + `targetAverageValue: 100Mi` | Indicates the deployment will scale pods up when the average running pod uses more that 100Mi of memory. +
+ +## Configuring HPA to Scale Using Resource Metrics (CPU and Memory) + +Clusters created in Rancher v2.0.7 and higher have all the requirements needed (metrics-server and Kubernetes cluster configuration) to use Horizontal Pod Autoscaler. + +Run the following commands to check if metrics are available in your installation: + +``` +$ kubectl top nodes +NAME CPU(cores) CPU% MEMORY(bytes) MEMORY% +node-controlplane 196m 9% 1623Mi 42% +node-etcd 80m 4% 1090Mi 28% +node-worker 64m 3% 1146Mi 29% +$ kubectl -n kube-system top pods +NAME CPU(cores) MEMORY(bytes) +canal-pgldr 18m 46Mi +canal-vhkgr 20m 45Mi +canal-x5q5v 17m 37Mi +canal-xknnz 20m 37Mi +kube-dns-7588d5b5f5-298j2 0m 22Mi +kube-dns-autoscaler-5db9bbb766-t24hw 0m 5Mi +metrics-server-97bc649d5-jxrlt 0m 12Mi +$ kubectl -n kube-system logs -l k8s-app=metrics-server +I1002 12:55:32.172841 1 heapster.go:71] /metrics-server --source=kubernetes.summary_api:https://kubernetes.default.svc?kubeletHttps=true&kubeletPort=10250&useServiceAccount=true&insecure=true +I1002 12:55:32.172994 1 heapster.go:72] Metrics Server version v0.2.1 +I1002 12:55:32.173378 1 configs.go:61] Using Kubernetes client with master "https://kubernetes.default.svc" and version +I1002 12:55:32.173401 1 configs.go:62] Using kubelet port 10250 +I1002 12:55:32.173946 1 heapster.go:128] Starting with Metric Sink +I1002 12:55:32.592703 1 serving.go:308] Generated self-signed cert (apiserver.local.config/certificates/apiserver.crt, apiserver.local.config/certificates/apiserver.key) +I1002 12:55:32.925630 1 heapster.go:101] Starting Heapster API server... +[restful] 2018/10/02 12:55:32 log.go:33: [restful/swagger] listing is available at https:///swaggerapi +[restful] 2018/10/02 12:55:32 log.go:33: [restful/swagger] https:///swaggerui/ is mapped to folder /swagger-ui/ +I1002 12:55:32.928597 1 serve.go:85] Serving securely on 0.0.0.0:443 +``` + + +## Configuring HPA to Scale Using Custom Metrics with Prometheus + +You can configure HPA to autoscale based on custom metrics provided by third-party software. The most common use case for autoscaling using third-party software is based on application-level metrics (i.e., HTTP requests per second). HPA uses the `custom.metrics.k8s.io` API to consume these metrics. This API is enabled by deploying a custom metrics adapter for the metrics collection solution. + +For this example, we are going to use [Prometheus](https://prometheus.io/). We are beginning with the following assumptions: + +- Prometheus is deployed in the cluster. +- Prometheus is configured correctly and collecting proper metrics from pods, nodes, namespaces, etc. +- Prometheus is exposed at the following URL and port: `http://prometheus.mycompany.io:80` + +Prometheus is available for deployment in the Rancher v2.0 catalog. Deploy it from Rancher catalog if it isn't already running in your cluster. + +For HPA to use custom metrics from Prometheus, package [k8s-prometheus-adapter](https://github.com/DirectXMan12/k8s-prometheus-adapter) is required in the `kube-system` namespace of your cluster. To install `k8s-prometheus-adapter`, we are using the Helm chart available at [banzai-charts](https://github.com/banzaicloud/banzai-charts). + +1. Initialize Helm in your cluster. + ``` + # kubectl -n kube-system create serviceaccount tiller + kubectl create clusterrolebinding tiller --clusterrole cluster-admin --serviceaccount=kube-system:tiller + helm init --service-account tiller + ``` + +1. Clone the `banzai-charts` repo from GitHub: + ``` + # git clone https://github.com/banzaicloud/banzai-charts + ``` + +1. Install the `prometheus-adapter` chart, specifying the Prometheus URL and port number. + ``` + # helm install --name prometheus-adapter banzai-charts/prometheus-adapter --set prometheus.url="http://prometheus.mycompany.io",prometheus.port="80" --namespace kube-system + ``` + +1. Check that `prometheus-adapter` is running properly. Check the service pod and logs in the `kube-system` namespace. + + 1. Check that the service pod is `Running`. Enter the following command. + ``` + # kubectl get pods -n kube-system + ``` + From the resulting output, look for a status of `Running`. + ``` + NAME READY STATUS RESTARTS AGE + ... + prometheus-adapter-prometheus-adapter-568674d97f-hbzfx 1/1 Running 0 7h + ... + ``` + 1. Check the service logs to make sure the service is running correctly by entering the command that follows. + ``` + # kubectl logs prometheus-adapter-prometheus-adapter-568674d97f-hbzfx -n kube-system + ``` + Then review the log output to confirm the service is running. + +
+ Prometheus Adaptor Logs + + ... + I0724 10:18:45.696679 1 round_trippers.go:436] GET https://10.43.0.1:443/api/v1/namespaces/default/pods?labelSelector=app%3Dhello-world 200 OK in 2 milliseconds + I0724 10:18:45.696695 1 round_trippers.go:442] Response Headers: + I0724 10:18:45.696699 1 round_trippers.go:445] Date: Tue, 24 Jul 2018 10:18:45 GMT + I0724 10:18:45.696703 1 round_trippers.go:445] Content-Type: application/json + I0724 10:18:45.696706 1 round_trippers.go:445] Content-Length: 2581 + I0724 10:18:45.696766 1 request.go:836] Response Body: {"kind":"PodList","apiVersion":"v1","metadata":{"selfLink":"/api/v1/namespaces/default/pods","resourceVersion":"6237"},"items":[{"metadata":{"name":"hello-world-54764dfbf8-q6l82","generateName":"hello-world-54764dfbf8-","namespace":"default","selfLink":"/api/v1/namespaces/default/pods/hello-world-54764dfbf8-q6l82","uid":"484cb929-8f29-11e8-99d2-067cac34e79c","resourceVersion":"4066","creationTimestamp":"2018-07-24T10:06:50Z","labels":{"app":"hello-world","pod-template-hash":"1032089694"},"annotations":{"cni.projectcalico.org/podIP":"10.42.0.7/32"},"ownerReferences":[{"apiVersion":"extensions/v1beta1","kind":"ReplicaSet","name":"hello-world-54764dfbf8","uid":"4849b9b1-8f29-11e8-99d2-067cac34e79c","controller":true,"blockOwnerDeletion":true}]},"spec":{"volumes":[{"name":"default-token-ncvts","secret":{"secretName":"default-token-ncvts","defaultMode":420}}],"containers":[{"name":"hello-world","image":"rancher/hello-world","ports":[{"containerPort":80,"protocol":"TCP"}],"resources":{"requests":{"cpu":"500m","memory":"64Mi"}},"volumeMounts":[{"name":"default-token-ncvts","readOnly":true,"mountPath":"/var/run/secrets/kubernetes.io/serviceaccount"}],"terminationMessagePath":"/dev/termination-log","terminationMessagePolicy":"File","imagePullPolicy":"Always"}],"restartPolicy":"Always","terminationGracePeriodSeconds":30,"dnsPolicy":"ClusterFirst","serviceAccountName":"default","serviceAccount":"default","nodeName":"34.220.18.140","securityContext":{},"schedulerName":"default-scheduler","tolerations":[{"key":"node.kubernetes.io/not-ready","operator":"Exists","effect":"NoExecute","tolerationSeconds":300},{"key":"node.kubernetes.io/unreachable","operator":"Exists","effect":"NoExecute","tolerationSeconds":300}]},"status":{"phase":"Running","conditions":[{"type":"Initialized","status":"True","lastProbeTime":null,"lastTransitionTime":"2018-07-24T10:06:50Z"},{"type":"Ready","status":"True","lastProbeTime":null,"lastTransitionTime":"2018-07-24T10:06:54Z"},{"type":"PodScheduled","status":"True","lastProbeTime":null,"lastTransitionTime":"2018-07-24T10:06:50Z"}],"hostIP":"34.220.18.140","podIP":"10.42.0.7","startTime":"2018-07-24T10:06:50Z","containerStatuses":[{"name":"hello-world","state":{"running":{"startedAt":"2018-07-24T10:06:54Z"}},"lastState":{},"ready":true,"restartCount":0,"image":"rancher/hello-world:latest","imageID":"docker-pullable://rancher/hello-world@sha256:4b1559cb4b57ca36fa2b313a3c7dde774801aa3a2047930d94e11a45168bc053","containerID":"docker://cce4df5fc0408f03d4adf82c90de222f64c302bf7a04be1c82d584ec31530773"}],"qosClass":"Burstable"}}]} + I0724 10:18:45.699525 1 api.go:74] GET http://prometheus-server.prometheus.34.220.18.140.xip.io/api/v1/query?query=sum%28rate%28container_fs_read_seconds_total%7Bpod_name%3D%22hello-world-54764dfbf8-q6l82%22%2Ccontainer_name%21%3D%22POD%22%2Cnamespace%3D%22default%22%7D%5B5m%5D%29%29+by+%28pod_name%29&time=1532427525.697 200 OK + I0724 10:18:45.699620 1 api.go:93] Response Body: {"status":"success","data":{"resultType":"vector","result":[{"metric":{"pod_name":"hello-world-54764dfbf8-q6l82"},"value":[1532427525.697,"0"]}]}} + I0724 10:18:45.699939 1 wrap.go:42] GET /apis/custom.metrics.k8s.io/v1beta1/namespaces/default/pods/%2A/fs_read?labelSelector=app%3Dhello-world: (12.431262ms) 200 [[kube-controller-manager/v1.10.1 (linux/amd64) kubernetes/d4ab475/system:serviceaccount:kube-system:horizontal-pod-autoscaler] 10.42.0.0:24268] + I0724 10:18:51.727845 1 request.go:836] Request Body: {"kind":"SubjectAccessReview","apiVersion":"authorization.k8s.io/v1beta1","metadata":{"creationTimestamp":null},"spec":{"nonResourceAttributes":{"path":"/","verb":"get"},"user":"system:anonymous","group":["system:unauthenticated"]},"status":{"allowed":false}} + ... +
+ + + +1. Check that the metrics API is accessible from kubectl. + + - If you are accessing the cluster directly, enter your Server URL in the kubectl config in the following format: `https://:6443`. + ``` + # kubectl get --raw /apis/custom.metrics.k8s.io/v1beta1 + ``` + If the API is accessible, you should receive output that's similar to what follows. + +
+ API Response + + {"kind":"APIResourceList","apiVersion":"v1","groupVersion":"custom.metrics.k8s.io/v1beta1","resources":[{"name":"pods/fs_usage_bytes","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/memory_rss","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/spec_cpu_period","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/cpu_cfs_throttled","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_io_time","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_read","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_sector_writes","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/cpu_user","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/last_seen","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/tasks_state","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/spec_cpu_quota","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/start_time_seconds","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_limit_bytes","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_write","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/memory_cache","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/memory_usage_bytes","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/cpu_cfs_periods","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/cpu_cfs_throttled_periods","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_reads_merged","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/memory_working_set_bytes","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/network_udp_usage","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_inodes_free","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_inodes","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_io_time_weighted","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/memory_failures","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/memory_swap","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/spec_cpu_shares","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/spec_memory_swap_limit_bytes","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/cpu_usage","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_io_current","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_writes","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/memory_failcnt","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_reads","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_writes_bytes","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_writes_merged","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/network_tcp_usage","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/memory_max_usage_bytes","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/spec_memory_limit_bytes","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/spec_memory_reservation_limit_bytes","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/cpu_load_average_10s","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/cpu_system","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_reads_bytes","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_sector_reads","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]}]} +
+ + - If you are accessing the cluster through Rancher, enter your Server URL in the kubectl config in the following format: `https:///k8s/clusters/`. Add the suffix `/k8s/clusters/` to API path. + ``` + # kubectl get --raw /k8s/clusters//apis/custom.metrics.k8s.io/v1beta1 + ``` + If the API is accessible, you should receive output that's similar to what follows. + +
+ API Response + + {"kind":"APIResourceList","apiVersion":"v1","groupVersion":"custom.metrics.k8s.io/v1beta1","resources":[{"name":"pods/fs_usage_bytes","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/memory_rss","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/spec_cpu_period","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/cpu_cfs_throttled","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_io_time","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_read","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_sector_writes","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/cpu_user","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/last_seen","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/tasks_state","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/spec_cpu_quota","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/start_time_seconds","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_limit_bytes","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_write","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/memory_cache","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/memory_usage_bytes","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/cpu_cfs_periods","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/cpu_cfs_throttled_periods","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_reads_merged","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/memory_working_set_bytes","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/network_udp_usage","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_inodes_free","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_inodes","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_io_time_weighted","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/memory_failures","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/memory_swap","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/spec_cpu_shares","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/spec_memory_swap_limit_bytes","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/cpu_usage","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_io_current","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_writes","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/memory_failcnt","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_reads","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_writes_bytes","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_writes_merged","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/network_tcp_usage","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/memory_max_usage_bytes","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/spec_memory_limit_bytes","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/spec_memory_reservation_limit_bytes","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/cpu_load_average_10s","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/cpu_system","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_reads_bytes","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_sector_reads","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]}]} +
diff --git a/versioned_docs/version-2.14/how-to-guides/new-user-guides/kubernetes-resources-setup/horizontal-pod-autoscaler/manage-hpas-with-ui.md b/versioned_docs/version-2.14/how-to-guides/new-user-guides/kubernetes-resources-setup/horizontal-pod-autoscaler/manage-hpas-with-ui.md new file mode 100644 index 00000000000..adc57ae88ee --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/new-user-guides/kubernetes-resources-setup/horizontal-pod-autoscaler/manage-hpas-with-ui.md @@ -0,0 +1,55 @@ +--- +title: Managing HPAs with the Rancher UI +--- + + + + + +The Rancher UI supports creating, managing, and deleting HPAs. You can configure CPU or memory usage as the metric that the HPA uses to scale. + +If you want to create HPAs that scale based on other metrics than CPU and memory, refer to [Configuring HPA to Scale Using Custom Metrics with Prometheus](./manage-hpas-with-kubectl.md#configuring-hpa-to-scale-using-custom-metrics-with-prometheus). + +## Creating an HPA + +1. In the upper left corner, click **☰ > Cluster Management**. +1. Go to the cluster you want to create an HPA in and click **Explore**. +1. In the left navigation bar, click **Service Discovery > HorizontalPodAutoscalers**. +1. Click **Create**. +1. Select a **Namespace** for the HPA. +1. Enter a **Name** for the HPA. +1. Select a **Target Reference** as scale target for the HPA. +1. Specify the **Minimum Replicas** and **Maximum Replicas** for the HPA. +1. Configure the metrics for the HPA. You can choose memory or CPU usage as the metric that will cause the HPA to scale the service up or down. In the **Quantity** field, enter the percentage of the workload's memory or CPU usage that will cause the HPA to scale the service. To configure other HPA metrics, including metrics available from Prometheus, you need to [manage HPAs using kubectl](./manage-hpas-with-kubectl.md#configuring-hpa-to-scale-using-custom-metrics-with-prometheus). + +1. Click **Create** to create the HPA. + +:::note Result: + +The HPA is deployed to the chosen namespace. You can view the HPA's status from the project's Resources > HPA view. + +::: + +## Get HPA Metrics and Status + +1. In the upper left corner, click **☰ > Cluster Management**. +1. Go to the cluster that has the HPA and click **Explore**. +1. In the left navigation bar, click **Service Discovery > HorizontalPodAutoscalers**. The **HorizontalPodAutoscalers** page shows the number of current replicas. + +For more detailed metrics and status of a specific HPA, click the name of the HPA. This leads to the HPA detail page. + + +## Deleting an HPA + +1. In the upper left corner, click **☰ > Cluster Management**. +1. Go to the cluster that has the HPA you want to delete and click **Explore**. +1. In the left navigation bar, click **Service Discovery > HorizontalPodAutoscalers**. +1. Click **Resources > HPA**. +1. Find the HPA which you would like to delete and click **⋮ > Delete**. +1. Click **Delete** to confirm. + +:::note Result: + +The HPA is deleted from the current cluster. + +::: \ No newline at end of file diff --git a/versioned_docs/version-2.14/how-to-guides/new-user-guides/kubernetes-resources-setup/horizontal-pod-autoscaler/test-hpas-with-kubectl.md b/versioned_docs/version-2.14/how-to-guides/new-user-guides/kubernetes-resources-setup/horizontal-pod-autoscaler/test-hpas-with-kubectl.md new file mode 100644 index 00000000000..6607274c4ee --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/new-user-guides/kubernetes-resources-setup/horizontal-pod-autoscaler/test-hpas-with-kubectl.md @@ -0,0 +1,534 @@ +--- +title: Testing HPAs with kubectl +--- + + + + + +This document describes how to check the status of your HPAs after scaling them up or down with your load testing tool. For information on how to check the status from the Rancher UI (at least version 2.3.x), refer to [Managing HPAs with the Rancher UI](./manage-hpas-with-kubectl.md). + +For HPA to work correctly, service deployments should have resources request definitions for containers. Follow this hello-world example to test if HPA is working correctly. + +1. Configure `kubectl` to connect to your Kubernetes cluster. + +1. Copy the `hello-world` deployment manifest below. + +
+ Hello World Manifest + + ``` + apiVersion: apps/v1beta2 + kind: Deployment + metadata: + labels: + app: hello-world + name: hello-world + namespace: default + spec: + replicas: 1 + selector: + matchLabels: + app: hello-world + strategy: + rollingUpdate: + maxSurge: 1 + maxUnavailable: 0 + type: RollingUpdate + template: + metadata: + labels: + app: hello-world + spec: + containers: + - image: rancher/hello-world + imagePullPolicy: Always + name: hello-world + resources: + requests: + cpu: 500m + memory: 64Mi + ports: + - containerPort: 80 + protocol: TCP + restartPolicy: Always + --- + apiVersion: v1 + kind: Service + metadata: + name: hello-world + namespace: default + spec: + ports: + - port: 80 + protocol: TCP + targetPort: 80 + selector: + app: hello-world + ``` + +
+ +1. Deploy it to your cluster. + + ``` + # kubectl create -f + ``` + +1. Copy one of the HPAs below based on the metric type you're using: + +
+ Hello World HPA: Resource Metrics + + ``` + apiVersion: autoscaling/v2beta1 + kind: HorizontalPodAutoscaler + metadata: + name: hello-world + namespace: default + spec: + scaleTargetRef: + apiVersion: extensions/v1beta1 + kind: Deployment + name: hello-world + minReplicas: 1 + maxReplicas: 10 + metrics: + - type: Resource + resource: + name: cpu + targetAverageUtilization: 50 + - type: Resource + resource: + name: memory + targetAverageValue: 1000Mi + ``` + +
+
+ Hello World HPA: Custom Metrics + + ``` + apiVersion: autoscaling/v2beta1 + kind: HorizontalPodAutoscaler + metadata: + name: hello-world + namespace: default + spec: + scaleTargetRef: + apiVersion: extensions/v1beta1 + kind: Deployment + name: hello-world + minReplicas: 1 + maxReplicas: 10 + metrics: + - type: Resource + resource: + name: cpu + targetAverageUtilization: 50 + - type: Resource + resource: + name: memory + targetAverageValue: 100Mi + - type: Pods + pods: + metricName: cpu_system + targetAverageValue: 20m + ``` + +
+ +1. View the HPA info and description. Confirm that metric data is shown. + +
+ Resource Metrics + + 1. Enter the following commands. + ``` + # kubectl get hpa + NAME REFERENCE TARGETS MINPODS MAXPODS REPLICAS AGE + hello-world Deployment/hello-world 1253376 / 100Mi, 0% / 50% 1 10 1 6m + # kubectl describe hpa + Name: hello-world + Namespace: default + Labels: + Annotations: + CreationTimestamp: Mon, 23 Jul 2018 20:21:16 +0200 + Reference: Deployment/hello-world + Metrics: ( current / target ) + resource memory on pods: 1253376 / 100Mi + resource cpu on pods (as a percentage of request): 0% (0) / 50% + Min replicas: 1 + Max replicas: 10 + Conditions: + Type Status Reason Message + ---- ------ ------ ------- + AbleToScale True ReadyForNewScale the last scale time was sufficiently old as to warrant a new scale + ScalingActive True ValidMetricFound the HPA was able to successfully calculate a replica count from memory resource + ScalingLimited False DesiredWithinRange the desired count is within the acceptable range + Events: + ``` + +
+
+ Custom Metrics + + 1. Enter the following command. + ``` + # kubectl describe hpa + ``` + You should receive the output that follows. + ``` + Name: hello-world + Namespace: default + Labels: + Annotations: + CreationTimestamp: Tue, 24 Jul 2018 18:36:28 +0200 + Reference: Deployment/hello-world + Metrics: ( current / target ) + resource memory on pods: 3514368 / 100Mi + "cpu_system" on pods: 0 / 20m + resource cpu on pods (as a percentage of request): 0% (0) / 50% + Min replicas: 1 + Max replicas: 10 + Conditions: + Type Status Reason Message + ---- ------ ------ ------- + AbleToScale True ReadyForNewScale the last scale time was sufficiently old as to warrant a new scale + ScalingActive True ValidMetricFound the HPA was able to successfully calculate a replica count from memory resource + ScalingLimited False DesiredWithinRange the desired count is within the acceptable range + Events: + ``` + +
+ +1. Generate a load for the service to test that your pods autoscale as intended. You can use any load-testing tool (Hey, Gatling, etc.), but we're using [Hey](https://github.com/rakyll/hey). + +1. Test that pod autoscaling works as intended.

+ **To Test Autoscaling Using Resource Metrics:** + +
+ Upscale to 2 Pods: CPU Usage Up to Target + + Use your load testing tool to scale up to two pods based on CPU Usage. + + 1. View your HPA. + ``` + # kubectl describe hpa + ``` + You should receive output similar to what follows. + ``` + Name: hello-world + Namespace: default + Labels: + Annotations: + CreationTimestamp: Mon, 23 Jul 2018 22:22:04 +0200 + Reference: Deployment/hello-world + Metrics: ( current / target ) + resource memory on pods: 10928128 / 100Mi + resource cpu on pods (as a percentage of request): 56% (280m) / 50% + Min replicas: 1 + Max replicas: 10 + Conditions: + Type Status Reason Message + ---- ------ ------ ------- + AbleToScale True SucceededRescale the HPA controller was able to update the target scale to 2 + ScalingActive True ValidMetricFound the HPA was able to successfully calculate a replica count from cpu resource utilization (percentage of request) + ScalingLimited False DesiredWithinRange the desired count is within the acceptable range + Events: + Type Reason Age From Message + ---- ------ ---- ---- ------- + Normal SuccessfulRescale 13s horizontal-pod-autoscaler New size: 2; reason: cpu resource utilization (percentage of request) above target + ``` + 1. Enter the following command to confirm you've scaled to two pods. + ``` + # kubectl get pods + ``` + You should receive output similar to what follows: + ``` + NAME READY STATUS RESTARTS AGE + hello-world-54764dfbf8-k8ph2 1/1 Running 0 1m + hello-world-54764dfbf8-q6l4v 1/1 Running 0 3h + ``` + +
+
+ Upscale to 3 pods: CPU Usage Up to Target + + Use your load testing tool to upscale to 3 pods based on CPU usage with `horizontal-pod-autoscaler-upscale-delay` set to 3 minutes. + + 1. Enter the following command. + ``` + # kubectl describe hpa + ``` + You should receive output similar to what follows + ``` + Name: hello-world + Namespace: default + Labels: + Annotations: + CreationTimestamp: Mon, 23 Jul 2018 22:22:04 +0200 + Reference: Deployment/hello-world + Metrics: ( current / target ) + resource memory on pods: 9424896 / 100Mi + resource cpu on pods (as a percentage of request): 66% (333m) / 50% + Min replicas: 1 + Max replicas: 10 + Conditions: + Type Status Reason Message + ---- ------ ------ ------- + AbleToScale True SucceededRescale the HPA controller was able to update the target scale to 3 + ScalingActive True ValidMetricFound the HPA was able to successfully calculate a replica count from cpu resource utilization (percentage of request) + ScalingLimited False DesiredWithinRange the desired count is within the acceptable range + Events: + Type Reason Age From Message + ---- ------ ---- ---- ------- + Normal SuccessfulRescale 4m horizontal-pod-autoscaler New size: 2; reason: cpu resource utilization (percentage of request) above target + Normal SuccessfulRescale 16s horizontal-pod-autoscaler New size: 3; reason: cpu resource utilization (percentage of request) above target + ``` + 2. Enter the following command to confirm three pods are running. + ``` + # kubectl get pods + ``` + You should receive output similar to what follows. + ``` + NAME READY STATUS RESTARTS AGE + hello-world-54764dfbf8-f46kh 0/1 Running 0 1m + hello-world-54764dfbf8-k8ph2 1/1 Running 0 5m + hello-world-54764dfbf8-q6l4v 1/1 Running 0 3h + ``` + +
+
+ Downscale to 1 Pod: All Metrics Below Target + + Use your load testing to scale down to 1 pod when all metrics are below target for `horizontal-pod-autoscaler-downscale-delay` (5 minutes by default). + + 1. Enter the following command. + ``` + # kubectl describe hpa + ``` + You should receive output similar to what follows. + ``` + Name: hello-world + Namespace: default + Labels: + Annotations: + CreationTimestamp: Mon, 23 Jul 2018 22:22:04 +0200 + Reference: Deployment/hello-world + Metrics: ( current / target ) + resource memory on pods: 10070016 / 100Mi + resource cpu on pods (as a percentage of request): 0% (0) / 50% + Min replicas: 1 + Max replicas: 10 + Conditions: + Type Status Reason Message + ---- ------ ------ ------- + AbleToScale True SucceededRescale the HPA controller was able to update the target scale to 1 + ScalingActive True ValidMetricFound the HPA was able to successfully calculate a replica count from memory resource + ScalingLimited False DesiredWithinRange the desired count is within the acceptable range + Events: + Type Reason Age From Message + ---- ------ ---- ---- ------- + Normal SuccessfulRescale 10m horizontal-pod-autoscaler New size: 2; reason: cpu resource utilization (percentage of request) above target + Normal SuccessfulRescale 6m horizontal-pod-autoscaler New size: 3; reason: cpu resource utilization (percentage of request) above target + Normal SuccessfulRescale 1s horizontal-pod-autoscaler New size: 1; reason: All metrics below target + ``` + +
+ + **To Test Autoscaling Using Custom Metrics:** + +
+ Upscale to 2 Pods: CPU Usage Up to Target + + Use your load testing tool to upscale two pods based on CPU usage. + + 1. Enter the following command. + ``` + # kubectl describe hpa + ``` + You should receive output similar to what follows. + ``` + Name: hello-world + Namespace: default + Labels: + Annotations: + CreationTimestamp: Tue, 24 Jul 2018 18:01:11 +0200 + Reference: Deployment/hello-world + Metrics: ( current / target ) + resource memory on pods: 8159232 / 100Mi + "cpu_system" on pods: 7m / 20m + resource cpu on pods (as a percentage of request): 64% (321m) / 50% + Min replicas: 1 + Max replicas: 10 + Conditions: + Type Status Reason Message + ---- ------ ------ ------- + AbleToScale True SucceededRescale the HPA controller was able to update the target scale to 2 + ScalingActive True ValidMetricFound the HPA was able to successfully calculate a replica count from cpu resource utilization (percentage of request) + ScalingLimited False DesiredWithinRange the desired count is within the acceptable range + Events: + Type Reason Age From Message + ---- ------ ---- ---- ------- + Normal SuccessfulRescale 16s horizontal-pod-autoscaler New size: 2; reason: cpu resource utilization (percentage of request) above target + ``` + 1. Enter the following command to confirm two pods are running. + ``` + # kubectl get pods + ``` + You should receive output similar to what follows. + ``` + NAME READY STATUS RESTARTS AGE + hello-world-54764dfbf8-5pfdr 1/1 Running 0 3s + hello-world-54764dfbf8-q6l82 1/1 Running 0 6h + ``` + +
+
+ Upscale to 3 Pods: CPU Usage Up to Target + + Use your load testing tool to scale up to three pods when the cpu_system usage limit is up to target. + + 1. Enter the following command. + ``` + # kubectl describe hpa + ``` + You should receive output similar to what follows: + ``` + Name: hello-world + Namespace: default + Labels: + Annotations: + CreationTimestamp: Tue, 24 Jul 2018 18:01:11 +0200 + Reference: Deployment/hello-world + Metrics: ( current / target ) + resource memory on pods: 8374272 / 100Mi + "cpu_system" on pods: 27m / 20m + resource cpu on pods (as a percentage of request): 71% (357m) / 50% + Min replicas: 1 + Max replicas: 10 + Conditions: + Type Status Reason Message + ---- ------ ------ ------- + AbleToScale True SucceededRescale the HPA controller was able to update the target scale to 3 + ScalingActive True ValidMetricFound the HPA was able to successfully calculate a replica count from cpu resource utilization (percentage of request) + ScalingLimited False DesiredWithinRange the desired count is within the acceptable range + Events: + Type Reason Age From Message + ---- ------ ---- ---- ------- + Normal SuccessfulRescale 3m horizontal-pod-autoscaler New size: 2; reason: cpu resource utilization (percentage of request) above target + Normal SuccessfulRescale 3s horizontal-pod-autoscaler New size: 3; reason: pods metric cpu_system above target + ``` + 1. Enter the following command to confirm three pods are running. + ``` + # kubectl get pods + ``` + You should receive output similar to what follows: + ``` + # kubectl get pods + NAME READY STATUS RESTARTS AGE + hello-world-54764dfbf8-5pfdr 1/1 Running 0 3m + hello-world-54764dfbf8-m2hrl 1/1 Running 0 1s + hello-world-54764dfbf8-q6l82 1/1 Running 0 6h + ``` + +
+
+ Upscale to 4 Pods: CPU Usage Up to Target + + Use your load testing tool to upscale to four pods based on CPU usage. `horizontal-pod-autoscaler-upscale-delay` is set to three minutes by default. + + 1. Enter the following command. + ``` + # kubectl describe hpa + ``` + You should receive output similar to what follows. + ``` + Name: hello-world + Namespace: default + Labels: + Annotations: + CreationTimestamp: Tue, 24 Jul 2018 18:01:11 +0200 + Reference: Deployment/hello-world + Metrics: ( current / target ) + resource memory on pods: 8374272 / 100Mi + "cpu_system" on pods: 27m / 20m + resource cpu on pods (as a percentage of request): 71% (357m) / 50% + Min replicas: 1 + Max replicas: 10 + Conditions: + Type Status Reason Message + ---- ------ ------ ------- + AbleToScale True SucceededRescale the HPA controller was able to update the target scale to 3 + ScalingActive True ValidMetricFound the HPA was able to successfully calculate a replica count from cpu resource utilization (percentage of request) + ScalingLimited False DesiredWithinRange the desired count is within the acceptable range + Events: + Type Reason Age From Message + ---- ------ ---- ---- ------- + Normal SuccessfulRescale 5m horizontal-pod-autoscaler New size: 2; reason: cpu resource utilization (percentage of request) above target + Normal SuccessfulRescale 3m horizontal-pod-autoscaler New size: 3; reason: pods metric cpu_system above target + Normal SuccessfulRescale 4s horizontal-pod-autoscaler New size: 4; reason: cpu resource utilization (percentage of request) above target + ``` + 1. Enter the following command to confirm four pods are running. + ``` + # kubectl get pods + ``` + You should receive output similar to what follows. + ``` + NAME READY STATUS RESTARTS AGE + hello-world-54764dfbf8-2p9xb 1/1 Running 0 5m + hello-world-54764dfbf8-5pfdr 1/1 Running 0 2m + hello-world-54764dfbf8-m2hrl 1/1 Running 0 1s + hello-world-54764dfbf8-q6l82 1/1 Running 0 6h + ``` + +
+
+ Downscale to 1 Pod: All Metrics Below Target + + Use your load testing tool to scale down to one pod when all metrics below target for `horizontal-pod-autoscaler-downscale-delay`. + + 1. Enter the following command. + ``` + # kubectl describe hpa + ``` + You should receive similar output to what follows. + ``` + Name: hello-world + Namespace: default + Labels: + Annotations: + CreationTimestamp: Tue, 24 Jul 2018 18:01:11 +0200 + Reference: Deployment/hello-world + Metrics: ( current / target ) + resource memory on pods: 8101888 / 100Mi + "cpu_system" on pods: 8m / 20m + resource cpu on pods (as a percentage of request): 0% (0) / 50% + Min replicas: 1 + Max replicas: 10 + Conditions: + Type Status Reason Message + ---- ------ ------ ------- + AbleToScale True SucceededRescale the HPA controller was able to update the target scale to 1 + ScalingActive True ValidMetricFound the HPA was able to successfully calculate a replica count from memory resource + ScalingLimited False DesiredWithinRange the desired count is within the acceptable range + Events: + Type Reason Age From Message + ---- ------ ---- ---- ------- + Normal SuccessfulRescale 10m horizontal-pod-autoscaler New size: 2; reason: cpu resource utilization (percentage of request) above target + Normal SuccessfulRescale 8m horizontal-pod-autoscaler New size: 3; reason: pods metric cpu_system above target + Normal SuccessfulRescale 5m horizontal-pod-autoscaler New size: 4; reason: cpu resource utilization (percentage of request) above target + Normal SuccessfulRescale 13s horizontal-pod-autoscaler New size: 1; reason: All metrics below target + ``` + 1. Enter the following command to confirm a single pods is running. + ``` + # kubectl get pods + ``` + You should receive output similar to what follows. + ``` + NAME READY STATUS RESTARTS AGE + hello-world-54764dfbf8-q6l82 1/1 Running 0 6h + ``` + +
diff --git a/versioned_docs/version-2.14/how-to-guides/new-user-guides/kubernetes-resources-setup/kubernetes-and-docker-registries.md b/versioned_docs/version-2.14/how-to-guides/new-user-guides/kubernetes-resources-setup/kubernetes-and-docker-registries.md new file mode 100644 index 00000000000..43951fe694b --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/new-user-guides/kubernetes-resources-setup/kubernetes-and-docker-registries.md @@ -0,0 +1,182 @@ +--- +title: Kubernetes Registry and Container Image Registry +description: Learn about the container image registry and Kubernetes registry, their use cases, and how to use a private registry with the Rancher UI +--- + + + + + +Registries are Kubernetes secrets containing credentials used to authenticate with [private container registries](https://kubernetes.io/docs/tasks/configure-pod-container/pull-image-private-registry/). + +The word "registry" can mean two things, depending on whether it is used to refer to a container or Kubernetes registry: + +- A **Container image registry** (formerly "Docker registry") contains container images that you can pull and deploy. The registry is a stateless, scalable server side application that stores and lets you distribute container images. +- The **Kubernetes registry** is an image pull secret that your deployment uses to authenticate with an image registry. + +Deployments use the Kubernetes registry secret to authenticate with a private image registry and then pull a container image hosted on it. + +Currently, deployments pull the private registry credentials automatically only if the workload is created in the Rancher UI and not when it is created via kubectl. + +## Creating a Registry in Namespaces + +:::note Prerequisite: + +You must have an available private registry already deployed. + +If you need to create a private registry, refer to the documentation pages for your respective runtime: + +* [Containerd](https://github.com/containerd/containerd/blob/main/docs/cri/config.md#registry-configuration). + * [Nerdctl commands and managed registry services](https://github.com/containerd/nerdctl/blob/main/docs/registry.md). +* [Docker](https://docs.docker.com/registry/deploying/). + +::: + +1. In the upper left corner, click **☰ > Cluster Management**. +1. Go to the cluster where you want to add a registry and click **Explore**. +1. In the left navigation, click either **Storage > Secrets** or **More Resources > Core > Secrets**. +1. Click **Create**. +1. Click **Registry**. +1. Enter a **Name** for the registry. + + :::note + + Kubernetes classifies secrets, certificates, and registries all as [secrets](https://kubernetes.io/docs/concepts/configuration/secret/), and no two secrets in a project or namespace can have duplicate names. Therefore, to prevent conflicts, your registry must have a unique name among all secrets within your workspace. + + ::: + +1. Select a namespace for the registry. +1. Select the website that hosts your private registry. Then enter credentials that authenticate with the registry. For example, if you use Docker Hub, provide your Docker Hub username and password. +1. Click **Save**. + +**Result:** + +- Your secret is added to the namespace you chose. +- You can view the secret in the Rancher UI by clicking either **Storage > Secrets** or **More Resources > Core > Secrets**. +- Any workload that you create in the Rancher UI will have the credentials to access the registry if the workload is within the registry's scope. + +## Creating a Registry in Projects + +:::note Prerequisites: + +You must have an available private registry already deployed. + +If you need to create a private registry, refer to the documentation pages for your respective runtime: + +* [Containerd](https://github.com/containerd/containerd/blob/main/docs/cri/config.md#registry-configuration). + * [Nerdctl commands and managed registry services](https://github.com/containerd/nerdctl/blob/main/docs/registry.md). +* [Docker](https://docs.docker.com/registry/deploying/). + +::: + +Before v2.6, secrets were required to be in a project scope. Projects are no longer required, and you may use the namespace scope instead. As a result, the Rancher UI was updated to reflect this new functionality. However, you may still create a project-scoped registry if desired. Use the following steps to do so: + +1. In the upper left corner, click **☰ > Global Settings** in the dropdown. +1. Click **Feature Flags**. +1. Go to the `legacy` feature flag and click **Activate**. +1. In the upper left corner, click **☰ > Cluster Management**. +1. Go to the cluster where you want to add a registry and click **Explore**. +1. In the left navigation, click either **Storage > Secrets** or **More Resources > Core > Secrets**. +1. Click **Create**. +1. Click **Registry**. +1. In the top navigation bar, filter to see only one project. +1. Enter a **Name** for the registry. + + :::note + + Kubernetes classifies secrets, certificates, and registries all as [secrets](https://kubernetes.io/docs/concepts/configuration/secret/), and no two secrets in a project or namespace can have duplicate names. Therefore, to prevent conflicts, your registry must have a unique name among all secrets within your workspace. + + ::: + +1. Select a namespace for the registry. +1. Select the website that hosts your private registry. Then enter credentials that authenticate with the registry. For example, if you use Docker Hub, provide your Docker Hub username and password. +1. Click **Save**. + +**Result:** + +- Your secret is added to the individual project you chose. +- You can view the secret in the Rancher UI by clicking either **Storage > Secrets** or **More Resources > Core > Secrets**. +- Any workload that you create in the Rancher UI will have the credentials to access the registry if the workload is within the registry's scope. + +:::note + +Project-scoped registries on the local cluster are only visible when a single project is selected. + +::: + +## Using a Private Registry + +You can deploy a workload with an image from a private registry through the Rancher UI, or with `kubectl`. + +### Using the Private Registry with the Rancher UI + +To deploy a workload with an image from your private registry, + +1. In the upper left corner, click **☰ > Cluster Management**. +1. Go to the cluster where you want to deploy a workload and click **Explore**. +1. Click **Workload**. +1. Click **Create**. +1. Select the type of workload you want to create. +1. Enter a unique name for the workload and choose a namespace. +1. In the **Container Image** field, enter the URL of the path to the image in your private registry. For example, if your private registry is on Quay.io, you could use `quay.io//`. +1. Click **Create**. + +**Result:** Your deployment should launch, authenticate using the private registry credentials you added in the Rancher UI, and pull the container image that you specified. + +### Using the Private Registry with kubectl + +When you create the workload using `kubectl`, you need to configure the pod so that its YAML has the path to the image in the private registry. You also have to create and reference the registry secret because the pod only automatically gets access to the private registry credentials if it is created in the Rancher UI. + +The secret has to be created in the same namespace where the workload gets deployed. + +Below is an example `pod.yml` for a workload that uses an image from a private registry. In this example, the pod uses an image from Quay.io, and the .yml specifies the path to the image. The pod authenticates with the registry using credentials stored in a Kubernetes secret called `testquay`, which is specified in `spec.imagePullSecrets` in the `name` field: + +```yaml +apiVersion: v1 +kind: Pod +metadata: + name: private-reg +spec: + containers: + - name: private-reg-container + image: quay.io// + imagePullSecrets: + - name: testquay +``` + +In this example, the secret named `testquay` is in the default namespace. + +You can use `kubectl` to create the secret with the private registry credentials. This command creates the secret named `testquay`: + +``` +kubectl create secret docker-registry testquay \ + --docker-server=quay.io \ + --docker-username= \ + --docker-password= +``` + +To see how the secret is stored in Kubernetes, you can use this command: + +``` +kubectl get secret testquay --output="jsonpath={.data.\.dockerconfigjson}" | base64 --decode +``` + +The result looks like this: + +``` +{"auths":{"quay.io":{"username":"","password":"","auth":"c291bXlhbGo6dGVzdGFiYzEyMw=="}}} +``` + +After the workload is deployed, you can check if the image was pulled successfully: + +``` +kubectl get events +``` +The result should look like this: +``` +14s Normal Scheduled Pod Successfully assigned default/private-reg2 to minikube +11s Normal Pulling Pod pulling image "quay.io//" +10s Normal Pulled Pod Successfully pulled image "quay.io//" +``` + +For more information, refer to the Kubernetes documentation on [creating a pod that uses your secret.](https://kubernetes.io/docs/tasks/configure-pod-container/pull-image-private-registry/#create-a-pod-that-uses-your-secret) diff --git a/versioned_docs/version-2.14/how-to-guides/new-user-guides/kubernetes-resources-setup/kubernetes-resources-setup.md b/versioned_docs/version-2.14/how-to-guides/new-user-guides/kubernetes-resources-setup/kubernetes-resources-setup.md new file mode 100644 index 00000000000..3e97882659c --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/new-user-guides/kubernetes-resources-setup/kubernetes-resources-setup.md @@ -0,0 +1,67 @@ +--- +title: Kubernetes Resources Setup +--- + + + + + +You can view and manipulate all of the custom resources and CRDs in a Kubernetes cluster from the Rancher UI. + +## Workloads + +Deploy applications to your cluster nodes using [workloads](workloads-and-pods/workloads-and-pods.md), which are objects that contain pods that run your apps, along with metadata that set rules for the deployment's behavior. Workloads can be deployed within the scope of the entire clusters or within a namespace. + +When deploying a workload, you can deploy from any image. There are a variety of [workload types](workloads-and-pods/workloads-and-pods.md#workload-types) to choose from which determine how your application should run. + +Following a workload deployment, you can continue working with it. You can: + +- [Upgrade](workloads-and-pods/upgrade-workloads.md) the workload to a newer version of the application it's running. +- [Roll back](workloads-and-pods/roll-back-workloads.md) a workload to a previous version, if an issue occurs during upgrade. +- [Add a sidecar](workloads-and-pods/add-a-sidecar.md), which is a workload that supports a primary workload. + +## Load Balancing and Ingress + +### Load Balancers + +After you launch an application, it's only available within the cluster. It can't be reached externally. + +If you want your applications to be externally accessible, you must add a load balancer to your cluster. Load balancers create a gateway for external connections to access your cluster, provided that the user knows the load balancer's IP address and the application's port number. + +Rancher supports two types of load balancers: + +- [Layer-4 Load Balancers](load-balancer-and-ingress-controller/layer-4-and-layer-7-load-balancing.md#layer-4-load-balancer) +- [Layer-7 Load Balancers](load-balancer-and-ingress-controller/layer-4-and-layer-7-load-balancing.md#layer-7-load-balancer) + +For more information, see [load balancers](load-balancer-and-ingress-controller/layer-4-and-layer-7-load-balancing.md). + +#### Ingress + +Load Balancers can only handle one IP address per service, which means if you run multiple services in your cluster, you must have a load balancer for each service. Running multiples load balancers can be expensive. You can get around this issue by using an ingress. + +Ingress is a set of rules that act as a load balancer. Ingress works in conjunction with one or more ingress controllers to dynamically route service requests. When the ingress receives a request, the ingress controller(s) in your cluster program the load balancer to direct the request to the correct service based on service subdomains or path rules that you've configured. + +For more information, see [Ingress](load-balancer-and-ingress-controller/add-ingresses.md). + +When using ingresses in a project, you can program the ingress hostname to an external DNS by setting up a Global DNS entry. + +## Service Discovery + +After you expose your cluster to external requests using a load balancer and/or ingress, it's only available by IP address. To create a resolveable hostname, you must create a service record, which is a record that maps an IP address, external hostname, DNS record alias, workload(s), or labelled pods to a specific hostname. + +For more information, see [Service Discovery](create-services.md). + +## Applications + +Besides launching individual components of an application, you can use the Rancher catalog to start launching applications, which are Helm charts. + +## Kubernetes Resources + +Within the context of a Rancher project or namespace, _resources_ are files and data that support operation of your pods. Within Rancher, certificates, registries, and secrets are all considered resources. However, Kubernetes classifies resources as different types of [secrets](https://kubernetes.io/docs/concepts/configuration/secret/). Therefore, within a single project or namespace, individual resources must have unique names to avoid conflicts. Although resources are primarily used to carry sensitive information, they have other uses as well. + +Resources include: + +- [Certificates](encrypt-http-communication.md): Files used to encrypt/decrypt data entering or leaving the cluster. +- [ConfigMaps](configmaps.md): Files that store general configuration information, such as a group of config files. +- [Secrets](secrets.md): Files that store sensitive data like passwords, tokens, or keys. +- [Registries](kubernetes-and-docker-registries.md): Files that carry credentials used to authenticate with private registries. diff --git a/versioned_docs/version-2.14/how-to-guides/new-user-guides/kubernetes-resources-setup/load-balancer-and-ingress-controller/add-ingresses.md b/versioned_docs/version-2.14/how-to-guides/new-user-guides/kubernetes-resources-setup/load-balancer-and-ingress-controller/add-ingresses.md new file mode 100644 index 00000000000..c102ee9550f --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/new-user-guides/kubernetes-resources-setup/load-balancer-and-ingress-controller/add-ingresses.md @@ -0,0 +1,22 @@ +--- +title: Adding Ingresses +description: Ingresses can be added for workloads to provide load balancing, SSL termination and host/path-based routing. Learn how to add Rancher ingress +--- + + + + + +Ingresses can be added for workloads to provide load balancing, SSL termination and host/path based routing. When using ingresses in a project, you can program the ingress hostname to an external DNS by setting up a Global DNS entry. + +1. In the upper left corner, click **☰ > Cluster Management**. +1. Go to the cluster that you want to add an ingress to and click **Explore**. +1. Click **Service Discovery > Ingresses**. +1. Click **Create**. +1. Select an existing **Namespace** from the drop-down list. +1. Enter a **Name** for the ingress. +1. [Create](./ingress-configuration.md) ingress forwarding **Rules**. If any of your ingress rules handle requests for encrypted ports, add a certificate to encrypt/decrypt communications. +1. **Optional:** click **Add Rule** to create additional ingress rules. For example, after you create ingress rules to direct requests for your hostname, you'll likely want to create a default backend to handle 404s. +1. Click **Create** at the bottom right. + +**Result:** Your ingress is added to the project. The ingress begins enforcing your ingress rules. diff --git a/versioned_docs/version-2.14/how-to-guides/new-user-guides/kubernetes-resources-setup/load-balancer-and-ingress-controller/ingress-configuration.md b/versioned_docs/version-2.14/how-to-guides/new-user-guides/kubernetes-resources-setup/load-balancer-and-ingress-controller/ingress-configuration.md new file mode 100644 index 00000000000..9ab3f01da4e --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/new-user-guides/kubernetes-resources-setup/load-balancer-and-ingress-controller/ingress-configuration.md @@ -0,0 +1,45 @@ +--- +title: Configuring an Ingress +description: Configuring an Ingress +--- + + + + + +:::note + +For Kubernetes v1.21 and up, the NGINX Ingress controller no longer runs in hostNetwork by default. It instead uses hostPorts for port 80 and port 443, so you can configure the admission webhook to be accessible only through the ClusterIP. This ensures that the webhook is only accessible from within the cluster. + +Because of this change to the controller, the default RKE1 behavior no longer sets `hostNetwork` to `true`. However, you must set `hostNetwork` to `true` for TCP- and UDP-based Services to work. To do so, [edit](../../../../reference-guides/cluster-configuration/rancher-server-configuration/rke1-cluster-configuration.md#editing-clusters-with-yaml) the cluster's YAML and follow the steps in the [official RKE1 documentation](https://rke.docs.rancher.com/config-options/add-ons/ingress-controllers#configuring-network-options). + +::: + +## Specify a hostname to use + +If you use this option, Ingress routes requests for a hostname to the service or workload that you specify. + +1. Specify a path of type `Prefix` and specify a path such as `/`. +1. Add a **Target Service**. +1. **Optional:** If you want to specify a workload or service when a request is sent to a particular hostname path, add a **Path** for the target. For example, if you want requests for `www.mysite.com/contact-us` to be sent to a different service than `www.mysite.com`, enter `/contact-us` in the **Path** field. Typically, the first rule that you create does not include a path. +1. Enter the **Port** number that each target operates on. + +## Certificates + +:::note + +You must have an SSL certificate that Ingress can use to encrypt and decrypt communications. For more information, see [Adding SSL Certificates](../encrypt-http-communication.md). + +::: + +1. To create an Ingress controller, click the **Certificates** tab. +1. Click **Add Certificate**. +1. Select a **Certificate - Secret Name** from the drop-down list. +1. Enter the host using encrypted communication. +1. To add more hosts that use the same certificate, click **Add Hosts**. + +## Labels and Annotations + +Add [Labels](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/) and/or [Annotations](https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations/) to provide metadata for your Ingress controller. + +For a list of annotations available for use, see the [Nginx Ingress Controller Documentation](https://kubernetes.github.io/ingress-nginx/user-guide/nginx-configuration/annotations/). diff --git a/versioned_docs/version-2.14/how-to-guides/new-user-guides/kubernetes-resources-setup/load-balancer-and-ingress-controller/layer-4-and-layer-7-load-balancing.md b/versioned_docs/version-2.14/how-to-guides/new-user-guides/kubernetes-resources-setup/load-balancer-and-ingress-controller/layer-4-and-layer-7-load-balancing.md new file mode 100644 index 00000000000..e0d25c169e6 --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/new-user-guides/kubernetes-resources-setup/load-balancer-and-ingress-controller/layer-4-and-layer-7-load-balancing.md @@ -0,0 +1,72 @@ +--- +title: "Layer 4 and Layer 7 Load Balancing" +description: "Kubernetes supports load balancing in two ways: Layer-4 Load Balancing and Layer-7 Load Balancing. Learn about the support for each way in different deployments" +--- + + + + + +Kubernetes supports load balancing in two ways: Layer-4 Load Balancing and Layer-7 Load Balancing. + +## Layer-4 Load Balancer + +Layer-4 load balancer (or the external load balancer) forwards traffic to Nodeports. Layer-4 load balancer allows you to forward both HTTP and TCP traffic. + +Often, the Layer-4 load balancer is supported by the underlying cloud provider, so when you deploy RKE clusters on bare-metal servers and vSphere clusters, Layer-4 load balancer is not supported. However, a single [globally managed config-map](https://kubernetes.github.io/ingress-nginx/user-guide/exposing-tcp-udp-services/) can be used to expose services on NGINX or third-party ingress. + +:::note + +It is possible to deploy a cluster with a non-cloud load balancer, such as [MetalLB.](https://metallb.universe.tf/) However, that use case is more advanced than the Layer-4 load balancer supported by a cloud provider, and it is not configurable in Rancher or RKE. + +::: + +### Support for Layer-4 Load Balancing + +Support for layer-4 load balancer varies based on the underlying cloud provider. + +Cluster Deployment | Layer-4 Load Balancer Support +----------------------------------------------|-------------------------------- +Amazon EKS | Supported by AWS cloud provider +Google GKE | Supported by GCE cloud provider +Azure AKS | Supported by Azure cloud provider +RKE on EC2 | Supported by AWS cloud provider +RKE on DigitalOcean | Limited NGINX or third-party Ingress* +RKE on vSphere | Limited NGINX or third party-Ingress* +RKE on Custom Hosts
(e.g. bare-metal servers) | Limited NGINX or third-party Ingress* +Third-party MetalLB | Limited NGINX or third-party Ingress* + +\* Services can be exposed through a single [globally managed config-map.](https://kubernetes.github.io/ingress-nginx/user-guide/exposing-tcp-udp-services/) + +## Layer-7 Load Balancer + +Layer-7 load balancer (or the ingress controller) supports host and path-based load balancing and SSL termination. Layer-7 load balancer only forwards HTTP and HTTPS traffic and therefore they listen on ports 80 and 443 only. Cloud providers such as Amazon and Google support layer-7 load balancer. In addition, RKE clusters deploys the Nginx Ingress Controller. + +### Support for Layer-7 Load Balancing + +Support for layer-7 load balancer varies based on the underlying cloud provider. + +Cluster Deployment | Layer-7 Load Balancer Support +----------------------------------------------|-------------------------------- +Amazon EKS | Supported by AWS cloud provider +Google GKE | Supported by GKE cloud provider +Azure AKS | Not Supported +RKE on EC2 | Nginx Ingress Controller +RKE on DigitalOcean | Nginx Ingress Controller +RKE on vSphere | Nginx Ingress Controller +RKE on Custom Hosts
(e.g. bare-metal servers) | Nginx Ingress Controller + +### Host Names in Layer-7 Load Balancer + +Some cloud-managed layer-7 load balancers (such as the ALB ingress controller on AWS) expose DNS addresses for ingress rules. You need to map (via CNAME) your domain name to the DNS address generated by the layer-7 load balancer. + +Other layer-7 load balancers, such as the Google Load Balancer or Nginx Ingress Controller, directly expose one or more IP addresses. Google Load Balancer provides a single routable IP address. Nginx Ingress Controller exposes the external IP of all nodes that run the Nginx Ingress Controller. You can do either of the following: + +1. Configure your own DNS to map (via A records) your domain name to the IP addresses exposes by the Layer-7 load balancer. +2. Ask Rancher to generate an xip.io host name for your ingress rule. Rancher will take one of your exposed IPs, say `a.b.c.d`, and generate a host name `..a.b.c.d.xip.io`. + +The benefit of using xip.io is that you obtain a working entrypoint URL immediately after you create the ingress rule. Setting up your own domain name, on the other hand, requires you to configure DNS servers and wait for DNS to propagate. + +## Related Links + +- [Create an External Load Balancer](https://kubernetes.io/docs/tasks/access-application-cluster/create-external-load-balancer/) diff --git a/versioned_docs/version-2.14/how-to-guides/new-user-guides/kubernetes-resources-setup/load-balancer-and-ingress-controller/load-balancer-and-ingress-controller.md b/versioned_docs/version-2.14/how-to-guides/new-user-guides/kubernetes-resources-setup/load-balancer-and-ingress-controller/load-balancer-and-ingress-controller.md new file mode 100644 index 00000000000..48d3f52e276 --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/new-user-guides/kubernetes-resources-setup/load-balancer-and-ingress-controller/load-balancer-and-ingress-controller.md @@ -0,0 +1,65 @@ +--- +title: Load Balancer and Ingress Controller Setup within Rancher +description: Learn how you can set up load balancers and ingress controllers to redirect service requests within Rancher, and learn about the limitations of load balancers +--- + + + + + +Within Rancher, you can set up load balancers and ingress controllers to redirect service requests. + +## Load Balancers + +After you launch an application, the app is only available within the cluster. It can't be reached from outside the cluster. + +If you want your applications to be externally accessible, you must add a load balancer or ingress to your cluster. Load balancers create a gateway for external connections to access your cluster, provided that the user knows the load balancer's IP address and the application's port number. + +Rancher supports two types of load balancers: + +- [Layer-4 Load Balancers](layer-4-and-layer-7-load-balancing.md#layer-4-load-balancer) +- [Layer-7 Load Balancers](layer-4-and-layer-7-load-balancing.md#layer-7-load-balancer) + +For more information, see [load balancers](layer-4-and-layer-7-load-balancing.md). + +### Load Balancer Limitations + +Load Balancers have a couple of limitations you should be aware of: + +- Load Balancers can only handle one IP address per service, which means if you run multiple services in your cluster, you must have a load balancer for each service. Running multiples load balancers can be expensive. + +- If you want to use a load balancer with a Hosted Kubernetes cluster (i.e., clusters hosted in GKE, EKS, or AKS), the load balancer must be running within that cloud provider's infrastructure. Please review the compatibility tables regarding support for load balancers based on how you've provisioned your clusters: + +- [Support for Layer-4 Load Balancing](layer-4-and-layer-7-load-balancing.md#support-for-layer-4-load-balancing) + +- [Support for Layer-7 Load Balancing](layer-4-and-layer-7-load-balancing.md#support-for-layer-7-load-balancing) + +## Ingress + +As mentioned in the limitations above, the disadvantages of using a load balancer are: + +- Load Balancers can only handle one IP address per service. +- If you run multiple services in your cluster, you must have a load balancer for each service. +- It can be expensive to have a load balancer for every service. + +In contrast, when an ingress is used as the entrypoint into a cluster, the ingress can route traffic to multiple services with greater flexibility. It can map multiple HTTP requests to services without individual IP addresses for each service. + +Therefore, it is useful to have an ingress if you want multiple services to be exposed with the same IP address, the same Layer 7 protocol, or the same privileged node-ports: 80 and 443. + +Ingress works in conjunction with one or more ingress controllers to dynamically route service requests. When the ingress receives a request, the ingress controller(s) in your cluster direct the request to the correct service based on service subdomains or path rules that you've configured. + +Each Kubernetes Ingress resource corresponds roughly to a file in `/etc/nginx/sites-available/` containing a `server{}` configuration block, where requests for specific files and folders are configured. + +Your ingress, which creates a port of entry to your cluster similar to a load balancer, can reside within your cluster or externally. Ingress and ingress controllers residing in RKE-launched clusters are powered by [Nginx](https://www.nginx.com/). + +Ingress can provide other functionality as well, such as SSL termination, name-based virtual hosting, and more. + +:::note Using Rancher in a High Availability Configuration? + +Refrain from adding an Ingress to the `local` cluster. The Nginx Ingress Controller that Rancher uses acts as a global entry point for _all_ clusters managed by Rancher, including the `local` cluster. Therefore, when users try to access an application, your Rancher connection may drop due to the Nginx configuration being reloaded. We recommend working around this issue by deploying applications only in clusters that you launch using Rancher. + +::: + +- For more information on how to set up ingress in Rancher, see [Ingress](add-ingresses.md). +- For complete information about ingress and ingress controllers, see the [Kubernetes Ingress Documentation](https://kubernetes.io/docs/concepts/services-networking/ingress/) +- When using ingresses in a project, you can program the ingress hostname to an external DNS by setting up a Global DNS entry. diff --git a/versioned_docs/version-2.14/how-to-guides/new-user-guides/kubernetes-resources-setup/secrets.md b/versioned_docs/version-2.14/how-to-guides/new-user-guides/kubernetes-resources-setup/secrets.md new file mode 100644 index 00000000000..362ffac61e5 --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/new-user-guides/kubernetes-resources-setup/secrets.md @@ -0,0 +1,117 @@ +--- +title: Secrets +--- + + + + + +[Secrets](https://kubernetes.io/docs/concepts/configuration/secret/#overview-of-secrets) store sensitive data like passwords, tokens, or keys. They may contain one or more key value pairs. + +:::note + +This page is about secrets in general. For details on setting up a private registry, refer to the section on [registries.](kubernetes-and-docker-registries.md) + +::: + +When configuring a workload, you are able to choose which secrets to include. Like config maps, secrets can be referenced by workloads as either an environment variable or a volume mount. + +Mounted secrets are updated automatically unless they are mounted as subpath volumes. For details on how updated secrets are propagated, refer to the [Kubernetes documentation.](https://kubernetes.io/docs/concepts/configuration/secret/#mounted-secrets-are-updated-automatically) + +## Creating Secrets in Namespaces + +1. In the upper left corner, click **☰ > Cluster Management**. +1. Go to the cluster where you want to add a secret and click **Explore**. +1. To navigate to secrets, you may click either **Storage > Secrets** or **More Resources > Core > Secrets**. +1. Select the **Namespaced** tab. +1. Click **Create**. +1. Select the type of secret you want to create. +1. Select a **Namespace** for the secret. +1. Enter a **Name** for the secret. + + :::note + + Kubernetes classifies secrets, certificates, and registries all as [secrets](https://kubernetes.io/docs/concepts/configuration/secret/), and no two secrets in a namespace can have duplicate names. Therefore, to prevent conflicts, your secret must have a unique name among all secrets within your workspace. + + ::: + +1. From **Data**, click **Add** to add a key-value pair. Add as many values as you need. + + :::tip + + You can add multiple key value pairs to the secret by copying and pasting. + + ::: + + ![](/img/bulk-key-values.gif) + +1. Click **Save**. + +**Result:** Your secret is added to the namespace you chose. You can view the secret in the Rancher UI by clicking either **Storage > Secrets** or **More Resources > Core > Secrets**. + +Mounted secrets are updated automatically unless they are mounted as subpath volumes. For details on how updated secrets are propagated, refer to the [Kubernetes documentation.](https://kubernetes.io/docs/concepts/configuration/secret/#mounted-secrets-are-updated-automatically) + + +## Creating Secrets in Projects + +When creating a secret in a project scope, the secret is copied into all namespaces within the project. + +### Creating a Project Scoped Secret in the UI + +1. In the upper left corner, click **☰ > Cluster Management**. +1. Go to the cluster where you want to add a secret and click **Explore**. +1. To navigate to secrets, you may click either **Storage > Secrets** or **More Resources > Core > Secrets**. +1. Select the **Project Scoped** tab. +1. Click **Create Project Scoped Secret**. +1. Select the type of secret you want to create. +1. Select a **Project** for the secret. +1. Enter a **Name** for the secret. + + :::note + + Kubernetes classifies secrets, certificates, and registries all as [secrets](https://kubernetes.io/docs/concepts/configuration/secret/), and no two secrets in a namespace can have duplicate names. If you create a project scoped secret that has the same name as an existing secret in one of the project namespaces, the existing secret is overwritten. + + ::: + +1. From **Data**, click **Add** to add a key-value pair. Add as many values as you need. + + :::tip + + You can add multiple key-value pairs to the secret by copying and pasting. + + ::: + + ![](/img/bulk-key-values.gif) + +1. Click **Save**. + +**Result:** Your secret is added to each namespace within the project. You can view the secret in the Rancher UI by clicking either **Storage > Secrets** or **More Resources > Core > Secrets**. + +### Creating a Project Scoped Secret with kubectl + +Project scoped secrets work by creating the original secret on the management cluster in what's known as the "Project Backing Namespace". Rancher stores important project related information in this namespace. You can find it in the `status.backingNamespace` field in the project CRD, or by doing `kubectl get projects -A` in the management cluster. + +In order for the secret to be acknowledged by Rancher as a project scoped secret, it also needs the label `management.cattle.io/project-scoped-secret: `. + +Example yaml: + +``` +apiVersion: v1 +data: + key: ZG9n +kind: Secret +metadata: + labels: + management.cattle.io/project-scoped-secret: p-vwxyz + name: test-secret + namespace: c-abc123-p-vwxyz +type: Opaque +``` + +In the above YAML, the namespace is the backing namespace of project `p-vwxyz` and the project scoped secret label references the projectID. When applied to the management cluster, all namespaces within the project `p-vwxyz` contain a copy of `test-secret`. + +## What's Next? + +Now that you have a secret added to a namespace, you can add it to a workload that you deploy. + +For more information on adding secret to a workload, see [Deploying Workloads](workloads-and-pods/deploy-workloads.md). diff --git a/versioned_docs/version-2.14/how-to-guides/new-user-guides/kubernetes-resources-setup/workloads-and-pods/add-a-sidecar.md b/versioned_docs/version-2.14/how-to-guides/new-user-guides/kubernetes-resources-setup/workloads-and-pods/add-a-sidecar.md new file mode 100644 index 00000000000..e5dc6e4b503 --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/new-user-guides/kubernetes-resources-setup/workloads-and-pods/add-a-sidecar.md @@ -0,0 +1,39 @@ +--- +title: Adding a Sidecar +--- + + + + + +A _sidecar_ is a container that extends or enhances the main container in a pod. The main container and the sidecar share a pod, and therefore share the same network space and storage. You can add sidecars to existing workloads by using the **Add a Sidecar** option. + +1. In the upper left corner, click **☰ > Cluster Management**. +1. Go to the cluster where you want to add a sidecar and click **Explore**. +1. In the left navigation bar, click **Workload**. + +1. Find the workload that you want to extend. Select **⋮ > + Add Sidecar**. + +1. Enter a **Name** for the sidecar. + +1. In the **General** section, select a sidecar type. This option determines if the sidecar container is deployed before or after the main container is deployed. + + - **Standard Container:** + + The sidecar container is deployed after the main container. + + - **Init Container:** + + The sidecar container is deployed before the main container. + +1. From the **Container Image** field, enter the name of the container image that you want to deploy in support of the main container. During deployment, Rancher pulls this image from [Docker Hub](https://hub.docker.com/explore/). Enter the name exactly as it appears on Docker Hub. + +1. Set the remaining options. You can read about them in [Deploying Workloads](deploy-workloads.md). + +1. Click **Launch**. + +**Result:** The sidecar is deployed according to your parameters. Following its deployment, you can view the sidecar by selecting **⋮ icon (...) > Edit** for the main deployment. + +## Related Links + +- [The Distributed System ToolKit: Patterns for Composite Containers](https://kubernetes.io/blog/2015/06/the-distributed-system-toolkit-patterns/) diff --git a/versioned_docs/version-2.14/how-to-guides/new-user-guides/kubernetes-resources-setup/workloads-and-pods/deploy-workloads.md b/versioned_docs/version-2.14/how-to-guides/new-user-guides/kubernetes-resources-setup/workloads-and-pods/deploy-workloads.md new file mode 100644 index 00000000000..b3c89b90949 --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/new-user-guides/kubernetes-resources-setup/workloads-and-pods/deploy-workloads.md @@ -0,0 +1,61 @@ +--- +title: Deploying Workloads +description: Read this step by step guide for deploying workloads. Deploy a workload to run an application in one or more containers. +--- + + + + + +Deploy a workload to run an application in one or more containers. + +1. In the upper left corner, click **☰ > Cluster Management**. +1. Go to the cluster where you want to upgrade a workload and click **Explore**. +1. In the left navigation bar, click **Workload**. +1. Click **Create**. +1. Choose the type of workload. +1. Select the namespace where the workload will be deployed. +1. Enter a **Name** for the workload. + +1. From the **Container Image** field, enter the name of the Docker image that you want to deploy to the project, optionally prefacing it with the registry host (e.g. `quay.io`, `registry.gitlab.com`, etc.). During deployment, Rancher pulls this image from the specified public or private registry. If no registry host is provided, Rancher will pull the image from [Docker Hub](https://hub.docker.com/explore/). Enter the name exactly as it appears in the registry server, including any required path, and optionally including the desired tag (e.g. `registry.gitlab.com/user/path/image:tag`). If no tag is provided, the `latest` tag will be automatically used. + +1. Either select an existing namespace, or click **Add to a new namespace** and enter a new namespace. + +1. Click **Add Port** to enter a port mapping, which enables access to the application inside and outside of the cluster . For more information, see [Services](workloads-and-pods.md#services). + +1. Configure the remaining options: + + - **Environment Variables** + + Use this section to either specify environment variables for your workload to consume on the fly, or to pull them from another source, such as a secret or [ConfigMap](../configmaps.md). + + - **Node Scheduling** + - **Health Check** + - **Volumes** + + Use this section to add storage for your workload. You can manually specify the volume that you want to add, use a persistent volume claim to dynamically create a volume for the workload, or read data for a volume to use from a file such as a [ConfigMap](../configmaps.md). + + When you are deploying a Stateful Set, you should use a Volume Claim Template when using Persistent Volumes. This will ensure that Persistent Volumes are created dynamically when you scale your Stateful Set. + + - **Scaling/Upgrade Policy** + + :::note Amazon Note for Volumes: + + To mount an Amazon EBS volume: + + - In [Amazon AWS](https://aws.amazon.com/), the nodes must be in the same Availability Zone and possess IAM permissions to attach/unattach volumes. + + - The cluster must be using the [AWS cloud provider](https://github.com/kubernetes/website/blob/release-1.18/content/en/docs/concepts/cluster-administration/cloud-providers.md#aws) option. For more information on enabling this option see [Creating an Amazon EC2 Cluster](../../launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/create-an-amazon-ec2-cluster.md) or [Creating a Custom Cluster](../../../../reference-guides/cluster-configuration/rancher-server-configuration/use-existing-nodes/use-existing-nodes.md). + + ::: + +1. Click **Show Advanced Options** and configure: + + - **Command** + - **Networking** + - **Labels & Annotations** + - **Security and Host Config** + +1. Click **Launch**. + +**Result:** The workload is deployed to the chosen namespace. You can view the workload's status from the project's **Workloads** view. diff --git a/versioned_docs/version-2.14/how-to-guides/new-user-guides/kubernetes-resources-setup/workloads-and-pods/roll-back-workloads.md b/versioned_docs/version-2.14/how-to-guides/new-user-guides/kubernetes-resources-setup/workloads-and-pods/roll-back-workloads.md new file mode 100644 index 00000000000..e8f87d33055 --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/new-user-guides/kubernetes-resources-setup/workloads-and-pods/roll-back-workloads.md @@ -0,0 +1,18 @@ +--- +title: Rolling Back Workloads +--- + + + + + +Sometimes there is a need to rollback to the previous version of the application, either for debugging purposes or because an upgrade did not go as planned. + +1. In the upper left corner, click **☰ > Cluster Management**. +1. Go to the cluster where you want to upgrade a workload and click **Explore**. +1. In the left navigation bar, click **Workload**. +1. Find the workload that you want to rollback and select **⋮ > Rollback**. + +1. Choose the revision that you want to roll back to. Click **Rollback**. + +**Result:** Your workload reverts to the previous version that you chose. Wait a few minutes for the action to complete. diff --git a/versioned_docs/version-2.14/how-to-guides/new-user-guides/kubernetes-resources-setup/workloads-and-pods/upgrade-workloads.md b/versioned_docs/version-2.14/how-to-guides/new-user-guides/kubernetes-resources-setup/workloads-and-pods/upgrade-workloads.md new file mode 100644 index 00000000000..05a51a640bf --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/new-user-guides/kubernetes-resources-setup/workloads-and-pods/upgrade-workloads.md @@ -0,0 +1,25 @@ +--- +title: Upgrading Workloads +--- + + + + + +When a new version of an application image is released on Docker Hub, you can upgrade any workloads running a previous version of the application to the new one. + +1. In the upper left corner, click **☰ > Cluster Management**. +1. Go to the cluster where you want to upgrade a workload and click **Explore**. +1. In the left navigation bar, click **Workload**. + +1. Find the workload that you want to upgrade and select **⋮ > Edit Config**. + +1. Update the **Container Image** and any options that you want to change. + +1. Review and edit the workload's **Scaling and Upgrade Policy**. + + These options control how the upgrade rolls out to containers that are currently running. For example, for scalable deployments, you can choose whether you want to stop old pods before deploying new ones, or vice versa, as well as the upgrade batch size. + +1. Click **Save**. + +**Result:** The workload begins upgrading its containers, per your specifications. Note that scaling up the deployment or updating the upgrade/scaling policy won't result in the pods recreation. diff --git a/versioned_docs/version-2.14/how-to-guides/new-user-guides/kubernetes-resources-setup/workloads-and-pods/workloads-and-pods.md b/versioned_docs/version-2.14/how-to-guides/new-user-guides/kubernetes-resources-setup/workloads-and-pods/workloads-and-pods.md new file mode 100644 index 00000000000..b9bd0fa0a47 --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/new-user-guides/kubernetes-resources-setup/workloads-and-pods/workloads-and-pods.md @@ -0,0 +1,82 @@ +--- +title: "Kubernetes Workloads and Pods" +description: "Learn about the two constructs with which you can build any complex containerized application in Kubernetes: Kubernetes workloads and pods" +--- + + + + + +You can build any complex containerized application in Kubernetes using two basic constructs: pods and workloads. Once you build an application, you can expose it for access either within the same cluster or on the Internet using a third construct: services. + +### Pods + +[_Pods_](https://kubernetes.io/docs/concepts/workloads/pods/pod-overview/) are one or more containers that share network namespaces and storage volumes. Most pods have only one container. Therefore when we discuss _pods_, the term is often synonymous with _containers_. You scale pods the same way you scale containers—by having multiple instances of the same pod that implement a service. Usually pods get scaled and managed by the workload. + +### Workloads + +_Workloads_ are objects that set deployment rules for pods. Based on these rules, Kubernetes performs the deployment and updates the workload with the current state of the application. +Workloads let you define the rules for application scheduling, scaling, and upgrade. + +#### Workload Types + +Kubernetes divides workloads into different types. The most popular types supported by Kubernetes are: + +- [Deployments](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/) + + _Deployments_ are best used for stateless applications (i.e., when you don't have to maintain the workload's state). Pods managed by deployment workloads are treated as independent and disposable. If a pod encounters disruption, Kubernetes removes it and then recreates it. An example application would be an Nginx web server. + +- [StatefulSets](https://kubernetes.io/docs/concepts/workloads/controllers/statefulset/) + + _StatefulSets_, in contrast to deployments, are best used when your application needs to maintain its identity and store data. An application would be something like Zookeeper—an application that requires a database for storage. + +- [DaemonSets](https://kubernetes.io/docs/concepts/workloads/controllers/daemonset/) + + _Daemonsets_ ensures that every node in the cluster runs a copy of pod. For use cases where you're collecting logs or monitoring node performance, this daemon-like workload works best. + +- [Jobs](https://kubernetes.io/docs/concepts/workloads/controllers/jobs-run-to-completion/) + + _Jobs_ launch one or more pods and ensure that a specified number of them successfully terminate. Jobs are best used to run a finite task to completion as opposed to managing an ongoing desired application state. + +- [CronJobs](https://kubernetes.io/docs/concepts/workloads/controllers/cron-jobs/) + + _CronJobs_ are similar to jobs. CronJobs, however, runs to completion on a cron-based schedule. + +### Services + +In many use cases, a workload has to be either: + +- Accessed by other workloads in the cluster. +- Exposed to the outside world. + +You can achieve these goals by creating a _Service_. Services are mapped to the underlying workload's pods using a [selector/label approach (view the code samples)](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/#service-and-replicationcontroller). Rancher UI simplifies this mapping process by automatically creating a service along with the workload, using the service port and type that you select. + +#### Service Types + +There are several types of services available in Rancher. The descriptions below are sourced from the [Kubernetes Documentation](https://kubernetes.io/docs/concepts/services-networking/service/#publishing-services-service-types). + +- **ClusterIP** + + >Exposes the service on a cluster-internal IP. Choosing this value makes the service only reachable from within the cluster. This is the default `ServiceType`. + +- **NodePort** + + >Exposes the service on each Node’s IP at a static port (the `NodePort`). A `ClusterIP` service, to which the `NodePort` service will route, is automatically created. You’ll be able to contact the `NodePort` service, from outside the cluster, by requesting `:`. + +- **LoadBalancer** + + >Exposes the service externally using a cloud provider’s load balancer. `NodePort` and `ClusterIP` services, to which the external load balancer will route, are automatically created. + +## Workload Options + +This section of the documentation contains instructions for deploying workloads and using workload options. + +- [Deploy Workloads](deploy-workloads.md) +- [Upgrade Workloads](upgrade-workloads.md) +- [Rollback Workloads](roll-back-workloads.md) + +## Related Links + +### External Links + +- [Services](https://kubernetes.io/docs/concepts/services-networking/service/) diff --git a/versioned_docs/version-2.14/how-to-guides/new-user-guides/launch-kubernetes-with-rancher/about-rancher-agents.md b/versioned_docs/version-2.14/how-to-guides/new-user-guides/launch-kubernetes-with-rancher/about-rancher-agents.md new file mode 100644 index 00000000000..375397eb513 --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/new-user-guides/launch-kubernetes-with-rancher/about-rancher-agents.md @@ -0,0 +1,98 @@ +--- +title: Rancher Agents +--- + + + + + +There are two different agent resources deployed on Rancher managed clusters: + +- [cattle-cluster-agent](#cattle-cluster-agent) +- [cattle-node-agent](#cattle-node-agent) + +For a conceptual overview of how the Rancher server provisions clusters and communicates with them, refer to the [architecture](../../../reference-guides/rancher-manager-architecture/rancher-manager-architecture.md). + +### cattle-cluster-agent + +The `cattle-cluster-agent` is used to connect to the Kubernetes API of [Rancher Launched Kubernetes](launch-kubernetes-with-rancher.md) clusters. The `cattle-cluster-agent` is deployed using a Deployment resource. + +### cattle-node-agent + +The `cattle-node-agent` is used to interact with nodes in a [Rancher Launched Kubernetes](launch-kubernetes-with-rancher.md) cluster when performing cluster operations. Examples of cluster operations are upgrading Kubernetes version and creating/restoring etcd snapshots. The `cattle-node-agent` is deployed using a DaemonSet resource to make sure it runs on every node. The `cattle-node-agent` is used as fallback option to connect to the Kubernetes API of [Rancher Launched Kubernetes](launch-kubernetes-with-rancher.md) clusters when `cattle-cluster-agent` is unavailable. + +### Requests + +The `cattle-cluster-agent` pod does not define the default CPU and memory request values. As a baseline, we recommend setting the CPU request at `50m` and memory request at `100Mi`. However, it is important that you assess your use case appropriately and that you allocate the correct resources to your cluster for your needs. + +To configure request values through the UI: + + + + +1. When you [create](./launch-kubernetes-with-rancher.md) or edit an existing cluster, go to the **Cluster Options** section. +1. Expand the **Cluster Configuration** subsection. +1. Configure your request values using the **CPU Requests** and **Memory Requests** fields as needed. + + + + +1. When you [create](./launch-kubernetes-with-rancher.md) or edit an existing cluster, go to the **Cluster Configuration**. +1. Select the **Cluster Agent** subsection. +1. Configure your request values using the **CPU Reservation** and **Memory Reservation** fields as needed. + + + + +If you prefer to configure via YAML, add the following snippet to your configuration file: + + + + +```yaml +cluster_agent_deployment_customization: + override_resource_requirements: + requests: + cpu: 50m + memory: 100Mi +``` + + + + +```yaml +spec: + clusterAgentDeploymentCustomization: + overrideResourceRequirements: + requests: + cpu: 50m + memory: 100Mi +``` + + + + +### Scheduling rules + +The `cattle-cluster-agent` uses either a fixed set of tolerations, or dynamically-added tolerations based on taints applied to the control plane nodes. This structure allows [Taint based Evictions](https://kubernetes.io/docs/concepts/scheduling-eviction/taint-and-toleration/#taint-based-evictions) to work properly for `cattle-cluster-agent`. + +If control plane nodes are present in the cluster, the default tolerations will be replaced with tolerations matching the taints on the control plane nodes. The default set of tolerations are described below. + +| Component | nodeAffinity nodeSelectorTerms | nodeSelector | Tolerations | +| ---------------------- | ------------------------------------------ | ------------ | ------------------------------------------------------------------------------ | +| `cattle-cluster-agent` | `beta.kubernetes.io/os:NotIn:windows` | none | **Note:** These are the default tolerations, and will be replaced by tolerations matching taints applied to controlplane nodes.

`effect:NoSchedule`
`key:node-role.kubernetes.io/controlplane`
`value:true`

`effect:NoSchedule`
`key:node-role.kubernetes.io/control-plane`
`operator:Exists`

`effect:NoSchedule`
`key:node-role.kubernetes.io/master`
`operator:Exists` | +| `cattle-node-agent` | `beta.kubernetes.io/os:NotIn:windows` | none | `operator:Exists` | + +The `cattle-cluster-agent` Deployment has preferred scheduling rules using `preferredDuringSchedulingIgnoredDuringExecution`, favoring to be scheduled on nodes with the `controlplane` node. When there are no controlplane nodes visible in the cluster (this is usually the case when using [Clusters from Hosted Kubernetes Providers](../kubernetes-clusters-in-rancher-setup/set-up-clusters-from-hosted-kubernetes-providers/set-up-clusters-from-hosted-kubernetes-providers.md)), you can add the label `cattle.io/cluster-agent=true` on a node to prefer scheduling the `cattle-cluster-agent` pod to that node. + +See [Kubernetes: Assigning Pods to Nodes](https://kubernetes.io/docs/concepts/configuration/assign-pod-node/) to find more information about scheduling rules. + +The `preferredDuringSchedulingIgnoredDuringExecution` configuration is shown in the table below: + +| Weight | Expression | +| ------ | ------------------------------------------------ | +| 100 | `node-role.kubernetes.io/controlplane:In:"true"` | +| 100 | `node-role.kubernetes.io/control-plane:In:"true"` | +| 100 | `node-role.kubernetes.io/master:In:"true"` | +| 1 | `cattle.io/cluster-agent:In:"true"` | + diff --git a/versioned_docs/version-2.14/how-to-guides/new-user-guides/launch-kubernetes-with-rancher/launch-kubernetes-with-rancher.md b/versioned_docs/version-2.14/how-to-guides/new-user-guides/launch-kubernetes-with-rancher/launch-kubernetes-with-rancher.md new file mode 100644 index 00000000000..89cfbba2469 --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/new-user-guides/launch-kubernetes-with-rancher/launch-kubernetes-with-rancher.md @@ -0,0 +1,60 @@ +--- +title: Launching Kubernetes with Rancher +--- + + + + + +Rancher allows you to launch a Kubernetes cluster on different types of nodes, including bare-metal servers, on-premise virtual machines, and virtual machines from an infrastructure provider. When deploying Kubernetes to these nodes, Rancher gives you the option to use [RKE2](https://docs.rke2.io). + +Rancher can install Kubernetes on existing nodes, or it can dynamically provision nodes in an infrastructure provider and install Kubernetes on them. + +Rancher can also create pools of machines. One benefit of installing Kubernetes on machine pools hosted by an infrastructure provider is that if a node loses connectivity with the cluster, Rancher can automatically create another node to join the cluster to ensure that the count of the machine pool is as expected. + +## RKE2 + +Rancher v2.6 introduced provisioning for [RKE2](https://docs.rke2.io/) clusters directly from the Rancher UI. RKE2, also known as RKE Government, is a fully conformant Kubernetes distribution that focuses on security and compliance within the U.S. Federal Government sector. In Rancher v.2.6.4 and earlier, RKE2 provisioning was in tech preview. + +Note that in Rancher v2.6.5, RKE2 provisioning became GA. + +### Requirements + +If you use RKE2 to set up a cluster, your nodes must meet the [requirements](https://docs.rke2.io/install/requirements) for nodes in downstream user clusters. + +### Launching Kubernetes on New Nodes in an Infrastructure Provider + +RKE2 provisioning is built on top of a new provisioning framework that leverages the upstream [Cluster API (CAPI)](https://github.com/kubernetes-sigs/cluster-api) project. With this new provisioning framework, you can: + +- Provision RKE2 clusters onto any provider for which Rancher has a node driver. +- Fully configure RKE2 clusters within Rancher. +- Choose CNI options Calico, Cilium, and Multus in addition to Canal. + +When you make changes to your cluster configuration in RKE2, this may result in nodes reprovisioning. This is controlled by CAPI controllers and not by Rancher itself. Note that for etcd nodes, the same behavior does not apply. + +The following are some specific example configuration changes that may cause the described behavior: + +- When editing the cluster and enabling drain before delete, the existing control plane nodes and worker are deleted and new nodes are created. + +RKE2 provisioning also includes installing RKE2 on clusters with Windows nodes. + +Windows features for RKE2 include: + +- Windows supports the vSphere node driver +- Calico and Flannel CNI for Windows RKE2 custom clusters +- Project Network Isolation (PNI) for Calico +- Windows Containers with RKE2 powered by containerd +- Provisioning of Windows RKE2 clusters through Terraform +- Provisioning of Windows RKE2 custom clusters directly from the Rancher UI + +Windows Support for RKE2 Custom Clusters requires choosing Calico as the CNI. + +### Launching Kubernetes on Existing Custom Nodes + +RKE2 provisioning also allows you to install custom clusters on previously provisioned VMs or bare-metal nodes. + +If you want to reuse a node from a previous custom cluster, [clean the node](../manage-clusters/clean-cluster-nodes.md#cleaning-up-nodes) before using it in a cluster again. If you reuse a node that hasn't been cleaned, cluster provisioning may fail. + +### Programmatically Creating RKE2 Clusters + +The most common way to programmatically deploy RKE2 clusters through Rancher is by using the [Rancher2 Terraform provider](https://registry.terraform.io/providers/rancher/rancher2/latest/docs/resources/cluster_v2). diff --git a/versioned_docs/version-2.14/how-to-guides/new-user-guides/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/create-a-digitalocean-cluster.md b/versioned_docs/version-2.14/how-to-guides/new-user-guides/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/create-a-digitalocean-cluster.md new file mode 100644 index 00000000000..7e6b5b57d11 --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/new-user-guides/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/create-a-digitalocean-cluster.md @@ -0,0 +1,58 @@ +--- +title: Creating a DigitalOcean Cluster +--- + + + + + +In this section, you'll learn how to deploy an [RKE2](https://docs.rke2.io/)/[K3s](https://docs.k3s.io/) Kubernetes cluster in DigitalOcean. + +First, you will set up your DigitalOcean cloud credentials in Rancher. + +Then you will create a DigitalOcean cluster in Rancher, and when configuring the new cluster, you will define machine pools for it. Each machine pool will have a Kubernetes role of etcd, controlplane, or worker. Rancher will install Kubernetes on the new nodes, and it will set up each node with the Kubernetes role defined by the machine pool. + +### 1. Create your cloud credentials + +If you already have a set of cloud credentials to use, skip this section. + +1. Click **☰ > Cluster Management**. +1. Click **Cloud Credentials**. +1. Click **Create**. +1. Click **DigitalOcean**. +1. Enter your Digital Ocean credentials. +1. Click **Create**. + +### 2. Create your cluster + +Use Rancher to create a Kubernetes cluster in DigitalOcean. + +1. Click **☰ > Cluster Management**. +1. On the **Clusters** page, click **Create**. +1. Toggle the switch to **RKE2/K3s**. +1. Click **DigitalOcean**. +1. Select a **Cloud Credential**, if more than one exists. Otherwise, it's preselected. +1. Enter a **Cluster Name**. +1. Create a machine pool for each Kubernetes role. Refer to the [best practices](use-new-nodes-in-an-infra-provider.md#node-roles) for recommendations on role assignments and counts. + 1. For each machine pool, define the machine configuration. Refer to the [DigitalOcean machine configuration reference](../../../../reference-guides/cluster-configuration/downstream-cluster-configuration/machine-configuration/digitalocean.md) for information on configuration options. +1. Use the **Cluster Configuration** to choose the version of Kubernetes that will be installed, what network provider will be used and if you want to enable project network isolation. For help configuring the cluster, refer to the [RKE2](../../../../reference-guides/cluster-configuration/rancher-server-configuration/rke2-cluster-configuration.md) and [K3s](../../../../reference-guides/cluster-configuration/rancher-server-configuration/k3s-cluster-configuration.md) cluster configuration reference. +1. Use **Member Roles** to configure user authorization for the cluster. Click **Add Member** to add users that can access the cluster. Use the **Role** drop-down to set permissions for each user. +1. Click **Create**. + +**Result:** + +Your cluster is created and assigned a state of **Provisioning**. Rancher is standing up your cluster. + +You can access your cluster after its state is updated to **Active**. + +**Active** clusters are assigned two Projects: + +- `Default`, containing the `default` namespace +- `System`, containing the `cattle-system`, `ingress-nginx`, `kube-public`, and `kube-system` namespaces + +## Optional Next Steps + +After creating your cluster, you can access it through the Rancher UI. As a best practice, we recommend setting up these alternate ways of accessing your cluster: + +- **Access your cluster with the kubectl CLI:** Follow [these steps](../../../new-user-guides/manage-clusters/access-clusters/use-kubectl-and-kubeconfig.md#accessing-clusters-with-kubectl-from-your-workstation) to access clusters with kubectl on your workstation. In this case, you will be authenticated through the Rancher server’s authentication proxy, then Rancher will connect you to the downstream cluster. This method lets you manage the cluster without the Rancher UI. +- **Access your cluster with the kubectl CLI, using the authorized cluster endpoint:** Follow [these steps](../../../new-user-guides/manage-clusters/access-clusters/use-kubectl-and-kubeconfig.md#authenticating-directly-with-a-downstream-cluster) to access your cluster with kubectl directly, without authenticating through Rancher. We recommend setting up this alternative method to access your cluster so that in case you can’t connect to Rancher, you can still access the cluster. diff --git a/versioned_docs/version-2.14/how-to-guides/new-user-guides/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/create-a-google-compute-engine-cluster.md b/versioned_docs/version-2.14/how-to-guides/new-user-guides/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/create-a-google-compute-engine-cluster.md new file mode 100644 index 00000000000..d7a09f4089c --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/new-user-guides/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/create-a-google-compute-engine-cluster.md @@ -0,0 +1,107 @@ +--- +title: Creating a Google Compute Engine cluster +--- + + + + + + +In this section, you'll learn how to use Rancher to provision an [RKE2](https://docs.rke2.io/)/[K3s](https://docs.k3s.io/) Kubernetes cluster on the Google Cloud Platform (GCP) using Google Compute Engine (GCE) through Rancher. + + +First, you will enable the GCE node driver in the Rancher UI. Then, you follow the steps to create a GCP service account with the necessary permissions, and generate a JSON key file. This key file will be used to create a cloud credential in Rancher. + + +Then, you will create a GCE cluster in Rancher, and when configuring the cluster, you will define machine pools for it. Each machine pool will have a Kubernetes role of etcd, controlplane, or worker. Rancher will install RKE2 onto the new nodes, and it will set up each node with the Kubernetes role defined by the machine pool. + + +1. [Enable the GCE node driver](#1-enable-the-gce-node-driver) +1. [Create your cloud credential](#2-create-a-cloud-credential) +1. [Create a GCE cluster with your cloud credential](#3-create-a-cluster-using-the-cloud-credential) +1. [GCE Best Practices](#gce-best-practices) + +### Prerequisites + +1. A valid Google Cloud Platform account and project. +1. A GCP Service Account JSON key file. The service account associated with this key must have the following IAM roles: + 1. **Compute Admin** + 1. **Service Account User** + 1. **Viewer** +1. A VPC Network to provision VMs within. + +Refer to the [GCP documentation](https://cloud.google.com/iam/docs/service-account-overview) on creating and managing service account keys for more details. + + +### 1. Enable the GCE node driver + +The GCE node driver is not enabled by default in Rancher. You must enable it before you can provision GCE clusters, or work with GCE specific CRDs. + +1. Click **☰ > Cluster Management**. +1. On the left hand side, click **Drivers**. +1. Open the **Node Drivers** tab. +1. Find the **Google GCE** driver and select **⋮ > Activate**. + + +### 2. Create a cloud credential + +1. Click **☰ > Cluster Management**. +1. Click **Cloud Credentials**. +1. Click **Create**. +1. Click **Google**. +1. Enter your GCP Service Account JSON key file. +1. Click **Create**. + +**Result:** You have created the cloud credentials that will be used to provision nodes in your cluster. You can reuse these credentials in other clusters. Depending on the permissions granted to the service account, this credential may also be used for GKE clusters. + + +### 3. Create a cluster using the cloud credential + +1. Click **☰ > Cluster Management**. +1. On the **Clusters** page, click **Create**. +1. Click **Google GCE**. +1. Select a **Cloud Credential** and provide the GCP project to create the VM in. +1. Enter a **Cluster Name**. +1. Create a machine pool for each Kubernetes role. Refer to the [best practices](use-new-nodes-in-an-infra-provider.md#node-roles) for recommendations on role assignments and counts. + 1. For each machine pool, define the machine configuration. Refer to the [Google GCE machine configuration reference](../../../../reference-guides/cluster-configuration/downstream-cluster-configuration/machine-configuration/google-gce.md) for information on configuration options. +1. Use the **Cluster Configuration** to choose the version of Kubernetes that will be installed, what network provider will be used and if you want to enable project network isolation. For help configuring the cluster, refer to the [RKE2](../../../../reference-guides/cluster-configuration/rancher-server-configuration/rke2-cluster-configuration.md) and [K3s](../../../../reference-guides/cluster-configuration/rancher-server-configuration/k3s-cluster-configuration.md) cluster configuration reference. +1. Use **Member Roles** to configure user authorization for the cluster. Click **Add Member** to add users that can access the cluster. Use the **Role** drop-down to set permissions for each user. +1. Click **Create**. + + +**Result:** + +Your cluster is created and assigned a state of **Provisioning**. Rancher is standing up your cluster. + +You can access your cluster after its state is updated to **Active**. + +**Active** clusters are assigned two Projects: + +- `Default`, containing the `default` namespace +- `System`, containing the `cattle-system`, `ingress-nginx`, `kube-public`, and `kube-system` namespaces + +### GCE Best Practices + +#### External Firewall Rules, Open Ports, and ACE + +If the cluster being provisioned will utilize the [Authorized Cluster Endpoint (ACE) feature](../../../new-user-guides/manage-clusters/access-clusters/use-kubectl-and-kubeconfig.md#authenticating-directly-with-a-downstream-cluster), controlplane nodes must expose port `6443`. This port is not exposed in the default machine pool configuration to prevent it from being exposed across all cluster nodes, and to reduce the number of firewall rules created by Rancher. + +In order for ACE to work as expected, you must specify this port in the Rancher UI when configuring the controlplane machine pool by enabling the `Expose external ports` checkbox, under the `Show Advanced` section of the machine pool configuration UI. Alternatively, you may manually create a custom firewall rule in GCP and provide the related network tag in the controlplane machine-pool configuration. + +#### Internal Firewall Rules + +Rancher will automatically create a firewall rule and network tag to facilitate communication between cluster nodes internally within the specified VPC network. This rule will contain the minimum number of ports required to create an RKE2/K3s cluster. + +If you need to extend the number of ports exposed internally between cluster nodes, a new firewall rule should be manually created, and the associated network tag assigned to the relevant machine pools. If desired, the automatic creation of the internal firewall rule can be disabled for each given machine pool when creating or updating the cluster. + +#### Cross Network Deployments + +While it is possible to deploy different machine pools into different VPC networks, the internal firewall rule created by Rancher does not support this configuration by default. To create machine pools in different networks, additional firewall rules to facilitate communication between nodes in different networks must be manually created. + + +## Optional Next Steps + +After creating your cluster, you can access it through the Rancher UI. As a best practice, we recommend setting up these alternate ways of accessing your cluster: + +- **Access your cluster with the kubectl CLI:** Follow [these steps](../../../new-user-guides/manage-clusters/access-clusters/use-kubectl-and-kubeconfig.md#accessing-clusters-with-kubectl-from-your-workstation) to access clusters with kubectl on your workstation. In this case, you will be authenticated through the Rancher server’s authentication proxy, then Rancher will connect you to the downstream cluster. This method lets you manage the cluster without the Rancher UI. +- **Access your cluster with the kubectl CLI, using the authorized cluster endpoint:** Follow [these steps](../../../new-user-guides/manage-clusters/access-clusters/use-kubectl-and-kubeconfig.md#authenticating-directly-with-a-downstream-cluster) to access your cluster with kubectl directly, without authenticating through Rancher. We recommend setting up this alternative method to access your cluster so that in case you can’t connect to Rancher, you can still access the cluster. diff --git a/versioned_docs/version-2.14/how-to-guides/new-user-guides/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/create-an-amazon-ec2-cluster.md b/versioned_docs/version-2.14/how-to-guides/new-user-guides/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/create-an-amazon-ec2-cluster.md new file mode 100644 index 00000000000..07b28f311fa --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/new-user-guides/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/create-an-amazon-ec2-cluster.md @@ -0,0 +1,227 @@ +--- +title: Creating an Amazon EC2 Cluster +description: Learn the prerequisites and steps required in order for you to create an Amazon EC2 cluster using Rancher +--- + + + + + +In this section, you'll learn how to deploy an [RKE2](https://docs.rke2.io/)/[K3s](https://docs.k3s.io/) Kubernetes cluster in Amazon EC2. + +First, you will set up your EC2 cloud credentials in Rancher. + +Then you will create an EC2 cluster in Rancher, and when configuring the new cluster, you will define machine pools for it. Each machine pool will have a Kubernetes role of etcd, controlplane, or worker. Rancher will install Kubernetes on the new nodes, and it will set up each node with the Kubernetes role defined by the machine pool. + +### Prerequisites + +- **AWS EC2 Access Key and Secret Key** that will be used to create the instances. See [Amazon Documentation: Creating Access Keys](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html#Using_CreateAccessKey) how to create an Access Key and Secret Key. +- **IAM Policy created** to add to the user of the Access Key And Secret Key. See [Amazon Documentation: Creating IAM Policies (Console)](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_create.html#access_policies_create-start) how to create an IAM policy. See our three example JSON policies below: + - [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 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 + +The steps to create a cluster differ based on your Rancher version. + +### 1. Create your cloud credentials + +If you already have a set of cloud credentials to use, skip this section. + +1. Click **☰ > Cluster Management**. +1. Click **Cloud Credentials**. +1. Click **Create**. +1. Click **Amazon**. +1. Enter a name for the cloud credential. +1. In the **Default Region** field, select the AWS region where your cluster nodes will be located. +1. Enter your AWS EC2 **Access Key** and **Secret Key**. +1. Click **Create**. + +**Result:** You have created the cloud credentials that will be used to provision nodes in your cluster. + +### 2. Create your cluster + +1. Click **☰ > Cluster Management**. +1. On the **Clusters** page, click **Create**. +1. Toggle the switch to **RKE2/K3s**. +1. Click **Amazon EC2**. +1. Select a **Cloud Credential**, if more than one exists. Otherwise, it's preselected. +1. Enter a **Cluster Name**. +1. Create a machine pool for each Kubernetes role. Refer to the [best practices](use-new-nodes-in-an-infra-provider.md#node-roles) for recommendations on role assignments and counts. + 1. For each machine pool, define the machine configuration. Refer to [the EC2 machine configuration reference](../../../../reference-guides/cluster-configuration/downstream-cluster-configuration/machine-configuration/amazon-ec2.md) for information on configuration options. +1. Use the **Cluster Configuration** to choose the version of Kubernetes that will be installed, what network provider will be used and if you want to enable project network isolation. For help configuring the cluster, refer to the [RKE2](../../../../reference-guides/cluster-configuration/rancher-server-configuration/rke2-cluster-configuration.md) and [K3s](../../../../reference-guides/cluster-configuration/rancher-server-configuration/k3s-cluster-configuration.md) cluster configuration reference. +1. Use **Member Roles** to configure user authorization for the cluster. Click **Add Member** to add users that can access the cluster. Use the **Role** drop-down to set permissions for each user. +1. Click **Create**. + +**Result:** + +Your cluster is created and assigned a state of **Provisioning**. Rancher is standing up your cluster. + +You can access your cluster after its state is updated to **Active**. + +**Active** clusters are assigned two Projects: + +- `Default`, containing the `default` namespace +- `System`, containing the `cattle-system`, `ingress-nginx`, `kube-public`, and `kube-system` namespaces + +### Optional Next Steps + +After creating your cluster, you can access it through the Rancher UI. As a best practice, we recommend setting up these alternate ways of accessing your cluster: + +- **Access your cluster with the kubectl CLI:** Follow [these steps](../../../new-user-guides/manage-clusters/access-clusters/use-kubectl-and-kubeconfig.md#accessing-clusters-with-kubectl-from-your-workstation) to access clusters with kubectl on your workstation. In this case, you will be authenticated through the Rancher server’s authentication proxy, then Rancher will connect you to the downstream cluster. This method lets you manage the cluster without the Rancher UI. +- **Access your cluster with the kubectl CLI, using the authorized cluster endpoint:** Follow [these steps](../../../new-user-guides/manage-clusters/access-clusters/use-kubectl-and-kubeconfig.md#authenticating-directly-with-a-downstream-cluster) to access your cluster with kubectl directly, without authenticating through Rancher. We recommend setting up this alternative method to access your cluster so that in case you can’t connect to Rancher, you can still access the cluster. + +## IAM Policies + +### Example IAM Policy + +```json +{ + "Version": "2012-10-17", + "Statement": [ + { + "Sid": "VisualEditor0", + "Effect": "Allow", + "Action": [ + "ec2:AuthorizeSecurityGroupIngress", + "ec2:Describe*", + "ec2:ImportKeyPair", + "ec2:CreateKeyPair", + "ec2:CreateSecurityGroup", + "ec2:CreateTags", + "ec2:DeleteKeyPair", + "ec2:ModifyInstanceMetadataOptions" + ], + "Resource": "*" + }, + { + "Sid": "VisualEditor1", + "Effect": "Allow", + "Action": [ + "ec2:RunInstances" + ], + "Resource": [ + "arn:aws:ec2:REGION::image/ami-*", + "arn:aws:ec2:REGION:AWS_ACCOUNT_ID:instance/*", + "arn:aws:ec2:REGION:AWS_ACCOUNT_ID:placement-group/*", + "arn:aws:ec2:REGION:AWS_ACCOUNT_ID:volume/*", + "arn:aws:ec2:REGION:AWS_ACCOUNT_ID:subnet/*", + "arn:aws:ec2:REGION:AWS_ACCOUNT_ID:key-pair/*", + "arn:aws:ec2:REGION:AWS_ACCOUNT_ID:network-interface/*", + "arn:aws:ec2:REGION:AWS_ACCOUNT_ID:security-group/*" + ] + }, + { + "Sid": "VisualEditor2", + "Effect": "Allow", + "Action": [ + "ec2:RebootInstances", + "ec2:TerminateInstances", + "ec2:StartInstances", + "ec2:StopInstances" + ], + "Resource": "arn:aws:ec2:REGION:AWS_ACCOUNT_ID:instance/*" + } + ] +} +``` + +### Example IAM Policy with PassRole + +```json +{ + "Version": "2012-10-17", + "Statement": [ + { + "Sid": "VisualEditor0", + "Effect": "Allow", + "Action": [ + "ec2:AuthorizeSecurityGroupIngress", + "ec2:Describe*", + "ec2:ImportKeyPair", + "ec2:CreateKeyPair", + "ec2:CreateSecurityGroup", + "ec2:CreateTags", + "ec2:DeleteKeyPair", + "ec2:ModifyInstanceMetadataOptions" + ], + "Resource": "*" + }, + { + "Sid": "VisualEditor1", + "Effect": "Allow", + "Action": [ + "iam:PassRole", + "ec2:RunInstances" + ], + "Resource": [ + "arn:aws:ec2:REGION::image/ami-*", + "arn:aws:ec2:REGION:AWS_ACCOUNT_ID:instance/*", + "arn:aws:ec2:REGION:AWS_ACCOUNT_ID:placement-group/*", + "arn:aws:ec2:REGION:AWS_ACCOUNT_ID:volume/*", + "arn:aws:ec2:REGION:AWS_ACCOUNT_ID:subnet/*", + "arn:aws:ec2:REGION:AWS_ACCOUNT_ID:key-pair/*", + "arn:aws:ec2:REGION:AWS_ACCOUNT_ID:network-interface/*", + "arn:aws:ec2:REGION:AWS_ACCOUNT_ID:security-group/*", + "arn:aws:iam::AWS_ACCOUNT_ID:role/YOUR_ROLE_NAME" + ] + }, + { + "Sid": "VisualEditor2", + "Effect": "Allow", + "Action": [ + "ec2:RebootInstances", + "ec2:TerminateInstances", + "ec2:StartInstances", + "ec2:StopInstances" + ], + "Resource": "arn:aws:ec2:REGION:AWS_ACCOUNT_ID:instance/*" + } + ] +} +``` +### Example IAM Policy to allow encrypted EBS volumes +``` json +{ + "Version": "2012-10-17", + "Statement": [ + { + "Effect": "Allow", + "Action": [ + "kms:Decrypt", + "kms:GenerateDataKeyWithoutPlaintext", + "kms:Encrypt", + "kms:DescribeKey", + "kms:CreateGrant", + "ec2:DetachVolume", + "ec2:AttachVolume", + "ec2:DeleteSnapshot", + "ec2:DeleteTags", + "ec2:CreateTags", + "ec2:CreateVolume", + "ec2:DeleteVolume", + "ec2:CreateSnapshot" + ], + "Resource": [ + "arn:aws:ec2:REGION:AWS_ACCOUNT_ID:volume/*", + "arn:aws:ec2:REGION:AWS_ACCOUNT_ID:instance/*", + "arn:aws:ec2:REGION:AWS_ACCOUNT_ID:snapshot/*", + "arn:aws:kms:REGION:AWS_ACCOUNT_ID:key/KMS_KEY_ID" + ] + }, + { + "Effect": "Allow", + "Action": [ + "ec2:DescribeInstances", + "ec2:DescribeTags", + "ec2:DescribeVolumes", + "ec2:DescribeSnapshots" + ], + "Resource": "*" + } + ] +} +``` diff --git a/versioned_docs/version-2.14/how-to-guides/new-user-guides/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/create-an-azure-cluster.md b/versioned_docs/version-2.14/how-to-guides/new-user-guides/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/create-an-azure-cluster.md new file mode 100644 index 00000000000..186a95f366c --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/new-user-guides/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/create-an-azure-cluster.md @@ -0,0 +1,98 @@ +--- +title: Creating an Azure Cluster +--- + + + + + +In this section, you'll learn how to deploy an [RKE2](https://docs.rke2.io/)/[K3s](https://docs.k3s.io/) Kubernetes cluster in Azure through Rancher. + +First, you will set up your Azure cloud credentials in Rancher. + +Then you will create an Azure cluster in Rancher, and when configuring the new cluster, you will define machine pools for it. Each machine pool will have a Kubernetes role of etcd, controlplane, or worker. Rancher will install Kubernetes on the new nodes, and it will set up each node with the Kubernetes role defined by the machine pool. + +:::caution + +When the Rancher RKE2/K3s cluster is running in Azure and has an Azure load balancer in front, the outbound flow will fail. The workaround for this problem is as follows: + +- Terminate the SSL/TLS on the internal load balancer +- Use the L7 load balancer + +For more information, refer to the documentation on [Azure load balancer limitations](https://docs.microsoft.com/en-us/azure/load-balancer/components#limitations). + +::: + +For more information on configuring the Kubernetes cluster that Rancher will install on the Azure nodes, refer to the [RKE2](../../../../reference-guides/cluster-configuration/rancher-server-configuration/rke2-cluster-configuration.md) and [K3s](../../../../reference-guides/cluster-configuration/rancher-server-configuration/k3s-cluster-configuration.md) cluster configuration references. + +For more information on configuring Azure machines, refer to the [Azure machine configuration reference](../../../../reference-guides/cluster-configuration/downstream-cluster-configuration/machine-configuration/azure.md). + +- [Preparation in Azure](#preparation-in-azure) +- [Creating an Azure Cluster](#creating-an-azure-cluster) + +## Preparation in Azure + +Before a cluster can be deployed, we must configure our Azure subscription to allow the manipulation of its resources by a third party, such as Rancher. + +To do this, we will first create a new Azure **service principal (SP)** in Azure **Active Directory (AD)**, which, in Azure, is an application user who has permission to manage Azure resources. + +The following is a template `az cli` script that you have to run for creating an service principal, where you have to enter your SP name, role, and scope: + +``` +az ad sp create-for-rbac \ + --name="" \ + --role="Contributor" \ + --scopes="/subscriptions/" +``` + +The creation of this service principal returns the **application ID**, also called the **client ID**, and the **client secret**. This information is used when you create your cloud credentials. + +## Creating an Azure Cluster + +### 1. Create your cloud credentials + +If you already have a set of cloud credentials to use, skip this section. + +1. Click **☰ > Cluster Management**. +1. Click **Cloud Credentials**. +1. Click **Create**. +1. Click **Azure**. +1. Enter your Azure credentials. +1. Click **Create**. + +**Result:** You have created the cloud credentials that will be used to provision nodes in your cluster. + +### 2. Create your cluster + +Use Rancher to create a Kubernetes cluster in Azure. + +1. Click **☰ > Cluster Management**. +1. On the **Clusters** page, click **Create**. +1. Toggle the switch to **RKE2/K3s**. +1. Click **Azure**. +1. Select a **Cloud Credential**, if more than one exists. Otherwise, it's preselected. +1. Enter a **Cluster Name**. +1. Create a machine pool for each Kubernetes role. Refer to the [best practices](use-new-nodes-in-an-infra-provider.md#node-roles) for recommendations on role assignments and counts. + 1. For each machine pool, define the machine configuration. Refer to the [Azure machine configuration reference](../../../../reference-guides/cluster-configuration/downstream-cluster-configuration/machine-configuration/azure.md) for information on configuration options. +1. Use the **Cluster Configuration** to choose the version of Kubernetes that will be installed, what network provider will be used and if you want to enable project network isolation. For help configuring the cluster, refer to the [RKE2](../../../../reference-guides/cluster-configuration/rancher-server-configuration/rke2-cluster-configuration.md) and [K3s](../../../../reference-guides/cluster-configuration/rancher-server-configuration/k3s-cluster-configuration.md) cluster configuration reference. +1. Use **Member Roles** to configure user authorization for the cluster. Click **Add Member** to add users that can access the cluster. Use the **Role** drop-down to set permissions for each user. +1. Click **Create**. + +**Result:** + +Your cluster is created and assigned a state of **Provisioning**. Rancher is standing up your cluster. + +You can access your cluster after its state is updated to **Active**. + +**Active** clusters are assigned two Projects: + +- `Default`, containing the `default` namespace +- `System`, containing the `cattle-system`, `ingress-nginx`, `kube-public`, and `kube-system` namespaces + + +### Optional Next Steps + +After creating your cluster, you can access it through the Rancher UI. As a best practice, we recommend setting up these alternate ways of accessing your cluster: + +- **Access your cluster with the kubectl CLI:** Follow [these steps](../../../new-user-guides/manage-clusters/access-clusters/use-kubectl-and-kubeconfig.md#accessing-clusters-with-kubectl-from-your-workstation) to access clusters with kubectl on your workstation. In this case, you will be authenticated through the Rancher server’s authentication proxy, then Rancher will connect you to the downstream cluster. This method lets you manage the cluster without the Rancher UI. +- **Access your cluster with the kubectl CLI, using the authorized cluster endpoint:** Follow [these steps](../../../new-user-guides/manage-clusters/access-clusters/use-kubectl-and-kubeconfig.md#authenticating-directly-with-a-downstream-cluster) to access your cluster with kubectl directly, without authenticating through Rancher. We recommend setting up this alternative method to access your cluster so that in case you can’t connect to Rancher, you can still access the cluster. diff --git a/versioned_docs/version-2.14/how-to-guides/new-user-guides/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/nutanix/nutanix.md b/versioned_docs/version-2.14/how-to-guides/new-user-guides/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/nutanix/nutanix.md new file mode 100644 index 00000000000..0ecdfd2e185 --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/new-user-guides/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/nutanix/nutanix.md @@ -0,0 +1,21 @@ +--- +title: Creating a Nutanix AOS Cluster +description: Use Rancher to create a Nutanix AOS (AHV) cluster. It may consist of groups of VMs with distinct properties which allow for fine-grained control over the sizing of nodes. +--- + + + + + +[Nutanix Acropolis Operating System](https://www.nutanix.com/products/acropolis) (Nutanix AOS) is an operating system for the Nutanix hyper-converged infrastructure platform. AOS comes with a built-in hypervisor called [Acropolis Hypervisor](https://www.nutanix.com/products/ahv), or AHV. By using Rancher with Nutanix AOS (AHV), you can bring cloud operations on-premises. + +Rancher can provision nodes in AOS (AHV) and install Kubernetes on them. When creating a Kubernetes cluster in AOS, Rancher first provisions the specified number of virtual machines by communicating with the Prism Central API. Then it installs Kubernetes on top of the VMs. + +A Nutanix cluster may consist of multiple groups of VMs with distinct properties, such as the amount of memory or the number of vCPUs. This grouping allows for fine-grained control over the sizing of nodes for each Kubernetes role. + +- [Creating a Nutanix Cluster](provision-kubernetes-clusters-in-aos.md#creating-a-nutanix-aos-cluster) +- [Provisioning Storage](provision-kubernetes-clusters-in-aos.md) + +## Creating a Nutanix Cluster + +In [this section,](provision-kubernetes-clusters-in-aos.md) you'll learn how to use Rancher to install an [RKE2](https://docs.rke2.io/)/[K3s](https://docs.k3s.io/) Kubernetes cluster in Nutanix AOS. \ No newline at end of file diff --git a/versioned_docs/version-2.14/how-to-guides/new-user-guides/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/nutanix/provision-kubernetes-clusters-in-aos.md b/versioned_docs/version-2.14/how-to-guides/new-user-guides/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/nutanix/provision-kubernetes-clusters-in-aos.md new file mode 100644 index 00000000000..df67f078ac3 --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/new-user-guides/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/nutanix/provision-kubernetes-clusters-in-aos.md @@ -0,0 +1,96 @@ +--- +title: Provisioning Kubernetes Clusters in Nutanix AOS +--- + + + + + +To use Rancher to install an [RKE](https://rancher.com/docs/rke/latest/en/) Kubernetes cluster in Nutanix AOS (AHV): + +1. Locate Rancher's built-in Nutanix [node driver and activate it](../../../authentication-permissions-and-global-configuration/about-provisioning-drivers/manage-node-drivers.md#activatingdeactivating-node-drivers). + +1. Create a node template, which Rancher will use to provision nodes in Nutanix AOS. + +1. Create a Nutanix AOS cluster in Rancher. When configuring the new cluster, you will define node pools for it. Each node pool will have a Kubernetes role of etcd, controlplane, or worker. Rancher will install RKE Kubernetes on the new nodes, and it will set up each node with the Kubernetes role defined by the node pool. + +For details on configuring the Nutanix AOS node template, refer to the [Nutanix AOS node template configuration reference.](../../../../../reference-guides/cluster-configuration/downstream-cluster-configuration/node-template-configuration/nutanix.md) + +For details on configuring RKE Kubernetes clusters in Rancher, refer to the [cluster configuration reference.](../../../../../reference-guides/cluster-configuration/rancher-server-configuration/rke1-cluster-configuration.md) + +- [Preparation in Nutanix AOS](#preparation-in-nutanix-aos) +- [Creating a Nutanix AOS Cluster](#creating-a-nutanix-aos-cluster) + +## Preparation in Nutanix AOS + +The following sections describe the requirements for setting up Nutanix AOS so that Rancher can provision VMs and clusters. + +:::note + +The node templates are documented and tested with Nutanix AOS version 5.20.2 and 6.0.1. + +::: + +### Create Credentials in Nutanix AOS + +Before proceeding to create a cluster, you must ensure that you have a [Nutanix Prism Central user account](https://portal.nutanix.com/page/documents/details?targetId=Nutanix-Security-Guide-v6_0:wc-user-create-wc-t.html) with admin permissions. When you set up a node template, the template will need to use these credentials. + +### Network Permissions + +You must ensure that the hosts running the Rancher server are able to establish the following network connections: + +- To the Nutanix Prism Central API (usually port 9440/TCP). +- To port 22/TCP and 2376/TCP on the created VMs + +See [Node Networking Requirements](../../../kubernetes-clusters-in-rancher-setup/node-requirements-for-rancher-managed-clusters.md#networking-requirements) for a detailed list of port requirements applicable for creating nodes on an infrastructure provider. + +### VM-VM Anti-Affinity Policies + +Setting up [VM-VM Anti-Affinity Policies](https://portal.nutanix.com/page/documents/details?targetId=AHV-Admin-Guide-v6_1:ahv-vm-anti-affinity-t.html) is recommended. These rules allow VMs assigned the etcd and control-plane roles to operate on separate AHV hosts when they are assigned to different node pools. This practice ensures that the failure of a single physical machine does not affect the availability of those planes. + +## Creating a Nutanix AOS Cluster + +1. [Create a node template ](#1-create-a-node-template) +2. [Create a cluster with node pools using the node template](#2-create-a-cluster-with-node-pools-using-the-node-template) + +### 1. Create a node template + +Creating a [node template](../use-new-nodes-in-an-infra-provider.md#node-templates) for Nutanix AOS will allow Rancher to provision new nodes in Nutanix AOS. Node templates can be reused for other clusters. + +1. Click **☰ > Cluster Management**. +1. Click **RKE1 Configuration > Node Templates**. +1. Click **Create**. +1. Click **Add Template**. +1. Click **Nutanix**. +1. Fill out a node template for Nutanix AOS. For help filling out the form, refer to the Nutanix AOS node template [configuration reference.](../../../../../reference-guides/cluster-configuration/downstream-cluster-configuration/node-template-configuration/nutanix.md). +1. Click **Create**. + +### 2. Create a cluster with node pools using the node template + +Use Rancher to create a Kubernetes cluster in Nutanix AOS. + +1. Click **☰ > Cluster Management**. +1. On the **Clusters** page, click **Create**. +1. Click **Nutanix**. +1. Enter a **Cluster Name**, then click **Continue**. +1. Use **Member Roles** to configure user authorization for the cluster. Click **Add Member** to add users who can access the cluster. Use the **Role** drop-down to set permissions for each user. +1. Use **Cluster Options** to choose the version of Kubernetes that will be installed, what network provider will be used, and whether you want to enable project network isolation. To see more cluster options, click on **Show advanced options**. For help configuring the cluster, refer to the [RKE cluster configuration reference.](../../../../../reference-guides/cluster-configuration/rancher-server-configuration/rke1-cluster-configuration.md) +1. Add one or more node pools to your cluster. Each node pool uses a node template to provision new nodes. For more information about node pools, including best practices for assigning Kubernetes roles to the nodes, see [this section.](../use-new-nodes-in-an-infra-provider.md#node-pools) +1. Review your options to confirm they're correct. Then click **Create**. + +**Result:** Your cluster is created and assigned a state of **Provisioning**. Rancher is standing up your cluster. + +You can access your cluster after its state is updated to **Active**. + +**Active** clusters are assigned two Projects: + +- `Default`, containing the `default` namespace +- `System`, containing the `cattle-system`, `ingress-nginx`, `kube-public`, and `kube-system` namespaces + +## Optional Next Steps + +After creating your cluster, you can access it through the Rancher UI. As a best practice, we recommend setting up these alternate ways of accessing your cluster: + +- **Access your cluster with the kubectl CLI:** Follow [these steps](../../../../new-user-guides/manage-clusters/access-clusters/use-kubectl-and-kubeconfig.md#accessing-clusters-with-kubectl-from-your-workstation) to access clusters with kubectl on your workstation. In this case, you will be authenticated through the Rancher server’s authentication proxy, then Rancher will connect you to the downstream cluster. This method lets you manage the cluster without the Rancher UI. + +- **Access your cluster with the kubectl CLI, using the authorized cluster endpoint:** Follow [these steps](../../../../new-user-guides/manage-clusters/access-clusters/use-kubectl-and-kubeconfig.md#authenticating-directly-with-a-downstream-cluster) to access your cluster with kubectl directly, without authenticating through Rancher. We recommend setting up this alternative method to access your cluster so that in case you can’t connect to Rancher, you can still access the cluster. \ No newline at end of file diff --git a/versioned_docs/version-2.14/how-to-guides/new-user-guides/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/use-new-nodes-in-an-infra-provider.md b/versioned_docs/version-2.14/how-to-guides/new-user-guides/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/use-new-nodes-in-an-infra-provider.md new file mode 100644 index 00000000000..45093ee8232 --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/new-user-guides/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/use-new-nodes-in-an-infra-provider.md @@ -0,0 +1,156 @@ +--- +title: Launching Kubernetes on New Nodes in an Infrastructure Provider +--- + + + + + +When you create an RKE or RKE2 cluster using a node template in Rancher, each resulting node pool is shown in a new **Machine Pools** tab. You can see the machine pools by doing the following: + +1. Click **☰ > Cluster Management**. +1. Click the name of the RKE or RKE2 cluster. + +## RKE Clusters + +Using Rancher, you can create pools of nodes based on a [node template](#node-templates). This node template defines the parameters you want to use to launch nodes in your infrastructure providers or cloud providers. + +One benefit of installing Kubernetes on node pools hosted by an infrastructure provider is that if a node loses connectivity with the cluster, Rancher can automatically create another node to join the cluster to ensure that the count of the node pool is as expected. + +The available cloud providers to create a node template are decided based on active [node drivers](#node-drivers). + +### Node Templates + +A node template is the saved configuration for the parameters to use when provisioning nodes in a specific cloud provider. These nodes can be launched from the UI. Rancher uses [Docker Machine](https://github.com/docker/docs/blob/vnext-engine/machine/overview.md) to provision these nodes. The available cloud providers to create node templates are based on the active node drivers in Rancher. + +After you create a node template in Rancher, it's saved so that you can use this template again to create node pools. Node templates are bound to your login. After you add a template, you can remove them from your user profile. + +#### Node Labels + +You can add [labels](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/) on each node template, so that any nodes created from the node template will automatically have these labels on them. + +Invalid labels can prevent upgrades or can prevent Rancher from starting. For details on label syntax requirements, see the [Kubernetes documentation.](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/#syntax-and-character-set) + +#### Node Taints + +You can add [taints](https://kubernetes.io/docs/concepts/configuration/taint-and-toleration/) on each node template, so that any nodes created from the node template will automatically have these taints on them. + +Since taints can be added at a node template and node pool, if there is no conflict with the same key and effect of the taints, all taints will be added to the nodes. If there are taints with the same key and different effect, the taints from the node pool will override the taints from the node template. + +#### Administrator Control of Node Templates + +Administrators can control all node templates. Admins can now maintain all the node templates within Rancher. When a node template owner is no longer using Rancher, the node templates created by them can be managed by administrators so the cluster can continue to be updated and maintained. + +To access all node templates, an administrator will need to do the following: + +1. Click **☰ > Cluster Management**. +1. Click **RKE1 Configuration > Node Templates**. + +**Result:** All node templates are listed. The templates can be edited or cloned by clicking the **⋮**. + +### Node Pools + +Using Rancher, you can create pools of nodes based on a [node template](#node-templates). + +A node template defines the configuration of a node, like what operating system to use, number of CPUs, and amount of memory. + +The benefit of using a node pool is that if a node is destroyed or deleted, you can increase the number of live nodes to compensate for the node that was lost. The node pool helps you ensure that the count of the node pool is as expected. + +Each node pool must have one or more nodes roles assigned. + +Each node role (i.e. etcd, controlplane, and worker) should be assigned to a distinct node pool. Although it is possible to assign multiple node roles to a node pool, this should not be done for production clusters. + +The recommended setup is to have: + +- a node pool with the etcd node role and a count of three +- a node pool with the controlplane node role and a count of at least two +- a node pool with the worker node role and a count of at least two + +**RKE1 downstream cluster nodes in an air-gapped environment:** + +By default, Rancher tries to run the Docker Install script when provisioning RKE1 downstream cluster nodes, such as in vSphere. However, the Rancher Docker installation script would fail in air-gapped environments. To work around this issue, you may choose to skip installing Docker when creating a Node Template where Docker is pre-installed onto a VM image. You can accomplish this by selecting **None** in the dropdown list for `Docker Install URL` under **Engine Options** in the Rancher UI. + +
**Engine Options Dropdown:**
+ +![Engine Options Dropdown](/img/node-template-engine-options-rke1.png) + +#### Node Pool Taints + +If you haven't defined [taints](https://kubernetes.io/docs/concepts/configuration/taint-and-toleration/) on your node template, you can add taints for each node pool. The benefit of adding taints to a node pool is that you can change the node template without having to first ensure that the taint exists in the new template. + +For each taint, they will automatically be added to any created node in the node pool. Therefore, if you add taints to a node pool that have existing nodes, the taints won't apply to existing nodes in the node pool, but any new node added into the node pool will get the taint. + +When there are taints on the node pool and node template, if there is no conflict with the same key and effect of the taints, all taints will be added to the nodes. If there are taints with the same key and different effect, the taints from the node pool will override the taints from the node template. + +#### About Node Auto-replace + +If a node is in a node pool, Rancher can automatically replace unreachable nodes. Rancher will use the existing node template for the given node pool to recreate the node if it becomes inactive for a specified number of minutes. + +:::caution + +Self-healing node pools are designed to help you replace worker nodes for stateless applications. It is not recommended to enable node auto-replace on a node pool of master nodes or nodes with persistent volumes attached, because VMs are treated ephemerally. When a node in a node pool loses connectivity with the cluster, its persistent volumes are destroyed, resulting in data loss for stateful applications. + +::: + +Node auto-replace works on top of the Kubernetes node controller. The node controller periodically checks the status of all the nodes (configurable via the `--node-monitor-period` flag of the `kube-controller`). When a node is unreachable, the node controller will taint that node. When this occurs, Rancher will begin its deletion countdown. You can configure the amount of time Rancher waits to delete the node. If the taint is not removed before the deletion countdown ends, Rancher will proceed to delete the node object. Rancher will then provision a node in accordance with the set quantity of the node pool. + +#### Enabling Node Auto-replace + +When you create the node pool, you can specify the amount of time in minutes that Rancher will wait to replace an unresponsive node. + +1. In the form for creating or editing a cluster, go to the **Node Pools** section. +1. Go to the node pool where you want to enable node auto-replace. In the **Recreate Unreachable After** field, enter the number of minutes that Rancher should wait for a node to respond before replacing the node. +1. Fill out the rest of the form for creating or editing the cluster. + +**Result:** Node auto-replace is enabled for the node pool. + +#### Disabling Node Auto-replace + +You can disable node auto-replace from the Rancher UI with the following steps: + +1. Click **☰ > Cluster Management**. +1. On the **Clusters** page, go to the cluster where you want to disable node auto-replace and click **⋮ > Edit Config**. +1. In the **Node Pools** section, go to the node pool where you want to enable node auto-replace. In the **Recreate Unreachable After** field, enter 0. +1. Click **Save**. + +**Result:** Node auto-replace is disabled for the node pool. + +### Cloud Credentials + +Node templates can use cloud credentials to store credentials for launching nodes in your cloud provider, which has some benefits: + +- Credentials are stored as a Kubernetes secret, which is not only more secure, but it also allows you to edit a node template without having to enter your credentials every time. + +- After the cloud credential is created, it can be re-used to create additional node templates. + +- Multiple node templates can share the same cloud credential to create node pools. If your key is compromised or expired, the cloud credential can be updated in a single place, which allows all node templates that are using it to be updated at once. + +After cloud credentials are created, the user can start [managing the cloud credentials that they created](../../../../reference-guides/user-settings/manage-cloud-credentials.md). + +### Node Drivers + +If you don't find the node driver that you want to use, you can see if it is available in Rancher's built-in [node drivers and activate it](../../authentication-permissions-and-global-configuration/about-provisioning-drivers/manage-node-drivers.md#activatingdeactivating-node-drivers), or you can [add your own custom node driver](../../authentication-permissions-and-global-configuration/about-provisioning-drivers/manage-node-drivers.md#adding-custom-node-drivers). + +## RKE2 Clusters + +Rancher v2.6 introduces provisioning for [RKE2](https://docs.rke2.io/) clusters directly from the Rancher UI. RKE2, also known as RKE Government, is a fully conformant Kubernetes distribution that focuses on security and compliance within the U.S. Federal Government sector. + +:::note + +For RKE2 cluster templates, please refer to [this page](../../manage-clusters/manage-cluster-templates.md#rke2-cluster-template) for additional information. + +::: + +### Node Roles + +The RKE2 CLI exposes two roles, `server` and `agent`, which represent the Kubernetes node-roles `etcd` + `controlplane` and `worker` respectively. With RKE2 integration in Rancher v2.6, RKE2 node pools can represent more fine-grained role assignments such that `etcd` and `controlplane` roles can be represented. + +The same functionality of using `etcd`, `controlplane` and `worker` nodes is possible in the RKE2 CLI by using flags and node tainting to control where workloads and the Kubernetes master were scheduled. The reason those roles were not implemented as first-class roles in the RKE2 CLI is that RKE2 is conceptualized as a set of raw building blocks that are best leveraged through an orchestration system such as Rancher. + +The implementation of the three node roles in Rancher means that Rancher managed RKE2 clusters are able to easily leverage all of the same architectural best practices that are recommended for RKE clusters. + +In our [recommended cluster architecture](../../kubernetes-clusters-in-rancher-setup/checklist-for-production-ready-clusters/recommended-cluster-architecture.md), we outline how many nodes of each role clusters should have: + +- At least three nodes with the role etcd to survive losing one node +- At least two nodes with the role controlplane for master component high availability +- At least two nodes with the role worker for workload rescheduling upon node failure diff --git a/versioned_docs/version-2.14/how-to-guides/new-user-guides/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/vsphere/create-a-vm-template.md b/versioned_docs/version-2.14/how-to-guides/new-user-guides/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/vsphere/create-a-vm-template.md new file mode 100644 index 00000000000..b33c13a7170 --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/new-user-guides/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/vsphere/create-a-vm-template.md @@ -0,0 +1,156 @@ +--- +title: Creating a VMware vSphere Virtual Machine Template +--- + + + + + +Creating virtual machines in a repeatable and reliable fashion can often be difficult. VMware vSphere offers the ability to build one VM that can then be converted to a template. The template can then be used to create identically configured VMs. Rancher leverages this capability to create identical RKE/K3s nodes. + +In order to leverage the template to create new VMs, Rancher has some [specific requirements](#requirements) that the VM must have pre-installed. After you configure the VM with these requirements, you will next need to [prepare the VM](#preparing-your-vm) before [creating the template](#creating-a-template). Finally, once preparation is complete, the VM can be [converted to a template](#converting-to-a-template) and [moved into a content library](#moving-to-a-content-library). + + +## Requirements + +There is specific tooling required for both Linux and Windows VMs to be usable by the vSphere node driver. The most critical dependency is [cloud-init](https://cloud-init.io/) for Linux and [cloudbase-init](https://cloudbase.it/cloudbase-init/) for Windows. Both of these are used for provisioning the VMs by configuring the hostname and by setting up the SSH access and the default Rancher user. Users can add more content to these as desired if other configuration is needed. In addition, other requirements are listed below for reference. + +:::note + +If you have any specific firewall rules or configuration, you will need to add this to the VM before creating a template. + +::: + +## Linux Dependencies + +The packages that need to be installed on the template are listed below. These will have slightly different names based on distribution; for example, some distributions ship these dependencies by default. The cluster provisioner will automatically install the dependencies required for Kubernetes. The dependencies listed below are required for the functioning of the Rancher cluster provisioner (not for Kubernetes): + +* curl +* wget +* git +* net-tools +* unzip +* apparmor-parser +* ca-certificates +* cloud-init +* cloud-guest-utils +* cloud-image-utils +* growpart (part of cloud-guest-utils) +* cloud-initramfs-growroot +* open-iscsi +* openssh-server +* [open-vm-tools](https://docs.vmware.com/en/VMware-Tools/11.3.0/com.vmware.vsphere.vmwaretools.doc/GUID-8B6EA5B7-453B-48AA-92E5-DB7F061341D1.html) + +## Windows Dependencies + +The list of packages that need to be installed on the template is as follows: + +* Windows Container Feature +* [cloudbase-init](https://cloudbase.it/cloudbase-init/#download) + +## Creating a Template + +You may either manually create your VM or you can utilize [other alternatives](#alternatives-to-manual-creation) to create your VM. + +### Manual Creation +1. Manually create your VM by following [these instructions](https://docs.vmware.com/en/VMware-vSphere/7.0/com.vmware.vsphere.vm_admin.doc/GUID-AE8AFBF1-75D1-4172-988C-378C35C9FAF2.html) from VMware. Once you have a VM running, you can manually install the dependencies listed above to configure the VM correctly for the vSphere node driver. +2. Customize as needed based on your specific environment and requirements. +3. Proceed with the final preparation before creating your template. + +### Alternatives to Manual Creation + +Other alternative options to create VMs are listed below: + +* [VMware PowerCLI](https://developer.vmware.com/powercli) +* [Packer](https://www.packer.io/) +* [SaltStack](https://saltproject.io/) +* [Ansible](https://www.ansible.com/) + +Packer is a frequently-used alternative. Refer to this [reference](https://github.com/vmware-samples/packer-examples-for-vsphere) for examples of its usage with vSphere. + +## Preparing Your VM + +After creating a VM with all the required dependencies (and any additional required items), you must perform the most critical step next: preparing the VM to be turned into a template. This preparation will reset critical data such as the VM hostname, IPs, etc., to prevent that information from being brought into a new VM. If you fail to perform this step, you could create a VM with the same hostname, IP address, etc. + +Note that these preparatory steps differ between Linux and Windows. + +### Linux Preparation + +The commands below will reset your VM in Linux: + +```bash +# Cleaning logs. +if [ -f /var/log/audit/audit.log ]; then + cat /dev/null > /var/log/audit/audit.log +fi +if [ -f /var/log/wtmp ]; then + cat /dev/null > /var/log/wtmp +fi +if [ -f /var/log/lastlog ]; then + cat /dev/null > /var/log/lastlog +fi + +# Cleaning udev rules. +if [ -f /etc/udev/rules.d/70-persistent-net.rules ]; then + rm /etc/udev/rules.d/70-persistent-net.rules +fi + +# Cleaning the /tmp directories +rm -rf /tmp/* +rm -rf /var/tmp/* + +# Cleaning the SSH host keys +rm -f /etc/ssh/ssh_host_* + +# Cleaning the machine-id +truncate -s 0 /etc/machine-id +rm /var/lib/dbus/machine-id +ln -s /etc/machine-id /var/lib/dbus/machine-id + +# Cleaning the shell history +unset HISTFILE +history -cw +echo > ~/.bash_history +rm -fr /root/.bash_history + +# Truncating hostname, hosts, resolv.conf and setting hostname to localhost +truncate -s 0 /etc/{hostname,hosts,resolv.conf} +hostnamectl set-hostname localhost + +# Clean cloud-init +cloud-init clean -s -l +``` + +### Windows Preparation + +Windows has a utility called [sysprep](https://learn.microsoft.com/en-us/windows-hardware/manufacture/desktop/sysprep--generalize--a-windows-installation?view=windows-11) that is used to generalize an image and reset the same items listed above for Linux. The command is as follows: + +```PowerShell +sysprep.exe /generalize /shutdown /oobe +``` + +## Converting to a Template + +1. Shut down and stop the VM. +2. Right-click on the VM in the inventory list and select **Template**. +3. Click on **Convert to Template**. + +**Result:** Once the process has completed, a template will be available for use. + +For additional information on converting a VM to a template, see the [VMware guide](https://docs.vmware.com/en/VMware-vSphere/7.0/com.vmware.vsphere.vm_admin.doc/GUID-5B3737CC-28DB-4334-BD18-6E12011CDC9F.html). + +## Moving to a Content library + +Rancher has the ability to use templates provided by a content library. Content libraries store and manage content within vSphere, and they also offer the ability to publish and share that content. + +Below are some helpful links on content libraries: + +* [Create a content library](https://docs.vmware.com/en/VMware-vSphere/7.0/com.vmware.vsphere.vm_admin.doc/GUID-2A0F1C13-7336-45CE-B211-610D39A6E1F4.html) +* [Clone the template to the content library](https://docs.vmware.com/en/VMware-vSphere/7.0/com.vmware.vsphere.vm_admin.doc/GUID-AC1545F0-F8BA-4CD2-96EB-21B3DFAA1DC1.html) + +## Other Resources + +Here is a list of additional resources that may be useful: + +* [Tutorial for creating a Linux template](https://docs.microsoft.com/en-us/azure/cloud-adoption-framework/manage/hybrid/server/best-practices/vmware-ubuntu-template) +* [Tutorial for creating a Windows template](https://docs.microsoft.com/en-us/azure/cloud-adoption-framework/manage/hybrid/server/best-practices/vmware-windows-template) diff --git a/versioned_docs/version-2.14/how-to-guides/new-user-guides/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/vsphere/create-credentials.md b/versioned_docs/version-2.14/how-to-guides/new-user-guides/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/vsphere/create-credentials.md new file mode 100644 index 00000000000..143bea5a219 --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/new-user-guides/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/vsphere/create-credentials.md @@ -0,0 +1,49 @@ +--- +title: Creating Credentials in the VMware vSphere Console +--- + + + + + +This section describes how to create a VMware vSphere username and password. You must provide these vSphere credentials to Rancher, which allows Rancher to provision resources in vSphere. + +The following table lists the permissions required for the vSphere user account: + +| Privilege Group | Operations | +|:-------------------------|:-----------------------------------------------------------------------| +| Cns Privileges | Searchable | +| Content library | Read Storage
(Required only if deploying Template from Content Library) | +| Cryptographic operations | Direct Access | +| Datastore | AllocateSpace
Browse
FileManagement (Low level file operations)
UpdateVirtualMachineFiles
UpdateVirtualMachineMetadata | +| Global | Set custom attribute | +| Network | Assign | +| Resource | AssignVMToPool | +| Virtual Machine | Config (All)
GuestOperations (All)
Interact (All)
Inventory (All)
Provisioning (All) | +| vSphere Tagging | Assign or Unassign vSphere Tag
Assign or Unassign vSphere Tag on Object | + +The following steps create a role with the required privileges and then assign it to a new user in the vSphere console: + +1. From the **vSphere** console, go to the **Administration** page. + +2. Go to the **Roles** tab. + +3. Create a new role. Give it a name and select the privileges listed in the permissions table above. + + ![](/img/rancherroles1.png) + +4. Go to the **Users and Groups** tab. + +5. Create a new user. Fill out the form and then click **OK**. Make sure to note the username and password, because you will need it when creating cloud credentials in Rancher. + + ![](/img/rancheruser.png) + +6. Go to the **Global Permissions** tab. + +7. Create a new Global Permission. Add the user you created earlier and assign it the role you created earlier. Click **OK**. + + ![](/img/globalpermissionuser.png) + + ![](/img/globalpermissionrole.png) + +**Result:** You now have credentials that Rancher can use to manipulate vSphere resources. diff --git a/versioned_docs/version-2.14/how-to-guides/new-user-guides/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/vsphere/provision-kubernetes-clusters-in-vsphere.md b/versioned_docs/version-2.14/how-to-guides/new-user-guides/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/vsphere/provision-kubernetes-clusters-in-vsphere.md new file mode 100644 index 00000000000..88f0599cdcb --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/new-user-guides/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/vsphere/provision-kubernetes-clusters-in-vsphere.md @@ -0,0 +1,98 @@ +--- +title: Provisioning Kubernetes Clusters in VMware vSphere +--- + + + + + +In this section, you'll learn how to deploy an [RKE2](https://docs.rke2.io/)/[K3s](https://docs.k3s.io/) Kubernetes cluster in VMware vSphere. + +First, you will set up your vSphere cloud credentials in Rancher. + +Then you will create a vSphere cluster in Rancher, and when configuring the new cluster, you will define machine pools for it. Each machine pool will have a Kubernetes role of etcd, controlplane, or worker. Rancher will install Kubernetes on the new nodes, and it will set up each node with the Kubernetes role defined by the machine pool. + +- [Preparation in vSphere](#preparation-in-vmware-vsphere) +- [Creating a vSphere Cluster](#creating-a-vmware-vsphere-cluster) + +## Preparation in VMware vSphere + +This section describes the requirements for setting up vSphere so that Rancher can provision VMs and clusters. + +### Create Credentials in VMware vSphere + +Before proceeding to create a cluster, you must ensure that you have a vSphere user with sufficient permissions. + +Refer to this [how-to guide](create-credentials.md) for instructions on how to create a user in vSphere with the required permissions. These steps result in a username and password that you will need to provide to Rancher, which allows Rancher to provision resources in vSphere. + +### Network Permissions + +It must be ensured that the hosts running the Rancher server are able to establish the following network connections: + +- To the vSphere API on the vCenter server (usually port 443/TCP). +- To the Host API (port 443/TCP) on all ESXi hosts used to instantiate virtual machines for the clusters (*only required when using the ISO creation method*). +- To port 22/TCP and 2376/TCP on the created VMs + +See [Node Networking Requirements](../../../kubernetes-clusters-in-rancher-setup/node-requirements-for-rancher-managed-clusters.md#networking-requirements) for a detailed list of port requirements applicable for creating nodes on an infrastructure provider. + +### Valid ESXi License for VMware vSphere API Access + +The free ESXi license does not support API access. The vSphere servers must have a valid or evaluation ESXi license. + +### VM-VM Affinity Rules for Clusters with DRS + +If you have a cluster with DRS enabled, setting up [VM-VM Affinity Rules](https://docs.vmware.com/en/VMware-vSphere/6.5/com.vmware.vsphere.resmgmt.doc/GUID-7297C302-378F-4AF2-9BD6-6EDB1E0A850A.html) is recommended. These rules allow VMs assigned the etcd and control-plane roles to operate on separate ESXi hosts when they are assigned to different node pools. This practice ensures that the failure of a single physical machine does not affect the availability of those planes. + +## Creating a VMware vSphere Cluster + +:::note + +User-data.iso files may have become orphaned upon node deletion due to a vSphere node driver or custom clusters created before v2.9.1. While [this issue](https://github.com/rancher/rancher/issues/25073) is resolved, no automatic cleanup exists for these previously orphaned files. vSphere administrators can manually remove orphaned files, but be careful not to remove files being used by existing machines, as this may cause outages for downstream virtual machines. + +::: + +### 1. Create your cloud credentials + +1. Click **☰ > Cluster Management**. +1. Click **Cloud Credentials**. +1. Click **Create**. +1. Click **VMware vSphere**. +1. Enter your vSphere credentials. For help, refer to **Account Access** in the [node template configuration reference.](../../../../../reference-guides/cluster-configuration/downstream-cluster-configuration/node-template-configuration/vsphere.md) +1. Click **Create**. + +**Result:** You have created the cloud credentials that will be used to provision nodes in your cluster. + +### 2. Create your cluster + +Use Rancher to create a Kubernetes cluster in vSphere. + +1. In the upper left corner, click **☰ > Cluster Management**. +1. On the **Clusters** page, click **Create**. +1. Click **VMware vSphere**. +1. Enter a **Cluster Name** and use your vSphere cloud credentials. +1. Create a machine pool for each Kubernetes role. Refer to the [best practices](../use-new-nodes-in-an-infra-provider.md#node-roles) for recommendations on role assignments and counts. + 1. For each machine pool, define the machine configuration. +1. Use **Cluster Configuration** to choose the version of Kubernetes that will be installed, what network provider will be used and if you want to enable project network isolation. For help configuring the cluster, refer to the [RKE2](../../../../../reference-guides/cluster-configuration/rancher-server-configuration/rke2-cluster-configuration.md) and [K3s](../../../../../reference-guides/cluster-configuration/rancher-server-configuration/k3s-cluster-configuration.md) cluster configuration reference. +1. Use **Member Roles** to configure user authorization for the cluster. Click **Add Member** to add users that can access the cluster. Use the **Role** drop-down to set permissions for each user. +1. If you want to dynamically provision persistent storage or other infrastructure later, you will need to enable the vSphere cloud provider by modifying the cluster YAML file. For details, refer to [in-tree vSphere cloud provider docs](../../../../../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-cloud-providers/configure-in-tree-vsphere.md) and [out-of-tree vSphere cloud provider docs](../../../../../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-cloud-providers/configure-out-of-tree-vsphere.md). +1. Review your options to confirm they're correct. Then click **Create**. + +**Result:** + +Your cluster is created and assigned a state of **Provisioning**. Rancher is standing up your cluster. + +You can access your cluster after its state is updated to **Active**. + +**Active** clusters are assigned two Projects: + +- `Default`, containing the `default` namespace +- `System`, containing the `cattle-system`, `ingress-nginx`, `kube-public`, and `kube-system` namespaces + + +## Optional Next Steps + +After creating your cluster, you can access it through the Rancher UI. As a best practice, we recommend setting up these alternate ways of accessing your cluster: + +- **Access your cluster with the kubectl CLI:** Follow [these steps](../../../../new-user-guides/manage-clusters/access-clusters/use-kubectl-and-kubeconfig.md#accessing-clusters-with-kubectl-from-your-workstation) to access clusters with kubectl on your workstation. In this case, you will be authenticated through the Rancher server’s authentication proxy, then Rancher will connect you to the downstream cluster. This method lets you manage the cluster without the Rancher UI. +- **Access your cluster with the kubectl CLI, using the authorized cluster endpoint:** Follow [these steps](../../../../new-user-guides/manage-clusters/access-clusters/use-kubectl-and-kubeconfig.md#authenticating-directly-with-a-downstream-cluster) to access your cluster with kubectl directly, without authenticating through Rancher. We recommend setting up this alternative method to access your cluster so that in case you can’t connect to Rancher, you can still access the cluster. +- **Provision Storage:** For an example of how to provision storage in vSphere using Rancher, refer to [this section.](../../../manage-clusters/provisioning-storage-examples/provisioning-storage-examples.md) In order to dynamically provision storage in vSphere, the vSphere provider must be enabled. For details, refer to [in-tree vSphere cloud provider docs](../../../../../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-cloud-providers/configure-in-tree-vsphere.md) and [out-of-tree vSphere cloud provider docs](../../../../../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-cloud-providers/configure-out-of-tree-vsphere.md). diff --git a/versioned_docs/version-2.14/how-to-guides/new-user-guides/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/vsphere/shutdown-vm.md b/versioned_docs/version-2.14/how-to-guides/new-user-guides/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/vsphere/shutdown-vm.md new file mode 100644 index 00000000000..0234eadecf4 --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/new-user-guides/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/vsphere/shutdown-vm.md @@ -0,0 +1,34 @@ +--- +title: Graceful Shutdown for VMware vSphere Virtual Machines +--- + + + + + +In Rancher v2.8.3 and later, you can configure the graceful shutdown of virtual machines (VMs) for VMware vSphere node driver clusters. Graceful shutdown introduces a delay before the VM is forcibly deleted, which allows time for terminating any running processes and open connections. + +In RKE2/K3s, you can set up graceful shutdown when you create the cluster, or edit the cluster configuration to add it afterward. + +:::note + +Since Rancher can't detect the platform of an imported cluster, you cannot enable graceful shutdown on VMware vSphere clusters you have imported. + +::: + +## Enable Graceful Shutdown During VMware vSphere Cluster Creation + +In RKE2/K3s, you can configure new VMware vSphere clusters with graceful shutdown for VMs: + +1. Click **☰ > Cluster Management**. +1. Click **Create** and select **VMware vSphere** to provision a new cluster. +1. Under **Machine Pools > Scheduling**, in the **Graceful Shutdown Timeout** field, enter an integer value greater than 0. The value you enter is the amount of time in seconds Rancher waits before deleting VMs on the cluster. If the value is set to `0`, graceful shutdown is disabled. + +## Enable Graceful Shutdown in Existing RKE2/K3s Clusters + +In RKE2/K3s, you can edit the configuration of an existing VMware vSphere cluster to enable graceful shutdown, which adds a delay before deleting VMs. + +1. Click **☰ > Cluster Management**. +1. On the **Clusters** page, find the VMware vSphere hosted cluster you want to edit. Click **⋮** at the end of the row associated with the cluster. Select **Edit Config**. +1. Under **Machine Pools > Scheduling**, in the **Graceful Shutdown Timeout** field, enter an integer value greater than 0. The value you enter is the amount of time in seconds Rancher waits before deleting VMs on the cluster. If the value is set to `0`, graceful shutdown is disabled. + diff --git a/versioned_docs/version-2.14/how-to-guides/new-user-guides/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/vsphere/vsphere.md b/versioned_docs/version-2.14/how-to-guides/new-user-guides/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/vsphere/vsphere.md new file mode 100644 index 00000000000..f155dd8263d --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/new-user-guides/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/vsphere/vsphere.md @@ -0,0 +1,30 @@ +--- +title: Creating a VMware vSphere Cluster +description: Use Rancher to create a VMware vSphere cluster. It may consist of groups of VMs with distinct properties which allow for fine-grained control over the sizing of nodes. +--- + + + + + +import YouTube from '@site/src/components/YouTube' + +By using Rancher with VMware vSphere, you can bring cloud operations on-premises. + +Rancher can provision nodes in vSphere and install Kubernetes on them. When creating a Kubernetes cluster in vSphere, Rancher first provisions the specified number of virtual machines by communicating with the vCenter API. Then it installs Kubernetes on top of them. + +A vSphere cluster may consist of multiple groups of VMs with distinct properties, such as the amount of memory or the number of vCPUs. This grouping allows for fine-grained control over the sizing of nodes for each Kubernetes role. + +## Creating a VMware vSphere Cluster + +In [this section,](provision-kubernetes-clusters-in-vsphere.md) you'll learn how to use Rancher to install an [RKE2](https://docs.rke2.io/)/[K3s](https://docs.k3s.io/) Kubernetes cluster in vSphere. + +## Provisioning Storage + +For an example of how to provision storage in vSphere using Rancher, refer to [this section.](../../../manage-clusters/provisioning-storage-examples/vsphere-storage.md) In order to dynamically provision storage in vSphere, the vSphere provider must be enabled. Refer to [in-tree vSphere config](../../../kubernetes-clusters-in-rancher-setup/set-up-cloud-providers/configure-in-tree-vsphere.md) and [out-of-tree vSphere config](../../../kubernetes-clusters-in-rancher-setup/set-up-cloud-providers/configure-out-of-tree-vsphere.md). + +## Enabling the VMware vSphere Cloud Provider + +When a cloud provider is set up in Rancher, the Rancher server can automatically provision new infrastructure for the cluster, including new nodes or persistent storage devices. + +For details on enabling the vSphere cloud provider, refer to [in-tree vSphere config](../../../kubernetes-clusters-in-rancher-setup/set-up-cloud-providers/configure-in-tree-vsphere.md) and [out-of-tree vSphere config](../../../kubernetes-clusters-in-rancher-setup/set-up-cloud-providers/configure-out-of-tree-vsphere.md). diff --git a/versioned_docs/version-2.14/how-to-guides/new-user-guides/manage-clusters/access-clusters/access-clusters.md b/versioned_docs/version-2.14/how-to-guides/new-user-guides/manage-clusters/access-clusters/access-clusters.md new file mode 100644 index 00000000000..66a81355f0e --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/new-user-guides/manage-clusters/access-clusters/access-clusters.md @@ -0,0 +1,65 @@ +--- +title: Access Clusters +--- + + + + + +This section is about what tools can be used to access clusters managed by Rancher. + +For information on how to give users permission to access a cluster, see the section on [adding users to clusters.](add-users-to-clusters.md) + +For more information on roles-based access control, see [this section.](../../authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/manage-role-based-access-control-rbac.md) + +For information on how to set up an authentication system, see [this section.](../../authentication-permissions-and-global-configuration/authentication-config/authentication-config.md) + +## Clusters in Rancher UI + +There are several paths to view and manage clusters through the Rancher UI. + +### Clusters Page + +You can access the **Clusters** page from the **☰** menu: + +1. Click **☰**. +1. Select **Cluster Management**. + +You can also access the **Clusters** page by clicking the **Manage** button above the clusters table on the Rancher UI **Home** page. + +On the **Clusters** page, select **⁝** at the end of each row to view a submenu with the following options: + +* [Kubectl Shell](use-kubectl-and-kubeconfig.md) +* Download KubeConfig +* Copy KubeConfig to Clipboard +* Edit Config +* View YAML +* Download YAML + +### Cluster Dashboard + +On the **Clusters** page, select the **Explore** button at the end of each row to view that cluster's **Cluster Dashboard**. You can also view the dashboard by clicking the name of a cluster in the table, then clicking the **Explore** buttton on the **Cluster** page. + +The **Cluster Dashboard** is also accessible from the Rancher UI **Home** page, by clicking on the name of a cluster. + +You can also access the **Cluster Dashboard** from the **☰** in the top navigation bar: + +1. Click **☰**. +1. Select the name of a cluster from the **Explore Cluster** menu option. + +The **Cluster Dashboard** lists information about a specific cluster, such as number of nodes, memory usage, events, and resources. + +## kubectl + +You can use the Kubernetes command-line tool, [kubectl](https://kubernetes.io/docs/reference/kubectl/overview/), to manage your clusters. You have two options for using kubectl: + +- **Rancher kubectl shell:** Interact with your clusters by launching a kubectl shell available in the Rancher UI. This option requires no configuration actions on your part. For more information, see [Accessing Clusters with kubectl Shell](use-kubectl-and-kubeconfig.md). +- **Terminal remote connection:** You can also interact with your clusters by installing [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/) on your local desktop and then copying the cluster's kubeconfig file to your local `~/.kube/config` directory. For more information, see [Accessing Clusters with kubectl and a kubeconfig File](use-kubectl-and-kubeconfig.md). + +## Rancher CLI + +You can control your clusters by downloading Rancher's own command-line interface, [Rancher CLI](../../../../reference-guides/cli-with-rancher/cli-with-rancher.md). This CLI tool can interact directly with different clusters and projects or pass them `kubectl` commands. + +## Rancher API + +Finally, you can interact with your clusters over the Rancher API. Before you use the API, you must obtain an [API key](../../../../reference-guides/user-settings/api-keys.md). To view the different resource fields and actions for an API object, open the API UI, which can be accessed by clicking on **View in API** for any Rancher UI object. diff --git a/versioned_docs/version-2.14/how-to-guides/new-user-guides/manage-clusters/access-clusters/add-users-to-clusters.md b/versioned_docs/version-2.14/how-to-guides/new-user-guides/manage-clusters/access-clusters/add-users-to-clusters.md new file mode 100644 index 00000000000..c6cadc9836a --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/new-user-guides/manage-clusters/access-clusters/add-users-to-clusters.md @@ -0,0 +1,78 @@ +--- +title: Adding Users to Clusters +--- + + + + + +To provide a user access to view certain cluster-level resources and create new projects, assign the user a **Cluster Membership**. Cluster members can create projects and manage resources in those projects. However, not all resources, namespaces and workloads in a cluster are accessible by cluster members. + +:::tip + +Want to provide a user with access to a _specific_ project within a cluster? See [Adding Project Members](../../../new-user-guides/add-users-to-projects.md) instead. + +::: + +There are two contexts where you can add cluster members: + +- Adding Members to a New Cluster + + You can add members to a cluster as you create it (recommended if possible). + +- [Adding Members to an Existing Cluster](#editing-cluster-membership) + + You can always add members to a cluster after a cluster is provisioned. + +## Editing Cluster Membership + +Cluster administrators can edit the membership for a cluster, controlling which Rancher users can access the cluster and what features they can use. + +1. Click **☰ > Cluster Management**. +1. Go to the cluster you want to add members to and click **⋮ > Edit Config**. +1. In the **Member Roles** tab, click **Add Member**. +1. Search for the user or group that you want to add to the cluster. + + :::note Notes: + + - At least 2 characters must be typed in the search box for results to appear. + - Users can be searched based on their username or display name. + - Search is prefix-based (e.g., a user named `Stan Dard` will appear when searching for `Sta`, but not when searching for `Dar`) and case-sensitive. + + ::: + + If external authentication is configured: + + - Rancher returns users from your [external authentication](../../authentication-permissions-and-global-configuration/authentication-config/authentication-config.md) source as you type. + + :::note Using AD but can't find your users? + + There may be an issue with your search attribute configuration. See [Configuring Active Directory Authentication: Step 5](../../../new-user-guides/authentication-permissions-and-global-configuration/authentication-config/configure-active-directory.md). + + ::: + + - A drop-down allows you to add groups instead of individual users. The drop-down only lists groups that you, the logged in user, are part of. + + :::note + + If you are logged in as a local user, external users do not display in your search results. For more information, see [External Authentication Configuration and Principal Users](../../authentication-permissions-and-global-configuration/authentication-config/authentication-config.md#external-authentication-configuration-and-principal-users). + + ::: + +1. Assign the user or group **Cluster** roles. + + [What are Cluster Roles?](../../../new-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/cluster-and-project-roles.md) + + :::tip + + For Custom Roles, you can modify the list of individual roles available for assignment. + + - To add roles to the list, [Add a Custom Role](../../../new-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/custom-roles.md). + - To remove roles from the list, [Lock/Unlock Roles](../../../new-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/locked-roles.md). + + ::: + +**Result:** The chosen users are added to the cluster. + +- To revoke cluster membership, select the user and click **Delete**. This action deletes membership, not the user. +- To modify a user's roles in the cluster, delete them from the cluster, and then re-add them with modified roles. diff --git a/versioned_docs/version-2.14/how-to-guides/new-user-guides/manage-clusters/access-clusters/authorized-cluster-endpoint.md b/versioned_docs/version-2.14/how-to-guides/new-user-guides/manage-clusters/access-clusters/authorized-cluster-endpoint.md new file mode 100644 index 00000000000..328537bb4fd --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/new-user-guides/manage-clusters/access-clusters/authorized-cluster-endpoint.md @@ -0,0 +1,53 @@ +--- +title: How the Authorized Cluster Endpoint Works +--- + + + + + +This section describes how the kubectl CLI, the kubeconfig file, and the authorized cluster endpoint work together to allow you to access a downstream Kubernetes cluster directly, without authenticating through the Rancher server. It is intended to provide background information and context to the instructions for [how to set up kubectl to directly access a cluster.](use-kubectl-and-kubeconfig.md#authenticating-directly-with-a-downstream-cluster) + +### About the Kubeconfig File + +The kubeconfig file is used to configure access to Kubernetes when used in conjunction with the kubectl command line tool (or other clients). + +The kubeconfig file and its contents are specific to each cluster. It can be downloaded from the **Clusters** page in Rancher: + +1. Click **☰** in the top left corner. +1. Select **Cluster Management**. +1. Find the cluster whose kubeconfig you want to download, and select **⁝** at the end of the row. +1. Select **Download KubeConfig** from the submenu. + +You need a separate kubeconfig file for each cluster that you have access to in Rancher. + +After you download the kubeconfig file, you are able to use the kubeconfig file and its Kubernetes [contexts](https://kubernetes.io/docs/reference/kubectl/cheatsheet/#kubectl-context-and-configuration) to access your downstream cluster. + +If admins have [kubeconfig token generation turned off](../../../../api/api-tokens.md#disable-tokens-in-generated-kubeconfigs), the kubeconfig file requires that the [Rancher CLI](../../../../reference-guides/cli-with-rancher/rancher-cli.md) to be present in your PATH. + +### Two Authentication Methods for RKE Clusters + +If the cluster is not an [RKE cluster,](../../launch-kubernetes-with-rancher/launch-kubernetes-with-rancher.md) the kubeconfig file allows you to access the cluster in only one way: it lets you be authenticated with the Rancher server, then Rancher allows you to run kubectl commands on the cluster. + +For RKE clusters, the kubeconfig file allows you to be authenticated in two ways: + +- **Through the Rancher server authentication proxy:** Rancher's authentication proxy validates your identity, then connects you to the downstream cluster that you want to access. +- **Directly with the downstream cluster's API server:** RKE clusters have an authorized cluster endpoint enabled by default. This endpoint allows you to access your downstream Kubernetes cluster with the kubectl CLI and a kubeconfig file, and it is enabled by default for RKE clusters. In this scenario, the downstream cluster's Kubernetes API server authenticates you by calling a webhook (the `kube-api-auth` microservice) that Rancher set up. + +This second method, the capability to connect directly to the cluster's Kubernetes API server, is important because it lets you access your downstream cluster if you can't connect to Rancher. + +To use the authorized cluster endpoint, you need to configure kubectl to use the extra kubectl context in the kubeconfig file that Rancher generates for you when the RKE cluster is created. This file can be downloaded from the cluster view in the Rancher UI, and the instructions for configuring kubectl are on [this page.](use-kubectl-and-kubeconfig.md#authenticating-directly-with-a-downstream-cluster) + +These methods of communicating with downstream Kubernetes clusters are also explained in the [architecture page](../../../../reference-guides/rancher-manager-architecture/communicating-with-downstream-user-clusters.md) in the larger context of explaining how Rancher works and how Rancher communicates with downstream clusters. + +### About the kube-api-auth Authentication Webhook + +The `kube-api-auth` microservice is deployed to provide the user authentication functionality for the [authorized cluster endpoint](../../../../reference-guides/rancher-manager-architecture/communicating-with-downstream-user-clusters.md#4-authorized-cluster-endpoint). When you access the user cluster using `kubectl`, the cluster's Kubernetes API server authenticates you by using the `kube-api-auth` service as a webhook. + +During cluster provisioning, the file `/etc/kubernetes/kube-api-authn-webhook.yaml` is deployed and `kube-apiserver` is configured with `--authentication-token-webhook-config-file=/etc/kubernetes/kube-api-authn-webhook.yaml`. This configures the `kube-apiserver` to query `http://127.0.0.1:6440/v1/authenticate` to determine authentication for bearer tokens. + +The scheduling rules for `kube-api-auth` are listed below: + +| Component | nodeAffinity nodeSelectorTerms | nodeSelector | Tolerations | +| -------------------- | ------------------------------------------ | ------------ | ------------------------------------------------------------------------------ | +| kube-api-auth | `beta.kubernetes.io/os:NotIn:windows`
`node-role.kubernetes.io/controlplane:In:"true"` | none | `operator:Exists` | diff --git a/versioned_docs/version-2.14/how-to-guides/new-user-guides/manage-clusters/access-clusters/use-kubectl-and-kubeconfig.md b/versioned_docs/version-2.14/how-to-guides/new-user-guides/manage-clusters/access-clusters/use-kubectl-and-kubeconfig.md new file mode 100644 index 00000000000..4919f5717dc --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/new-user-guides/manage-clusters/access-clusters/use-kubectl-and-kubeconfig.md @@ -0,0 +1,109 @@ +--- +title: "Access a Cluster with Kubectl and kubeconfig" +description: "Learn how you can access and manage your Kubernetes clusters using kubectl with kubectl Shell or with kubectl CLI and kubeconfig file. A kubeconfig file is used to configure access to Kubernetes. When you create a cluster with Rancher, it automatically creates a kubeconfig for your cluster." +--- + + + + + +This section describes how to manipulate your downstream Kubernetes cluster with kubectl from the Rancher UI or from your workstation. + +For more information on using kubectl, see [Kubernetes Documentation: Overview of kubectl](https://kubernetes.io/docs/reference/kubectl/overview/). + +### Accessing Clusters with kubectl Shell in the Rancher UI + +You can access and manage your clusters by logging into Rancher and opening the kubectl shell in the UI. No further configuration necessary. + +1. Click **☰ > Cluster Management**. +1. Go to the cluster you want to access with kubectl and click **Explore**. +1. In the top navigation menu, click the **Kubectl Shell** button. Use the window that opens to interact with your Kubernetes cluster. + +### Accessing Clusters with kubectl from Your Workstation + +This section describes how to download your cluster's kubeconfig file, launch kubectl from your workstation, and access your downstream cluster. + +This alternative method of accessing the cluster allows you to authenticate with Rancher and manage your cluster without using the Rancher UI. + +:::note Prerequisites: + +These instructions assume that you have already created a Kubernetes cluster, and that kubectl is installed on your workstation. For help installing kubectl, refer to the official [Kubernetes documentation.](https://kubernetes.io/docs/tasks/tools/install-kubectl/) + +::: + +1. Click **☰** in the top left corner. +1. Select **Cluster Management**. +1. Find the cluster whose kubeconfig you want to download, and select **⁝** at the end of the row. +1. Select **Download KubeConfig** from the submenu. +1. Save the YAML file on your local computer. Move the file to `~/.kube/config`. Note: The default location that kubectl uses for the kubeconfig file is `~/.kube/config`, but you can use any directory and specify it using the `--kubeconfig` flag, as in this command: + ``` + kubectl --kubeconfig /custom/path/kube.config get pods + ``` +1. From your workstation, launch kubectl. Use it to interact with your kubernetes cluster. + + +### Note on Resources Created Using kubectl + +Rancher will discover and show resources created by `kubectl`. However, these resources might not have all the necessary annotations on discovery. If an operation (for instance, scaling the workload) is done to the resource using the Rancher UI/API, this may trigger recreation of the resources due to the missing annotations. This should only happen the first time an operation is done to the discovered resource. + +## Authenticating Directly with a Downstream Cluster + +This section intended to help you set up an alternative method to access a [Rancher-launched cluster.](../../launch-kubernetes-with-rancher/launch-kubernetes-with-rancher.md) + +This method is only available RKE2 and K3s clusters that have the [authorized cluster endpoint](../../../../reference-guides/rancher-manager-architecture/communicating-with-downstream-user-clusters.md#4-authorized-cluster-endpoint) enabled. When Rancher creates the cluster, it generates a kubeconfig file that includes additional kubectl context(s) for accessing your cluster. This additional context allows you to use kubectl to authenticate with the downstream cluster without authenticating through Rancher. For a longer explanation of how the authorized cluster endpoint works, refer to [this page](authorized-cluster-endpoint.md). + +On RKE2 and K3s clusters, you need to [manually enable](../../kubernetes-clusters-in-rancher-setup/register-existing-clusters.md#authorized-cluster-endpoint-support-for-rke2-and-k3s-clusters) authorized cluster endpoints. + +We recommend that as a best practice, you should set up this method to access your RKE2 and K3s clusters, so that just in case you can’t connect to Rancher, you can still access the cluster. + +:::note Prerequisites: + +The following steps assume that you have created a Kubernetes cluster and followed the steps to [connect to your cluster with kubectl from your workstation.](#accessing-clusters-with-kubectl-from-your-workstation) + +::: + +To find the name of the context(s) in your downloaded kubeconfig file, run: + +``` +kubectl config get-contexts --kubeconfig /custom/path/kube.config +CURRENT NAME CLUSTER AUTHINFO NAMESPACE +* my-cluster my-cluster user-46tmn + my-cluster-controlplane-1 my-cluster-controlplane-1 user-46tmn +``` + +In this example, when you use `kubectl` with the first context, `my-cluster`, you will be authenticated through the Rancher server. + +With the second context, `my-cluster-controlplane-1`, you would authenticate with the authorized cluster endpoint, communicating with an downstream RKE2/K3s cluster directly. + +We recommend using a load balancer with the authorized cluster endpoint. For details, refer to the [recommended architecture section.](../../../../reference-guides/rancher-manager-architecture/architecture-recommendations.md#architecture-for-an-authorized-cluster-endpoint-ace) + +Now that you have the name of the context needed to authenticate directly with the cluster, you can pass the name of the context in as an option when running kubectl commands. The commands will differ depending on whether your cluster has an FQDN defined. Examples are provided in the sections below. + +When `kubectl` works normally, it confirms that you can access your cluster while bypassing Rancher's authentication proxy. + +### Connecting Directly to Clusters with FQDN Defined + +If an FQDN is defined for the cluster, a single context referencing the FQDN will be created. The context will be named `-fqdn`. When you want to use `kubectl` to access this cluster without Rancher, you will need to use this context. + +Assuming the kubeconfig file is located at `~/.kube/config`: + +``` +kubectl --context -fqdn get nodes +``` +Directly referencing the location of the kubeconfig file: +``` +kubectl --kubeconfig /custom/path/kube.config --context -fqdn get pods +``` + +### Connecting Directly to Clusters without FQDN Defined + +If there is no FQDN defined for the cluster, extra contexts will be created referencing the IP address of each node in the control plane. Each context will be named `-`. When you want to use `kubectl` to access this cluster without Rancher, you will need to use this context. + +Assuming the kubeconfig file is located at `~/.kube/config`: +``` +kubectl --context - get nodes +``` +Directly referencing the location of the kubeconfig file: +``` +kubectl --kubeconfig /custom/path/kube.config --context - get pods +``` diff --git a/versioned_docs/version-2.14/how-to-guides/new-user-guides/manage-clusters/clean-cluster-nodes.md b/versioned_docs/version-2.14/how-to-guides/new-user-guides/manage-clusters/clean-cluster-nodes.md new file mode 100644 index 00000000000..8dfc8c2daf1 --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/new-user-guides/manage-clusters/clean-cluster-nodes.md @@ -0,0 +1,382 @@ +--- +title: Removing Kubernetes Components from Nodes +description: Learn about cluster cleanup when removing nodes from your Rancher-launched Kubernetes cluster. What is removed, how to do it manually +--- + + + + + +This section describes how to disconnect a node from a Rancher-launched Kubernetes cluster and remove all of the Kubernetes components from the node. This process allows you to use the node for other purposes. + +When you use Rancher to install Kubernetes on new nodes in an infrastructure provider, resources (containers/virtual network interfaces) and configuration items (certificates/configuration files) are created. + +When removing nodes from your Rancher launched Kubernetes cluster (provided that they are in `Active` state), those resources are automatically cleaned, and the only action needed is to restart the node. When a node has become unreachable and the automatic cleanup process cannot be used, we describe the steps that need to be executed before the node can be added to a cluster again. + +## What Gets Removed? + +When cleaning nodes provisioned using Rancher, the following components are deleted based on the type of cluster node you're removing. + +| Removed Component | [Nodes Hosted by Infrastructure Provider][1] | [Custom Nodes][2] | [Hosted Cluster][3] | [Registered Nodes][4] | +|--------------------------------------------------------------------------------|----------------------------------------------|-------------------|---------------------|-----------------------| +| The Rancher deployment namespace (`cattle-system` by default) | ✓ | ✓ | ✓ | ✓ | +| `serviceAccount`, `clusterRoles`, and `clusterRoleBindings` labeled by Rancher | ✓ | ✓ | ✓ | ✓ | +| Labels, Annotations, and Finalizers | ✓ | ✓ | ✓ | ✓ | +| Rancher Deployment | ✓ | ✓ | ✓ | | +| Machines, clusters, projects, and user custom resource definitions (CRDs) | ✓ | ✓ | ✓ | | +| All resources create under the `management.cattle.io` API Group | ✓ | ✓ | ✓ | | +| All CRDs created by Rancher v2.x | ✓ | ✓ | ✓ | | + +[1]: ../launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/use-new-nodes-in-an-infra-provider.md +[2]: ../../../reference-guides/cluster-configuration/rancher-server-configuration/use-existing-nodes/use-existing-nodes.md +[3]: ../kubernetes-clusters-in-rancher-setup/set-up-clusters-from-hosted-kubernetes-providers/set-up-clusters-from-hosted-kubernetes-providers.md +[4]: ../../../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/register-existing-clusters.md + +## Removing a Node from a Cluster by Rancher UI + +When the node is in `Active` state, removing the node from a cluster will trigger a process to clean up the node. Please restart the node after the automatic cleanup process is done to make sure any non-persistent data is properly removed. + +**To restart a node:** + +``` +# using reboot +$ sudo reboot + +# using shutdown +$ sudo shutdown -r now +``` + +## Removing Rancher Components from a Cluster Manually + +When a node is unreachable and removed from the cluster, the automatic cleaning process can't be triggered because the node is unreachable. Please follow the steps below to manually remove the Rancher components. + +:::danger + +The commands listed below will remove data from the node. Make sure you have created a backup of files you want to keep before executing any of the commands as data will be lost. + +::: + +### Removing Rancher Components from Registered Clusters + +For registered clusters, the process for removing Rancher is a little different. You have the option of simply deleting the cluster in the Rancher UI, or your can run a script that removes Rancher components from the nodes. Both options make the same deletions. + +After the registered cluster is detached from Rancher, the cluster's workloads will be unaffected and you can access the cluster using the same methods that you did before the cluster was registered into Rancher. + + + + +:::danger + +This process will remove data from your cluster. Make sure you have created a backup of files you want to keep before executing the command, as data will be lost. + +::: + +After you initiate the removal of a registered cluster using the Rancher UI (or API), the following events occur. + +1. Rancher creates a `serviceAccount` that it uses to remove the Rancher components from the cluster. This account is assigned the [clusterRole](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#role-and-clusterrole) and [clusterRoleBinding](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#rolebinding-and-clusterrolebinding) permissions, which are required to remove the Rancher components. + +1. Using the `serviceAccount`, Rancher schedules and runs a [job](https://kubernetes.io/docs/concepts/workloads/controllers/jobs-run-to-completion/) that cleans the Rancher components off of the cluster. This job also references the `serviceAccount` and its roles as dependencies, so the job deletes them before its completion. + +1. Rancher is removed from the cluster. However, the cluster persists, running the native version of Kubernetes. + +**Result:** All components listed for registered clusters in [What Gets Removed?](#what-gets-removed) are deleted. + + + + +Rather than cleaning registered cluster nodes using the Rancher UI, you can run a script instead. + +:::note Prerequisite: + +Install [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/). + +::: + +1. Open a web browser, navigate to [GitHub](https://github.com/rancher/rancher/blob/master/cleanup/user-cluster.sh), and download `user-cluster.sh`. + +1. Make the script executable by running the following command from the same directory as `user-cluster.sh`: + + ``` + chmod +x user-cluster.sh + ``` + +1. **Air Gap Environments Only:** Open `user-cluster.sh` and replace `yaml_url` with the URL in `user-cluster.yml`. + + If you don't have an air gap environment, skip this step. + +1. From the same directory, run the script and provide the `rancher/rancher-agent` image version which should be equal to the version of Rancher used to manage the cluster. (``): + + :::tip + + Add the `-dry-run` flag to preview the script's outcome without making changes. + ``` + ./user-cluster.sh rancher/rancher-agent: + ``` + + ::: + +**Result:** The script runs. All components listed for registered clusters in [What Gets Removed?](#what-gets-removed) are deleted. + + + + +## Cleaning up Nodes + + + + +:::note + +For instructions on cleaning nodes in RKE2 clusters that weren't deployed by Rancher, see the [official RKE2 documentation](https://docs.rke2.io/install/uninstall) on uninstalling clusters. + +::: + +You need to remove the following components from Rancher-provisioned RKE2 nodes: + +* The rancher-system-agent, which connects to Rancher and installs and manages RKE2. +* RKE2 itself. + +### Removing rancher-system-agent + +To remove the rancher-system-agent, run the [system-agent-uninstall.sh](https://github.com/rancher/system-agent/blob/main/system-agent-uninstall.sh) script: + +``` +curl https://raw.githubusercontent.com/rancher/system-agent/main/system-agent-uninstall.sh > system-agent-uninstall.sh +sudo sh system-agent-uninstall.sh +``` + +### Removing RKE2 + +To remove the RKE2 installation, run the `rke2-uninstall` script that is already present on the node: + +``` +sudo rke2-uninstall.sh +``` + + + + +You need to remove the following components from Rancher-provisioned K3s nodes: + +* The rancher-system-agent, which connects to Rancher and installs and manages K3s. +* K3s itself. + +### Removing rancher-system-agent + +To remove the rancher-system-agent, run the [system-agent-uninstall.sh](https://github.com/rancher/system-agent/blob/main/system-agent-uninstall.sh) script: + +``` +curl https://raw.githubusercontent.com/rancher/system-agent/main/system-agent-uninstall.sh > system-agent-uninstall.sh +sudo sh system-agent-uninstall.sh +``` + +### Removing K3s + +To remove the K3s installation, run the `k3s-uninstall` script that is already present on the node: + +``` +sudo k3s-uninstall.sh +``` + + + + +### Directories and Files + +The following directories are used when adding a node to a cluster, and should be removed. You can remove a directory using `rm -rf /directory_name`. + +:::important + +Depending on the role you assigned to the node, certain directories may or may not be present on the node. + +::: + + + + +| Directories | +|------------------------------| +| `/etc/ceph` | +| `/etc/cni` | +| `/etc/kubernetes` | +| `/etc/rancher` | +| `/opt/cni` | +| `/run/calico` | +| `/run/flannel` | +| `/run/secrets/kubernetes.io` | +| `/var/lib/calico` | +| `/var/lib/cni` | +| `/var/lib/etcd` | +| `/var/lib/kubelet` | +| `/var/lib/rancher` | +| `/var/lib/weave` | +| `/var/log/containers` | +| `/var/log/pods` | +| `/var/run/calico` | + +**To clean the directories:** + +```shell +rm -rf /etc/ceph \ + /etc/cni \ + /etc/kubernetes \ + /etc/rancher \ + /opt/cni \ + /run/calico \ + /run/flannel \ + /run/secrets/kubernetes.io \ + /var/lib/calico \ + /var/lib/cni \ + /var/lib/etcd \ + /var/lib/kubelet \ + /var/lib/rancher \ + /var/lib/weave \ + /var/log/containers \ + /var/log/pods \ + /var/run/calico +``` + + + + +| Directories | +|------------------------------| +| `/etc/ceph` | +| `/etc/cni` | +| `/etc/kubernetes` | +| `/etc/rancher` | +| `/etc/systemd/system/k3s` | +| `/opt/cni` | +| `/run/calico` | +| `/run/flannel` | +| `/run/secrets/kubernetes.io` | +| `/usr/local/bin/k3s` | +| `/var/lib/calico` | +| `/var/lib/cni` | +| `/var/lib/etcd` | +| `/var/lib/kubelet` | +| `/var/lib/rancher` | +| `/var/lib/weave` | +| `/var/log/containers` | +| `/var/log/pods` | +| `/var/run/calico` | + +**To clean the directories:** + +```shell +rm -rf /etc/ceph \ + /etc/cni \ + /etc/kubernetes \ + /etc/rancher \ + /etc/systemd/system/k3s \ + /opt/cni \ + /run/calico \ + /run/flannel \ + /run/secrets/kubernetes.io \ + /usr/local/bin/k3s \ + /var/lib/calico \ + /var/lib/cni \ + /var/lib/etcd \ + /var/lib/kubelet \ + /var/lib/rancher \ + /var/lib/weave \ + /var/log/containers \ + /var/log/pods \ + /var/run/calico +``` + + + + +### Network Interfaces and Iptables + +The remaining two components that are changed/configured are (virtual) network interfaces and iptables rules. Both are non-persistent to the node, meaning that they will be cleared after a restart of the node. To remove these components, a restart is recommended. + +**To restart a node:** + +``` +# using reboot +$ sudo reboot + +# using shutdown +$ sudo shutdown -r now +``` + +If you want to know more on (virtual) network interfaces or iptables rules, please see the specific subjects below. + +### Network Interfaces + +:::note + +Depending on the network provider configured for the cluster the node was part of, some of the interfaces will or won't be present on the node. + +::: + +| Interfaces | +|--------------------------------------------| +| `flannel.1` | +| `cni0` | +| `tunl0` | +| `caliXXXXXXXXXXX` (random interface names) | +| `vethXXXXXXXX` (random interface names) | + +**To list all interfaces:** + +``` +# Using ip +ip address show + +# Using ifconfig +ifconfig -a +``` + +**To remove an interface:** + +``` +ip link delete interface_name +``` + +### Iptables + +:::note + +Depending on the network provider configured for the cluster the node was part of, some of the chains will or won't be present on the node. + +::: + +Iptables rules are used to route traffic from and to containers. The created rules are not persistent, so restarting the node will restore iptables to its original state. + +| Chains | +|--------------------------------------------------| +| `cali-failsafe-in` | +| `cali-failsafe-out` | +| `cali-fip-dnat` | +| `cali-fip-snat` | +| `cali-from-hep-forward` | +| `cali-from-host-endpoint` | +| `cali-from-wl-dispatch` | +| `cali-fw-caliXXXXXXXXXXX` (random chain names) | +| `cali-nat-outgoing` | +| `cali-pri-kns.NAMESPACE` (chain per namespace) | +| `cali-pro-kns.NAMESPACE` (chain per namespace) | +| `cali-to-hep-forward` | +| `cali-to-host-endpoint` | +| `cali-to-wl-dispatch` | +| `cali-tw-caliXXXXXXXXXXX` (random chain names) | +| `cali-wl-to-host` | +| `KUBE-EXTERNAL-SERVICES` | +| `KUBE-FIREWALL` | +| `KUBE-MARK-DROP` | +| `KUBE-MARK-MASQ` | +| `KUBE-NODEPORTS` | +| `KUBE-SEP-XXXXXXXXXXXXXXXX` (random chain names) | +| `KUBE-SERVICES` | +| `KUBE-SVC-XXXXXXXXXXXXXXXX` (random chain names) | + +**To list all iptables rules:** + +``` +iptables -L -t nat +iptables -L -t mangle +iptables -L +``` diff --git a/versioned_docs/version-2.14/how-to-guides/new-user-guides/manage-clusters/create-kubernetes-persistent-storage/create-kubernetes-persistent-storage.md b/versioned_docs/version-2.14/how-to-guides/new-user-guides/manage-clusters/create-kubernetes-persistent-storage/create-kubernetes-persistent-storage.md new file mode 100644 index 00000000000..67a8c9dffbd --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/new-user-guides/manage-clusters/create-kubernetes-persistent-storage/create-kubernetes-persistent-storage.md @@ -0,0 +1,78 @@ +--- +title: Create Kubernetes Persistent Volumes and Storage Classes +description: "Learn about the two ways with which you can create persistent storage in Kubernetes: persistent volumes and storage classes" +--- + + + + + +When deploying an application that needs to retain data, you'll need to create persistent storage. Persistent storage allows you to store application data external from the pod running your application. This storage practice allows you to maintain application data, even if the application's pod fails. + +The documents in this section assume that you understand the Kubernetes concepts of persistent volumes, persistent volume claims, and storage classes. For more information, refer to the section on [how storage works.](manage-persistent-storage/about-persistent-storage.md) + +### Prerequisites + +To set up persistent storage, the `Manage Volumes` [role](../../authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/cluster-and-project-roles.md#project-role-reference) is required. + +If you are provisioning storage for a cluster hosted in the cloud, the storage and cluster hosts must have the same cloud provider. + +For provisioning new storage with Rancher, the cloud provider must be enabled. For details on enabling cloud providers, refer to [this page.](../../kubernetes-clusters-in-rancher-setup/set-up-cloud-providers/set-up-cloud-providers.md) + +For attaching existing persistent storage to a cluster, the cloud provider does not need to be enabled. + +### Setting up Existing Storage + +The overall workflow for setting up existing storage is as follows: + +1. Set up your persistent storage. This may be storage in an infrastructure provider, or it could be your own storage. +2. Add a persistent volume (PV) that refers to the persistent storage. +3. Add a persistent volume claim (PVC) that refers to the PV. +4. Mount the PVC as a volume in your workload. + +For details and prerequisites, refer to [this page.](manage-persistent-storage/set-up-existing-storage.md) + +### Dynamically Provisioning New Storage in Rancher + +The overall workflow for provisioning new storage is as follows: + +1. Add a StorageClass and configure it to use your storage provider. The StorageClass could refer to storage in an infrastructure provider, or it could refer to your own storage. +2. Add a persistent volume claim (PVC) that refers to the storage class. +3. Mount the PVC as a volume for your workload. + +For details and prerequisites, refer to [this page.](manage-persistent-storage/dynamically-provision-new-storage.md) + +### Longhorn Storage + +[Longhorn](https://longhorn.io/) is a lightweight, reliable and easy-to-use distributed block storage system for Kubernetes. + +Longhorn is free, open source software. Originally developed by Rancher Labs, it is now being developed as a sandbox project of the Cloud Native Computing Foundation. It can be installed on any Kubernetes cluster with Helm, with kubectl, or with the Rancher UI. + +If you have a pool of block storage, Longhorn can help you provide persistent storage to your Kubernetes cluster without relying on cloud providers. For more information about Longhorn features, refer to the [documentation.](https://longhorn.io/docs/latest/what-is-longhorn/) + +Rancher v2.5 simplified the process of installing Longhorn on a Rancher-managed cluster. For more information, see [Cloud Native Storage with Longhorn](../../../../integrations-in-rancher/longhorn/longhorn.md). + +### Provisioning Storage Examples + +We provide examples of how to provision storage with [NFS,](../provisioning-storage-examples/nfs-storage.md) [vSphere,](../provisioning-storage-examples/vsphere-storage.md) and [Amazon's EBS.](../provisioning-storage-examples/persistent-storage-in-amazon-ebs.md) + +### GlusterFS Volumes + +In clusters that store data on GlusterFS volumes, you may experience an issue where pods fail to mount volumes after restarting the `kubelet`. For details on preventing this from happening, refer to [this page.](manage-persistent-storage/about-glusterfs-volumes.md) + +### iSCSI Volumes + +In [Rancher Launched Kubernetes clusters](../../launch-kubernetes-with-rancher/launch-kubernetes-with-rancher.md) that store data on iSCSI volumes, you may experience an issue where kubelets fail to automatically connect with iSCSI volumes. For details on resolving this issue, refer to [this page.](manage-persistent-storage/install-iscsi-volumes.md) + +### hostPath Volumes +Before you create a hostPath volume, you need to set up an [extra_bind](https://rancher.com/docs/rke/latest/en/config-options/services/services-extras/#extra-binds/) in your cluster configuration. This will mount the path as a volume in your kubelets, which can then be used for hostPath volumes in your workloads. + +### Migrating VMware vSphere Cloud Provider from In-tree to Out-of-tree + +Kubernetes is moving away from maintaining cloud providers in-tree. vSphere has an out-of-tree cloud provider that can be used by installing the vSphere cloud provider and cloud storage plugins. + +For instructions on how to migrate from the in-tree vSphere cloud provider to out-of-tree, and manage the existing VMs post migration, refer to [this page.](../../kubernetes-clusters-in-rancher-setup/set-up-cloud-providers/configure-out-of-tree-vsphere.md) + +### Related Links + +- [Kubernetes Documentation: Storage](https://kubernetes.io/docs/concepts/storage/) diff --git a/versioned_docs/version-2.14/how-to-guides/new-user-guides/manage-clusters/create-kubernetes-persistent-storage/manage-persistent-storage/about-glusterfs-volumes.md b/versioned_docs/version-2.14/how-to-guides/new-user-guides/manage-clusters/create-kubernetes-persistent-storage/manage-persistent-storage/about-glusterfs-volumes.md new file mode 100644 index 00000000000..69398199394 --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/new-user-guides/manage-clusters/create-kubernetes-persistent-storage/manage-persistent-storage/about-glusterfs-volumes.md @@ -0,0 +1,43 @@ +--- +title: GlusterFS Volumes +--- + + + + + +:::note + +This section only applies to [RKE clusters.](../../../launch-kubernetes-with-rancher/launch-kubernetes-with-rancher.md) + +::: + +In clusters that store data on GlusterFS volumes, you may experience an issue where pods fail to mount volumes after restarting the `kubelet`. The logging of the `kubelet` will show: `transport endpoint is not connected`. To prevent this from happening, you can configure your cluster to mount the `systemd-run` binary in the `kubelet` container. There are two requirements before you can change the cluster configuration: + +- The node needs to have the `systemd-run` binary installed (this can be checked by using the command `which systemd-run` on each cluster node) +- The `systemd-run` binary needs to be compatible with Debian OS on which the hyperkube image is based (this can be checked using the following command on each cluster node, replacing the image tag with the Kubernetes version you want to use) + +``` +docker run -v /usr/bin/systemd-run:/usr/bin/systemd-run -v /usr/lib/x86_64-linux-gnu/libcrypto.so.3:/usr/lib/x86_64-linux-gnu/libcrypto.so.3 -v /lib/systemd/libsystemd-shared-249.so:/lib/systemd/libsystemd-shared-249.so --entrypoint /usr/bin/systemd-run rancher/hyperkube:v1.26.14-rancher1 --version +``` + +:::caution + +Before updating your Kubernetes YAML to mount the `systemd-run` binary, make sure the `systemd` package is installed on your cluster nodes. If this package isn't installed _before_ the bind mounts are created in your Kubernetes YAML, Docker will automatically create the directories and files on each node and will not allow the package install to succeed. + +::: + +``` +services: + kubelet: + extra_binds: + - "/usr/bin/systemd-run:/usr/bin/systemd-run" + - "/usr/lib/x86_64-linux-gnu/libcrypto.so.3:/usr/lib/x86_64-linux-gnu/libcrypto.so.3" + - "/lib/systemd/libsystemd-shared-249.so:/lib/systemd/libsystemd-shared-249.so" +``` + +After the cluster has finished provisioning, you can check the `kubelet` container logging to see if the functionality is activated by looking for the following logline: + +``` +Detected OS with systemd +``` \ No newline at end of file diff --git a/versioned_docs/version-2.14/how-to-guides/new-user-guides/manage-clusters/create-kubernetes-persistent-storage/manage-persistent-storage/about-persistent-storage.md b/versioned_docs/version-2.14/how-to-guides/new-user-guides/manage-clusters/create-kubernetes-persistent-storage/manage-persistent-storage/about-persistent-storage.md new file mode 100644 index 00000000000..f4acbdf85ef --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/new-user-guides/manage-clusters/create-kubernetes-persistent-storage/manage-persistent-storage/about-persistent-storage.md @@ -0,0 +1,76 @@ +--- +title: How Persistent Storage Works +--- + + + + + +A persistent volume (PV) is a piece of storage in the Kubernetes cluster, while a persistent volume claim (PVC) is a request for storage. + +There are two ways to use persistent storage in Kubernetes: + +- Use an existing persistent volume +- Dynamically provision new persistent volumes + +To use an existing PV, your application will need to use a PVC that is bound to a PV, and the PV should include the minimum resources that the PVC requires. + +For dynamic storage provisioning, your application will need to use a PVC that is bound to a storage class. The storage class contains the authorization to provision new persistent volumes. + +![Setting Up New and Existing Persistent Storage](/img/rancher-storage.svg) + +For more information, refer to the [official Kubernetes documentation on storage](https://kubernetes.io/docs/concepts/storage/volumes/) + + +## About Persistent Volume Claims + +Persistent volume claims (PVCs) are objects that request storage resources from your cluster. They're similar to a voucher that your deployment can redeem for storage access. A PVC is mounted into a workloads as a volume so that the workload can claim its specified share of the persistent storage. + +To access persistent storage, a pod must have a PVC mounted as a volume. This PVC lets your deployment application store its data in an external location, so that if a pod fails, it can be replaced with a new pod and continue accessing its data stored externally, as though an outage never occurred. + +Each Rancher project contains a list of PVCs that you've created, available from **Resources > Workloads > Volumes**. You can reuse these PVCs when creating deployments in the future. + +### PVCs are Required for Both New and Existing Persistent Storage + +A PVC is required for pods to use any persistent storage, regardless of whether the workload is intended to use storage that already exists, or the workload will need to dynamically provision new storage on demand. + +If you are setting up existing storage for a workload, the workload mounts a PVC, which refers to a PV, which corresponds to existing storage infrastructure. + +If a workload should request new storage, the workload mounts PVC, which refers to a storage class, which has the capability to create a new PV along with its underlying storage infrastructure. + +Rancher lets you create as many PVCs within a project as you'd like. + +You can mount PVCs to a deployment as you create it, or later, after the deployment is running. + +## Setting up Existing Storage with a PVC and PV + +Your pods can store data in [volumes,](https://kubernetes.io/docs/concepts/storage/volumes/) but if the pod fails, that data is lost. To solve this issue, Kubernetes offers persistent volumes (PVs), which are Kubernetes resources that correspond to external storage disks or file systems that your pods can access. If a pod crashes, its replacement pod can access the data in persistent storage without any data loss. + +PVs can represent a physical disk or file system that you host on premise, or a vendor-hosted storage resource, such as Amazon EBS or Azure Disk. + +Creating a persistent volume in Rancher will not create a storage volume. It only creates a Kubernetes resource that maps to an existing volume. Therefore, before you can create a persistent volume as a Kubernetes resource, you must have storage provisioned. + +:::note Important: + +PVs are created at the cluster level, which means that in a multi-tenant cluster, teams with access to separate namespaces could have access to the same PV. + +::: + +### Binding PVs to PVCs + +When pods are set up to use persistent storage, they mount a persistent volume claim (PVC) that is mounted the same way as any other Kubernetes volume. When each PVC is created, the Kubernetes master considers it to be a request for storage and binds it to a PV that matches the minimum resource requirements of the PVC. Not every PVC is guaranteed to be bound to a PV. According to the Kubernetes [documentation,](https://kubernetes.io/docs/concepts/storage/persistent-volumes/) + +> Claims will remain unbound indefinitely if a matching volume does not exist. Claims will be bound as matching volumes become available. For example, a cluster provisioned with many 50Gi PVs would not match a PVC requesting 100Gi. The PVC can be bound when a 100Gi PV is added to the cluster. + +In other words, you can create unlimited PVCs, but they will only be bound to PVs if the Kubernetes master can find a sufficient PV that has at least the amount of disk space required by the PVC. + +To dynamically provision new storage, the PVC mounted in the pod would have to correspond to a storage class instead of a persistent volume. + +## Provisioning New Storage with a PVC and Storage Class + +Storage Classes allow you to create PVs dynamically without having to create persistent storage in an infrastructure provider first. + +For example, if a workload is bound to a PVC and the PVC refers to an Amazon EBS Storage Class, the storage class can dynamically create an EBS volume and a corresponding PV. + +The Kubernetes master will then bind the newly created PV to your workload's PVC, allowing your workload to use the persistent storage. + diff --git a/versioned_docs/version-2.14/how-to-guides/new-user-guides/manage-clusters/create-kubernetes-persistent-storage/manage-persistent-storage/dynamically-provision-new-storage.md b/versioned_docs/version-2.14/how-to-guides/new-user-guides/manage-clusters/create-kubernetes-persistent-storage/manage-persistent-storage/dynamically-provision-new-storage.md new file mode 100644 index 00000000000..0c89ef1162a --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/new-user-guides/manage-clusters/create-kubernetes-persistent-storage/manage-persistent-storage/dynamically-provision-new-storage.md @@ -0,0 +1,91 @@ +--- +title: Dynamically Provisioning New Storage in Rancher +--- + + + + + +This section describes how to provision new persistent storage for workloads in Rancher. + +This section assumes that you understand the Kubernetes concepts of storage classes and persistent volume claims. For more information, refer to the section on [how storage works.](about-persistent-storage.md) + +New storage is often provisioned by a cloud provider such as Amazon EBS. However, new storage doesn't have to be in the cloud. + +If you have a pool of block storage, and you don't want to use a cloud provider, Longhorn could help you provide persistent storage to your Kubernetes cluster. For more information, see [Cloud Native Storage with Longhorn](../../../../../integrations-in-rancher/longhorn/longhorn.md). + +To provision new storage for your workloads, follow these steps: + +1. [Add a storage class and configure it to use your storage.](#1-add-a-storage-class-and-configure-it-to-use-your-storage) +2. [Use the Storage Class for Pods Deployed with a StatefulSet.](#2-use-the-storage-class-for-pods-deployed-with-a-statefulset) + +## Prerequisites + +- To set up persistent storage, the `Manage Volumes` [role](../../../authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/cluster-and-project-roles.md#project-role-reference) is required. +- If you are provisioning storage for a cluster hosted in the cloud, the storage and cluster hosts must have the same cloud provider. +- The cloud provider must be enabled. For details on enabling cloud providers, refer to [this page.](../../../kubernetes-clusters-in-rancher-setup/set-up-cloud-providers/set-up-cloud-providers.md) +- Make sure your storage provisioner is available to be enabled. + +The following storage provisioners are enabled by default: + +Name | Plugin +--------|---------- +Amazon EBS Disk | `aws-ebs` +AzureFile | `azure-file` +AzureDisk | `azure-disk` +Google Persistent Disk | `gce-pd` +Longhorn | `flex-volume-longhorn` +VMware vSphere Volume | `vsphere-volume` +Local | `local` +Network File System | `nfs` +hostPath | `host-path` + +To use a storage provisioner that is not on the above list, you will need to use a [feature flag to enable unsupported storage drivers.](../../../../advanced-user-guides/enable-experimental-features/unsupported-storage-drivers.md) + +## 1. Add a storage class and configure it to use your storage + +These steps describe how to set up a storage class at the cluster level. + +1. Click **☰ > Cluster Management**. +1. Go to the cluster where you want to dynamically provision persistent storage volumes and click **Explore**. +1. Click **Storage > Storage Classes**. +1. Click **Create**. +1. Enter a name for your storage class. +1. From the **Provisioner** drop-down, select the service that you want to use to dynamically provision storage volumes. For example, if you have a Amazon EC2 cluster and you want to use cloud storage for it, use the `Amazon EBS Disk` provisioner. +1. In the **Parameters** tab, fill out the information required for the service to dynamically provision storage volumes. Each provisioner requires different information to dynamically provision storage volumes. Consult the service's documentation for help on how to obtain this information. +1. Click **Create**. + +**Result:** The storage class is available to be consumed by a PVC. + +For full information about the storage class parameters, refer to the official [Kubernetes documentation.](https://kubernetes.io/docs/concepts/storage/storage-classes/#parameters). + +## 2. Use the Storage Class for Pods Deployed with a StatefulSet + +StatefulSets manage the deployment and scaling of Pods while maintaining a sticky identity for each Pod. In this StatefulSet, we will configure a VolumeClaimTemplate. Each Pod managed by the StatefulSet will be deployed with a PersistentVolumeClaim based on this VolumeClaimTemplate. The PersistentVolumeClaim will refer to the StorageClass that we created. Therefore, when each Pod managed by the StatefulSet is deployed, it will be bound to dynamically provisioned storage using the StorageClass defined in its PersistentVolumeClaim. + +1. Click **☰ > Cluster Management**. +1. Go to the cluster where you want to add use the StorageClass for a workload and click **Explore**. +1. In the left navigation bar, click **Workload**. +1. Click **Create**. +1. Click **StatefulSet**. +1. In the **Volume Claim Templates** tab, click **Add Claim Template**. +1. Enter a name for the persistent volume. +1. In the **StorageClass** field, select the StorageClass that will dynamically provision storage for pods managed by this StatefulSet. +1. In the **Mount Point** field, enter the path that the workload will use to access the volume. +1. Click **Launch**. + +**Result:** When each Pod managed by the StatefulSet is deployed, it will make a request for the specified amount of disk space to the Kubernetes master. If a PV with the specified resources is available when the workload is deployed, the Kubernetes master will bind the PV to Pod with a compatible PVC. + +To attach the PVC to an existing workload, + +1. Click **☰ > Cluster Management**. +1. Go to the cluster where you want to add use the StorageClass for a workload and click **Explore**. +1. In the left navigation bar, click **Workload**. +1. Go to the workload that will use storage provisioned with the StorageClass that you cared at click **⋮ > Edit Config**. +1. In the **Volume Claim Templates** section, click **Add Claim Template**. +1. Enter a persistent volume name. +1. In the **StorageClass** field, select the StorageClass that will dynamically provision storage for pods managed by this StatefulSet. +1. In the **Mount Point** field, enter the path that the workload will use to access the volume. +1. Click **Save**. + +**Result:** The workload will make a request for the specified amount of disk space to the Kubernetes master. If a PV with the specified resources is available when the workload is deployed, the Kubernetes master will bind the PV to the PVC. If not, Rancher will provision new persistent storage. diff --git a/versioned_docs/version-2.14/how-to-guides/new-user-guides/manage-clusters/create-kubernetes-persistent-storage/manage-persistent-storage/install-iscsi-volumes.md b/versioned_docs/version-2.14/how-to-guides/new-user-guides/manage-clusters/create-kubernetes-persistent-storage/manage-persistent-storage/install-iscsi-volumes.md new file mode 100644 index 00000000000..6fe70097a2f --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/new-user-guides/manage-clusters/create-kubernetes-persistent-storage/manage-persistent-storage/install-iscsi-volumes.md @@ -0,0 +1,66 @@ +--- +title: iSCSI Volumes +--- + + + + + +In [Rancher Launched Kubernetes clusters](../../../launch-kubernetes-with-rancher/launch-kubernetes-with-rancher.md) that store data on iSCSI volumes, you may experience an issue where kubelets fail to automatically connect with iSCSI volumes. This failure is likely due to an incompatibility issue involving the iSCSI initiator tool. You can resolve this issue by installing the iSCSI initiator tool on each of your cluster nodes. + +Rancher Launched Kubernetes clusters storing data on iSCSI volumes leverage the [iSCSI initiator tool](http://www.open-iscsi.com/), which is embedded in the kubelet's `rancher/hyperkube` Docker image. From each kubelet (i.e., the _initiator_), the tool discovers and launches sessions with an iSCSI volume (i.e., the _target_). However, in some instances, the versions of the iSCSI initiator tool installed on the initiator and the target may not match, resulting in a connection failure. + +If you encounter this issue, you can work around it by installing the initiator tool on each node in your cluster. You can install the iSCSI initiator tool by logging into your cluster nodes and entering one of the following commands: + +| Platform | Package Name | Install Command | +| ------------- | ----------------------- | -------------------------------------- | +| Ubuntu/Debian | `open-iscsi` | `sudo apt install open-iscsi` | +| RHEL | `iscsi-initiator-utils` | `yum install iscsi-initiator-utils -y` | + + +After installing the initiator tool on your nodes, edit the YAML for your cluster, editing the kubelet configuration to mount the iSCSI binary and configuration, as shown in the sample below. + +:::note Notes + +- Before updating your Kubernetes YAML to mount the iSCSI binary and configuration, make sure either the `open-iscsi` (deb) or `iscsi-initiator-utils` (yum) package is installed on your cluster nodes. If this package isn't installed _before_ the bind mounts are created in your Kubernetes YAML, Docker will automatically create the directories and files on each node and will not allow the package install to succeed. + +- The example YAML below does not apply to K3s, but only to RKE clusters. Since the K3s kubelet does not run in a container, adding extra binds is not necessary. However, all iSCSI tools must still be installed on your K3s nodes. + +::: + +``` +services: + kubelet: + extra_binds: + - "/etc/iscsi:/etc/iscsi" + - "/sbin/iscsiadm:/sbin/iscsiadm" +``` + +If you're using RHEL 7.9, you need to mount the file `/usr/lib64/libcrypto.so.10` as shown in the sample below. + +``` +services: + kubelet: + extra_binds: + - "/etc/iscsi:/etc/iscsi" + - "/sbin/iscsiadm:/sbin/iscsiadm" + - "/usr/lib64/libcrypto.so.10:/usr/lib/libcrypto.so.10" +``` + +If you're using RHEL 8.6, you need to mount the file `/usr/lib64/libcrypto.so.1.1` as shown in the sample below. + +``` +services: + kubelet: + extra_binds: + - "/etc/iscsi:/etc/iscsi" + - "/sbin/iscsiadm:/sbin/iscsiadm" + - "/usr/lib64/libcrypto.so.1.1:/usr/lib/libcrypto.so.1.1" +``` + + +:::tip + +To verify iscsiadm is working properly, you can run the command `docker exec kubelet iscsiadm --version` on any node. + +::: diff --git a/versioned_docs/version-2.14/how-to-guides/new-user-guides/manage-clusters/create-kubernetes-persistent-storage/manage-persistent-storage/set-up-existing-storage.md b/versioned_docs/version-2.14/how-to-guides/new-user-guides/manage-clusters/create-kubernetes-persistent-storage/manage-persistent-storage/set-up-existing-storage.md new file mode 100644 index 00000000000..194d8284b3f --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/new-user-guides/manage-clusters/create-kubernetes-persistent-storage/manage-persistent-storage/set-up-existing-storage.md @@ -0,0 +1,89 @@ +--- +title: Setting up Existing Storage +--- + + + + + +This section describes how to set up existing persistent storage for workloads in Rancher. + +:::note + +This section assumes that you understand the Kubernetes concepts of persistent volumes and persistent volume claims. For more information, refer to the section on [how storage works.](about-persistent-storage.md) + +::: + +To set up storage, follow these steps: + +1. [Set up persistent storage.](#1-set-up-persistent-storage) +2. [Add a PersistentVolume that refers to the persistent storage.](#2-add-a-persistentvolume-that-refers-to-the-persistent-storage) +3. [Use the Storage Class for Pods Deployed with a StatefulSet.](#3-use-the-storage-class-for-pods-deployed-with-a-statefulset) + +## Prerequisites + +- To create a persistent volume as a Kubernetes resource, you must have the `Manage Volumes` [role.](../../../authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/cluster-and-project-roles.md#project-role-reference) +- If you are provisioning storage for a cluster hosted in the cloud, the storage and cluster hosts must have the same cloud provider. + +## 1. Set up persistent storage + +Creating a persistent volume in Rancher will not create a storage volume. It only creates a Kubernetes resource that maps to an existing volume. Therefore, before you can create a persistent volume as a Kubernetes resource, you must have storage provisioned. + +The steps to set up a persistent storage device will differ based on your infrastructure. We provide examples of how to set up storage using [vSphere,](../../provisioning-storage-examples/vsphere-storage.md) [NFS,](../../provisioning-storage-examples/nfs-storage.md) or Amazon's [EBS.](../../provisioning-storage-examples/persistent-storage-in-amazon-ebs.md) + +If you have a pool of block storage, and you don't want to use a cloud provider, Longhorn could help you provide persistent storage to your Kubernetes cluster. For more information, see [Cloud Native Storage with Longhorn](../../../../../integrations-in-rancher/longhorn/longhorn.md). + +## 2. Add a PersistentVolume that refers to the persistent storage + +These steps describe how to set up a PersistentVolume at the cluster level in Kubernetes. + +1. Click **☰ > Cluster Management**. +1. Go to the cluster where you want to add a persistent volume and click **Explore**. +1. In the left navigation bar, click **Storage > Persistent Volumes**. +1. Click **Create**. +1. Enter a **Name** for the persistent volume. +1. Select the **Volume Plugin** for the disk type or service that you're using. When adding storage to a cluster that's hosted by a cloud provider, use the cloud provider's plug-in for cloud storage. For example, if you have a Amazon EC2 cluster and you want to use cloud storage for it, you must use the `Amazon EBS Disk` volume plugin. +1. Enter the **Capacity** of your volume in gigabytes. +1. Complete the **Plugin Configuration** form. Each plugin type requires information specific to the vendor of disk type. For help regarding each plugin's form and the information that's required, refer to the plug-in's vendor documentation. +1. Optional: In the **Customize** form, configure the [access modes.](https://kubernetes.io/docs/concepts/storage/persistent-volumes/#access-modes) This options sets how many nodes can access the volume, along with the node read/write permissions. The [Kubernetes Documentation](https://kubernetes.io/docs/concepts/storage/persistent-volumes/#access-modes) includes a table that lists which access modes are supported by the plugins available. +1. Optional: In the **Customize** form, configure the [mount options.](https://kubernetes.io/docs/concepts/storage/persistent-volumes/#mount-options) Each volume plugin allows you to specify additional command line options during the mounting process. Consult each plugin's vendor documentation for the mount options available. +1. Click **Create**. + +**Result:** Your new persistent volume is created. + + +## 3. Use the Storage Class for Pods Deployed with a StatefulSet + +StatefulSets manage the deployment and scaling of Pods while maintaining a sticky identity for each Pod. In this StatefulSet, we will configure a VolumeClaimTemplate. Each Pod managed by the StatefulSet will be deployed with a PersistentVolumeClaim based on this VolumeClaimTemplate. The PersistentVolumeClaim will refer to the PersistentVolume that we created. Therefore, when each Pod managed by the StatefulSet is deployed, it will be bound a PersistentVolume as defined in its PersistentVolumeClaim. + +You can configure storage for the StatefulSet during or after workload creation. + +The following steps describe how to assign existing storage to a new StatefulSet: + +1. Click **☰ > Cluster Management**. +1. Go to the cluster where you want to configure storage for the StatefulSet and click **Explore**. +1. In the left navigation bar, click **Workload > StatefulSets**. +1. Click **Create**. +1. Choose the namespace where the workload will be deployed. +1. Enter a name for the StatefulSet. +1. On the **Volume Claim Templates** tab, click **Add Claim Template**. +1. Click **Use an existing Persistent Volume**. +1. In the Persistent Volumes field, select the Persistent Volume that you created. +1. In the **Mount Point** field, enter the path that the workload will use to access the volume. +1. Click **Launch**. + +**Result:** When the workload is deployed, it will make a request for the specified amount of disk space to the Kubernetes master. If a PV with the specified resources is available when the workload is deployed, the Kubernetes master will bind the PV to the PVC. + +The following steps describe how to assign persistent storage to an existing workload: + +1. Click **☰ > Cluster Management**. +1. Go to the cluster where you want to configure storage for the StatefulSet and click **Explore**. +1. In the left navigation bar, click **Workload > StatefulSets**. +1. Go to the workload that you want to add the persistent storage to. Click **⋮ > Edit**. +1. On the **Volume Claim Templates** tab, click **Add Claim Template**. +1. Click **Use an existing Persistent Volume**. +1. In the Persistent Volumes field, select the Persistent Volume that you created. +1. In the **Mount Point** field, enter the path that the workload will use to access the volume. +1. Click **Launch**. + +**Result:** The workload will make a request for the specified amount of disk space to the Kubernetes master. If a PV with the specified resources is available when the workload is deployed, the Kubernetes master will bind the PV to the PVC. diff --git a/versioned_docs/version-2.14/how-to-guides/new-user-guides/manage-clusters/create-kubernetes-persistent-storage/manage-persistent-storage/use-external-ceph-driver.md b/versioned_docs/version-2.14/how-to-guides/new-user-guides/manage-clusters/create-kubernetes-persistent-storage/manage-persistent-storage/use-external-ceph-driver.md new file mode 100644 index 00000000000..67252a62748 --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/new-user-guides/manage-clusters/create-kubernetes-persistent-storage/manage-persistent-storage/use-external-ceph-driver.md @@ -0,0 +1,424 @@ +--- +title: Using an External Ceph Driver +--- + + + + + +These instructions are about using the external Ceph driver in an RKE2 cluster. If you are using RKE, additional steps are required. For details, refer to [this section.](#using-the-ceph-driver-with-rke) + + +## Requirements + +Make sure ceph-common and xfsprogs packages are installed on SLE worker nodes. + +## Using the Ceph Driver with RKE + +The resources below are fully compatible with RKE based clusters, but there is a need to do an additional kubelet configuration for RKE. + +On RKE clusters, the kubelet component is running in a Docker container and doesn't have access to the host's kernel modules as rbd and libceph by default. + +To solve this limitation, you can either run `modprobe rbd` on worker nodes, or configure the kubelet containers to automatically mount the `/lib/modules` directory from the host into the container. + +For the kubelet configuration, put the following lines into the `cluster.yml` file prior to RKE cluster provisioning. You can also modify the `cluster.yml` later in the Rancher UI by clicking on **Edit Cluster > Edit as YAML** and restarting the worker nodes. + +```yaml +services: + kubelet: + extra_binds: + - '/lib/modules:/lib/modules:ro' +``` + +For more information about the `extra_binds` directive, refer to [this section.](https://rancher.com/docs/rke/latest/en/config-options/services/services-extras/#extra-binds) + +## Installing the ceph-csi driver on an RKE2 cluster + +:::note + +These steps are needed for dynamic RBD provisioning only. + +::: + +For more information about the `ceph-csi-rbd` chart, refer to [this page.](https://github.com/ceph/ceph-csi/blob/devel/charts/ceph-csi-rbd/README.md) + +To get details about your SES cluster, run: + +``` +ceph mon dump +``` + +Read its output: + +``` +dumped monmap epoch 3 +epoch 3 +fsid 79179d9d-98d8-4976-ab2e-58635caa7235 +last_changed 2021-02-11T10:56:42.110184+0000 +created 2021-02-11T10:56:22.913321+0000 +min_mon_release 15 (octopus) +0: [v2:10.85.8.118:3300/0,v1:10.85.8.118:6789/0] mon.a +1: [v2:10.85.8.123:3300/0,v1:10.85.8.123:6789/0] mon.b +2: [v2:10.85.8.124:3300/0,v1:10.85.8.124:6789/0] mon.c +``` + +Later you'll need the fsid and mon addresses values. + +## Install the ceph-csi Driver Using Helm + +Run these commands: + +``` +helm repo add ceph-csi https://ceph.github.io/csi-charts +helm repo update +helm search repo ceph-csi -l +helm inspect values ceph-csi/ceph-csi-rbd > ceph-csi-rbd-values.yaml +``` + +Modify the `ceph-csi-rbd-values.yaml` file and keep there only the required changes: + +```yaml +# ceph-csi-rbd-values.yaml +csiConfig: + - clusterID: "79179d9d-98d8-4976-ab2e-58635caa7235" + monitors: + - "10.85.8.118:6789" + - "10.85.8.123:6789" + - "10.85.8.124:6789" +provisioner: + name: provisioner + replicaCount: 2 +``` + +Make sure the ceph monitors are reachable from the RKE2 cluster, for example, by ping. + +``` +kubectl create namespace ceph-csi-rbd +helm install --namespace ceph-csi-rbd ceph-csi-rbd ceph-csi/ceph-csi-rbd --values ceph-csi-rbd-values.yaml +kubectl rollout status deployment ceph-csi-rbd-provisioner -n ceph-csi-rbd +helm status ceph-csi-rbd -n ceph-csi-rbd +``` + +in case you'd like to modify the configuration directly via Helm, you may adapt the `ceph-csi-rbd-values.yaml` file and call: + +``` +helm upgrade \ + --namespace ceph-csi-rbd ceph-csi-rbd ceph-csi/ceph-csi-rbd --values ceph-csi-rbd-values.yaml +``` + +## Creating RBD Ceph Resources + +``` +# Create a ceph pool: +ceph osd pool create myPool 64 64 + +# Create a block device pool: +rbd pool init myPool + +# Create a block device image: +rbd create -s 2G myPool/image + +# Create a block device user and record the key: +ceph auth get-or-create-key client.myPoolUser mon "allow r" osd "allow class-read object_prefix rbd_children, allow rwx pool=myPool" | tr -d '\n' | base64 +QVFDZ0R5VmdyRk9KREJBQTJ5b2s5R1E2NUdSWExRQndhVVBwWXc9PQ== + +# Encode the ceph user myPoolUser into a bash64 hash: +echo "myPoolUser" | tr -d '\n' | base64 +bXlQb29sVXNlcg== + +# Create a block device admin user and record the key: +ceph auth get-or-create-key client.myPoolAdmin mds 'allow *' mgr 'allow *' mon 'allow *' osd 'allow * pool=myPool' | tr -d '\n' | base64 +QVFCK0hDVmdXSjQ1T0JBQXBrc0VtcVhlZFpjc0JwaStIcmU5M3c9PQ== + +# Encode the ceph user myPoolAdmin into a bash64 hash: +echo "myPoolAdmin" | tr -d '\n' | base64 +bXlQb29sQWRtaW4= +``` +## Configure RBD Ceph Access Secrets + +### User Account + +For static RBD provisioning (the image within the ceph pool must exist), run these commands: + +``` +cat > ceph-user-secret.yaml << EOF +apiVersion: v1 +kind: Secret +metadata: + name: ceph-user + namespace: default +type: kubernetes.io/rbd +data: + userID: bXlQb29sVXNlcg== + userKey: QVFDZ0R5VmdyRk9KREJBQTJ5b2s5R1E2NUdSWExRQndhVVBwWXc9PQ== +EOF + +kubectl apply -f ceph-user-secret.yaml +``` + +### Admin Account + +For dynamic RBD provisioning (used for automatic image creation within a given ceph pool), run these commands: + +``` +cat > ceph-admin-secret.yaml << EOF +apiVersion: v1 +kind: Secret +metadata: + name: ceph-admin + namespace: default +type: kubernetes.io/rbd +data: + userID: bXlQb29sQWRtaW4= + userKey: QVFCK0hDVmdXSjQ1T0JBQXBrc0VtcVhlZFpjc0JwaStIcmU5M3c9PQ== +EOF + +kubectl apply -f ceph-admin-secret.yaml +``` + +## Create RBD Testing Resources + +### Using RBD in Pods + +```yaml +# pod +cat > ceph-rbd-pod-inline.yaml << EOF +apiVersion: v1 +kind: Pod +metadata: + name: ceph-rbd-pod-inline +spec: + containers: + - name: ceph-rbd-pod-inline + image: busybox + command: ["sleep", "infinity"] + volumeMounts: + - mountPath: /mnt/ceph_rbd + name: volume + volumes: + - name: volume + rbd: + monitors: + - 10.85.8.118:6789 + - 10.85.8.123:6789 + - 10.85.8.124:6789 + pool: myPool + image: image + user: myPoolUser + secretRef: + name: ceph-user + fsType: ext4 + readOnly: false +EOF + +kubectl apply -f ceph-rbd-pod-inline.yaml +kubectl get pod +kubectl exec pod/ceph-rbd-pod-inline -- df -k | grep rbd +``` + +### Using RBD in Persistent Volumes + +```yaml +# pod-pvc-pv +cat > ceph-rbd-pod-pvc-pv-allinone.yaml << EOF +apiVersion: v1 +kind: PersistentVolume +metadata: + name: ceph-rbd-pv +spec: + capacity: + storage: 2Gi + accessModes: + - ReadWriteOnce + rbd: + monitors: + - 10.85.8.118:6789 + - 10.85.8.123:6789 + - 10.85.8.124:6789 + pool: myPool + image: image + user: myPoolUser + secretRef: + name: ceph-user + fsType: ext4 + readOnly: false +--- +kind: PersistentVolumeClaim +apiVersion: v1 +metadata: + name: ceph-rbd-pvc +spec: + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 2Gi +--- +apiVersion: v1 +kind: Pod +metadata: + name: ceph-rbd-pod-pvc-pv +spec: + containers: + - name: ceph-rbd-pod-pvc-pv + image: busybox + command: ["sleep", "infinity"] + volumeMounts: + - mountPath: /mnt/ceph_rbd + name: volume + volumes: + - name: volume + persistentVolumeClaim: + claimName: ceph-rbd-pvc +EOF + +kubectl apply -f ceph-rbd-pod-pvc-pv-allinone.yaml +kubectl get pv,pvc,pod +kubectl exec pod/ceph-rbd-pod-pvc-pv -- df -k | grep rbd +``` + +### Using RBD in Storage Classes + +This example is for dynamic provisioning. The ceph-csi driver is needed. + +```yaml +# pod-pvc-sc +cat > ceph-rbd-pod-pvc-sc-allinone.yaml < /root/.bashrc << EOF +export PATH=$PATH:/var/lib/rancher/rke2/bin/ +export KUBECONFIG=/etc/rancher/rke2/rke2.yaml +EOF + +cat /var/lib/rancher/rke2/server/node-token +token: K10ca0c38d4ff90d8b80319ab34092e315a8b732622e6adf97bc9eb0536REDACTED::server:ec0308000b8a6b595da000efREDACTED +``` + +### RKE2 Agent/Worker provisioning + +``` +mkdir -p /etc/rancher/rke2/ + +cat > /etc/rancher/rke2/config.yaml << EOF +server: https://10.100.103.23:9345 +token: K10ca0c38d4ff90d8b80319ab34092e315a8b732622e6adf97bc9eb0536REDACTED::server:ec0308000b8a6b595da000efREDACTED +EOF + +curl -sfL https://get.rke2.io | INSTALL_RKE2_TYPE="agent" sh - +systemctl enable --now rke2-agent.service +``` + +To import the cluster into Rancher, click **☰ > Cluster Management**. Then on the **Clusters** page, click **Import Existing**. Then run the provided kubectl command on the server/master node. + +## Tested Versions + +OS for running RKE2 nodes: JeOS SLE15-SP2 with installed kernel-default-5.3.18-24.49 + +``` +kubectl version +Client Version: version.Info{Major:"1", Minor:"18", GitVersion:"v1.18.4", GitCommit:"c96aede7b5205121079932896c4ad89bb93260af", GitTreeState:"clean", BuildDate:"2020-06-22T12:00:00Z", GoVersion:"go1.13.11", Compiler:"gc", Platform:"linux/amd64"} +Server Version: version.Info{Major:"1", Minor:"19", GitVersion:"v1.19.7+rke2r1", GitCommit:"1dd5338295409edcfff11505e7bb246f0d325d15", GitTreeState:"clean", BuildDate:"2021-01-20T01:50:52Z", GoVersion:"go1.15.5b5", Compiler:"gc", Platform:"linux/amd64"} + +helm version +version.BuildInfo{Version:"3.4.1", GitCommit:"c4e74854886b2efe3321e185578e6db9be0a6e29", GitTreeState:"clean", GoVersion:"go1.14.12"} +``` + +Kubernetes version on RKE2 cluster: v1.19.7+rke2r1 + +## Troubleshooting + +In case you are using SUSE's ceph-rook based on SES7, it might be useful to expose the monitors on hostNetwork by editing `rook-1.4.5/ceph/cluster.yaml` and setting `spec.network.hostNetwork=true`. + +Also for operating the ceph-rook cluster, it is useful to deploy a toolbox on the Kubernetes cluster where ceph-rook is provisioned by `kubectl apply -f rook-1.4.5/ceph/toolbox.yaml` Then all the ceph related commands can be executed in the toolbox pod, for example, by running `kubectl exec -it -n rook-ceph rook-ceph-tools-686d8b8bfb-2nvqp -- bash` + +Operating with the ceph - basic commands: + +``` +ceph osd pool stats +ceph osd pool delete myPool myPool --yes-i-really-really-mean-it +rbd list -p myPool +> csi-vol-f5d3766c-7296-11eb-b32a-c2b045952d38 +> image +``` + +Delete the image: `rbd rm csi-vol-f5d3766c-7296-11eb-b32a-c2b045952d38 -p myPool` + +CephFS commands in rook toolbox: + +``` +ceph -s +ceph fs ls +ceph fs fail cephfs +ceph fs rm cephfs --yes-i-really-mean-it +ceph osd pool delete cephfs_data cephfs_data --yes-i-really-really-mean-it +ceph osd pool delete cephfs_metadata cephfs_metadata --yes-i-really-really-mean-it +``` + +To prepare a cephfs filesystem, you can run this command on a rook cluster: + +``` +kubectl apply -f rook-1.4.5/ceph/filesystem.yaml +``` \ No newline at end of file diff --git a/versioned_docs/version-2.14/how-to-guides/new-user-guides/manage-clusters/manage-cluster-templates.md b/versioned_docs/version-2.14/how-to-guides/new-user-guides/manage-clusters/manage-cluster-templates.md new file mode 100644 index 00000000000..83bf07410b2 --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/new-user-guides/manage-clusters/manage-cluster-templates.md @@ -0,0 +1,128 @@ +--- +title: Cluster Templates +--- + + + + + +Cluster templates encompass both Kubernetes configuration and node pool configuration, allowing a single template to contain all the information Rancher needs to provision new nodes in a cloud provider and install Kubernetes on those nodes. + +## Overview + +Cluster templates are provided as Helm charts. To use them, you will need to clone and fork the templates, change them according to your use case, and then install the Helm charts on the Rancher management cluster. When the Helm chart is installed on the Rancher management cluster, a new cluster resource is created, which Rancher uses to provision the new cluster. + +After the cluster is provisioned using the template, no changes to the template will affect the cluster. After the cluster is created from the cluster template, its configuration and infrastructure can change, because no restrictions are enforced by cluster templates. + +### Kubernetes Distribution + +Cluster templates can use any Kubernetes distribution. For now, we provide an example with an RKE2 Kubernetes cluster. We may provide more examples in the future using other Kubernetes distributions. + +### Versioning + +Rancher doesn't manage version control for cluster templates. Version control is handled in the repository containing the template's Helm chart. + +## RKE2 Cluster Template + +See the example repository for an [RKE2 cluster template](https://github.com/rancher/cluster-template-examples). + +## Adding a Cluster Template to Rancher + +In this section, you'll learn how to add the cluster template to the `local` cluster's chart repo list. The result is that Rancher will include the cluster template as an option when users install new Kubernetes clusters. + +:::note Prerequisites: + +- You will need permission to install Helm charts on the `local` Rancher cluster. +- To make the chart viewable in the cluster creation form, both the chart and the index.yaml file must have the annotation, `catalog.cattle.io/type: cluster-template`. + +::: + +1. Go to a cluster template example repository. Rancher's examples are in [this GitHub repository.](https://github.com/rancher/cluster-template-examples) +1. Fork the repository. +1. Optional: Edit the cluster options by editing the `values.yaml` file. For help editing the file, see the cluster template's Helm chart README. +1. Add the chart repository to Rancher. Click **☰ > Cluster Management**. +1. Go to the `local` cluster and click **Explore.** +1. In the left navigation bar, click **Apps > Chart Repositories.** +1. Click **Create.** +1. Enter a name for the cluster template repository. +1. Click **Git Repository containing Helm chart definitions.** +1. In the **Git Repo URL** field, enter the URL for the repository. For example, `https://github.com/rancher/cluster-template-examples.git`. +1. In the **Git Branch** field, enter the branch to use as the source for the template. Rancher's example repository uses `main`. +1. Click **Create.** + +**Result:** The cluster template available from the **Apps** in Rancher's `local` cluster. It can now be used to deploy clusters. + +## Creating a Cluster from a Cluster Template + +:::note Prerequisites: + +- You will need permission to provision new Kubernetes clusters. +- You will need cloud credentials for provisioning infrastructure using the template. +- In order to show in the form for creating new clusters, the cluster template's Helm chart must have the `catalog.cattle.io/type: cluster-template` annotation. + +::: + +1. Click **☰ > Cluster Management**. +1. On the **Clusters** page, click **Create.** +1. Click the name of your cluster template. +1. Finish installing the Helm chart. + +**Result:** After Rancher provisions the new cluster, it is managed in the same way as any other Rancher-launched Kubernetes cluster. You can configure any options through the UI if the cluster template has options for the user to choose from. + +## Updating a Cluster Created from a Cluster Template + +You can update any clusters using a template from the **Apps > Installed Apps** page, given there is a new version of a template being used by those clusters. + +## Deploying Clusters from a Template with Fleet + +:::note Prerequisites: + +- You will need permission to provision new Kubernetes clusters. +- You will need cloud credentials for provisioning infrastructure using the template. +- In order to show in the form for creating new clusters, the cluster template's Helm chart must have the `catalog.cattle.io/type:cluster-template` annotation. +- In order to use a template as part of continuous delivery/GitOps, the cluster template needs to be deployed in the `fleet-local` namespace of the `local` cluster. +- All values must be set in the `values.yaml` of the template. +- Fleet repositories must follow these [guidelines](https://fleet.rancher.io/gitrepo-content). For RKE2 cluster templates, that means a `fleet.yaml` file must be added to the repository. + +::: + +1. Click **☰ > Cluster Management**. +1. On the **Clusters** page, click **Create.** +1. Click **Create Cluster from Template.** + +**Result:** After Rancher provisions the new cluster, it is managed by Fleet. + +## Uninstalling Cluster Templates + +1. Click **☰ > Cluster Management**. +1. Go to the `local` cluster and click **Apps > Chart Repositories.** +1. Go to the chart repository for your cluster template and click **⋮ > Delete.** +1. Confirm the deletion. + +**Result:** The cluster template is uninstalled. This action does not affect clusters created with the cluster template. + +An admin with access to the `local` cluster can also remove a cluster deployed via cluster templates through the **Apps > Installed Apps** page. + +## Configuration Options + +Cluster templates are flexible enough that they can be used to configure all of the following options: + +- Node configuration +- Node pools +- Pre-specified cloud credentials +- Enable/configure an authorized cluster endpoint to get kubectl access to the cluster without using Rancher as a proxy +- Install Rancher V2 monitoring +- Kubernetes version +- Assign cluster members +- Infrastructure configuration such as AWS VPC/subnets or vSphere data center +- Cloud provider options +- Pod security options +- Network providers +- Ingress controllers +- Network security configuration +- Network plugins +- Private registry URL and credentials +- Add-ons +- Kubernetes options, including configurations for Kubernetes components such as kube-api, kube-controller, kubelet, and services + +For details on how to configure the template, refer to the cluster template's Helm chart README. \ No newline at end of file diff --git a/versioned_docs/version-2.14/how-to-guides/new-user-guides/manage-clusters/manage-clusters.md b/versioned_docs/version-2.14/how-to-guides/new-user-guides/manage-clusters/manage-clusters.md new file mode 100644 index 00000000000..a694c2f77c2 --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/new-user-guides/manage-clusters/manage-clusters.md @@ -0,0 +1,35 @@ +--- +title: Cluster Administration +--- + + + + + +After you provision a cluster in Rancher, you can begin using powerful Kubernetes features to deploy and scale your containerized applications in development, testing, or production environments. + +:::note + +This section assumes a basic familiarity with Docker and Kubernetes. For a brief explanation of how Kubernetes components work together, refer to the [concepts](../../../reference-guides/kubernetes-concepts.md) page. + +::: + +## Managing Clusters in Rancher + +After clusters have been [provisioned into Rancher](../kubernetes-clusters-in-rancher-setup/kubernetes-clusters-in-rancher-setup.md), [cluster owners](../authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/cluster-and-project-roles.md#cluster-roles) will need to manage these clusters. There are many different options of how to manage your cluster. + +import ClusterCapabilitiesTable from '../../../shared-files/_cluster-capabilities-table.md'; + + + +## Configuring Tools + +Rancher contains a variety of tools that aren't included in Kubernetes to assist in your DevOps operations. Rancher can integrate with external services to help your clusters run more efficiently. Tools are divided into the following categories: + +- Alerts +- Notifiers +- Logging +- Monitoring +- Istio Service Mesh + +Tools can be installed through **Apps.** diff --git a/versioned_docs/version-2.14/how-to-guides/new-user-guides/manage-clusters/nodes-and-node-pools.md b/versioned_docs/version-2.14/how-to-guides/new-user-guides/manage-clusters/nodes-and-node-pools.md new file mode 100644 index 00000000000..b8c2133a475 --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/new-user-guides/manage-clusters/nodes-and-node-pools.md @@ -0,0 +1,197 @@ +--- +title: Nodes and Node Pools +--- + + + + + +After you launch a Kubernetes cluster in Rancher, you can manage individual nodes from the cluster's **Node** tab. + +1. Click **☰** in the top left corner. +1. Select **Cluster Management**. +1. Find the cluster whose nodes you want to manage, and click the **Explore** button at the end of the row. +1. Select **Nodes** from the left navigation. + +Depending on the [option used](../kubernetes-clusters-in-rancher-setup/kubernetes-clusters-in-rancher-setup.md) to provision the cluster, there are different node options available. + +:::note + +If you want to manage the _cluster_ and not individual nodes, see [Editing Clusters](../../../reference-guides/cluster-configuration/cluster-configuration.md). + +::: + + +## Node Options Available for Each Cluster Creation Option + +The following table lists which node options are available for each type of cluster in Rancher. Click the links in the **Option** column for more detailed information about each feature. + +| Option | [Nodes Hosted by an Infrastructure Provider][1] | [Custom Node][2] | [Hosted Cluster][3] | [Registered EKS Nodes][4] | [All Other Registered Nodes][5] | Description | +| ------------------------------------------------ | ------------------------------------------------ | ---------------- | ------------------- | ------------------- | -------------------| ------------------------------------------------------------------ | +| [Cordon](#cordoning-a-node) | ✓ | ✓ | ✓ | ✓ | ✓ | Marks the node as unschedulable. | +| [Drain](#draining-a-node) | ✓ | ✓ | ✓ | ✓ | ✓ | Marks the node as unschedulable _and_ evicts all pods. | +| [Edit](#managing-and-editing-individual-nodes) | ✓ | ✓ | ✓ | ✓ | ✓ | Enter a custom name, description, label, or taints for a node. | +| [View API](#viewing-a-node-in-the-rancher-api) | ✓ | ✓ | ✓ | ✓ | ✓ | View API data. | +| [Delete](#deleting-a-node) | ✓ | ✓ | | * | * | Deletes defective nodes from the cluster. | +| [Download Keys](#ssh-into-a-node-hosted-by-an-infrastructure-provider) | ✓ | | | | | Download SSH key in order to SSH into the node. | +| [Node Scaling](#scaling-nodes) | ✓ | | | ✓ | | Scale the number of nodes in the node pool up or down. | + +[1]: ../launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/use-new-nodes-in-an-infra-provider.md +[2]: ../../../reference-guides/cluster-configuration/rancher-server-configuration/use-existing-nodes/use-existing-nodes.md +[3]: ../kubernetes-clusters-in-rancher-setup/set-up-clusters-from-hosted-kubernetes-providers/set-up-clusters-from-hosted-kubernetes-providers.md +[4]: ../../../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/register-existing-clusters.md +[5]: ../../../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/register-existing-clusters.md + +\* Delete option accessible via View API + + +### Nodes Hosted by an Infrastructure Provider + +Node pools are available when you provision Rancher-launched Kubernetes clusters on nodes that are [hosted in an infrastructure provider.](../launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/use-new-nodes-in-an-infra-provider.md) + +Clusters provisioned using [one of the node pool options](../launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/use-new-nodes-in-an-infra-provider.md#node-pools) can be scaled up or down if the node pool is edited. + +A node pool can also automatically maintain the node scale that's set during the initial cluster provisioning if [node auto-replace is enabled.](../launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/use-new-nodes-in-an-infra-provider.md#about-node-auto-replace) This scale determines the number of active nodes that Rancher maintains for the cluster. + +Rancher uses [node templates](../launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/use-new-nodes-in-an-infra-provider.md#node-templates) to replace nodes in the node pool. Each node template uses cloud provider credentials to allow Rancher to set up the node in the infrastructure provider. + +### Nodes Provisioned by Hosted Kubernetes Providers + +Options for managing nodes [hosted by a Kubernetes provider](../kubernetes-clusters-in-rancher-setup/set-up-clusters-from-hosted-kubernetes-providers/set-up-clusters-from-hosted-kubernetes-providers.md) are somewhat limited in Rancher. Rather than using the Rancher UI to make edits such as scaling the number of nodes up or down, edit the cluster directly. + +### Registered Nodes + +Although you can deploy workloads to a [registered cluster](../../new-user-guides/kubernetes-clusters-in-rancher-setup/register-existing-clusters.md) using Rancher, you cannot manage individual cluster nodes. All management of imported cluster nodes must take place outside of Rancher. + +## Managing and Editing Individual Nodes + +Editing a node lets you: + +* Change its name +* Change its description +* Add [labels](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/) +* Add/Remove [taints](https://kubernetes.io/docs/concepts/configuration/taint-and-toleration/) + +To manage individual nodes, browse to the cluster that you want to manage and then select **Nodes** from the main menu. You can open the options menu for a node by clicking its **⋮** icon (**..**.). + +## Viewing a Node in the Rancher API + +Select this option to view the node's [API endpoints](../../../api/quickstart.md). + +## Deleting a Node + +Use **Delete** to remove defective nodes from the cloud provider. + +When you the delete a defective node, Rancher can automatically replace it with an identically provisioned node if the node is in a node pool and [node auto-replace is enabled.](../launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/use-new-nodes-in-an-infra-provider.md#about-node-auto-replace) + +:::tip + +If your cluster is hosted by an infrastructure provider, and you want to scale your cluster down instead of deleting a defective node, [scale down](#scaling-nodes) rather than delete. + +::: + +## Scaling Nodes + +For nodes hosted by an infrastructure provider, you can scale the number of nodes in each [node pool](../launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/use-new-nodes-in-an-infra-provider.md#node-pools) by using the scale controls. This option isn't available for other cluster types. + +## SSH into a Node Hosted by an Infrastructure Provider + +For [nodes hosted by an infrastructure provider](../launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/use-new-nodes-in-an-infra-provider.md), you have the option of downloading its SSH key so that you can connect to it remotely from your desktop. + +1. In the upper left corner, click **☰ > Cluster Management**. +1. On the **Clusters** page, go to the cluster where you want to SSH into a node and click the name of the cluster. +1. On the **Machine Pools** tab, find the node that you want to remote into and click **⋮ > Download SSH Key**. A ZIP file containing files used for SSH is then downloaded. +1. Extract the ZIP file to any location. +1. Open Terminal. Change your location to the extracted ZIP file. +1. Enter the following command: + + ``` + ssh -i id_rsa root@ + ``` + +## Cordoning a Node + +_Cordoning_ a node marks it as unschedulable. This feature is useful for performing short tasks on the node during small maintenance windows, like reboots, upgrades or decommissions. When you're done, power back on and make the node schedulable again by uncordoning it. + +## Draining a Node + +_Draining_ is the process of first cordoning the node, and then evicting all its pods. This feature is useful for performing node maintenance (like kernel upgrades or hardware maintenance). It prevents new pods from deploying to the node while redistributing existing pods so that users don't experience service interruption. + +- For pods with a replica set, the pod is replaced by a new pod that is scheduled to a new node. Additionally, if the pod is part of a service, then clients are automatically redirected to the new pod. + +- For pods with no replica set, you need to bring up a new copy of the pod, and assuming it is not part of a service, redirect clients to it. + +You can drain nodes that are in either a `cordoned` or `active` state. When you drain a node, the node is cordoned, the nodes are evaluated for conditions they must meet to be drained, and then (if it meets the conditions) the node evicts its pods. + +However, you can override the conditions draining when you initiate the drain. You're also given an opportunity to set a grace period and timeout value. + +### Aggressive and Safe Draining Options + +When you configure the upgrade strategy for the cluster, you can enable node draining. If node draining is enabled, you are able to configure how pods are deleted and rescheduled. + +- **Aggressive Mode** + + In this mode, pods won't get rescheduled to a new node, even if they do not have a controller. Kubernetes expects you to have your own logic that handles the deletion of these pods. + + Kubernetes also expects the implementation to decide what to do with pods using emptyDir. If a pod uses emptyDir to store local data, you might not be able to safely delete it, since the data in the emptyDir is deleted once the pod is removed from the node. Choosing aggressive mode deletes these pods. + +- **Safe Mode** + + If a node has stand-alone pods or ephemeral data it is cordoned but not drained. + +### Grace Period + +The timeout given to each pod for cleaning things up so they have a chance to exit gracefully. For example, when pods might need to finish any outstanding requests, roll back transactions or save state to an external storage. If negative, the default value specified in the pod is used. + +### Timeout + +The amount of time drain should continue to wait before giving up. + +:::note Kubernetes Known Issue: + +The [timeout setting](https://github.com/kubernetes/kubernetes/pull/64378) was not enforced while draining a node before Kubernetes 1.12. + +::: + +### Drained and Cordoned State + +If there's any error related to user input, the node enters a `cordoned` state because the drain failed. You can either correct the input and attempt to drain the node again, or you can abort by uncordoning the node. + +If the drain continues without error, the node enters a `draining` state. You'll have the option to stop the drain when the node is in this state, which then stops the drain process and changes the node's state to `cordoned`. + +Once drain successfully completes, the node is in a state of `drained`. You can then power off or delete the node. + +**Want to know more about cordon and drain?** See the [Kubernetes documentation](https://kubernetes.io/docs/tasks/administer-cluster/safely-drain-node/). + +## Labeling a Node to be Ignored by Rancher + +Certain solutions, such as F5's BIG-IP integration, may require creating a node that is never registered to a cluster. + +Since the node never finishes registering, it is always shown as unhealthy in the Rancher UI. + +In that case, you may want to label the node to be ignored by Rancher so that Rancher only shows nodes as unhealthy when they are actually failing. + +You can label nodes to be ignored by using a setting in the Rancher UI, or by using `kubectl`. + +:::note + +There is an [open issue](https://github.com/rancher/rancher/issues/24172) in which nodes labeled to be ignored can get stuck in an updating state. + +::: + + +### Labeling Nodes to be Ignored with kubectl + +To add a node that is ignored by Rancher, use `kubectl` to create a node that has the following label: + +``` +cattle.rancher.io/node-status: ignore +``` + +**Result**: If you add the node to a cluster, Rancher skips syncing with this node. The node can still be part of the cluster and can be listed with `kubectl`. + +If the label is added before the node is added to the cluster, the node is not shown in the Rancher UI. + +If the label is added after the node is added to a Rancher cluster, the node is not removed from the UI. + +If you delete the node from the Rancher server using the Rancher UI or API, the node is not removed from the cluster if the `nodeName` is listed in the Rancher settings in the Rancher API under `v3/settings/ignore-node-name`. diff --git a/versioned_docs/version-2.14/how-to-guides/new-user-guides/manage-clusters/projects-and-namespaces.md b/versioned_docs/version-2.14/how-to-guides/new-user-guides/manage-clusters/projects-and-namespaces.md new file mode 100644 index 00000000000..57233c17fb1 --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/new-user-guides/manage-clusters/projects-and-namespaces.md @@ -0,0 +1,202 @@ +--- +title: Projects and Kubernetes Namespaces with Rancher +description: Rancher Projects ease the administrative burden of your cluster and support multi-tenancy. Learn to create projects and divide projects into Kubernetes namespaces +--- + + + + + +A namespace is a Kubernetes concept that allows a virtual cluster within a cluster, which is useful for dividing the cluster into separate "virtual clusters" that each have their own access control and resource quotas. + +A project is a group of namespaces, and it is a concept introduced by Rancher. Projects allow you to manage multiple namespaces as a group and perform Kubernetes operations in them. You can use projects to support multi-tenancy, so that a team can access a project within a cluster without having access to other projects in the same cluster. + +:::note + +Projects are de-emphasized on the UI because it is not required to create Kubernetes resources within a project scope. However, resources such as [Secrets](../../new-user-guides/kubernetes-resources-setup/secrets.md#creating-secrets-in-projects) can still be created in a project scope. + +::: + +This section describes how projects and namespaces work with Rancher. + +## About Namespaces + +A namespace is a concept introduced by Kubernetes. According to the [official Kubernetes documentation on namespaces,](https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/) + +:::note + +Kubernetes supports multiple virtual clusters backed by the same physical cluster. These virtual clusters are called namespaces. [...] Namespaces are intended for use in environments with many users spread across multiple teams, or projects. For clusters with a few to tens of users, you should not need to create or think about namespaces at all. + +::: + +Namespaces provide the following functionality: + +- **Providing a scope for names:** Names of resources need to be unique within a namespace, but not across namespaces. Namespaces can not be nested inside one another and each Kubernetes resource can only be in one namespace. +- **Resource quotas:** Namespaces provide a way to divide cluster resources between multiple users. + +You can assign resources at the project level so that each namespace in the project can use them. You can also bypass this inheritance by assigning resources explicitly to a namespace. + +You can assign the following resources directly to namespaces: + +- [Workloads](../kubernetes-resources-setup/workloads-and-pods/workloads-and-pods.md) +- [Load Balancers/Ingress](../kubernetes-resources-setup/load-balancer-and-ingress-controller/load-balancer-and-ingress-controller.md) +- [Service Discovery Records](../../new-user-guides/kubernetes-resources-setup/create-services.md) +- [Persistent Volume Claims](create-kubernetes-persistent-storage/create-kubernetes-persistent-storage.md) +- [Certificates](../../new-user-guides/kubernetes-resources-setup/encrypt-http-communication.md) +- [ConfigMaps](../../new-user-guides/kubernetes-resources-setup/configmaps.md) +- [Registries](../../new-user-guides/kubernetes-resources-setup/kubernetes-and-docker-registries.md) +- [Secrets](../../new-user-guides/kubernetes-resources-setup/secrets.md) + +To manage permissions in a vanilla Kubernetes cluster, cluster admins configure role-based access policies for each namespace. With Rancher, user permissions are assigned on the project level instead, and permissions are automatically inherited by any namespace owned by the particular project. + +For more information on creating and moving namespaces, see [Namespaces](../../new-user-guides/manage-namespaces.md). + +### Role-based access control issues with namespaces and kubectl + +Because projects are a concept introduced by Rancher, kubectl does not have the capability to restrict the creation of namespaces to a project the creator has access to. + +This means that when standard users with project-scoped permissions create a namespaces with `kubectl`, it may be unusable because `kubectl` doesn't require the new namespace to be scoped within a certain project. + +If your permissions are restricted to the project level, it is better to [create a namespace through Rancher](../../new-user-guides/manage-namespaces.md) to ensure that you will have permission to access the namespace. + +If a standard user is a project owner, the user will be able to create namespaces within that project. The Rancher UI will prevent that user from creating namespaces outside the scope of the projects they have access to. + +## About Projects + +In terms of hierarchy: + +- Clusters contain projects +- Projects contain namespaces + +You can use projects to support multi-tenancy, so that a team can access a project within a cluster without having access to other projects in the same cluster. + +In the base version of Kubernetes, features like role-based access rights or cluster resources are assigned to individual namespaces. A project allows you to save time by giving an individual or a team access to multiple namespaces simultaneously. + +You can use projects to perform actions such as: + +- Assign users to a group of namespaces (i.e., [project membership](../authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/cluster-and-project-roles.md)). +- Assign users specific roles in a project. A role can be owner, member, read-only, or [custom](../authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/custom-roles.md). +- Assign resources to the project. +- Assign Pod Security Policies. + +When you create a cluster, two projects are automatically created within it: + +- [Default Project](#the-clusters-default-project) +- [System Project](#the-system-project) + +### The Cluster's Default Project + +When you provision a cluster with Rancher, it automatically creates a `default` project for the cluster. This is a project you can use to get started with your cluster, but you can always delete it and replace it with projects that have more descriptive names. + +If you don't have a need for more than the default namespace, you also do not need more than the **Default** project in Rancher. + +If you require another level of organization beyond the **Default** project, you can create more projects in Rancher to isolate namespaces, applications and resources. + +### The System Project + +When troubleshooting, you can view the `system` project to check if important namespaces in the Kubernetes system are working properly. This easily accessible project saves you from troubleshooting individual system namespace containers. + +To open it, open the cluster view and click **Cluster > Projects/Namespaces**. This view shows all of the namespaces in the `system` project. + +The `system` project: + +- Is automatically created when you provision a cluster. +- Lists all namespaces that exist in `v3/settings/system-namespaces`, if they exist. +- Allows you to add more namespaces or move its namespaces to other projects. +- Cannot be deleted because it's required for cluster operations. + +:::note + +In RKE2/K3s clusters where the project network isolation option is enabled, the `system` project overrides the project network isolation option so that it can communicate with other projects, collect logs, and check health. + +::: + +## Project Authorization + +Standard users are only authorized for project access in two situations: + +- An administrator, cluster owner or cluster member explicitly adds the standard user to the project's **Members** tab. +- Standard users can access projects that they create themselves. + +## Pod Security Policies + +Rancher extends Kubernetes to allow the application of [Pod Security Policies](https://kubernetes.io/docs/concepts/policy/pod-security-policy/) at the project level in addition to the cluster level. However, as a best practice, we recommend applying Pod Security Policies at the cluster level. + +## Creating Projects + +This section describes how to create a new project with a name and with optional pod security policy, members, and resource quotas. + +1. [Name a new project.](#name-a-new-project) +1. [Recommended: Add project members.](#recommended-add-project-members) +1. [Optional: Add resource quotas.](#optional-add-resource-quotas) + +### Name a New Project + +1. In the upper left corner, click **☰ > Cluster Management**. +1. On the **Clusters** page, go to the cluster you want to project in and click **Explore**. +1. Click **Cluster > Projects/Namespaces**. +1. Click **Create Project**. +1. Enter a **Project Name**. + +### Recommended: Add Project Members + +Use the **Members** section to provide other users with project access and roles. + +By default, your user is added as the project `Owner`. + +:::note Notes on Permissions: + +- Users assigned the `Owner` or `Member` role for a project automatically inherit the `namespace creation` role. However, this role is a [Kubernetes ClusterRole](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#role-and-clusterrole), meaning its scope extends to all projects in the cluster. Therefore, users explicitly assigned the `Owner` or `Member` role for a project can create namespaces in other projects they're assigned to, even with only the `Read Only` role assigned. + +- By default, the Rancher role of `project-member` inherits from the `Kubernetes-edit` role, and the `project-owner` role inherits from the `Kubernetes-admin` role. As such, both `project-member` and `project-owner` roles will allow for namespace management, including the ability to create and delete namespaces. + +- Choose `Custom` to create a custom role on the fly: [Custom Project Roles](../authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/cluster-and-project-roles.md#custom-project-roles). + +::: + +To add members: + +1. In the **Members** tab, click **Add**. +1. From the **Select Member** field, search for a user or group that you want to assign project access. You can only search for groups if external authentication is enabled. + + :::note Notes: + + - At least 2 characters must be typed in the search box for results to appear. + - Users can be searched based on their username or display name. + - Search is prefix-based (e.g., a user named `Stan Dard` will appear when searching for `Sta`, but not when searching for `Dar`) and case-sensitive. + + ::: +1. In the **Project Permissions** section, choose a role. For more information, refer to the [documentation on project roles.](../authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/cluster-and-project-roles.md) + +### Optional: Add Resource Quotas + +Resource quotas limit the resources that a project (and its namespaces) can consume. For more information, see [Resource Quotas](../../advanced-user-guides/manage-projects/manage-project-resource-quotas/manage-project-resource-quotas.md). + +To add a resource quota, + +1. In the **Resource Quotas** tab, click **Add Resource**. +1. Select a **Resource Type**. For more information, see [Resource Quotas.](../../advanced-user-guides/manage-projects/manage-project-resource-quotas/manage-project-resource-quotas.md). +1. Enter values for the **Project Limit** and the **Namespace Default Limit**. +1. **Optional:** Specify **Container Default Resource Limit**, which will be applied to every container started in the project. The parameter is recommended if you have CPU or Memory limits set by the Resource Quota. It can be overridden on per an individual namespace or a container level. For more information, see [Container Default Resource Limit](../../advanced-user-guides/manage-projects/manage-project-resource-quotas/manage-project-resource-quotas.md) +1. Click **Create**. + +**Result:** Your project is created. You can view it from the cluster's **Projects/Namespaces** view. + +| Field | Description | +| ----------------------- | -------------------------------------------------------------------------------------------------------- | +| Project Limit | The overall resource limit for the project. | +| Namespace Default Limit | The default resource limit available for each namespace. This limit is propagated to each namespace in the project when created. The combined limit of all project namespaces shouldn't exceed the project limit. | + +## Deleting Projects + +1. In the upper left corner, click **☰ > Cluster Management**. +1. On the **Clusters** page, go to the cluster the project is attached to, and click **Explore**. +1. Click **Cluster > Projects/Namespaces**. +1. Find the project you want to delete, and click **⋮**. +1. Select **Delete**. + +When you delete a project, any namespaces that were formerly associated with the project will remain on the cluster. You can find these namespaces in the Rancher UI, in the **Not in a Project** tab of the **Projects/Namespaces** page. You can reassign these namespaces to a project by [moving](../manage-namespaces.md#moving-namespaces-to-another-project) them. + +## Further Reading + +You can create projects and project members more programmatically via the [Public API](../../../api/quickstart.md). See the [project workflow doc](../../../api/workflows/projects.md) for more information. diff --git a/versioned_docs/version-2.14/how-to-guides/new-user-guides/manage-clusters/provisioning-storage-examples/nfs-storage.md b/versioned_docs/version-2.14/how-to-guides/new-user-guides/manage-clusters/provisioning-storage-examples/nfs-storage.md new file mode 100644 index 00000000000..b5fd1fee669 --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/new-user-guides/manage-clusters/provisioning-storage-examples/nfs-storage.md @@ -0,0 +1,79 @@ +--- +title: NFS Storage +--- + + + + + +Before you can use the NFS storage volume plug-in with Rancher deployments, you need to provision an NFS server. + +:::note + +- If you already have an NFS share, you don't need to provision a new NFS server to use the NFS volume plugin within Rancher. Instead, skip the rest of this procedure and complete [adding storage](../create-kubernetes-persistent-storage/create-kubernetes-persistent-storage.md). + +- This procedure demonstrates how to set up an NFS server using Ubuntu, although you should be able to use these instructions for other Linux distros (e.g. Debian, RHEL, Arch Linux, etc.). For official instruction on how to create an NFS server using another Linux distro, consult the distro's documentation. + +::: + +:::note Recommended: + +To simplify the process of managing firewall rules, use NFSv4. + +::: + +1. Using a remote Terminal connection, log into the Ubuntu server that you intend to use for NFS storage. + +1. Enter the following command: + + ``` + sudo apt-get install nfs-kernel-server + ``` + +1. Enter the command below, which sets the directory used for storage, along with user access rights. Modify the command if you'd like to keep storage at a different directory. + + ``` + mkdir -p /nfs && chown nobody:nogroup /nfs + ``` + - The `-p /nfs` parameter creates a directory named `nfs` at root. + - The `chown nobody:nogroup /nfs` parameter allows all access to the storage directory. + +1. Create an NFS exports table. This table sets the directory paths on your NFS server that are exposed to the nodes that will use the server for storage. + + 1. Open `/etc/exports` using your text editor of choice. + 1. Add the path of the `/nfs` folder that you created in step 3, along with the IP addresses of your cluster nodes. Add an entry for each IP address in your cluster. Follow each address and its accompanying parameters with a single space that is a delimiter. + + ``` + /nfs (rw,sync,no_subtree_check) (rw,sync,no_subtree_check) (rw,sync,no_subtree_check) + ``` + + :::tip + + You can replace the IP addresses with a subnet. For example: `10.212.50.12/24` + + ::: + + 1. Update the NFS table by entering the following command: + + ``` + exportfs -ra + ``` + +1. Open the ports used by NFS. + + 1. To find out what ports NFS is using, enter the following command: + + ``` + rpcinfo -p | grep nfs + ``` + 2. [Open the ports](https://help.ubuntu.com/lts/serverguide/firewall.html.en) that the previous command outputs. For example, the following command opens port 2049: + + ``` + sudo ufw allow 2049 + ``` + +**Result:** Your NFS server is configured to be used for storage with your Rancher nodes. + +## What's Next? + +Within Rancher, add the NFS server as a storage volume and/or storage class. After adding the server, you can use it for storage for your deployments. diff --git a/versioned_docs/version-2.14/how-to-guides/new-user-guides/manage-clusters/provisioning-storage-examples/persistent-storage-in-amazon-ebs.md b/versioned_docs/version-2.14/how-to-guides/new-user-guides/manage-clusters/provisioning-storage-examples/persistent-storage-in-amazon-ebs.md new file mode 100644 index 00000000000..059bb688673 --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/new-user-guides/manage-clusters/provisioning-storage-examples/persistent-storage-in-amazon-ebs.md @@ -0,0 +1,19 @@ +--- +title: Creating Persistent Storage in Amazon's EBS +--- + + + + + +This section describes how to set up Amazon's Elastic Block Store in EC2. + +1. From the EC2 console, go to the **ELASTIC BLOCK STORE** section in the left panel and click **Volumes**. +1. Click **Create Volume**. +1. Optional: Configure the size of the volume or other options. The volume should be created in the same availability zone as the instance it will be attached to. +1. Click **Create Volume**. +1. Click **Close**. + +**Result:** Persistent storage has been created. + +For details on how to set up the newly created storage in Rancher, refer to the section on [setting up existing storage.](../../../new-user-guides/manage-clusters/create-kubernetes-persistent-storage/manage-persistent-storage/set-up-existing-storage.md) \ No newline at end of file diff --git a/versioned_docs/version-2.14/how-to-guides/new-user-guides/manage-clusters/provisioning-storage-examples/provisioning-storage-examples.md b/versioned_docs/version-2.14/how-to-guides/new-user-guides/manage-clusters/provisioning-storage-examples/provisioning-storage-examples.md new file mode 100644 index 00000000000..d4b85fec0c2 --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/new-user-guides/manage-clusters/provisioning-storage-examples/provisioning-storage-examples.md @@ -0,0 +1,15 @@ +--- +title: Provisioning Storage Examples +--- + + + + + +Rancher supports persistent storage with a variety of volume plugins. However, before you use any of these plugins to bind persistent storage to your workloads, you have to configure the storage itself, whether its a cloud-based solution from a service-provider or an on-prem solution that you manage yourself. + +For your convenience, Rancher offers documentation on how to configure some of the popular storage methods: + +- [NFS](nfs-storage.md) +- [vSphere](vsphere-storage.md) +- [EBS](persistent-storage-in-amazon-ebs.md) diff --git a/versioned_docs/version-2.14/how-to-guides/new-user-guides/manage-clusters/provisioning-storage-examples/vsphere-storage.md b/versioned_docs/version-2.14/how-to-guides/new-user-guides/manage-clusters/provisioning-storage-examples/vsphere-storage.md new file mode 100644 index 00000000000..9d818629963 --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/new-user-guides/manage-clusters/provisioning-storage-examples/vsphere-storage.md @@ -0,0 +1,76 @@ +--- +title: VMware vSphere Storage +--- + + + + + +To provide stateful workloads with VMware vSphere storage, we recommend creating a vSphereVolume StorageClass. This practice dynamically provisions vSphere storage when workloads request volumes through a PersistentVolumeClaim. + +In order to dynamically provision storage in vSphere, the vSphere provider must be enabled. See the following pages for more: [Out-of-tree vSphere](../../../new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-cloud-providers/configure-out-of-tree-vsphere.md) and [in-tree vSphere](../../../new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-cloud-providers/configure-in-tree-vsphere.md). + + +### Prerequisites + +In order to provision vSphere volumes in a cluster created with the [Rancher Kubernetes Engine (RKE)](../../launch-kubernetes-with-rancher/launch-kubernetes-with-rancher.md), the [vSphere cloud provider](https://rancher.com/docs/rke/latest/en/config-options/cloud-providers/vsphere) must be explicitly enabled in the [cluster options](../../../../reference-guides/cluster-configuration/rancher-server-configuration/rke1-cluster-configuration.md). + +### Creating a StorageClass + +:::tip + +The following steps can also be performed using the `kubectl` command line tool. See [Kubernetes documentation on persistent volumes](https://kubernetes.io/docs/concepts/storage/persistent-volumes/) for details. + +::: + +1. Click **☰ > Cluster Management**. +1. Choose the cluster you want to provide vSphere storage to and click **Exlpore**. +1. In the left navigation bar, select **Storage > StorageClasses**. +1. Click **Create**. +3. Enter a **Name** for the StorageClass. +4. Under **Provisioner**, select **VMWare vSphere Volume**. + + ![](/img/vsphere-storage-class.png) + +5. Optionally, specify additional properties for this storage class under **Parameters**. Refer to the [vSphere storage documentation](https://github.com/vmware-archive/vsphere-storage-for-kubernetes/blob/master/documentation/storageclass.md) for details. +5. Click **Create**. + +### Creating a Workload with a VMware vSphere Volume + +1. In the left navigation bar, click **Workload**. +1. Click **Create**. +1. Click **StatefulSet**. +1. In the **Volume Claim Templates** tab, click **Add Claim Template**. +1. Enter a persistent volume name. +1. In the Storage Class field, select the vSphere StorageClass that you created. +6. Enter the required **Capacity** for the volume. Then click **Define**. +7. Assign a path in the **Mount Point** field. This is the full path where the volume will be mounted in the container file system, e.g. `/persistent`. +8. Click **Create**. + +### Verifying Persistence of the Volume + +1. In the left navigation bar, click **Workload > Pods**. +1. Go to the workload you just created and click **⋮ > Execute Shell**. +2. Note the directory at root where the volume has been mounted to (in this case `/persistent`). +3. Create a file in the volume by executing the command `touch //data.txt`. +4. Close the shell window. +5. Click on the name of the workload to reveal detail information. +7. Click **⋮ > Delete**. +8. Observe that the pod is deleted. Then a new pod is scheduled to replace it so that the workload maintains its configured scale of a single stateful pod. +9. Once the replacement pod is running, click **Execute Shell**. +10. Inspect the contents of the directory where the volume is mounted by entering `ls -l /`. Note that the file you created earlier is still present. + + ![workload-persistent-data](/img/workload-persistent-data.png) + +### Why to Use StatefulSets Instead of Deployments + +You should always use [StatefulSets](https://kubernetes.io/docs/concepts/workloads/controllers/statefulset/) for workloads consuming vSphere storage, as this resource type is designed to address a VMDK block storage caveat. + +Since vSphere volumes are backed by VMDK block storage, they only support an [access mode](https://kubernetes.io/docs/concepts/storage/persistent-volumes/#persistentvolumeclaims) of `ReadWriteOnce`. This setting restricts the volume so that it can only be mounted to a single pod at a time, unless all pods consuming that volume are co-located on the same node. This behavior makes a deployment resource unusable for scaling beyond a single replica if it consumes vSphere volumes. + +Even using a deployment resource with just a single replica may result in a deadlock situation while updating the deployment. If the updated pod is scheduled to a node different from where the existing pod lives, it will fail to start because the VMDK is still attached to the other node. + +### Related Links + +- [vSphere Storage for Kubernetes](https://github.com/vmware-archive/vsphere-storage-for-kubernetes/tree/master/documentation) +- [Kubernetes Persistent Volumes](https://kubernetes.io/docs/concepts/storage/persistent-volumes/) diff --git a/versioned_docs/version-2.14/how-to-guides/new-user-guides/manage-clusters/rotate-certificates.md b/versioned_docs/version-2.14/how-to-guides/new-user-guides/manage-clusters/rotate-certificates.md new file mode 100644 index 00000000000..259fcecbcf6 --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/new-user-guides/manage-clusters/rotate-certificates.md @@ -0,0 +1,54 @@ +--- +title: Certificate Rotation +--- + + + + + +:::caution + +Rotating Kubernetes certificates may result in your cluster being temporarily unavailable as components are restarted. For production environments, it's recommended to perform this action during a maintenance window. + +::: + +By default, Kubernetes clusters require certificates and Rancher launched Kubernetes clusters automatically generate certificates for the Kubernetes components. Rotating these certificates is important before the certificates expire as well as if a certificate is compromised. After the certificates are rotated, the Kubernetes components are automatically restarted. + +Certificates can be rotated for the following services: + +- admin +- api-server +- controller-manager +- scheduler +- rke2-controller +- rke2-server +- cloud-controller +- etcd +- auth-proxy +- kubelet +- kube-proxy + +:::note + +For users who didn't rotate their webhook certificates, and they have expired after one year, please see this [page](../../../troubleshooting/other-troubleshooting-tips/expired-webhook-certificate-rotation.md) for help. + +::: + +### Certificate Rotation + +Rancher launched Kubernetes clusters have the ability to rotate the auto-generated certificates through the UI. + +1. In the upper left corner, click **☰ > Cluster Management**. +1. On the **Clusters** page, go to the cluster you want to rotate certificates for and click **⋮ > Rotate Certificates**. +1. Select which certificates that you want to rotate. + + * Rotate all Service certificates (keep the same CA) + * Rotate an individual service and choose one of the services from the drop-down menu + +1. Click **Save**. + +**Results:** The selected certificates will be rotated and the related services will be restarted to start using the new certificate. + +### Additional Notes + +In RKE2/K3s, both etcd and control plane nodes are treated as the same `server` concept. As such, when rotating certificates of services specific to either of these components will result in certificates being rotated on both. The certificates will only change for the specified service, but you will see nodes for both components go into an updating state. You may also see worker only nodes go into an updating state. This is to restart the workers after a certificate change to ensure they get the latest client certs. diff --git a/versioned_docs/version-2.14/how-to-guides/new-user-guides/manage-clusters/rotate-encryption-key.md b/versioned_docs/version-2.14/how-to-guides/new-user-guides/manage-clusters/rotate-encryption-key.md new file mode 100644 index 00000000000..59d1eed2fac --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/new-user-guides/manage-clusters/rotate-encryption-key.md @@ -0,0 +1,23 @@ +--- +title: Encryption Key Rotation +--- + + + + + +:::note Important + +Encryption key rotation is enabled by default and cannot be disabled. + +::: + +To rotate keys in the Rancher UI: + +1. Click **☰ > Cluster Management**. + +1. Select **⋮ > Rotate Encryption Keys** on the far right of the screen next to your chosen cluster: + + ![Encryption Key Rotation](/img/rke2-encryption-key.png) + +>**Note:** For more information on RKE2 secrets encryption config, please see the [RKE2 docs](https://docs.rke2.io/security/secrets_encryption). diff --git a/versioned_docs/version-2.14/how-to-guides/new-user-guides/manage-namespaces.md b/versioned_docs/version-2.14/how-to-guides/new-user-guides/manage-namespaces.md new file mode 100644 index 00000000000..5d92c7331a2 --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/new-user-guides/manage-namespaces.md @@ -0,0 +1,78 @@ +--- +title: Namespaces +--- + + + + + +Within Rancher, you can further divide projects into different [namespaces](https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/), which are virtual clusters within a project backed by a physical cluster. Should you require another level of organization beyond projects and the `default` namespace, you can use multiple namespaces to isolate applications and resources. + +Although you assign resources at the project level so that each namespace in the project can use them, you can override this inheritance by assigning resources explicitly to a namespace. + +Resources that you can assign directly to namespaces include: + +- [Workloads](kubernetes-resources-setup/workloads-and-pods/workloads-and-pods.md) +- [Load Balancers/Ingress](kubernetes-resources-setup/load-balancer-and-ingress-controller/load-balancer-and-ingress-controller.md) +- [Service Discovery Records](kubernetes-resources-setup/create-services.md) +- [Persistent Volume Claims](manage-clusters/create-kubernetes-persistent-storage/create-kubernetes-persistent-storage.md) +- [Certificates](kubernetes-resources-setup/encrypt-http-communication.md) +- [ConfigMaps](kubernetes-resources-setup/configmaps.md) +- [Registries](kubernetes-resources-setup/kubernetes-and-docker-registries.md) +- [Secrets](kubernetes-resources-setup/secrets.md) + +To manage permissions in a vanilla Kubernetes cluster, cluster admins configure role-based access policies for each namespace. With Rancher, user permissions are assigned on the project level instead, and permissions are automatically inherited by any namespace owned by the particular project. + +:::note + +If you create a namespace with `kubectl`, it may be unusable because `kubectl` doesn't require your new namespace to be scoped within a project that you have access to. If your permissions are restricted to the project level, it is better to [create a namespace through Rancher](#creating-namespaces) to ensure that you will have permission to access the namespace. + +::: + +## Creating Namespaces + +Create a new namespace to isolate apps and resources in a project. + +:::tip + +When working with project resources that you can assign to a namespace (i.e., [workloads](kubernetes-resources-setup/workloads-and-pods/deploy-workloads.md), [certificates](kubernetes-resources-setup/encrypt-http-communication.md), [ConfigMaps](kubernetes-resources-setup/configmaps.md), etc.) you can create a namespace on the fly. + +::: + +1. In the upper left corner, click **☰ > Cluster Management**. +1. On the **Clusters** page, go to the cluster where you want to create a namespace and click **Explore**. +1. Click **Cluster > Projects/Namespaces**. +1. Go to the project where you want to add a namespace and click **Create Namespace**. Alternately, go to **Not in a Project** to create a namespace not associated with a project. + +1. **Optional:** If your project has [Resource Quotas](../advanced-user-guides/manage-projects/manage-project-resource-quotas/manage-project-resource-quotas.md) in effect, you can override the default resource **Limits** (which places a cap on the resources that the namespace can consume). + +1. Enter a **Name** and then click **Create**. + +**Result:** Your namespace is added to the project. You can begin assigning cluster resources to the namespace. + +## Moving Namespaces to Another Project + +Cluster admins and members may occasionally need to move a namespace to another project, such as when you want a different team to start using the application. + +1. In the upper left corner, click **☰ > Cluster Management**. +1. On the **Clusters** page, go to the cluster where you want to move a namespace and click **Explore**. +1. Click **Cluster > Projects/Namespaces**. +1. Go to the namespace you want to move and click **⋮ > Move**. + +1. Select the namespace(s) that you want to move to a different project. Then click **Move**. You can move multiple namespaces at one. + + :::note Notes: + + - Don't move the namespaces in the `System` project. Moving these namespaces can adversely affect cluster networking. + - You cannot move a namespace into a project that already has a [resource quota](../advanced-user-guides/manage-projects/manage-project-resource-quotas/manage-project-resource-quotas.md)configured. + - If you move a namespace from a project that has a quota set to a project with no quota set, the quota is removed from the namespace. + +1. Choose a new project for the new namespace and then click **Move**. Alternatively, you can remove the namespace from all projects by selecting **None**. + +**Result:** Your namespace is moved to a different project (or is unattached from all projects). If any project resources are attached to the namespace, the namespace releases them and then attached resources from the new project. + +## Editing Namespace Resource Quotas + +You can always override the namespace default limit to provide a specific namespace with access to more (or less) project resources. + +For more information, see how to [edit namespace resource quotas](../advanced-user-guides/manage-projects/manage-project-resource-quotas/override-default-limit-in-namespaces.md). \ No newline at end of file diff --git a/versioned_docs/version-2.14/how-to-guides/new-user-guides/new-user-guides.md b/versioned_docs/version-2.14/how-to-guides/new-user-guides/new-user-guides.md new file mode 100644 index 00000000000..cc86980e4ad --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/new-user-guides/new-user-guides.md @@ -0,0 +1,13 @@ +--- +title: New User Guides +--- + + + + + +New user guides, also known as **tutorials**, describe practical steps for users to follow in order to complete some concrete action. These docs are known as "learning-oriented" docs in which users learn by "doing". + +The new user guides are designed to guide beginners, or the everyday users of Rancher, through a series of steps to learn how to do something. The goal is that the user will be able to learn how to complete tasks by using easy-to-follow, meaningful, and repeatable directions. These guides will assist users to do work to then get the promised results immediately. + +The average Rancher user has a level of technical skill that is above the level of "beginner"; however, the new user guides are designed to help new, or beginner, users as well as the seasoned Rancher customer equally. This is accomplished by using a combination of high-level and technical language to introduce topics and guide the user through general tasks that are essential for every Rancher user to know. \ No newline at end of file diff --git a/versioned_docs/version-2.14/integrations-in-rancher/cloud-marketplace/aws-cloud-marketplace/adapter-requirements.md b/versioned_docs/version-2.14/integrations-in-rancher/cloud-marketplace/aws-cloud-marketplace/adapter-requirements.md new file mode 100644 index 00000000000..0116f4d9f63 --- /dev/null +++ b/versioned_docs/version-2.14/integrations-in-rancher/cloud-marketplace/aws-cloud-marketplace/adapter-requirements.md @@ -0,0 +1,100 @@ +--- +title: Prerequisites +--- + + + + + +### 1. Setting Up License Manager and Purchasing Support + +First, complete the [first step](https://docs.aws.amazon.com/license-manager/latest/userguide/getting-started.html) of the license manager one-time setup. +Next, go to the AWS Marketplace. Locate the "Rancher Premium Support Billing Container Starter Pack". Purchase at least one entitlement. + +If you have installed Rancher using the "Rancher Setup" AWS Marketplace offering, skip to [Step 4](#4-create-an-oidc-provider). + +> **Note:** Each entitlement grants access to support for a certain amount of nodes. You can purchase more licenses as necessary later on. + +### 2. Create an EKS Cluster +Follow the [Rancher docs](../../../getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/rancher-on-amazon-eks.md) to create an EKS cluster. When you get to the [final step to install Rancher](../../../getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/rancher-on-amazon-eks.md#8-install-the-rancher-helm-chart), **stop and return to this page**. This cluster will need to meet the following requirements: + +- EKS version 1.22. +- Each node in the cluster has access to the registry containing Rancher and its related images. +- Each node in the cluster has access to the ECR repo storing the CSP Adapter. +- Each node in the cluster has access to the license manager service. +- Each node in the cluster has access to global endpoints for the STS service. + +### 3. Install Rancher + +In addition to the options specified to install Rancher in the [Rancher docs](../../../getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/rancher-on-amazon-eks.md#8-install-the-rancher-helm-chart), you will also need to enable extra metrics. +This can be done through the Helm CLI through the following options: + +```bash +--set extraEnv\[0\].name="CATTLE_PROMETHEUS_METRICS" --set-string extraEnv\[0\].value=true +``` + +You can also use a values.yaml like the below: + +```yaml +extraEnv: + - name: "CATTLE_PROMETHEUS_METRICS" + value: "true" +``` + +You will also need to install Rancher version 2.6.7 or higher. + +### 4. Create an OIDC Provider + +Follow the [AWS documentation](https://docs.aws.amazon.com/eks/latest/userguide/enable-iam-roles-for-service-accounts.html) to create an OIDC provider for the cluster specified in the previous section. + +### 5. Create an IAM Role + +An IAM role is required for the CSP adapter to check-in/check-out entitlements. + +First, configure the trust policy as below. Replace `MY_AWS_ACC` with your AWS account number, `MY_AWS_REGION` with your AWS region, and `MY_OIDC_PROVIDER` with the id of your OIDC provider: + +```json +{ + "Version": "2012-10-17", + "Statement": [ + { + "Effect": "Allow", + "Principal": { + "Federated": "arn:aws:iam::${MY_AWS_ACC}:oidc-provider/oidc.eks.${MY_AWS_REGION}.amazonaws.com/id/${MY_OIDC_PROVIDER}" + }, + "Action": "sts:AssumeRoleWithWebIdentity", + "Condition": { + "StringEquals": { + "oidc.eks.${MY_AWS_REGION}.amazonaws.com/id/${MY_OIDC_PROVIDER}:sub": "system:serviceaccount:cattle-csp-adapter-system:rancher-csp-adapter", + "oidc.eks.${MY_AWS_REGION}.amazonaws.com/id/${MY_OIDC_PROVIDER}:aud": "sts.amazonaws.com" + } + } + } + ] +} +``` + +Next, use a policy for the role which has the following permissions: + +```json +{ + "Version": "2012-10-17", + "Statement": [ + { + "Sid": "RancherCSPAdapterPermissions", + "Effect": "Allow", + "Action": [ + "license-manager:ListReceivedLicenses", + "license-manager:CheckoutLicense", + "license-manager:ExtendLicenseConsumption", + "license-manager:CheckInLicense", + "license-manager:GetLicense", + "license-manager:GetLicenseUsage" + ], + "Resource": "*" + } + ] +} +``` + +Save the name of the role. You will need it later on when installing the CSP adapter. diff --git a/versioned_docs/version-2.14/integrations-in-rancher/cloud-marketplace/aws-cloud-marketplace/aws-cloud-marketplace.md b/versioned_docs/version-2.14/integrations-in-rancher/cloud-marketplace/aws-cloud-marketplace/aws-cloud-marketplace.md new file mode 100644 index 00000000000..a216cd61317 --- /dev/null +++ b/versioned_docs/version-2.14/integrations-in-rancher/cloud-marketplace/aws-cloud-marketplace/aws-cloud-marketplace.md @@ -0,0 +1,40 @@ +--- +title: AWS Marketplace Integration +--- + + + + + +## Overview + +Rancher offers an integration with the AWS Marketplace which allows users to purchase a support contract with SUSE. This integration allows you easily adjust your support needs as you start to support more clusters. + +## Required Skills + +At a minimum, users are expected to have a working knowledge of EKS and peripheral functions such as IAM Policies and Roles, Route 53 DNS, and the use of awscli and Helm commands. + +## Limitations + +- You must be running Rancher v2.6.7 or higher +- Rancher must be deployed with additional metrics enabled. +- Rancher must be installed on an EKS cluster. +- You must purchase at least one entitlement to Rancher support through AWS Marketplace. +- You may need additional setup to support proxy/airgap use cases. See the [prerequisites](adapter-requirements.md) for more information. + +## How to Use + +1. Complete the [prerequisite steps](adapter-requirements.md). +2. [Install the CSP Adapter](install-adapter.md). + +## FAQ + +**Can I purchase support for more nodes later on?** + +Yes. Simply go to the AWS Marketplace entry that you used to initially purchase support and increase the number of entitlements. + +**Can I use multiple instances of Rancher in the same AWS account?** + +Yes. However, each cluster that Rancher is installed in will need to adhere to the prerequisites. + +In addition, keep in mind that a given entitlement can only be used by one Rancher management server at a time. diff --git a/versioned_docs/version-2.14/integrations-in-rancher/cloud-marketplace/aws-cloud-marketplace/common-issues.md b/versioned_docs/version-2.14/integrations-in-rancher/cloud-marketplace/aws-cloud-marketplace/common-issues.md new file mode 100644 index 00000000000..c8f8e51cce7 --- /dev/null +++ b/versioned_docs/version-2.14/integrations-in-rancher/cloud-marketplace/aws-cloud-marketplace/common-issues.md @@ -0,0 +1,32 @@ +--- +title: Common Issues +--- + + + + + +**After installing the adapter, a banner message appears in Rancher that says "AWS Marketplace Adapter: Unable to run the adapter, please check the adapter logs"** + +This error indicates that while the adapter was installed into the cluster, an error has occurred which prevents it from properly checking-in/checking-out licenses. + +This often occurs because the IAM role was not set up properly. Review the [prerequisites](./adapter-requirements.md) and verify that: + +- An OIDC provider has been created/associated with the cluster Rancher is running on. +- The IAM role has been configured to trust this OIDC provider. +- The IAM role has at least the permissions outlined in the policy. + +If all of the above have been configured correctly, reach out to support for assistance. + +**I see a banner message that states, "AWS Marketplace Adapter: You have exceeded your licensed node count. At least x more license(s) are required in AWS to become compliant"** + +This message indicates that you do not have enough entitlements for the amount of nodes Rancher is currently managing. + +Keep in mind the following limitations: + +- Each entitlement is valid for a certain number of nodes. +- Every node currently managed by Rancher counts toward your usage total (with exception of nodes in the cluster rancher is installed on). +- Each entitlement can be used by at most one Rancher instance. For example, if you have two running Rancher instances in your account (each installed on a separate EKS cluster), then you will need at least two entitlements. + +You may also have recently uninstalled/re-installed the adapter. If the adapter loses track of the licenses that it is currently managing, it can take up to an hour to resolve the actual state of the licenses. + diff --git a/versioned_docs/version-2.14/integrations-in-rancher/cloud-marketplace/aws-cloud-marketplace/install-adapter.md b/versioned_docs/version-2.14/integrations-in-rancher/cloud-marketplace/aws-cloud-marketplace/install-adapter.md new file mode 100644 index 00000000000..939522101ea --- /dev/null +++ b/versioned_docs/version-2.14/integrations-in-rancher/cloud-marketplace/aws-cloud-marketplace/install-adapter.md @@ -0,0 +1,156 @@ +--- +title: Installing the Adapter +--- + + + + + +> **Important:** If you are attempting to re-install the adapter, you may experience errant out-of-compliance messages for up to an hour. + +### Rancher vs. Adapter Compatibility Matrix + +:::note Important: + +Different versions of the CSP adapter rely on features found in specific versions of Rancher. +In order to deploy and run the adapter successfully, you need to ensure its version corresponds to the necessary version of Rancher. + +::: + +| Rancher Version | Adapter Version | +|-----------------|------------------| +| v2.13.3 | 108.0.0+up8.0.0 | +| v2.13.2 | 108.0.0+up8.0.0 | +| v2.13.1 | 108.0.0+up8.0.0 | +| v2.13.0 | 108.0.0+up8.0.0 | + +### 1. Gain Access to the Local Cluster + +> **Note:** Only admin users should have access to the local cluster. Because the CSP adapter must be installed in the local cluster, this installation must be carried out by an admin user. + +First, click on the local cluster and download a kubeconfig token. You can then configure your CLI to use this new token with the following command, replacing `$TOKEN_PATH` with the path on your filesystem to the downloaded token: + +```bash +export KUBECONFIG=$TOKEN_PATH +``` + +### 2. Create the Adapter Namespace + +Create the namespace that the adapter will be installed in. + +```bash +kubectl create ns cattle-csp-adapter-system +``` + +### 3. Create Certificate Secrets + +The adapter requires access to the root CA that Rancher is using to communicate with the Rancher server. You can read more about which certificate options Rancher supports in the [chart options page](../../../getting-started/installation-and-upgrade/installation-references/helm-chart-options.md). + +If your Rancher install uses a certificate signed by a recognized Certificate Authority such as Let's Encrypt, then you can safely skip to [Step 4](#4-install-the-chart). + +However, if your Rancher install uses a custom certificate such as a Rancher-generated certificate or one signed by a private Certificate Authority, you will need to provide the certificate for this authority in PEM-encoded format so that the adapter can communicate with Rancher. + +First, retrieve the certificate that Rancher is using and place in a file named `ca-additional.pem`. If you are using the Rancher-generated certs option, this can be done with the following command: + +```bash +kubectl get secret tls-rancher -n cattle-system -o jsonpath="{.data.tls\.crt}" | base64 -d >> ca-additional.pem +``` + +Then, create a secret which uses this cert: + +```bash +kubectl -n cattle-csp-adapter-system create secret generic tls-ca-additional --from-file=ca-additional.pem +``` + +> **Important:** Do not change the names of the file or of the created secret. Making changes to these values may result in errors when the adapter runs. + +### 4. Install the Chart + +First, add the `rancher/charts` repo using the following command: + +```bash +helm repo add rancher-charts https://charts.rancher.io +``` + +Next, install the CSP adapter. You must specify several values, including the account number, and the name of the role created in the prerequisites. + +Ensure that you use the version of the CSP adapter that matches the version of Rancher that you are running, as defined [above](#rancher-vs-adapter-compatibility-matrix). + +For the below instructions, replace `$MY_ACC_NUM` with your AWS account number and `$MY_ROLE_NAME` with the name of the role created in the prerequisites. In addition, replace `$CSP_ADAPTER_VERSION` with the version that matches your Rancher version in the [version matrix](#rancher-vs-adapter-compatibility-matrix). + +> **Note:** If you use shell variables, do not specify quotation marks. For example, MY_ACC_NUM=123456789012 will work, but MY_ACC_NUM="123456789012" will fail. + +> **Note:** Accounts using the AWS Marketplace listing for the EU and the UK will need to specify an additional `--set image.repository=rancher/rancher-csp-adapter-eu` option. To see if your account needs this option when installing the adapter, refer to the usage instructions of the marketplace listing. + + + + + ```bash + helm install rancher-csp-adapter rancher-charts/rancher-csp-adapter --namespace cattle-csp-adapter-system --set aws.enabled=true --set aws.roleName=$MY_ROLE_NAME --set-string aws.accountNumber=$MY_ACC_NUM --version $CSP_ADAPTER_VERSION + ``` + + + Alternatively, you can use a `values.yaml` and specify options like below: + + ```yaml + aws: + enabled: true + accountNumber: "$MY_ACC_NUM" + roleName: $MY_ROLE_NAME + ``` + + > **Note:** The account number needs to be specified in a string format, like the above, or the installation will fail. + + You can then install the adapter with the following command: + + ```bash + helm install rancher-csp-adapter rancher-charts/rancher-csp-adapter -f values.yaml --version $CSP_ADAPTER_VERSION + ``` + + + + + ```bash + helm install rancher-csp-adapter rancher-charts/rancher-csp-adapter --namespace cattle-csp-adapter-system --set aws.enabled=true --set aws.roleName=$MY_ROLE_NAME --set-string aws.accountNumber=$MY_ACC_NUM --set additionalTrustedCAs=true --version $CSP_ADAPTER_VERSION + ``` + + Alternatively, you can use a `values.yaml` and specify options the below: + + ```yaml + aws: + enabled: true + accountNumber: "$MY_ACC_NUM" + roleName: $MY_ROLE_NAME + additionalTrustedCAs: true + ``` + + > **Note:** The account number needs to be specified in a string format, like the above, or the installation will fail. + + You can then install the adapter with the following command: + + ```bash + helm install rancher-csp-adapter rancher-charts/rancher-csp-adapter -f values.yaml --version $CSP_ADAPTER_VERSION + ``` + + + + +### 5. Managing Certificate Updates + +If you had to create a secret storing a custom cert in [Step 3](#3-create-certificate-secrets), you will need to update this secret over time as the certificate is rotated. + +First, delete the original secret in the cattle-csp-adapter-system namespace, using the below command: + +```bash +kubectl delete secret tls-ca-additional -n cattle-csp-adapter-system +``` + +Then, follow the original installation steps in [Step 3](#3-create-certificate-secrets) to replace the content of the secret with the updated value. + +Finally, restart the rancher-csp-adapter deployment to ensure that the updated value is made available to the adapter: + +```bash +kubectl rollout restart deploy rancher-csp-adapter -n cattle-csp-adapter-system +``` + +> **Note:** Methods such as cert-manager's [trust operator](https://cert-manager.io/docs/projects/trust/) allow you to automate some of these tasks. Although these methods aren't officially supported, they can reduce how often you need to manually rotate certificates. diff --git a/versioned_docs/version-2.14/integrations-in-rancher/cloud-marketplace/aws-cloud-marketplace/uninstall-adapter.md b/versioned_docs/version-2.14/integrations-in-rancher/cloud-marketplace/aws-cloud-marketplace/uninstall-adapter.md new file mode 100644 index 00000000000..51e11fe0360 --- /dev/null +++ b/versioned_docs/version-2.14/integrations-in-rancher/cloud-marketplace/aws-cloud-marketplace/uninstall-adapter.md @@ -0,0 +1,25 @@ +--- +title: Uninstalling The Adapter +--- + + + + + +### 1. Uninstall the adapter chart using helm. + +```bash +helm uninstall rancher-csp-adapter -n cattle-csp-adapter-system +``` + +### 2. Remove the namespace created for the adapter. + +```bash +kubectl delete ns cattle-csp-adapter-system +``` + +### 3. (Optional) remove any outstanding user notifications. + +```bash +kubectl delete RancherUserNotification csp-compliance +``` diff --git a/versioned_docs/version-2.14/integrations-in-rancher/cloud-marketplace/cloud-marketplace.md b/versioned_docs/version-2.14/integrations-in-rancher/cloud-marketplace/cloud-marketplace.md new file mode 100644 index 00000000000..ab6234b156d --- /dev/null +++ b/versioned_docs/version-2.14/integrations-in-rancher/cloud-marketplace/cloud-marketplace.md @@ -0,0 +1,11 @@ +--- +title: Cloud Marketplace Integration +--- + + + + + +Rancher offers integration with cloud marketplaces to easily purchase support for installations hosted on certain cloud providers. In addition, this integration also provides the ability to generate a supportconfig bundle which can be provided to rancher support. + +This integration only supports AWS. diff --git a/versioned_docs/version-2.14/integrations-in-rancher/cloud-marketplace/supportconfig.md b/versioned_docs/version-2.14/integrations-in-rancher/cloud-marketplace/supportconfig.md new file mode 100644 index 00000000000..4dbda92bf19 --- /dev/null +++ b/versioned_docs/version-2.14/integrations-in-rancher/cloud-marketplace/supportconfig.md @@ -0,0 +1,57 @@ +--- +title: Supportconfig Bundle +--- + + + + + +After installing the CSP adapter, you will have the ability to generate a supportconfig bundle. This bundle is a tar file which can be used to quickly provide information to support. + +These bundles can be created through Rancher or through direct access to the cluster that Rancher is installed on. Note that accessing through Rancher is preferred. + +> **Note:** Only admin users can generate/download supportconfig bundles, regardless of method. + +## Accessing Through Rancher + +First, click on the hamburger menu. Then click the `Get Support` button. + +![Get Support](/img/support-help.png) + +In the next page, click on the `Generate Support Config` button. + +> **Note:** If the adapter is not installed, the option to generate the supportconfig bundle will not be present. You must install the CSP adapter to generate a supportconfig bundle. + +![Get Support](/img/generate-support-config.png) + +## Accessing Without Rancher + +First, generate a kubeconfig for the cluster that Rancher is installed on. + +> **Note:** If Rancher is down, you will not be able to use a kubeconfig token generated by Rancher to access the cluster. + +Configure your shell environment to use this kubeconfig token: + +```bash +export KUBECONFIG=$MY_KUBECONFIG_PATH +``` + +It is recommended to create a temporary working directory while running this command, like below: + +```bash +mkdir temp && cd temp +``` + +Then, retrieve the supportconfig bundle: + +```bash +mkdir rancher && kubectl get configmap csp-config -n cattle-csp-adapter-system -o=jsonpath='{.data.data}' >> rancher/config.json && tar -c -f supportconfig_rancher.tar rancher && rm -rf rancher +``` + +This will create a `supportconfig_rancher.tar` file in your current directory. + +Users who run these commands on Mac may experience issues due to incompatibilities between gnu-tar and bsd-tar. If support has issues reading a supportconfig that you produce, try using the below command after making gnu-tar accessible as `gtar` on your path: + +```bash +mkdir rancher && kubectl get configmap csp-config -n cattle-csp-adapter-system -o=jsonpath='{.data.data}' >> rancher/config.json && gtar -c -f supportconfig_rancher.tar rancher && rm -rf rancher +``` diff --git a/versioned_docs/version-2.14/integrations-in-rancher/cluster-api/cluster-api.md b/versioned_docs/version-2.14/integrations-in-rancher/cluster-api/cluster-api.md new file mode 100644 index 00000000000..d570c52539f --- /dev/null +++ b/versioned_docs/version-2.14/integrations-in-rancher/cluster-api/cluster-api.md @@ -0,0 +1,14 @@ +--- +title: Cluster API (CAPI) with Rancher Turtles +--- + + + + + +[Rancher Turtles](https://turtles.docs.rancher.com/) is a [Kubernetes Operator](https://kubernetes.io/docs/concepts/extend-kubernetes/operator/#operators-in-kubernetes) that manages the lifecycle of provisioned Kubernetes clusters, by providing integration between your Cluster API (CAPI) and Rancher. With Rancher Turtles, you can: + +- Import CAPI clusters into Rancher, by installing the Rancher Cluster Agent in CAPI provisioned clusters. +- Configure the [CAPI Operator](https://turtles.docs.rancher.com/turtles/stable/en/operator/chart.html#_cluster_api_operator_values). + +The [Overview](./overview.md) section outlines installation options, Rancher Turtles architecture, and a brief demo. For more details, see the [Rancher Turtles documentation](https://turtles.docs.rancher.com/). diff --git a/versioned_docs/version-2.14/integrations-in-rancher/cluster-api/overview.md b/versioned_docs/version-2.14/integrations-in-rancher/cluster-api/overview.md new file mode 100644 index 00000000000..e2e4a661ce0 --- /dev/null +++ b/versioned_docs/version-2.14/integrations-in-rancher/cluster-api/overview.md @@ -0,0 +1,260 @@ +--- +title: Overview +--- + + + + + +## Architecture Diagram + +Below is a visual representation of the key components of Rancher Turtles and their relationship to Rancher and the Rancher Cluster Agent. Understanding these components is essential for gaining insights into how Rancher leverages the CAPI operator for cluster management. + +![overview](/img/30000ft_view.png) + +## Security + +As defined by [Supply-chain Levels for Software Artifacts (SLSA)](https://slsa.dev/spec/v1.0/about), SLSA is a set of incrementally adoptable guidelines for supply chain security, established by industry consensus. The specification set by SLSA is useful for both software producers and consumers: producers can follow SLSA’s guidelines to make their software supply chain more secure, and consumers can use SLSA to make decisions about whether to trust a software package. + +Rancher Turtles meets [SLSA Level 3](https://slsa.dev/spec/v1.0/levels#build-l3) requirements as an appropriate hardened build platform, with consistent build processes, and provenance distribution. For more information, visit the [Rancher Turtles Security](https://turtles.docs.rancher.com/turtles/stable/en/security/slsa.html) document. + +## Prerequisites + +Before installing Rancher Turtles in your Rancher environment, you must disable Rancher's `embedded-cluster-api` functionality. This also includes cleaning up Rancher-specific webhooks that otherwise would conflict with CAPI ones. + +To simplify setting up Rancher for installing Rancher Turtles, the official Rancher Turtles Helm chart includes a `pre-install` hook that removes the following: + +- Disables the `embedded-cluster-api` feature in Rancher. +- Deletes the `mutating-webhook-configuration` and `validating-webhook-configuration` webhooks, as they are no longer needed. + +These webhooks can be removed through the Rancher UI as well: + +1. In the upper left corner, click **☰** > **Cluster Management**. +1. Select your local cluster. +1. In the left-hand navigation menu, select **More Resources** > **Admission**. +1. From the dropdown, select the Resource pages for `MutatingWebhookConfiguration` and `ValidatingWebhookConfiguration`. +1. On the respective Resource pages, click the **⋮** that are attached to the `mutating-webhook-configuration` and `validating-webhook-configuration` webhooks and select the **Delete** option. + +The webhooks can also be accessed by entering the names of the webhooks into the **Resource Search** field. + +The following `kubectl` commands can manually remove the necessary webhooks: + +```console +kubectl delete mutatingwebhookconfiguration.admissionregistration.k8s.io mutating-webhook-configuration +``` + +```console +kubectl delete validatingwebhookconfigurations.admissionregistration.k8s.io validating-webhook-configuration +``` + +Use the following example to disable the `embedded-cluster-api` feature from the console: + +1. Create a `feature.yaml` file, with `embedded-cluster-api` set to false: + +```yaml title="feature.yaml" +apiVersion: management.cattle.io/v3 +kind: Feature +metadata: + name: embedded-cluster-api +spec: + value: false +``` + +2. Use `kubectl` to apply the `feature.yaml` file to the cluster: + +```bash +kubectl apply -f feature.yaml +``` + +## Installing the Rancher Turtles Operator + +You can install the Rancher Turtles operator via the Rancher UI, or with Helm. The first method is recommended for most environments. + +:::caution + +If you already have the Cluster API (CAPI) Operator installed in your cluster, you must use the [manual Helm installation method](#installing-via-helm). + +::: + +### Installing via the Rancher UI + +By adding the Turtles repository via the Rancher UI, Rancher can process the installation and configuration of the CAPI Extension. + +1. Click **☰**. Under **Explore Cluster** in the left navigation menu, select **local**. +1. In the left navigation menu of the **Cluster Dashboard**, select **Apps > Repositories**. +1. Click **Create** to add a new repository. +1. Enter the following: + - **Name**: turtles + - **Index URL**: https://rancher.github.io/turtles +1. Wait until the new repository has a status of `Active`. +1. In the left navigation menu, select **Apps > Charts**. +1. Enter "turtles" into the search filter to find the Turtles chart. +1. Click **Rancher Turtles - the Cluster API Extension**. +1. Click **Install > Next > Install**. + +This process uses the default values for the Helm chart, which are good for most installations. If your configuration requires overriding some of these defaults, you can either specify the values during installation from the Rancher UI or you can [manually install the chart via Helm](#installing-via-helm). For details about available values, see the Rancher Turtles [Helm chart reference guide](https://turtles.docs.rancher.com/turtles/stable/en/operator/chart.html). + +The installation may take a few minutes and after completing you can see the following new deployments in the cluster: + +- `rancher-turtles-system/rancher-turtles-controller-manager` +- `rancher-turtles-system/rancher-turtles-cluster-api-operator` +- `capi-system/capi-controller-manager` + +#### Demo + +This demo illustrates how to use the Rancher UI to install Rancher Turtles, create/import a CAPI cluster, and install monitoring on the cluster: + + + +### Installing via Helm + +There are two ways to install Rancher Turtles with Helm, depending on whether you include the [CAPI Operator](https://github.com/kubernetes-sigs/cluster-api-operator) as a dependency: + +- [Install Rancher Turtles with CAPI Operator as a dependency](#installing-rancher-turtles-with-cluster-api-capi-operator-as-a-helm-dependency). +- [Install Rancher Turtles without CAPI Operator](#installing-rancher-turtles-without-cluster-api-capi-operator-as-a-helm-dependency). + +The CAPI Operator is required for installing Rancher Turtles. You can choose whether you want to take care of this dependency yourself or let the Rancher Turtles Helm chart manage it for you. [Installing Turtles as a dependency](#installing-rancher-turtles-with-cluster-api-capi-operator-as-a-helm-dependency) is simpler, but your best option depends on your specific configuration. + +The CAPI Operator allows for handling the lifecycle of [CAPI providers](https://turtles.docs.rancher.com/turtles/stable/en/operator/manual.html) using a declarative approach, extending the capabilities of `clusterctl`. If you want to learn more about it, you can refer to [Cluster API Operator book](https://cluster-api-operator.sigs.k8s.io/). + +#### Installing Rancher Turtles with `Cluster API (CAPI) Operator` as a Helm dependency + +1. Add the Helm repository containing the `rancher-turtles` chart as the first step in installation: + +```bash +helm repo add turtles https://rancher.github.io/turtles +helm repo update +``` + +2. As mentioned before, installing Rancher Turtles requires the [CAPI Operator](https://github.com/kubernetes-sigs/cluster-api-operator). The Helm chart can automatically install it with a minimal set of flags: + +```bash +helm install rancher-turtles turtles/rancher-turtles --version \ + -n rancher-turtles-system \ + --dependency-update \ + --create-namespace --wait \ + --timeout 180s +``` + +3. This operation could take a few minutes and after completing you can review the installed controllers listed below: + +- `rancher-turtles-controller` +- `capi-operator` + +:::note + +- If `cert-manager` is already available in the cluster, disable its installation as a Rancher Turtles dependency. This prevents dependency conflicts: +`--set cluster-api-operator.cert-manager.enabled=false` +- For a list of Rancher Turtles versions, refer to the [Turtles release page](https://github.com/rancher/turtles/releases). + +::: + +This is the basic, recommended configuration, which manages the creation of a secret containing the required CAPI feature flags (`CLUSTER_TOPOLOGY`, `EXP_CLUSTER_RESOURCE_SET` and `EXP_MACHINE_POOL` enabled) in the core provider namespace. These feature flags are required to enable additional CAPI functionality. + +If you need to override the default behavior and use an existing secret (or add custom environment variables), you can pass the secret name Helm flag. In this case, as a user, you are in charge of managing the secret creation and its content, including enabling the minimum required features: `CLUSTER_TOPOLOGY`, `EXP_CLUSTER_RESOURCE_SET` and `EXP_MACHINE_POOL`. + +```bash +helm install ... + # Passing secret name and namespace for additional environment variables + --set cluster-api-operator.cluster-api.configSecret.name= +``` + +The following is an example of a user-managed secret `cluster-api-operator.cluster-api.configSecret.name=variables` with `CLUSTER_TOPOLOGY`, `EXP_CLUSTER_RESOURCE_SET` and `EXP_MACHINE_POOL` feature flags set and an extra custom variable: + +```yaml title="secret.yaml" +apiVersion: v1 +kind: Secret +metadata: + name: variables + namespace: rancher-turtles-system +type: Opaque +stringData: + CLUSTER_TOPOLOGY: "true" + EXP_CLUSTER_RESOURCE_SET: "true" + EXP_MACHINE_POOL: "true" + CUSTOM_ENV_VAR: "false" +``` + +:::info + +For detailed information on the values supported by the chart and their usage, refer to [Helm chart options](https://turtles.docs.rancher.com/turtles/stable/en/operator/chart.html). + +::: + +#### Installing Rancher Turtles without `Cluster API (CAPI) Operator` as a Helm dependency + +:::note + +Remember that if you opt for this installation option, you must manage the CAPI Operator installation yourself. You can follow the [manual installation guide](https://turtles.docs.rancher.com/turtles/stable/en/operator/manual.html) in the Rancher Turtles documentation for assistance. + +::: + +1. Add the Helm repository containing the `rancher-turtles` chart as the first step in installation: + +```bash +helm repo add turtles https://rancher.github.io/turtles +helm repo update +``` + +2. Install the chart into the `rancher-turtles-system` namespace: + +```bash +helm install rancher-turtles turtles/rancher-turtles --version + -n rancher-turtles-system + --set cluster-api-operator.enabled=false + --set cluster-api-operator.cluster-api.enabled=false + --create-namespace --wait + --dependency-update +``` + +The previous commands tell Helm to ignore installing `cluster-api-operator` as a dependency. + +3. This operation could take a few minutes and after completing you can review the installed controller listed below: + +- `rancher-turtles-controller` + +## Uninstalling Rancher Turtles + +:::caution + +When installing Rancher Turtles in your Rancher environment, by default, Rancher Turtles enables the CAPI Operator cleanup. This includes cleaning up CAPI Operator specific webhooks and deployments that otherwise cause issues with Rancher provisioning. + +To simplify uninstalling Rancher Turtles (via Rancher or Helm command), the official Rancher Turtles Helm chart includes a `post-delete` hook that removes the following: + +- Deletes the `mutating-webhook-configuration` and `validating-webhook-configuration` webhooks that are no longer needed. +- Deletes the CAPI `deployments` that are no longer needed. + +::: + +To uninstall Rancher Turtles: + +```bash +helm uninstall -n rancher-turtles-system rancher-turtles --cascade foreground --wait +``` + +This may take a few minutes to complete. + +:::note + +Remember that, if you use a different name for the installation or a different namespace, you may need to customize the command for your specific configuration. + +::: + +After Rancher Turtles is uninstalled, Rancher's `embedded-cluster-api` feature must be re-enabled: + +1. Create a `feature.yaml` file, with `embedded-cluster-api` set to true: + +```yaml title="feature.yaml" +apiVersion: management.cattle.io/v3 +kind: Feature +metadata: + name: embedded-cluster-api +spec: + value: true +``` + +2. Use `kubectl` to apply the `feature.yaml` file to the cluster: + +```bash +kubectl apply -f feature.yaml +``` diff --git a/versioned_docs/version-2.14/integrations-in-rancher/compliance-scans/compliance-scans.md b/versioned_docs/version-2.14/integrations-in-rancher/compliance-scans/compliance-scans.md new file mode 100644 index 00000000000..5ea2cfded41 --- /dev/null +++ b/versioned_docs/version-2.14/integrations-in-rancher/compliance-scans/compliance-scans.md @@ -0,0 +1,113 @@ +--- +title: Compliance Scans +--- + + + + + +Rancher can run a security scan to check whether a cluster is deployed according to security best practices as defined in Kubernetes security benchmarks, such as the ones provided by STIG, BSI or CIS. The Compliance scans can run on any Kubernetes cluster, including hosted Kubernetes providers such as EKS, AKS, and GKE. + +The `rancher-compliance` app leverages kube-bench, an open-source tool from Aqua Security, to check the compliance of clusters against Kubernetes Benchmarks. Also, to generate a cluster-wide report, the application utilizes Sonobuoy for report aggregation. + + +## About the CIS Benchmark + +The Center for Internet Security is a 501(c\)(3) non-profit organization, formed in October 2000, with a mission to "identify, develop, validate, promote, and sustain best practice solutions for cyber defense and build and lead communities to enable an environment of trust in cyberspace". The organization is headquartered in East Greenbush, New York, with members including large corporations, government agencies, and academic institutions. + +CIS Benchmarks are best practices for the secure configuration of a target system. CIS Benchmarks are developed through the generous volunteer efforts of subject matter experts, technology vendors, public and private community members, and the CIS Benchmark Development team. + +[Sign up](https://learn.cisecurity.org/benchmarks) at the CIS website to view the official Benchmark documents. + +## About the Generated Report + +Each scan generates a report can be viewed in the Rancher UI and can be downloaded in CSV format. + +By default, the CIS Benchmark v1.6 is used. + +The Benchmark version is included in the generated report. + +The Benchmark provides recommendations of two types: Automated and Manual. Recommendations marked as Manual in the Benchmark are not included in the generated report. + +Some tests are designated as "Not Applicable." These tests will not be run on any CIS scan because of the way that Rancher provisions RKE2/K3s clusters. For information on how test results can be audited, and why some tests are designated to be not applicable, refer to Rancher's [self-assessment guide](../../reference-guides/rancher-security/rancher-security.md#the-cis-benchmark-and-self-assessment) for the corresponding Kubernetes version. + +The report contains the following information: + +| Column in Report | Description | +|-------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `id` | The ID number of the CIS Benchmark. | +| `description` | The description of the CIS Benchmark test. | +| `remediation` | What needs to be fixed in order to pass the test. | +| `state` | Indicates if the test passed, failed, was skipped, or was not applicable. | +| `node_type` | The node role, which affects which tests are run on the node. Master tests are run on controlplane nodes, etcd tests are run on etcd nodes, and node tests are run on the worker nodes. | +| `audit` | This is the audit check that `kube-bench` runs for this test. | +| `audit_config` | Any configuration applicable to the audit script. | +| `test_info` | Test-related info as reported by `kube-bench`, if any. | +| `commands` | Test-related commands as reported by `kube-bench`, if any. | +| `config_commands` | Test-related configuration data as reported by `kube-bench`, if any. | +| `actual_value` | The test's actual value, present if reported by `kube-bench`. | +| `expected_result` | The test's expected result, present if reported by `kube-bench`. | + +Refer to [the table in the cluster hardening guide](../../reference-guides/rancher-security/rancher-security.md) for information on which versions of Kubernetes, the Benchmark, Rancher, and our cluster hardening guide correspond to each other. Also refer to the hardening guide for configuration files of CIS-compliant clusters and information on remediating failed tests. + +## Test Profiles + +The following profiles are available: + +- Generic CIS 1.6 +- Generic CIS 1.20 +- Generic CIS 1.23 +- RKE2 permissive 1.6 +- RKE2 hardened 1.6 +- RKE2 permissive 1.20 +- RKE2 hardened 1.20 +- RKE2 permissive 1.23 +- RKE2 hardened 1.23 +- K3s permissive 1.6 +- K3s hardened 1.6 +- K3s permissive 1.20 +- K3s hardened 1.20 +- K3s permissive 1.23 +- K3s hardened 1.23 +- AKS +- EKS +- GKE + +You also have the ability to customize a profile by saving a set of tests to skip. + +All profiles will have a set of not applicable tests that will be skipped during the CIS scan. These tests are not applicable based on how a RKE2/K3s cluster manages Kubernetes. + +There are two types of RKE2/K3s cluster scan profiles: + +- **Permissive:** This profile has a set of tests that have been will be skipped as these tests will fail on a default RKE2/K3s Kubernetes cluster. Besides the list of skipped tests, the profile will also not run the not applicable tests. +- **Hardened:** This profile will not skip any tests, except for the non-applicable tests. + +The EKS and GKE cluster scan profiles are based on CIS Benchmark versions that are specific to those types of clusters. + +In order to pass the "Hardened" profile, you will need to follow the steps on the [hardening guide](../../reference-guides/rancher-security/rancher-security.md#rancher-hardening-guide) and use the `cluster.yml` defined in the hardening guide to provision a hardened cluster. + +The default profile and the supported CIS benchmark version depends on the type of cluster that will be scanned: + +The `rancher-compliance` supports the CIS 1.9 Benchmark version. + +- For RKE2 Kubernetes clusters, the RKE2 Permissive 1.9 profile is the default. +- EKS and GKE have their own CIS Benchmarks published by `kube-bench`. The corresponding test profiles are used by default for those clusters. +- For cluster types other than RKE2, EKS and GKE, the Generic CIS 1.5 profile is used by default. + +## About Skipped and Not Applicable Tests + +For now, only user-defined skipped tests are marked as skipped in the generated report. + +Any skipped tests that are defined as being skipped by one of the default profiles are marked as not applicable. + +## Roles-based Access Control + +For information about permissions, refer to [this page](rbac-for-compliance-scans.md) + +## Configuration + +For more information about configuring the custom resources for the scans, profiles, and benchmark versions, refer to [this page](configuration-reference.md) + +## How-to Guides + +Please refer to the [Compliance Scan Guides](../../how-to-guides/advanced-user-guides/compliance-scan-guides/compliance-scan-guides.md) to learn how to run Compliance scans. diff --git a/versioned_docs/version-2.14/integrations-in-rancher/compliance-scans/configuration-reference.md b/versioned_docs/version-2.14/integrations-in-rancher/compliance-scans/configuration-reference.md new file mode 100644 index 00000000000..700b0d311e0 --- /dev/null +++ b/versioned_docs/version-2.14/integrations-in-rancher/compliance-scans/configuration-reference.md @@ -0,0 +1,113 @@ +--- +title: Configuration +--- + + + + + +This configuration reference is intended to help you manage the custom resources created by the `rancher-compliance` application. These resources are used for performing compliance scans on a cluster, skipping tests, setting the test profile that will be used during a scan, and other customization. + +To configure the custom resources, go to the **Cluster Dashboard** To configure the compliance scans, + +1. In the upper left corner, click **☰ > Cluster Management**. +1. On the **Clusters** page, go to the cluster where you want to configure compliance scans and click **Explore**. +1. In the left navigation bar, click **Compliance**. + +## Scans + +A scan is created to trigger a compliance scan on the cluster based on the defined profile. A report is created after the scan is completed. + +When configuring a scan, you need to define the name of the scan profile that will be used with the `scanProfileName` directive. + +An example ClusterScan custom resource is below: + +```yaml +apiVersion: compliance.cattle.io/v1 +kind: ClusterScan +metadata: + name: scan-smnr9 +spec: + scanProfileName: cis-1.10-profile +``` + +## Profiles + +A profile contains the configuration for the compliance scan, which includes the benchmark version to use and any specific tests to skip in that benchmark. + +:::caution + +By default, a few ClusterScanProfiles are installed as part of the `rancher-compliance` chart. If a user edits these default benchmarks or profiles, the next chart update will reset them back. So it is advisable for users to not edit the default ClusterScanProfiles. + +::: + +Users can clone the ClusterScanProfiles to create custom profiles. + +Skipped tests are listed under the `skipTests` directive. + +When you create a new profile, you will also need to give it a name. + +An example `ClusterScanProfile` is below: + +```yaml +apiVersion: compliance.cattle.io/v1 +kind: ClusterScanProfile +metadata: + annotations: + clusterscanprofile.compliance.cattle.io/builtin: 'true' + meta.helm.sh/release-name: rancher-compliance + meta.helm.sh/release-namespace: compliance-operator-system + creationTimestamp: '2025-09-15T18:09:52Z' + generation: 1 + labels: + app.kubernetes.io/managed-by: Helm + name: cis-1.10-profile + resourceVersion: '93582' + uid: 0baad187-1157-46ac-982d-014338847c27 +spec: + benchmarkVersion: cis-1.10 + skipTests: + - '1.1.20' + - '1.1.21' +``` + +## Benchmark Versions + +A benchmark version is the name of benchmark to run using `kube-bench`, as well as the valid configuration parameters for that benchmark. + +A `ClusterScanBenchmark` defines the Compliance `BenchmarkVersion` name and test configurations. The `BenchmarkVersion` name is a parameter provided to the `kube-bench` tool. + +By default, a few `BenchmarkVersion` names and test configurations are packaged as part of the Compliance scan application. When this feature is enabled, these default BenchmarkVersions will be automatically installed and available for users to create a ClusterScanProfile. + +:::caution + +If the default BenchmarkVersions are edited, the next chart update will reset them back. Therefore we don't recommend editing the default ClusterScanBenchmarks. + +::: + +A ClusterScanBenchmark consists of the fields: + +- `ClusterProvider`: This is the cluster provider name for which this benchmark is applicable. For example: RKE2, EKS, GKE, etc. Leave it empty if this benchmark can be run on any cluster type. +- `MinKubernetesVersion`: Specifies the cluster's minimum kubernetes version necessary to run this benchmark. Leave it empty if there is no dependency on a particular Kubernetes version. +- `MaxKubernetesVersion`: Specifies the cluster's maximum Kubernetes version necessary to run this benchmark. Leave it empty if there is no dependency on a particular k8s version. + +An example `ClusterScanBenchmark` is below: + +```yaml +apiVersion: compliance.cattle.io/v1 +kind: ClusterScanBenchmark +metadata: + annotations: + meta.helm.sh/release-name: rancher-compliance + meta.helm.sh/release-namespace: compliance-operator-system + creationTimestamp: '2025-09-15T18:09:52Z' + generation: 1 + labels: + app.kubernetes.io/managed-by: Helm + name: cis-1.10 + resourceVersion: '93569' + uid: 309e543e-9102-4091-be91-08d7af7fb7a7 +spec: + clusterProvider: '' + minKubernetesVersion: 1.28.0 +``` diff --git a/versioned_docs/version-2.14/integrations-in-rancher/compliance-scans/custom-benchmark.md b/versioned_docs/version-2.14/integrations-in-rancher/compliance-scans/custom-benchmark.md new file mode 100644 index 00000000000..fc4bf0e3b4b --- /dev/null +++ b/versioned_docs/version-2.14/integrations-in-rancher/compliance-scans/custom-benchmark.md @@ -0,0 +1,83 @@ +--- +title: Creating a Custom Benchmark Version for Running a Cluster Scan +--- + + + + + +Each Benchmark Version defines a set of test configuration files that define the Compliance tests to be run by the kube-bench tool. +The `rancher-compliance` application installs a few default Benchmark Versions which are listed under Compliance application menu. + + +But in the following cases, a custom configuration or remediation may be required: + +- Non-standard file locations: When Kubernetes binaries, configuration or certificate paths deviate from upstream benchmark defaults. +Example: Unlike traditional Kubernetes, K3s bundles control plane components into a single binary. Therefore,` --anonymous-auth` flag presence and configuration should be verified in K3s' logs (`journalctl`), not via `kube-apiserver` process checks (`ps`). + +- Alternative risk mitigations: If a setup doesn't meet a check but has an equally effective compensating control with justification. Or simply is not concerned by the check requirement because of its design. +Example: By default, K3s embeds the api server within the k3s process. There is no API server pod specification file, so verifying the latter's file permissions is not required. + +## 1. Prepare the Custom Benchmark Version ConfigMap + +To create a custom benchmark version, first you need to create a ConfigMap containing the benchmark version's config files and upload it to your Kubernetes cluster where you want to run the scan. + +To prepare a custom benchmark version ConfigMap, suppose we want to add a custom Benchmark Version named `foo`. + +1. Create a directory named `foo` and inside this directory, place all the config YAML files that the kube-bench tool looks for. For example, here are the config YAML files for a Generic CIS 1.5 Benchmark Version https://github.com/aquasecurity/kube-bench/tree/master/cfg/cis-1.5 +1. Place the complete `config.yaml` file, which includes all the components that should be tested. +1. Add the Benchmark version name to the `target_mapping` section of the `config.yaml`: + + ```yaml + target_mapping: + "foo": + - "master" + - "node" + - "controlplane" + - "etcd" + - "policies" + ``` +1. Upload this directory to your Kubernetes Cluster by creating a ConfigMap: + + ```yaml + kubectl create configmap -n foo --from-file= + ``` + +## 2. Add a Custom Benchmark Version to a Cluster + +1. In the upper left corner, click **☰ > Cluster Management**. +1. On the **Clusters** page, go to the cluster where you want to add a custom benchmark and click **Explore**. +1. In the left navigation bar, click **Compliance > Benchmark Version**. +1. Click **Create**. +1. Enter the **Name** and a description for your custom benchmark version. +1. Choose the cluster provider that your benchmark version applies to. +1. Choose the ConfigMap you have uploaded from the dropdown. +1. Add the minimum and maximum Kubernetes version limits applicable, if any. +1. Click **Create**. + +## 3. Create a New Profile for the Custom Benchmark Version + +To run a scan using your custom benchmark version, you need to add a new Profile pointing to this benchmark version. + +1. In the upper left corner, click **☰ > Cluster Management**. +1. On the **Clusters** page, go to the cluster where you want to add a custom benchmark and click **Explore**. +1. In the left navigation bar, click **Compliance > Profile**. +1. Click **Create**. +1. Provide a **Name** and description. In this example, we name it `foo-profile`. +1. Choose the Benchmark Version from the dropdown. +1. Click **Create**. + +## 4. Run a Scan Using the Custom Benchmark Version + +Once the Profile pointing to your custom benchmark version `foo` has been created, you can create a new Scan to run the custom test configs in the Benchmark Version. + +To run a scan, + +1. In the upper left corner, click **☰ > Cluster Management**. +1. On the **Clusters** page, go to the cluster where you want to add a custom benchmark and click **Explore**. +1. In the left navigation bar, click **Compliance > Scan**. +1. Click **Create**. +1. Choose the new cluster scan profile. +1. Click **Create**. + +**Result:** A report is generated with the scan results. To see the results, click the name of the scan that appears. diff --git a/versioned_docs/version-2.14/integrations-in-rancher/compliance-scans/rbac-for-compliance-scans.md b/versioned_docs/version-2.14/integrations-in-rancher/compliance-scans/rbac-for-compliance-scans.md new file mode 100644 index 00000000000..71348248436 --- /dev/null +++ b/versioned_docs/version-2.14/integrations-in-rancher/compliance-scans/rbac-for-compliance-scans.md @@ -0,0 +1,48 @@ +--- +title: Roles-based Access Control +--- + + + + + +This section describes the permissions required to use the rancher-compliance App. + +The rancher-compliance is a cluster-admin only feature by default. + +However, the `rancher-compliance` chart installs these two default `ClusterRoles`: + +- compliance-admin +- compliance-view + +In Rancher, only cluster owners and global administrators have `compliance-admin` access by default. + +## Cluster-Admin Access + +Rancher Compliance Scans is a cluster-admin only feature by default. +This means only the Rancher global admins, and the cluster’s cluster-owner can: + +- Install/Uninstall the rancher-compliance App +- See the navigation links for Compliance CRDs - ClusterScanBenchmarks, ClusterScanProfiles, ClusterScans +- List the default ClusterScanBenchmarks and ClusterScanProfiles +- Create/Edit/Delete new ClusterScanProfiles +- Create/Edit/Delete a new ClusterScan to run the Compliance scan on the cluster +- View and Download the ClusterScanReport created after the ClusterScan is complete + + +## Summary of Default Permissions for Kubernetes Default Roles + +The rancher-compliance creates three `ClusterRoles` and adds the Compliance CRD access to the following default K8s `ClusterRoles`: + +| ClusterRole created by chart | Default K8s ClusterRole | Permissions given with Role +| ------------------------------| ---------------------------| ---------------------------| +| `compliance-admin` | `admin`| Ability to CRUD clusterscanbenchmarks, clusterscanprofiles, clusterscans, clusterscanreports CR +| `compliance-view` | `view `| Ability to List(R) clusterscanbenchmarks, clusterscanprofiles, clusterscans, clusterscanreports CR + + +By default only cluster-owner role will have ability to manage and use `rancher-compliance` feature. + +The other Rancher roles (cluster-member, project-owner, project-member) do not have any default permissions to manage and use rancher-compliance resources. + +But if a cluster-owner wants to delegate access to other users, they can do so by creating ClusterRoleBindings between these users and the above Compliance ClusterRoles manually. +There is no automatic role aggregation supported for the `rancher-compliance` ClusterRoles. diff --git a/versioned_docs/version-2.14/integrations-in-rancher/elemental/elemental.md b/versioned_docs/version-2.14/integrations-in-rancher/elemental/elemental.md new file mode 100644 index 00000000000..a408aa19a55 --- /dev/null +++ b/versioned_docs/version-2.14/integrations-in-rancher/elemental/elemental.md @@ -0,0 +1,31 @@ +--- +title: Operating System Management with Elemental +--- + + + + + +Elemental enables cloud-native host management. Elemental allows you to onboard any machine in any location, whether its in a datacenter or on the edge, and integrate them seamlessly into Kubernetes while managing your workflows (e.g., OS updates). + +## Elemental with Rancher + +Elemental in Rancher: + +- Is Kubernetes native, which allows you to manage the OS via Elemental in Kubernetes clusters. +- Is nondisruptive from a Kubernetes operational perspective. +- Is declarative and GitOps friendly. +- Allows OCI Image-based flows, which are trusted, deterministic, and predictable. +- Works at scale. It enables fleet-sized OS management. + +### When should I use Elemental? + +- Elemental enables cloud-native OS management from Rancher manager. It works with any OS (e.g., SLE Micro vanilla). +- Elemental allows cloud-native management for machines in datacenters and on the edge. +- Elemental is flexible and allows platform teams to perform all kind of workflows across their fleet of machines. + +## Elemental with Rancher Prime + +- Deeply integrated already as GUI Extension in Rancher. +- Extends the Rancher story to the OS. Working perfectly with SLE Micro for Rancher today. + \ No newline at end of file diff --git a/versioned_docs/version-2.14/integrations-in-rancher/fleet/architecture.md b/versioned_docs/version-2.14/integrations-in-rancher/fleet/architecture.md new file mode 100644 index 00000000000..556bd33f4e8 --- /dev/null +++ b/versioned_docs/version-2.14/integrations-in-rancher/fleet/architecture.md @@ -0,0 +1,12 @@ +--- +title: Fleet Architecture +--- + + + + + +Fleet can manage deployments from git of raw Kubernetes YAML, Helm charts, or Kustomize or any combination of the three. Regardless of the source, all resources are dynamically turned into Helm charts, and Helm is used as the engine to deploy everything in the cluster. This gives you a high degree of control, consistency, and auditability. Fleet focuses not only on the ability to scale, but to give one a high degree of control and visibility to exactly what is installed on the cluster. + +![Architecture](/img/fleet-architecture.svg) + diff --git a/versioned_docs/version-2.14/integrations-in-rancher/fleet/fleet.md b/versioned_docs/version-2.14/integrations-in-rancher/fleet/fleet.md new file mode 100644 index 00000000000..878ecd75d85 --- /dev/null +++ b/versioned_docs/version-2.14/integrations-in-rancher/fleet/fleet.md @@ -0,0 +1,27 @@ +--- +title: Continuous Delivery with Fleet +--- + + + + + +Fleet orchestrates and manages the continuous delivery of applications through the supply chain for fleets of clusters. Fleet organizes the supply chain to help teams deliver with confidence and trust in a timely manner using GitOps as a safe operating model. + +## Fleet with Rancher + +Many users often manage over 10 clusters at a time. Given the proliferation of clusters, continuous delivery is an important part of Rancher. Fleet ensures a reliable continuous delivery experience using GitOps, which is a safe and increasingly common operating model. + +### When should I use Fleet? + +- I need to deploy my monitoring stack (e.g., Grafana, Prometheus) across geographical regions, each with different retention policies. +- I am a platform operator and want to provision clusters with all components using a scalable and safe operating model (GitOps). +- I am an application developer and want my latest changes to automatically go into my development environment. + +## Fleet with Rancher Prime + +Fleet is already deeply integrated as the Continuous Delivery tool and GitOps Engine in Rancher. + + diff --git a/versioned_docs/version-2.14/integrations-in-rancher/fleet/overview.md b/versioned_docs/version-2.14/integrations-in-rancher/fleet/overview.md new file mode 100644 index 00000000000..efe2f2fd2f4 --- /dev/null +++ b/versioned_docs/version-2.14/integrations-in-rancher/fleet/overview.md @@ -0,0 +1,73 @@ +--- +title: Overview +--- + + + + + +## What is Continuous Delivery with Fleet? + +Continuous Delivery is Rancher's GitOps functionality, which is provided via integration with Fleet. + + - *Cluster engine*: Fleet is a container management and deployment engine designed to offer users more control on the local cluster and constant monitoring through GitOps. Fleet focuses not only on the ability to scale, but it also gives users a high degree of control and visibility to monitor exactly what is installed on the cluster. + + - *Deployment management*: Fleet can manage deployments from git of raw Kubernetes YAML, Helm charts, Kustomize, or any combination of the three. Regardless of the source, all resources are dynamically turned into Helm charts, and Helm is used as the engine to deploy all resources in the cluster. As a result, users can enjoy a high degree of control, consistency, and auditability of their clusters. + +## Architecture + +For information about how Fleet works, see the [Architecture](./architecture.md) page. + +## Accessing Fleet in the Rancher UI + +Fleet comes preinstalled in Rancher and is managed by the **Continuous Delivery** option in the Rancher UI. For additional information on Continuous Delivery and other Fleet troubleshooting tips, refer [here](https://fleet.rancher.io/troubleshooting). + +Users can leverage continuous delivery to deploy their applications to the Kubernetes clusters in the git repository without any manual operation by following **gitops** practice. + +Follow the steps below to access Continuous Delivery in the Rancher UI: + +1. Click **☰ > Continuous Delivery**. + +1. Select your namespace at the top of the menu, noting the following: + + - By default, **fleet-default** is selected which includes all downstream clusters that are registered through Rancher. + + - You may switch to **fleet-local**, which only contains the **local** cluster, or you may create your own workspace to which you may assign and move clusters. + + - You can then manage clusters by clicking on **Clusters** on the left navigation bar. + +1. Click on **Gitrepos** on the left navigation bar to deploy the gitrepo into your clusters in the current workspace. + +1. Select your [git repository](https://fleet.rancher.io/gitrepo-add) and [target clusters/cluster group](https://fleet.rancher.io/gitrepo-targets). You can also create the cluster group in the UI by clicking on **Cluster Groups** from the left navigation bar. + +1. Once the gitrepo is deployed, you can monitor the application through the Rancher UI. + +## Windows Support + +For details on support for clusters with Windows nodes, see the [Windows Support](./windows-support.md) page. + +## GitHub Repository + +The Fleet Helm charts are available [here](https://github.com/rancher/fleet/releases). + +## Using Fleet Behind a Proxy + +For details on using Fleet behind a proxy, see the [Using Fleet Behind a Proxy](./use-fleet-behind-a-proxy.md) page. + +## Helm Chart Dependencies + +In order for Helm charts with dependencies to deploy successfully, you must run a manual command (as listed below), as it is up to the user to fulfill the dependency list. If you do not do this and proceed to clone your repository and run `helm install`, your installation will fail because the dependencies will be missing. + +The Helm chart in the git repository must include its dependencies in the charts subdirectory. You must either manually run `helm dependencies update $chart` or run `helm dependencies build $chart` locally, then commit the complete charts directory to your git repository. Note that you will update your commands with the applicable parameters + +## Troubleshooting + +- **Known Issue**: clientSecretName and helmSecretName secrets for Fleet gitrepos are not included in the backup nor restore created by the [backup-restore-operator](../../how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/back-up-rancher.md#1-install-the-rancher-backup-operator). We will update the community once a permanent solution is in place. + +- **Temporary Workaround**: By default, user-defined secrets are not backed up in Fleet. It is necessary to recreate secrets if performing a disaster recovery restore or migration of Rancher into a fresh cluster. To modify resourceSet to include extra resources you want to backup, refer to docs [here](https://github.com/rancher/backup-restore-operator#user-flow). + +- **Debug logging**: To enable debug logging of Fleet components, create a new **fleet** entry in the existing **rancher-config** ConfigMap in the **cattle-system** namespace with the value `{"debug": 1, "debugLevel": 1}`. The Fleet application restarts after you save the ConfigMap. + +## Documentation + +See the [official Fleet documentation](https://fleet.rancher.io/) to learn more. diff --git a/versioned_docs/version-2.14/integrations-in-rancher/fleet/use-fleet-behind-a-proxy.md b/versioned_docs/version-2.14/integrations-in-rancher/fleet/use-fleet-behind-a-proxy.md new file mode 100644 index 00000000000..2075854a175 --- /dev/null +++ b/versioned_docs/version-2.14/integrations-in-rancher/fleet/use-fleet-behind-a-proxy.md @@ -0,0 +1,82 @@ +--- +title: Using Fleet Behind a Proxy +--- + + + + + +In this section, you'll learn how to enable Fleet in a setup that has a Rancher server with a public IP a Kubernetes cluster that has no public IP, but is configured to use a proxy. + +Rancher does not establish connections with registered downstream clusters. The Rancher agent deployed on the downstream cluster must be able to establish the connection with Rancher. + +To set up Fleet to work behind a proxy, you will need to set the **Agent Environment Variables** for the downstream cluster. These are cluster-level configuration options. + +Through the Rancher UI, you can configure these environment variables for any cluster type, including registered and custom clusters. The variables can be added while editing an existing cluster or while provisioning a new cluster. + +For public downstream clusters, it is sufficient to [set the required environment variables in the Rancher UI.](#setting-environment-variables-in-the-rancher-ui) + +For private nodes or private clusters, the environment variables need to be set on the nodes themselves. Then the environment variables are configured from the Rancher UI, typically when provisioning a custom cluster or when registering the private cluster. For an example of how to set the environment variables on Ubuntu node in a K3s Kubernetes cluster, see [this section.](#setting-environment-variables-on-private-nodes) + +## Required Environment Variables + +When adding Fleet agent environment variables for the proxy, replace with your private proxy IP. + +:::caution + +The `NO_PROXY` environment variable is not standardized, and the accepted format of the value can differ between applications. When configuring the `NO_PROXY` variable in Rancher, the value must adhere to the format expected by Golang. + +Specifically, the value should be a comma-delimited string which only contains IP addresses, CIDR notation, domain names, or special DNS labels (e.g. `*`). For a full description of the expected value format, refer to the [**upstream Golang documentation**](https://pkg.go.dev/golang.org/x/net/http/httpproxy#Config) + +::: + +| Variable Name | Value | +|------------------|--------| +| `HTTP_PROXY` | http://:8888 | +| `HTTPS_PROXY` | http://:8888 +| `NO_PROXY` | 127.0.0.0/8,10.0.0.0/8,172.16.0.0/12,192.168.0.0/16,.svc,.cluster.local | + +## Setting Environment Variables in the Rancher UI + +To add the environment variable to an existing cluster: + + + + +1. Click **☰ > Cluster Management**. +1. Go to the cluster where you want to add environment variables and click **⋮ > Edit Config**. +1. Click **Agent Environment Vars** under **Cluster configuration**. +1. Click **Add**. +1. Enter the [required environment variables](#required-environment-variables) +1. Click **Save**. + + + + +1. Click **☰ > Cluster Management**. +1. Go to the cluster where you want to add environment variables and click **⋮ > Edit Config**. +1. Click **Advanced Options**. +1. Click **Add Environment Variable**. +1. Enter the [required environment variables](#required-environment-variables) +1. Click **Save**. + + + + +**Result:** The Fleet agent works behind a proxy. + +## Setting Environment Variables on Private Nodes + +For private nodes and private clusters, the proxy environment variables need to be set on the nodes themselves, as well as configured from the Rancher UI. + +This example shows how the environment variables would be set up on an Ubuntu node in a K3s Kubernetes cluster: + +``` +ssh -o ForwardAgent=yes ubuntu@ +ssh +export proxy_private_ip= +export HTTP_PROXY=http://${proxy_private_ip}:8888 +export HTTPS_PROXY=http://${proxy_private_ip}:8888 +export NO_PROXY=127.0.0.0/8,10.0.0.0/8,172.16.0.0/12,192.168.0.0/16,.svc,.cluster.local +export KUBECONFIG=/etc/rancher/k3s/k3s.yaml +``` diff --git a/versioned_docs/version-2.14/integrations-in-rancher/fleet/windows-support.md b/versioned_docs/version-2.14/integrations-in-rancher/fleet/windows-support.md new file mode 100644 index 00000000000..15fd1ac2263 --- /dev/null +++ b/versioned_docs/version-2.14/integrations-in-rancher/fleet/windows-support.md @@ -0,0 +1,25 @@ +--- +title: Windows Support +--- + + + + + +Prior to Rancher v2.5.6, the `agent` did not have native Windows manifests on downstream clusters with Windows nodes. This would result in a failing `agent` pod for the cluster. + +If you are upgrading from an older version of Rancher to v2.5.6+, you can deploy a working `agent` with the following workflow *in the downstream cluster*: + +1. Cordon all Windows nodes. +1. Apply the below toleration to the `agent` workload. +1. Uncordon all Windows nodes. +1. Delete all `agent` pods. New pods should be created with the new toleration. +1. Once the `agent` pods are running, and auto-update is enabled for Fleet, they should be updated to a Windows-compatible `agent` version. + +```yaml +tolerations: +- effect: NoSchedule + key: cattle.io/os + operator: Equal + value: linux +``` \ No newline at end of file diff --git a/versioned_docs/version-2.14/integrations-in-rancher/harvester/harvester.md b/versioned_docs/version-2.14/integrations-in-rancher/harvester/harvester.md new file mode 100644 index 00000000000..f187fe086af --- /dev/null +++ b/versioned_docs/version-2.14/integrations-in-rancher/harvester/harvester.md @@ -0,0 +1,15 @@ +--- +title: Virtualization on Kubernetes with Harvester +--- + + + + + +## Harvester + +Introduced in Rancher v2.6.1, Harvester is an open-source hyper-converged infrastructure (HCI) software built on Kubernetes. Harvester installs on bare metal servers and provides integrated virtualization and distributed storage capabilities. Although Harvester operates using Kubernetes, it does not require knowledge of Kubernetes concepts, making it more user-friendly. + +## Harvester with Rancher + +With Rancher Prime and Harvester, IT operators now have access to an enterprise-ready, simple-to-use infrastructure platform that cohesively manages their virtual machines and Kubernetes clusters alongside one another. For more information on the support offering, see the [Support Matrix](https://www.suse.com/suse-harvester/support-matrix/all-supported-versions/harvester-v1-2-0/). With the Rancher Virtualization Management feature, users can import and manage multiple Harvester clusters. Leveraging the Rancher's authentication feature and RBAC control for multi-tenancy support. diff --git a/versioned_docs/version-2.14/integrations-in-rancher/harvester/overview.md b/versioned_docs/version-2.14/integrations-in-rancher/harvester/overview.md new file mode 100644 index 00000000000..ac94aa363b2 --- /dev/null +++ b/versioned_docs/version-2.14/integrations-in-rancher/harvester/overview.md @@ -0,0 +1,42 @@ +--- +title: Overview +--- + + + + + +Introduced in Rancher v2.6.1, [Harvester](https://docs.harvesterhci.io/) is an open-source hyper-converged infrastructure (HCI) software built on Kubernetes. Harvester installs on bare metal servers and provides integrated virtualization and distributed storage capabilities. Although Harvester operates using Kubernetes, it does not require users to know Kubernetes concepts, making it a more user-friendly application. + +## Feature Flag + +The Harvester feature flag is used to manage access to the Virtualization Management (VM) page in Rancher where users can navigate directly to Harvester clusters and access the Harvester UI. The Harvester feature flag is enabled by default. Click [here](../../how-to-guides/advanced-user-guides/enable-experimental-features/enable-experimental-features.md) for more information on feature flags in Rancher. + +To navigate to the Harvester cluster, click **☰ > Virtualization Management**. From Harvester Clusters page, click one of the clusters listed to go to the single Harvester cluster view. + +* If the Harvester feature flag is enabled, Harvester clusters will be filtered out from any pages or apps (such as Continuous Delivery with Fleet) that list Kubernetes clusters. + +* If the Harvester feature flag is disabled, and a Harvester cluster is imported, the Harvester cluster will be shown in the Rancher cluster list in the Cluster Management page. Harvester clusters will only be shown on the cluster list when the feature flag is off. + +* With the Harvester integration, Harvester clusters can now be imported into Rancher as a cluster type `Harvester`. + +* Users may import a Harvester cluster only on the Virtualization Management page. Importing a cluster on the Cluster Management page is not supported, and a warning will advise you to return to the VM page to do so. + +## Harvester Node Driver + +The [Harvester node driver](https://docs.harvesterhci.io/v1.5/rancher/node/node-driver/) is generally available for K3s and RKE2 options in Rancher. The node driver is available whether or not the Harvester feature flag is enabled. Note that the node driver is off by default. Users may create K3s or RKE2 clusters on Harvester only from the Cluster Management page. + +Harvester allows `.ISO` images to be uploaded and displayed through the Harvester UI, but this is not supported in the Rancher UI. This is because `.ISO` images usually require additional setup that interferes with a clean deployment (without requiring user intervention), and they are not typically used in cloud environments. + +See [Provisioning Drivers](../../how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/about-provisioning-drivers/about-provisioning-drivers.md#node-drivers) for more information on node drivers in Rancher. + +## Port Requirements + +The port requirements for the Harvester cluster can be found [here](https://docs.harvesterhci.io/v1.5/install/requirements#networking). + +In addition, other networking considerations are as follows: + +- Be sure to enable VLAN trunk ports of the physical switch for VM VLAN networks. +- Follow the networking setup guidance [here](https://docs.harvesterhci.io/v1.5/networking/index). + +For other port requirements for other guest clusters, such as K3s and RKE2, please see [these docs](https://docs.harvesterhci.io/v1.5/install/requirements/#guest-clusters). diff --git a/versioned_docs/version-2.14/integrations-in-rancher/integrations-in-rancher.md b/versioned_docs/version-2.14/integrations-in-rancher/integrations-in-rancher.md new file mode 100644 index 00000000000..afeba6da5e6 --- /dev/null +++ b/versioned_docs/version-2.14/integrations-in-rancher/integrations-in-rancher.md @@ -0,0 +1,18 @@ +--- +title: Integrations in Rancher +--- + + + + + +Prime is the Rancher ecosystem’s enterprise offering, with additional security, extended lifecycles, and access to Prime-exclusive documentation. Rancher Prime installation assets are hosted on a trusted SUSE registry, owned and managed by Rancher. The trusted Prime registry includes only stable releases that have been community-tested. + +Prime also offers options for production support, as well as add-ons to your subscription that tailor to your commercial needs. + +To learn more and get started with Rancher Prime, please visit [this page](https://www.rancher.com/quick-start). + +import DocCardList from '@theme/DocCardList'; +import { useCurrentSidebarCategory } from '@docusaurus/theme-common/internal'; + + diff --git a/versioned_docs/version-2.14/integrations-in-rancher/istio/configuration-options/configuration-options.md b/versioned_docs/version-2.14/integrations-in-rancher/istio/configuration-options/configuration-options.md new file mode 100644 index 00000000000..467f67d7b89 --- /dev/null +++ b/versioned_docs/version-2.14/integrations-in-rancher/istio/configuration-options/configuration-options.md @@ -0,0 +1,47 @@ +--- +title: Configuration Options +--- + + + + + +:::warning + +[Rancher-Istio](https://github.com/rancher/charts/tree/release-v2.11/charts/rancher-istio) will be deprecated in Rancher v2.12.0; turn to the [SUSE Rancher Application Collection](https://apps.rancher.io) build of Istio for enhanced security (included in SUSE Rancher Prime subscriptions). + +Detailed information can be found in [this announcement](https://forums.suse.com/t/deprecation-of-rancher-istio/45043). + +::: + +### Egress Support + +By default the Egress gateway is disabled, but can be enabled on install or upgrade through the values.yaml or via the [overlay file](#overlay-file). + +### Enabling Automatic Sidecar Injection + +Automatic sidecar injection is disabled by default. To enable this, set the `sidecarInjectorWebhook.enableNamespacesByDefault=true` in the values.yaml on install or upgrade. This automatically enables Istio sidecar injection into all new namespaces that are deployed. + +### Overlay File + +An Overlay File is designed to support extensive configuration of your Istio installation. It allows you to make changes to any values available in the [IstioOperator API](https://istio.io/latest/docs/reference/config/istio.operator.v1alpha1/). This will ensure you can customize the default installation to fit any scenario. + +The Overlay File will add configuration on top of the default installation that is provided from the Istio chart installation. This means you do not need to redefine the components that already defined for installation. + +For more information on Overlay Files, refer to the [Istio documentation.](https://istio.io/latest/docs/setup/install/istioctl/#configure-component-settings) + +### Selectors and Scrape Configs + +The Monitoring app sets `prometheus.prometheusSpec.ignoreNamespaceSelectors=false` which enables monitoring across all namespaces by default. This ensures you can view traffic, metrics and graphs for resources deployed in a namespace with `istio-injection=enabled` label. + +If you would like to limit Prometheus to specific namespaces, set `prometheus.prometheusSpec.ignoreNamespaceSelectors=true`. Once you do this, you must perform some additional configuration to continue to monitor your resources. + +For details, refer to [this section.](selectors-and-scrape-configurations.md) + +### Additional Steps for Installing Istio on an RKE2 Cluster + +Refer to [this section.](install-istio-on-rke2-cluster.md) + +### Additional Steps for Project Network Isolation + +Refer to [this section.](project-network-isolation.md) \ No newline at end of file diff --git a/versioned_docs/version-2.14/integrations-in-rancher/istio/configuration-options/install-istio-on-rke2-cluster.md b/versioned_docs/version-2.14/integrations-in-rancher/istio/configuration-options/install-istio-on-rke2-cluster.md new file mode 100644 index 00000000000..c2d5ac693d0 --- /dev/null +++ b/versioned_docs/version-2.14/integrations-in-rancher/istio/configuration-options/install-istio-on-rke2-cluster.md @@ -0,0 +1,72 @@ +--- +title: Additional Steps for Installing Istio on RKE2 and K3s Clusters +--- + + + + + +:::warning + +[Rancher-Istio](https://github.com/rancher/charts/tree/release-v2.11/charts/rancher-istio) will be deprecated in Rancher v2.12.0; turn to the [SUSE Rancher Application Collection](https://apps.rancher.io) build of Istio for enhanced security (included in SUSE Rancher Prime subscriptions). + +Detailed information can be found in [this announcement](https://forums.suse.com/t/deprecation-of-rancher-istio/45043). + +::: + +When installing or upgrading the Istio Helm chart through **Apps,** + +1. If you are installing the chart, click **Customize Helm options before install** and click **Next**. +1. You will see options for configuring the Istio Helm chart. On the **Components** tab, check the box next to **Enabled CNI**. +1. Add a custom overlay file specifying `cniBinDir` and `cniConfDir`. For more information on these options, refer to the [Istio documentation.](https://istio.io/latest/docs/setup/additional-setup/cni/#helm-chart-parameters) An example is below: + + + + +```yaml +apiVersion: install.istio.io/v1alpha1 +kind: IstioOperator +spec: + components: + cni: + enabled: true + k8s: + overlays: + - apiVersion: "apps/v1" + kind: "DaemonSet" + name: "istio-cni-node" + patches: + - path: spec.template.spec.containers.[name:install-cni].securityContext.privileged + value: true + values: + cni: + cniBinDir: /opt/cni/bin + cniConfDir: /etc/cni/net.d +``` + + + +```yaml +apiVersion: install.istio.io/v1alpha1 +kind: IstioOperator +spec: + components: + cni: + enabled: true + k8s: + overlays: + - apiVersion: "apps/v1" + kind: "DaemonSet" + name: "istio-cni-node" + patches: + - path: spec.template.spec.containers.[name:install-cni].securityContext.privileged + value: true + values: + cni: + cniBinDir: /var/lib/rancher/k3s/data/current/bin + cniConfDir: /var/lib/rancher/k3s/agent/etc/cni/net.d +``` + + + +**Result:** Now you should be able to utilize Istio as desired, including sidecar injection and monitoring via Kiali. diff --git a/versioned_docs/version-2.14/integrations-in-rancher/istio/configuration-options/project-network-isolation.md b/versioned_docs/version-2.14/integrations-in-rancher/istio/configuration-options/project-network-isolation.md new file mode 100644 index 00000000000..1663ed4610b --- /dev/null +++ b/versioned_docs/version-2.14/integrations-in-rancher/istio/configuration-options/project-network-isolation.md @@ -0,0 +1,33 @@ +--- +title: Additional Steps for Project Network Isolation +--- + + + + + +:::warning + +[Rancher-Istio](https://github.com/rancher/charts/tree/release-v2.11/charts/rancher-istio) has been deprecated since Rancher v2.12.0; turn to the [SUSE Rancher Application Collection](https://apps.rancher.io) build of Istio for enhanced security (included in SUSE Rancher Prime subscriptions). + +Detailed information can be found in [this announcement](https://forums.suse.com/t/deprecation-of-rancher-istio/45043). + +::: + +In clusters where: + +- You are using Rancher v2.5.8+ with an any RKE2 network plug-in that supports the enforcement of Kubernetes network policies, such as Canal +- The Project Network Isolation option is enabled +- You install the Istio Ingress module + +The Istio Ingress Gateway pod won't be able to redirect ingress traffic to the workloads by default. This is because all the namespaces will be inaccessible from the namespace where Istio is installed. You have two options. + +The first option is to add a new Network Policy in each of the namespaces where you intend to have ingress controlled by Istio. Your policy should include the following lines: + +``` +- podSelector: + matchLabels: + app: istio-ingressgateway +``` + +The second option is to move the `istio-system` namespace to the `system` project, which by default is excluded from the network isolation. \ No newline at end of file diff --git a/versioned_docs/version-2.14/integrations-in-rancher/istio/configuration-options/selectors-and-scrape-configurations.md b/versioned_docs/version-2.14/integrations-in-rancher/istio/configuration-options/selectors-and-scrape-configurations.md new file mode 100644 index 00000000000..babc665b31b --- /dev/null +++ b/versioned_docs/version-2.14/integrations-in-rancher/istio/configuration-options/selectors-and-scrape-configurations.md @@ -0,0 +1,132 @@ +--- +title: Selectors and Scrape Configs +--- + + + + + +:::warning + +[Rancher-Istio](https://github.com/rancher/charts/tree/release-v2.11/charts/rancher-istio) will be deprecated in Rancher v2.12.0; turn to the [SUSE Rancher Application Collection](https://apps.rancher.io) build of Istio for enhanced security (included in SUSE Rancher Prime subscriptions). + +Detailed information can be found in [this announcement](https://forums.suse.com/t/deprecation-of-rancher-istio/45043). + +::: + +The Monitoring app sets `prometheus.prometheusSpec.ignoreNamespaceSelectors=false`, which enables monitoring across all namespaces by default. + +This ensures you can view traffic, metrics and graphs for resources deployed in a namespace with `istio-injection=enabled` label. + +If you would like to limit Prometheus to specific namespaces, set `prometheus.prometheusSpec.ignoreNamespaceSelectors=true`. Once you do this, you must perform some additional configuration to continue to monitor your resources. + + +### Limiting Monitoring to Specific Namespaces by Setting ignoreNamespaceSelectors to True + +To limit monitoring to specific namespaces, you will edit the `ignoreNamespaceSelectors` Helm chart option. You will configure this option when installing or upgrading the Monitoring Helm chart: + +1. When installing or upgrading the Monitoring Helm chart, edit the values.yml and set`prometheus.prometheusSpec.ignoreNamespaceSelectors=true`. +1. Complete the install or upgrade. + +**Result:** Prometheus will be limited to specific namespaces which means one of the following configurations will need to be set up to continue to view data in various dashboards + +### Enabling Prometheus to Detect Resources in Other Namespaces + +There are two different ways to enable Prometheus to detect resources in other namespaces when `prometheus.prometheusSpec.ignoreNamespaceSelectors=true`: + +- **Monitoring specific namespaces:** Add a Service Monitor or Pod Monitor in the namespace with the targets you want to scrape. +- **Monitoring across namespaces:** Add an `additionalScrapeConfig` to your rancher-monitoring instance to scrape all targets in all namespaces. + +### Monitoring Specific Namespaces: Create a Service Monitor or Pod Monitor + +This option allows you to define which specific services or pods you would like monitored in a specific namespace. + +The usability tradeoff is that you have to create the service monitor or pod monitor per namespace since you cannot monitor across namespaces. + +:::note Prerequisite: + +Define a ServiceMonitor or PodMonitor for ``. An example ServiceMonitor is provided below. + +::: + +1. Click **☰ > Cluster Management**. +1. Go to the cluster that you created and click **Explore**. +1. In the top navigation bar, open the kubectl shell. +1. If the ServiceMonitor or PodMonitor file is stored locally in your cluster, in `kubectl create -f .yaml`. +1. If the ServiceMonitor or PodMonitor is not stored locally, run `cat<< EOF | kubectl apply -f -`, paste the file contents into the terminal, then run `EOF` to complete the command. +1. Run `kubectl label namespace istio-injection=enabled` to enable the envoy sidecar injection. + +**Result:** `` can be scraped by prometheus. + +
Example Service Monitor for Istio Proxies
+ +```yaml +apiVersion: monitoring.coreos.com/v1 +kind: ServiceMonitor +metadata: + name: envoy-stats-monitor + namespace: istio-system + labels: + monitoring: istio-proxies +spec: + selector: + matchExpressions: + - {key: istio-prometheus-ignore, operator: DoesNotExist} + namespaceSelector: + any: true + jobLabel: envoy-stats + endpoints: + - path: /stats/prometheus + targetPort: 15090 + interval: 15s + relabelings: + - sourceLabels: [__meta_kubernetes_pod_container_port_name] + action: keep + regex: '.*-envoy-prom' + - action: labeldrop + regex: "__meta_kubernetes_pod_label_(.+)" + - sourceLabels: [__meta_kubernetes_namespace] + action: replace + targetLabel: namespace + - sourceLabels: [__meta_kubernetes_pod_name] + action: replace + targetLabel: pod_name +``` + +### Monitoring across namespaces: Set ignoreNamespaceSelectors to False + +This enables monitoring across namespaces by giving Prometheus additional scrape configurations. + +The usability tradeoff is that all of Prometheus' `additionalScrapeConfigs` are maintained in a single Secret. This could make upgrading difficult if monitoring is already deployed with additionalScrapeConfigs before installing Istio. + +1. When installing or upgrading the Monitoring Helm chart, edit the values.yml and set the `prometheus.prometheusSpec.additionalScrapeConfigs` array to the **Additional Scrape Config** provided below. +1. Complete the install or upgrade. + +**Result:** All namespaces with the `istio-injection=enabled` label will be scraped by prometheus. + +
Additional Scrape Config
+ +``` yaml +- job_name: 'istio/envoy-stats' + scrape_interval: 15s + metrics_path: /stats/prometheus + kubernetes_sd_configs: + - role: pod + relabel_configs: + - source_labels: [__meta_kubernetes_pod_container_port_name] + action: keep + regex: '.*-envoy-prom' + - source_labels: [__address__, __meta_kubernetes_pod_annotation_prometheus_io_port] + action: replace + regex: ([^:]+)(?::\d+)?;(\d+) + replacement: $1:15090 + target_label: __address__ + - action: labelmap + regex: __meta_kubernetes_pod_label_(.+) + - source_labels: [__meta_kubernetes_namespace] + action: replace + target_label: namespace + - source_labels: [__meta_kubernetes_pod_name] + action: replace + target_label: pod_name +``` diff --git a/versioned_docs/version-2.14/integrations-in-rancher/istio/cpu-and-memory-allocations.md b/versioned_docs/version-2.14/integrations-in-rancher/istio/cpu-and-memory-allocations.md new file mode 100644 index 00000000000..c769311c5ed --- /dev/null +++ b/versioned_docs/version-2.14/integrations-in-rancher/istio/cpu-and-memory-allocations.md @@ -0,0 +1,75 @@ +--- +title: CPU and Memory Allocations +--- + + + + + +:::warning + +[Rancher-Istio](https://github.com/rancher/charts/tree/release-v2.11/charts/rancher-istio) will be deprecated in Rancher v2.12.0; turn to the [SUSE Rancher Application Collection](https://apps.rancher.io) build of Istio for enhanced security (included in SUSE Rancher Prime subscriptions). + +Detailed information can be found in [this announcement](https://forums.suse.com/t/deprecation-of-rancher-istio/45043). + +::: + +This section describes the minimum recommended computing resources for the Istio components in a cluster. + +The CPU and memory allocations for each component are [configurable.](#configuring-resource-allocations) + +Before enabling Istio, we recommend that you confirm that your Rancher worker nodes have enough CPU and memory to run all of the components of Istio. + +:::tip + +In larger deployments, it is strongly advised that the infrastructure be placed on dedicated nodes in the cluster by adding a node selector for each Istio component. + +::: + +The table below shows a summary of the minimum recommended resource requests and limits for the CPU and memory of each core Istio component. + +In Kubernetes, the resource request indicates that the workload will not deployed on a node unless the node has at least the specified amount of memory and CPU available. If the workload surpasses the limit for CPU or memory, it can be terminated or evicted from the node. For more information on managing resource limits for containers, refer to the [Kubernetes documentation.](https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container/) + +| Workload | CPU - Request | Memory - Request | CPU - Limit | Memory - Limit | +|----------------------|---------------|------------|-----------------|-------------------| +| ingress gateway | 100m | 128mi | 2000m | 1024mi | +| egress gateway | 100m | 128mi | 2000m | 1024mi | +| istiod | 500m | 2048mi | No limit | No limit | +| proxy | 10m | 10mi | 2000m | 1024mi | +| **Totals:** | **710m** | **2314Mi** | **6000m** | **3072Mi** | + +## Configuring Resource Allocations + +You can individually configure the resource allocation for each type of Istio component. This section includes the default resource allocations for each component. + +To make it easier to schedule the workloads to a node, a cluster-admin can reduce the CPU and memory resource requests for the component. However, the default CPU and memory allocations are the minimum that we recommend. + +You can find more information about Istio configuration in the [official Istio documentation](https://istio.io/). + +To configure the resources allocated to an Istio component, + +1. Click **☰ > Cluster Management**. +1. Go to the cluster that you created and click **Explore**. +1. In the left navigation bar, click **Apps**. +1. Click **Installed Apps**. +1. Go to the `istio-system` namespace. In one of the Istio workloads, such as `rancher-istio`, click **⋮ > Edit/Upgrade**. +1. Click **Upgrade** to edit the base components via changes to the values.yaml or add an [overlay file](configuration-options/configuration-options.md#overlay-file). For more information about editing the overlay file, see [this section.](#editing-the-overlay-file) +1. Change the CPU or memory allocations, the nodes where each component will be scheduled to, or the node tolerations. +1. Click **Upgrade**. to rollout changes + +**Result:** The resource allocations for the Istio components are updated. + +### Editing the Overlay File + +The overlay file can contain any of the values in the [Istio Operator spec.](https://istio.io/latest/docs/reference/config/istio.operator.v1alpha1/#IstioOperatorSpec) The overlay file included with the Istio application is just one example of a potential configuration of the overlay file. + +As long as the file contains `kind: IstioOperator` and the YAML options are valid, the file can be used as an overlay. + +In the example overlay file provided with the Istio application, the following section allows you to change Kubernetes resources: + +``` +# k8s: +# resources: +# requests: +# cpu: 200m +``` diff --git a/versioned_docs/version-2.14/integrations-in-rancher/istio/disable-istio.md b/versioned_docs/version-2.14/integrations-in-rancher/istio/disable-istio.md new file mode 100644 index 00000000000..ca647cca1ab --- /dev/null +++ b/versioned_docs/version-2.14/integrations-in-rancher/istio/disable-istio.md @@ -0,0 +1,54 @@ +--- +title: Disabling Istio +--- + + + + + +:::warning + +[Rancher-Istio](https://github.com/rancher/charts/tree/release-v2.11/charts/rancher-istio) will be deprecated in Rancher v2.12.0; turn to the [SUSE Rancher Application Collection](https://apps.rancher.io) build of Istio for enhanced security (included in SUSE Rancher Prime subscriptions). + +Detailed information can be found in [this announcement](https://forums.suse.com/t/deprecation-of-rancher-istio/45043). + +::: + +This section describes how to uninstall Istio in a cluster or disable a namespace, or workload. + +## Uninstall Istio in a Cluster + +To uninstall Istio, + +1. Click **☰ > Cluster Management**. +1. Go to the cluster that you created and click **Explore**. +1. In the left navigation bar, click **Apps > Installed Apps**. +1. In the `istio-system` namespace, go to `rancher-istio` and click **⋮ > Delete**. +1. After `rancher-istio` is deleted, you can then select all the remaining apps in the `istio-system` namespace and click **Delete**. + +**Result:** The `rancher-istio` app in the cluster gets removed. The Istio sidecar cannot be deployed on any workloads in the cluster. + +:::note + +You can no longer disable and re-enable your Istio installation. If you would like to save your settings for a future install, view and save individual YAMLs to refer back to / reuse for future installations. + +::: + +**Troubleshooting Uninstall:** If you didn't follow the uninstall steps, you may encounter a warning during uninstall: + +`Error: uninstallation completed with 1 error(s): unable to build kubernetes objects for delete: unable to recognize "": no matches for kind "MonitoringDashboard" in version "monitoring.kiali.io/v1alpha1"` + +This could mean a few things. You either selected all the apps in the `istio-system` namespace and deleted them at the same time, or you deleted `rancher-istio` chart dependencies prior to deleting the `rancher-istio` chart. Since the uninstall did not complete properly, you will have resources remaining in the `istio-system` namespace that you will need to manually clean up. Another option to avoid manual clean up is to install `rancher-istio` again, then uninstall it in the correct order. + +## Disable Istio in a Namespace + +1. Click **☰ > Cluster Management**. +1. Go to the cluster that you created and click **Explore**. +1. Click **Cluster > Projects/Namespaces**. +1. Go to the namespace where you want to enable Istio and click **⋮ > Enable Istio Auto Injection**. Alternately, click the namespace, and then on the namespace detail page, click **⋮ > Enable Istio Auto Injection**. + +**Result:** When workloads are deployed in this namespace, they will not have the Istio sidecar. + +## Remove the Istio Sidecar from a Workload + +Disable Istio in the namespace, then redeploy the workloads with in it. They will be deployed without the Istio sidecar. diff --git a/versioned_docs/version-2.14/integrations-in-rancher/istio/istio.md b/versioned_docs/version-2.14/integrations-in-rancher/istio/istio.md new file mode 100644 index 00000000000..ba08fb8505e --- /dev/null +++ b/versioned_docs/version-2.14/integrations-in-rancher/istio/istio.md @@ -0,0 +1,157 @@ +--- +title: Istio +--- + + + + + +:::warning + +[Rancher-Istio](https://github.com/rancher/charts/tree/release-v2.11/charts/rancher-istio) will be deprecated in Rancher v2.12.0; turn to the [SUSE Rancher Application Collection](https://apps.rancher.io) build of Istio for enhanced security (included in SUSE Rancher Prime subscriptions). + +Detailed information can be found in [this announcement](https://forums.suse.com/t/deprecation-of-rancher-istio/45043). + +::: + +[Istio](https://istio.io/) is an open-source tool that makes it easier for DevOps teams to observe, secure, control, and troubleshoot the traffic within a complex network of microservices. + +As a network of microservices changes and grows, the interactions between them can become increasingly difficult to manage and understand. In such a situation, it is useful to have a service mesh as a separate infrastructure layer. Istio's service mesh lets you manipulate traffic between microservices without changing the microservices directly. + +Our integration of Istio is designed so that a Rancher operator, such as an administrator or cluster owner, can deliver Istio to a team of developers. Then developers can use Istio to enforce security policies, troubleshoot problems, or manage traffic for green/blue deployments, canary deployments, or A/B testing. + +This core service mesh provides features that include but are not limited to the following: + +- **Traffic Management** such as ingress and egress routing, circuit breaking, mirroring. +- **Security** with resources to authenticate and authorize traffic and users, mTLS included. +- **Observability** of logs, metrics, and distributed traffic flows. + +After [setting up istio](../../how-to-guides/advanced-user-guides/istio-setup-guide/istio-setup-guide.md) you can leverage Istio's control plane functionality through the Rancher UI, `kubectl`, or `istioctl`. + +Istio needs to be set up by a `cluster-admin` before it can be used in a project. + + +## What's New in Rancher v2.5 + +The overall architecture of Istio has been simplified. A single component, Istiod, has been created by combining Pilot, Citadel, Galley and the sidecar injector. Node Agent functionality has also been merged into istio-agent. + +Addons that were previously installed by Istio (cert-manager, Grafana, Jaeger, Kiali, Prometheus, Zipkin) will now need to be installed separately. Istio will support installation of integrations that are from the Istio Project and will maintain compatibility with those that are not. + +A Prometheus integration will still be available through an installation of [Rancher Monitoring](../monitoring-and-alerting/monitoring-and-alerting.md), or by installing your own Prometheus operator. Rancher's Istio chart will also install Kiali by default to ensure you can get a full picture of your microservices out of the box. + +Istio has migrated away from Helm as a way to install Istio and now provides installation through the istioctl binary or Istio Operator. To ensure the easiest interaction with Istio, Rancher's Istio will maintain a Helm chart that utilizes the istioctl binary to manage your Istio installation. + +This Helm chart will be available via the Apps and Marketplace in the UI. A user that has access to the Rancher Chart's catalog will need to set up Istio before it can be used in the project. + +## Tools Bundled with Istio + +Our [Istio](https://istio.io/) installer wraps the istioctl binary commands in a handy Helm chart, including an overlay file option to allow complex customization. + +It also includes the following: + +### Kiali + +[Kiali](https://kiali.io/) is a comprehensive visualization aid used for graphing traffic flow throughout the service mesh. It allows you to see how they are connected, including the traffic rates and latencies between them. + +You can check the health of the service mesh, or drill down to see the incoming and outgoing requests to a single component. + +:::note +For Istio installations `103.1.0+up1.19.6` and later, Kiali uses a token value for its authentication strategy. The name of the Kiali service account in Rancher is `kiali`. Use this name if you are writing commands that require you to enter the name of the Kiali service account (for example, if you are trying to generate or retrieve a session token). For more information, refer to the [Kiali token authentication FAQ](https://kiali.io/docs/faq/authentication/). +::: + +### Jaeger + +Our Istio installer includes a quick-start, all-in-one installation of [Jaeger,](https://www.jaegertracing.io/) a tool used for tracing distributed systems. + +Note that this is not a production-qualified deployment of Jaeger. This deployment uses an in-memory storage component, while a persistent storage component is recommended for production. For more information on which deployment strategy you may need, refer to the [Jaeger documentation.](https://www.jaegertracing.io/docs/1.65/operator/#production-strategy) + +## Prerequisites + +Before enabling Istio, we recommend that you confirm that your Rancher worker nodes have enough [CPU and memory](cpu-and-memory-allocations.md) to run all of the components of Istio. + +If you are installing Istio on RKE2 cluster, some additional steps are required. For details, see [this section.](#additional-steps-for-installing-istio-on-an-rke2-cluster) + +## Setup Guide + +Refer to the [setup guide](../../how-to-guides/advanced-user-guides/istio-setup-guide/istio-setup-guide.md) for instructions on how to set up Istio and use it in a project. + +## Remove Istio + +To remove Istio components from a cluster, namespace, or workload, refer to the section on [uninstalling Istio.](disable-istio.md) + +## Accessing Visualizations + +> By default, only cluster-admins have access to Kiali. For instructions on how to allow admin, edit or views roles to access them, see [this section.](rbac-for-istio.md) + +:::note +For Istio installations version `103.1.0+up1.19.6` and later, Kiali uses a token value for its authentication strategy. The name of the Kiali service account in Rancher is `kiali`. Use this name if you are writing commands that require you to enter the name of the Kiali service account (for example, if you are trying to generate or retrieve a session token). For more information, refer to the [Kiali token authentication FAQ](https://kiali.io/docs/faq/authentication/). +::: + +After Istio is set up in a cluster, Grafana, Prometheus, and Kiali are available in the Rancher UI. + +To access the Grafana and Prometheus visualizations, + +1. In the upper left corner, click **☰ > Cluster Management**. +1. On the **Clusters** page, go to the cluster where you want to see the visualizations and click **Explore**. +1. In the left navigation bar, click **Monitoring**. +1. Click **Grafana** or any of the other dashboards. + +To access the Kiali visualization, + +1. In the upper left corner, click **☰ > Cluster Management**. +1. On the **Clusters** page, go to the cluster where you want to see Kiali and click **Explore**. +1. In the left navigation bar, click **Istio**. +1. Click **Kiali**. From here you can access the **Traffic Graph** tab or the **Traffic Metrics** tab to see network visualizations and metrics. + +By default, all namespace will picked up by prometheus and make data available for Kiali graphs. Refer to [selector/scrape config setup](configuration-options/selectors-and-scrape-configurations.md) if you would like to use a different configuration for prometheus data scraping. + +Your access to the visualizations depend on your role. Grafana and Prometheus are only available for `cluster-admin` roles. The Kiali UI is available only to `cluster-admin` by default, but `cluster-admin` can allow other roles to access them by editing the Istio values.yaml. + +## Architecture + +Istio installs a service mesh that uses [Envoy](https://www.envoyproxy.io) sidecar proxies to intercept traffic to each workload. These sidecars intercept and manage service-to-service communication, allowing fine-grained observation and control over traffic within the cluster. + +Only workloads that have the Istio sidecar injected can be tracked and controlled by Istio. + +When a namespace has Istio enabled, new workloads deployed in the namespace will automatically have the Istio sidecar. You need to manually enable Istio in preexisting workloads. + +For more information on the Istio sidecar, refer to the [Istio sidecare-injection docs](https://istio.io/docs/setup/kubernetes/additional-setup/sidecar-injection/) and for more information on Istio's architecture, refer to the [Istio Architecture docs](https://istio.io/latest/docs/ops/deployment/architecture/) + +### Multiple Ingresses + +By default, each Rancher-provisioned cluster has one NGINX ingress controller allowing traffic into the cluster. Istio also installs an ingress gateway by default into the `istio-system` namespace. The result is that your cluster will have two ingresses in your cluster. + +![In an Istio-enabled cluster, you can have two ingresses: the default Nginx ingress, and the default Istio controller.](/img/istio-ingress.svg) + + Additional Istio Ingress gateways can be enabled via the [overlay file](configuration-options/configuration-options.md#overlay-file). + +### Egress Support + +By default the Egress gateway is disabled, but can be enabled on install or upgrade through the values.yaml or via the [overlay file](configuration-options/configuration-options.md#overlay-file). + +## Additional Steps for Installing Istio on an RKE2 Cluster + +To install Istio on an RKE2 cluster, follow the steps in [this section.](configuration-options/install-istio-on-rke2-cluster.md) + +## Upgrading Istio in an Air-Gapped Environment + +The Istio pod security policy is now enabled by default. A new value, `installer.releaseMirror.enabled`, has been added to the rancher-istio chart to enable and disable the server that supports air-gapped upgrades. Note that `installer.releaseMirror.enabled` is set to `false` by default. You can set this value as needed when you install or upgrade. Follow the steps below: + +1. Provision an air-gapped Rancher instance and an air-gapped custom cluster in the Rancher UI. +2. Install Monitoring in the cluster: **Cluster Explorer -> Apps & Marketplace -> Charts -> Monitoring**. +3. Pull all required images for Istio into the private registry you will use in the air-gapped environment. +4. Install Istio in the cluster: **Cluster Explorer -> Apps & Marketplace -> Charts -> Istio**. + +:::note + +You can enable [Jaeger](https://www.jaegertracing.io/) and [Kiali](https://kiali.io/) on a fresh Istio install. To ensure that Jaeger and Kiali work, set `installer.releaseMirror.enabled` to `true` in `values.yaml` during installation. + +::: + +5. Upgrade the Istio installation. + +:::caution + +If you haven't already, set `installer.releaseMirror.enabled=true` to upgrade Istio. + +::: diff --git a/versioned_docs/version-2.14/integrations-in-rancher/istio/rbac-for-istio.md b/versioned_docs/version-2.14/integrations-in-rancher/istio/rbac-for-istio.md new file mode 100644 index 00000000000..ab8e5d4770e --- /dev/null +++ b/versioned_docs/version-2.14/integrations-in-rancher/istio/rbac-for-istio.md @@ -0,0 +1,55 @@ +--- +title: Role-based Access Control +--- + + + + + +:::warning + +[Rancher-Istio](https://github.com/rancher/charts/tree/release-v2.11/charts/rancher-istio) will be deprecated in Rancher v2.12.0; turn to the [SUSE Rancher Application Collection](https://apps.rancher.io) build of Istio for enhanced security (included in SUSE Rancher Prime subscriptions). + +Detailed information can be found in [this announcement](https://forums.suse.com/t/deprecation-of-rancher-istio/45043). + +::: + +This section describes the permissions required to access Istio features. + +The rancher istio chart installs three `ClusterRoles` + +## Cluster-Admin Access + +By default, only those with the `cluster-admin` `ClusterRole` can: + +- Install istio app in a cluster +- Configure resource allocations for Istio + + +## Admin and Edit access + +By default, only Admin and Edit roles can: + +- Enable and disable Istio sidecar auto-injection for namespaces +- Add the Istio sidecar to workloads +- View the traffic metrics and traffic graph for the cluster +- Configure Istio's resources (such as the gateway, destination rules, or virtual services) + +## Summary of Default Permissions for Kubernetes Default roles + +Istio creates three `ClusterRoles` and adds Istio CRD access to the following default K8s `ClusterRole`: + +ClusterRole create by chart | Default K8s ClusterRole | Rancher Role | + ------------------------------:| ---------------------------:|---------:| + `istio-admin` | admin| Project Owner | + `istio-edit`| edit | Project Member | + `istio-view` | view | Read-only | + +Rancher will continue to use cluster-owner, cluster-member, project-owner, project-member, etc as role names, but will utilize default roles to determine access. For each default K8s `ClusterRole` there are different Istio CRD permissions and K8s actions (Create ( C ), Get ( G ), List ( L ), Watch ( W ), Update ( U ), Patch ( P ), Delete( D ), All ( * )) that can be performed. + + +|CRDs | Admin | Edit | View +|----------------------------| ------| -----| ----- +|
  • `config.istio.io`
    • `adapters`
    • `attributemanifests`
    • `handlers`
    • `httpapispecbindings`
    • `httpapispecs`
    • `instances`
    • `quotaspecbindings`
    • `quotaspecs`
    • `rules`
    • `templates`
| GLW | GLW | GLW +|
  • `networking.istio.io`
    • `destinationrules`
    • `envoyfilters`
    • `gateways`
    • `serviceentries`
    • `sidecars`
    • `virtualservices`
    • `workloadentries`
| * | * | GLW +|
  • `security.istio.io`
    • `authorizationpolicies`
    • `peerauthentications`
    • `requestauthentications`
| * | * | GLW \ No newline at end of file diff --git a/versioned_docs/version-2.14/integrations-in-rancher/kubernetes-distributions/kubernetes-distributions.md b/versioned_docs/version-2.14/integrations-in-rancher/kubernetes-distributions/kubernetes-distributions.md new file mode 100644 index 00000000000..c36a1519f76 --- /dev/null +++ b/versioned_docs/version-2.14/integrations-in-rancher/kubernetes-distributions/kubernetes-distributions.md @@ -0,0 +1,35 @@ +--- +title: Kubernetes Distributions +--- + + + + + +## K3s + +K3s is a lightweight, fully compliant Kubernetes distribution designed for a range of use cases, including edge computing, IoT, CI/CD, development and embedding Kubernetes into applications. It simplifies Kubernetes management by packaging the system as a single binary, using sqlite3 as the default storage, and offering a user-friendly launcher. K3s includes essential features like local storage and load balancing, Helm chart controller and the Traefik CNI. It minimizes external dependencies and provides a streamlined Kubernetes experience. K3s was donated to the CNCF as a Sandbox Project in June 2020. + +### K3s with Rancher + +- Rancher allows easy provision of K3s across a range of platforms including Amazon EC2, DigitalOcean, Azure, vSphere, or existing servers. +- Standard Rancher management of Kubernetes clusters including all outlined [cluster management capabilities](../../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/kubernetes-clusters-in-rancher-setup.md#cluster-management-capabilities-by-cluster-type). + + +## RKE2 + +RKE2 is a compliant Kubernetes distribution developed by Rancher. It is specifically designed for security and compliance within the U.S. Federal Government sector. + +Primary characteristics of RKE2 include: + +1. **Security and Compliance Focus**: RKE2 places a strong emphasis on security and compliance, operating under a "secure by default" framework, making it suitable for government services and highly regulated industries like finance and healthcare. +1. **CIS Kubernetes Benchmark Conformance**: RKE2 comes pre-configured to meet the CIS Kubernetes Hardening Benchmark (currently supporting v1.23 and v1.7), with minimal manual intervention required. +1. **FIPS 140-2 Compliance**: RKE2 complies with the FIPS 140-2 standard using FIPS-validated crypto modules for its components. +1. **Embedded etcd**: RKE2 defaults to using an embedded etcd as its data store. This aligns it more closely with standard Kubernetes practices, allowing better integration with other Kubernetes tools and reducing the risk of misconfiguration. +1. **Alignment with Upstream Kubernetes**: RKE2 aims to stay closely aligned with upstream Kubernetes, reducing the risk of non-conformance that may occur when using distributions that deviate from standard Kubernetes practices. +1. **Multiple CNI Support**: RKE2 offers support for multiple Container Network Interface (CNI) plugins, including Cilium, Calico, and Multus. This is essential for use cases such as telco distribution centers and factories with various production facilities. + +## RKE2 with Rancher + +- Rancher allows easy provision of RKE2 across a range of platforms including Amazon EC2, DigitalOcean, Azure, vSphere, or existing servers. +- Standard Rancher management of Kubernetes clusters including all outlined [cluster management capabilities](../../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/kubernetes-clusters-in-rancher-setup.md#cluster-management-capabilities-by-cluster-type). diff --git a/versioned_docs/version-2.14/integrations-in-rancher/kubewarden/kubewarden.md b/versioned_docs/version-2.14/integrations-in-rancher/kubewarden/kubewarden.md new file mode 100644 index 00000000000..7a6ee36b308 --- /dev/null +++ b/versioned_docs/version-2.14/integrations-in-rancher/kubewarden/kubewarden.md @@ -0,0 +1,35 @@ +--- +title: Advanced Policy Management with Kubewarden +--- + + + + + +Kubewarden is a Policy Engine that secures and helps manage your cluster resources. It allows for validation and mutation of resource requests via policies, including context-aware policies and verifying image signatures. It can run policies in monitor or enforcing mode and provides an overview of the state of the cluster. + +Kubewarden aims to be the Universal Policy Engine by enabling and simplifying Policy as Code. Kubewarden policies are compiled into WebAssembly: they are small (400KBs ~ 2MBs), sandboxed, secure, and portable. It aims to be universal by catering to each persona in your organization: + +- Policy User: manage and declare policies using Kubernetes Custom Resources, reuse existing policies written in Rego (OPA and Gatekeeper). Test the policies outside the cluster in CI/CD. +- Policy Developer: write policies in your preferred Wasm-compiling language (Rego, Go, Rust, C#, Swift, Typescript, and more to come). Reuse the ecosystem of tools, libraries, and workflows you already know. +- Policy Distributor: policies are OCI artifacts, serve them through your OCI repository and use industry standards in your infrastructure, like Software-Bill-Of-Materials and artifact signatures. +- Cluster Operator: Kubewarden is modular (OCI registry, PolicyServers, Audit Scanner, Controller). Configure your deployment to suit your needs, segregating different tenants. Get an overview of past, current, and possible violations across the cluster with the Audit Scanner and the PolicyReports. +- Kubewarden Integrator: use it as a platform to write new Kubewarden modules and custom policies. + +## Kubewarden with Rancher + +Kubewarden’s upstream Helm charts are fully integrated as Rancher Apps, providing a UI for the install options. The charts also come with defaults that respect the Rancher stack (for example: not policing Rancher system namespaces), and default PolicyServer and Policies. Users have access to all Kubewarden features and can deploy PolicyServers and Policies manually by interacting with the Kubernetes API (e.g.: using kubectl). + +Kubewarden provides a full replacement of the removed Kubernetes Pod Security Policies. Kubewarden also integrates with the new Pod Security Admission feature introduced by a recent version of Kubernetes by augmenting its security capabilities. + +## Kubewarden with Rancher Prime + +The available Rancher UI Extension for Kubewarden integrates it into the Rancher UI. The UI Extension automates the installation and configuration of the Kubewarden stack and configures access to the policies maintained by SUSE. The UI Extension provides access to a curated catalog of ready-to-use policies. Using the UI Extension, one can browse, install, and configure these policies. + +The UI Extension provides an overview of the Kubewarden stack components and their behavior. This includes access to the Kubewarden metrics and trace events. An operator can understand the impact of policies on the cluster and troubleshoot issues. + +In addition, the UI Extension provides the Policy Reporter UI, which gives a visual overview of the compliance status of the Kubernetes cluster. With this UI, an operator can quickly identify all non-compliant Kubernetes resources, understand the reasons for violations and act accordingly. +All of this with the support offering of Rancher Prime. + + + \ No newline at end of file diff --git a/versioned_docs/version-2.14/integrations-in-rancher/logging/custom-resource-configuration/custom-resource-configuration.md b/versioned_docs/version-2.14/integrations-in-rancher/logging/custom-resource-configuration/custom-resource-configuration.md new file mode 100644 index 00000000000..b1099777da3 --- /dev/null +++ b/versioned_docs/version-2.14/integrations-in-rancher/logging/custom-resource-configuration/custom-resource-configuration.md @@ -0,0 +1,12 @@ +--- +title: Custom Resource Configuration +--- + + + + + +The following Custom Resource Definitions are used to configure logging: + +- [Flow and ClusterFlow](flows-and-clusterflows.md) +- [Output and ClusterOutput](outputs-and-clusteroutputs.md) \ No newline at end of file diff --git a/versioned_docs/version-2.14/integrations-in-rancher/logging/custom-resource-configuration/flows-and-clusterflows.md b/versioned_docs/version-2.14/integrations-in-rancher/logging/custom-resource-configuration/flows-and-clusterflows.md new file mode 100644 index 00000000000..66f1614b045 --- /dev/null +++ b/versioned_docs/version-2.14/integrations-in-rancher/logging/custom-resource-configuration/flows-and-clusterflows.md @@ -0,0 +1,79 @@ +--- +title: Flows and ClusterFlows +--- + + + + + +See the [Logging operator documentation](https://kube-logging.github.io/docs/configuration/flow/) for the full details on how to configure `Flows` and `ClusterFlows`. + +See [Rancher Integration with Logging Services: Troubleshooting](../logging.md#The-Logging-Buffer-Overloads-Pods) for how to resolve memory problems with the logging buffer. + +## Flows + +A `Flow` defines which logs to collect and filter and which output to send the logs to. + +The `Flow` is a namespaced resource, which means logs will only be collected from the namespace that the `Flow` is deployed in. + +`Flows` can be configured by filling out forms in the Rancher UI. + +For more details about the `Flow` custom resource, see [FlowSpec.](https://kube-logging.github.io/docs/configuration/crds/v1beta1/flow_types/) + +### Matches + +Match statements are used to select which containers to pull logs from. + +You can specify match statements to select or exclude logs according to Kubernetes labels, container and host names. Match statements are evaluated in the order they are defined and processed only until the first matching select or exclude rule applies. + +Matches can be configured by filling out the `Flow` or `ClusterFlow` forms in the Rancher UI. + +For detailed examples on using the match statement, see the [official documentation on log routing.](https://kube-logging.github.io/docs/configuration/log-routing/) + +### Filters + +You can define one or more filters within a `Flow`. Filters can perform various actions on the logs, such as adding data, transforming the logs, or parsing values from the records. The filters in the `Flow` are applied in the same order they appear in the definition. + +For a list of filters supported by the Logging operator, see [the official documentation on Fluentd filters](https://kube-logging.github.io/docs/configuration/plugins/filters/). + +Filters need to be configured in YAML. + +### Outputs + +This `Output` will receive logs from the `Flow`. Because the `Flow` is a namespaced resource, the `Output` must reside in same namespace as the `Flow`. + +`Outputs` can be referenced when filling out the `Flow` or `ClusterFlow` forms in the Rancher UI. + +## ClusterFlows + +Matches, filters and `Outputs` are configured for `ClusterFlows` in the same way that they are configured for `Flows`. The key difference is that the `ClusterFlow` is scoped at the cluster level and can configure log collection across all namespaces. + +`ClusterFlows` can be configured by filling out forms in the Rancher UI. + +After `ClusterFlow` selects logs from all namespaces in the cluster, logs from the cluster will be collected and logged to the selected `ClusterOutput`. + +## YAML Example + +The following example `Flow` transforms the log messages from the default namespace and sends them to an S3 `Output`: + +```yaml +apiVersion: logging.banzaicloud.io/v1beta1 +kind: Flow +metadata: + name: flow-sample + namespace: default +spec: + filters: + - parser: + remove_key_name_field: true + parse: + type: nginx + - tag_normaliser: + format: ${namespace_name}.${pod_name}.${container_name} + localOutputRefs: + - s3-output + match: + - select: + labels: + app: nginx +``` diff --git a/versioned_docs/version-2.14/integrations-in-rancher/logging/custom-resource-configuration/outputs-and-clusteroutputs.md b/versioned_docs/version-2.14/integrations-in-rancher/logging/custom-resource-configuration/outputs-and-clusteroutputs.md new file mode 100644 index 00000000000..e62870d33f6 --- /dev/null +++ b/versioned_docs/version-2.14/integrations-in-rancher/logging/custom-resource-configuration/outputs-and-clusteroutputs.md @@ -0,0 +1,299 @@ +--- +title: Outputs and ClusterOutputs +--- + + + + + +See the [Logging operator documentation](https://kube-logging.github.io/docs/configuration/flow/) for the full details on how to configure `Flows` and `ClusterFlows`. + +See [Rancher Integration with Logging Services: Troubleshooting](../logging.md#The-Logging-Buffer-Overloads-Pods) for how to resolve memory problems with the logging buffer. + +## Outputs + +The `Output` resource defines where your `Flows` can send the log messages. `Outputs` are the final stage for a logging `Flow`. + +The `Output` is a namespaced resource, which means only a `Flow` within the same namespace can access it. + +You can use secrets in these definitions, but they must also be in the same namespace. + +`Outputs` can be configured by filling out forms in the Rancher UI. + +For the details of `Output` custom resource, see [OutputSpec.](https://kube-logging.github.io/docs/configuration/crds/v1beta1/output_types/). + +The Rancher UI provides forms for configuring the following `Output` types: + +- Amazon ElasticSearch +- Azure Storage +- Cloudwatch +- Datadog +- Elasticsearch +- File +- Fluentd +- GCS +- Kafka +- Kinesis Stream +- LogDNA +- LogZ +- Loki +- New Relic +- Splunk +- SumoLogic +- Syslog + +The Rancher UI provides forms for configuring the `Output` type, target, and access credentials if applicable. + +For example configuration for each logging plugin supported by the logging operator, see the [Logging operator documentation](https://kube-logging.github.io/docs/configuration/plugins/outputs/). + +## ClusterOutputs + +`ClusterOutput` defines an `Output` without namespace restrictions. It is only effective when deployed in the same namespace as the logging operator. + +`ClusterOutputs` can be configured by filling out forms in the Rancher UI. + +For the details of the `ClusterOutput` custom resource, see [ClusterOutput.](https://kube-logging.github.io/docs/configuration/crds/v1beta1/clusteroutput_types/) + +## YAML Examples + +Once logging is installed, you can use these examples to help craft your own logging pipeline. + +- [Cluster Output to ElasticSearch](#cluster-output-to-elasticsearch) +- [Output to Splunk](#output-to-splunk) +- [Output to Syslog](#output-to-syslog) +- [Unsupported Outputs](#unsupported-outputs) + +### Cluster Output to ElasticSearch + +Let's say you wanted to send all logs in your cluster to an `elasticsearch` cluster. First, we create a cluster `Output`. + +```yaml +apiVersion: logging.banzaicloud.io/v1beta1 +kind: ClusterOutput +metadata: + name: "example-es" + namespace: "cattle-logging-system" +spec: + elasticsearch: + host: elasticsearch.example.com + port: 9200 + scheme: http +``` + +We have created this `ClusterOutput`, without elasticsearch configuration, in the same namespace as our operator: `cattle-logging-system.`. Any time we create a `ClusterFlow` or `ClusterOutput`, we have to put it in the `cattle-logging-system` namespace. + +Now that we have configured where we want the logs to go, let's configure all logs to go to that `ClusterOutput`. + +```yaml +apiVersion: logging.banzaicloud.io/v1beta1 +kind: ClusterFlow +metadata: + name: "all-logs" + namespace: "cattle-logging-system" +spec: + globalOutputRefs: + - "example-es" +``` + +We should now see our configured index with logs in it. + + +### Output to Splunk + +What if we have an application team who only wants logs from a specific namespaces sent to a `splunk` server? For this case, we can use namespaced `Outputs` and `Flows`. + +Before we start, let's set up that team's application: `coolapp`. + +```yaml +apiVersion: v1 +kind: Namespace +metadata: + name: devteam +--- +apiVersion: apps/v1 +kind: Deployment +metadata: + name: coolapp + namespace: devteam + labels: + app: coolapp +spec: + replicas: 2 + selector: + matchLabels: + app: coolapp + template: + metadata: + labels: + app: coolapp + spec: + containers: + - name: generator + image: paynejacob/loggenerator:latest +``` + +With `coolapp` running, we will follow a similar path as when we created a `ClusterOutput`. However, unlike `ClusterOutputs`, we create our `Output` in our application's namespace. + +```yaml +apiVersion: logging.banzaicloud.io/v1beta1 +kind: Output +metadata: + name: "devteam-splunk" + namespace: "devteam" +spec: + splunkHec: + hec_host: splunk.example.com + hec_port: 8088 + protocol: http +``` + +Once again, let's feed our `Output` some logs: + +```yaml +apiVersion: logging.banzaicloud.io/v1beta1 +kind: Flow +metadata: + name: "devteam-logs" + namespace: "devteam" +spec: + localOutputRefs: + - "devteam-splunk" +``` + + +### Output to Syslog + +Let's say you wanted to send all logs in your cluster to an `syslog` server. First, we create a `ClusterOutput`: + +```yaml +apiVersion: logging.banzaicloud.io/v1beta1 +kind: ClusterOutput +metadata: + name: "example-syslog" + namespace: "cattle-logging-system" +spec: + syslog: + buffer: + timekey: 30s + timekey_use_utc: true + timekey_wait: 10s + flush_interval: 5s + format: + type: json + app_name_field: test + host: syslog.example.com + insecure: true + port: 514 + transport: tcp +``` + +Now that we have configured where we want the logs to go, let's configure all logs to go to that `Output`. + +```yaml +apiVersion: logging.banzaicloud.io/v1beta1 +kind: ClusterFlow +metadata: + name: "all-logs" + namespace: cattle-logging-system +spec: + globalOutputRefs: + - "example-syslog" +``` + +### Unsupported Outputs + +For the final example, we create an `Output` to write logs to a destination that is not supported out of the box: + +:::note Note on syslog: + +`syslog` is a supported `Output`. However, this example still provides an overview on using unsupported plugins. + +::: + +```yaml +apiVersion: v1 +kind: Secret +metadata: + name: syslog-config + namespace: cattle-logging-system +type: Opaque +stringData: + fluent-bit.conf: | + [INPUT] + Name forward + Port 24224 + + [OUTPUT] + Name syslog + InstanceName syslog-output + Match * + Addr syslog.example.com + Port 514 + Cluster ranchers + +--- +apiVersion: apps/v1 +kind: Deployment +metadata: + name: fluentbit-syslog-forwarder + namespace: cattle-logging-system + labels: + output: syslog +spec: + selector: + matchLabels: + output: syslog + template: + metadata: + labels: + output: syslog + spec: + containers: + - name: fluentbit + image: paynejacob/fluent-bit-out-syslog:latest + ports: + - containerPort: 24224 + volumeMounts: + - mountPath: "/fluent-bit/etc/" + name: configuration + volumes: + - name: configuration + secret: + secretName: syslog-config +--- +apiVersion: v1 +kind: Service +metadata: + name: syslog-forwarder + namespace: cattle-logging-system +spec: + selector: + output: syslog + ports: + - protocol: TCP + port: 24224 + targetPort: 24224 +--- +apiVersion: logging.banzaicloud.io/v1beta1 +kind: ClusterFlow +metadata: + name: all-logs + namespace: cattle-logging-system +spec: + globalOutputRefs: + - syslog +--- +apiVersion: logging.banzaicloud.io/v1beta1 +kind: ClusterOutput +metadata: + name: syslog + namespace: cattle-logging-system +spec: + forward: + servers: + - host: "syslog-forwarder.cattle-logging-system" + require_ack_response: false + ignore_network_errors_at_startup: false +``` + +Let's break down what is happening here. First, we create a deployment of a container that has the additional `syslog` plugin and accepts logs forwarded from another `fluentd`. Next we create an `Output` configured as a forwarder to our deployment. The deployment `fluentd` will then forward all logs to the configured `syslog` destination. diff --git a/versioned_docs/version-2.14/integrations-in-rancher/logging/logging-architecture.md b/versioned_docs/version-2.14/integrations-in-rancher/logging/logging-architecture.md new file mode 100644 index 00000000000..ec56b8d1ef6 --- /dev/null +++ b/versioned_docs/version-2.14/integrations-in-rancher/logging/logging-architecture.md @@ -0,0 +1,32 @@ +--- +title: Logging Architecture +--- + + + + + +This section summarizes the architecture of the Rancher logging application. + +For more details about how the Logging operator works, see the [official documentation.](https://kube-logging.github.io/docs/#architecture) + +## How the Logging Operator Works + +The Logging operator automates the deployment and configuration of a Kubernetes logging pipeline. It deploys and configures a Fluent Bit DaemonSet on every node to collect container and application logs from the node file system. + +Fluent Bit queries the Kubernetes API and enriches the logs with metadata about the pods, and transfers both the logs and the metadata to Fluentd. Fluentd receives, filters, and transfers logs to multiple `Outputs`. + +The following custom resources are used to define how logs are filtered and sent to their `Outputs`: + +- A `Flow` is a namespaced custom resource that uses filters and selectors to route log messages to the appropriate `Outputs`. +- A `ClusterFlow` is used to route cluster-level log messages. +- An `Output` is a namespaced resource that defines where the log messages are sent. +- A `ClusterOutput` defines an `Output` that is available from all `Flows` and `ClusterFlows`. + +Each `Flow` must reference an `Output`, and each `ClusterFlow` must reference a `ClusterOutput`. + +The following figure from the [Logging Operator documentation](https://kube-logging.github.io/docs/#architecture) shows the new logging architecture: + +
How the Logging Operator Works with Fluentd and Fluent Bit
+ +![How the Logging Operator Works with Fluentd](/img/banzai-cloud-logging-operator.png) diff --git a/versioned_docs/version-2.14/integrations-in-rancher/logging/logging-helm-chart-options.md b/versioned_docs/version-2.14/integrations-in-rancher/logging/logging-helm-chart-options.md new file mode 100644 index 00000000000..1c77d299816 --- /dev/null +++ b/versioned_docs/version-2.14/integrations-in-rancher/logging/logging-helm-chart-options.md @@ -0,0 +1,97 @@ +--- +title: rancher-logging Helm Chart Options +--- + + + + + +## Enable/Disable Windows Node Logging + +You can enable or disable Windows node logging by setting `global.cattle.windows.enabled` to either `true` or `false` in the `values.yaml`. + +By default, Windows node logging will be enabled if the Cluster Dashboard UI is used to install the logging application on a Windows cluster. + +In this scenario, setting `global.cattle.windows.enabled` to `false` will disable Windows node logging on the cluster. +When disabled, logs will still be collected from Linux nodes within the Windows cluster. + +:::note + +Currently an [issue](https://github.com/rancher/rancher/issues/32325) exists where Windows nodeAgents are not deleted when performing a `helm upgrade` after disabling Windows logging in a Windows cluster. In this scenario, users may need to manually remove the Windows nodeAgents if they are already installed. + +::: + +## Working with a Custom Docker Root Directory + +If using a custom Docker root directory, you can set `global.dockerRootDirectory` in `values.yaml`. + +This will ensure that the Logging CRs created will use your specified path rather than the default Docker `data-root` location. + +Note that this only affects Linux nodes. + +If there are any Windows nodes in the cluster, the change will not be applicable to those nodes. + +## Adding NodeSelector Settings and Tolerations for Custom Taints + +You can add your own `nodeSelector` settings and add `tolerations` for additional taints by editing the logging Helm chart values. For details, see [this page.](taints-and-tolerations.md) + +## Enabling the Logging Application to Work with SELinux + +:::note Requirements: + +Logging v2 was tested with SELinux on RHEL/CentOS 7 and 8. + +::: + +[Security-Enhanced Linux (SELinux)](https://en.wikipedia.org/wiki/Security-Enhanced_Linux) is a security enhancement to Linux. After being historically used by government agencies, SELinux is now industry standard and is enabled by default on CentOS 7 and 8. + +To use Logging v2 with SELinux, we recommend installing the `rancher-selinux` RPM according to these [instructions](../../reference-guides/rancher-security/selinux-rpm/selinux-rpm.md). + +Then, when installing the logging application, configure the chart to be SELinux aware by changing `global.seLinux.enabled` to `true` in the `values.yaml`. + +## Additional Logging Sources + +By default, Rancher collects logs for [control plane components](https://kubernetes.io/docs/concepts/overview/components/#control-plane-components) and [node components](https://kubernetes.io/docs/concepts/overview/components/#node-components) for all cluster types. + +In some cases, Rancher may be able to collect additional logs. + +The following table summarizes the sources where additional logs may be collected for each node types: + +| Logging Source | Linux Nodes (including in Windows cluster) | Windows Nodes | +| --- | --- | ---| +| RKE2 | ✓ | | +| K3s | ✓ | | +| AKS | ✓ | | +| EKS | ✓ | | +| GKE | ✓ | | + +To enable hosted Kubernetes providers as additional logging sources, enable **Enable enhanced cloud provider logging** option when installing or upgrading the Logging Helm chart. + +When enabled, Rancher collects all additional node and control plane logs the provider has made available, which may vary between providers + +If you're already using a cloud provider's own logging solution such as AWS CloudWatch or Google Cloud operations suite (formerly Stackdriver), it is not necessary to enable this option as the native solution will have unrestricted access to all logs. + +## Systemd Configuration + +In Rancher logging, `SystemdLogPath` must be configured for K3s and RKE2 Kubernetes distributions. + +K3s and RKE2 Kubernetes distributions log to journald, which is the subsystem of systemd that is used for logging. In order to collect these logs, the `systemdLogPath` needs to be defined. While the `run/log/journal` directory is used by default, some Linux distributions do not default to this path. For example, Ubuntu defaults to `var/log/journal`. To determine your `systemdLogPath` configuration, see steps below. + +**Steps for Systemd Configuration:** + +* Run `cat /etc/systemd/journald.conf | grep -E ^\#?Storage | cut -d"=" -f2` on one of your nodes. +* If `persistent` is returned, your `systemdLogPath` should be `/var/log/journal`. +* If `volatile` is returned, your `systemdLogPath` should be `/run/log/journal`. +* If `auto` is returned, check if `/var/log/journal` exists. + * If `/var/log/journal` exists, then use `/var/log/journal`. + * If `/var/log/journal` does not exist, then use `/run/log/journal`. + +:::note + +If any value not described above is returned, Rancher Logging will not be able to collect control plane logs. To address this issue, you will need to perform the following actions on every control plane node: + +* Set `Storage=volatile` in journald.conf. +* Reboot your machine. +* Set `systemdLogPath` to `/run/log/journal`. + +::: diff --git a/versioned_docs/version-2.14/integrations-in-rancher/logging/logging.md b/versioned_docs/version-2.14/integrations-in-rancher/logging/logging.md new file mode 100644 index 00000000000..217f64f9019 --- /dev/null +++ b/versioned_docs/version-2.14/integrations-in-rancher/logging/logging.md @@ -0,0 +1,152 @@ +--- +title: Rancher Integration with Logging Services +description: Rancher integrates with popular logging services. Learn the requirements and benefits of integrating with logging services, and enable logging on your cluster. +--- + + + + + +The [Logging operator](https://kube-logging.github.io/docs/) now powers Rancher's logging solution in place of the former, in-house solution. + +## Enabling Logging + +You can enable the logging for a Rancher managed cluster by going to the Apps page and installing the logging app. + +1. Go to the cluster where you want to install logging and click **Apps**. +1. Click the **Logging** app. +1. Scroll to the bottom of the Helm chart README and click **Install**. + +**Result:** The logging app is deployed in the `cattle-logging-system` namespace. + +## Uninstall Logging + +1. Go to the cluster where you want to install logging and click **Apps**. +1. Click **Installed Apps**. +1. Go to the `cattle-logging-system` namespace and check the boxes for `rancher-logging` and `rancher-logging-crd`. +1. Click **Delete**. +1. Confirm **Delete**. + +**Result** `rancher-logging` is uninstalled. + +## Architecture + +For more information about how the logging application works, see [this section.](logging-architecture.md) + + + +## Role-based Access Control + +Rancher logging has two roles, `logging-admin` and `logging-view`. For more information on how and when to use these roles, see [this page.](rbac-for-logging.md) + +## Configuring Logging Custom Resources + +To manage `Flows,` `ClusterFlows`, `Outputs`, and `ClusterOutputs`, + +1. In the upper left corner, click **☰ > Cluster Management**. +1. On the **Clusters** page, go to the cluster where you want to configure logging custom resources and click **Explore**. +1. In the left navigation bar, click **Logging**. + +### Flows and ClusterFlows + +For help with configuring `Flows` and `ClusterFlows`, see [this page.](custom-resource-configuration/flows-and-clusterflows.md) + +### Outputs and ClusterOutputs + +For help with configuring `Outputs` and `ClusterOutputs`, see [this page.](custom-resource-configuration/outputs-and-clusteroutputs.md) + +## Using a custom HostTailer image + +To use a custom image for the `HostTailer` resource, you need to specify the image in the `containerOverrides` section of each `fileTailer` of the `HostTailer` resource. + +```yaml +apiVersion: logging-extensions.banzaicloud.io/v1alpha1 +kind: HostTailer +metadata: + name: cluster-system-log +spec: + workloadMetaOverrides: + annotations: {} + labels: {} + fileTailers: + - disabled: false + name: kubelet-log + path: /var/lib/rancher/rke2/agent/logs/*.log + containerOverrides: + image: /: + - disabled: false + name: containerd-log + path: /var/lib/rancher/rke2/agent/containerd/*.log + containerOverrides: + image: /: + - name: kube-audit + path: /var/log/kube-audit/audit-log.json + disabled: false + containerOverrides: + image: /: +``` + +## Configuring the Logging Helm Chart + +For a list of options that can be configured when the logging application is installed or upgraded, see [this page.](logging-helm-chart-options.md) + +### Windows Support + +You can [enable logging](logging-helm-chart-options.md#enabledisable-windows-node-logging) from Windows nodes. + + +### Working with a Custom Docker Root Directory + +For details on using a custom Docker root directory, see [this section.](logging-helm-chart-options.md#working-with-a-custom-docker-root-directory) + + +### Working with Taints and Tolerations + +For information on how to use taints and tolerations with the logging application, see [this page.](taints-and-tolerations.md) + + +### Logging V2 with SELinux + +For information on enabling the logging application for SELinux-enabled nodes, see [this section.](logging-helm-chart-options.md#enabling-the-logging-application-to-work-with-selinux) + +### Additional Logging Sources + +By default, Rancher collects logs for control plane components and node components for all cluster types. In some cases additional logs can be collected. For details, see [this section.](logging-helm-chart-options.md#additional-logging-sources) + + +## Troubleshooting + +### The Logging Buffer Overloads Pods + +Depending on your configuration, the default buffer size may be too large and cause pod failures. One way to reduce the load is to lower the logger's flush interval. This prevents logs from overfilling the buffer. You can also add more flush threads to handle moments when many logs are attempting to fill the buffer at once. + +For a more complete description of how to configure the logging buffer to suit your organization's needs, see the official Logging operator documentation on [buffers](https://kube-logging.github.io/docs/configuration/plugins/outputs/buffer/) and on [Fluentd configuration](https://kube-logging.github.io/docs/logging-infrastructure/fluentd/). + +### The `cattle-logging` Namespace Being Recreated + +If your cluster previously deployed logging from the global view in the legacy Rancher UI, you may encounter an issue where its `cattle-logging` namespace is continually being recreated. + +The solution is to delete all `clusterloggings.management.cattle.io` and `projectloggings.management.cattle.io` custom resources from the cluster specific namespace in the management cluster. +The existence of these custom resources causes Rancher to create the `cattle-logging` namespace in the downstream cluster if it does not exist. + +The cluster namespace matches the cluster ID, so we need to find the cluster ID for each cluster. + +1. In the upper left corner, click **☰ > Cluster Management**. +1. On the **Clusters** page, go to the cluster you want to get the ID of and click **Explore**. +2. Copy the `` portion from one of the URLs below. The `` portion is the cluster namespace name. + +```bash +# Cluster Management UI +https:///c// + +# Cluster Dashboard +https:///dashboard/c// +``` + +Now that we have the `` namespace, we can delete the CRs that cause `cattle-logging` to be continually recreated. +*Warning:* ensure that logging, the version installed from the global view in the legacy Rancher UI, is not currently in use. + +```bash +kubectl delete crd clusterloggings.management.cattle.io -n +kubectl delete crd projectloggings.management.cattle.io -n +``` diff --git a/versioned_docs/version-2.14/integrations-in-rancher/logging/rbac-for-logging.md b/versioned_docs/version-2.14/integrations-in-rancher/logging/rbac-for-logging.md new file mode 100644 index 00000000000..e718dce1887 --- /dev/null +++ b/versioned_docs/version-2.14/integrations-in-rancher/logging/rbac-for-logging.md @@ -0,0 +1,27 @@ +--- +title: Role-based Access Control for Logging +--- + + + + + +Rancher logging has two roles, `logging-admin` and `logging-view`. + +- `logging-admin` gives users full access to namespaced `Flows` and `Outputs` +- `logging-view` allows users to *view* namespaced `Flows` and `Outputs`, and `ClusterFlows` and `ClusterOutputs` + +:::note Why choose one role over the other? + +Edit access to `ClusterFlow` and `ClusterOutput` resources is powerful. Any user with it has edit access for all logs in the cluster. + +::: + +In Rancher, the cluster administrator role is the only role with full access to all `rancher-logging` resources. Cluster members are not able to edit or read any logging resources. Project owners and members have the following privileges: + +Project Owners | Project Members +--- | --- +able to create namespaced `Flows` and `Outputs` in their projects' namespaces | only able to view the `Flows` and `Outputs` in projects' namespaces +can collect logs from anything in their projects' namespaces | cannot collect any logs in their projects' namespaces + +Both project owners and project members require at least *one* namespace in their project to use logging. If they do not, then they may not see the logging button in the top nav dropdown. \ No newline at end of file diff --git a/versioned_docs/version-2.14/integrations-in-rancher/logging/taints-and-tolerations.md b/versioned_docs/version-2.14/integrations-in-rancher/logging/taints-and-tolerations.md new file mode 100644 index 00000000000..0147598e84c --- /dev/null +++ b/versioned_docs/version-2.14/integrations-in-rancher/logging/taints-and-tolerations.md @@ -0,0 +1,69 @@ +--- +title: Working with Taints and Tolerations +--- + + + + + +"Tainting" a Kubernetes node causes pods to repel running on that node. + +Unless the pods have a `toleration` for that node's taint, they will run on other nodes in the cluster. + +[Taints and tolerations](https://kubernetes.io/docs/concepts/scheduling-eviction/taint-and-toleration/) can work in conjunction with the `nodeSelector` [field](https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node/#nodeselector) within the `PodSpec`, which enables the *opposite* effect of a taint. + +Using `nodeSelector` gives pods an affinity towards certain nodes. + +Both provide choice for the what node(s) the pod will run on. + +- [Default Implementation in Rancher's Logging Stack](#default-implementation-in-ranchers-logging-stack) +- [Adding NodeSelector Settings and Tolerations for Custom Taints](#adding-nodeselector-settings-and-tolerations-for-custom-taints) + + +## Default Implementation in Rancher's Logging Stack + +By default, Rancher taints all Linux nodes with `cattle.io/os=linux`, and does not taint Windows nodes. +The logging stack pods have `tolerations` for this taint, which enables them to run on Linux nodes. +Moreover, most logging stack pods run on Linux only and have a `nodeSelector` added to ensure they run on Linux nodes. + +This example Pod YAML file shows a nodeSelector being used with a toleration: + +```yaml +apiVersion: v1 +kind: Pod +# metadata... +spec: + # containers... + tolerations: + - key: cattle.io/os + operator: "Equal" + value: "linux" + effect: NoSchedule + nodeSelector: + kubernetes.io/os: linux +``` + +In the above example, we ensure that our pod only runs on Linux nodes, and we add a `toleration` for the taint we have on all of our Linux nodes. + +You can do the same with Rancher's existing taints, or with your own custom ones. + +## Adding NodeSelector Settings and Tolerations for Custom Taints + +If you would like to add your own `nodeSelector` settings, or if you would like to add `tolerations` for additional taints, you can pass the following to the chart's values. + +```yaml +tolerations: + # insert tolerations... +nodeSelector: + # insert nodeSelector... +``` + +These values will add both settings to the `fluentd`, `fluentbit`, and `logging-operator` containers. +Essentially, these are global settings for all pods in the logging stack. + +However, if you would like to add tolerations for *only* the `fluentbit` container, you can add the following to the chart's values. + +```yaml +fluentbit_tolerations: + # insert tolerations list for fluentbit containers only... +``` diff --git a/versioned_docs/version-2.14/integrations-in-rancher/longhorn/longhorn.md b/versioned_docs/version-2.14/integrations-in-rancher/longhorn/longhorn.md new file mode 100644 index 00000000000..e6f65680932 --- /dev/null +++ b/versioned_docs/version-2.14/integrations-in-rancher/longhorn/longhorn.md @@ -0,0 +1,15 @@ +--- +title: Cloud Native Storage with Longhorn +--- + + + + + +## Longhorn + +Longhorn is an official [Cloud Native Computing Foundation project (CNCF)](https://cncf.io/) project that delivers a powerful cloud-native distributed storage platform for Kubernetes that can run anywhere. When combined with Rancher, Longhorn makes the deployment of highly available persistent block storage in your Kubernetes environment easy, fast and reliable. + +## Longhorn with Rancher + +With Rancher Prime and Longhorn, users can easily deploy with 1-click via the Rancher catalog and conduct lifecycle management for managed clusters; empowering the user to install and upgrade, together with draining operation for graceful operations. Longhorn with Rancher also provides mixed cluster support with Windows, Rancher hosted images, UI Proxy access through Rancher, and Rancher monitoring with Longhorn metrics. diff --git a/versioned_docs/version-2.14/integrations-in-rancher/longhorn/overview.md b/versioned_docs/version-2.14/integrations-in-rancher/longhorn/overview.md new file mode 100644 index 00000000000..13a581175d2 --- /dev/null +++ b/versioned_docs/version-2.14/integrations-in-rancher/longhorn/overview.md @@ -0,0 +1,74 @@ +--- +title: Overview +--- + + + + + +[Longhorn](https://longhorn.io/) is a lightweight, reliable, and easy-to-use distributed block storage system for Kubernetes. + +Longhorn is free, open source software. Originally developed by Rancher Labs, it is now being developed as a sandbox project of the Cloud Native Computing Foundation. It can be installed on any Kubernetes cluster with Helm, with kubectl, or with the Rancher UI. You can learn more about its architecture [here.](https://longhorn.io/docs/latest/concepts/) + +With Longhorn, you can: + +- Use Longhorn volumes as persistent storage for the distributed stateful applications in your Kubernetes cluster +- Partition your block storage into Longhorn volumes so that you can use Kubernetes volumes with or without a cloud provider +- Replicate block storage across multiple nodes and data centers to increase availability +- Store backup data in external storage such as NFS or AWS S3 +- Create cross-cluster disaster recovery volumes so that data from a primary Kubernetes cluster can be quickly recovered from backup in a second Kubernetes cluster +- Schedule recurring snapshots of a volume, and schedule recurring backups to NFS or S3-compatible secondary storage +- Restore volumes from backup +- Upgrade Longhorn without disrupting persistent volumes + +
Longhorn Dashboard
+ +![Longhorn Dashboard](/img/longhorn-screenshot.png) + +## Installing Longhorn with Rancher + +1. Fulfill all [Installation Requirements.](https://longhorn.io/docs/latest/deploy/install/#installation-requirements) +1. Go to the cluster where you want to install Longhorn. +1. Click **Apps**. +1. Click **Charts**. +1. Click **Longhorn**. +1. Optional: To customize the initial settings, click **Longhorn Default Settings** and edit the configuration. For help customizing the settings, refer to the [Longhorn documentation.](https://longhorn.io/docs/latest/references/settings/) +1. Click **Install**. + +**Result:** Longhorn is deployed in the Kubernetes cluster. + +## Accessing Longhorn from the Rancher UI + +1. Go to the cluster where Longhorn is installed. In the left navigation menu, click **Longhorn**. +1. On this page, you can edit Kubernetes resources managed by Longhorn. To view the Longhorn UI, click the **Longhorn** button in the **Overview** section. + +**Result:** You will be taken to the Longhorn UI, where you can manage your Longhorn volumes and their replicas in the Kubernetes cluster, as well as secondary backups of your Longhorn storage that may exist in another Kubernetes cluster or in S3. + +## Uninstalling Longhorn from the Rancher UI + +1. Go to the cluster where Longhorn is installed and click **Apps**. +1. Click **Installed Apps**. +1. Go to the `longhorn-system` namespace and check the boxes next to the `longhorn` and `longhorn-crd` apps. +1. Click **Delete,** and confirm **Delete**. + +**Result:** Longhorn is uninstalled. + +## GitHub Repository + +The Longhorn project is available [here.](https://github.com/longhorn/longhorn) + +## Documentation + +The Longhorn documentation is [here.](https://longhorn.io/docs/) + +## Architecture + +Longhorn creates a dedicated storage controller for each volume and synchronously replicates the volume across multiple replicas stored on multiple nodes. + +The storage controller and replicas are themselves orchestrated using Kubernetes. + +You can learn more about its architecture [here.](https://longhorn.io/docs/latest/concepts/) + +
Longhorn Architecture
+ +![Longhorn Architecture](/img/longhorn-architecture.svg) diff --git a/versioned_docs/version-2.14/integrations-in-rancher/monitoring-and-alerting/built-in-dashboards.md b/versioned_docs/version-2.14/integrations-in-rancher/monitoring-and-alerting/built-in-dashboards.md new file mode 100644 index 00000000000..0f212e8012e --- /dev/null +++ b/versioned_docs/version-2.14/integrations-in-rancher/monitoring-and-alerting/built-in-dashboards.md @@ -0,0 +1,121 @@ +--- +title: Built-in Dashboards +--- + + + + + +## Grafana UI + +[Grafana](https://grafana.com/grafana/) allows you to query, visualize, alert on and understand your metrics no matter where they are stored. Create, explore, and share dashboards with your team and foster a data driven culture. + +To see the default dashboards for time series data visualization, go to the Grafana UI. + +### Customizing Grafana + +To view and customize the PromQL queries powering the Grafana dashboard, see [this page.](../../how-to-guides/advanced-user-guides/monitoring-alerting-guides/customize-grafana-dashboard.md) + +### Persistent Grafana Dashboards + +To create a persistent Grafana dashboard, see [this page.](../../how-to-guides/advanced-user-guides/monitoring-alerting-guides/create-persistent-grafana-dashboard.md) + +### Access to Grafana + +For information about role-based access control for Grafana, see [this section.](rbac-for-monitoring.md#role-based-access-control-for-grafana) + + +## Alertmanager UI + +When `rancher-monitoring` is installed, the Prometheus Alertmanager UI is deployed, allowing you to view your alerts and the current Alertmanager configuration. + +:::note + +This section assumes familiarity with how monitoring components work together. For more information about Alertmanager, see [How Alertmanager Works.](how-monitoring-works.md#3-how-alertmanager-works) + +::: + +### Accessing the Alertmanager UI + +The Alertmanager UI lets you see the most recently fired alerts. + +:::note Prerequisite: + +The `rancher-monitoring` application must be installed. + +::: + +To see the Alertmanager UI, + +1. In the upper left corner, click **☰ > Cluster Management**. +1. On the **Clusters** page, go to the cluster where you want to see the Alertmanager UI, click **Explore**. +1. In the left navigation bar, click **Monitoring**. +1. Click **Alertmanager**. + +**Result:** The Alertmanager UI opens in a new tab. For help with configuration, refer to the [official Alertmanager documentation.](https://prometheus.io/docs/alerting/latest/alertmanager/) + +For more information on configuring Alertmanager in Rancher, see [this page.](../../how-to-guides/advanced-user-guides/monitoring-v2-configuration-guides/advanced-configuration/alertmanager.md) + +
The Alertmanager UI
+ +![Alertmanager UI](/img/alertmanager-ui.png) + + +### Viewing Default Alerts + +To see alerts that are fired by default, go to the Alertmanager UI and click **Expand all groups**. + + +## Prometheus UI + +By default, the [kube-state-metrics service](https://github.com/kubernetes/kube-state-metrics) provides a wealth of information about CPU and memory utilization to the monitoring application. These metrics cover Kubernetes resources across namespaces. This means that in order to see resource metrics for a service, you don't need to create a new ServiceMonitor for it. Because the data is already in the time series database, you can go to the Prometheus UI and run a PromQL query to get the information. The same query can be used to configure a Grafana dashboard to show a graph of those metrics over time. + +To see the Prometheus UI, install `rancher-monitoring`. Then: + +1. In the upper left corner, click **☰ > Cluster Management**. +1. On the **Clusters** page, go to the cluster where you want to see the Prometheus UI and click **Explore**. +1. In the left navigation bar, click **Monitoring**. +1. Click **Prometheus Graph**. + +
Prometheus Graph UI
+ +![Prometheus Graph UI](/img/prometheus-graph-ui.png) + +### Viewing the Prometheus Targets + +To see what services you are monitoring, you will need to see your targets. Targets are set up by ServiceMonitors and PodMonitors as sources to scrape metrics from. You won't need to directly edit targets, but the Prometheus UI can be useful for giving you an overview of all of the sources of metrics that are being scraped. + +To see the Prometheus Targets, install `rancher-monitoring`. Then: + + +1. In the upper left corner, click **☰ > Cluster Management**. +1. On the **Clusters** page, go to the cluster where you want to see the Prometheus targets and click **Explore**. +1. In the left navigation bar, click **Monitoring**. +1. Click **Prometheus Targets**. + +
Targets in the Prometheus UI
+ +![Prometheus Targets UI](/img/prometheus-targets-ui.png) + +### Viewing the PrometheusRules + +When you define a Rule (which is declared within a RuleGroup in a PrometheusRule resource), the [spec of the Rule itself](https://github.com/prometheus-operator/prometheus-operator/blob/main/Documentation/api-reference/api.md#rule) contains labels that are used by Alertmanager to figure out which Route should receive a certain Alert. + +To see the PrometheusRules, install `rancher-monitoring`. Then: + +1. In the upper left corner, click **☰ > Cluster Management**. +1. On the **Clusters** page, go to the cluster where you want to see the visualizations and click **Explore**. +1. In the left navigation bar, click **Monitoring**. +1. Click **Prometheus Rules**. + +You can also see the rules in the Prometheus UI: + +
Rules in the Prometheus UI
+ +![PrometheusRules UI](/img/prometheus-rules-ui.png) + +For more information on configuring PrometheusRules in Rancher, see [this page.](../../how-to-guides/advanced-user-guides/monitoring-v2-configuration-guides/advanced-configuration/prometheusrules.md) + +## Legacy UI + +For information on the dashboards available in v2.2 to v2.4 of Rancher, before the introduction of the `rancher-monitoring` application, see the [Rancher v2.0—v2.4 docs](https://github.com/rancher/rancher-docs/tree/main/archived_docs/en/version-2.0-2.4/explanations/integrations-in-rancher/cluster-monitoring/viewing-metrics.md). diff --git a/versioned_docs/version-2.14/integrations-in-rancher/monitoring-and-alerting/how-monitoring-works.md b/versioned_docs/version-2.14/integrations-in-rancher/monitoring-and-alerting/how-monitoring-works.md new file mode 100644 index 00000000000..1a34415ea58 --- /dev/null +++ b/versioned_docs/version-2.14/integrations-in-rancher/monitoring-and-alerting/how-monitoring-works.md @@ -0,0 +1,249 @@ +--- +title: How Monitoring Works +--- + + + + + +## 1. Architecture Overview + +_**The following sections describe how data flows through the Monitoring V2 application:**_ + +### Prometheus Operator + +Prometheus Operator observes ServiceMonitors, PodMonitors, and PrometheusRules being created. When the Prometheus configuration resources are created, Prometheus Operator calls the Prometheus API to sync the new configuration. As the diagram at the end of this section shows, the Prometheus Operator acts as the intermediary between Prometheus and Kubernetes, calling the Prometheus API to synchronize Prometheus with the monitoring-related resources in Kubernetes. + +### ServiceMonitors and PodMonitors + +ServiceMonitors and PodMonitors declaratively specify targets, such as Services and Pods, that need to be monitored. + +- Targets are scraped on a recurring schedule based on the configured Prometheus scrape interval, and the metrics that are scraped are stored into the Prometheus Time Series Database (TSDB). + +- In order to perform the scrape, ServiceMonitors and PodMonitors are defined with label selectors that determine which Services or Pods should be scraped and endpoints that determine how the scrape should happen on the given target, e.g., scrape/metrics in TCP 10252, proxying through IP addr x.x.x.x. + +- Out of the box, Monitoring V2 comes with certain pre-configured exporters that are deployed based on the type of Kubernetes cluster that it is deployed on. For more information, see [Scraping and Exposing Metrics](#5-scraping-and-exposing-metrics). + +### How PushProx Works + +- Certain internal Kubernetes components are scraped via a proxy deployed as part of Monitoring V2 called **PushProx**. The Kubernetes components that expose metrics to Prometheus through PushProx are the following: +`kube-controller-manager`, `kube-scheduler`, `etcd`, and `kube-proxy`. + +- For each PushProx exporter, we deploy one PushProx client onto all target nodes. For example, a PushProx client is deployed onto all controlplane nodes for kube-controller-manager, all etcd nodes for kube-etcd, and all nodes for kubelet. + +- We deploy exactly one PushProx proxy per exporter. The process for exporting metrics is as follows: + +1. The PushProx Client establishes an outbound connection with the PushProx Proxy. +1. The client then polls the proxy for scrape requests that have come into the proxy. +1. When the proxy receives a scrape request from Prometheus, the client sees it as a result of the poll. +1. The client scrapes the internal component. +1. The internal component responds by pushing metrics back to the proxy. + + +

Process for Exporting Metrics with PushProx:
+ +![Process for Exporting Metrics with PushProx](/img/pushprox-process.svg) + +### PrometheusRules + +PrometheusRules allow users to define rules for what metrics or time series database queries should result in alerts being fired. Rules are evaluated on an interval. + +- **Recording rules** create a new time series based on existing series that have been collected. They are frequently used to precompute complex queries. +- **Alerting rules** run a particular query and fire an alert from Prometheus if the query evaluates to a non-zero value. + +### Alert Routing + +Once Prometheus determines that an alert needs to be fired, alerts are forwarded to **Alertmanager**. + +- Alerts contain labels that come from the PromQL query itself and additional labels and annotations that can be provided as part of specifying the initial PrometheusRule. + +- Before receiving any alerts, Alertmanager will use the **routes** and **receivers** specified in its configuration to form a routing tree on which all incoming alerts are evaluated. Each node of the routing tree can specify additional grouping, labeling, and filtering that needs to happen based on the labels attached to the Prometheus alert. A node on the routing tree (usually a leaf node) can also specify that an alert that reaches it needs to be sent out to a configured Receiver, e.g., Slack, PagerDuty, SMS, etc. Note that Alertmanager will send an alert first to **alertingDriver**, then alertingDriver will send or forward alert to the proper destination. + +- Routes and receivers are also stored in the Kubernetes API via the Alertmanager Secret. When the Secret is updated, Alertmanager is also updated automatically. Note that routing occurs via labels only (not via annotations, etc.). + +## 2. How Prometheus Works + +### Storing Time Series Data + +After collecting metrics from exporters, Prometheus stores the time series in a local on-disk time series database. Prometheus optionally integrates with remote systems, but `rancher-monitoring` uses local storage for the time series database. + +Once stored, users can query this TSDB using PromQL, the query language for Prometheus. + +PromQL queries can be visualized in one of two ways: + +1. By supplying the query in Prometheus's Graph UI, which will show a simple graphical view of the data. +1. By creating a Grafana Dashboard that contains the PromQL query and additional formatting directives that label axes, add units, change colors, use alternative visualizations, etc. + +### Defining Rules for Prometheus + +Rules define queries that Prometheus needs to execute on a regular `evaluationInterval` to perform certain actions, such as firing an alert (alerting rules) or precomputing a query based on others existing in its TSDB (recording rules). These rules are encoded in PrometheusRules custom resources. When PrometheusRule custom resources are created or updated, the Prometheus Operator observes the change and calls the Prometheus API to synchronize the set of rules that Prometheus is currently evaluating on a regular interval. + +A PrometheusRule allows you to define one or more RuleGroups. Each RuleGroup consists of a set of Rule objects that can each represent either an alerting or a recording rule with the following fields: + +- The name of the new alert or record +- A PromQL expression for the new alert or record +- Labels that should be attached to the alert or record that identify it (e.g. cluster name or severity) +- Annotations that encode any additional important pieces of information that need to be displayed on the notification for an alert (e.g. summary, description, message, runbook URL, etc.). This field is not required for recording rules. + +Upon evaluating a [rule](https://github.com/prometheus-operator/prometheus-operator/blob/main/Documentation/api-reference/api.md#rule), Prometheus runs the provided PromQL query, adds the provided labels, and runs the appropriate action for the rule. If the rule triggers an alert, Prometheus also adds the provided annotations. For example, an Alerting Rule that adds `team: front-end` as a label to the provided PromQL query will append that label to the fired alert, which will allow Alertmanager to forward the alert to the correct Receiver. + +### Alerting and Recording Rules + +Prometheus doesn't maintain the state of whether alerts are active. It fires alerts repetitively at every evaluation interval, relying on Alertmanager to group and filter the alerts into meaningful notifications. + +The `evaluation_interval` constant defines how often Prometheus evaluates its alerting rules against the time series database. Similar to the `scrape_interval`, the `evaluation_interval` also defaults to one minute. + +The rules are contained in a set of rule files. Rule files include both alerting rules and recording rules, but only alerting rules result in alerts being fired after their evaluation. + +For recording rules, Prometheus runs a query, then stores it as a time series. This synthetic time series is useful for storing the results of an expensive or time-consuming query so that it can be queried more quickly in the future. + +Alerting rules are more commonly used. Whenever an alerting rule evaluates to a positive number, Prometheus fires an alert. + +The Rule file adds labels and annotations to alerts before firing them, depending on the use case: + +- Labels indicate information that identifies the alert and could affect the routing of the alert. For example, if when sending an alert about a certain container, the container ID could be used as a label. + +- Annotations denote information that doesn't affect where an alert is routed, for example, a runbook or an error message. + +## 3. How Alertmanager Works + +The Alertmanager handles alerts sent by client applications such as the Prometheus server. It takes care of the following tasks: + +- Deduplicating, grouping, and routing alerts to the correct receiver integration such as email, PagerDuty, or OpsGenie + +- Silencing and inhibition of alerts + +- Tracking alerts that fire over time + +- Sending out the status of whether an alert is currently firing, or if it is resolved + +### Alerts Forwarded by alertingDrivers + +When alertingDrivers are installed, this creates a `Service` that can be used as the receiver's URL for Teams or SMS, based on the alertingDriver's configuration. The URL in the Receiver points to the alertingDrivers; so the Alertmanager sends alert first to alertingDriver, then alertingDriver forwards or sends alert to the proper destination. + +### Routing Alerts to Receivers + +Alertmanager coordinates where alerts are sent. It allows you to group alerts based on labels and fire them based on whether certain labels are matched. One top-level route accepts all alerts. From there, Alertmanager continues routing alerts to receivers based on whether they match the conditions of the next route. + +While the Rancher UI forms only allow editing a routing tree that is two levels deep, you can configure more deeply nested routing structures by editing the Alertmanager Secret. + +### Configuring Multiple Receivers + +By editing the forms in the Rancher UI, you can set up a Receiver resource with all the information Alertmanager needs to send alerts to your notification system. + +By editing custom YAML in the Alertmanager or Receiver configuration, you can also send alerts to multiple notification systems. For more information, see the section on configuring [Receivers.](../../reference-guides/monitoring-v2-configuration/receivers.md#configuring-multiple-receivers) + +## 4. Monitoring V2 Specific Components + +Prometheus Operator introduces a set of [Custom Resource Definitions](https://github.com/prometheus-operator/prometheus-operator#customresourcedefinitions) that allow users to deploy and manage Prometheus and Alertmanager instances by creating and modifying those custom resources on a cluster. + +Prometheus Operator will automatically update your Prometheus configuration based on the live state of the resources and configuration options that are edited in the Rancher UI. + +### Resources Deployed by Default + +By default, a set of resources curated by the [kube-prometheus](https://github.com/prometheus-operator/kube-prometheus) project are deployed onto your cluster as part of installing the Rancher Monitoring Application to set up a basic Monitoring/Alerting stack. + +The resources that get deployed onto your cluster to support this solution can be found in the [`rancher-monitoring`](https://github.com/rancher/charts/tree/main/charts/rancher-monitoring) Helm chart, which closely tracks the upstream [kube-prometheus-stack](https://github.com/prometheus-community/helm-charts/tree/main/charts/kube-prometheus-stack) Helm chart maintained by the Prometheus community with certain changes tracked in the [CHANGELOG.md](https://github.com/rancher/charts/blob/main/charts/rancher-monitoring/CHANGELOG.md). + +### Default Exporters + +Monitoring V2 deploys three default exporters that provide additional metrics for Prometheus to store: + +1. `node-exporter`: exposes hardware and OS metrics for Linux hosts. For more information on `node-exporter`, refer to the [upstream documentation](https://prometheus.io/docs/guides/node-exporter/). + +1. `windows-exporter`: exposes hardware and OS metrics for Windows hosts (only deployed on Windows clusters). For more information on `windows-exporter`, refer to the [upstream documentation](https://github.com/prometheus-community/windows_exporter). + +1. `kube-state-metrics`: expose additional metrics that track the state of resources contained in the Kubernetes API (e.g., pods, workloads, etc.). For more information on `kube-state-metrics`, refer to the [upstream documentation](https://github.com/kubernetes/kube-state-metrics/tree/master/docs). + +ServiceMonitors and PodMonitors will scrape these exporters, as defined [here](#defining-what-metrics-are-scraped). Prometheus stores these metrics, and you can query the results via either Prometheus's UI or Grafana. + +See the [architecture](#1-architecture-overview) section for more information on recording rules, alerting rules, and Alertmanager. + +### Components Exposed in the Rancher UI + +When the monitoring application is installed, you will be able to edit the following components in the Rancher UI: + +| Component | Type of Component | Purpose and Common Use Cases for Editing | +|--------------|------------------------|---------------------------| +| ServiceMonitor | Custom resource | Sets up Kubernetes Services to scrape custom metrics from. Automatically updates the scrape configuration in the Prometheus custom resource. | +| PodMonitor | Custom resource | Sets up Kubernetes Pods to scrape custom metrics from. Automatically updates the scrape configuration in the Prometheus custom resource. | +| Receiver | Configuration block (part of Alertmanager) | Modifies information on where to send an alert (e.g., Slack, PagerDuty, etc.) and any necessary information to send the alert (e.g., TLS certs, proxy URLs, etc.). Automatically updates the Alertmanager custom resource. | +| Route | Configuration block (part of Alertmanager) | Modifies the routing tree that is used to filter, label, and group alerts based on labels and send them to the appropriate Receiver. Automatically updates the Alertmanager custom resource. | +| PrometheusRule | Custom resource | Defines additional queries that need to trigger alerts or define materialized views of existing series that are within Prometheus's TSDB. Automatically updates the Prometheus custom resource. | + +### PushProx + +PushProx allows Prometheus to scrape metrics across a network boundary, which prevents users from having to expose metrics ports for internal Kubernetes components on each node in a Kubernetes cluster. + +Since the metrics for Kubernetes components are generally exposed on the host network of nodes in the cluster, PushProx deploys a DaemonSet of clients that sit on the hostNetwork of each node and make an outbound connection to a single proxy that is sitting on the Kubernetes API. Prometheus can then be configured to proxy scrape requests through the proxy to each client, which allows it to scrape metrics from the internal Kubernetes components without requiring any inbound node ports to be open. + +Refer to [Scraping Metrics with PushProx](#scraping-metrics-with-pushprox) for more. + +## 5. Scraping and Exposing Metrics + +### Defining what Metrics are Scraped + +ServiceMonitors and PodMonitors define targets that are intended for Prometheus to scrape. The [Prometheus custom resource](https://github.com/prometheus-operator/prometheus-operator/blob/main/Documentation/getting-started/design.md#prometheus) tells Prometheus which ServiceMonitors or PodMonitors it should use to find out where to scrape metrics from. + +The Prometheus Operator observes the ServiceMonitors and PodMonitors. When it observes that they are created or updated, it calls the Prometheus API to update the scrape configuration in the Prometheus custom resource and keep it in sync with the scrape configuration in the ServiceMonitors or PodMonitors. This scrape configuration tells Prometheus which endpoints to scrape metrics from and how it will label the metrics from those endpoints. + +Prometheus scrapes all of the metrics defined in its scrape configuration at every `scrape_interval`, which is one minute by default. + +The scrape configuration can be viewed as part of the Prometheus custom resource that is exposed in the Rancher UI. + +### How the Prometheus Operator Sets up Metrics Scraping + +The Prometheus Deployment or StatefulSet scrapes metrics, and the configuration of Prometheus is controlled by the Prometheus custom resources. The Prometheus Operator watches for Prometheus and Alertmanager resources, and when they are created, the Prometheus Operator creates a Deployment or StatefulSet for Prometheus or Alertmanager with the user-defined configuration. + +When the Prometheus Operator observes ServiceMonitors, PodMonitors, and PrometheusRules being created, it knows that the scrape configuration needs to be updated in Prometheus. It updates Prometheus by first updating the configuration and rules files in the volumes of Prometheus's Deployment or StatefulSet. Then it calls the Prometheus API to sync the new configuration, resulting in the Prometheus Deployment or StatefulSet to be modified in place. + +### How Kubernetes Component Metrics are Exposed + +Prometheus scrapes metrics from deployments known as [exporters,](https://prometheus.io/docs/instrumenting/exporters/) which export the time series data in a format that Prometheus can ingest. In Prometheus, time series consist of streams of timestamped values belonging to the same metric and the same set of labeled dimensions. + +### Scraping Metrics with PushProx + +Certain internal Kubernetes components are scraped via a proxy deployed as part of Monitoring V2 called PushProx. For detailed information on PushProx, refer [here](#how-pushprox-works) and to the above [architecture](#1-architecture-overview) section. + +### Scraping Metrics + +The following Kubernetes components are directly scraped by Prometheus: + +- kubelet* +- ingress-nginx** +- coreDns/kubeDns +- kube-api-server + +\* You can optionally use `hardenedKubelet.enabled` to use a PushProx, but that is not the default. + +** For RKE2 clusters, ingress-nginx is deployed by default and treated as an internal Kubernetes component. + +### Scraping Metrics Based on Kubernetes Distribution + +Metrics are scraped differently based on the Kubernetes distribution. For help with terminology, refer [here](#terminology). For details, see the table below: + +
How Metrics are Exposed to Prometheus
+ +| Kubernetes Component | RKE2 | KubeADM | K3s | +|-----|-----|-----|-----|-----| +| kube-controller-manager | rke2ControllerManager.enabled | kubeAdmControllerManager.enabled | k3sServer.enabled | +| kube-scheduler | rke2Scheduler.enabled |kubeAdmScheduler.enabled | k3sServer.enabled | +| etcd | rke2Etcd.enabled | kubeAdmEtcd.enabled | Not available | +| kube-proxy | rke2Proxy.enabled | kubeAdmProxy.enabled | k3sServer.enabled | +| kubelet | Collects metrics directly exposed by kubelet | Collects metrics directly exposed by kubelet | Collects metrics directly exposed by kubelet | +| ingress-nginx* | Collects metrics directly exposed by kubelet, Exposed by rke2IngressNginx.enabled | Not available | Not available | +| coreDns/kubeDns | Collects metrics directly exposed by coreDns/kubeDns | Collects metrics directly exposed by coreDns/kubeDns | Collects metrics directly exposed by coreDns/kubeDns | +| kube-api-server | Collects metrics directly exposed by kube-api-server | Collects metrics directly exposed by kube-appi-server | Collects metrics directly exposed by kube-api-server | + +\* For RKE2 clusters, ingress-nginx is deployed by default and treated as an internal Kubernetes component. + +### Terminology + +- **kube-scheduler:** The internal Kubernetes component that uses information in the pod spec to decide on which node to run a pod. +- **kube-controller-manager:** The internal Kubernetes component that is responsible for node management (detecting if a node fails), pod replication and endpoint creation. +- **etcd:** The internal Kubernetes component that is the distributed key/value store which Kubernetes uses for persistent storage of all cluster information. +- **kube-proxy:** The internal Kubernetes component that watches the API server for pods/services changes in order to maintain the network up to date. +- **kubelet:** The internal Kubernetes component that watches the API server for pods on a node and makes sure they are running. +- **ingress-nginx:** An Ingress controller for Kubernetes using NGINX as a reverse proxy and load balancer. +- **coreDns/kubeDns:** The internal Kubernetes component responsible for DNS. +- **kube-api-server:** The main internal Kubernetes component that is responsible for exposing APIs for the other master components. diff --git a/versioned_docs/version-2.14/integrations-in-rancher/monitoring-and-alerting/monitoring-and-alerting.md b/versioned_docs/version-2.14/integrations-in-rancher/monitoring-and-alerting/monitoring-and-alerting.md new file mode 100644 index 00000000000..75358ecccf6 --- /dev/null +++ b/versioned_docs/version-2.14/integrations-in-rancher/monitoring-and-alerting/monitoring-and-alerting.md @@ -0,0 +1,102 @@ +--- +title: Monitoring and Alerting +description: Prometheus lets you view metrics from your different Rancher and Kubernetes objects. Learn about the scope of monitoring and how to enable cluster monitoring +--- + + + + + +The `rancher-monitoring` application can quickly deploy leading open-source monitoring and alerting solutions onto your cluster. + +Introduced in Rancher v2.5, the application is powered by [Prometheus](https://prometheus.io/), [Grafana](https://grafana.com/grafana/), [Alertmanager](https://prometheus.io/docs/alerting/latest/alertmanager/), the [Prometheus Operator](https://github.com/prometheus-operator/prometheus-operator), and the [Prometheus adapter.](https://github.com/DirectXMan12/k8s-prometheus-adapter) + +For information on V1 monitoring and alerting, available in Rancher v2.2 up to v2.4, please see the Rancher v2.0—v2.4 docs on [cluster monitoring](https://github.com/rancher/rancher-docs/tree/main/archived_docs/en/version-2.0-2.4/explanations/integrations-in-rancher/cluster-monitoring/cluster-monitoring.md), [alerting](https://github.com/rancher/rancher-docs/tree/main/archived_docs/en/version-2.0-2.4/explanations/integrations-in-rancher/cluster-alerts/cluster-alerts.md), [notifiers](https://github.com/rancher/rancher-docs/tree/main/archived_docs/en/version-2.0-2.4/explanations/integrations-in-rancher/notifiers.md) and other [tools](https://github.com/rancher/rancher-docs/tree/main/archived_docs/en/version-2.0-2.4/reference-guides/rancher-project-tools/rancher-project-tools.md). + +Using the `rancher-monitoring` application, you can quickly deploy leading open-source monitoring and alerting solutions onto your cluster. + +## Features + +Prometheus lets you view metrics from your Rancher and Kubernetes objects. Using timestamps, Prometheus lets you query and view these metrics in easy-to-read graphs and visuals, either through the Rancher UI or Grafana, which is an analytics viewing platform deployed along with Prometheus. + +By viewing data that Prometheus scrapes from your cluster control plane, nodes, and deployments, you can stay on top of everything happening in your cluster. You can then use these analytics to better run your organization: stop system emergencies before they start, develop maintenance strategies, or restore crashed servers. + +The monitoring application: + +- Monitors the state and processes of your cluster nodes, Kubernetes components, and software deployments. +- Defines alerts based on metrics collected via Prometheus. +- Creates custom Grafana dashboards. +- Configures alert-based notifications via email, Slack, PagerDuty, etc. using Prometheus Alertmanager. +- Defines precomputed, frequently needed or computationally expensive expressions as new time series based on metrics collected via Prometheus. +- Exposes collected metrics from Prometheus to the Kubernetes Custom Metrics API via Prometheus Adapter for use in HPA. + +See [How Monitoring Works](how-monitoring-works.md) for an explanation of how the monitoring components work together. + +## Default Components and Deployments + +### Built-in Dashboards + +By default, the monitoring application deploys Grafana dashboards (curated by the [kube-prometheus](https://github.com/prometheus-operator/kube-prometheus) project) onto a cluster. + +It also deploys an Alertmanager UI and a Prometheus UI. For more information about these tools, see [Built-in Dashboards.](built-in-dashboards.md) +### Default Metrics Exporters + +By default, Rancher Monitoring deploys exporters (such as [node-exporter](https://github.com/prometheus/node_exporter) and [kube-state-metrics](https://github.com/kubernetes/kube-state-metrics)). + +These default exporters automatically scrape metrics for CPU and memory from all components of your Kubernetes cluster, including your workloads. + +### Default Alerts + +The monitoring application deploys some alerts by default. To see the default alerts, go to the [Alertmanager UI](built-in-dashboards.md#alertmanager-ui) and click **Expand all groups.** + +### Components Exposed in the Rancher UI + +For a list of monitoring components exposed in the Rancher UI, along with common use cases for editing them, see [this section.](how-monitoring-works.md#components-exposed-in-the-rancher-ui) + +## Role-based Access Control + +For more information on configuring access to monitoring, see [this page.](rbac-for-monitoring.md) + +:::note + +Rancher and Project read permissions don't necessarily apply to monitoring resources. See [monitoring-ui-view](rbac-for-monitoring.md#additional-monitoring-clusterroles) for more details. + +::: + +## Guides + +- [Enable monitoring](../../how-to-guides/advanced-user-guides/monitoring-alerting-guides/enable-monitoring.md) +- [Uninstall monitoring](../../how-to-guides/advanced-user-guides/monitoring-alerting-guides/uninstall-monitoring.md) +- [Monitoring workloads](../../how-to-guides/advanced-user-guides/monitoring-alerting-guides/set-up-monitoring-for-workloads.md) +- [Customizing Grafana dashboards](../../how-to-guides/advanced-user-guides/monitoring-alerting-guides/customize-grafana-dashboard.md) +- [Persistent Grafana dashboards](../../how-to-guides/advanced-user-guides/monitoring-alerting-guides/create-persistent-grafana-dashboard.md) +- [Debugging high memory usage](../../how-to-guides/advanced-user-guides/monitoring-alerting-guides/debug-high-memory-usage.md) + +## Configuration + +### Configuring Monitoring Resources in Rancher + +The configuration reference assumes familiarity with how monitoring components work together. For more information, see [How Monitoring Works.](how-monitoring-works.md) + +- [ServiceMonitor and PodMonitor](../../reference-guides/monitoring-v2-configuration/servicemonitors-and-podmonitors.md) +- [Receiver](../../reference-guides/monitoring-v2-configuration/receivers.md) +- [Route](../../reference-guides/monitoring-v2-configuration/routes.md) +- [PrometheusRule](../../how-to-guides/advanced-user-guides/monitoring-v2-configuration-guides/advanced-configuration/prometheusrules.md) +- [Prometheus](../../how-to-guides/advanced-user-guides/monitoring-v2-configuration-guides/advanced-configuration/prometheus.md) +- [Alertmanager](../../how-to-guides/advanced-user-guides/monitoring-v2-configuration-guides/advanced-configuration/alertmanager.md) + +### Configuring Helm Chart Options + +For more information on `rancher-monitoring` chart options, including options to set resource limits and requests, see [Helm Chart Options](../../reference-guides/monitoring-v2-configuration/helm-chart-options.md). + +## Windows Cluster Support + +To be able to fully deploy Monitoring V2 for Windows, all of your Windows hosts must have a minimum [wins](https://github.com/rancher/wins) version of v0.1.0. + +For more details on how to upgrade wins on existing Windows hosts, see [Windows cluster support for Monitoring V2.](windows-support.md). + +## Known Issues + +There is a [known issue](https://github.com/rancher/rancher/issues/28787#issuecomment-693611821) that K3s clusters require more than the allotted default memory. If you enable monitoring on a K3s cluster, set `prometheus.prometheusSpec.resources.memory.limit` to 2500 Mi and `prometheus.prometheusSpec.resources.memory.request` to 1750 Mi. + +See [Debugging High Memory Usage](../../how-to-guides/advanced-user-guides/monitoring-alerting-guides/debug-high-memory-usage.md) for advice and recommendations. diff --git a/versioned_docs/version-2.14/integrations-in-rancher/monitoring-and-alerting/promql-expressions.md b/versioned_docs/version-2.14/integrations-in-rancher/monitoring-and-alerting/promql-expressions.md new file mode 100644 index 00000000000..0ea6b134300 --- /dev/null +++ b/versioned_docs/version-2.14/integrations-in-rancher/monitoring-and-alerting/promql-expressions.md @@ -0,0 +1,369 @@ +--- +title: PromQL Expression Reference +--- + + + + + +The PromQL expressions in this doc can be used to configure alerts. + +For more information about querying the Prometheus time series database, refer to the official [Prometheus documentation.](https://prometheus.io/docs/prometheus/latest/querying/basics/) + + +## Cluster Metrics + +### Cluster CPU Utilization + +| Catalog | Expression | +| --- | --- | +| Detail | `1 - (avg(irate(node_cpu_seconds_total{mode="idle"}[5m])) by (instance))` | +| Summary | `1 - (avg(irate(node_cpu_seconds_total{mode="idle"}[5m])))` | + +### Cluster Load Average + +| Catalog | Expression | +| --- | --- | +| Detail |
load1`sum(node_load1) by (instance) / count(node_cpu_seconds_total{mode="system"}) by (instance)`
load5`sum(node_load5) by (instance) / count(node_cpu_seconds_total{mode="system"}) by (instance)`
load15`sum(node_load15) by (instance) / count(node_cpu_seconds_total{mode="system"}) by (instance)`
| +| Summary |
load1`sum(node_load1) by (instance) / count(node_cpu_seconds_total{mode="system"})`
load5`sum(node_load5) by (instance) / count(node_cpu_seconds_total{mode="system"})`
load15`sum(node_load15) by (instance) / count(node_cpu_seconds_total{mode="system"})`
| + +### Cluster Memory Utilization + +| Catalog | Expression | +| --- | --- | +| Detail | `1 - sum(node_memory_MemAvailable_bytes) by (instance) / sum(node_memory_MemTotal_bytes) by (instance)` | +| Summary | `1 - sum(node_memory_MemAvailable_bytes) / sum(node_memory_MemTotal_bytes)` | + +### Cluster Disk Utilization + +| Catalog | Expression | +| --- | --- | +| Detail | `(sum(node_filesystem_size_bytes{device!="rootfs"}) by (instance) - sum(node_filesystem_free_bytes{device!="rootfs"}) by (instance)) / sum(node_filesystem_size_bytes{device!="rootfs"}) by (instance)` | +| Summary | `(sum(node_filesystem_size_bytes{device!="rootfs"}) - sum(node_filesystem_free_bytes{device!="rootfs"})) / sum(node_filesystem_size_bytes{device!="rootfs"})` | + +### Cluster Disk I/O + +| Catalog | Expression | +| --- | --- | +| Detail |
read`sum(rate(node_disk_read_bytes_total[5m])) by (instance)`
written`sum(rate(node_disk_written_bytes_total[5m])) by (instance)`
| +| Summary |
read`sum(rate(node_disk_read_bytes_total[5m]))`
written`sum(rate(node_disk_written_bytes_total[5m]))`
| + +### Cluster Network Packets + +| Catalog | Expression | +| --- | --- | +| Detail |
receive-droppedsum(rate(node_network_receive_drop_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*"}[5m])) by (instance)
receive-errssum(rate(node_network_receive_errs_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*"}[5m])) by (instance)
receive-packetssum(rate(node_network_receive_packets_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*"}[5m])) by (instance)
transmit-droppedsum(rate(node_network_transmit_drop_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*"}[5m])) by (instance)
transmit-errssum(rate(node_network_transmit_errs_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*"}[5m])) by (instance)
transmit-packetssum(rate(node_network_transmit_packets_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*"}[5m])) by (instance)
| +| Summary |
receive-droppedsum(rate(node_network_receive_drop_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*"}[5m]))
receive-errssum(rate(node_network_receive_errs_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*"}[5m]))
receive-packetssum(rate(node_network_receive_packets_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*"}[5m]))
transmit-droppedsum(rate(node_network_transmit_drop_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*"}[5m]))
transmit-errssum(rate(node_network_transmit_errs_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*"}[5m]))
transmit-packetssum(rate(node_network_transmit_packets_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*"}[5m]))
| + +### Cluster Network I/O + +| Catalog | Expression | +| --- | --- | +| Detail |
receivesum(rate(node_network_receive_bytes_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*"}[5m])) by (instance)
transmitsum(rate(node_network_transmit_bytes_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*"}[5m])) by (instance)
| +| Summary |
receivesum(rate(node_network_receive_bytes_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*"}[5m]))
transmitsum(rate(node_network_transmit_bytes_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*"}[5m]))
| + +## Node Metrics + +### Node CPU Utilization + +| Catalog | Expression | +| --- | --- | +| Detail | `avg(irate(node_cpu_seconds_total{mode!="idle", instance=~"$instance"}[5m])) by (mode)` | +| Summary | `1 - (avg(irate(node_cpu_seconds_total{mode="idle", instance=~"$instance"}[5m])))` | + +### Node Load Average + +| Catalog | Expression | +| --- | --- | +| Detail |
load1`sum(node_load1{instance=~"$instance"}) / count(node_cpu_seconds_total{mode="system",instance=~"$instance"})`
load5`sum(node_load5{instance=~"$instance"}) / count(node_cpu_seconds_total{mode="system",instance=~"$instance"})`
load15`sum(node_load15{instance=~"$instance"}) / count(node_cpu_seconds_total{mode="system",instance=~"$instance"})`
| +| Summary |
load1`sum(node_load1{instance=~"$instance"}) / count(node_cpu_seconds_total{mode="system",instance=~"$instance"})`
load5`sum(node_load5{instance=~"$instance"}) / count(node_cpu_seconds_total{mode="system",instance=~"$instance"})`
load15`sum(node_load15{instance=~"$instance"}) / count(node_cpu_seconds_total{mode="system",instance=~"$instance"})`
| + +### Node Memory Utilization + +| Catalog | Expression | +| --- | --- | +| Detail | `1 - sum(node_memory_MemAvailable_bytes{instance=~"$instance"}) / sum(node_memory_MemTotal_bytes{instance=~"$instance"})` | +| Summary | `1 - sum(node_memory_MemAvailable_bytes{instance=~"$instance"}) / sum(node_memory_MemTotal_bytes{instance=~"$instance"}) ` | + +### Node Disk Utilization + +| Catalog | Expression | +| --- | --- | +| Detail | `(sum(node_filesystem_size_bytes{device!="rootfs",instance=~"$instance"}) by (device) - sum(node_filesystem_free_bytes{device!="rootfs",instance=~"$instance"}) by (device)) / sum(node_filesystem_size_bytes{device!="rootfs",instance=~"$instance"}) by (device)` | +| Summary | `(sum(node_filesystem_size_bytes{device!="rootfs",instance=~"$instance"}) - sum(node_filesystem_free_bytes{device!="rootfs",instance=~"$instance"})) / sum(node_filesystem_size_bytes{device!="rootfs",instance=~"$instance"})` | + +### Node Disk I/O + +| Catalog | Expression | +| --- | --- | +| Detail |
read`sum(rate(node_disk_read_bytes_total{instance=~"$instance"}[5m]))`
written`sum(rate(node_disk_written_bytes_total{instance=~"$instance"}[5m]))`
| +| Summary |
read`sum(rate(node_disk_read_bytes_total{instance=~"$instance"}[5m]))`
written`sum(rate(node_disk_written_bytes_total{instance=~"$instance"}[5m]))`
| + +### Node Network Packets + +| Catalog | Expression | +| --- | --- | +| Detail |
receive-droppedsum(rate(node_network_receive_drop_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*",instance=~"$instance"}[5m])) by (device)
receive-errssum(rate(node_network_receive_errs_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*",instance=~"$instance"}[5m])) by (device)
receive-packetssum(rate(node_network_receive_packets_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*",instance=~"$instance"}[5m])) by (device)
transmit-droppedsum(rate(node_network_transmit_drop_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*",instance=~"$instance"}[5m])) by (device)
transmit-errssum(rate(node_network_transmit_errs_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*",instance=~"$instance"}[5m])) by (device)
transmit-packetssum(rate(node_network_transmit_packets_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*",instance=~"$instance"}[5m])) by (device)
| +| Summary |
receive-droppedsum(rate(node_network_receive_drop_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*",instance=~"$instance"}[5m]))
receive-errssum(rate(node_network_receive_errs_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*",instance=~"$instance"}[5m]))
receive-packetssum(rate(node_network_receive_packets_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*",instance=~"$instance"}[5m]))
transmit-droppedsum(rate(node_network_transmit_drop_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*",instance=~"$instance"}[5m]))
transmit-errssum(rate(node_network_transmit_errs_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*",instance=~"$instance"}[5m]))
transmit-packetssum(rate(node_network_transmit_packets_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*",instance=~"$instance"}[5m]))
| + +### Node Network I/O + +| Catalog | Expression | +| --- | --- | +| Detail |
receivesum(rate(node_network_receive_bytes_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*",instance=~"$instance"}[5m])) by (device)
transmitsum(rate(node_network_transmit_bytes_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*",instance=~"$instance"}[5m])) by (device)
| +| Summary |
receivesum(rate(node_network_receive_bytes_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*",instance=~"$instance"}[5m]))
transmitsum(rate(node_network_transmit_bytes_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*",instance=~"$instance"}[5m]))
| + +## Etcd Metrics + +### Etcd Has a Leader + +`max(etcd_server_has_leader)` + +### Number of Times the Leader Changes + +`max(etcd_server_leader_changes_seen_total)` + +### Number of Failed Proposals + +`sum(etcd_server_proposals_failed_total)` + +### GRPC Client Traffic + +| Catalog | Expression | +| --- | --- | +| Detail |
in`sum(rate(etcd_network_client_grpc_received_bytes_total[5m])) by (instance)`
out`sum(rate(etcd_network_client_grpc_sent_bytes_total[5m])) by (instance)`
| +| Summary |
in`sum(rate(etcd_network_client_grpc_received_bytes_total[5m]))`
out`sum(rate(etcd_network_client_grpc_sent_bytes_total[5m]))`
| + +### Peer Traffic + +| Catalog | Expression | +| --- | --- | +| Detail |
in`sum(rate(etcd_network_peer_received_bytes_total[5m])) by (instance)`
out`sum(rate(etcd_network_peer_sent_bytes_total[5m])) by (instance)`
| +| Summary |
in`sum(rate(etcd_network_peer_received_bytes_total[5m]))`
out`sum(rate(etcd_network_peer_sent_bytes_total[5m]))`
| + +### DB Size + +| Catalog | Expression | +| --- | --- | +| Detail | `sum(etcd_debugging_mvcc_db_total_size_in_bytes) by (instance)` | +| Summary | `sum(etcd_debugging_mvcc_db_total_size_in_bytes)` | + +### Active Streams + +| Catalog | Expression | +| --- | --- | +| Detail |
lease-watch`sum(grpc_server_started_total{grpc_service="etcdserverpb.Lease",grpc_type="bidi_stream"}) by (instance) - sum(grpc_server_handled_total{grpc_service="etcdserverpb.Lease",grpc_type="bidi_stream"}) by (instance)`
watch`sum(grpc_server_started_total{grpc_service="etcdserverpb.Watch",grpc_type="bidi_stream"}) by (instance) - sum(grpc_server_handled_total{grpc_service="etcdserverpb.Watch",grpc_type="bidi_stream"}) by (instance)`
| +| Summary |
lease-watch`sum(grpc_server_started_total{grpc_service="etcdserverpb.Lease",grpc_type="bidi_stream"}) - sum(grpc_server_handled_total{grpc_service="etcdserverpb.Lease",grpc_type="bidi_stream"})`
watch`sum(grpc_server_started_total{grpc_service="etcdserverpb.Watch",grpc_type="bidi_stream"}) - sum(grpc_server_handled_total{grpc_service="etcdserverpb.Watch",grpc_type="bidi_stream"})`
| + +### Raft Proposals + +| Catalog | Expression | +| --- | --- | +| Detail |
applied`sum(increase(etcd_server_proposals_applied_total[5m])) by (instance)`
committed`sum(increase(etcd_server_proposals_committed_total[5m])) by (instance)`
pending`sum(increase(etcd_server_proposals_pending[5m])) by (instance)`
failed`sum(increase(etcd_server_proposals_failed_total[5m])) by (instance)`
| +| Summary |
applied`sum(increase(etcd_server_proposals_applied_total[5m]))`
committed`sum(increase(etcd_server_proposals_committed_total[5m]))`
pending`sum(increase(etcd_server_proposals_pending[5m]))`
failed`sum(increase(etcd_server_proposals_failed_total[5m]))`
| + +### RPC Rate + +| Catalog | Expression | +| --- | --- | +| Detail |
total`sum(rate(grpc_server_started_total{grpc_type="unary"}[5m])) by (instance)`
fail`sum(rate(grpc_server_handled_total{grpc_type="unary",grpc_code!="OK"}[5m])) by (instance)`
| +| Summary |
total`sum(rate(grpc_server_started_total{grpc_type="unary"}[5m]))`
fail`sum(rate(grpc_server_handled_total{grpc_type="unary",grpc_code!="OK"}[5m]))`
| + +### Disk Operations + +| Catalog | Expression | +| --- | --- | +| Detail |
commit-called-by-backend`sum(rate(etcd_disk_backend_commit_duration_seconds_sum[1m])) by (instance)`
fsync-called-by-wal`sum(rate(etcd_disk_wal_fsync_duration_seconds_sum[1m])) by (instance)`
| +| Summary |
commit-called-by-backend`sum(rate(etcd_disk_backend_commit_duration_seconds_sum[1m]))`
fsync-called-by-wal`sum(rate(etcd_disk_wal_fsync_duration_seconds_sum[1m]))`
| + +### Disk Sync Duration + +| Catalog | Expression | +| --- | --- | +| Detail |
wal`histogram_quantile(0.99, sum(rate(etcd_disk_wal_fsync_duration_seconds_bucket[5m])) by (instance, le))`
db`histogram_quantile(0.99, sum(rate(etcd_disk_backend_commit_duration_seconds_bucket[5m])) by (instance, le))`
| +| Summary |
wal`sum(histogram_quantile(0.99, sum(rate(etcd_disk_wal_fsync_duration_seconds_bucket[5m])) by (instance, le)))`
db`sum(histogram_quantile(0.99, sum(rate(etcd_disk_backend_commit_duration_seconds_bucket[5m])) by (instance, le)))`
| + +## Kubernetes Components Metrics + +### API Server Request Latency + +| Catalog | Expression | +| --- | --- | +| Detail | `avg(apiserver_request_latencies_sum / apiserver_request_latencies_count) by (instance, verb) /1e+06` | +| Summary | `avg(apiserver_request_latencies_sum / apiserver_request_latencies_count) by (instance) /1e+06` | + +### API Server Request Rate + +| Catalog | Expression | +| --- | --- | +| Detail | `sum(rate(apiserver_request_count[5m])) by (instance, code)` | +| Summary | `sum(rate(apiserver_request_count[5m])) by (instance)` | + +### Scheduling Failed Pods + +| Catalog | Expression | +| --- | --- | +| Detail | `sum(kube_pod_status_scheduled{condition="false"})` | +| Summary | `sum(kube_pod_status_scheduled{condition="false"})` | + +### Controller Manager Queue Depth + +| Catalog | Expression | +| --- | --- | +| Detail |
volumes`sum(volumes_depth) by instance`
deployment`sum(deployment_depth) by instance`
replicaset`sum(replicaset_depth) by instance`
service`sum(service_depth) by instance`
serviceaccount`sum(serviceaccount_depth) by instance`
endpoint`sum(endpoint_depth) by instance`
daemonset`sum(daemonset_depth) by instance`
statefulset`sum(statefulset_depth) by instance`
replicationmanager`sum(replicationmanager_depth) by instance`
| +| Summary |
volumes`sum(volumes_depth)`
deployment`sum(deployment_depth)`
replicaset`sum(replicaset_depth)`
service`sum(service_depth)`
serviceaccount`sum(serviceaccount_depth)`
endpoint`sum(endpoint_depth)`
daemonset`sum(daemonset_depth)`
statefulset`sum(statefulset_depth)`
replicationmanager`sum(replicationmanager_depth)`
| + +### Scheduler E2E Scheduling Latency + +| Catalog | Expression | +| --- | --- | +| Detail | `histogram_quantile(0.99, sum(scheduler_e2e_scheduling_latency_microseconds_bucket) by (le, instance)) / 1e+06` | +| Summary | `sum(histogram_quantile(0.99, sum(scheduler_e2e_scheduling_latency_microseconds_bucket) by (le, instance)) / 1e+06)` | + +### Scheduler Preemption Attempts + +| Catalog | Expression | +| --- | --- | +| Detail | `sum(rate(scheduler_total_preemption_attempts[5m])) by (instance)` | +| Summary | `sum(rate(scheduler_total_preemption_attempts[5m]))` | + +### Ingress Controller Connections + +| Catalog | Expression | +| --- | --- | +| Detail |
reading`sum(nginx_ingress_controller_nginx_process_connections{state="reading"}) by (instance)`
waiting`sum(nginx_ingress_controller_nginx_process_connections{state="waiting"}) by (instance)`
writing`sum(nginx_ingress_controller_nginx_process_connections{state="writing"}) by (instance)`
accepted`sum(ceil(increase(nginx_ingress_controller_nginx_process_connections_total{state="accepted"}[5m]))) by (instance)`
active`sum(ceil(increase(nginx_ingress_controller_nginx_process_connections_total{state="active"}[5m]))) by (instance)`
handled`sum(ceil(increase(nginx_ingress_controller_nginx_process_connections_total{state="handled"}[5m]))) by (instance)`
| +| Summary |
reading`sum(nginx_ingress_controller_nginx_process_connections{state="reading"})`
waiting`sum(nginx_ingress_controller_nginx_process_connections{state="waiting"})`
writing`sum(nginx_ingress_controller_nginx_process_connections{state="writing"})`
accepted`sum(ceil(increase(nginx_ingress_controller_nginx_process_connections_total{state="accepted"}[5m])))`
active`sum(ceil(increase(nginx_ingress_controller_nginx_process_connections_total{state="active"}[5m])))`
handled`sum(ceil(increase(nginx_ingress_controller_nginx_process_connections_total{state="handled"}[5m])))`
| + +### Ingress Controller Request Process Time + +| Catalog | Expression | +| --- | --- | +| Detail | `topk(10, histogram_quantile(0.95,sum by (le, host, path)(rate(nginx_ingress_controller_request_duration_seconds_bucket{host!="_"}[5m]))))` | +| Summary | `topk(10, histogram_quantile(0.95,sum by (le, host)(rate(nginx_ingress_controller_request_duration_seconds_bucket{host!="_"}[5m]))))` | + +## Rancher Logging Metrics + + +### Fluentd Buffer Queue Rate + +| Catalog | Expression | +| --- | --- | +| Detail | `sum(rate(fluentd_output_status_buffer_queue_length[5m])) by (instance)` | +| Summary | `sum(rate(fluentd_output_status_buffer_queue_length[5m]))` | + +### Fluentd Input Rate + +| Catalog | Expression | +| --- | --- | +| Detail | `sum(rate(fluentd_input_status_num_records_total[5m])) by (instance)` | +| Summary | `sum(rate(fluentd_input_status_num_records_total[5m]))` | + +### Fluentd Output Errors Rate + +| Catalog | Expression | +| --- | --- | +| Detail | `sum(rate(fluentd_output_status_num_errors[5m])) by (type)` | +| Summary | `sum(rate(fluentd_output_status_num_errors[5m]))` | + +### Fluentd Output Rate + +| Catalog | Expression | +| --- | --- | +| Detail | `sum(rate(fluentd_output_status_num_records_total[5m])) by (instance)` | +| Summary | `sum(rate(fluentd_output_status_num_records_total[5m]))` | + +## Workload Metrics + +### Workload CPU Utilization + +| Catalog | Expression | +| --- | --- | +| Detail |
cfs throttled seconds`sum(rate(container_cpu_cfs_throttled_seconds_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m])) by (pod_name)`
user seconds`sum(rate(container_cpu_user_seconds_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m])) by (pod_name)`
system seconds`sum(rate(container_cpu_system_seconds_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m])) by (pod_name)`
usage seconds`sum(rate(container_cpu_usage_seconds_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m])) by (pod_name)`
| +| Summary |
cfs throttled seconds`sum(rate(container_cpu_cfs_throttled_seconds_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m]))`
user seconds`sum(rate(container_cpu_user_seconds_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m]))`
system seconds`sum(rate(container_cpu_system_seconds_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m]))`
usage seconds`sum(rate(container_cpu_usage_seconds_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m]))`
| + +### Workload Memory Utilization + +| Catalog | Expression | +| --- | --- | +| Detail | `sum(container_memory_working_set_bytes{namespace="$namespace",pod_name=~"$podName", container_name!=""}) by (pod_name)` | +| Summary | `sum(container_memory_working_set_bytes{namespace="$namespace",pod_name=~"$podName", container_name!=""})` | + +### Workload Network Packets + +| Catalog | Expression | +| --- | --- | +| Detail |
receive-packets`sum(rate(container_network_receive_packets_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m])) by (pod_name)`
receive-dropped`sum(rate(container_network_receive_packets_dropped_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m])) by (pod_name)`
receive-errors`sum(rate(container_network_receive_errors_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m])) by (pod_name)`
transmit-packets`sum(rate(container_network_transmit_packets_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m])) by (pod_name)`
transmit-dropped`sum(rate(container_network_transmit_packets_dropped_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m])) by (pod_name)`
transmit-errors`sum(rate(container_network_transmit_errors_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m])) by (pod_name)`
| +| Summary |
receive-packets`sum(rate(container_network_receive_packets_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m]))`
receive-dropped`sum(rate(container_network_receive_packets_dropped_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m]))`
receive-errors`sum(rate(container_network_receive_errors_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m]))`
transmit-packets`sum(rate(container_network_transmit_packets_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m]))`
transmit-dropped`sum(rate(container_network_transmit_packets_dropped_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m]))`
transmit-errors`sum(rate(container_network_transmit_errors_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m]))`
| + +### Workload Network I/O + +| Catalog | Expression | +| --- | --- | +| Detail |
receive`sum(rate(container_network_receive_bytes_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m])) by (pod_name)`
transmit`sum(rate(container_network_transmit_bytes_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m])) by (pod_name)`
| +| Summary |
receive`sum(rate(container_network_receive_bytes_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m]))`
transmit`sum(rate(container_network_transmit_bytes_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m]))`
| + +### Workload Disk I/O + +| Catalog | Expression | +| --- | --- | +| Detail |
read`sum(rate(container_fs_reads_bytes_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m])) by (pod_name)`
write`sum(rate(container_fs_writes_bytes_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m])) by (pod_name)`
| +| Summary |
read`sum(rate(container_fs_reads_bytes_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m]))`
write`sum(rate(container_fs_writes_bytes_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m]))`
| + +## Pod Metrics + +### Pod CPU Utilization + +| Catalog | Expression | +| --- | --- | +| Detail |
cfs throttled seconds`sum(rate(container_cpu_cfs_throttled_seconds_total{container_name!="POD",namespace="$namespace",pod_name="$podName", container_name!=""}[5m])) by (container_name)`
usage seconds`sum(rate(container_cpu_usage_seconds_total{container_name!="POD",namespace="$namespace",pod_name="$podName", container_name!=""}[5m])) by (container_name)`
system seconds`sum(rate(container_cpu_system_seconds_total{container_name!="POD",namespace="$namespace",pod_name="$podName", container_name!=""}[5m])) by (container_name)`
user seconds`sum(rate(container_cpu_user_seconds_total{container_name!="POD",namespace="$namespace",pod_name="$podName", container_name!=""}[5m])) by (container_name)`
| +| Summary |
cfs throttled seconds`sum(rate(container_cpu_cfs_throttled_seconds_total{container_name!="POD",namespace="$namespace",pod_name="$podName", container_name!=""}[5m]))`
usage seconds`sum(rate(container_cpu_usage_seconds_total{container_name!="POD",namespace="$namespace",pod_name="$podName", container_name!=""}[5m]))`
system seconds`sum(rate(container_cpu_system_seconds_total{container_name!="POD",namespace="$namespace",pod_name="$podName", container_name!=""}[5m]))`
user seconds`sum(rate(container_cpu_user_seconds_total{container_name!="POD",namespace="$namespace",pod_name="$podName", container_name!=""}[5m]))`
| + +### Pod Memory Utilization + +| Catalog | Expression | +| --- | --- | +| Detail | `sum(container_memory_working_set_bytes{container_name!="POD",namespace="$namespace",pod_name="$podName",container_name!=""}) by (container_name)` | +| Summary | `sum(container_memory_working_set_bytes{container_name!="POD",namespace="$namespace",pod_name="$podName",container_name!=""})` | + +### Pod Network Packets + +| Catalog | Expression | +| --- | --- | +| Detail |
receive-packets`sum(rate(container_network_receive_packets_total{namespace="$namespace",pod_name="$podName",container_name!=""}[5m]))`
receive-dropped`sum(rate(container_network_receive_packets_dropped_total{namespace="$namespace",pod_name="$podName",container_name!=""}[5m]))`
receive-errors`sum(rate(container_network_receive_errors_total{namespace="$namespace",pod_name="$podName",container_name!=""}[5m]))`
transmit-packets`sum(rate(container_network_transmit_packets_total{namespace="$namespace",pod_name="$podName",container_name!=""}[5m]))`
transmit-dropped`sum(rate(container_network_transmit_packets_dropped_total{namespace="$namespace",pod_name="$podName",container_name!=""}[5m]))`
transmit-errors`sum(rate(container_network_transmit_errors_total{namespace="$namespace",pod_name="$podName",container_name!=""}[5m]))`
| +| Summary |
receive-packets`sum(rate(container_network_receive_packets_total{namespace="$namespace",pod_name="$podName",container_name!=""}[5m]))`
receive-dropped`sum(rate(container_network_receive_packets_dropped_total{namespace="$namespace",pod_name="$podName",container_name!=""}[5m]))`
receive-errors`sum(rate(container_network_receive_errors_total{namespace="$namespace",pod_name="$podName",container_name!=""}[5m]))`
transmit-packets`sum(rate(container_network_transmit_packets_total{namespace="$namespace",pod_name="$podName",container_name!=""}[5m]))`
transmit-dropped`sum(rate(container_network_transmit_packets_dropped_total{namespace="$namespace",pod_name="$podName",container_name!=""}[5m]))`
transmit-errors`sum(rate(container_network_transmit_errors_total{namespace="$namespace",pod_name="$podName",container_name!=""}[5m]))`
| + +### Pod Network I/O + +| Catalog | Expression | +| --- | --- | +| Detail |
receive`sum(rate(container_network_receive_bytes_total{namespace="$namespace",pod_name="$podName",container_name!=""}[5m]))`
transmit`sum(rate(container_network_transmit_bytes_total{namespace="$namespace",pod_name="$podName",container_name!=""}[5m]))`
| +| Summary |
receive`sum(rate(container_network_receive_bytes_total{namespace="$namespace",pod_name="$podName",container_name!=""}[5m]))`
transmit`sum(rate(container_network_transmit_bytes_total{namespace="$namespace",pod_name="$podName",container_name!=""}[5m]))`
| + +### Pod Disk I/O + +| Catalog | Expression | +| --- | --- | +| Detail |
read`sum(rate(container_fs_reads_bytes_total{namespace="$namespace",pod_name="$podName",container_name!=""}[5m])) by (container_name)`
write`sum(rate(container_fs_writes_bytes_total{namespace="$namespace",pod_name="$podName",container_name!=""}[5m])) by (container_name)`
| +| Summary |
read`sum(rate(container_fs_reads_bytes_total{namespace="$namespace",pod_name="$podName",container_name!=""}[5m]))`
write`sum(rate(container_fs_writes_bytes_total{namespace="$namespace",pod_name="$podName",container_name!=""}[5m]))`
| + +## Container Metrics + +### Container CPU Utilization + +| Catalog | Expression | +| --- | --- | +| cfs throttled seconds | `sum(rate(container_cpu_cfs_throttled_seconds_total{namespace="$namespace",pod_name="$podName",container_name="$containerName"}[5m]))` | +| usage seconds | `sum(rate(container_cpu_usage_seconds_total{namespace="$namespace",pod_name="$podName",container_name="$containerName"}[5m]))` | +| system seconds | `sum(rate(container_cpu_system_seconds_total{namespace="$namespace",pod_name="$podName",container_name="$containerName"}[5m]))` | +| user seconds | `sum(rate(container_cpu_user_seconds_total{namespace="$namespace",pod_name="$podName",container_name="$containerName"}[5m]))` | + +### Container Memory Utilization + +`sum(container_memory_working_set_bytes{namespace="$namespace",pod_name="$podName",container_name="$containerName"})` + +### Container Disk I/O + +| Catalog | Expression | +| --- | --- | +| read | `sum(rate(container_fs_reads_bytes_total{namespace="$namespace",pod_name="$podName",container_name="$containerName"}[5m]))` | +| write | `sum(rate(container_fs_writes_bytes_total{namespace="$namespace",pod_name="$podName",container_name="$containerName"}[5m]))` | diff --git a/versioned_docs/version-2.14/integrations-in-rancher/monitoring-and-alerting/rbac-for-monitoring.md b/versioned_docs/version-2.14/integrations-in-rancher/monitoring-and-alerting/rbac-for-monitoring.md new file mode 100644 index 00000000000..101e1611b37 --- /dev/null +++ b/versioned_docs/version-2.14/integrations-in-rancher/monitoring-and-alerting/rbac-for-monitoring.md @@ -0,0 +1,266 @@ +--- +title: Role-based Access Control +--- + + + + + +This section describes the expectations for RBAC for Rancher Monitoring. + + +## Cluster Admins + +By default, only those with the cluster-admin `ClusterRole` should be able to: + +- Install the `rancher-monitoring` App onto a cluster and all other relevant configuration performed on the chart deploy + - e.g. whether default dashboards are created, what exporters are deployed onto the cluster to collect metrics, etc. +- Create / modify / delete Prometheus deployments in the cluster via Prometheus CRs +- Create / modify / delete Alertmanager deployments in the cluster via Alertmanager CRs +- Persist new Grafana dashboards or datasources via creating ConfigMaps in the appropriate namespace +- Expose certain Prometheus metrics to the k8s Custom Metrics API for HPA via a Secret in the `cattle-monitoring-system` namespace + +## Users with Kubernetes ClusterRole-based Permissions + +The `rancher-monitoring` chart installs the following three `ClusterRoles`. By default, they aggregate into the corresponding k8s `ClusterRoles`: + +| ClusterRole | Aggregates To Default K8s ClusterRole | +| ------------------------------| ---------------------------| +| `monitoring-admin` | `admin`| +| `monitoring-edit` | `edit` | +| `monitoring-view` | `view ` | + +These `ClusterRoles` provide different levels of access to the Monitoring CRDs based on the actions that can be performed: + +| CRDs (monitoring.coreos.com) | Admin | Edit | View | +| ------------------------------| ---------------------------| ---------------------------| ---------------------------| +|
  • `prometheuses`
  • `alertmanagers`
| Get, List, Watch | Get, List, Watch | Get, List, Watch | +|
  • `servicemonitors`
  • `podmonitors`
  • `prometheusrules`
| * | * | Get, List, Watch | + +On a high level, the following permissions are assigned by default as a result. + +### Users with Kubernetes Admin/Edit Permissions + +Only those with the the cluster-admin, admin or edit `ClusterRole` should be able to: + +- Modify the scrape configuration of Prometheus deployments via ServiceMonitor and PodMonitor CRs +- Modify the alerting / recording rules of a Prometheus deployment via PrometheusRules CRs + +### Users with Kubernetes View Permissions + +Only those with who have some Kubernetes `ClusterRole` should be able to: + +- View the configuration of Prometheuses that are deployed within the cluster +- View the configuration of Alertmanagers that are deployed within the cluster +- View the scrape configuration of Prometheus deployments via ServiceMonitor and PodMonitor CRs +- View the alerting/recording rules of a Prometheus deployment via PrometheusRules CRs + +### Additional Monitoring Roles + +Monitoring also creates additional `Roles` that are not assigned to users by default but are created within the cluster. They can be bound to a namespace by deploying a `RoleBinding` that references it. To define a `RoleBinding` with `kubectl` instead of through Rancher, click [here](#assigning-roles-and-clusterroles-with-kubectl). + +Admins should use these roles to provide more fine-grained access to users: + +| Role | Purpose | +| ------------------------------| ---------------------------| +| monitoring-config-admin | Allow admins to assign roles to users to be able to view / modify Secrets and ConfigMaps within the cattle-monitoring-system namespace. Modifying Secrets / ConfigMaps in this namespace could allow users to alter the cluster's Alertmanager configuration, Prometheus Adapter configuration, additional Grafana datasources, TLS secrets, etc. | +| monitoring-config-edit | Allow admins to assign roles to users to be able to view / modify Secrets and ConfigMaps within the cattle-monitoring-system namespace. Modifying Secrets / ConfigMaps in this namespace could allow users to alter the cluster's Alertmanager configuration, Prometheus Adapter configuration, additional Grafana datasources, TLS secrets, etc. | +| monitoring-config-view | Allow admins to assign roles to users to be able to view Secrets and ConfigMaps within the cattle-monitoring-system namespace. Viewing Secrets / ConfigMaps in this namespace could allow users to observe the cluster's Alertmanager configuration, Prometheus Adapter configuration, additional Grafana datasources, TLS secrets, etc. | +| monitoring-dashboard-admin | Allow admins to assign roles to users to be able to edit / view ConfigMaps within the cattle-dashboards namespace. ConfigMaps in this namespace will correspond to Grafana Dashboards that are persisted onto the cluster. | +| monitoring-dashboard-edit | Allow admins to assign roles to users to be able to edit / view ConfigMaps within the cattle-dashboards namespace. ConfigMaps in this namespace will correspond to Grafana Dashboards that are persisted onto the cluster. | +| monitoring-dashboard-view | Allow admins to assign roles to users to be able to view ConfigMaps within the cattle-dashboards namespace. ConfigMaps in this namespace will correspond to Grafana Dashboards that are persisted onto the cluster. | + + +### Assigning Monitoring Roles through Custom Roles + +Admins may assign custom roles in the Rancher UI for admin, editing, and viewing monitoring. These "roles" are created by default when the monitoring app is installed. Additionally, these roles are also deployed to the corresponding Kubernetes roles: admin, edit, and view `ClusterRoles`. + +:::note Important + +The UI won't offer `monitoring-admin`, `monitoring-edit`, and `monitoring-view` options when users are being added to a cluster. These monitoring roles can only be assigned by manually creating a custom role that inherits from Project Owner and Project Monitoring View roles. + +::: + + 1. Create the custom role: + + 1.1 Click **☰ > Users & Authentication > Roles**. + + 1.2 Select the appropriate tab, e.g., **Cluster** role. Then click **Create Cluster Role**. + + 1.3 In the **Name** field, create a custom role such as `View Monitoring`, `Edit Monitoring`, or `Admin Monitoring`. + + 1.4 Click **Inherit From > Add Resource**, then select the Kubernetes role, as applicable, from the dropdown. + + 1.5 Click **Create**. + + + 2. Assign the custom role to a new user: + + 2.1 Click **☰ > Cluster Management > Cluster Explore > Cluster > Cluster Members > Add**. + + 2.2 Search for your new user name from **Select Member** options displayed. + + 2.3 Assign the new custom role from **Cluster Permissions** to the new user. + + 2.4 Click **Create**. + +**Result:** The new user should now be able to see the monitoring tools. + +### Additional Monitoring ClusterRoles + +Monitoring also creates additional `ClusterRoles` that aren't assigned to users by default but are created within the cluster. They aren't aggregated by default but can be bound to a namespace by deploying a `RoleBinding` or `ClusterRoleBinding` that references it. To define a `RoleBinding` with `kubectl` instead of through Rancher, click [here](#assigning-roles-and-clusterroles-with-kubectl). + +| Role | Purpose | +| ------------------------------| ---------------------------| +| monitoring-ui-view | This ClusterRole allows users with write access to the project to view metrics graphs for the specified cluster in the Rancher UI. This is done by granting Read-only access to external Monitoring UIs. Users with this role have permission to list the Prometheus, Alertmanager, and Grafana endpoints and make GET requests to Prometheus, Alertmanager, and Grafana UIs through the Rancher proxy.

This role doesn't grant access to monitoring endpoints. As a result, users with this role won't be able to view cluster monitoring graphs and dashboards in the Rancher UI; however, they are able to access the monitoring Grafana, Prometheus, and Alertmanager UIs if provided those links. | + +:::note + +A user bound to the **View Monitoring** Rancher role and read-only project permissions can't view links in the Monitoring UI. They can still access external monitoring UIs if provided links to those UIs. If you wish to grant access to users with the **View Monitoring** role and read-only project permissions, move the `cattle-monitoring-system` namespace into the project. + +::: + +### Assigning Roles and ClusterRoles with kubectl + +#### Using `kubectl create` + +One method is to use either `kubectl create clusterrolebinding` or `kubectl create rolebinding` to assign a `Role` or `ClusterRole`. This is shown in the following examples: + +- Assign to a specific user: + + + + ```plain + kubectl create clusterrolebinding my-binding --clusterrole=monitoring-ui-view --user=u-l4npx + ``` + + + + + ```plain + kubectl create rolebinding my-binding --clusterrole=monitoring-ui-view --user=u-l4npx --namespace=my-namespace + ``` + + + +- Assign to all authenticated users: + + + + ```plain + kubectl create clusterrolebinding my-binding --clusterrole=monitoring-ui-view --group=system:authenticated + ``` + + + + + ```plain + kubectl create rolebinding my-binding --clusterrole=monitoring-ui-view --group=system:authenticated --namespace=my-namespace + ``` + + + + +#### Using YAML Files + +Another method is to define bindings in YAML files that you create. You must first configure the `RoleBinding` or `ClusterRoleBinding` with a YAML file. Then, apply the configuration changes by running the `kubectl apply` command. + +- **Roles**: Below is an example YAML file to help you configure `RoleBindings` in Kubernetes. You'll need to fill in the name below. + +:::note + +Names are case-sensitive. + +::: + +```yaml +# monitoring-config-view-role-binding.yaml +apiVersion: rbac.authorization.k8s.io/v1 +kind: RoleBinding +metadata: + name: monitoring-config-view + namespace: cattle-monitoring-system +roleRef: + kind: Role + name: monitoring-config-view + apiGroup: rbac.authorization.k8s.io +subjects: +- kind: User + name: u-b4qkhsnliz # this can be found via `kubectl get users -A` + apiGroup: rbac.authorization.k8s.io +``` + +- **kubectl**: Below is an example of a `kubectl` command used to apply the binding you've created in the YAML file. Remember to fill in your YAML filename accordingly. + ```plain + kubectl apply -f monitoring-config-view-role-binding.yaml + ``` + +## Users with Rancher Based Permissions + +The relationship between the default roles deployed by Rancher (i.e. cluster-owner, cluster-member, project-owner, project-member), the default Kubernetes roles, and the roles deployed by the rancher-monitoring chart are detailed in the table below: + +
Default Rancher Permissions and Corresponding Kubernetes ClusterRoles
+ +| Rancher Role | Kubernetes Role | Monitoring ClusterRole / Role | ClusterRoleBinding or RoleBinding? | +| --------- | --------- | --------- | --------- | +| cluster-owner | cluster-admin | N/A | ClusterRoleBinding | +| cluster-member | admin | monitoring-admin | ClusterRoleBinding | +| project-owner | admin | monitoring-admin | RoleBinding within Project namespace | +| project-member | edit | monitoring-edit | RoleBinding within Project namespace | + +In addition to these default roles, the following Rancher project roles can be applied to members of your cluster to provide access to monitoring. These Rancher roles are tied to ClusterRoles deployed by the monitoring chart: + +
Non-default Rancher Permissions and Corresponding Kubernetes ClusterRoles
+ +| Rancher Role | Kubernetes ClusterRole | Available In Rancher From | Available in Monitoring v2 From | +|--------------------------|-------------------------------|-------|------| +| View Monitoring* | [monitoring-ui-view](#additional-monitoring-clusterroles) | 2.4.8+ | 9.4.204+ | + +:::note + +A user bound to the **View Monitoring** Rancher role and read-only project permissions can't view links in the Monitoring UI. They can still access external monitoring UIs if provided links to those UIs. If you wish to grant access to users with the **View Monitoring** role and read-only project permissions, move the `cattle-monitoring-system` namespace into the project. + +::: + +### Differences in 2.5.x + +Users with the project-member or project-owners roles assigned will not be given access to either Prometheus or Grafana in Rancher 2.5.x since we only create Grafana or Prometheus on a cluster-level. + +In addition, while project owners will still be only able to add ServiceMonitors / PodMonitors that scrape resources within their project's namespace by default, PrometheusRules are not scoped to a single namespace / project. Therefore, any alert rules or recording rules created by project-owners within their project namespace will be applied across the entire cluster, although they will be unable to view / edit / delete any rules that were created outside the project's namespace. + +### Assigning Additional Access + +If cluster-admins would like to provide additional admin/edit access to users outside of the roles offered by the rancher-monitoring chart, the following table identifies the potential impact: + +|CRDs (monitoring.coreos.com) | Can it cause impact outside of a namespace / project? | Impact | +|----------------------------| ------| ----------------------------| +| `prometheuses`| Yes, this resource can scrape metrics from any targets across the entire cluster (unless the Operator itself is otherwise configured). | User will be able to define the configuration of new cluster-level Prometheus deployments that should be created in the cluster. | +| `alertmanagers`| No | User will be able to define the configuration of new cluster-level Alertmanager deployments that should be created in the cluster. Note: if you just want to allow users to configure settings like Routes and Receivers, you should just provide access to the Alertmanager Config Secret instead. | +|
  • `servicemonitors`
  • `podmonitors`
| No, not by default; this is configurable via `ignoreNamespaceSelectors` on the Prometheus CR. | User will be able to set up scrapes by Prometheus on endpoints exposed by Services / Pods within the namespace they are given this permission in. | +| `prometheusrules`| Yes, PrometheusRules are cluster-scoped. | User will be able to define alert or recording rules on Prometheus based on any series collected across the entire cluster. | + +| k8s Resources | Namespace | Can it cause impact outside of a namespace / project? | Impact | +|----------------------------| ------| ------| ----------------------------| +|
  • `secrets`
  • `configmaps`
| `cattle-monitoring-system` | Yes, Configs and Secrets in this namespace can impact the entire monitoring / alerting pipeline. | User will be able to create or edit Secrets / ConfigMaps such as the Alertmanager Config, Prometheus Adapter Config, TLS secrets, additional Grafana datasources, etc. This can have broad impact on all cluster monitoring / alerting. | +|
  • `secrets`
  • `configmaps`
| `cattle-dashboards` | Yes, Configs and Secrets in this namespace can create dashboards that make queries on all metrics collected at a cluster-level. | User will be able to create Secrets / ConfigMaps that persist new Grafana Dashboards only. | + +## Role-based Access Control for Grafana + +Rancher allows any users who are authenticated by Kubernetes and have access the Grafana service deployed by the Rancher Monitoring chart to access Grafana via the Rancher Dashboard UI. By default, all users who are able to access Grafana are given the [Viewer](https://grafana.com/docs/grafana/latest/permissions/organization_roles/#viewer-role) role, which allows them to view any of the default dashboards deployed by Rancher. + +However, users can choose to log in to Grafana as an [Admin](https://grafana.com/docs/grafana/latest/permissions/organization_roles/#admin-role) if necessary. The default Admin username and password for the Grafana instance will be `admin`/`prom-operator`, but alternative credentials can also be supplied on deploying or upgrading the chart. + +To see the Grafana UI, install `rancher-monitoring`. Then: + +1. In the upper left corner, click **☰ > Cluster Management**. +1. On the **Clusters** page, go to the cluster where you want to see the visualizations and click **Explore**. +1. In the left navigation bar, click **Monitoring**. +1. Click **Grafana**. + +
Cluster Compute Resources Dashboard in Grafana
+ +![Cluster Compute Resources Dashboard in Grafana](/img/cluster-compute-resources-dashboard.png) + +
Default Dashboards in Grafana
+ +![Default Dashboards in Grafana](/img/grafana-default-dashboard.png) \ No newline at end of file diff --git a/versioned_docs/version-2.14/integrations-in-rancher/monitoring-and-alerting/windows-support.md b/versioned_docs/version-2.14/integrations-in-rancher/monitoring-and-alerting/windows-support.md new file mode 100644 index 00000000000..db1dfb8bfa3 --- /dev/null +++ b/versioned_docs/version-2.14/integrations-in-rancher/monitoring-and-alerting/windows-support.md @@ -0,0 +1,43 @@ +--- +title: Windows Cluster Support for Monitoring V2 +--- + + + + + +Monitoring V2 can be deployed on a Windows cluster to scrape metrics from Windows nodes using [prometheus-community/windows_exporter](https://github.com/prometheus-community/windows_exporter) (previously named `wmi_exporter`). + +## Cluster Requirements + +Monitoring V2 for Windows can only scrape metrics from Windows hosts that have a minimum `wins` version of v0.1.0. To be able to fully deploy Monitoring V2 for Windows, all of your hosts must meet this requirement. + +### Upgrading Existing Clusters to wins v0.1.0 + +If the cluster was provisioned before Rancher 2.5.8 (even if the current Rancher version is 2.5.8), you will not be able to successfully deploy Monitoring V2 for Windows until you upgrade the wins version on each host to at least v0.1.0. + +To facilitate this upgrade, Rancher 2.5.8 has released a brand new Helm chart called `rancher-wins-upgrader`. + +1. Deploy `rancher-wins-upgrader` with the following override: + + ```yaml + # Masquerading bootstraps the wins-upgrader installation via + # a previously whitelisted process path since the normal install path, + # c:\etc\rancher\wins\wins-upgrade.exe is not normally whitelisted. + # In this case, we are using the previously whitelisted process + # path used by Monitoring V1. + masquerade: + enabled: true + as: c:\\etc\wmi-exporter\wmi-exporter.exe + ``` + +2. Once all your hosts have been successfully upgraded, please ensure that you deploy the Helm chart once again with default values to avoid conflicts with the following settings: + + ```yaml + masquerade: + enabled: false + ``` + +**Result:** The hosts are ready for Monitoring V2 to be installed. You may choose to uninstall the `rancher-wins-upgrader` chart or keep it in your cluster to facilitate future upgrades. + +For more information on how it can be used, please see the [README.md](https://github.com/rancher/wins/blob/master/charts/rancher-wins-upgrader/README.md) of the chart. diff --git a/versioned_docs/version-2.14/integrations-in-rancher/neuvector/neuvector.md b/versioned_docs/version-2.14/integrations-in-rancher/neuvector/neuvector.md new file mode 100644 index 00000000000..4d823368dee --- /dev/null +++ b/versioned_docs/version-2.14/integrations-in-rancher/neuvector/neuvector.md @@ -0,0 +1,27 @@ +--- +title: Container Security with NeuVector +--- + + + + + +NeuVector is the only 100% open source, Zero Trust container security platform. Continuously scan throughout the container lifecycle. Remove security roadblocks. Bake in security policies at the start to maximize developer agility. NeuVector provides vulnerability and compliance scanning and management from build to production. The unique NeuVector run-time protection protects network connections within and ingress/egress to the cluster with a Layer7 container firewall. Additionally, NeuVector monitors process and file activity in containers and on hosts to stop unauthorized activity. + +## NeuVector with Rancher + +All NeuVector features are available through Rancher with integrated deployment and single-sign on to the NeuVector console. Rancher cluster admins are able to deploy and manage the NeuVector deployment on their clusters and easily configure NeuVector through Helm values, configMaps, custom resource definitions (CRDs) and the NeuVector console. + +With NeuVector and Rancher: + +- Deploy, manage and secure multiple clusters. +- Manage and report vulnerabilities and compliance results for Rancher workloads and nodes. + +## NeuVector Prime with Rancher Prime + +The NeuVector UI Extension for Rancher Manager is available and supported for Rancher Prime and NeuVector Prime customers. This extension provides: + +- Automated deployment of NeuVector, including the Rancher Prime NeuVector Extension dashboard. +- Access to important security information from each cluster, such as critical security events, vulnerability scan results, and ingress/egress exposures. +- Integrated vulnerability (CVE) and compliance scan results directly in Rancher resources such as nodes and containers/pods. +- Integrated actions such as manual triggers of scans on Rancher resources. diff --git a/versioned_docs/version-2.14/integrations-in-rancher/neuvector/overview.md b/versioned_docs/version-2.14/integrations-in-rancher/neuvector/overview.md new file mode 100644 index 00000000000..968e45d820b --- /dev/null +++ b/versioned_docs/version-2.14/integrations-in-rancher/neuvector/overview.md @@ -0,0 +1,170 @@ +--- +title: Overview +--- + + + + + +[NeuVector 5.x](https://open-docs.neuvector.com/) is an open-source container-centric security platform that is integrated with Rancher. NeuVector offers real-time compliance, visibility, and protection for critical applications and data during runtime. NeuVector provides a firewall, container process/file system monitoring, security auditing with CIS benchmarks, and vulnerability scanning. For more information on Rancher security, please see the [security documentation](../../reference-guides/rancher-security/rancher-security.md). + +NeuVector can be enabled through a Helm chart that may be installed either through **Apps** or through the **Cluster Tools** button in the Rancher UI. Once the Helm chart is installed, users can easily [deploy and manage NeuVector clusters within Rancher](https://open-docs.neuvector.com/deploying/rancher#deploy-and-manage-neuvector-through-rancher-apps-marketplace). + +## Installing NeuVector with Rancher + +The Harvester Helm Chart is used to manage access to the NeuVector UI in Rancher where users can navigate directly to deploy and manage their NeuVector clusters. + +**To navigate to and install the NeuVector chart through Apps:** + +1. Click **☰ > Cluster Management**. +1. On the Clusters page, go to the cluster where you want to deploy NeuVector, and click **Explore**. +1. Go to **Apps > Charts**, and install **NeuVector** from the chart repo. +1. Different cluster types require different container runtimes. When configuring Helm chart values, go to the **Container Runtime** section, and select your runtime in accordance with the cluster type. Finally, click **Install** again. + +Some examples are as follows: + +- K3s and RKE2: `k3scontainerd` +- AKS: `containerd` for v1.19 and up +- EKS: `docker` for v1.22 and below; `containerd` for v1.23 and up +- GKE: `containerd` (see the [Google docs](https://cloud.google.com/kubernetes-engine/docs/concepts/using-containerd) for more) + + :::note + + Only one container runtime engine may be selected at a time during installation. + + ::: + +**To navigate to and install the NeuVector chart through Cluster Tools:** + +1. Click **☰ > Cluster Management**. +1. On the Clusters page, go to the cluster where you want to deploy NeuVector, and click **Explore**. +1. Click on **Cluster Tools** at the bottom of the left navigation bar. +1. Repeat step 4 above to select your container runtime accordingly, then click **Install** again. + +## Accessing NeuVector from the Rancher UI + +1. Navigate to the cluster explorer of the cluster where NeuVector is installed. In the left navigation bar, click **NeuVector**. +1. Click the external link to go to the NeuVector UI. Once the link is selected, users must accept the `END USER LICENSE AGREEMENT` to access the NeuVector UI. + +## Uninstalling NeuVector from the Rancher UI + +**To uninstall from Apps:** + +1. Click **☰ > Cluster Management**. +1. Under **Apps**, click **Installed Apps**. +1. Under `cattle-neuvector-system`, select both the NeuVector app (and the associated CRD if desired), then click **Delete**. + +**To uninstall from Cluster Tools:** + +1. Click **☰ > Cluster Management**. +1. Click on **Cluster Tools** at the bottom-left of the screen, then click on the trash can icon under the NeuVector chart. Select `Delete the CRD associated with this app` if desired, then click **Delete**. + +## GitHub Repository + +The NeuVector project is available [here](https://github.com/neuvector/neuvector). + +## Documentation + +The NeuVector documentation is [here](https://open-docs.neuvector.com/). + +## Architecture + +The NeuVector security solution contains four types of security containers: Controllers, Enforcers, Managers, and Scanners. A special container called an All-in-One is also provided to combine the Controller, Enforcer, and Manager functions all in one container, primarily for Docker-native deployments. There is also an Updater which, when run, will update the CVE database. + +- **Controller:** Manages the NeuVector Enforcer container; provides REST APIs for the management console. +- **Enforcer:** Enforces security policies. +- **Manager:** Provides a web-UI and CLI console to manage the NeuVector platform. +- **All-in-One:** Includes the Controller, Enforcer, and Manager. +- **Scanner:** Performs the vulnerability and compliance scanning for images, containers, and nodes. +- **Updater:** Updates the CVE database for Neuvector (when run); redeploys scanner pods. + +
**NeuVector Security Containers:**
+ +![NeuVector Security Containers](/img/neuvector-security-containers.png) + +
**NeuVector Architecture:**
+ +![NeuVector Architecture](/img/neuvector-architecture.png) + +To learn more about NeuVector's architecture, please refer [here](https://open-docs.neuvector.com/basics/overview#architecture). + +## CPU and Memory Allocations + +Below are the minimum recommended computing resources for the NeuVector chart installation in a default deployment. Note that the resource limit is not set. + +| Container | CPU - Request | Memory - Request | +|------------|--------|---------| +| Controller | 3 (1GB 1vCPU needed per controller) | * +| Enforcer | On all nodes (500MB .5vCPU) | 1GB +| Manager | 1 (500MB .5vCPU) | * +| Scanner | 3 (100MB .5vCPU) | * + +\* Minimum 1GB of memory total required for Controller, Manager, and Scanner containers combined. + +## Hardened Cluster Support - Calico and Canal + +NeuVector components Controller and Enforcer are deployable if PSP is set to true. + +**Applicable to NeuVector chart version 100.0.0+up2.2.0 only:** + +For Manager, Scanner, and Updater components, additional configuration is required as shown below: + +```sh +kubectl patch deploy neuvector-manager-pod -n cattle-neuvector-system --patch '{"spec":{"template":{"spec":{"securityContext":{"runAsUser": 5400}}}}}' +kubectl patch deploy neuvector-scanner-pod -n cattle-neuvector-system --patch '{"spec":{"template":{"spec":{"securityContext":{"runAsUser": 5400}}}}}' +kubectl patch cronjob neuvector-updater-pod -n cattle-neuvector-system --patch '{"spec":{"jobTemplate":{"spec":{"template":{"spec":{"securityContext":{"runAsUser": 5400}}}}}}}' +``` + +You will need to set additional configuration for your hardened cluster environment. + +:::note +You must update your config in both RKE2 and K3s hardened clusters as shown below. +::: + +1. Click **☰ > Cluster Management**. +1. Go to the cluster that you created and click **Explore**. +1. In the left navigation bar, click **Apps**. +1. Install (or upgrade to) NeuVector version `100.0.1+up2.2.2`. + +- Under **Edit Options** > **Other Configuration**, enable **Pod Security Policy** by checking the box. Note that you must also enter a value greater than `zero` for `Manager runAsUser ID`, `Scanner runAsUser ID`, and `Updater runAsUser ID`: + + ![Enable PSP for RKE2 and K3s Hardened Clusters](/img/psp-nv-rke2.png) + +1. Click **Install** at the bottom-right to complete. + +## SELinux-enabled Cluster Support - Calico and Canal + +To enable SELinux on RKE2 clusters, follow the steps below: + +- NeuVector components Controller and Enforcer are deployable if PSP is set to true. + + +**Applicable to NeuVector chart version 100.0.0+up2.2.0 only:** + +- For Manager, Scanner, and Updater components, additional configuration is required as shown below: + +``` +kubectl patch deploy neuvector-manager-pod -n cattle-neuvector-system --patch '{"spec":{"template":{"spec":{"securityContext":{"runAsUser": 5400}}}}}' +kubectl patch deploy neuvector-scanner-pod -n cattle-neuvector-system --patch '{"spec":{"template":{"spec":{"securityContext":{"runAsUser": 5400}}}}}' +kubectl patch cronjob neuvector-updater-pod -n cattle-neuvector-system --patch '{"spec":{"jobTemplate":{"spec":{"template":{"spec":{"securityContext":{"runAsUser": 5400}}}}}}}' +``` + +## Cluster Support in an Air-Gapped Environment + +- All NeuVector components are deployable on a cluster in an air-gapped environment without any additional configuration needed. + +## Support Limitations + +* Only admins and cluster owners are currently supported. + +* Fleet multi-cluster deployment is not supported. + +* NeuVector is not supported on a Windows cluster. + +## Other Limitations + +* Currently, NeuVector feature chart installation fails when a NeuVector partner chart already exists. To work around this issue, uninstall the NeuVector partner chart and reinstall the NeuVector feature chart. + +* Sometimes when the controllers are not ready, the NeuVector UI is not accessible from the Rancher UI. During this time, controllers will try to restart, and it takes a few minutes for the controllers to be active. + +* Container runtime is not auto-detected for different cluster types when installing the NeuVector chart. To work around this, you can specify the runtime manually. diff --git a/versioned_docs/version-2.14/integrations-in-rancher/rancher-desktop.md b/versioned_docs/version-2.14/integrations-in-rancher/rancher-desktop.md new file mode 100644 index 00000000000..a790e814c0e --- /dev/null +++ b/versioned_docs/version-2.14/integrations-in-rancher/rancher-desktop.md @@ -0,0 +1,34 @@ +--- +title: Kubernetes on the Desktop with Rancher Desktop +--- + + + + + + +Rancher Desktop bundles together essential tools for developing and testing cloud-native applications from your desktop. + +If you're working from your local machine on apps intended for cloud environments, you normally need a lot of preparation. You need to select a container run-time, install Kubernetes and popular utilities, and possibly set up a virtual machine. Installing components individually and getting them to work together can be a time-consuming process. + +To reduce the complexity, Rancher Desktop offers teams the following key features: + +- Simple and easy installation on macOS, Linux and Windows operating systems. +- K3s, a ready-to-use, light-weight Kubernetes distribution. +- The ability to easily switch between Kubernetes versions. +- A GUI-based cluster dashboard powered by Rancher to explore your local cluster. +- Freedom to choose your container engine: dockerd (moby) or containerd. +- Preference settings to configure the application to suit your needs. +- Bundled tools required for your container, for Kubernetes-based development, and for operation workflows. +- Periodic updates to keep bundled tools up to date. +- Integration with popular tools/IDEs, including VS Code and Skaffold. +- Image & Registry access control. +- Support for Docker extensions. + +Visit the [Rancher Desktop](https://rancherdesktop.io) website and read the [docs](https://docs.rancherdesktop.io/) to learn more. + +To install Rancher Desktop on your machine, refer to the [installation guide](https://docs.rancherdesktop.io/getting-started/installation). + +## Trying Rancher on Rancher Desktop + +Rancher Desktop offers the setup and tools you need to easily try out containerized, Helm-based applications. You can get started with the Rancher Kubernetes Management platform using Rancher Desktop, by following this [how-to guide](https://docs.rancherdesktop.io/how-to-guides/rancher-on-rancher-desktop). diff --git a/versioned_docs/version-2.14/integrations-in-rancher/rancher-extensions.md b/versioned_docs/version-2.14/integrations-in-rancher/rancher-extensions.md new file mode 100644 index 00000000000..52901b706b3 --- /dev/null +++ b/versioned_docs/version-2.14/integrations-in-rancher/rancher-extensions.md @@ -0,0 +1,198 @@ +--- +title: Rancher Extensions +--- + + + + + +Extensions allow users, developers, partners, and customers to extend and enhance the Rancher UI. In addition, users can make changes and create enhancements to their UI functionality independent of Rancher releases. Extensions will enable users to build on top of Rancher to better tailor it to their respective environments. Note that users will also have the ability to update to new versions as well as roll back to a previous version. + +Extensions are Helm charts that can only be installed once into a cluster; therefore, these charts have been simplified and separated from the general Helm charts listed under **Apps**. + +Examples of built-in Rancher extensions are Fleet, Explorer, and Harvester. Examples of other extensions that use the Extensions API that can be manually added are Kubewarden and Elemental. + +## Prerequisites + +> You must log in as an admin in order to view and interact with the extensions management page. + +## Installing Extensions + +1. Click **☰ > Extensions** under **Configuration**. + +2. If not already installed in **Apps**, you must enable the extension operator by clicking the **Enable** button. + + - Click **OK** to add the Rancher extension repository if your installation is not air-gapped. Otherwise, uncheck the box to do so and click **OK**. + + ![Rancher extension repository](/img/add-rancher-extension-repo.png) + +3. On the **Extensions** page, click on the **Available** tab to select which extensions you want to install. + +4. If no extensions are showing as available, you may manually add repos as follows: + + 4.1. On the upper right of screen, click on **⋮ > Manage Repositories > Create**. + + 4.2. Add the desired repo name, making sure to also specify the Git Repo URL and the Git Branch. + + 4.3. Click **Create** in the lower right again to complete. + + ![Manage repositories](/img/manage-repos.png) + +5. Under the **Available** tab, click **Install** on the desired extension and version as in the example below. You can also update your extension from this screen, as the button to **Update** will appear on the extension if one is available. + + ![Install Kubewarden](/img/install-kubewarden.png) + +6. Click the **Reload** page button that will appear after your extension successfully installs. Note that a logged-in user who has just installed an extension will not see a change to the UI **unless** they reload the page. + + ![Reload button](/img/reload-button.png) + +## Updating and Upgrading Extensions + +1. Click **☰ > Extensions** under **Configuration**. +1. Select the **Updates** tab. +1. Click **Update**. + +If there is a new version of the extension, there will also be an **Update** button visible on the associated card for the extension in the **Available** tab. + +## Deleting Extensions + +1. Click **☰**, then click on the name of your local cluster. +1. From the sidebar, select **Apps > Installed Apps**. +1. Find the name of the chart you want to delete and select the checkbox next to it. +1. Click **Delete**. + +## Deleting Extension Repositories + +1. Click **☰ > Extensions** under **Configuration**. +1. On the top right, click **⋮ > Manage Repositories**. +1. Find the name of the extension repository you want to delete. Select the checkbox next to the repository name, then click **Delete**. + +## Deleting Extension Repository Container Images + +1. Click **☰**, then select **Extensions**, under **Configuration**. +1. On the top right, click **⋮ > Manage Extension Catalogs**. +1. Find the name of the container image you want to delete, then click **⋮ > Uninstall**. + +## Uninstalling Extensions + +There are two ways to uninstall or disable an extension: + +1. Under the **Installed** tab, click the **Uninstall** button on the extension you wish to remove. + + ![Uninstall extensions](/img/uninstall-extension.png) + +1. On the extensions management page, click **⋮ > Disable Extension Support**. This will disable all installed extensions. + + ![Disable extensions](/img/disable-extension-support.png) + +:::caution + +You must reload the page after disabling extensions or display issues may occur. + +::: + +## Developing Extensions + +To learn how to develop your own extensions, refer to the official [Getting Started](https://rancher.github.io/dashboard/extensions/extensions-getting-started) guide. + +## Working with Extensions in an Air-gapped Environment + +If you intend to work with extensions in an air-gapped environment, you must perform some extra steps before you can complete certain tasks. + +### Accessing Rancher UI Extensions in an Air-Gapped Environment + +Rancher provides some extensions, such as Kubewarden and Elemental, through the `ui-plugin-catalog` container image at https://hub.docker.com/r/rancher/ui-plugin-catalog/tags. If you're trying to install these extensions in an air-gapped environment, you must make the `ui-plugin-catalog` image accessible. + +1. Mirror the `ui-plugin-catalog` image to a private registry: + + ```bash + export REGISTRY_ENDPOINT= # e.g. "my-private-registry.com" + docker pull rancher/ui-plugin-catalog: + docker tag rancher/ui-plugin-catalog: $REGISTRY_ENDPOINT/rancher/ui-plugin-catalog: + docker push $REGISTRY_ENDPOINT/rancher/ui-plugin-catalog: +2. Use the mirrored image to create a Kubernetes [deployment](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/): + ```yaml + apiVersion: apps/v1 + kind: Deployment + metadata: + name: ui-plugin-catalog + namespace: cattle-ui-plugin-system + labels: + catalog.cattle.io/ui-extensions-catalog-image: ui-plugin-catalog + spec: + replicas: 1 + selector: + matchLabels: + catalog.cattle.io/ui-extensions-catalog-image: ui-plugin-catalog + template: + metadata: + namespace: cattle-ui-plugin-system + labels: + catalog.cattle.io/ui-extensions-catalog-image: ui-plugin-catalog + spec: + containers: + - name: server + image: /rancher/ui-plugin-catalog: + imagePullPolicy: Always + imagePullSecrets: + - name: + ``` +3. Expose the deployment by creating a [ClusterIP service](https://kubernetes.io/docs/concepts/services-networking/service/#type-clusterip): + ```yaml + apiVersion: v1 + kind: Service + metadata: + name: ui-plugin-catalog-svc + namespace: cattle-ui-plugin-system + spec: + ports: + - name: catalog-svc-port + port: 8080 + protocol: TCP + targetPort: 8080 + selector: + catalog.cattle.io/ui-extensions-catalog-image: ui-plugin-catalog + type: ClusterIP + ``` +4. Create a [ClusterRepo](../how-to-guides/new-user-guides/helm-charts-in-rancher/helm-charts-in-rancher.md) that targets the ClusterIP service: + ```yaml + apiVersion: catalog.cattle.io/v1 + kind: ClusterRepo + metadata: + name: ui-plugin-catalog-repo + spec: + url: http://ui-plugin-catalog-svc.cattle-ui-plugin-system:8080 + ``` + +After you successfully set up these resources, you can install the extensions from the `ui-plugin-charts` manifest into your air-gapped environment. + +### Importing and Installing Extensions in an Air-gapped Environment + +1. Find the address of the container image repository that you want to import as an extension. You should import and use the latest tagged version of the image to ensure you receive the latest features and security updates. + - **(Optional)** If the container image is private: [Create](../how-to-guides/new-user-guides/kubernetes-resources-setup/secrets.md) a registry secret within the `cattle-ui-plugin-system` namespace. Enter the domain of the image address in the **Registry Domain Name** field. +1. Click **☰**, then select **Extensions**, under **Configuration**. +1. On the top right, click **⋮ > Manage Extension Catalogs**. +1. Select the **Import Extension Catalog** button. +1. Enter the image address in the **Catalog Image Reference** field. + * **(Optional)** If the container image is private, select the secret you just created from the **Pull Secrets** drop-down menu. +1. Click **Load**. The extension will now be **Pending**. +1. Return to the **Extensions** page. +1. Select the **Available** tab, and click **Reload** to make sure that the list of extensions is up to date. +1. Find the extension you just added, and click **Install**. + +### Updating and Upgrading an Extensions Repository in an Air-gapped Environment + +Extensions repositories that aren't air-gapped are automatically updated. If the repository is air-gapped, you must update it manually. + +First, mirror the latest changes to your private registry by following the same steps for initially [importing and installing an extension repository](#importing-and-installing-extensions-in-an-air-gapped-environment). + +After you mirror the latest changes, follow these steps: + +1. Click **☰ > Local**. +1. From the sidebar, select **Workloads > Deployments**. +1. From the namespaces dropdown menu, select **cattle-ui-plugin-system**. +1. Find the **cattle-ui-plugin-system** namespace. +1. Select the `ui-plugin-catalog` deployment. +1. Click **⋮ > Edit config**. +1. Update the **Container Image** field within the deployment's container with the latest image. +1. Click **Save**. diff --git a/versioned_docs/version-2.14/integrations-in-rancher/suse-observability/suse-observability.md b/versioned_docs/version-2.14/integrations-in-rancher/suse-observability/suse-observability.md new file mode 100644 index 00000000000..cd1b2ed430c --- /dev/null +++ b/versioned_docs/version-2.14/integrations-in-rancher/suse-observability/suse-observability.md @@ -0,0 +1,21 @@ +--- +title: SUSE Observability +--- + + + + + +SUSE Observability is a complete observability solution that provides deep insights into the health of your clusters and nodes, and the workloads running on them. Designed to give you clear visibility into your entire Kubernetes environment, SUSE Observability’s full-stack approach allows you to seamlessly explore everything from services to infrastructure within a single platform, eliminating the need for multiple observability tools. + +SUSE Observability securely collects and correlates data, offering actionable insights into both existing and potential issues in your cluster. This helps you address current problems swiftly and take preventative measures against future challenges. + +The intuitive dashboards highlight problem areas and offer remediation steps, guiding you from issue identification to root cause analysis, and ultimately to resolution, in the quickest possible time. + +For more information and to set up SUSE Observability in your SUSE Rancher-managed Kubernetes cluster, please refer to the [documentation](https://docs.stackstate.com/). + +:::note + +The documentation portal for SUSE Observability is currently under development. In the coming months, the portal will be rolled out featuring comprehensive guides, tutorials, and references to support you on your SUSE Observability journey. Stay tuned! + +::: diff --git a/versioned_docs/version-2.14/rancher-manager.md b/versioned_docs/version-2.14/rancher-manager.md new file mode 100644 index 00000000000..ad5eeb33b87 --- /dev/null +++ b/versioned_docs/version-2.14/rancher-manager.md @@ -0,0 +1,20 @@ +--- +slug: / +title: "What is Rancher?" +sidebar_label: What is Rancher? +description: "Rancher adds significant value on top of Kubernetes: managing hundreds of clusters from one interface, centralizing RBAC, enabling monitoring and alerting. Read more." +--- + + + + + +Rancher is a Kubernetes management tool to deploy and run clusters anywhere and on any provider. + +Rancher can provision Kubernetes from a hosted provider, provision compute nodes and then install Kubernetes onto them, or import existing Kubernetes clusters running anywhere. + +Rancher adds significant value on top of Kubernetes, first by centralizing authentication and role-based access control (RBAC) for all of the clusters, giving global admins the ability to control cluster access from one location. + +It then enables detailed monitoring and alerting for clusters and their resources, ships logs to external providers, and integrates directly with Helm via the Application Catalog. If you have an external CI/CD system, you can plug it into Rancher, but if you don't, Rancher even includes Fleet to help you automatically deploy and upgrade workloads. + +Rancher is a _complete_ container management platform for Kubernetes, giving you the tools to successfully run Kubernetes anywhere. diff --git a/versioned_docs/version-2.14/reference-guides/backup-restore-configuration/backup-configuration.md b/versioned_docs/version-2.14/reference-guides/backup-restore-configuration/backup-configuration.md new file mode 100644 index 00000000000..2ece25be1a0 --- /dev/null +++ b/versioned_docs/version-2.14/reference-guides/backup-restore-configuration/backup-configuration.md @@ -0,0 +1,208 @@ +--- +title: Backup Configuration +--- + + + + + +The **Backup: Create** page lets you configure a schedule, enable encryption and specify the storage location for your backups. + + +You must first [install](../../how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/back-up-rancher.md) the `rancher-backup` operator. After you do so, you can access the **Backup: Create** page: + +## Schedule + +Select the first option to perform a one-time backup, or select the second option to schedule recurring backups. Selecting **Recurring Backups** lets you configure following two fields: + +- **Schedule**: This field accepts + - Standard [cron expressions](https://en.wikipedia.org/wiki/Cron), such as `"0 * * * *"` + - Descriptors, such as `"@midnight"` or `"@every 1h30m"` +- **Retention Count**: This value specifies how many backup files must be retained. If files exceed the given retentionCount, the oldest files will be deleted. The default value is 10. + +| YAML Directive Name | Description | +| ---------------- | ---------------- | +| `schedule` | Provide the cron string for scheduling recurring backups. | +| `retentionCount` | Provide the number of backup files to be retained. | + +## ResourceSet + +While you can create your own ResourceSets to back up custom applications, two ResourceSets specifically for backing up Rancher are officially maintained and created by default by the `rancher-backup` operator. We refer to these as `rancher-resource-set-basic` and `rancher-resource-set-full`. The difference between them is whether they include secrets or not in the backups. + +`rancher-resource-set-basic` does not include any secrets in the backup files to safeguard confidential information. You are responsible for recording any secrets and redeploying them safely. + +`rancher-resource-set-full` includes all essential secrets in the backup files to ensure Rancher continues running smoothly after a restore or migration. To avoid storing sensitive information in plain text, we strongly advise you to enable encryption with a strong key. + +| YAML Directive Name | Description | +| ---------------- | ---------------- | +| `resourceSetName` | Provide the name of the ResourceSet to define which resources will be included in this backup. | + +## Encryption + +The rancher-backup gathers resources by making calls to the kube-apiserver. Objects returned by apiserver are decrypted, so even if [encryption at rest](https://kubernetes.io/docs/tasks/administer-cluster/encrypt-data/) is enabled, even the encrypted objects gathered by the backup will be in plaintext. + +To avoid storing them in plaintext, you can use the same `EncryptionConfiguration` file that was used for at rest encryption, to encrypt certain resources in your backup. + +:::note Important: + +When encrypting objects in the backup you must save the `EncryptionConfiguration` file for future use, because it won’t be saved by the rancher-backup operator. + +For example, when [migrating Rancher to a new cluster](../../how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/migrate-rancher-to-new-cluster.md) the file is used to re-create the secret in the new cluster. + +::: + +The operator consumes the `EncryptionConfiguration` as a Kubernetes Secret in the `cattle-resources-system` namespace under the key named `encryption-provider-config.yaml` in the secret data. + +For the `EncryptionConfiguration`, you can use the [sample file provided in the Kubernetes documentation.](https://kubernetes.io/docs/tasks/administer-cluster/encrypt-data/#understanding-the-encryption-at-rest-configuration) + +To ensure the correct key is used in the secret, the encryption configuration file must be named `encryption-provider-config.yaml`. The below command uses the `--from-file` flag to create the secret with the correct key name. + +Save the `EncryptionConfiguration` in a file called `encryption-provider-config.yaml` and run this command: + +```bash +kubectl create secret generic encryptionconfig \ + --from-file=./encryption-provider-config.yaml \ + -n cattle-resources-system +``` + +This will ensure that the secret contains a key named `encryption-provider-config.yaml`, and the operator will use this key to get the encryption configuration. + +The `Encryption Config Secret` dropdown will filter out and list only those Secrets that have this exact key. + +![](/img/backup_restore/backup/encryption.png) + +In the example command above, the name `encryptionconfig` can be changed to anything. + + +| YAML Directive Name | Description | +| ---------------- | ---------------- | +| `encryptionConfigSecretName` | Provide the name of the Secret from `cattle-resources-system` namespace, that contains the encryption config file. | + +## Storage Location + +If the StorageLocation is specified in the Backup, the operator will retrieve the backup location from that particular S3 bucket. If not specified, the operator will try to find this file in the default operator-level S3 store, and in the operator-level PVC store. The default storage location is configured during the deployment of the `rancher-backup` operator. + +Selecting the first option stores this backup in the storage location configured while installing the rancher-backup chart. The second option lets you configure a different S3 compatible storage provider for storing the backup. + +### S3 + +:::caution + +If you use an S3 backup target, make sure that every cluster has its own bucket or folder. Rancher populates snapshot information from any available snapshot listed in the S3 bucket or folder configured for that cluster. + +::: + +The S3 storage location contains the following configuration fields: + +1. **Credential Secret** (optional): If you need an AWS access key or secret key to access an S3 bucket, [create a secret](../../how-to-guides/new-user-guides/kubernetes-resources-setup/secrets.md) using your credentials, with keys and directives named `accessKey` and `secretKey`. The secret can be in any namespace. An example secret is [here](#example-credentialsecret). This directive is unnecessary if the nodes running your operator are in EC2 and assigned [IAM permissions to access S3](#iam-permissions-for-ec2-nodes-to-access-s3). The **Credential Secret** dropdown lists secrets in all namespaces. +1. **Bucket Name**: The name of the S3 bucket where backup files will be stored. +1. **Region** (optional): The AWS [region](https://aws.amazon.com/about-aws/global-infrastructure/regions_az/) where the S3 bucket is located. This field isn't needed for configuring MinIO. +1. **Folder** (optional): The name of the folder in the S3 bucket where backup files will be stored. Nested folders (e.g., `rancher/cluster1`) are not supported. If this field is left empty, the default behavior is to store the backup files in the root folder of the S3 bucket. +1. **Endpoint**: The [endpoint](https://docs.aws.amazon.com/general/latest/gr/s3.html) that is used to access S3 in the region of your bucket. +1. **Endpoint CA** (optional): This should be the Base64 encoded CA cert. For an example, refer to the [example S3 compatible configuration.](#example-s3-storage-configuration) +1. **Skip TLS Verifications** (optional): Set to true if you are not using TLS. + + +#### YAML Directive Fields + +| YAML Directive Name | Description | Required | +| ---------------- | ---------------- | ------------ | +| `credentialSecretName` | If you need an AWS access key or secret key to access an S3 bucket, [create a secret](../../how-to-guides/new-user-guides/kubernetes-resources-setup/secrets.md) using your credentials, with keys and directives named `accessKey` and `secretKey`. The secret can be in any namespace. An example secret is [here](#example-credentialsecret). This directive is unnecessary if the nodes running your operator are in EC2 and assigned [IAM permissions to access S3](#iam-permissions-for-ec2-nodes-to-access-s3). | | +| `credentialSecretNamespace` | The namespace of the secret containing the credentials to access S3. This directive is unnecessary if the nodes running your operator are in EC2 and set up with IAM permissions that allow them to access S3, as described in [this section.](#iam-permissions-for-ec2-nodes-to-access-s3) | | +| `bucketName` | The name of the S3 bucket where backup files will be stored. | ✓ | +| `folder` | The name of the folder in the S3 bucket where backup files will be stored. Nested folders (e.g., `rancher/cluster1`) are not supported. If this field is left empty, the default behavior is to store the backup files in the root folder of the S3 bucket. | | +| `region` | The AWS [region](https://aws.amazon.com/about-aws/global-infrastructure/regions_az/) where the S3 bucket is located. | ✓ | +| `endpoint` | The [endpoint](https://docs.aws.amazon.com/general/latest/gr/s3.html) that is used to access S3 in the region of your bucket. | ✓ | +| `endpointCA` | This should be the Base64 encoded CA cert. For an example, refer to the [example S3 compatible configuration.](#example-s3-storage-configuration) | | +| `insecureTLSSkipVerify` | Set to true if you are not using TLS. | | + +### Example S3 Storage Configuration + +```yaml +s3: + credentialSecretName: s3-creds + credentialSecretNamespace: default + bucketName: rancher-backups + folder: rancher + region: us-west-2 + endpoint: s3.us-west-2.amazonaws.com +``` + +### Example MinIO Configuration + +```yaml +s3: + credentialSecretName: minio-creds + bucketName: rancherbackups + endpoint: minio.35.202.130.254.xip.io + endpointCA: LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSURHakNDQWdLZ0F3SUJBZ0lKQUtpWFZpNEpBb0J5TUEwR0NTcUdTSWIzRFFFQkN3VUFNQkl4RURBT0JnTlYKQkFNTUIzUmxjM1F0WTJFd0hoY05NakF3T0RNd01UZ3lOVFE1V2hjTk1qQXhNREk1TVRneU5UUTVXakFTTVJBdwpEZ1lEVlFRRERBZDBaWE4wTFdOaE1JSUJJakFOQmdrcWhraUc5dzBCQVFFRkFBT0NBUThBTUlJQkNnS0NBUUVBCjA4dnV3Q2Y0SEhtR2Q2azVNTmozRW5NOG00T2RpS3czSGszd1NlOUlXQkwyVzY5WDZxenBhN2I2M3U2L05mMnkKSnZWNDVqeXplRFB6bFJycjlpbEpWaVZ1NFNqWlFjdG9jWmFCaVNsL0xDbEFDdkFaUlYvKzN0TFVTZSs1ZDY0QQpWcUhDQlZObU5xM3E3aVY0TE1aSVpRc3N6K0FxaU1Sd0pOMVVKQTZ6V0tUc2Yzc3ByQ0J2dWxJWmZsVXVETVAyCnRCTCt6cXZEc0pDdWlhNEEvU2JNT29tVmM2WnNtTGkwMjdub3dGRld3MnRpSkM5d0xMRE14NnJoVHQ4a3VvVHYKQXJpUjB4WktiRU45L1Uzb011eUVKbHZyck9YS2ZuUDUwbk8ycGNaQnZCb3pUTStYZnRvQ1d5UnhKUmI5cFNTRApKQjlmUEFtLzNZcFpMMGRKY2sxR1h3SURBUUFCbzNNd2NUQWRCZ05WSFE0RUZnUVU5NHU4WXlMdmE2MTJnT1pyCm44QnlFQ2NucVFjd1FnWURWUjBqQkRzd09ZQVU5NHU4WXlMdmE2MTJnT1pybjhCeUVDY25xUWVoRnFRVU1CSXgKRURBT0JnTlZCQU1NQjNSbGMzUXRZMkdDQ1FDb2wxWXVDUUtBY2pBTUJnTlZIUk1FQlRBREFRSC9NQTBHQ1NxRwpTSWIzRFFFQkN3VUFBNElCQVFER1JRZ1RtdzdVNXRQRHA5Q2psOXlLRW9Vd2pYWWM2UlAwdm1GSHpubXJ3dUVLCjFrTkVJNzhBTUw1MEpuS29CY0ljVDNEeGQ3TGdIbTNCRE5mVVh2anArNnZqaXhJYXR2UWhsSFNVaWIyZjJsSTkKVEMxNzVyNCtROFkzelc1RlFXSDdLK08vY3pJTGh5ei93aHRDUlFkQ29lS1dXZkFiby8wd0VSejZzNkhkVFJzNwpHcWlGNWZtWGp6S0lOcTBjMHRyZ0xtalNKd1hwSnU0ZnNGOEcyZUh4b2pOKzdJQ1FuSkg5cGRIRVpUQUtOL2ppCnIvem04RlZtd1kvdTBndEZneWVQY1ZWbXBqRm03Y0ZOSkc4Y2ZYd0QzcEFwVjhVOGNocTZGeFBHTkVvWFZnclMKY1VRMklaU0RJd1FFY3FvSzFKSGdCUWw2RXBaUVpWMW1DRklrdFBwSQotLS0tLUVORCBDRVJUSUZJQ0FURS0tLS0t +``` +### Example credentialSecret + +```yaml +apiVersion: v1 +kind: Secret +metadata: + name: creds +type: Opaque +data: + accessKey: + secretKey: +``` + +:::note + +To avoid encoding issues, the `credentialSecret` can be created with the below command, updating the values for `accessKey` and `secretKey`. + +```bash +kubectl create secret generic s3-creds \ + --from-literal=accessKey= \ + --from-literal=secretKey= +``` + +::: + +### IAM Permissions for EC2 Nodes to Access S3 + +There are two ways to set up the `rancher-backup` operator to use S3 as the backup storage location. + +One way is to configure the `credentialSecretName` in the Backup custom resource, which refers to AWS credentials that have access to S3. + +If the cluster nodes are in Amazon EC2, the S3 access can also be set up by assigning IAM permissions to the EC2 nodes so that they can access S3. + +To allow a node to access S3, follow the instructions in the [AWS documentation](https://aws.amazon.com/premiumsupport/knowledge-center/ec2-instance-access-s3-bucket/) to create an IAM role for EC2. When you add a custom policy to the role, add the following permissions, and replace the `Resource` with your bucket name: + +```json +{ + "Version": "2012-10-17", + "Statement": [ + { + "Effect": "Allow", + "Action": [ + "s3:ListBucket" + ], + "Resource": [ + "arn:aws:s3:::rancher-backups" + ] + }, + { + "Effect": "Allow", + "Action": [ + "s3:PutObject", + "s3:GetObject", + "s3:DeleteObject", + "s3:PutObjectAcl" + ], + "Resource": [ + "arn:aws:s3:::rancher-backups/*" + ] + } + ] +} +``` + +After the role is created, and you have attached the corresponding instance profile to your EC2 instance(s), the `credentialSecretName` directive can be left empty in the Backup custom resource. + +## Examples + +For example Backup custom resources, refer to [this page.](examples.md#backup) diff --git a/versioned_docs/version-2.14/reference-guides/backup-restore-configuration/backup-restore-configuration.md b/versioned_docs/version-2.14/reference-guides/backup-restore-configuration/backup-restore-configuration.md new file mode 100644 index 00000000000..ad817581489 --- /dev/null +++ b/versioned_docs/version-2.14/reference-guides/backup-restore-configuration/backup-restore-configuration.md @@ -0,0 +1,12 @@ +--- +title: Rancher Backup Configuration Reference +--- + + + + + +- [Backup configuration](backup-configuration.md) +- [Restore configuration](restore-configuration.md) +- [Storage location configuration](storage-configuration.md) +- [Example Backup and Restore Custom Resources](examples.md) \ No newline at end of file diff --git a/versioned_docs/version-2.14/reference-guides/backup-restore-configuration/examples.md b/versioned_docs/version-2.14/reference-guides/backup-restore-configuration/examples.md new file mode 100644 index 00000000000..542c49cc872 --- /dev/null +++ b/versioned_docs/version-2.14/reference-guides/backup-restore-configuration/examples.md @@ -0,0 +1,297 @@ +--- +title: Backup and Restore Examples +--- + + + + + +This section contains examples of Backup and Restore custom resources. + +The default backup storage location is configured when the `rancher-backup` operator is installed or upgraded. + +Encrypted backups can only be restored if the Restore custom resource uses the same encryption configuration secret that was used to create the backup. + +## Backup + +This section contains example Backup custom resources. + +>**Note:** Refer to the [backup config reference page](./backup-configuration.md) for more information on configuring the options below. + +### Backup in the Default Location with Encryption + +```yaml +apiVersion: resources.cattle.io/v1 +kind: Backup +metadata: + name: default-location-encrypted-backup +spec: + resourceSetName: rancher-resource-set-full + encryptionConfigSecretName: encryptionconfig +``` + +### Recurring Backup in the Default Location + +```yaml +apiVersion: resources.cattle.io/v1 +kind: Backup +metadata: + name: default-location-recurring-backup +spec: + resourceSetName: rancher-resource-set-basic + schedule: "@every 1h" + retentionCount: 10 +``` + +### Encrypted Recurring Backup in the Default Location + +```yaml +apiVersion: resources.cattle.io/v1 +kind: Backup +metadata: + name: default-enc-recurring-backup +spec: + resourceSetName: rancher-resource-set-full + encryptionConfigSecretName: encryptionconfig + schedule: "@every 1h" + retentionCount: 3 +``` + +### Encrypted Backup in Minio + +```yaml +apiVersion: resources.cattle.io/v1 +kind: Backup +metadata: + name: minio-backup +spec: + storageLocation: + s3: + credentialSecretName: minio-creds + credentialSecretNamespace: default + bucketName: rancherbackups + endpoint: minio.xip.io + endpointCA: + resourceSetName: rancher-resource-set-full + encryptionConfigSecretName: encryptionconfig +``` + +### Backup in S3 Using AWS Credential Secret + +```yaml +apiVersion: resources.cattle.io/v1 +kind: Backup +metadata: + name: s3-backup +spec: + storageLocation: + s3: + credentialSecretName: s3-creds + credentialSecretNamespace: default + bucketName: rancher-backups + folder: ecm1 + region: us-west-2 + endpoint: s3.us-west-2.amazonaws.com + resourceSetName: rancher-resource-set-full + encryptionConfigSecretName: encryptionconfig +``` + +### Recurring Backup in S3 Using AWS Credential Secret + +```yaml +apiVersion: resources.cattle.io/v1 +kind: Backup +metadata: + name: s3-recurring-backup +spec: + storageLocation: + s3: + credentialSecretName: s3-creds + credentialSecretNamespace: default + bucketName: rancher-backups + folder: ecm1 + region: us-west-2 + endpoint: s3.us-west-2.amazonaws.com + resourceSetName: rancher-resource-set-full + encryptionConfigSecretName: encryptionconfig + schedule: "@every 1h" + retentionCount: 10 +``` + +### Backup from EC2 Nodes with IAM Permission to Access S3 + +This example shows that the AWS credential secret does not have to be provided to create a backup if the nodes running `rancher-backup` have [these permissions for access to S3.](backup-configuration.md#iam-permissions-for-ec2-nodes-to-access-s3) + +```yaml +apiVersion: resources.cattle.io/v1 +kind: Backup +metadata: + name: s3-iam-backup +spec: + storageLocation: + s3: + bucketName: rancher-backups + folder: ecm1 + region: us-west-2 + endpoint: s3.us-west-2.amazonaws.com + resourceSetName: rancher-resource-set-full + encryptionConfigSecretName: encryptionconfig +``` + +## Restore + +This section contains example Restore custom resources. + +>**Note:** Refer to the [restore config reference page](./restore-configuration.md) for more information on configuring the options below. + +### Restore Using the Default Backup File Location + +```yaml +apiVersion: resources.cattle.io/v1 +kind: Restore +metadata: + name: restore-default +spec: + backupFilename: default-location-recurring-backup-752ecd87-d958-4d20-8350-072f8d090045-2020-09-26T12-29-54-07-00.tar.gz +# encryptionConfigSecretName: test-encryptionconfig +``` + +### Restore for Rancher Migration +```yaml +apiVersion: resources.cattle.io/v1 +kind: Restore +metadata: + name: restore-migration +spec: + backupFilename: backup-b0450532-cee1-4aa1-a881-f5f48a007b1c-2020-09-15T07-27-09Z.tar.gz + prune: false + storageLocation: + s3: + credentialSecretName: s3-creds + credentialSecretNamespace: default + bucketName: rancher-backups + folder: ecm1 + region: us-west-2 + endpoint: s3.us-west-2.amazonaws.com +``` + +### Restore from Encrypted Backup + +```yaml +apiVersion: resources.cattle.io/v1 +kind: Restore +metadata: + name: restore-encrypted +spec: + backupFilename: default-test-s3-def-backup-c583d8f2-6daf-4648-8ead-ed826c591471-2020-08-24T20-47-05Z.tar.gz + encryptionConfigSecretName: encryptionconfig +``` + +### Restore an Encrypted Backup from Minio + +```yaml +apiVersion: resources.cattle.io/v1 +kind: Restore +metadata: + name: restore-minio +spec: + backupFilename: default-minio-backup-demo-aa5c04b7-4dba-4c48-9ac4-ab7916812eaa-2020-08-30T13-18-17-07-00.tar.gz + storageLocation: + s3: + credentialSecretName: minio-creds + credentialSecretNamespace: default + bucketName: rancherbackups + endpoint: minio.xip.io + endpointCA: + encryptionConfigSecretName: test-encryptionconfig +``` + +### Restore from Backup Using an AWS Credential Secret to Access S3 + +```yaml +apiVersion: resources.cattle.io/v1 +kind: Restore +metadata: + name: restore-s3-demo +spec: + backupFilename: test-s3-recurring-backup-752ecd87-d958-4d20-8350-072f8d090045-2020-09-26T12-49-34-07-00.tar.gz.enc + storageLocation: + s3: + credentialSecretName: s3-creds + credentialSecretNamespace: default + bucketName: rancher-backups + folder: ecm1 + region: us-west-2 + endpoint: s3.us-west-2.amazonaws.com + encryptionConfigSecretName: test-encryptionconfig +``` + +### Restore from EC2 Nodes with IAM Permissions to Access S3 + +This example shows that the AWS credential secret does not have to be provided to restore from backup if the nodes running `rancher-backup` have [these permissions for access to S3.](backup-configuration.md#iam-permissions-for-ec2-nodes-to-access-s3) + +```yaml +apiVersion: resources.cattle.io/v1 +kind: Restore +metadata: + name: restore-s3-demo +spec: + backupFilename: default-test-s3-recurring-backup-84bf8dd8-0ef3-4240-8ad1-fc7ec308e216-2020-08-24T10#52#44-07#00.tar.gz + storageLocation: + s3: + bucketName: rajashree-backup-test + folder: ecm1 + region: us-west-2 + endpoint: s3.us-west-2.amazonaws.com + encryptionConfigSecretName: test-encryptionconfig +``` + +## Example EncryptionConfiguration + +The snippets below demonstrate two different types of secrets and their relevance with respect to Backup and Restore of custom resources. Creating the secret can be done with the following command: + +```plain +kubectl create secret generic example-encryptionconfig \ + --from-file=./encryption-provider-config.yaml \ + -n cattle-resources-system +``` + +The first example is that of a secret used to encrypt the backup files. The backup operator will read the contents of the **encryption-provider-config.yaml** key, which contains the definition of an EncryptionConfiguration resource encoded as Base64. + +The second example is that of the Kubernetes EncryptionConfiguration resource itself, being the plain-text form of the Base64-encoded content from the first example. This resource is also used to encrypt secrets when stored in etcd and general cases of Encryption at Rest in Kubernetes. More information on that can be found in the [upstream documentation](https://kubernetes.io/docs/tasks/administer-cluster/encrypt-data/). The keys defined in this resource are essential for accessing the contents of encrypted Backups, particularly during the Restore process. For that reason, these must be kept secure, confidential and easily retrievable. + +```yaml +apiVersion: v1 +data: + encryption-provider-config.yaml: YXBpVmVyc2lvbjogYXBpc2VydmVyLmNvbmZpZy5rOHMuaW8vdjEKa2luZDogRW5jcnlwdGlvbkNvbmZpZ3VyYXRpb24KcmVzb3VyY2VzOgogIC0gcmVzb3VyY2VzOgogICAgICAtIHNlY3JldHMKICAgIHByb3ZpZGVyczoKICAgICAgLSBhZXNnY206CiAgICAgICAgICBrZXlzOgogICAgICAgICAgICAtIG5hbWU6IGtleTEKICAgICAgICAgICAgICBzZWNyZXQ6IGMyVmpjbVYwSUdseklITmxZM1Z5WlE9PQogICAgICAgICAgICAtIG5hbWU6IGtleTIKICAgICAgICAgICAgICBzZWNyZXQ6IGRHaHBjeUJwY3lCd1lYTnpkMjl5WkE9PQogICAgICAtIGFlc2NiYzoKICAgICAgICAgIGtleXM6CiAgICAgICAgICAgIC0gbmFtZToga2V5MQogICAgICAgICAgICAgIHNlY3JldDogYzJWamNtVjBJR2x6SUhObFkzVnlaUT09CiAgICAgICAgICAgIC0gbmFtZToga2V5MgogICAgICAgICAgICAgIHNlY3JldDogZEdocGN5QnBjeUJ3WVhOemQyOXlaQT09CiAgICAgIC0gc2VjcmV0Ym94OgogICAgICAgICAga2V5czoKICAgICAgICAgICAgLSBuYW1lOiBrZXkxCiAgICAgICAgICAgICAgc2VjcmV0OiBZV0pqWkdWbVoyaHBhbXRzYlc1dmNIRnljM1IxZG5kNGVYb3hNak0wTlRZPQ== +kind: Secret +metadata: + name: example-encryptionconfig + namespace: cattle-resources-system +type: Opaque +``` + +```yaml +apiVersion: apiserver.config.k8s.io/v1 +kind: EncryptionConfiguration +resources: + - resources: + - secrets + providers: + - aesgcm: + keys: + - name: key1 + secret: c2VjcmV0IGlzIHNlY3VyZQ== + - name: key2 + secret: dGhpcyBpcyBwYXNzd29yZA== + - aescbc: + keys: + - name: key1 + secret: c2VjcmV0IGlzIHNlY3VyZQ== + - name: key2 + secret: dGhpcyBpcyBwYXNzd29yZA== + - secretbox: + keys: + - name: key1 + secret: YWJjZGVmZ2hpamtsbW5vcHFyc3R1dnd4eXoxMjM0NTY= +``` diff --git a/versioned_docs/version-2.14/reference-guides/backup-restore-configuration/restore-configuration.md b/versioned_docs/version-2.14/reference-guides/backup-restore-configuration/restore-configuration.md new file mode 100644 index 00000000000..b162a6ef873 --- /dev/null +++ b/versioned_docs/version-2.14/reference-guides/backup-restore-configuration/restore-configuration.md @@ -0,0 +1,85 @@ +--- +title: Restore Configuration +--- + + + + + +The Restore Create page lets you provide details of the backup to restore from + +![](/img/backup_restore/restore/restore.png) + + +## Backup Source +Provide details of the backup file and its storage location, which the operator will then use to perform the restore. Select from the following options to provide these details + + + + +### An existing backup config + +Selecting this option will populate the **Target Backup** dropdown with the Backups available in this cluster. Select the Backup from the dropdown, and that will fill out the **Backup Filename** field for you, and will also pass the backup source information from the selected Backup to the operator. + +![](/img/backup_restore/restore/existing.png) + +If the Backup custom resource does not exist in the cluster, you need to get the exact filename and provide the backup source details with the default storage target or an S3-compatible object store. + + +### The default storage target + +Select this option if you are restoring from a backup file that exists in the default storage location configured at the operator-level. The operator-level configuration is the storage location that was configured when the `rancher-backup` operator was installed or upgraded. Provide the exact filename in the **Backup Filename** field. + +![](/img/backup_restore/restore/default.png) + +### An S3-compatible object store + +Select this option if no default storage location is configured at the operator-level, OR if the backup file exists in a different S3 bucket than the one configured as the default storage location. Provide the exact filename in the **Backup Filename** field. Refer to [this section](#getting-the-backup-filename-from-s3) for exact steps on getting the backup filename from s3. Fill in all the details for the S3 compatible object store. Its fields are exactly same as ones for the `backup.StorageLocation` configuration in the [Backup custom resource.](backup-configuration.md#storage-location) + +![](/img/backup_restore/restore/s3store.png) + +## Encryption + +If the backup was created with encryption enabled, its file will have `.enc` suffix. Choosing such a Backup, or providing a backup filename with `.enc` suffix will display another dropdown named **Encryption Config Secret**. + +![](/img/backup_restore/restore/encryption.png) + +The Secret selected from this dropdown must have the same contents as the one used for the Backup custom resource while performing the backup. If the encryption configuration doesn't match, the restore will fail + +The `Encryption Config Secret` dropdown will filter out and list only those Secrets that have this exact key + +| YAML Directive Name | Description | +| ---------------- | ---------------- | +| `encryptionConfigSecretName` | Provide the name of the Secret from `cattle-resources-system` namespace, that contains the encryption config file. | + +:::note Important: + +This field should only be set if the backup was created with encryption enabled. Providing the incorrect encryption config will cause the restore to fail. + +::: + +## Prune During Restore + +* **Prune**: In order to fully restore Rancher from a backup, and to go back to the exact state it was at when the backup was performed, we need to delete any additional resources that were created by Rancher after the backup was taken. The operator does so if the **Prune** flag is enabled. Prune is enabled by default and it is recommended to keep it enabled. +* **Delete Timeout**: This is the amount of time the operator will wait while deleting a resource before editing the resource to remove finalizers and attempt deletion again. + +| YAML Directive Name | Description | +| ---------------- | ---------------- | +| `prune` | Delete the resources managed by Rancher that are not present in the backup (Recommended). | +| `deleteTimeoutSeconds` | Amount of time the operator will wait while deleting a resource before editing the resource to remove finalizers and attempt deletion again. | + +## Getting the Backup Filename from S3 + +This is the name of the backup file that the `rancher-backup` operator will use to perform the restore. + +To obtain this file name from S3, go to your S3 bucket (and folder if it was specified while performing backup). + +Copy the filename and store it in your Restore custom resource. So assuming the name of your backup file is `backupfile`, + +- If your bucket name is `s3bucket` and no folder was specified, then the `backupFilename` to use will be `backupfile`. +- If your bucket name is `s3bucket` and the base folder is`s3folder`, the `backupFilename` to use is only `backupfile` . +- If there is a subfolder inside `s3Folder` called `s3sub`, and that has your backup file, then the `backupFilename` to use is `s3sub/backupfile`. + +| YAML Directive Name | Description | +| ---------------- | ---------------- | +| `backupFilename` | This is the name of the backup file that the `rancher-backup` operator will use to perform the restore. | diff --git a/versioned_docs/version-2.14/reference-guides/backup-restore-configuration/storage-configuration.md b/versioned_docs/version-2.14/reference-guides/backup-restore-configuration/storage-configuration.md new file mode 100644 index 00000000000..64d9a810a44 --- /dev/null +++ b/versioned_docs/version-2.14/reference-guides/backup-restore-configuration/storage-configuration.md @@ -0,0 +1,59 @@ +--- +title: Backup Storage Location Configuration +--- + + + + + +Configure a storage location where all backups are saved by default. You will have the option to override this with each backup, but will be limited to using an S3-compatible object store. + +Only one storage location can be configured at the operator level. + + +## Storage Location Configuration + +### No Default Storage Location + +You can choose to not have any operator-level storage location configured. If you select this option, you must configure an S3-compatible object store as the storage location for each individual backup. + +### S3-compatible Object Store + +| Parameter | Description | +| -------------- | -------------- | +| Credential Secret | Choose the credentials for S3 from your secrets in Rancher. [Example](backup-configuration.md#example-credentialsecret). | +| Bucket Name | Enter the name of the [S3 bucket](https://docs.aws.amazon.com/AmazonS3/latest/dev/UsingBucket.html) where the backups will be stored. Default: `rancherbackups`. | +| Region | The [AWS region](https://aws.amazon.com/about-aws/global-infrastructure/regions_az/) where the S3 bucket is located. | +| Folder | The [folder in the S3 bucket](https://docs.aws.amazon.com/AmazonS3/latest/user-guide/using-folders.html) where the backups will be stored. If this field is left empty, the default behavior is to store the backup files in the root folder of the S3 bucket. | +| Endpoint | The [S3 endpoint](https://docs.aws.amazon.com/general/latest/gr/s3.html) For example, `s3.us-west-2.amazonaws.com`. | +| Endpoint CA | The CA cert used to for the S3 endpoint. Default: base64 encoded CA cert | +| insecureTLSSkipVerify | Set to true if you are not using TLS. | + +### Existing StorageClass + +Installing the `rancher-backup` chart by selecting the StorageClass option will create a Persistent Volume Claim (PVC), and Kubernetes will in turn dynamically provision a Persistent Volume (PV) where all the backups will be saved by default. + +For information about creating storage classes refer to [this section.](../../how-to-guides/new-user-guides/manage-clusters/create-kubernetes-persistent-storage/manage-persistent-storage/dynamically-provision-new-storage.md) + +:::note Important: + +It is highly recommended to use a StorageClass with a reclaim policy of "Retain". Otherwise if the PVC created by the `rancher-backup` chart gets deleted (either during app upgrade, or accidentally), the PV will get deleted too, which means all backups saved in it will get deleted. +If no such StorageClass is available, after the PV is provisioned, make sure to edit its reclaim policy and set it to "Retain" before storing backups in it. + +::: + +### Existing Persistent Volume + +Select an existing Persistent Volume (PV) that will be used to store your backups. For information about creating PersistentVolumes in Rancher, refer to [this section.](../../how-to-guides/new-user-guides/manage-clusters/create-kubernetes-persistent-storage/manage-persistent-storage/set-up-existing-storage.md#2-add-a-persistentvolume-that-refers-to-the-persistent-storage) + +:::note Important: + +It is highly recommended to use a Persistent Volume with a reclaim policy of "Retain". Otherwise if the PVC created by the `rancher-backup` chart gets deleted (either during app upgrade, or accidentally), the PV will get deleted too, which means all backups saved in it will get deleted. + +::: + +## Example YAML File: Rancher Backup Helm Chart + +The documented `values.yaml` file that can be used to configure the `backup-restore-operator` when the Helm CLI is used can be found in the [backup-restore-operator repository.](https://github.com/rancher/backup-restore-operator/blob/master/charts/rancher-backup/values.yaml) + +For more information about `values.yaml` files and configuring Helm charts during installation, refer to the [Helm documentation.](https://helm.sh/docs/intro/using_helm/#customizing-the-chart-before-installing) diff --git a/versioned_docs/version-2.14/reference-guides/best-practices/best-practices.md b/versioned_docs/version-2.14/reference-guides/best-practices/best-practices.md new file mode 100644 index 00000000000..c0b4a9cc233 --- /dev/null +++ b/versioned_docs/version-2.14/reference-guides/best-practices/best-practices.md @@ -0,0 +1,21 @@ +--- +title: Best Practice Guides +--- + + + + + +The purpose of this section is to consolidate best practices for Rancher implementations. This also includes recommendations for related technologies, such as Kubernetes, Docker, containers, and more. The objective is to improve the outcome of a Rancher implementation using the operational experience of Rancher and its customers. + +If you have any questions about how these might apply to your use case, please contact your Customer Success Manager or Support. + +Use the navigation bar on the left to find the current best practices for managing and deploying the Rancher Server. + +For more guidance on best practices, you can consult these resources: + +- [Security](../rancher-security/rancher-security.md) +- [Rancher Blog](https://www.suse.com/c/rancherblog/) +- [Rancher Forum](https://forums.rancher.com/) +- [Rancher Users Slack](https://slack.rancher.io/) +- [Rancher Labs YouTube Channel - Online Meetups, Demos, Training, and Webinars](https://www.youtube.com/channel/UCh5Xtp82q8wjijP8npkVTBA/featured) diff --git a/versioned_docs/version-2.14/reference-guides/best-practices/rancher-managed-clusters/disconnected-clusters.md b/versioned_docs/version-2.14/reference-guides/best-practices/rancher-managed-clusters/disconnected-clusters.md new file mode 100644 index 00000000000..e0b9eb6757f --- /dev/null +++ b/versioned_docs/version-2.14/reference-guides/best-practices/rancher-managed-clusters/disconnected-clusters.md @@ -0,0 +1,19 @@ +--- +title: Best Practices for Disconnected Clusters +--- + + + + + +Rancher supports managing clusters that may not always be online due to network disruptions, control plane availability, or because all cluster nodes are down. At the moment there are no known issues with disconnected clusters in the latest released Rancher version. + +While a managed cluster is disconnected from Rancher, management operations will be unavailable, and the Rancher UI will not allow navigation to the cluster. However, once the connection is reestablished, functionality is fully restored. + +### Best Practices for Managing Disconnected Clusters + +- **Cluster Availability During Rancher Upgrades**: It is recommended to have all, or at least most, managed clusters online during a Rancher upgrade. The reason is that upgrading Rancher automatically upgrades the Rancher agent software running on managed clusters. Keeping the agent and Rancher versions aligned ensures consistent functionality. Any clusters that are disconnected during the upgrade will have their agents updated as soon as they reconnect. + +- **Cleaning Up Disconnected Clusters**: Regularly remove clusters that will no longer reconnect to Rancher (e.g., clusters that have been decommissioned or destroyed). Keeping such clusters in the Rancher management system consumes unnecessary resources, which could impact Rancher's performance over time. + +- **Certificate Rotation Considerations**: When designing processes that involve regularly shutting down clusters, whether connected to Rancher or not, take into account certificate rotation policies. For example, RKE2/K3s clusters may rotate certificates on startup if they exceeded their lifetime. diff --git a/versioned_docs/version-2.14/reference-guides/best-practices/rancher-managed-clusters/logging-best-practices.md b/versioned_docs/version-2.14/reference-guides/best-practices/rancher-managed-clusters/logging-best-practices.md new file mode 100644 index 00000000000..7fda8ae4c35 --- /dev/null +++ b/versioned_docs/version-2.14/reference-guides/best-practices/rancher-managed-clusters/logging-best-practices.md @@ -0,0 +1,90 @@ +--- +title: Logging Best Practices +--- + + + + + +In this guide, we recommend best practices for cluster-level logging and application logging. + +- [Cluster-level Logging](#cluster-level-logging) +- [Application Logging](#application-logging) +- [General Best Practices](#general-best-practices) + +Before Rancher v2.5, logging in Rancher has historically been a pretty static integration. There were a fixed list of aggregators to choose from (ElasticSearch, Splunk, Kafka, Fluentd and Syslog), and only two configuration points to choose (Cluster-level and Project-level). + +Rancher provides a flexible experience for log aggregation. With the logging feature, administrators and users alike can deploy logging that meets fine-grained collection criteria while offering a wider array of destinations and configuration options. + +"Under the hood", Rancher logging uses the [Logging operator](https://github.com/kube-logging/logging-operator). We provide manageability of this operator (and its resources), and tie that experience in with managing your Rancher clusters. + +## Cluster-level Logging + +### Cluster-wide Scraping + +For some users, it is desirable to scrape logs from every container running in the cluster. This usually coincides with your security team's request (or requirement) to collect all logs from all points of execution. + +In this scenario, it is recommended to create at least two _ClusterOutput_ objects - one for your security team (if you have that requirement), and one for yourselves, the cluster administrators. When creating these objects take care to choose an output endpoint that can handle the significant log traffic coming from the entire cluster. Also make sure to choose an appropriate index to receive all these logs. + +Once you have created these _ClusterOutput_ objects, create a _ClusterFlow_ to collect all the logs. Do not define any _Include_ or _Exclude_ rules on this flow. This will ensure that all logs from across the cluster are collected. If you have two _ClusterOutputs_, make sure to send logs to both of them. + +### Kubernetes Components + +_ClusterFlows_ have the ability to collect logs from all containers on all hosts in the Kubernetes cluster. This works well in cases where those containers are part of a Kubernetes pod. + +A future release of Rancher will include the source container name which will enable filtering of these component logs. Once that change is made, you will be able to customize a _ClusterFlow_ to retrieve **only** the Kubernetes component logs, and direct them to an appropriate output. + +## Application Logging + +Best practice not only in Kubernetes but in all container-based applications is to direct application logs to `stdout`/`stderr`. The container runtime will then trap these logs and do **something** with them - typically writing them to a file. Depending on the container runtime (and its configuration), these logs can end up in any number of locations. + +In the case of writing the logs to a file, Kubernetes helps by creating a `/var/log/containers` directory on each host. This directory symlinks the log files to their actual destination (which can differ based on configuration or container runtime). + +Rancher logging will read all log entries in `/var/log/containers`, ensuring that all log entries from all containers (assuming a default configuration) will have the opportunity to be collected and processed. + +### Specific Log Files + +Log collection only retrieves `stdout`/`stderr` logs from pods in Kubernetes. But what if we want to collect logs from other files that are generated by applications? Here, a log streaming sidecar (or two) may come in handy. + +The goal of setting up a streaming sidecar is to take log files that are written to disk, and have their contents streamed to `stdout`. This way, the Logging Operator can pick up those logs and send them to your desired output. + +To set this up, edit your workload resource (e.g. Deployment) and add the following sidecar definition: + +```yaml +... +containers: +- args: + - -F + - /path/to/your/log/file.log + command: + - tail + image: busybox + name: stream-log-file-[name] + volumeMounts: + - mountPath: /path/to/your/log + name: mounted-log +... +``` + +This will add a container to your workload definition that will now stream the contents of (in this example) `/path/to/your/log/file.log` to `stdout`. + +This log stream is then automatically collected according to any _Flows_ or _ClusterFlows_ you have setup. You may also wish to consider creating a _Flow_ specifically for this log file by targeting the name of the container. See example: + +```yaml +... +spec: + match: + - select: + container_names: + - stream-log-file-name +... +``` + + +## General Best Practices + +- Where possible, output structured log entries (e.g. `syslog`, JSON). This makes handling of the log entry easier as there are already parsers written for these formats. +- Try to provide the name of the application that is creating the log entry, in the entry itself. This can make troubleshooting easier as Kubernetes objects do not always carry the name of the application as the object name. For instance, a pod ID may be something like `myapp-098kjhsdf098sdf98` which does not provide much information about the application running inside the container. +- Except in the case of collecting all logs cluster-wide, try to scope your _Flow_ and _ClusterFlow_ objects tightly. This makes it easier to troubleshoot when problems arise, and also helps ensure unrelated log entries do not show up in your aggregator. An example of tight scoping would be to constrain a _Flow_ to a single _Deployment_ in a namespace, or perhaps even a single container within a _Pod_. +- Keep the log verbosity down except when troubleshooting. High log verbosity poses a number of issues, chief among them being **noise**: significant events can be drowned out in a sea of `DEBUG` messages. This is somewhat mitigated with automated alerting and scripting, but highly verbose logging still places an inordinate amount of stress on the logging infrastructure. +- Where possible, try to provide a transaction or request ID with the log entry. This can make tracing application activity across multiple log sources easier, especially when dealing with distributed applications. diff --git a/versioned_docs/version-2.14/reference-guides/best-practices/rancher-managed-clusters/monitoring-best-practices.md b/versioned_docs/version-2.14/reference-guides/best-practices/rancher-managed-clusters/monitoring-best-practices.md new file mode 100644 index 00000000000..9234765e61f --- /dev/null +++ b/versioned_docs/version-2.14/reference-guides/best-practices/rancher-managed-clusters/monitoring-best-practices.md @@ -0,0 +1,115 @@ +--- +title: Monitoring Best Practices +--- + + + + + +Configuring sensible monitoring and alerting rules is vital for running any production workloads securely and reliably. This is not different when using Kubernetes and Rancher. Fortunately the integrated monitoring and alerting functionality makes this whole process a lot easier. + +The [Rancher monitoring documentation](../../../integrations-in-rancher/monitoring-and-alerting/monitoring-and-alerting.md) describes how you can set up a complete Prometheus and Grafana stack. Out of the box this will scrape monitoring data from all system and Kubernetes components in your cluster and provide sensible dashboards and alerts for them to get started. But for a reliable setup, you also need to monitor your own workloads and adapt Prometheus and Grafana to your own specific use cases and cluster sizes. This document aims to give you best practices for this. + +## What to Monitor + +Kubernetes itself, as well as applications running inside of it, form a distributed system where different components interact with each other. For the whole system and each individual component, you have to ensure performance, availability, reliability and scalability. A good resource with more details and information is Google's free [Site Reliability Engineering Book](https://sre.google/sre-book/table-of-contents/), especially the chapter about [Monitoring distributed systems](https://sre.google/sre-book/monitoring-distributed-systems/). + +## Configuring Prometheus Resource Usage + +When installing the integrated monitoring stack, Rancher allows to configure several settings that are dependent on the size of your cluster and the workloads running in it. This chapter covers these in more detail. + +### Storage and Data Retention + +The amount of storage needed for Prometheus directly correlates to the amount of time series and labels that you store and the data retention you have configured. It is important to note that Prometheus is not meant to be used as a long-term metrics storage. Data retention time is usually only a couple of days and not weeks or months. The reason for this is that Prometheus does not perform any aggregation on its stored metrics. This is great because aggregation can dilute data, but it also means that the needed storage grows linearly over time without retention. + +One way to calculate the necessary storage is to look at the average size of a storage chunk in Prometheus with this query + +``` +rate(prometheus_tsdb_compaction_chunk_size_bytes_sum[1h]) / rate(prometheus_tsdb_compaction_chunk_samples_sum[1h]) +``` + +Next, find out your data ingestion rate per second: + +``` +rate(prometheus_tsdb_head_samples_appended_total[1h]) +``` + +and then multiply this with the retention time, adding a few percentage points as buffer: + +``` +average chunk size in bytes * ingestion rate per second * retention time in seconds * 1.1 = necessary storage in bytes +``` + +You can find more information about how to calculate the necessary storage in this [blog post](https://www.robustperception.io/how-much-disk-space-do-prometheus-blocks-use). + +You can read more about the Prometheus storage concept in the [Prometheus documentation](https://prometheus.io/docs/prometheus/latest/storage). + +### CPU and Memory Requests and Limits + +In larger Kubernetes clusters Prometheus can consume quite a bit of memory. The amount of memory Prometheus needs directly correlates to the amount of time series and amount of labels it stores and the scrape interval in which these are filled. + +You can find more information about how to calculate the necessary memory in this [blog post](https://www.robustperception.io/how-much-ram-does-prometheus-2-x-need-for-cardinality-and-ingestion). + +The amount of necessary CPUs correlate with the amount of queries you are performing. + +### Federation and Long-term Storage + +Prometheus is not meant to store metrics for a long amount of time, but should only be used for short term storage. + +In order to store some, or all metrics for a long time, you can leverage Prometheus' [remote read/write](https://prometheus.io/docs/prometheus/latest/storage/#remote-storage-integrations) capabilities to connect it to storage systems like [Thanos](https://thanos.io/), [InfluxDB](https://www.influxdata.com/), [M3DB](https://www.m3db.io/), or others. You can find an example setup in this [blog post](https://rancher.com/blog/2020/prometheus-metric-federation). + +## Scraping Custom Workloads + +While the integrated Rancher Monitoring already scrapes system metrics from a cluster's nodes and system components, the custom workloads that you deploy on Kubernetes should also be scraped for data. For that you can configure Prometheus to do an HTTP request to an endpoint of your applications in a certain interval. These endpoints should then return their metrics in a Prometheus format. + +In general, you want to scrape data from all the workloads running in your cluster so that you can use them for alerts or debugging issues. Often, you recognize that you need some data only when you actually need the metrics during an incident. It is good, if it is already scraped and stored. Since Prometheus is only meant to be a short-term metrics storage, scraping and keeping lots of data is usually not that expensive. If you are using a long-term storage solution with Prometheus, you can then still decide which data you are actually persisting and keeping there. + +### About Prometheus Exporters + +Many 3rd party workloads, such as databases, queues, and web-servers, already support exposing metrics in a Prometheus format, or offer exporters that translate between the tool's metrics and a format that Prometheus understands. You can usually add these exporters as additional sidecar containers to the workload's Pods. Many Helm charts already include options to deploy the correct exporter. You can find a curated list of exports on [ExporterHub](https://exporterhub.io/). + +### Prometheus support in Programming Languages and Frameworks + +To get your own custom application metrics into Prometheus, you have to collect and expose these metrics directly from your application's code. Fortunately, there are already libraries and integrations available to help with this for most popular programming languages and frameworks. One example for this is the Prometheus support in the [Spring Framework](https://docs.spring.io/spring-metrics/docs/current/public/prometheus). + +### ServiceMonitors and PodMonitors + +Once all of your workloads expose metrics in a Prometheus format, you must configure Prometheus to scrape them. Under the hood, Rancher uses the [prometheus-operator](https://github.com/prometheus-operator/prometheus-operator). This makes it easy to add scraping targets with ServiceMonitors and PodMonitors. Many Helm charts already include an option to create these monitors directly. You can also find more information in the Rancher documentation. + +### Prometheus Push Gateway + +There are some workloads that are traditionally hard to scrape by Prometheus. Examples for these are short lived workloads like Jobs and CronJobs, or applications that do not allow sharing data between individual handled incoming requests, like PHP applications. + +To still get metrics for these use cases, you can set up [prometheus-pushgateways](https://github.com/prometheus/pushgateway). The CronJob or PHP application would push metric updates to the pushgateway. The pushgateway aggregates and exposes them through an HTTP endpoint, which then can be scraped by Prometheus. + +### Prometheus Blackbox Monitor + +Sometimes it is useful to monitor workloads from the outside. For this, you can use the [Prometheus blackbox-exporter](https://github.com/prometheus/blackbox_exporter) which allows probing any kind of endpoint over HTTP, HTTPS, DNS, TCP and ICMP. + +## Monitoring in a (Micro)Service Architecture + +If you have a (micro)service architecture where multiple individual workloads within your cluster are communicating with each other, it is really important to have detailed metrics and traces about this traffic to understand how all these workloads are communicating with each other and where a problem or bottleneck may be. + +Of course you can monitor all this internal traffic in all your workloads and expose these metrics to Prometheus. But this can quickly become quite work intensive. Service Meshes like Istio, which can be installed with [a click](../../../integrations-in-rancher/istio/istio.md) in Rancher, can do this automatically and provide rich telemetry about the traffic between all services. + +## Real User Monitoring + +Monitoring the availability and performance of all your internal workloads is vitally important to run stable, reliable and fast applications. But these metrics only show you parts of the picture. To get a complete view it is also necessary to know how your end users are actually perceiving it. For this you can look into various [Real user monitoring solutions](https://en.wikipedia.org/wiki/Real_user_monitoring). + +## Security Monitoring + +In addition to monitoring workloads to detect performance, availability or scalability problems, the cluster and the workloads running into it should also be monitored for potential security problems. A good starting point is to frequently run and alert on [Compliance Scans](../../../how-to-guides/advanced-user-guides/compliance-scan-guides/compliance-scan-guides.md) which check if the cluster is configured according to security best practices. + +For the workloads, you can have a look at Kubernetes and Container security solutions like [NeuVector](https://www.suse.com/products/neuvector/), [Falco](https://falco.org/), [Aqua Kubernetes Security](https://www.aquasec.com/products/kubernetes-security/), [SysDig](https://sysdig.com/). + +## Setting up Alerts + +Getting all the metrics into a monitoring systems and visualizing them in dashboards is great, but you also want to be pro-actively alerted if something goes wrong. + +The integrated Rancher monitoring already configures a sensible set of alerts that make sense in any Kubernetes cluster. You should extend these to cover your specific workloads and use cases. + +When setting up alerts, configure them for all the workloads that are critical to the availability of your applications. But also make sure that they are not too noisy. Ideally every alert you are receiving should be because of a problem that needs your attention and needs to be fixed. If you have alerts that are firing all the time but are not that critical, there is a danger that you start ignoring your alerts all together and then miss the real important ones. Less may be more here. Start to focus on the real important metrics first, for example alert if your application is offline. Fix all the problems that start to pop up and then start to create more detailed alerts. + +If an alert starts firing, but there is nothing you can do about it at the moment, it's also fine to silence the alert for a certain amount of time, so that you can look at it later. + +You can find more information on how to set up alerts and notification channels in the [Rancher Documentation](../../../integrations-in-rancher/monitoring-and-alerting/monitoring-and-alerting.md). diff --git a/versioned_docs/version-2.14/reference-guides/best-practices/rancher-managed-clusters/rancher-managed-clusters-in-vsphere.md b/versioned_docs/version-2.14/reference-guides/best-practices/rancher-managed-clusters/rancher-managed-clusters-in-vsphere.md new file mode 100644 index 00000000000..73242a90abb --- /dev/null +++ b/versioned_docs/version-2.14/reference-guides/best-practices/rancher-managed-clusters/rancher-managed-clusters-in-vsphere.md @@ -0,0 +1,62 @@ +--- +title: Best Practices for Rancher Managed VMware vSphere Clusters +--- + + + + + +This guide outlines a reference architecture for provisioning downstream Rancher clusters in a vSphere environment, in addition to standard vSphere best practices as documented by VMware. + +- [1. VM Considerations](#1-vm-considerations) +- [2. Network Considerations](#2-network-considerations) +- [3. Storage Considerations](#3-storage-considerations) +- [4. Backups and Disaster Recovery](#4-backups-and-disaster-recovery) + +
Solution Overview
+ +![Solution Overview](/img/solution_overview.drawio.svg) + +## 1. VM Considerations + +### Leverage VM Templates to Construct the Environment + +To facilitate consistency across the deployed Virtual Machines across the environment, consider the use of "Golden Images" in the form of VM templates. Packer can be used to accomplish this, adding greater customisation options. + +### Leverage DRS Anti-Affinity Rules (Where Possible) to Separate Downstream Cluster Nodes Across ESXi Hosts + +Doing so will ensure node VM's are spread across multiple ESXi hosts - preventing a single point of failure at the host level. + +### Leverage DRS Anti-Affinity Rules (Where Possible) to Separate Downstream Cluster Nodes Across Datastores + +Doing so will ensure node VM's are spread across multiple datastores - preventing a single point of failure at the datastore level. + +### Configure VM's as Appropriate for Kubernetes + +It’s important to follow K8s and etcd best practices when deploying your nodes, including disabling swap, double-checking you have full network connectivity between all machines in the cluster, using unique hostnames, MAC addresses, and product_uuids for every node. + +## 2. Network Considerations + +### Leverage Low Latency, High Bandwidth Connectivity Between ETCD Nodes + +Deploy etcd members within a single data center where possible to avoid latency overheads and reduce the likelihood of network partitioning. For most setups, 1Gb connections will suffice. For large clusters, 10Gb connections can reduce the time taken to restore from backup. + +### Consistent IP Addressing for VM's + +Each node used should have a static IP configured. In the case of DHCP, each node should have a DHCP reservation to make sure the node gets the same IP allocated. + +## 3. Storage Considerations + +### Leverage SSD Drives for ETCD Nodes + +ETCD is very sensitive to write latency. Therefore, leverage SSD disks where possible. + +## 4. Backups and Disaster Recovery + +### Perform Regular Downstream Cluster Backups + +Kubernetes uses etcd to store all its data - from configuration, state and metadata. Backing this up is crucial in the event of disaster recovery. + +### Back up Downstream Node VMs + +Incorporate the Rancher downstream node VM's within a standard VM backup policy. \ No newline at end of file diff --git a/versioned_docs/version-2.14/reference-guides/best-practices/rancher-managed-clusters/rancher-managed-clusters.md b/versioned_docs/version-2.14/reference-guides/best-practices/rancher-managed-clusters/rancher-managed-clusters.md new file mode 100644 index 00000000000..c0bdf07d88d --- /dev/null +++ b/versioned_docs/version-2.14/reference-guides/best-practices/rancher-managed-clusters/rancher-managed-clusters.md @@ -0,0 +1,27 @@ +--- +title: Best Practices for Rancher Managed Clusters +--- + + + + + +### Logging + +Refer to [this guide](logging-best-practices.md) for our recommendations for cluster-level logging and application logging. + +### Monitoring + +Configuring sensible monitoring and alerting rules is vital for running any production workloads securely and reliably. Refer to this [guide](monitoring-best-practices.md) for our recommendations. + +### Disconnected clusters + +Rancher supports managing clusters that may not always be online due to network disruptions, control plane availability, or because all cluster nodes are down. Refer to this [guide](disconnected-clusters.md) for our recommendations. + +### Tips for Setting Up Containers + +Running well-built containers can greatly impact the overall performance and security of your environment. Refer to this [guide](tips-to-set-up-containers.md) for tips. + +### Best Practices for Rancher Managed VMware vSphere Clusters + +This [guide](rancher-managed-clusters-in-vsphere.md) outlines a reference architecture for provisioning downstream Rancher clusters in a vSphere environment, in addition to standard vSphere best practices as documented by VMware. diff --git a/versioned_docs/version-2.14/reference-guides/best-practices/rancher-managed-clusters/tips-to-set-up-containers.md b/versioned_docs/version-2.14/reference-guides/best-practices/rancher-managed-clusters/tips-to-set-up-containers.md new file mode 100644 index 00000000000..0cec0a91864 --- /dev/null +++ b/versioned_docs/version-2.14/reference-guides/best-practices/rancher-managed-clusters/tips-to-set-up-containers.md @@ -0,0 +1,56 @@ +--- +title: Tips for Setting Up Containers +--- + + + + + +Running well-built containers can greatly impact the overall performance and security of your environment. + +Below are a few tips for setting up your containers. + +For a more detailed discussion of security for containers, you can also refer to Rancher's [Guide to Container Security.](https://rancher.com/complete-guide-container-security) + +### Use a Common Container OS + +When possible, you should try to standardize on a common container base OS. + +Smaller distributions such as Alpine and BusyBox reduce container image size and generally have a smaller attack/vulnerability surface. + +Popular distributions such as Ubuntu, Fedora, and CentOS are more field-tested and offer more functionality. + +### Start with a FROM scratch container +If your microservice is a standalone static binary, you should use a FROM scratch container. + +The FROM scratch container is an [official Docker image](https://hub.docker.com/_/scratch) that is empty so that you can use it to design minimal images. + +This will have the smallest attack surface and smallest image size. + +### Run Container Processes as Unprivileged +When possible, use a non-privileged user when running processes within your container. While container runtimes provide isolation, vulnerabilities and attacks are still possible. Inadvertent or accidental host mounts can also be impacted if the container is running as root. For details on configuring a security context for a pod or container, refer to the [Kubernetes docs](https://kubernetes.io/docs/tasks/configure-pod-container/security-context/). + +### Define Resource Limits +Apply CPU and memory limits to your pods. This can help manage the resources on your worker nodes and avoid a malfunctioning microservice from impacting other microservices. + +In standard Kubernetes, you can set resource limits on the namespace level. In Rancher, you can set resource limits on the project level and they will propagate to all the namespaces within the project. For details, refer to the Rancher docs. + +When setting resource quotas, if you set anything related to CPU or Memory (i.e. limits or reservations) on a project or namespace, all containers will require a respective CPU or Memory field set during creation. To avoid setting these limits on each and every container during workload creation, a default container resource limit can be specified on the namespace. + +The Kubernetes docs have more information on how resource limits can be set at the [container level](https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container/#resource-requests-and-limits-of-pod-and-container) and the namespace level. + +### Define Resource Requirements +You should apply CPU and memory requirements to your pods. This is crucial for informing the scheduler which type of compute node your pod needs to be placed on, and ensuring it does not over-provision that node. In Kubernetes, you can set a resource requirement by defining `resources.requests` in the resource requests field in a pod's container spec. For details, refer to the [Kubernetes docs](https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container/#resource-requests-and-limits-of-pod-and-container). + +:::note + +If you set a resource limit for the namespace that the pod is deployed in, and the container doesn't have a specific resource request, the pod will not be allowed to start. To avoid setting these fields on each and every container during workload creation, a default container resource limit can be specified on the namespace. + +::: + +It is recommended to define resource requirements on the container level because otherwise, the scheduler makes assumptions that will likely not be helpful to your application when the cluster experiences load. + +### Liveness and Readiness Probes +Set up liveness and readiness probes for your container. Unless your container completely crashes, Kubernetes will not know it's unhealthy unless you create an endpoint or mechanism that can report container status. Alternatively, make sure your container halts and crashes if unhealthy. + +The Kubernetes docs show how to [configure liveness and readiness probes for containers.](https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-probes/) diff --git a/versioned_docs/version-2.14/reference-guides/best-practices/rancher-server/on-premises-rancher-in-vsphere.md b/versioned_docs/version-2.14/reference-guides/best-practices/rancher-server/on-premises-rancher-in-vsphere.md new file mode 100644 index 00000000000..b5b412a1bef --- /dev/null +++ b/versioned_docs/version-2.14/reference-guides/best-practices/rancher-server/on-premises-rancher-in-vsphere.md @@ -0,0 +1,88 @@ +--- +title: Installing Rancher in a VMware vSphere Environment +--- + + + + + +This guide outlines a reference architecture for installing Rancher on an RKE Kubernetes cluster in a VMware vSphere environment. It also desctibes standard vSphere best practices as documented by VMware. + + +
Solution Overview
+ +![Solution Overview](/img/rancher-on-prem-vsphere.svg) + +## 1. Load Balancer Considerations + +A load balancer is required to direct traffic to the Rancher workloads residing on the RKE nodes. + +### Leverage Fault Tolerance and High Availability + +Leverage the use of an external (hardware or software) load balancer that has inherit high-availability functionality (F5, NSX-T, Keepalived, etc). + +### Back Up Load Balancer Configuration + +In the event of a Disaster Recovery activity, availability of the Load balancer configuration will expedite the recovery process. + +### Configure Health Checks + +Configure the Load balancer to automatically mark nodes as unavailable if a health check is failed. For example, NGINX can facilitate this with: + +`max_fails=3 fail_timeout=5s` + +### Leverage an External Load Balancer + +Avoid implementing a software load balancer within the management cluster. + +### Secure Access to Rancher + +Configure appropriate Firewall / ACL rules to only expose access to Rancher + +## 2. VM Considerations + +### Size the VM's According to Rancher Documentation + +See [Installation Requirements](../../../getting-started/installation-and-upgrade/installation-requirements/installation-requirements.md). + +### Leverage VM Templates to Construct the Environment + +To facilitate the consistency of Virtual Machines deployed across the environment, consider the use of "Golden Images" in the form of VM templates. Packer can be used to accomplish this, adding greater customization options. + +### Leverage DRS Anti-Affinity Rules (Where Possible) to Separate Rancher Cluster Nodes Across ESXi Hosts + +Doing so will ensure node VM's are spread across multiple ESXi hosts - preventing a single point of failure at the host level. + +### Leverage DRS Anti-Affinity Rules (Where Possible) to Separate Rancher Cluster Nodes Across Datastores + +Doing so will ensure node VM's are spread across multiple datastores - preventing a single point of failure at the datastore level. + +### Configure VM's as Appropriate for Kubernetes + +It’s important to follow K8s and etcd best practices when deploying your nodes, including disabling swap, double-checking you have full network connectivity between all machines in the cluster, using unique hostnames, MAC addresses, and product_uuids for every node. + +## 3. Network Considerations + +### Leverage Low Latency, High Bandwidth Connectivity Between ETCD Nodes + +Deploy etcd members within a single data center where possible to avoid latency overheads and reduce the likelihood of network partitioning. For most setups, 1Gb connections will suffice. For large clusters, 10Gb connections can reduce the time taken to restore from backup. + +### Consistent IP Addressing for VM's + +Each node used should have a static IP configured. In the case of DHCP, each node should have a DHCP reservation to make sure the node gets the same IP allocated. + +## 4. Storage Considerations + +### Leverage SSD Drives for ETCD Nodes + +ETCD is very sensitive to write latency. Therefore, leverage SSD disks where possible. + +## 5. Backups and Disaster Recovery + +### Perform Regular Management Cluster Backups + +Rancher stores its data in the ETCD datastore of the Kubernetes cluster it resides on. Like with any Kubernetes cluster, perform frequent, tested backups of this cluster. + +### Back up Rancher Cluster Node VMs + +Incorporate the Rancher management node VM's within a standard VM backup policy. diff --git a/versioned_docs/version-2.14/reference-guides/best-practices/rancher-server/rancher-deployment-strategy.md b/versioned_docs/version-2.14/reference-guides/best-practices/rancher-server/rancher-deployment-strategy.md new file mode 100644 index 00000000000..99583f75579 --- /dev/null +++ b/versioned_docs/version-2.14/reference-guides/best-practices/rancher-server/rancher-deployment-strategy.md @@ -0,0 +1,40 @@ +--- +title: Rancher Deployment Strategy +--- + + + + + +There are two recommended deployment strategies for a Rancher instance that manages downstream Kubernetes clusters. Each one has its own pros and cons. Read more about which one would fit best for your use case. + +## Hub & Spoke Strategy +--- + +In this deployment scenario, there is a single Rancher instance managing Kubernetes clusters across the globe. The Rancher instance would be run on a high-availability Kubernetes cluster, and there would be impact due to latencies. + +### Pros + +* Single control plane interface to view/see all regions and environments. +* Kubernetes does not require Rancher to operate and can tolerate losing connectivity to the Rancher instance. + +### Cons + +* Subject to network latencies. +* If Rancher goes down, global provisioning of new services is unavailable until it is restored. However, each Kubernetes cluster can continue to be managed individually. + +## Regional Strategy +--- +In the regional deployment model a Rancher instance is deployed in close proximity to the downstream Kubernetes clusters. + +### Pros + +* Rancher functionality in regions stay operational if a Rancher instance in another region goes down. +* Network latency between Rancher and downstream clusters is greatly reduced, improving the performance of functionality in Rancher. +* Upgrades of Rancher can be done independently per region. + +### Cons + +* Overhead of managing multiple Rancher installations. +* Visibility into Kubernetes clusters in different regions requires multiple interfaces/panes of glass. +* Deploying multi-cluster apps in Rancher requires repeating the process for each Rancher server. diff --git a/versioned_docs/version-2.14/reference-guides/best-practices/rancher-server/rancher-server.md b/versioned_docs/version-2.14/reference-guides/best-practices/rancher-server/rancher-server.md new file mode 100644 index 00000000000..3ebebc02958 --- /dev/null +++ b/versioned_docs/version-2.14/reference-guides/best-practices/rancher-server/rancher-server.md @@ -0,0 +1,21 @@ +--- +title: Best Practices for the Rancher Server +--- + + + + + +This guide contains our recommendations for running the Rancher server, and is intended to be used in situations in which Rancher manages downstream Kubernetes clusters. + +### Recommended Architecture and Infrastructure + +Refer to this [guide](tips-for-running-rancher.md) for our general advice for setting up the Rancher server for a production installation. + +### Deployment Strategies + +This [guide](rancher-deployment-strategy.md) is designed to help you choose whether a regional deployment strategy or a hub-and-spoke deployment strategy is better for a Rancher server that manages downstream Kubernetes clusters. + +### Installing Rancher in a VMware vSphere Environment + +This [guide](on-premises-rancher-in-vsphere.md) outlines a reference architecture for installing Rancher in a vSphere environment, in addition to standard vSphere best practices as documented by VMware. \ No newline at end of file diff --git a/versioned_docs/version-2.14/reference-guides/best-practices/rancher-server/tips-for-running-rancher.md b/versioned_docs/version-2.14/reference-guides/best-practices/rancher-server/tips-for-running-rancher.md new file mode 100644 index 00000000000..877b5084bf9 --- /dev/null +++ b/versioned_docs/version-2.14/reference-guides/best-practices/rancher-server/tips-for-running-rancher.md @@ -0,0 +1,70 @@ +--- +title: Tips for Running Rancher +--- + + + + + +This guide is geared toward use cases where Rancher is used to manage downstream Kubernetes clusters. The high-availability setup is intended to prevent losing access to downstream clusters if the Rancher server is not available. + +A high-availability Kubernetes installation, defined as an installation of Rancher on a Kubernetes cluster with at least three nodes, should be used in any production installation of Rancher, as well as any installation deemed "important." Multiple Rancher instances running on multiple nodes ensure high availability that cannot be accomplished with a single node environment. + +If you are installing Rancher in a vSphere environment, refer to the best practices documented [here.](on-premises-rancher-in-vsphere.md) + +When you set up your high-availability Rancher installation, consider the following: + +### Minimize Third-Party Software on the Upstream Cluster + +We generally recommend running Rancher on a dedicated cluster, free of other workloads, to avoid potential performance and compatibility issues. + +Rancher, especially when managing a growing number of clusters, nodes, and workloads, places a significant load on core Kubernetes components like `etcd` and `kube-apiserver` on the upstream cluster. Third-party software can interfere with the performance of these components and Rancher, potentially leading to instability. + +Furthermore, third-party software can functionally interfere with Rancher. To minimize compatibility risks, deploy only essential Kubernetes system components and Rancher on the upstream cluster. + +The following applications and components generally do not interfere with Rancher or the Kubernetes system: + * Rancher internal components, such as Fleet + * Rancher extensions + * Cluster API components + * CNIs, CPIs, CSIs + * Cloud controller managers + * Observability and monitoring tools (except prometheus-rancher-exporter) + +Note that each of these components has its own minimum resource requirements, which must be met in addition to Rancher's. For high-scale deployments, also consider dedicating separate nodes to non-Rancher software using [taints and tolerations](https://kubernetes.io/docs/concepts/scheduling-eviction/taint-and-toleration/) to minimize interference. + +The following software can interfere with Rancher performance and is therefore discouraged on the upstream cluster: + * [CrossPlane](https://www.crossplane.io/) + * [Argo CD](https://argoproj.github.io/cd/) + * [Flux](https://fluxcd.io/) + * [prometheus-rancher-exporter](https://github.com/David-VTUK/prometheus-rancher-exporter) (see [issue 33](https://github.com/David-VTUK/prometheus-rancher-exporter/issues/33)) + * Container registries such as [Harbor](https://goharbor.io/), which can require significant bandwidth for serving images + +### Guidance for Container Registries + +Container registries, such as [Harbor](https://goharbor.io/), can consume significant network bandwidth when serving images. This demand increases with the number of images, the frequency of image pulls, and the quantity of clusters and container runtimes they serve. Due to this potential for interference with Rancher UI and API traffic, we recommend against running container registries on the same cluster as the Rancher management server. + +Regardless of your deployment strategy for a container registry, ensure sufficient bandwidth is available, ideally reserved using Quality of Service (QoS) mechanisms. + +Consider the following recommendations based on your needs: + +* **Simple Setups (HA Not a Primary Concern):** A container registry deployed as a single Virtual Machine (VM) can be a viable solution. +* **High Availability (HA) Requirements:** We recommend running the registry in a dedicated Kubernetes cluster. All other clusters should then be configured to pull images from this centralized, HA registry. +* **Very Large-Scale or Complex Network Topologies:** Multiple registry clusters might be necessary. These can be deployed in a hierarchical or federated model to efficiently distribute images and manage traffic. + +### Make sure nodes are configured correctly for Kubernetes +It's important to follow K8s and etcd best practices when deploying your nodes, including disabling swap, double checking you have full network connectivity between all machines in the cluster, using unique hostnames, MAC addresses, and product_uuids for every node, checking that all correct ports are opened, and deploying with ssd backed etcd. More details can be found in the [kubernetes docs](https://kubernetes.io/docs/setup/production-environment/tools/kubeadm/install-kubeadm/#before-you-begin) and [etcd's performance op guide](https://etcd.io/docs/v3.5/op-guide/performance/). + +### Run All Nodes in the Cluster in the Same Datacenter +For best performance, run all three of your nodes in the same geographic datacenter. If you are running nodes in the cloud, such as AWS, run each node in a separate Availability Zone. For example, launch node 1 in us-west-2a, node 2 in us-west-2b, and node 3 in us-west-2c. + +### Development and Production Environments Should be Similar +It's strongly recommended to have a "staging" or "pre-production" environment of the Kubernetes cluster that Rancher runs on. This environment should mirror your production environment as closely as possible in terms of software and hardware configuration. + +### Monitor Your Clusters to Plan Capacity +The Rancher server's Kubernetes cluster should run within the [system and hardware requirements](../../../getting-started/installation-and-upgrade/installation-requirements/installation-requirements.md) as closely as possible. The more you deviate from the system and hardware requirements, the more risk you take. + +However, metrics-driven capacity planning analysis should be the ultimate guidance for scaling Rancher, because the published requirements take into account a variety of workload types. + +Using Rancher, you can monitor the state and processes of your cluster nodes, Kubernetes components, and software deployments through integration with Prometheus, a leading open-source monitoring solution, and Grafana, which lets you visualize the metrics from Prometheus. + +After you [enable monitoring](../../../integrations-in-rancher/monitoring-and-alerting/monitoring-and-alerting.md) in the cluster, you can set up alerts to let you know if your cluster is approaching its capacity. You can also use the Prometheus and Grafana monitoring framework to establish a baseline for key metrics as you scale. diff --git a/versioned_docs/version-2.14/reference-guides/best-practices/rancher-server/tuning-and-best-practices-for-rancher-at-scale.md b/versioned_docs/version-2.14/reference-guides/best-practices/rancher-server/tuning-and-best-practices-for-rancher-at-scale.md new file mode 100644 index 00000000000..87a74b259c2 --- /dev/null +++ b/versioned_docs/version-2.14/reference-guides/best-practices/rancher-server/tuning-and-best-practices-for-rancher-at-scale.md @@ -0,0 +1,125 @@ +--- +title: Tuning and Best Practices for Rancher at Scale +--- + + + + + + +This guide describes the best practices and tuning approaches to scale Rancher setups and the associated challenges with doing so. As systems grow, performance will naturally reduce, but there are steps that can minimize the load put on Rancher and optimize Rancher's ability to manage larger infrastructures. + +## Optimizing Rancher Performance + +* Keep Rancher up to date with patch releases. We are continuously improving Rancher with performance enhancements and bug fixes. The latest Rancher release contains all accumulated improvements to performance and stability, plus updates based on developer experience and user feedback. + +* Always scale up gradually, and monitor and observe any changes in behavior while doing do. It is usually easier to resolve performance problems as soon as they surface, before other problems obscure the root cause. + +* Reduce network latency between the upstream Rancher cluster and downstream clusters to the extent possible. Note that latency is, among other factors, a function of geographic distance - if you require clusters or nodes spread across the world, consider multiple Rancher installations. + +## Minimizing Load on the Upstream Cluster + +When scaling up Rancher, one typical bottleneck is resource growth in the upstream (local) Kubernetes cluster. The upstream cluster contains information for all downstream clusters. Many operations that apply to downstream clusters create new objects in the upstream cluster and require computation from handlers running in the upstream cluster. + +### Minimizing Third-Party Software on the Upstream Cluster + +Recommendations outlined in the [general Rancher recommendations](./tips-for-running-rancher.md#minimize-third-party-software-on-the-upstream-cluster) are particularly important in a high scale context. + +### Managing Your Object Counts + +Etcd is the backing database for Kubernetes and for Rancher. The database may eventually encounter limitations to the number of a single Kubernetes resource type it can store. Exact limits vary and depend on a number of factors. However, experience indicates that performance issues frequently arise once a single resource type's object count exceeds 60,000. Often that type is `RoleBinding`. + +This is typical in Rancher, as many operations create new `RoleBinding` objects in the upstream cluster as a side effect. + +You can reduce the number of `RoleBindings` in the upstream cluster in the following ways: +* Only add users to clusters and projects when necessary. +* Remove clusters and projects when they are no longer needed. +* Only use custom roles if necessary. +* Use as few rules as possible in custom roles. +* Consider whether adding a role to a user is redundant. +* Consider using less, but more powerful, clusters. +* Kubernetes permissions are always "additive" (allow-list) rather than "subtractive" (deny-list). Try to minimize configurations that gives access to all but one aspect of a cluster, project, or namespace, as that will result in the creation of a high number of `RoleBinding` objects. +* Experiment to see if creating new projects or clusters manifests in fewer `RoleBindings` for your specific use case. + +### Using External Authentication + +If you have fifty or more users, you should configure an [external authentication provider](../../../how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/authentication-config/authentication-config.md). This is necessary for better performance. + +After you configure external authentication, make sure to assign permissions to groups instead of to individual users. This helps reduce the `RoleBinding` object count. + +### RoleBinding Count Estimation + +Predicting how many `RoleBinding` objects a given configuration will create is complicated. However, the following considerations can offer a rough estimate: +* For a minimum estimate, use the formula `32C + U + 2UaC + 8P + 5Pa`. + * `C` is the total number of clusters. + * `U` is the total number of users. + * `Ua` is the average number of users with a membership on a cluster. + * `P` is the total number of projects. + * `Pa` is the average number of users with a membership on a project. +* The number of `RoleBindings` increases linearly with the number of clusters, projects, and users. + +### Using New Apps Over Legacy Apps + +Rancher uses two Kubernetes app resources: `apps.projects.cattle.io` and `apps.cattle.cattle.io`. Legacy apps, represented by `apps.projects.cattle.io`, were introduced with the former Cluster Manager UI and are now outdated. Current apps, represented by `apps.catalog.cattle.io`, are found in the Cluster Explorer UI for their respective cluster. `Apps.cattle.cattle.io` apps are preferable because their data resides in downstream clusters, which frees up resources in the upstream cluster. + +You should remove any remaining legacy apps that appear in the Cluster Manager UI, and replace them with apps in the Cluster Explorer UI. Create any new apps only in the Cluster Explorer UI. + +### Using the Authorized Cluster Endpoint (ACE) + +An [Authorized Cluster Endpoint](../../../reference-guides/rancher-manager-architecture/communicating-with-downstream-user-clusters.md#4-authorized-cluster-endpoint) (ACE) provides access to the Kubernetes API of Rancher-provisioned RKE2 and K3s clusters. When enabled, the ACE adds a context to kubeconfig files generated for the cluster. The context uses a direct endpoint to the cluster, thereby bypassing Rancher. This reduces load on Rancher for cases where unmediated API access is acceptable or preferable. See [Authorized Cluster Endpoint](../../../reference-guides/rancher-manager-architecture/communicating-with-downstream-user-clusters.md#4-authorized-cluster-endpoint) for more information and configuration instructions. + +### Reducing Event Handler Executions + +The bulk of Rancher's logic occurs on event handlers. These event handlers run on an object whenever the object is updated, and when Rancher is started. Additionally, they run every 10 hours when Rancher syncs caches. In scaled setups these scheduled runs come with huge performance costs because every handler is being run on every applicable object. However, the scheduled handler execution can be disabled with the `CATTLE_SYNC_ONLY_CHANGED_OBJECTS` environment variable. If resource allocation spikes are seen every 10 hours, this setting can help. + +The value for `CATTLE_SYNC_ONLY_CHANGED_OBJECTS` can be a comma separated list of the following options. The values refer to types of handlers and controllers (the structures that contain and run handlers). Adding the controller types to the variable disables that set of controllers from running their handlers as part of cache resyncing. + +* `mgmt` refers to management controllers which only run on one Rancher node. +* `user` refers to user controllers which run for every cluster. Some of these run on the same node as management controllers, while others run in the downstream cluster. This option targets the former. +* `scaled` refers to scaled controllers which run on every Rancher node. You should avoid setting this value, as the scaled handlers are responsible for critical functions and changes may disrupt cluster stability. + +In short, if you notice CPU usage peaks every 10 hours, add the `CATTLE_SYNC_ONLY_CHANGED_OBJECTS` environment variable to your Rancher deployment (in the `spec.containers.env` list) with the value `mgmt,user` + +## Optimizations Outside of Rancher + +Important influencing factors are the underlying cluster's own performance and configuration. The upstream cluster, if misconfigured, can introduce a bottleneck Rancher software has no chance to resolve. + +### Manage Upstream Cluster Nodes Directly with RKE2 + +As Rancher can be very demanding on the upstream cluster, especially at scale, you should have full administrative control of the cluster's configuration and nodes. To identify the root cause of excess resource consumption, use standard Linux troubleshooting techniques and tools. This can aid in distinguishing between whether Rancher, Kubernetes, or operating system components are causing issues. + +Although managed Kubernetes services make it easier to deploy and run Kubernetes clusters, they are discouraged for the upstream cluster in high scale scenarios. Managed Kubernetes services typically limit access to configuration and insights on individual nodes and services. + +Use RKE2 for large scale use cases. + +### Keep all Upstream Cluster Nodes co-located + +To provide high availability, Kubernetes is designed to run nodes and control components in different zones. However, if nodes and control plane components are located in different zones, network traffic may be slower. + +Traffic between Rancher components and the Kubernetes API is especially sensitive to network latency, as is etcd traffic between nodes. + +To improve performance, run all upstream node clusters in the same location. In particular, make sure that latency between etcd nodes and Rancher is as low as possible. + +### Keeping Kubernetes Versions Up to Date + +You should keep the local Kubernetes cluster up to date. This will ensure that your cluster has all available performance enhancements and bug fixes. + +### Optimizing etcd + +Etcd is the backend database for Kubernetes and for Rancher. It plays a very important role in Rancher performance. + +The two main bottlenecks to [etcd performance](https://etcd.io/docs/v3.5/op-guide/performance/) are disk and network speed. Etcd should run on dedicated nodes with a fast network setup and with SSDs that have high input/output operations per second (IOPS). For more information regarding etcd performance, see [Slow etcd performance (performance testing and optimization)](https://www.suse.com/support/kb/doc/?id=000020100) and [Tuning etcd for Large Installations](../../../how-to-guides/advanced-user-guides/tune-etcd-for-large-installs.md). Information on disks can also be found in the [Installation Requirements](../../../getting-started/installation-and-upgrade/installation-requirements/installation-requirements.md#disks). + +It's best to run etcd on exactly three nodes, as adding more nodes will reduce operation speed. This may be counter-intuitive to common scaling approaches, but it's due to etcd's [replication mechanisms](https://etcd.io/docs/v3.5/faq/#what-is-maximum-cluster-size). + +Etcd performance will also be negatively affected by network latency between nodes as that will slow down network communication. Etcd nodes should be located together with Rancher nodes. + +### Browser Requirements + +At high scale, Rancher transfers more data from the upstream cluster to UI components running in the browser, and those components also need to perform more processing. + +For best performance, ensure that the host running the hardware meets these requirements: + - 2020 i5 10th generation Intel (4 cores) or equivalent + - 8 GB RAM + - Total network bandwidth to the upstream cluster: 72 Mb/s (equivalent to a single 802.11n Wi-Fi 4 link stream, ~8 MB/s http download throughput) + - Round-trip time (ping time) from browser to upstream cluster: 150 ms or less diff --git a/versioned_docs/version-2.14/reference-guides/cli-with-rancher/cli-with-rancher.md b/versioned_docs/version-2.14/reference-guides/cli-with-rancher/cli-with-rancher.md new file mode 100644 index 00000000000..a18cabf5abb --- /dev/null +++ b/versioned_docs/version-2.14/reference-guides/cli-with-rancher/cli-with-rancher.md @@ -0,0 +1,9 @@ +--- +title: CLI with Rancher +--- + + + + + +Interact with Rancher using command line interface (CLI) tools from your workstation. The following docs will describe the [Rancher CLI](rancher-cli.md) and [kubectl Utility](kubectl-utility.md). \ No newline at end of file diff --git a/versioned_docs/version-2.14/reference-guides/cli-with-rancher/kubectl-utility.md b/versioned_docs/version-2.14/reference-guides/cli-with-rancher/kubectl-utility.md new file mode 100644 index 00000000000..5b863d2e4be --- /dev/null +++ b/versioned_docs/version-2.14/reference-guides/cli-with-rancher/kubectl-utility.md @@ -0,0 +1,37 @@ +--- +title: kubectl Utility +--- + + + + + +## kubectl + +Interact with Rancher using kubectl. + +### kubectl Utility + +Install the `kubectl` utility. See [install kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/). + +Configure kubectl by visiting your cluster in the Rancher Web UI, clicking on `Kubeconfig`, copying contents, and putting them into your `~/.kube/config` file. + +Run `kubectl cluster-info` or `kubectl get pods` successfully. + +### Authentication with kubectl and kubeconfig Tokens with TTL + +_Requirements_ + +If admins have [kubeconfig token generation turned off](../../api/api-tokens.md#disable-tokens-in-generated-kubeconfigs), the kubeconfig file requires the [Rancher CLI](./rancher-cli.md) to be present in your PATH when you run `kubectl`. Otherwise, you’ll see an error like: +`Unable to connect to the server: getting credentials: exec: exec: "rancher": executable file not found in $PATH`. + +This feature enables kubectl to authenticate with the Rancher server and get a new kubeconfig token when required. The following auth providers are currently supported: + +1. Local +2. Active Directory (LDAP only) +3. FreeIPA +4. OpenLDAP +5. SAML providers: Ping, Okta, ADFS, Keycloak, Shibboleth +6. Azure AD + +When you first run kubectl, for example, `kubectl get pods`, you are prompted to pick an auth provider and log in with the Rancher server. The kubeconfig token is cached in the path where you run kubectl under `./.cache/token`. This token is valid until [it expires](../../api/api-tokens.md#disable-tokens-in-generated-kubeconfigs), or [gets deleted from the Rancher server](../../api/api-tokens.md#deleting-tokens). Upon expiration, you must log in with the Rancher server again to run the `kubectl get pods` command. diff --git a/versioned_docs/version-2.14/reference-guides/cli-with-rancher/rancher-cli.md b/versioned_docs/version-2.14/reference-guides/cli-with-rancher/rancher-cli.md new file mode 100644 index 00000000000..da517b3c40f --- /dev/null +++ b/versioned_docs/version-2.14/reference-guides/cli-with-rancher/rancher-cli.md @@ -0,0 +1,93 @@ +--- +title: Rancher CLI +description: Interact with Rancher using command line interface (CLI) tools from your workstation. +--- + + + + + +The Rancher CLI (Command Line Interface) is a unified tool that you can use to interact with Rancher. With this tool, you can operate Rancher using a command line rather than the GUI. + +## Download Rancher CLI + +The binary can be downloaded directly from the UI. + +1. In the upper left corner, click **☰**. +1. At the bottom of the navigation sidebar menu, click the Rancher version number. +1. Under the **CLI Downloads section**, there are links to download the binaries for Windows, Mac, and Linux. You can also check the [releases page for our CLI](https://github.com/rancher/cli/releases) for direct downloads of the binary. + +## Requirements + +After you download the Rancher CLI, you need to make a few configurations. Rancher CLI requires: + +- Your Rancher Server URL, which is used to connect to Rancher Server. +- An API Bearer Token, which is used to authenticate with Rancher. For more information about obtaining a Bearer Token, see [Creating an API Key](../user-settings/api-keys.md). + +## CLI Authentication + +Before you can use Rancher CLI to control your Rancher Server, you must authenticate using an API Bearer Token. Log in using the following command (replace `` and `` with your information): + +```bash +$ ./rancher login https:// --token +``` + +If Rancher Server uses a self-signed certificate, Rancher CLI prompts you to continue with the connection. + +## Project Selection + +Before you can perform any commands, you must select a Rancher project to perform those commands against. To select a [project](../../how-to-guides/new-user-guides/manage-clusters/projects-and-namespaces.md) to work on, use the command `./rancher context switch`. When you enter this command, a list of available projects displays. Enter a number to choose your project. + +**Example: `./rancher context switch` Output** +``` +User:rancher-cli-directory user$ ./rancher context switch +NUMBER CLUSTER NAME PROJECT ID PROJECT NAME +1 cluster-2 c-7q96s:p-h4tmb project-2 +2 cluster-2 c-7q96s:project-j6z6d Default +3 cluster-1 c-lchzv:p-xbpdt project-1 +4 cluster-1 c-lchzv:project-s2mch Default +Select a Project: +``` + +After you enter a number, the console displays a message that you've changed projects. + +``` +INFO[0005] Setting new context to project project-1 +INFO[0005] Saving config to /Users/markbishop/.ranchcli2.json +``` + +Ensure you can run `rancher kubectl get pods` successfully. + +## Commands + +The following commands are available for use in Rancher CLI. + +| Command | Result | +|---|---| +| `clusters, [cluster]` | Performs operations on your [clusters](../../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/kubernetes-clusters-in-rancher-setup.md). | +| `context` | Switches between Rancher [projects](../../how-to-guides/new-user-guides/manage-clusters/projects-and-namespaces.md). For an example, see [Project Selection](#project-selection). | +| `inspect [OPTIONS] [RESOURCEID RESOURCENAME]` | Displays details about [Kubernetes resources](https://kubernetes.io/docs/reference/kubectl/cheatsheet/#resource-types) or Rancher resources (i.e.: [projects](../../how-to-guides/new-user-guides/manage-clusters/projects-and-namespaces.md) and [workloads](../../how-to-guides/new-user-guides/kubernetes-resources-setup/workloads-and-pods/workloads-and-pods.md)). Specify resources by name or ID. | +| `kubectl` | Runs [kubectl commands](https://kubernetes.io/docs/reference/kubectl/overview/#operations). | +| `login, [l]` | Logs into a Rancher Server. For an example, see [CLI Authentication](#cli-authentication). | +| `machines, [machine]` | Performs operations on machines. | +| `namespaces, [namespace]` | Performs operations on [namespaces](../../how-to-guides/new-user-guides/manage-namespaces.md). | +| `nodes, [node]` | Performs operations on [nodes](../../how-to-guides/new-user-guides/manage-clusters/nodes-and-node-pools.md). | +| `projects, [project]` | Performs operations on [projects](../../how-to-guides/new-user-guides/manage-clusters/projects-and-namespaces.md). | +| `ps` | Displays [workloads](../../how-to-guides/new-user-guides/kubernetes-resources-setup/workloads-and-pods/workloads-and-pods.md) in a project. | +| `server` | Performs operations for the server. | +| `settings, [setting]` | Shows the current settings for your Rancher Server. | +| `ssh` | Connects to one of your cluster nodes using the SSH protocol. | +| `up` | Applies compose config. | +| `wait` | Waits for resources cluster, app, project, multiClusterApp. | +| `token` | Authenticates and generates new kubeconfig token. | +| `help, [h]` | Shows a list of commands or help for one command. | + +## Rancher CLI Help + +Once logged into Rancher Server using the CLI, enter `./rancher --help` for a list of commands. + +All commands accept the `--help` flag, which documents each command's usage. + +## Limitations + +The Rancher CLI **cannot** be used to install [dashboard apps or Rancher feature charts](../../how-to-guides/new-user-guides/helm-charts-in-rancher/helm-charts-in-rancher.md). diff --git a/versioned_docs/version-2.14/reference-guides/cluster-configuration/cluster-configuration.md b/versioned_docs/version-2.14/reference-guides/cluster-configuration/cluster-configuration.md new file mode 100644 index 00000000000..75bae23a493 --- /dev/null +++ b/versioned_docs/version-2.14/reference-guides/cluster-configuration/cluster-configuration.md @@ -0,0 +1,32 @@ +--- +title: Cluster Configuration +--- + + + + + +After you provision a Kubernetes cluster using Rancher, you can still edit options and settings for the cluster. + +For information on editing cluster membership, go to [this page.](../../how-to-guides/new-user-guides/manage-clusters/access-clusters/add-users-to-clusters.md) + +## Cluster Configuration References + +The cluster configuration options depend on the type of Kubernetes cluster: + +- [RKE2 Cluster Configuration](rancher-server-configuration/rke2-cluster-configuration.md) +- [K3s Cluster Configuration](rancher-server-configuration/k3s-cluster-configuration.md) +- [EKS Cluster Configuration](rancher-server-configuration/eks-cluster-configuration.md) +- [GKE Cluster Configuration](rancher-server-configuration/gke-cluster-configuration/gke-cluster-configuration.md) +- [AKS Cluster Configuration](rancher-server-configuration/aks-cluster-configuration.md) + +## Cluster Management Capabilities by Cluster Type + +The options and settings available for an existing cluster change based on the method that you used to provision it. + +The following table summarizes the options and settings available for each cluster type: + +import ClusterCapabilitiesTable from '../../shared-files/_cluster-capabilities-table.md'; + + + diff --git a/versioned_docs/version-2.14/reference-guides/cluster-configuration/downstream-cluster-configuration/downstream-cluster-configuration.md b/versioned_docs/version-2.14/reference-guides/cluster-configuration/downstream-cluster-configuration/downstream-cluster-configuration.md new file mode 100644 index 00000000000..b10fe62447f --- /dev/null +++ b/versioned_docs/version-2.14/reference-guides/cluster-configuration/downstream-cluster-configuration/downstream-cluster-configuration.md @@ -0,0 +1,9 @@ +--- +title: Downstream Cluster Configuration +--- + + + + + +The following docs will discuss [machine configuration](machine-configuration/machine-configuration.md). \ No newline at end of file diff --git a/versioned_docs/version-2.14/reference-guides/cluster-configuration/downstream-cluster-configuration/machine-configuration/amazon-ec2.md b/versioned_docs/version-2.14/reference-guides/cluster-configuration/downstream-cluster-configuration/machine-configuration/amazon-ec2.md new file mode 100644 index 00000000000..e9ac92a352e --- /dev/null +++ b/versioned_docs/version-2.14/reference-guides/cluster-configuration/downstream-cluster-configuration/machine-configuration/amazon-ec2.md @@ -0,0 +1,97 @@ +--- +title: EC2 Machine Configuration Reference +--- + + + + + +For more details about EC2 nodes, refer to the official documentation for the [EC2 Management Console](https://aws.amazon.com/ec2). + +### Region + +The geographical [region](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-regions-availability-zones.html) in which to build your cluster. + +### Zone + +The [zone](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-regions-availability-zones.html#concepts-availability-zones), an isolated location within a region to build your cluster + +### Instance Type + +The [instance type](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/instance-types.html), which determines the hardware characteristics, used to provision your cluster. + +### Root Disk Size + +Configure the size (in GB) for your [root device](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/RootDeviceStorage.html). + +### VPC/Subnet + +The [VPC](https://docs.aws.amazon.com/vpc/latest/userguide/configure-your-vpc.html) or specific [subnet](https://docs.aws.amazon.com/vpc/latest/userguide/configure-subnets.html), an IP range in your VPC, to add your resources to. + +### IAM Instance Profile Name + +The name of the [instance profile](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use_switch-role-ec2_instance-profiles.html) used to pass an IAM role to an EC2 instance. + +## Advanced Options + +### AMI ID + +The [Amazon Machine Image](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/AMIs.html) used for the nodes in your cluster. + +### SSH Username for AMI + +The username for connecting to your launched instances. Refer to [here](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/connection-prereqs.html) for the default usernames to selected AMIs. For AMIs not listed, check with the AMI provider. + +### Security Group + +Choose the default security group or configure a security group. + +Please refer to [Amazon EC2 security group when using Node Driver](../../../../getting-started/installation-and-upgrade/installation-requirements/port-requirements.md#rancher-aws-ec2-security-group) to see what rules are created in the `rancher-nodes` Security Group. + +### EBS Root Volume Type + +The [EBS volume type](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ebs-volume-types.html) to use for the root device. + +### Encrypt EBS Volume + +Enable [Amazon EBS Encryption](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/EBSEncryption.html). + +### Request Spot Instance + +Enable option to [request spot instances](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/spot-requests.html) and specify the maximum instance price per hour you're willing to pay. + +### Use only private address + +Enable option on use only [private addresses](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-instance-addressing.html). + +### EBS-Optimized Instance + +Use an [EBS-optimized instance](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ebs-optimized.html). + +### Allow access to EC2 metadata + +Enable access to [EC2 metadata](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-instance-metadata.html). + +### Use tokens for metadata + +Use [Instance Metadata Service Version 2 (IMDSv2)](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/configuring-instance-metadata-service.html), a token-based method to access metadata. + +### Add Tag + +Add metadata using [tags](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/Using_Tags.html) to categorize resources. + +### IPv6 Address Count + +Specify how many IPv6 addresses to assign to the instance’s network interface. + +### IPv6 Address Only + +Enable this option if the instance should use IPv6 exclusively. IPv6-only VPCs or subnets require this. When enabled, the instance will have IPv6 as its sole address, and the IPv6 Address Count must be greater than zero. + +### HTTP Protocol IPv6 + +Enable or disable IPv6 endpoints for the instance metadata service. + +### Enable Primary IPv6 + +Enable this option to designate the first assigned IPv6 address as the primary address. This ensures a consistent, non-changing IPv6 address for the instance. It does not control whether IPv6 addresses are assigned. diff --git a/versioned_docs/version-2.14/reference-guides/cluster-configuration/downstream-cluster-configuration/machine-configuration/azure.md b/versioned_docs/version-2.14/reference-guides/cluster-configuration/downstream-cluster-configuration/machine-configuration/azure.md new file mode 100644 index 00000000000..ba7e806295e --- /dev/null +++ b/versioned_docs/version-2.14/reference-guides/cluster-configuration/downstream-cluster-configuration/machine-configuration/azure.md @@ -0,0 +1,124 @@ +--- +title: Azure Machine Configuration +--- + + + + + +For more information about Azure, refer to the official [Azure documentation.](https://docs.microsoft.com/en-us/azure/?product=featured) + +### Environment + +Microsoft provides multiple [clouds](https://docs.microsoft.com/en-us/cli/azure/cloud?view=azure-cli-latest) for compliance with regional laws, which are available for your use: + +- AzurePublicCloud +- AzureGermanCloud +- AzureChinaCloud +- AzureUSGovernmentCloud + +### Location + +Configure the cluster and node [location](https://docs.microsoft.com/en-us/azure/virtual-machines/regions). + +### Resource Group + +A resource group is a container that holds related resources for an Azure solution. The resource group can include all the resources for the solution, or only those resources that you want to manage as a group. You decide how you want to allocate resources to resource groups based on what makes the most sense for your organization. Generally, add resources that share the same lifecycle to the same resource group so you can easily deploy, update, and delete them as a group. + +Use an existing resource group or enter a resource group name and one will be created for you. + +For information on managing resource groups, see the [Azure documentation.](https://docs.microsoft.com/en-us/azure/azure-resource-manager/management/manage-resource-groups-portal) + +### Availability Set (unmanaged) + +Name or ID of an existing [availability set](https://docs.microsoft.com/en-us/azure/virtual-machines/availability-set-overview) to add the VM to. + +### Image + +The name of the operating system image provided as an ARM resource identifier. Requires using managed disk. + +### VM Size + +Choose a size for each VM in the node pool. For details about each VM size, see [this page.](https://azure.microsoft.com/en-us/pricing/details/virtual-machines/linux/) + +## Advanced Options + +### Fault Domain Count + +Fault domains define the group of virtual machines that share a common power source and network switch. If the availability set has already been created, the fault domain count will be ignored. + +For more information on fault domains, see [refer here](https://docs.microsoft.com/en-us/azure/virtual-machines/availability-set-overview#how-do-availability-sets-work). + +### Update Domain Count + +Update domains indicate groups of virtual machines and underlying physical hardware that can be rebooted at the same time. If the availability set has already been created, the update domain count will be ignored. + +For more information on update domains, see [refer here](https://docs.microsoft.com/en-us/azure/virtual-machines/availability-set-overview#how-do-availability-sets-work). + +### Purchase Plan + +Some VM images in the Azure Marketplace require a plan. If applicable, select a purchase plan, formatted as `publisher:product:plan`, to use with your chosen image. + +### Subnet + +The name of the subnet when creating a new VNet or referencing an existing one. + +Default: `docker-machine` + +### Subnet Prefix + +The subnet IP address prefix to use when creating a new VNet in CIDR format. + +Default: `192.168.0.0/16` + +### Virtual Network + +The [virtual network](https://docs.microsoft.com/en-us/azure/virtual-network/virtual-networks-overview) to use or create if one does not exist. Formatted as `[resourcegroup:]name`. + +### Public IP Options + +#### No Public IP + +Do not allocate a public IP address. + +#### Static Public IP + +Allocate a static public IP address. + +### Use Private IP + +Use a static private IP address. + +### Private IP Address + +Configure a static private IP address to use. + +### Network Security Group + +The [network security group](https://docs.microsoft.com/en-us/azure/virtual-network/network-security-groups-overview) to use. All nodes using this template will use the supplied network security group. If no network security group is provided, a new one will be created for each node. + +### DNS Label + +A unique DNS name label for the public IP address. + +### Storage Type + +The [storage account](https://docs.microsoft.com/en-us/azure/storage/common/storage-account-overview) type to use with your VMs. Options include Standard LRS, Standard ZRS, Standard GRS, Standard RAGRS, and Premium LRS. + +### Use Managed Disks + +[Azure managed disks](https://docs.microsoft.com/en-us/azure/virtual-machines/managed-disks-overview) are block-level storage volumes that are managed by Azure and used with Azure Virtual Machines. Managed disks are designed for 99.999% availability. Managed disks achieve this by providing you with three replicas of your data, allowing for high durability. + +### Managed Disk Size + +The size in GB for the disk for each node. + +### SSH Username + +The username used to create an SSH connection to your nodes. + +### Open Port + +Opens inbound traffic on specified ports. When using an existing Network Security Group, Open Ports are ignored. + +Default: `2379/tcp, 2380/tcp, 6443/tcp, 9796/tcp, 10250/tcp, 10251/tcp, 10252/tcp, 10256/tcp` and `8472/udp, 4789/udp` \ No newline at end of file diff --git a/versioned_docs/version-2.14/reference-guides/cluster-configuration/downstream-cluster-configuration/machine-configuration/digitalocean.md b/versioned_docs/version-2.14/reference-guides/cluster-configuration/downstream-cluster-configuration/machine-configuration/digitalocean.md new file mode 100644 index 00000000000..0c8662b46a3 --- /dev/null +++ b/versioned_docs/version-2.14/reference-guides/cluster-configuration/downstream-cluster-configuration/machine-configuration/digitalocean.md @@ -0,0 +1,39 @@ +--- +title: DigitalOcean Machine Configuration +--- + + + + + +For more details about DigitalOcean, Droplets, refer to the [official documentation](https://docs.digitalocean.com/products/compute/). + +### Region + +Configure the [region](https://docs.digitalocean.com/glossary/region/) where Droplets are created. + +### Size + +Configure the [size](https://docs.digitalocean.com/products/droplets/resources/choose-plan/) of Droplets. + +### OS Image + +Configure the operating system [image](https://docs.digitalocean.com/products/images/) Droplets are created from. + +### Monitoring + +Enable the DigitalOcean agent for additional [monitoring](https://docs.digitalocean.com/products/monitoring/). + +### IPv6 + +Enable IPv6 for Droplets. + +For more information, refer to the [Digital Ocean IPv6 documentation](https://docs.digitalocean.com/products/networking/ipv6). + +### Private Networking + +Enable private networking for Droplets. + +### Droplet Tags + +Apply a tag (label) to a Droplet. Tags may only contain letters, numbers, colons, dashes, and underscores. For example, `my_server`. diff --git a/versioned_docs/version-2.14/reference-guides/cluster-configuration/downstream-cluster-configuration/machine-configuration/google-gce.md b/versioned_docs/version-2.14/reference-guides/cluster-configuration/downstream-cluster-configuration/machine-configuration/google-gce.md new file mode 100644 index 00000000000..85c77d64b17 --- /dev/null +++ b/versioned_docs/version-2.14/reference-guides/cluster-configuration/downstream-cluster-configuration/machine-configuration/google-gce.md @@ -0,0 +1,87 @@ +--- +title: GCE Machine Configuration +--- + + + + + + +For more information about Google Cloud Platform (GCP) and the Google Compute Engine (GCE), refer to the official [GCP documentation](https://cloud.google.com/docs). + +### Zone + +The GCP Region and Zone that the VM will be deployed to. For example, `us-east1-b`. + +### Machine Image Project + +The image project that the desired image families belong to. + +### Machine Image Family + +The image family that the desired machine operating system belongs to. + +### Machine Image + +The operating system that will be installed onto the VM. + +### Disk Type + +The type of the disk attached to the VM. The available types may differ between regions. + +### Disk Size + +The size of the disk attached to the VM, in Gigabytes. + +### Machine Type + +The type of VM that will be deployed. Machine types determine the number of resources (vCPU, RAM, etc.) allocated for each node. + +### Network + +The VPC network that the VM will be created in. This value cannot be changed once the machine pool has been provisioned. + +### Subnet + +The VPC subnetwork tha the VM will be created in. This value cannot be changed once the machine pool has been provisioned. + +### Username + +A custom username set as the default user of the GCE VM. + +### External Address + +The desired external IP address for the GCE VM. + +### Scopes + +A list of OAuth2 scopes which allow the VM to access other GCP APIs. + +### Allow Internal Communication + +By default, a VPC firewall rule is automatically created to expose a fixed set of ports within the VPC to facilitate communication between cluster nodes. This behavior can be disabled on a per machine pool basis, when clicking the `Show Advanced` option and disabling the `Allow Internal Communication` checkbox. + +### Expose External ports + +A list of ports to be opened _externally_ to the wider internet. Open ports are defined at the machine pool level. Enabling this option will result in the automatic creation of a VPC firewall rule. This rule will be automatically deleted when the cluster or machine pool is deleted. + +### Network Tags + +Tags is a list of _network tags_, which can be used to associate preexisting Firewall Rules with all VMs within a machine pool. + +### Labels + +A comma separated list of custom labels to be attached to all VMs within a given machine pool. Unlike Tags, Labels do not influence networking behavior and only serve to organize cloud resources. + +## Advanced Options + +When creating clusters via the Rancher UI some options are automatically configured for you. However, when creating machine config objects manually, you must ensure you properly configure the below fields. + +### external-firewall-rule-prefix + +A prefix that will be used when creating the firewall rule to expose ports publicly. Ideally, this should be a concatenation the machine pool name and the cluster name. This field must be set if the machine pool is configured to expose ports publicly, otherwise it can be omitted. + +### internal-firewall-rule-prefix + +A prefix that will be used when creating the internal firewall rule which allows for communication between nodes within the cluster. If this field is omitted, no internal firewall rule will be created. + diff --git a/versioned_docs/version-2.14/reference-guides/cluster-configuration/downstream-cluster-configuration/machine-configuration/machine-configuration.md b/versioned_docs/version-2.14/reference-guides/cluster-configuration/downstream-cluster-configuration/machine-configuration/machine-configuration.md new file mode 100644 index 00000000000..b9515bade61 --- /dev/null +++ b/versioned_docs/version-2.14/reference-guides/cluster-configuration/downstream-cluster-configuration/machine-configuration/machine-configuration.md @@ -0,0 +1,9 @@ +--- +title: Machine Configuration +--- + + + + + +Machine configuration is the arrangement of resources assigned to a virtual machine. Please see the docs for [Amazon EC2](amazon-ec2.md), [DigitalOcean](digitalocean.md), [Google GCE](google-gce.md), and [Azure](azure.md) to learn more. diff --git a/versioned_docs/version-2.14/reference-guides/cluster-configuration/downstream-cluster-configuration/node-template-configuration/amazon-ec2.md b/versioned_docs/version-2.14/reference-guides/cluster-configuration/downstream-cluster-configuration/node-template-configuration/amazon-ec2.md new file mode 100644 index 00000000000..4c9abb51206 --- /dev/null +++ b/versioned_docs/version-2.14/reference-guides/cluster-configuration/downstream-cluster-configuration/node-template-configuration/amazon-ec2.md @@ -0,0 +1,51 @@ +--- +title: EC2 Node Template Configuration +--- + + + + + +For more details about EC2, nodes, refer to the official documentation for the [EC2 Management Console](https://aws.amazon.com/ec2). + +### Region + +In the **Region** field, select the same region that you used when creating your cloud credentials. + +### Cloud Credentials + +Your AWS account access information, stored in a [cloud credential.](../../../user-settings/manage-cloud-credentials.md) + +See [Amazon Documentation: Creating Access Keys](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html#Using_CreateAccessKey) how to create an Access Key and Secret Key. + +See [Amazon Documentation: Creating IAM Policies (Console)](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_create.html#access_policies_create-start) how to create an IAM policy. + +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 an IAM + +See our three example JSON policies: + +- [Example IAM Policy](../../../../how-to-guides/new-user-guides/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/create-an-amazon-ec2-cluster.md#example-iam-policy) +- [Example IAM Policy with PassRole](../../../../how-to-guides/new-user-guides/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/create-an-amazon-ec2-cluster.md#example-iam-policy-with-passrole) (needed if you want to use [Kubernetes Cloud Provider](../../../../how-to-guides/new-user-guides/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](../../../../how-to-guides/new-user-guides/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/create-an-amazon-ec2-cluster.md#example-iam-policy-to-allow-encrypted-ebs-volumes) policy to an user. + +### Authenticate & Configure Nodes + +Choose an availability zone and network settings for your cluster. + +### Security Group + +Choose the default security group or configure a security group. + +Please refer to [Amazon EC2 security group when using Node Driver](../../../../getting-started/installation-and-upgrade/installation-requirements/port-requirements.md#rancher-aws-ec2-security-group) to see what rules are created in the `rancher-nodes` Security Group. + +If you provide your own security group for an EC2 instance, please note that Rancher will not modify it. As such, you will be responsible for ensuring that your security group is set to allow the [necessary ports for Rancher to provision the instance](../../../../getting-started/installation-and-upgrade/installation-requirements/port-requirements.md#ports-for-rancher-server-nodes-on-rke2). For more information on controlling inbound and outbound traffic to EC2 instances with security groups, refer [here](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_SecurityGroups.html#WorkingWithSecurityGroups). + +### Instance Options + +Configure the instances that will be created. Make sure you configure the correct **SSH User** for the configured AMI. It is possible that a selected region does not support the default instance type. In this scenario you must select an instance type that does exist, otherwise an error will occur stating the requested configuration is not supported. + +If you need to pass an **IAM Instance Profile Name** (not ARN), for example, when you want to use a [Kubernetes Cloud Provider](../../../../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-cloud-providers/set-up-cloud-providers.md), you will need an additional permission in your policy. See [Example IAM policy with PassRole](../../../../how-to-guides/new-user-guides/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/create-an-amazon-ec2-cluster.md#example-iam-policy-with-passrole) for an example policy. + +### Engine Options + +In the **Engine Options** section of the node template, you can configure the container daemon. You may want to specify the container version or a container image registry mirror. diff --git a/versioned_docs/version-2.14/reference-guides/cluster-configuration/downstream-cluster-configuration/node-template-configuration/azure.md b/versioned_docs/version-2.14/reference-guides/cluster-configuration/downstream-cluster-configuration/node-template-configuration/azure.md new file mode 100644 index 00000000000..e747dbbb547 --- /dev/null +++ b/versioned_docs/version-2.14/reference-guides/cluster-configuration/downstream-cluster-configuration/node-template-configuration/azure.md @@ -0,0 +1,37 @@ +--- +title: Azure Node Template Configuration +--- + + + + + +For more information about Azure, refer to the official [Azure documentation.](https://docs.microsoft.com/en-us/azure/?product=featured) + +Account access information is stored as a cloud credential. Cloud credentials are stored as Kubernetes secrets. Multiple node templates can use the same cloud credential. You can use an existing cloud credential or create a new one. + +- **Placement** sets the geographical region where your cluster is hosted and other location metadata. +- **Network** configures the networking used in your cluster. +- **Instance** customizes your VM configuration. + + :::note + + If using a VNet in a different Resource Group than the VMs, the VNet name should be prefixed with the Resource Group name. For example, `:`. + + ::: + +If you use Docker, the [Docker daemon](https://docs.docker.com/engine/docker-overview/#the-docker-daemon) configuration options include: + +- **Labels:** For information on labels, refer to the [Docker object label documentation.](https://docs.docker.com/config/labels-custom-metadata/). +- **Docker Engine Install URL:** Determines what Docker version will be installed on the instance. + + :::note + + If you're provisioning Red Hat Enterprise Linux (RHEL) or CentOS nodes, leave the **Docker Install URL** field as the default value, or select **none**. This will bypass a check for Docker installation, as Docker is already installed on these node types. + + If you set **Docker Install URL** to a value other than the default or **none**, you might see an error message such as the following: `Error creating machine: RHEL ssh command error: command: sudo -E yum install -y curl err: exit status 1 output: Updating Subscription Management repositories.` + + ::: + +- **Registry mirrors:** Docker Registry mirror to be used by the Docker daemon. +- **Other advanced options:** Refer to the [Docker daemon option reference](https://docs.docker.com/engine/reference/commandline/dockerd/). diff --git a/versioned_docs/version-2.14/reference-guides/cluster-configuration/downstream-cluster-configuration/node-template-configuration/digitalocean.md b/versioned_docs/version-2.14/reference-guides/cluster-configuration/downstream-cluster-configuration/node-template-configuration/digitalocean.md new file mode 100644 index 00000000000..11b7a300a97 --- /dev/null +++ b/versioned_docs/version-2.14/reference-guides/cluster-configuration/downstream-cluster-configuration/node-template-configuration/digitalocean.md @@ -0,0 +1,22 @@ +--- +title: DigitalOcean Node Template Configuration +--- + + + + + +Account access information is stored as a cloud credential. Cloud credentials are stored as Kubernetes secrets. Multiple node templates can use the same cloud credential. You can use an existing cloud credential or create a new one. + +## Droplet Options + +The **Droplet Options** provision your cluster's geographical region and specifications. + +## Docker Daemon + +If you use Docker, the [Docker daemon](https://docs.docker.com/engine/docker-overview/#the-docker-daemon) configuration options include: + +- **Labels:** For information on labels, refer to the [Docker object label documentation.](https://docs.docker.com/config/labels-custom-metadata/) +- **Docker Engine Install URL:** Determines what Docker version will be installed on the instance. +- **Registry mirrors:** Docker Registry mirror to be used by the Docker daemon +- **Other advanced options:** Refer to the [Docker daemon option reference](https://docs.docker.com/engine/reference/commandline/dockerd/). diff --git a/versioned_docs/version-2.14/reference-guides/cluster-configuration/downstream-cluster-configuration/node-template-configuration/node-template-configuration.md b/versioned_docs/version-2.14/reference-guides/cluster-configuration/downstream-cluster-configuration/node-template-configuration/node-template-configuration.md new file mode 100644 index 00000000000..693a225a9f7 --- /dev/null +++ b/versioned_docs/version-2.14/reference-guides/cluster-configuration/downstream-cluster-configuration/node-template-configuration/node-template-configuration.md @@ -0,0 +1,11 @@ +--- +title: Node Template Configuration +--- + + + + + + + +To learn about node template config, refer to [EC2 Node Template Configuration](amazon-ec2.md), [DigitalOcean Node Template Configuration](digitalocean.md), [Azure Node Template Configuration](azure.md), [vSphere Node Template Configuration](vsphere.md), and [Nutanix Node Template Configuration](nutanix.md). diff --git a/versioned_docs/version-2.14/reference-guides/cluster-configuration/downstream-cluster-configuration/node-template-configuration/nutanix.md b/versioned_docs/version-2.14/reference-guides/cluster-configuration/downstream-cluster-configuration/node-template-configuration/nutanix.md new file mode 100644 index 00000000000..4e44d5ceca7 --- /dev/null +++ b/versioned_docs/version-2.14/reference-guides/cluster-configuration/downstream-cluster-configuration/node-template-configuration/nutanix.md @@ -0,0 +1,70 @@ +--- +title: Nutanix Node Template Configuration +--- + + + + + +## Account Access + +| Parameter | Required | Description | Default +|:-----------------------------|:--------:|:-----------------------------------------------------------------|:----- +| Management Endpoint | ✓ | Hostname/IP address of Prism Central | +| Username | ✓ | Username of the Prism Central user | +| Password | ✓ | Password of the Prism Central user | +| Allow insecure communication | | Set to true to allow insecure SSL communication to Prism Central | False + +## Scheduling + +Choose what Nutanix cluster the virtual machine will be scheduled to. + +| Parameter | Required | Description +|:----------|:--------:|:---------------------------------------------------------------------------- +| Cluster | ✓ | Name of the Nutanix cluster where the VM should be deployed (case sensitive) + +## Instance Options + +In the **Instance Options** section, configure the number of vCPUs, memory, and disk size for the VMs created by this template. + +| Parameter | Required | Description | Default +|:---------------------|:--------:|:--------------------------------------------------------------------------------------------|:------- +| CPUs | | Number of vCPUs allocated to the VM (cores) | 2 +| Memory | | Amount of RAM allocated to the VM (MB) | 2 GB +| Template Image | ✓ | Name of the Disk Image template to clone as the VM's primary disk (must support cloud-init) | +| VM Disk Size | | New size of the VM's primary disk (in GiB) | +| Additional Disk Size | | Size of an additional disk to add to the VM (in GiB) | +| Storage Container | | Storage container _UUID_ in which to provision an additional disk | +| Cloud Config YAML | | Cloud-init to provide to the VM (will be patched with Rancher root user) | +| Network | ✓ | Name(s) of the network(s) to attach to the VM | +| VM Categories | | Name(s) of any categories to be applied to the VM | + +The VM may use any modern Linux operating system that is configured with support for [cloud-init](https://cloudinit.readthedocs.io/en/latest/) using the [Config Drive v2 datasource](https://cloudinit.readthedocs.io/en/latest/reference/datasources/configdrive.html). + +## Networks + +The node template allows a VM to be provisioned with multiple networks. In the **Network** field, you can click **Add** to add any networks available to you in AOS. + +## VM Categories + +A category is a grouping of entities into a key value pair. Typically, VMs are assigned to a category based on some criteria. Policies can then be tied to those entities that are assigned (grouped by) a specific category value. + +## cloud-init + +[Cloud-init](https://cloudinit.readthedocs.io/en/latest/) allows you to initialize your nodes by applying configuration on the first boot. This may involve things such as creating users or authorizing SSH keys. + +To make use of cloud-init initialization, paste a cloud config using valid YAML syntax into the **Cloud Config YAML** field. Refer to the [cloud-init documentation](https://cloudinit.readthedocs.io/en/latest/topics/examples.html) for a commented set of examples of supported cloud config directives. + +Note that cloud-init based network configuration is not recommended and only supported via user data `runcmd` rather than by NoCloud or other network configuration datasources. + +Nutanix IP Address Management (IPAM) or another DHCP service is recommended. + +## Engine Options + +In the **Engine Options** section of the node template, you can configure the container daemon. You may want to specify the container version or a container image registry mirror. + +:::note +If you're provisioning Red Hat Enterprise Linux (RHEL) or CentOS nodes, leave the **Docker Install URL** field as the default value, or select **none**. This will bypass a check for Docker installation, as Docker is already installed on these node types. + +If you set **Docker Install URL** to a value other than the default or **none**, you might see an error message such as the following: `Error creating machine: RHEL ssh command error: command: sudo -E yum install -y curl err: exit status 1 output: Updating Subscription Management repositories.` +::: \ No newline at end of file diff --git a/versioned_docs/version-2.14/reference-guides/cluster-configuration/downstream-cluster-configuration/node-template-configuration/vsphere.md b/versioned_docs/version-2.14/reference-guides/cluster-configuration/downstream-cluster-configuration/node-template-configuration/vsphere.md new file mode 100644 index 00000000000..805ed2170d8 --- /dev/null +++ b/versioned_docs/version-2.14/reference-guides/cluster-configuration/downstream-cluster-configuration/node-template-configuration/vsphere.md @@ -0,0 +1,100 @@ +--- +title: VMware vSphere Node Template Configuration +--- + + + + + +## Account Access + +| Parameter | Required | Description | +|:----------------------|:--------:|:-----| +| Cloud Credentials | * | Your vSphere account access information, stored in a [cloud credential.](../../../user-settings/manage-cloud-credentials.md) | + +Your cloud credential has these fields: + +| Credential Field | Description | +|-----------------|--------------| +| vCenter or ESXi Server | Enter the vCenter or ESXi hostname/IP. ESXi is the virtualization platform where you create and run virtual machines and virtual appliances. vCenter Server is the service through which you manage multiple hosts connected in a network and pool host resources. | +| Port | Configure the port of the vCenter or ESXi server. | +| Username and password | Enter your vSphere login username and password. | + +## Scheduling + +Choose what hypervisor the virtual machine will be scheduled to. + +The fields in the **Scheduling** section should auto-populate with the data center and other scheduling options that are available to you in vSphere. + +| Field | Required | Explanation | +|---------|---------------|-----------| +| Data Center | * | Choose the name/path of the data center where the VM will be scheduled. | +| Resource Pool | | Name of the resource pool to schedule the VMs in. Resource pools can be used to partition available CPU and memory resources of a standalone host or cluster, and they can also be nested. Leave blank for standalone ESXi. If not specified, the default resource pool is used. | +| Data Store | * | If you have a data store cluster, you can toggle the **Data Store** field. This lets you select a data store cluster where your VM will be scheduled to. If the field is not toggled, you can select an individual disk. | +| Folder | | Name of a folder in the datacenter to create the VMs in. Must already exist. The VM folders in this dropdown menu directly correspond to your VM folders in vSphere. The folder name should be prefaced with `vm/` in your vSphere config file. | +| Host | | The IP of the host system to schedule VMs in. Leave this field blank for a standalone ESXi or for a cluster with DRS (Distributed Resource Scheduler). If specified, the host system's pool will be used and the **Resource Pool** parameter will be ignored. | +| Graceful Shutdown Timeout | | The amount of time, in seconds, that Rancher waits before deleting virtual machines on a cluster. If set to `0`, graceful shutdown is disabled. Only accepts integer values. | + +## Instance Options + +In the **Instance Options** section, configure the number of vCPUs, memory, and disk size for the VMs created by this template. + +| Parameter | Required | Description | +|:----------------|:--------:|:-----------| +| CPUs | * | Number of vCPUS to assign to VMs. | +| Memory | * | Amount of memory to assign to VMs. | +| Disk | * | Size of the disk (in MB) to attach to the VMs. | +| Creation method | * | The method for setting up an operating system on the node. The operating system can be installed from an ISO or from a VM template. Depending on the creation method, you will also have to specify a VM template, content library, existing VM, or ISO. For more information on creation methods, refer to [About VM Creation Methods.](#about-vm-creation-methods) | +| Cloud Init | | URL of a `cloud-config.yml` file or URL to provision VMs with. This file allows further customization of the operating system, such as network configuration, DNS servers, or system daemons. The operating system must support `cloud-init`. | +| Networks | | Name(s) of the network to attach the VM to. | +| Configuration Parameters used for guestinfo | | Additional configuration parameters for the VMs. These correspond to the [Advanced Settings](https://kb.vmware.com/s/article/1016098) in the vSphere console. Example use cases include providing RancherOS [guestinfo](https://rancher.com/docs/os/v1.x/en/installation/cloud/vmware-esxi/#vmware-guestinfo) parameters or enabling disk UUIDs for the VMs (`disk.EnableUUID=TRUE`). | + + +### About VM Creation Methods + +In the **Creation method** field, configure the method used to provision VMs in vSphere. Available options include creating VMs that boot from a RancherOS ISO or creating VMs by cloning from an existing virtual machine or [VM template](https://docs.vmware.com/en/VMware-vSphere/6.5/com.vmware.vsphere.vm_admin.doc/GUID-F7BF0E6B-7C4F-4E46-8BBF-76229AEA7220.html). + +The existing VM or template may use any modern Linux operating system that is configured with support for [cloud-init](https://cloudinit.readthedocs.io/en/latest/) using the [NoCloud datasource](https://canonical-cloud-init.readthedocs-hosted.com/en/latest/reference/datasources/nocloud.html). + +Choose the way that the VM will be created: + +- **Deploy from template: Data Center:** Choose a VM template that exists in the data center that you selected. +- **Deploy from template: Content Library:** First, select the [Content Library](https://docs.vmware.com/en/VMware-vSphere/6.5/com.vmware.vsphere.vm_admin.doc/GUID-254B2CE8-20A8-43F0-90E8-3F6776C2C896.html) that contains your template, then select the template from the populated list **Library templates**. +- **Clone an existing virtual machine:** In the **Virtual machine** field, choose an existing VM that the new VM will be cloned from. +- **Install from boot2docker ISO:** Ensure that the **OS ISO URL** field contains the URL of a VMware ISO release for RancherOS (`rancheros-vmware.iso`). Note that this URL must be accessible from the nodes running your Rancher server installation. + +## Networks + +The node template now allows a VM to be provisioned with multiple networks. In the **Networks** field, you can now click **Add Network** to add any networks available to you in vSphere. + +## Node Tags and Custom Attributes + +Tags allow you to attach metadata to objects in the vSphere inventory to make it easier to sort and search for these objects. + +For tags, all your vSphere tags will show up as options to select from in your node template. + +In the custom attributes, Rancher will let you select all the custom attributes you have already set up in vSphere. The custom attributes are keys and you can enter values for each one. + +:::note + +Custom attributes are a legacy feature that will eventually be removed from vSphere. + +::: + +## cloud-init + +[Cloud-init](https://cloudinit.readthedocs.io/en/latest/) allows you to initialize your nodes by applying configuration on the first boot. This may involve things such as creating users, authorizing SSH keys or setting up the network. + +To make use of cloud-init initialization, create a cloud config file using valid YAML syntax and paste the file content in the the **Cloud Init** field. Refer to the [cloud-init documentation.](https://cloudinit.readthedocs.io/en/latest/topics/examples.html) for a commented set of examples of supported cloud config directives. + +Note that cloud-init is not supported when using the ISO creation method. + +## Engine Options + +In the **Engine Options** section of the node template, you can configure the container daemon. You may want to specify the container version or a container image registry mirror. + +:::note +If you're provisioning Red Hat Enterprise Linux (RHEL) or CentOS nodes, leave the **Docker Install URL** field as the default value, or select **none**. This will bypass a check for Docker installation, as Docker is already installed on these node types. + +If you set **Docker Install URL** to a value other than the default or **none**, you might see an error message such as the following: `Error creating machine: RHEL ssh command error: command: sudo -E yum install -y curl err: exit status 1 output: Updating Subscription Management repositories.` +::: diff --git a/versioned_docs/version-2.14/reference-guides/cluster-configuration/rancher-server-configuration/aks-cluster-configuration.md b/versioned_docs/version-2.14/reference-guides/cluster-configuration/rancher-server-configuration/aks-cluster-configuration.md new file mode 100644 index 00000000000..2e479ae0248 --- /dev/null +++ b/versioned_docs/version-2.14/reference-guides/cluster-configuration/rancher-server-configuration/aks-cluster-configuration.md @@ -0,0 +1,221 @@ +--- +title: AKS Cluster Configuration Reference +--- + + + + + +## Role-based Access Control + +When provisioning an AKS cluster in the Rancher UI, RBAC cannot be disabled. If RBAC is disabled in the AKS cluster, the cluster cannot be registered or imported into Rancher. In practice, this means that local accounts must be enabled in order to register or import an AKS cluster. + +Rancher can configure member roles for AKS clusters in the same way as any other cluster. For more information, see the section on [role-based access control.](../../../how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/manage-role-based-access-control-rbac.md) + +## Cloud Credentials + +:::note + +The configuration information in this section assumes you have already set up a service principal for Rancher. For step-by-step instructions for how to set up the service principal, see [this section.](../../../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-clusters-from-hosted-kubernetes-providers/aks.md#prerequisites-in-microsoft-azure) + +::: + +### Subscription ID + +To get the subscription ID, click **All Services** in the left navigation bar. Then click **Subscriptions**. Go to the name of the subscription that you want to associate with your Kubernetes cluster and copy the **Subscription ID**. + +### Client ID + +To get the client ID, go to the Azure Portal, then click **Azure Active Directory**, then click **App registrations,** then click the name of the service principal. The client ID is listed on the app registration detail page as **Application (client) ID**. + +### Client Secret + +You can't retrieve the client secret value after it is created, so if you don't already have a client secret value, you will need to create a new client secret. + +To get a new client secret, go to the Azure Portal, then click **Azure Active Directory**, then click **App registrations,** then click the name of the service principal. + +Then click **Certificates & secrets** and click **New client secret**. Click **Add**. Then copy the **Value** of the new client secret. + +### Environment + +Microsoft provides multiple [clouds](https://docs.microsoft.com/en-us/cli/azure/cloud?view=azure-cli-latest) for compliance with regional laws, which are available for your use: + +- AzurePublicCloud +- AzureGermanCloud +- AzureChinaCloud +- AzureUSGovernmentCloud + +## Account Access + +In this section you will need to select an existing Azure cloud credential or create a new one. + +For help configuring your Azure cloud credential, see [this section.](#cloud-credentials) + +## Cluster Location + +Configure the cluster and node location. For more information on availability zones for AKS, see the [AKS documentation.](https://docs.microsoft.com/en-us/azure/aks/availability-zones) + +The high availability locations include multiple availability zones. + +## Cluster Options + +### Kubernetes Version + +The available Kubernetes versions are dynamically fetched from the Azure API. + +### Cluster Resource Group + +A resource group is a container that holds related resources for an Azure solution. The resource group can include all the resources for the solution, or only those resources that you want to manage as a group. You decide how you want to allocate resources to resource groups based on what makes the most sense for your organization. Generally, add resources that share the same lifecycle to the same resource group so you can easily deploy, update, and delete them as a group. + +Use an existing resource group or enter a resource group name and one will be created for you. + +Using a resource group containing an existing AKS cluster will create a new resource group. Azure AKS only allows one AKS cluster per resource group. + +For information on managing resource groups, see the [Azure documentation.](https://docs.microsoft.com/en-us/azure/azure-resource-manager/management/manage-resource-groups-portal) + +### Linux Admin Username + +The username used to create an SSH connection to the Linux nodes. + +The default username for AKS nodes is `azureuser`. + +### SSH Public Key + +The key used to create an SSH connection to the Linux nodes. + +### Tags + +Cluster tags can be useful if your organization uses tags as a way to organize resources across multiple Azure services. These tags don't apply to resources within the cluster. + +## Networking Options + +### LoadBalancer SKU + +Azure load balancers support both standard and basic SKUs (stock keeping units). + +For a comparison of standard and basic load balancers, see the official [Azure documentation.](https://docs.microsoft.com/en-us/azure/load-balancer/skus#skus) Microsoft recommends the Standard load balancer. + +The Standard load balancer is required if you have selected one or more availability zones, or if you have more than one node pool. + +### Network Policy + +All pods in an AKS cluster can send and receive traffic without limitations, by default. To improve security, you can define rules that control the flow of traffic. The Network Policy feature in Kubernetes lets you define rules for ingress and egress traffic between pods in a cluster. + +Azure provides two ways to implement network policy. You choose a network policy option when you create an AKS cluster. The policy option can't be changed after the cluster is created: + +- Azure's own implementation, called Azure Network Policies. The Azure network policy requires the Azure CNI. +- Calico Network Policies, an open-source network and network security solution founded by [Tigera](https://www.tigera.io/). + +You can also choose to have no network policy. + +For more information about the differences between Azure and Calico network policies and their capabilities, see the [AKS documentation.](https://docs.microsoft.com/en-us/azure/aks/use-network-policies#differences-between-azure-and-calico-policies-and-their-capabilities) + +### DNS Prefix +Enter a unique DNS prefix for your cluster's Kubernetes API server FQDN. + +### Network Plugin +There are two network plugins: kubenet and Azure CNI. + +The [kubenet](https://kubernetes.io/docs/concepts/cluster-administration/network-plugins/#kubenet) Kubernetes plugin is the default configuration for AKS cluster creation. When kubenet is used, each node in the cluster receives a routable IP address. The pods use NAT to communicate with other resources outside the AKS cluster. This approach reduces the number of IP addresses you need to reserve in your network space for pods to use. + +With the Azure CNI (advanced) networking plugin, pods get full virtual network connectivity and can be directly reached via their private IP address from connected networks. This plugin requires more IP address space. + +For more information on the differences between kubenet and Azure CNI, see the [AKS documentation.](https://docs.microsoft.com/en-us/azure/aks/concepts-network#compare-network-models) + +### HTTP Application Routing + +When enabled, the HTTP application routing add-on makes it easier to access applications deployed to the AKS cluster. It deploys two components: a [Kubernetes Ingress controller](https://kubernetes.io/docs/concepts/services-networking/ingress/) and an [External-DNS](https://github.com/kubernetes-incubator/external-dns) controller. + +For more information, see the [AKS documentation.](https://docs.microsoft.com/en-us/azure/aks/http-application-routing) + +### Set Authorized IP Ranges + +You can secure access to the Kubernetes API server using [authorized IP address ranges.](https://docs.microsoft.com/en-us/azure/aks/api-server-authorized-ip-ranges#overview-of-api-server-authorized-ip-ranges) + +The Kubernetes API server exposes the Kubernetes API. This component provides the interaction for management tools, such as kubectl. AKS provides a single-tenant cluster control plane with a dedicated API server. By default, the API server is assigned a public IP address, and you should control access to it using Kubernetes-based or Azure-based RBAC. + +To secure access to the otherwise publicly accessible AKS control plane and API server, you can enable and use authorized IP ranges. These authorized IP ranges only allow defined IP address ranges to communicate with the API server. + +However, even if you use authorized IP address ranges, you should still use Kubernetes RBAC or Azure RBAC to authorize users and the actions they request. + +### Container Monitoring + +Container monitoring gives you performance visibility by collecting memory and processor metrics from controllers, nodes, and containers that are available in Kubernetes through the Metrics API. Container logs are also collected. After you enable monitoring, metrics and logs are automatically collected for you through a containerized version of the Log Analytics agent for Linux. Metrics are written to the metrics store and log data is written to the logs store associated with your [Log Analytics](https://docs.microsoft.com/en-us/azure/azure-monitor/logs/log-query-overview) workspace. + +### Log Analytics Workspace Resource Group + +The [resource group](https://docs.microsoft.com/en-us/azure/azure-resource-manager/management/overview#resource-groups) containing the Log Analytics Workspace. You must create at least one workspace to use Azure Monitor Logs. + +### Log Analytics Workspace Name + +Data collected by Azure Monitor Logs is stored in one or more [Log Analytics workspaces.](https://docs.microsoft.com/en-us/azure/azure-monitor/logs/design-logs-deployment) The workspace defines the geographic location of the data, access rights defining which users can access data, and configuration settings such as the pricing tier and data retention. + +You must create at least one workspace to use Azure Monitor Logs. A single workspace may be suffxicient for all of your monitoring data, or may choose to create multiple workspaces depending on your requirements. For example, you might have one workspace for your production data and another for testing. + +For more information about Azure Monitor Logs, see the [Azure documentation.](https://docs.microsoft.com/en-us/azure/azure-monitor/logs/data-platform-logs) + +### Support Private Kubernetes Service + +Typically, AKS worker nodes do not get public IPs, regardless of whether the cluster is private. In a private cluster, the control plane does not have a public endpoint. + +Rancher can connect to a private AKS cluster in one of two ways. + +The first way to ensure that Rancher is running on the same [NAT](https://docs.microsoft.com/en-us/azure/virtual-network/nat-overview) as the AKS nodes. + +The second way is to run a command to register the cluster with Rancher. Once the cluster is provisioned, you can run the displayed command anywhere you can connect to the cluster’s Kubernetes API. This command is displayed in a pop-up when you provision an AKS cluster with a private API endpoint enabled. + +:::note + +Please be aware that when registering an existing AKS cluster, the cluster might take some time, possibly hours, to appear in the `Cluster To register` dropdown list. This outcome will be based on region. + +::: + +For more information about connecting to an AKS private cluster, see the [AKS documentation.](https://docs.microsoft.com/en-us/azure/aks/private-clusters#options-for-connecting-to-the-private-cluster) + +## Node Pools + +### Mode + +The Azure interface allows users to specify whether a Primary Node Pool relies on either `system` (normally used for control planes) or `user` (what is most typically needed for Rancher). + +For Primary Node Pools, you can specify Mode, OS, Count and Size. + +System node pools always require running nodes, so they cannot be scaled below one node. At least one system node pool is required. + +For subsequent node pools, the Rancher UI forces the default of User. User node pools allow you to scale to zero nodes. User node pools don't run any part of the Kubernetes controlplane. + +AKS doesn't expose the nodes that run the Kubernetes controlplane components. + +### Availability Zones + +[Availability zones](https://docs.microsoft.com/en-us/azure/availability-zones/az-overview) are unique physical locations within a region. Each zone is made up of one or more data centers equipped with independent power, cooling, and networking. + +Not all regions have support for availability zones. For a list of Azure regions with availability zones, see the [Azure documentation.](https://docs.microsoft.com/en-us/azure/availability-zones/az-region#azure-regions-with-availability-zones) + +### VM Size + +Choose a size for each VM in the node pool. For details about each VM size, see [this page.](https://azure.microsoft.com/en-us/pricing/details/virtual-machines/linux/) + +### OS Disk Type + +The nodes in the node pool can have either managed or ephemeral disks. + +[Ephemeral OS disks](https://docs.microsoft.com/en-us/azure/virtual-machines/ephemeral-os-disks) are created on the local virtual machine storage and not saved to the remote Azure Storage. Ephemeral OS disks work well for stateless workloads, where applications are tolerant of individual VM failures, but are more affected by VM deployment time or reimaging the individual VM instances. With Ephemeral OS disk, you get lower read/write latency to the OS disk and faster VM reimage. + +[Azure managed disks](https://docs.microsoft.com/en-us/azure/virtual-machines/managed-disks-overview) are block-level storage volumes that are managed by Azure and used with Azure Virtual Machines. Managed disks are designed for 99.999% availability. Managed disks achieve this by providing you with three replicas of your data, allowing for high durability. + +### OS Disk Size + +The size in GB for the disk for each node. + +### Node Count +The number of nodes in the node pool. The maximum number of nodes may be limited by your [Azure subscription.](https://docs.microsoft.com/en-us/azure/azure-resource-manager/management/azure-subscription-service-limits) + +### Max Pods Per Node +The maximum number of pods per node defaults to 110 with a maximum of 250. + +### Enable Auto Scaling + +When auto scaling is enabled, you will need to enter a minimum and maximum node count. + +When Auto Scaling is enabled, you can't manually scale the node pool. The scale is controlled by the AKS autoscaler. diff --git a/versioned_docs/version-2.14/reference-guides/cluster-configuration/rancher-server-configuration/eks-cluster-configuration.md b/versioned_docs/version-2.14/reference-guides/cluster-configuration/rancher-server-configuration/eks-cluster-configuration.md new file mode 100644 index 00000000000..dd3bf822712 --- /dev/null +++ b/versioned_docs/version-2.14/reference-guides/cluster-configuration/rancher-server-configuration/eks-cluster-configuration.md @@ -0,0 +1,180 @@ +--- +title: EKS Cluster Configuration Reference +--- + + + + + +### Account Access + +Complete each drop-down and field using the information obtained for your IAM policy. + +| Setting | Description | +| ---------- | -------------------------------------------------------------------------------------------------------------------- | +| Region | From the drop-down choose the geographical region in which to build your cluster. | +| Cloud Credentials | Select the cloud credentials that you created for your IAM policy. For more information on creating cloud credentials in Rancher, refer to [this page.](../../user-settings/manage-cloud-credentials.md) | + +### Service Role + +Choose a [service role](https://docs.aws.amazon.com/IAM/latest/UserGuide/using-service-linked-roles.html). + +Service Role | Description +-------------|--------------------------- +Standard: Rancher generated service role | If you choose this role, Rancher automatically adds a service role for use with the cluster. +Custom: Choose from your existing service roles | If you choose this role, Rancher lets you choose from service roles that you're already created within AWS. For more information on creating a custom service role in AWS, see the [Amazon documentation](https://docs.aws.amazon.com/IAM/latest/UserGuide/using-service-linked-roles.html#create-service-linked-role). + +### Secrets Encryption + +Optional: To encrypt secrets, select or enter a key created in [AWS Key Management Service (KMS)](https://docs.aws.amazon.com/kms/latest/developerguide/overview.html) + +### API Server Endpoint Access + +Configuring Public/Private API access is an advanced use case. For details, refer to the EKS cluster endpoint access control [documentation.](https://docs.aws.amazon.com/eks/latest/userguide/cluster-endpoint.html) + +### Private-only API Endpoints + +If you enable private and disable public API endpoint access when creating a cluster, then there is an extra step you must take in order for Rancher to connect to the cluster successfully. In this case, a pop-up will be displayed with a command that you will run on the cluster to register it with Rancher. Once the cluster is provisioned, you can run the displayed command anywhere you can connect to the cluster's Kubernetes API. + +There are two ways to avoid this extra manual step: +- You can create the cluster with both private and public API endpoint access on cluster creation. You can disable public access after the cluster is created and in an active state and Rancher will continue to communicate with the EKS cluster. +- You can ensure that Rancher shares a subnet with the EKS cluster. Then security groups can be used to enable Rancher to communicate with the cluster's API endpoint. In this case, the command to register the cluster is not needed, and Rancher will be able to communicate with your cluster. For more information on configuring security groups, refer to the [security groups documentation](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_SecurityGroups.html). + +### Public Access Endpoints + +Optionally limit access to the public endpoint via explicit CIDR blocks. + +If you limit access to specific CIDR blocks, then it is recommended that you also enable the private access to avoid losing network communication to the cluster. + +One of the following is required to enable private access: +- Rancher's IP must be part of an allowed CIDR block +- Private access should be enabled, and Rancher must share a subnet with the cluster and have network access to the cluster, which can be configured with a security group + +For more information about public and private access to the cluster endpoint, refer to the [Amazon EKS documentation.](https://docs.aws.amazon.com/eks/latest/userguide/cluster-endpoint.html) + +### Subnet + +| Option | Description | +| ------- | ------------ | +| Standard: Rancher generated VPC and Subnet | While provisioning your cluster, Rancher generates a new VPC with 3 public subnets. | +| Custom: Choose from your existing VPC and Subnets | While provisioning your cluster, Rancher configures your Control Plane and nodes to use a VPC and Subnet that you've already [created in AWS](https://docs.aws.amazon.com/vpc/latest/userguide/what-is-amazon-vpc.html). | + + For more information, refer to the AWS documentation for [Cluster VPC Considerations](https://docs.aws.amazon.com/eks/latest/userguide/network_reqs.html). Follow one of the sets of instructions below based on your selection from the previous step. + +- [What Is Amazon VPC?](https://docs.aws.amazon.com/vpc/latest/userguide/what-is-amazon-vpc.html) +- [VPCs and Subnets](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_Subnets.html) + +### Security Group + +Amazon Documentation: + +- [Cluster Security Group Considerations](https://docs.aws.amazon.com/eks/latest/userguide/sec-group-reqs.html) +- [Security Groups for Your VPC](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_SecurityGroups.html) +- [Create a Security Group](https://docs.aws.amazon.com/vpc/latest/userguide/getting-started-ipv4.html#getting-started-create-security-group) + +### Logging + +Configure control plane logs to send to Amazon CloudWatch. You are charged the standard CloudWatch Logs data ingestion and storage costs for any logs sent to CloudWatch Logs from your clusters. + +Each log type corresponds to a component of the Kubernetes control plane. To learn more about these components, see [Kubernetes Components](https://kubernetes.io/docs/concepts/overview/components/) in the Kubernetes documentation. + +For more information on EKS control plane logging, refer to the official [documentation.](https://docs.aws.amazon.com/eks/latest/userguide/control-plane-logs.html) + +### Managed Node Groups + +Amazon EKS managed node groups automate the provisioning and lifecycle management of nodes (Amazon EC2 instances) for Amazon EKS Kubernetes clusters. + +For more information about how node groups work and how they are configured, refer to the [EKS documentation.](https://docs.aws.amazon.com/eks/latest/userguide/managed-node-groups.html) + +#### User-provided Launch Templates + +You can provide your own launch template ID and version to configure the EC2 instances in a node group. If you provide the launch template, none of the template settings will be configurable from Rancher. You must set all of the required options listed below in your launch template. + +Also, if you provide the launch template, you can only update the template version, not the template ID. To use a new template ID, create a new managed node group. + +| Option | Description | Required/Optional | +| ------ | ----------- | ----------------- | +| Instance Type | Choose the [hardware specs](https://aws.amazon.com/ec2/instance-types/) for the instance you're provisioning. | Required | +| Image ID | Specify a custom AMI for the nodes. Custom AMIs used with EKS must be [configured properly](https://aws.amazon.com/premiumsupport/knowledge-center/eks-custom-linux-ami/) | Optional | +| Node Volume Size | The launch template must specify an EBS volume with the desired size | Required | +| SSH Key | A key to be added to the instances to provide SSH access to the nodes | Optional | +| User Data | Cloud init script in [MIME multi-part format](https://docs.aws.amazon.com/eks/latest/userguide/launch-templates.html#launch-template-user-data) | Optional | +| Instance Resource Tags | Tag each EC2 instance and its volumes in the node group | Optional | + +:::caution + +You can't directly update a node group to a newer Kubernetes version if the node group was created from a custom launch template. You must create a new launch template with the proper Kubernetes version, and associate the node group with the new template. + +::: + + +#### Rancher-managed Launch Templates + +If you do not specify a launch template, then you will be able to configure the above options in the Rancher UI and all of them can be updated after creation. In order to take advantage of all of these options, Rancher will create and manage a launch template for you. Each cluster in Rancher will have one Rancher-managed launch template and each managed node group that does not have a specified launch template will have one version of the managed launch template. The name of this launch template will have the prefix "rancher-managed-lt-" followed by the display name of the cluster. In addition, the Rancher-managed launch template will be tagged with the key "rancher-managed-template" and value "do-not-modify-or-delete" to help identify it as Rancher-managed. It is important that this launch template and its versions not be modified, deleted, or used with any other clusters or managed node groups. Doing so could result in your node groups being "degraded" and needing to be destroyed and recreated. + +#### Custom AMIs + +If you specify a custom AMI, whether in a launch template or in Rancher, then the image must be [configured properly](https://aws.amazon.com/premiumsupport/knowledge-center/eks-custom-linux-ami/) and you must provide user data to [bootstrap the node](https://docs.aws.amazon.com/eks/latest/userguide/launch-templates.html#launch-template-custom-ami). This is considered an advanced use case and understanding the requirements is imperative. + +If you specify a launch template that does not contain a custom AMI, then Amazon will use the [EKS-optimized AMI](https://docs.aws.amazon.com/eks/latest/userguide/eks-optimized-ami.html) for the Kubernetes version and selected region. You can also select a [GPU enabled instance](https://docs.aws.amazon.com/eks/latest/userguide/eks-optimized-ami.html#gpu-ami) for workloads that would benefit from it. + +:::note + +The GPU enabled instance setting in Rancher is ignored if a custom AMI is provided, either in the dropdown or in a launch template. + +::: + +#### Spot instances + +Spot instances are now [supported by EKS](https://docs.aws.amazon.com/eks/latest/userguide/managed-node-groups.html#managed-node-group-capacity-types-spot). If a launch template is specified, Amazon recommends that the template not provide an instance type. Instead, Amazon recommends providing multiple instance types. If the "Request Spot Instances" checkbox is enabled for a node group, then you will have the opportunity to provide multiple instance types. + +:::note + +Any selection you made in the instance type dropdown will be ignored in this situation and you must specify at least one instance type to the "Spot Instance Types" section. Furthermore, a launch template used with EKS cannot request spot instances. Requesting spot instances must be part of the EKS configuration. + +::: + +#### Node Group Settings + +The following settings are also configurable. All of these except for the "Node Group Name" are editable after the node group is created. + +| Option | Description | +| ------- | ------------ | +| Node Group Name | The name of the node group. | +| Desired ASG Size | The desired number of instances. | +| Maximum ASG Size | The maximum number of instances. This setting won't take effect until the [Cluster Autoscaler](https://docs.aws.amazon.com/eks/latest/userguide/cluster-autoscaler.html) is installed. | +| Minimum ASG Size | The minimum number of instances. This setting won't take effect until the [Cluster Autoscaler](https://docs.aws.amazon.com/eks/latest/userguide/cluster-autoscaler.html) is installed. | +| Labels | Kubernetes labels applied to the nodes in the managed node group. | +| Tags | These are tags for the managed node group and do not propagate to any of the associated resources. | + +### Self-managed Amazon Linux Nodes + +You can register an EKS cluster containing self-managed Amazon Linux nodes. You must configure this type of cluster according to the instructions in the official AWS documentation for [launching self-managed Amazon Linux nodes](https://docs.aws.amazon.com/eks/latest/userguide/launch-workers.html). EKS clusters containing self-managed Amazon Linux nodes are usually operated by the [Karpenter](https://karpenter.sh/docs/) project. After you provision an EKS cluster containing self-managed Amazon Linux nodes, [register the cluster](../../../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/register-existing-clusters.md) so it can be managed by Rancher. However, the nodes won't be visible in the Rancher UI. + +### IAM Roles for Service Accounts + +An Applications Deployment running on an EKS cluster can make requests to AWS services via IAM permissions. These applications must sign their requests with AWS credentials. IAM roles for service accounts manage these credentials using an AWS OIDC endpoint. Rather than distributing AWS credentials to containers or relying on an EC2 instance's role, you can link an [IAM role to a Kubernetes service account](https://docs.aws.amazon.com/eks/latest/userguide/iam-roles-for-service-accounts.html) and configure your Pods to use this account. + +:::note + +Linking to an IAM role is not supported for Rancher pods in an EKS cluster. + +::: + +To enable IAM roles for service accounts: +1. [Create an IAM OIDC provider for your cluster](https://docs.aws.amazon.com/eks/latest/userguide/enable-iam-roles-for-service-accounts.html) +1. [Configure a Kubernetes service account to assume an IAM role](https://docs.aws.amazon.com/eks/latest/userguide/associate-service-account-role.html) +1. [Configure Pods to use a Kubernetes service account](https://docs.aws.amazon.com/eks/latest/userguide/pod-configuration.html) +1. [Use a supported AWS SDK](https://docs.aws.amazon.com/eks/latest/userguide/iam-roles-for-service-accounts-minimum-sdk.html) + +### Configuring the Refresh Interval + +The `eks-refresh-cron` setting is deprecated. It has been migrated to the `eks-refresh` setting, which is an integer representing seconds. + +The default value is 300 seconds. + +The syncing interval can be changed by running `kubectl edit setting eks-refresh`. + +If the `eks-refresh-cron` setting was previously set, the migration will happen automatically. + +The shorter the refresh window, the less likely any race conditions will occur, but it does increase the likelihood of encountering request limits that may be in place for AWS APIs. diff --git a/versioned_docs/version-2.14/reference-guides/cluster-configuration/rancher-server-configuration/gke-cluster-configuration/gke-cluster-configuration.md b/versioned_docs/version-2.14/reference-guides/cluster-configuration/rancher-server-configuration/gke-cluster-configuration/gke-cluster-configuration.md new file mode 100644 index 00000000000..a604d75ef3d --- /dev/null +++ b/versioned_docs/version-2.14/reference-guides/cluster-configuration/rancher-server-configuration/gke-cluster-configuration/gke-cluster-configuration.md @@ -0,0 +1,327 @@ +--- +title: GKE Cluster Configuration Reference +--- + + + + + +## Cluster Location + +| Value | Description | +|--------|--------------| +| Location Type | Zonal or Regional. With GKE, you can create a cluster tailored to the availability requirements of your workload and your budget. By default, a cluster's nodes run in a single compute zone. When multiple zones are selected, the cluster's nodes will span multiple compute zones, while the controlplane is located in a single zone. Regional clusters increase the availability of the controlplane as well. For help choosing the type of cluster availability, refer to [these docs.](https://cloud.google.com/kubernetes-engine/docs/best-practices/scalability#choosing_a_regional_or_zonal_control_plane) | +| Zone | Each region in Compute engine contains a number of zones. For more information about available regions and zones, refer to [these docs.](https://cloud.google.com/compute/docs/regions-zones#available) | +| Additional Zones | For zonal clusters, you can select additional zones to create a [multi-zone cluster.](https://cloud.google.com/kubernetes-engine/docs/concepts/types-of-clusters#multi-zonal_clusters) | +| Region | For [regional clusters,](https://cloud.google.com/kubernetes-engine/docs/concepts/types-of-clusters#regional_clusters) you can select a region. For more information about available regions and zones, refer to [this section](https://cloud.google.com/compute/docs/regions-zones#available). The first part of each zone name is the name of the region. | + +## Cluster Options + +### Kubernetes Version + +_Mutable: yes_ + +For more information on GKE Kubernetes versions, refer to [these docs.](https://cloud.google.com/kubernetes-engine/versioning) + +### Container Address Range + +_Mutable: no_ + +The IP address range for pods in the cluster. Must be a valid CIDR range, e.g. 10.42.0.0/16. If not specified, a random range is automatically chosen from 10.0.0.0/8 and will exclude ranges already allocated to VMs, other clusters, or routes. Automatically chosen ranges may conflict with reserved IP addresses, dynamic routes, or routes within VPCs peering with the cluster. + +### Network + +_Mutable: no_ + +The Compute Engine Network that the cluster connects to. Routes and firewalls will be created using this network. If using [Shared VPCs](https://cloud.google.com/vpc/docs/shared-vpc), the VPC networks that are shared to your project will appear here. will be available to select in this field. For more information, refer to [this page](https://cloud.google.com/vpc/docs/vpc#vpc_networks_and_subnets). + +### Node Subnet / Subnet + +_Mutable: no_ + +The Compute Engine subnetwork that the cluster connects to. This subnetwork must belong to the network specified in the **Network** field. Select an existing subnetwork, or select "Auto Create Subnetwork" to have one automatically created. If not using an existing network, **Subnetwork Name** is required to generate one. If using [Shared VPCs](https://cloud.google.com/vpc/docs/shared-vpc), the VPC subnets that are shared to your project will appear here. If using a Shared VPC network, you cannot select "Auto Create Subnetwork". For more information, refer to [this page.](https://cloud.google.com/vpc/docs/vpc#vpc_networks_and_subnets) + +### Subnetwork Name + +_Mutable: no_ + +Automatically create a subnetwork with the provided name. Required if "Auto Create Subnetwork" is selected for **Node Subnet** or **Subnet**. For more information on subnetworks, refer to [this page.](https://cloud.google.com/vpc/docs/vpc#vpc_networks_and_subnets) + +### Ip Aliases + +_Mutable: no_ + +Enable [alias IPs](https://cloud.google.com/vpc/docs/alias-ip). This enables VPC-native traffic routing. Required if using [Shared VPCs](https://cloud.google.com/vpc/docs/shared-vpc). + +### Network Policy + +_Mutable: yes_ + +Enable network policy enforcement on the cluster. A network policy defines the level of communication that can occur between pods and services in the cluster. For more information, refer to [this page.](https://cloud.google.com/kubernetes-engine/docs/how-to/network-policy) + +### Project Network Isolation + +_Mutable: yes_ + +Choose whether to enable or disable inter-project communication. + +#### Imported Clusters + +For imported clusters, Project Network Isolation (PNI) requires Kubernetes Network Policy to be enabled on the cluster beforehand. +For clusters created by Rancher, Rancher enables Kubernetes Network Policy automatically. + +1. In GKE, enable Network Policy at the cluster level. Refer to the [official GKE guide](https://cloud.google.com/kubernetes-engine/docs/how-to/network-policy) for instructions. +1. After enabling Network Policy, import the cluster into Rancher and enable PNI for project-level isolation. + +### Node Ipv4 CIDR Block + +_Mutable: no_ + +The IP address range of the instance IPs in this cluster. Can be set if "Auto Create Subnetwork" is selected for **Node Subnet** or **Subnet**. Must be a valid CIDR range, e.g. 10.96.0.0/14. For more information on how to determine the IP address range, refer to [this page.](https://cloud.google.com/kubernetes-engine/docs/concepts/alias-ips#cluster_sizing) + +### Cluster Secondary Range Name + +_Mutable: no_ + +The name of an existing secondary range for Pod IP addresses. If selected, **Cluster Pod Address Range** will automatically be populated. Required if using a Shared VPC network. + +### Cluster Pod Address Range + +_Mutable: no_ + +The IP address range assigned to pods in the cluster. Must be a valid CIDR range, e.g. 10.96.0.0/11. If not provided, will be created automatically. Must be provided if using a Shared VPC network. For more information on how to determine the IP address range for your pods, refer to [this section.](https://cloud.google.com/kubernetes-engine/docs/concepts/alias-ips#cluster_sizing_secondary_range_pods) + +### Services Secondary Range Name + +_Mutable: no_ + +The name of an existing secondary range for service IP addresses. If selected, **Service Address Range** will be automatically populated. Required if using a Shared VPC network. + +### Service Address Range + +_Mutable: no_ + +The address range assigned to the services in the cluster. Must be a valid CIDR range, e.g. 10.94.0.0/18. If not provided, will be created automatically. Must be provided if using a Shared VPC network. For more information on how to determine the IP address range for your services, refer to [this section.](https://cloud.google.com/kubernetes-engine/docs/concepts/alias-ips#cluster_sizing_secondary_range_svcs) + +### Private Cluster + +_Mutable: no_ + +:::caution + +Private clusters require additional planning and configuration outside of Rancher. Refer to the [private cluster guide](gke-private-clusters.md). + +::: + +Assign nodes only internal IP addresses. Private cluster nodes cannot access the public internet unless additional networking steps are taken in GCP. + +### Enable Private Endpoint + +:::caution + +Private clusters require additional planning and configuration outside of Rancher. Refer to the [private cluster guide](gke-private-clusters.md). + +::: + +_Mutable: no_ + +Locks down external access to the control plane endpoint. Only available if **Private Cluster** is also selected. If selected, and if Rancher does not have direct access to the Virtual Private Cloud network the cluster is running in, Rancher will provide a registration command to run on the cluster to enable Rancher to connect to it. + +### Master IPV4 CIDR Block + +_Mutable: no_ + +The IP range for the control plane VPC. + +### Master Authorized Network + +_Mutable: yes_ + +Enable control plane authorized networks to block untrusted non-GCP source IPs from accessing the Kubernetes master through HTTPS. If selected, additional authorized networks may be added. If the cluster is created with a public endpoint, this option is useful for locking down access to the public endpoint to only certain networks, such as the network where your Rancher service is running. If the cluster only has a private endpoint, this setting is required. + +## Additional Options + +### Cluster Addons + +Additional Kubernetes cluster components. For more information, refer to [this page.](https://cloud.google.com/kubernetes-engine/docs/reference/rest/v1/projects.locations.clusters#Cluster.AddonsConfig) + +#### Horizontal Pod Autoscaling + +_Mutable: yes_ + +The Horizontal Pod Autoscaler changes the shape of your Kubernetes workload by automatically increasing or decreasing the number of Pods in response to the workload's CPU or memory consumption, or in response to custom metrics reported from within Kubernetes or external metrics from sources outside of your cluster. For more information, see [this page.](https://cloud.google.com/kubernetes-engine/docs/concepts/horizontalpodautoscaler) + +#### HTTP (L7) Load Balancing + +_Mutable: yes_ + +HTTP (L7) Load Balancing distributes HTTP and HTTPS traffic to backends hosted on GKE. For more information, refer to [this page.](https://cloud.google.com/kubernetes-engine/docs/tutorials/http-balancer) + +#### Network Policy Config (master only) + +_Mutable: yes_ + +Configuration for NetworkPolicy. This only tracks whether the addon is enabled or not on the master, it does not track whether network policy is enabled for the nodes. + +### Cluster Features (Alpha Features) + +_Mutable: no_ + +Turns on all Kubernetes alpha API groups and features for the cluster. When enabled, the cluster cannot be upgraded and will be deleted automatically after 30 days. Alpha clusters are not recommended for production use as they are not covered by the GKE SLA. For more information, refer to [this page.](https://cloud.google.com/kubernetes-engine/docs/concepts/alpha-clusters) + +### Logging Service + +_Mutable: yes_ + +The logging service the cluster uses to write logs. Use either [Cloud Logging](https://cloud.google.com/logging) or no logging service in which case no logs are exported from the cluster. + +### Monitoring Service + +_Mutable: yes_ + +The monitoring service the cluster uses to write metrics. Use either [Cloud Monitoring](https://cloud.google.com/monitoring) or monitoring service in which case no metrics are exported from the cluster. + + +### Maintenance Window + +_Mutable: yes_ + +Set the start time for a 4 hour maintenance window. The time is specified in the UTC time zone using the HH:MM format. For more information, refer to [this page.](https://cloud.google.com/kubernetes-engine/docs/concepts/maintenance-windows-and-exclusions) + +## Node Pools + +In this section, enter details describing the configuration of each node in the node pool. + +### Kubernetes Version + +_Mutable: yes_ + +The Kubernetes version for each node in the node pool. For more information on GKE Kubernetes versions, refer to [these docs.](https://cloud.google.com/kubernetes-engine/versioning) + +### Image Type + +_Mutable: yes_ + +The node operating system image. For more information for the node image options that GKE offers for each OS, refer to [this page.](https://cloud.google.com/kubernetes-engine/docs/concepts/node-images#available_node_images) + +:::note + +The default option is "Container-Optimized OS with Docker". The read-only filesystem on GCP's Container-Optimized OS is not compatible with the [legacy logging](https://github.com/rancher/rancher-docs/tree/main/archived_docs/en/version-2.0-2.4/explanations/integrations-in-rancher/cluster-logging/cluster-logging.md) implementation in Rancher. If you need to use the legacy logging feature, select "Ubuntu with Docker" or "Ubuntu with Containerd". The [current logging feature](../../../../integrations-in-rancher/logging/logging.md) is compatible with the Container-Optimized OS image. + +::: + +:::note + +If selecting "Windows Long Term Service Channel" or "Windows Semi-Annual Channel" for the node pool image type, you must also add at least one Container-Optimized OS or Ubuntu node pool. + +::: + +### Machine Type + +_Mutable: no_ + +The virtualized hardware resources available to node instances. For more information on Google Cloud machine types, refer to [this page.](https://cloud.google.com/compute/docs/machine-types#machine_types) + +### Root Disk Type + +_Mutable: no_ + +Standard persistent disks are backed by standard hard disk drives (HDD), while SSD persistent disks are backed by solid state drives (SSD). For more information, refer to [this section.](https://cloud.google.com/compute/docs/disks) + +### Local SSD Disks + +_Mutable: no_ + +Configure each node's local SSD disk storage in GB. Local SSDs are physically attached to the server that hosts your VM instance. Local SSDs have higher throughput and lower latency than standard persistent disks or SSD persistent disks. The data that you store on a local SSD persists only until the instance is stopped or deleted. For more information, see [this section.](https://cloud.google.com/compute/docs/disks#localssds) + +### Preemptible nodes (beta) + +_Mutable: no_ + +Preemptible nodes, also called preemptible VMs, are Compute Engine VM instances that last a maximum of 24 hours in general, and provide no availability guarantees. For more information, see [this page.](https://cloud.google.com/kubernetes-engine/docs/how-to/preemptible-vms) + +### Taints + +_Mutable: no_ + +When you apply a taint to a node, only Pods that tolerate the taint are allowed to run on the node. In a GKE cluster, you can apply a taint to a node pool, which applies the taint to all nodes in the pool. + +### Node Labels + +_Mutable: no_ + +You can apply labels to the node pool, which applies the labels to all nodes in the pool. + +Invalid labels can prevent upgrades or can prevent Rancher from starting. For details on label syntax requirements, see the [Kubernetes documentation.](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/#syntax-and-character-set) + +### Network Tags + +_Mutable: no_ + +You can add network tags to the node pool to make firewall rules and routes between subnets. Tags will apply to all nodes in the pool. + +For details on tag syntax and requirements, see the [Kubernetes documentation](https://cloud.google.com/vpc/docs/add-remove-network-tags). + +## Group Details + +In this section, enter details describing the node pool. + +### Name + +_Mutable: no_ + +Enter a name for the node pool. + +### Initial Node Count + +_Mutable: yes_ + +Integer for the starting number of nodes in the node pool. + +### Max Pod Per Node + +_Mutable: no_ + +GKE has a hard limit of 110 Pods per node. For more information on the Kubernetes limits, see [this section.](https://cloud.google.com/kubernetes-engine/docs/best-practices/scalability#dimension_limits) + +### Autoscaling + +_Mutable: yes_ + +Node pool autoscaling dynamically creates or deletes nodes based on the demands of your workload. For more information, see [this page.](https://cloud.google.com/kubernetes-engine/docs/concepts/cluster-autoscaler) + +### Auto Repair + +_Mutable: yes_ + +GKE's node auto-repair feature helps you keep the nodes in your cluster in a healthy, running state. When enabled, GKE makes periodic checks on the health state of each node in your cluster. If a node fails consecutive health checks over an extended time period, GKE initiates a repair process for that node. For more information, see the section on [auto-repairing nodes.](https://cloud.google.com/kubernetes-engine/docs/how-to/node-auto-repair) + +### Auto Upgrade + +_Mutable: yes_ + +When enabled, the auto-upgrade feature keeps the nodes in your cluster up-to-date with the cluster control plane (master) version when your control plane is [updated on your behalf.](https://cloud.google.com/kubernetes-engine/upgrades#automatic_cp_upgrades) For more information about auto-upgrading nodes, see [this page.](https://cloud.google.com/kubernetes-engine/docs/how-to/node-auto-upgrades) + +### Access Scopes + +_Mutable: no_ + +Access scopes are the legacy method of specifying permissions for your nodes. + +- **Allow default access:** The default access for new clusters is the [Compute Engine default service account.](https://cloud.google.com/compute/docs/access/service-accounts?hl=en_US#default_service_account) +- **Allow full access to all Cloud APIs:** Generally, you can just set the cloud-platform access scope to allow full access to all Cloud APIs, then grant the service account only relevant IAM roles. The combination of access scopes granted to the virtual machine instance and the IAM roles granted to the service account determines the amount of access the service account has for that instance. +- **Set access for each API:** Alternatively, you can choose to set specific scopes that permit access to the particular API methods that the service will call. + +For more information, see the [section about enabling service accounts for a VM.](https://cloud.google.com/compute/docs/access/create-enable-service-accounts-for-instances) + + +### Configuring the Refresh Interval + +The refresh interval can be configured through the setting "gke-refresh", which is an integer representing seconds. + +The default value is 300 seconds. + +The syncing interval can be changed by running `kubectl edit setting gke-refresh`. + +The shorter the refresh window, the less likely any race conditions will occur, but it does increase the likelihood of encountering request limits that may be in place for GCP APIs. + diff --git a/versioned_docs/version-2.14/reference-guides/cluster-configuration/rancher-server-configuration/gke-cluster-configuration/gke-private-clusters.md b/versioned_docs/version-2.14/reference-guides/cluster-configuration/rancher-server-configuration/gke-cluster-configuration/gke-private-clusters.md new file mode 100644 index 00000000000..4322fb5e2d2 --- /dev/null +++ b/versioned_docs/version-2.14/reference-guides/cluster-configuration/rancher-server-configuration/gke-cluster-configuration/gke-private-clusters.md @@ -0,0 +1,54 @@ +--- +title: Private Clusters +--- + + + + + +In GKE, [private clusters](https://cloud.google.com/kubernetes-engine/docs/concepts/private-cluster-concept) are clusters whose nodes are isolated from inbound and outbound traffic by assigning them internal IP addresses only. Private clusters in GKE have the option of exposing the control plane endpoint as a publicly accessible address or as a private address. This is different from other Kubernetes providers, which may refer to clusters with private control plane endpoints as "private clusters" but still allow traffic to and from nodes. You may want to create a cluster with private nodes, with or without a public control plane endpoint, depending on your organization's networking and security requirements. A GKE cluster provisioned from Rancher can use isolated nodes by selecting "Private Cluster" in the Cluster Options (under "Show advanced options"). The control plane endpoint can optionally be made private by selecting "Enable Private Endpoint". + +## Private Nodes + +Because the nodes in a private cluster only have internal IP addresses, they will not be able to install the cluster agent and Rancher will not be able to fully manage the cluster. This can be overcome in a few ways. + +### Cloud NAT + +:::caution + +Cloud NAT will [incur charges](https://cloud.google.com/nat/pricing). + +::: + +If restricting outgoing internet access is not a concern for your organization, use Google's [Cloud NAT](https://cloud.google.com/nat/docs/using-nat) service to allow nodes in the private network to access the internet, enabling them to download the required images from Docker Hub and contact the Rancher management server. This is the simplest solution. + +### Private Registry + +:::caution + +This scenario is not officially supported, but is described for cases in which using the Cloud NAT service is not sufficient. + +::: + +If restricting both incoming and outgoing traffic to nodes is a requirement, follow the air-gapped installation instructions to set up a private container image [registry](../../../../getting-started/installation-and-upgrade/other-installation-methods/air-gapped-helm-cli-install/air-gapped-helm-cli-install.md) on the VPC where the cluster is going to be, allowing the cluster nodes to access and download the images they need to run the cluster agent. If the control plane endpoint is also private, Rancher will need [direct access](#direct-access) to it. + +## Private Control Plane Endpoint + +If the cluster has a public endpoint exposed, Rancher will be able to reach the cluster, and no additional steps need to be taken. However, if the cluster has no public endpoint, then considerations must be made to ensure Rancher can access the cluster. + +### Cloud NAT + +:::caution + +Cloud NAT will [incur charges](https://cloud.google.com/nat/pricing). + +::: + +As above, if restricting outgoing internet access to the nodes is not a concern, then Google's [Cloud NAT](https://cloud.google.com/nat/docs/using-nat) service can be used to allow the nodes to access the internet. While the cluster is provisioning, Rancher will provide a registration command to run on the cluster. Download the [kubeconfig](https://cloud.google.com/kubernetes-engine/docs/how-to/cluster-access-for-kubectl) for the new cluster and run the provided kubectl command on the cluster. Gaining access +to the cluster in order to run this command can be done by creating a temporary node or using an existing node in the VPC, or by logging on to or creating an SSH tunnel through one of the cluster nodes. + +### Direct Access + +If the Rancher server is run on the same VPC as the cluster's control plane, it will have direct access to the control plane's private endpoint. The cluster nodes will need to have access to a [private registry](#private-registry) to download images as described above. + +You can also use services from Google such as [Cloud VPN](https://cloud.google.com/network-connectivity/docs/vpn/concepts/overview) or [Cloud Interconnect VLAN](https://cloud.google.com/network-connectivity/docs/interconnect) to facilitate connectivity between your organization's network and your Google VPC. diff --git a/versioned_docs/version-2.14/reference-guides/cluster-configuration/rancher-server-configuration/k3s-cluster-configuration.md b/versioned_docs/version-2.14/reference-guides/cluster-configuration/rancher-server-configuration/k3s-cluster-configuration.md new file mode 100644 index 00000000000..cd185c88983 --- /dev/null +++ b/versioned_docs/version-2.14/reference-guides/cluster-configuration/rancher-server-configuration/k3s-cluster-configuration.md @@ -0,0 +1,551 @@ +--- +title: K3s Cluster Configuration Reference +--- + + + + + +This section covers the configuration options that are available in Rancher for a new or existing K3s Kubernetes cluster. + +## Overview + +You can configure the Kubernetes options one of two ways: + +- [Rancher UI](#configuration-options-in-the-rancher-ui): Use the Rancher UI to select options that are commonly customized when setting up a Kubernetes cluster. +- [Cluster Config File](#cluster-config-file-reference): Instead of using the Rancher UI to choose Kubernetes options for the cluster, advanced users can create a K3s config file. Using a config file lets you set any of the [options](https://rancher.com/docs/k3s/latest/en/installation/install-options/) available during a K3s installation. + +## Editing Clusters in the Rancher UI + +The Rancher UI provides two ways to edit a cluster: +1. With a form. +1. With YAML. + +### Editing Clusters with a Form + +The form covers the most frequently needed options for clusters. + +To edit your cluster, + +1. Click **☰ > Cluster Management**. +1. Go to the cluster you want to configure and click **⋮ > Edit Config**. + +### Editing Clusters in YAML + +For a complete reference of configurable options for K3s clusters in YAML, see the [K3s documentation](https://docs.k3s.io/installation/configuration). + +To edit your cluster with YAML: + +1. Click **☰ > Cluster Management**. +1. Go to the cluster you want to configure and click **⋮ > Edit as YAML**. +1. Edit the RKE options under the `rkeConfig` directive. + +## Configuration Options in the Rancher UI + +### Machine Pool Configuration + +This subsection covers generic machine pool configurations. For specific infrastructure provider configurations, refer to the following: + +- [Azure](../downstream-cluster-configuration/machine-configuration/azure.md) +- [DigitalOcean](../downstream-cluster-configuration/machine-configuration/digitalocean.md) +- [Amazon EC2](../downstream-cluster-configuration/machine-configuration/amazon-ec2.md) +- [Google GCE](../downstream-cluster-configuration/machine-configuration/google-gce.md) + +##### Pool Name + +The name of the machine pool. + +##### Machine Count + +The number of machines in the pool. + +##### Roles + +Option to assign etcd, control plane, and worker roles to nodes. + +#### Advanced + +##### Auto Replace + +The amount of time nodes can be unreachable before they are automatically deleted and replaced. + +##### Drain Before Delete + +Enables draining nodes by evicting all pods before the node is deleted. + +##### Kubernetes Node Labels + +Add [labels](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/) to nodes to help with organization and object selection. + +For details on label syntax requirements, see the [Kubernetes documentation.](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/#syntax-and-character-set) + +##### Taints + +Add [taints](https://kubernetes.io/docs/concepts/configuration/taint-and-toleration/) to nodes, to prevent pods from being scheduled to or executed on the nodes, unless the pods have matching tolerations. + +### Cluster Configuration +#### Basics +##### Kubernetes Version + +The version of Kubernetes installed on your cluster nodes. + +For details on upgrading or rolling back Kubernetes, refer to [this guide](../../../getting-started/installation-and-upgrade/upgrade-and-roll-back-kubernetes.md). + +##### Pod Security Admission Configuration Template + +The default [pod security admission configuration template](../../../how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/psa-config-templates.md) for the cluster. + +##### Encrypt Secrets + +Option to enable or disable secrets encryption. When enabled, secrets will be encrypted using a AES-CBC key. If disabled, any previously secrets will not be readable until encryption is enabled again. Refer to the [K3s documentation](https://rancher.com/docs/k3s/latest/en/advanced/#secrets-encryption-config-experimental) for details. + +##### Project Network Isolation + +If your network provider allows project network isolation, you can choose whether to enable or disable inter-project communication. + +##### SELinux + +Option to enable or disable [SELinux](https://rancher.com/docs/k3s/latest/en/advanced/#selinux-support) support. + +##### CoreDNS + +By default, [CoreDNS](https://coredns.io/) is installed as the default DNS provider. If CoreDNS is not installed, an alternate DNS provider must be installed yourself. Refer to the [K3s documentation](https://rancher.com/docs/k3s/latest/en/networking/#coredns) for details. + +##### Klipper Service LB + +Option to enable or disable the [Klipper](https://github.com/rancher/klipper-lb) service load balancer. Refer to the [K3s documentation](https://rancher.com/docs/k3s/latest/en/networking/#service-load-balancer) for details. + +##### Traefik Ingress + +Option to enable or disable the [Traefik](https://traefik.io/) HTTP reverse proxy and load balancer. For more details and configuration options, see the [K3s documentation](https://rancher.com/docs/k3s/latest/en/networking/#traefik-ingress-controller). + +##### Local Storage + +Option to enable or disable [local storage](https://rancher.com/docs/k3s/latest/en/storage/) on the node(s). + +##### Metrics Server + +Option to enable or disable the [metrics server](https://github.com/kubernetes-incubator/metrics-server). If enabled, ensure port 10250 is opened for inbound TCP traffic. + +#### Add-On Config + +Additional Kubernetes manifests, managed as a [Add-on](https://kubernetes.io/docs/concepts/cluster-administration/addons/), to apply to the cluster on startup. Refer to the [K3s documentation](https://rancher.com/docs/k3s/latest/en/helm/#automatically-deploying-manifests-and-helm-charts) for details. + +#### Agent Environment Vars + +Option to set environment variables for [K3s agents](https://rancher.com/docs/k3s/latest/en/architecture/). The environment variables can be set using key value pairs. Refer to the [K3 documentation](https://rancher.com/docs/k3s/latest/en/installation/install-options/agent-config/) for more details. + +#### etcd + +##### Automatic Snapshots + +Option to enable or disable recurring etcd snapshots. If enabled, users have the option to configure the frequency of snapshots. For details, refer to the [K3s documentation](https://docs.k3s.io/cli/etcd-snapshot#creating-snapshots). + +##### Metrics + +Option to choose whether to expose etcd metrics to the public or only within the cluster. + +#### Networking + +##### Cluster CIDR + +IPv4/IPv6 network CIDRs to use for pod IPs (default: `10.42.0.0/16`). + +Example values: + +- IPv4-only: `10.42.0.0/16` +- IPv6-only: `2001:cafe:42::/56` +- Dual-stack: `10.42.0.0/16,2001:cafe:42::/56` + +For additional requirements and limitations related to dual-stack or IPv6-only networking, see the following resources: + +- [K3s documentation: Dual-stack (IPv4 + IPv6) Networking](https://docs.k3s.io/networking/basic-network-options#dual-stack-ipv4--ipv6-networking) +- [K3s documentation: Single-stack IPv6 Networking](https://docs.k3s.io/networking/basic-network-options#single-stack-ipv6-networking) + +:::caution + +You must configure the Service CIDR when you first create the cluster. You cannot enable the Service CIDR on an existing cluster after it starts. + +::: + +##### Service CIDR + +IPv4/IPv6 network CIDRs to use for service IPs (default: `10.43.0.0/16`). + +Example values: + +- IPv4-only: `10.43.0.0/16` +- IPv6-only: `2001:cafe:43::/112` +- Dual-stack: `10.43.0.0/16,2001:cafe:43::/112` + +For additional requirements and limitations related to dual-stack or IPv6-only networking, see the following resources: + +- [K3s documentation: Dual-stack (IPv4 + IPv6) Networking](https://docs.k3s.io/networking/basic-network-options#dual-stack-ipv4--ipv6-networking) +- [K3s documentation: Single-stack IPv6 Networking](https://docs.k3s.io/networking/basic-network-options#single-stack-ipv6-networking) + +:::caution + +You must configure the Service CIDR when you first create the cluster. You cannot enable the Service CIDR on an existing cluster after it starts. + +::: + +##### Cluster DNS + +IPv4 Cluster IP for coredns service. Should be in your service-cidr range (default: `10.43.0.10`). + +##### Cluster Domain + +Select the domain for the cluster. The default is `cluster.local`. + +##### NodePort Service Port Range + +Option to change the range of ports that can be used for [NodePort services](https://kubernetes.io/docs/concepts/services-networking/service/#nodeport). The default is `30000-32767`. + +##### Truncate Hostnames + +Option to truncate hostnames to 15 characters or fewer. You can only set this field during the initial creation of the cluster. You can't enable or disable the 15-character limit after cluster creation. + +This setting only affects machine-provisioned clusters. Since custom clusters set hostnames during their own node creation process, which occurs outside of Rancher, this field doesn't restrict custom cluster hostname length. + +Truncating hostnames in a cluster improves compatibility with Windows-based systems. Although Kubernetes allows hostnames up to 63 characters in length, systems that use NetBIOS restrict hostnames to 15 characters or fewer. + +##### TLS Alternate Names + +Add hostnames or IPv4/IPv6 addresses as Subject Alternative Names on the server TLS cert. + +##### Authorized Cluster Endpoint + +Authorized Cluster Endpoint can be used to directly access the Kubernetes API server, without requiring communication through Rancher. + +For more detail on how an authorized cluster endpoint works and why it is used, refer to the [architecture section.](../../../reference-guides/rancher-manager-architecture/communicating-with-downstream-user-clusters.md#4-authorized-cluster-endpoint) + +We recommend using a load balancer with the authorized cluster endpoint. For details, refer to the [recommended architecture section.](../../rancher-manager-architecture/architecture-recommendations.md#architecture-for-an-authorized-cluster-endpoint-ace) + +##### Stack Preference + +Choose the networking stack for the cluster. This option affects: + +- The address used for health and readiness probes of components such as Calico, etcd, kube-apiserver, kube-scheduler, kube-controller-manager, and kubelet. +- The server URL in the `authentication-token-webhook-config-file` for the Authorized Cluster Endpoint. +- The `advertise-client-urls` setting for etcd during snapshot restoration. + +Options are `ipv4`, `ipv6`, `dual`: + +- When set to `ipv4`, the cluster uses `127.0.0.1` +- When set to `ipv6`, the cluster uses `[::1]` +- When set to `dual`, the cluster uses `localhost` + +The stack preference must match the cluster’s networking configuration: + +- Set to `ipv4` for IPv4-only clusters +- Set to `ipv6` for IPv6-only clusters +- Set to `dual` for dual-stack clusters + +:::caution + +Ensuring the loopback address configuration is correct is critical for successful cluster provisioning. +For more information, refer to the [Node Requirements](../../../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/node-requirements-for-rancher-managed-clusters.md) page. + +::: + +#### Registries + +Select the image repository to pull Rancher images from. For more details and configuration options, see the [K3s documentation](https://rancher.com/docs/k3s/latest/en/installation/private-registry/). + +#### Upgrade Strategy + +##### Control Plane Concurrency + +Select how many nodes can be upgraded at the same time. Can be a fixed number or percentage. + +##### Worker Concurrency + +Select how many nodes can be upgraded at the same time. Can be a fixed number or percentage. + +##### Drain Nodes (Control Plane) + +Option to remove all pods from the node prior to upgrading. + +##### Drain Nodes (Worker Nodes) + +Option to remove all pods from the node prior to upgrading. + +#### Advanced + +Option to set kubelet options for different nodes. For available options, refer to the [Kubernetes documentation](https://kubernetes.io/docs/reference/command-line-tools-reference/kubelet/). + +## Cluster Config File Reference + +Editing clusters in YAML allows you to set configurations that are already listed in [Configuration Options in the Rancher UI](#configuration-options-in-the-rancher-ui), as well as set Rancher-specific parameters. + +
+ + Example Cluster Config File Snippet + + +```yaml +apiVersion: provisioning.cattle.io/v1 +kind: Cluster +spec: + cloudCredentialSecretName: cattle-global-data:cc-fllv6 + clusterAgentDeploymentCustomization: {} + fleetAgentDeploymentCustomization: {} + kubernetesVersion: v1.26.7+k3s1 + localClusterAuthEndpoint: {} + rkeConfig: + additionalManifest: "" + chartValues: {} + etcd: + snapshotRetention: 5 + snapshotScheduleCron: 0 */5 * * * + machineGlobalConfig: + disable-apiserver: false + disable-cloud-controller: false + disable-controller-manager: false + disable-etcd: false + disable-kube-proxy: false + disable-network-policy: false + disable-scheduler: false + etcd-expose-metrics: false + kube-apiserver-arg: + - audit-policy-file=/etc/rancher/k3s/user-audit-policy.yaml + - audit-log-path=/etc/rancher/k3s/user-audit.logs + profile: null + secrets-encryption: false + machinePools: + - controlPlaneRole: true + etcdRole: true + machineConfigRef: + kind: Amazonec2Config + name: nc-test-pool1-pwl5h + name: pool1 + quantity: 1 + unhealthyNodeTimeout: 0s + workerRole: true + machineSelectorConfig: + - config: + docker: false + protect-kernel-defaults: false + selinux: false + machineSelectorFiles: + - fileSources: + - configMap: + name: '' + secret: + name: audit-policy + items: + - key: audit-policy + path: /etc/rancher/k3s/user-audit-policy.yaml + machineLabelSelector: + matchLabels: + rke.cattle.io/control-plane-role: 'true' + registries: {} + upgradeStrategy: + controlPlaneConcurrency: '1' + controlPlaneDrainOptions: + deleteEmptyDirData: true + disableEviction: false + enabled: false + force: false + gracePeriod: -1 + ignoreDaemonSets: true + ignoreErrors: false + postDrainHooks: null + preDrainHooks: null + skipWaitForDeleteTimeoutSeconds: 0 + timeout: 120 + workerConcurrency: '1' + workerDrainOptions: + deleteEmptyDirData: true + disableEviction: false + enabled: false + force: false + gracePeriod: -1 + ignoreDaemonSets: true + ignoreErrors: false + postDrainHooks: null + preDrainHooks: null + skipWaitForDeleteTimeoutSeconds: 0 + timeout: 120 +``` +
+ +### additionalManifest + +Specify additional manifests to deliver to the control plane nodes. + +The value is a String, and will be placed at the path `/var/lib/rancher/k3s/server/manifests/rancher/addons.yaml` on target nodes. + +Example: + +```yaml +additionalManifest: |- + apiVersion: v1 + kind: Namespace + metadata: + name: name-xxxx +``` + + +:::note + +If you want to customize system charts, you should use the `chartValues` field as described below. + +Alternatives, such as using a HelmChartConfig to customize the system charts via `additionalManifest`, can cause unexpected behavior, due to having multiple HelmChartConfigs for the same chart. + +::: + +### chartValues + +Specify the values for the system charts installed by K3s. + +For more information about how K3s manges packaged components, please refer to [K3s documentation](https://docs.k3s.io/installation/packaged-components). + +Example: + +```yaml +chartValues: + chart-name: + key: value +``` + +### machineGlobalConfig + +Specify K3s configurations. Any configuration change made here will apply to every node. The configuration options available in the [standalone version of k3s](https://docs.k3s.io/cli/server) can be applied here. + +Example: + +```yaml +machineGlobalConfig: + etcd-arg: + - key1=value1 + - key2=value2 +``` + +To make it easier to put files on nodes beforehand, Rancher expects the following values to be included in the configuration, while K3s expects the values to be entered as file paths: +- private-registry +- flannel-conf + +Rancher delivers the files to the path `/var/lib/rancher/k3s/etc/config-files/