本文档采用自动化机器翻译技术翻译。 尽管我们力求提供准确的译文，但不对翻译内容的完整性、准确性或可靠性作出任何保证。 若出现任何内容不一致情况，请以原始 英文 版本为准，且原始英文版本为权威文本。

已知问题

已知问题会定期更新，旨在告知您可能在下一个即将发布的版本中未能立即解决的任何问题。要获取最新信息，请查看 K3s 项目问题跟踪器 上的开放和固定问题。如果您没有运行最新版本的 K3s，请确保还搜索已关闭的问题和发布说明，以确保您的问题尚未解决。

Kine/SQL 2147483647（最大整数）修订限制

当使用 K3s 与在 2024 年 5 月之前的 K3s 版本上创建的 外部 SQL 数据库 时，您必须对数据库应用模式迁移，以允许在数据库中存储超过 210 万个修订。当当前数据存储修订达到 2147483647 时，未更新模式的数据库将变为只读。

您可以通过检查对 Kubernetes API 发出的列表调用的响应中的 resourceVersion 字段来查看当前数据存储的修订。 例如，在以下输出中，当前修订为 12345：

$ kubectl get --raw /api/v1/namespaces?labelSelector=none
{"kind":"NamespaceList","apiVersion":"v1","metadata":{"resourceVersion":"12345"},"items":[]}

Docker Snap

如果您计划将 K3s 与 Docker 容器运行时一起使用，不建议使用 Docker snap 包，因为已知会导致运行 K3s 时出现问题。使用您的操作系统提供的本地软件包管理系统安装 Docker。

Iptables

如果您的节点在 nftables 模式下使用 iptables v1.6.1 或更早版本，您可能会遇到问题。我们建议使用更新的 iptables（如 1.6.1+），或运行 iptables 传统模式，以避免问题。

update-alternatives --set iptables /usr/sbin/iptables-legacy
update-alternatives --set ip6tables /usr/sbin/ip6tables-legacy

Iptables 版本 1.8.0-1.8.4 也存在已知问题，可能导致 K3s 失败。一些流行的 Linux 发行套件默认包含这些版本。一个错误导致重复规则的积累，这会对节点的性能和稳定性产生负面影响。有关如何确定您是否受到此问题影响的信息，请参见 问题 #3117。

K3s 包含一个已知良好的 iptables 版本（v1.8.8），经过测试可以正常工作。您可以通过使用 --prefer-bundled-bin 选项启动 K3s，或者通过从操作系统中卸载 iptables/nftables 软件包来告诉 K3s 使用其捆绑版本的 iptables。

版本门

从 2022-12 版本（v1.26.0+k3s1、v1.25.5+k3s1、v1.24.9+k3s1、v1.23.15+k3s1）开始，--prefer-bundled-bin 标志可用。

无根模式

以无根模式运行 K3s 是实验性的，并且存在几个 已知问题。

将安全强化集群从 v1.24.x 升级到 v1.25.x

Kubernetes 在 v1.25 中移除了 PodSecurityPolicy，以支持 Pod 安全标准。您可以在 上游文档 中阅读更多关于 PSS 的信息。对于 K3S，如果节点上配置了任何 PodSecurityPolicy，则必须采取一些手动步骤。

  1. 在所有节点上，更新 kube-apiserver-arg 值以移除 PodSecurityPolicy admission-plugin。请改为添加以下 arg 值：'admission-control-config-file=/var/lib/rancher/k3s/server/psa.yaml'，但请不要立即重启或升级 K3S。以下是此更新后用于节点安全强化的配置文件示例：

    protect-kernel-defaults: true
secrets-encryption: true
kube-apiserver-arg:
  - 'admission-control-config-file=/var/lib/rancher/k3s/server/psa.yaml'
  - 'audit-log-path=/var/lib/rancher/k3s/server/logs/audit.log'
  - 'audit-policy-file=/var/lib/rancher/k3s/server/audit.yaml'
  - 'audit-log-maxage=30'
  - 'audit-log-maxbackup=10'
  - 'audit-log-maxsize=100'
kube-controller-manager-arg:
  - 'terminated-pod-gc-threshold=10'
  - 'use-service-account-credentials=true'
kubelet-arg:
  - 'streaming-connection-idle-timeout=5m'

  2. 创建包含以下内容的 /var/lib/rancher/k3s/server/psa.yaml 文件。您可能还想要豁免更多命名空间。以下示例豁免了 kube-system（必需）、cis-operator-system（可选，但在通过 Rancher 进行安全扫描时很有用）和 system-upgrade（如果进行 自动升级 则必需）。

    apiVersion: apiserver.config.k8s.io/v1
kind: AdmissionConfiguration
plugins:
- name: PodSecurity
  configuration:
 apiVersion: pod-security.admission.config.k8s.io/v1beta1
 kind: PodSecurityConfiguration
 defaults:
   enforce: "restricted"
   enforce-version: "latest"
   audit: "restricted"
   audit-version: "latest"
   warn: "restricted"
   warn-version: "latest"
 exemptions:
   usernames: []
   runtimeClasses: []
   namespaces: [kube-system, cis-operator-system, system-upgrade]

  3. 正常进行升级。如果进行 自动升级，请确保运行 system-upgrade-controller pod 的命名空间已设置为特权，以符合 Pod 安全级别：

    apiVersion: v1
kind: Namespace
metadata:
  name: system-upgrade
  labels:
 # This value must be privileged for the controller to run successfully.
 pod-security.kubernetes.io/enforce: privileged
 pod-security.kubernetes.io/enforce-version: v1.25
 # We are setting these to our _desired_ `enforce` level, but note that these below values can be any of the available options.
 pod-security.kubernetes.io/audit: privileged
 pod-security.kubernetes.io/audit-version: v1.25
 pod-security.kubernetes.io/warn: privileged
 pod-security.kubernetes.io/warn-version: v1.25

  4. 升级完成后，移除集群中任何剩余的 PSP 资源。在许多情况下，可能会在 /var/lib/rancher/k3s/server/manifests/ 中用于安全强化的自定义文件中存在 PodSecurityPolicies 和相关的 RBAC 资源。移除这些资源，k3s 将自动更新。有时，由于时机的原因，这些可能会留在集群中，在这种情况下，您需要手动删除它们。如果之前遵循了硬化指南，您应该能够通过以下方式删除它们：

# Get the resources associated with PSPs
$ kubectl get roles,clusterroles,rolebindings,clusterrolebindings -A | grep -i psp

# Delete those resources:
$ kubectl delete clusterrole.rbac.authorization.k8s.io/psp:restricted-psp clusterrole.rbac.authorization.k8s.io/psp:svclb-psp clusterrole.rbac.authorization.k8s.io/psp:system-unrestricted-psp clusterrolebinding.rbac.authorization.k8s.io/default:restricted-psp clusterrolebinding.rbac.authorization.k8s.io/system-unrestricted-node-psp-rolebinding && kubectl delete -n kube-system rolebinding.rbac.authorization.k8s.io/svclb-psp-rolebinding rolebinding.rbac.authorization.k8s.io/system-unrestricted-svc-acct-psp-rolebinding