Kubernetes

Kubernetes 是一种用于部署、伸缩和管理容器化应用的容器编排引擎。为 PyCharm 安装并启用 Kubernetes 插件，以添加以下用于管理您的 Kubernetes 集群的功能：

为 Kubernetes 资源配置文件提供编码辅助。
为 Helm chart 和模板提供编码辅助。更多详情请参阅专用 Helm 页面。
使用自定义资源定义（CRD）规范对自定义资源进行验证。
为 Kustomize 文件提供编码辅助：字段与本地文件路径补全、快速文档，以及在 Kustomize 文件与补丁之间导航。相关 Kustomize 文件列表会显示在编辑器中已打开的 Kustomize 补丁顶部。
在 PyCharm 中与集群交互：使用服务工具窗口查看 Kubernetes 集群的所有资源、跳转到相关资源定义、查看在 Pod 上运行的容器的日志等。

Kubernetes 插件支持 Kubernetes 版本 1.26 到 1.34（您可以选择适用的版本）。

安装 Kubernetes 插件

此功能依赖于 Kubernetes 插件，您需要安装并启用该插件。

按 Ctrl+Alt+S 打开设置，然后选择插件。
打开 Marketplace 选项卡，找到 Kubernetes 插件，并点击安装（如有提示，请重启 IDE）。

指定 kubectl 的自定义路径

PyCharm 使用由 PATH 环境变量确定的默认 kubectl（以及如果您使用它，则为 helm ）可执行文件。

如果您将 kubectl 安装在自定义目录中，则可以手动指定其路径。

在设置对话框（Ctrl+Alt+S ）中，选择构建、执行、部署 | Kubernetes。
在 kubectl 可执行文件路径字段中，指定 kubectl 可执行文件的路径。
点击测试以检查文件位置。如果未找到，您可以手动检查文件位置，或点击安装，PyCharm 将下载并安装缺失的软件。

使用自定义 Kubernetes 配置文件

有关集群的信息存储在 kubeconfig 文件中。 PyCharm 会检测默认的 kubeconfig 文件，通常位于 $HOME/.kube/config （该位置可通过 KUBECONFIG 环境变量更改）。如果您希望 PyCharm 不仅从默认文件，还从自定义 kubeconfig 文件获取有关集群的信息，您可以在 IDE 设置中指定这些文件。您可以全局应用，或为每个项目使用不同的文件。

在设置对话框（Ctrl+Alt+S ）中，选择构建、执行、部署 | Kubernetes。
在配置下，点击并指定一个 kubeconfig 文件的路径。
如果您希望在所有项目中使用该配置文件，请在范围列中选择全局。若仅在当前项目中使用，请保持项目作用域。

添加文件后，PyCharm 会验证其语法，并报告任何错误。

配置 Kubernetes API 版本

PyCharm 为配置键值提供补全，通过装订线图标导航到相关选择器与定义，提供检查已弃用值和必需键的专用检查等辅助功能。这些取决于您使用的 API 版本。 Kubernetes 插件支持 Kubernetes 版本 1.26 到 1.34。默认情况下，PyCharm 将其设置为最新版本。但是，如果您的资源使用较早版本，您可以进行更改。

在设置对话框（Ctrl+Alt+S ）中，选择语言与框架 | Kubernetes。
根据需要更改 Kubernetes API 版本和 Kustomize 版本选项。

资源配置文件

Kubernetes 插件为 YAML 格式的资源配置文件提供了丰富的支持，而对 JSON 格式仅提供基础支持。

支持的功能

功能	YAML	JSON
自动补全	支持	支持
快速文档	支持	支持
检查与快速修复	无效、缺失和重复的键不可编辑（只读）的键和资源已弃用的键和资源无效的整数和枚举键值	无效、缺失和重复的属性
实时模板	常见资源类型的预定义模板	无预定义实时模板
智能补全	支持	不支持
自定义资源定义	支持	不支持
标签定义与选择器	使用装订线图标导航、查找用法和重命名	不支持
对原始 Kubernetes 模型的增强	在适用的位置使用枚举而非普通字符串	无

PyCharm 通过以下必填字段识别 Kubernetes 资源配置文件：

apiVersion ：标识对象表示的版本化架构
kind ：标识资源类型（例如， Service、 Pod、 Deployment 等）

如果 YAML 或 JSON 文件同时包含上述两个字段，PyCharm 将使用相应的 Kubernetes 图标标记该文件，并启用所有可用功能。

创建资源文件

使用 PyCharm，您可以为 Kubernetes 中最常用的一些资源快速创建配置文件。

在项目工具窗口 Alt+1 中，右键点击文件夹，选择新建或按 Alt+Insert ，然后选择 Kubernetes 资源。
在名称字段中，输入资源名称，并从列表中选择文件模板。
这将根据所选的文件模板创建一个新文件及其内容。

或者，在 YAML 文件中，您可以使用预定义的实时模板，例如：

kconfigmap ：Kubernetes ConfigMap
kcronjob ：Kubernetes CronJob
kdeployment ：Kubernetes Deployment
kingress ：Kubernetes Ingress
kpod ：Kubernetes Pod
kresource ：Kubernetes Resource from Scratch
kservice ：Kubernetes Service

在编辑器中打开 Kubernetes 资源文件时，PyCharm 会显示内联提示和包含最常用操作的浮动工具栏，其中包括：

在浮动工具栏中，您可以：
- 选择当前集群和命名空间
- 应用更改并将其提交到当前集群
- 删除资源
- 将更改与集群版本进行比较
- 从集群重新加载内容
用于检查已部署资源的状态的内联提示
用于显示并复制引用的 Secret 值的内联提示
用于转发端口的内联提示

您可以配置在编辑器中显示浮动工具栏的时机。

按 Ctrl+Alt+S 打开设置，然后选择构建、执行、部署 | Kubernetes。
使用在编辑器中显示浮动工具栏选项选择浮动工具栏的显示时机：
- 始终显示
- 鼠标移动时显示
- 不显示
或者，您可以右键点击浮动工具栏并选择所需选项。

禁用 Kubernetes 架构验证

PyCharm 会根据 Kubernetes API 架构验证您的 Kubernetes 文件。这包括检查必需的键以及资源的可能类型。

如果您的文件包含 apiVersion 和 kind ，但它不是 Kubernetes 文件，您可以禁用此类验证。您可以在设置 | 编辑器 | 检查 | Kubernetes 中抑制检查，并更改其作用域和严重性。或者，您可以使用特殊指令标记文件，以在其中禁用验证：

在文件开头添加 # nonk8s。
或者，如果您已经看到关于未知资源的警告，请在问题工具窗口中右键点击它并选择显示快速修复 | 将此文件标记为非 Kubernetes。

管理您的集群

使用服务工具窗口查看您的集群、在命名空间之间切换并修改集群资源。

添加集群

要与 Kubernetes 集群交互，请在服务工具窗口中添加集群。

打开服务工具窗口：选择视图(V) | 工具窗口(T) | 服务或按 Alt+8。
在服务工具窗口中右键点击一个 Kubernetes 节点，并选择添加集群。或者，点击并选择 Kubernetes | 添加集群。
接下来，选择要添加的 Kubernetes 集群的来源：
- 来自默认目录：从默认位置获取集群（通常为 $HOME/.kube/config）。
- 来自自定义 kubeconfig ：从您的计算机中选择任意 kubeconfig 文件。
- 粘贴 kubeconfig 内容：将 kubeconfig 内容粘贴到打开的文本区域中。
在打开的添加集群窗口中，选择要添加的集群并点击添加集群。

添加的 Kubernetes 集群将在服务工具窗口中可用。您可以通过右键点击某个集群并选择在新标签页中打开，在单独的选项卡中打开每个集群。

要实时监控集群资源，您可以连接到集群。

连接到集群

连接到集群，以便在 IDE 中与其交互：跟随日志、预览资源、查看其配置文件，并在资源被修改时获取实时更新。无需连接到集群，您也可以在编辑器中修改其资源。

打开服务工具窗口：选择视图(V) | 工具窗口(T) | 服务或按 Alt+8。
如果服务工具窗口中没有集群，请添加集群。
右键点击某个集群并选择连接集群。

编辑 kubeconfig

kubeconfig 文件包含有关集群、用户、命名空间和身份验证的信息。

打开服务工具窗口：选择视图(V) | 工具窗口(T) | 服务或按 Alt+8。
选择一个集群，并在工具栏上点击（在编辑器中打开kubeconfig 文件）。在服务工具窗口中右键点击任何 Kubernetes 对象时，也可使用此操作。
这将在编辑器的新选项卡中打开 kubeconfig 文件。要更改此操作打开的默认文件，您可以在 kubeconfig 文件路径中指定另一个文件的路径。

当您更改 kubeconfig 文件时，配置会自动重新加载。您还可以通过右键点击某个集群或任何 Kubernetes 对象并选择更多(M) | 自动重新加载配置，手动重新加载或禁用自动重新加载。

在命名空间之间切换

Kubernetes 命名空间可让您在集群内对资源进行逻辑隔离。借助 PyCharm，您可以快速在命名空间之间切换。

打开服务工具窗口：选择视图(V) | 工具窗口(T) | 服务或按 Alt+8。
右键点击您的集群或任何资源，选择命名空间（或在工具栏上点击），然后选择所需的命名空间。
要查看所有命名空间的资源，请选择所有命名空间。

选择当前集群

当前集群是指在编辑器和项目工具窗口中与资源交互时设置为默认的集群。

当您在本地修改或创建资源文件时，您可以通过点击或使用浮动工具栏来选择要将资源应用到的集群。您也可以提前进行选择。

打开服务工具窗口：选择视图(V) | 工具窗口(T) | 服务或按 Alt+8。
右键点击某个集群并选择将集群设置为当前。
或者，选择一个集群并在工具栏上点击。

该设置也可在 IDE 设置的语言与框架 | Kubernetes 下找到。

在集群中创建资源

在创建资源文件后，您可以在集群中创建相应的资源。

在编辑器中打开所需的资源文件。如果未设置当前集群，请使用浮动工具栏进行选择。
如有需要，您还可以从列表中选择命名空间。
点击将更改应用到当前集群和命名空间。

修改集群资源

打开服务工具窗口：选择视图(V) | 工具窗口(T) | 服务或按 Alt+8。
右键点击某个资源并选择查看YAML。
这将在编辑器的新选项卡中打开所选资源的清单。当您更改字段时，修改的行会在装订线中高亮显示。您可以点击装订线中的高亮区域，快速预览或回滚更改。
请确保在浮动工具栏上已选择当前集群，并点击以应用更改。
更改某些 Kubernetes 对象字段可能会导致创建新对象。例如，如果您更改资源名称，应用此更改将创建一个新资源。或者，如果您更改命名空间，应用此更改将在指定的命名空间中创建一个新资源。

查看资源详细信息

PyCharm 允许您无需手动运行任何命令即可快速查看 Kubernetes 资源的详细信息。

在服务工具窗口中，选择一个资源以查看其详细信息。
PyCharm 会在编辑器中直接显示已部署的 Kubernetes 资源的实时状态。例如，当您打开 Deployment 清单时，状态指示器会显示在 replicas 字段旁，显示当前有多少 Pod 处于运行、挂起或失败状态。
您可以在相应清单中的名称字段旁检查各个 Pod 和 Job 的状态。
如果发生错误且某个资源失败，PyCharm 会显示打开日志链接，帮助您快速导航到描述该问题的相关日志条目。

删除资源

您可以通过以下任意方式删除资源：

在服务工具窗口中，右键点击某个资源并选择删除。
在服务工具窗口中，选择某个资源并在工具栏上点击（删除资源）。
如果资源 YAML 文件已在编辑器中打开，请在浮动工具栏上选择当前集群并点击。
如果资源 YAML 文件已打开，且浮动工具栏上未选择任何集群，请在编辑器中任意位置右键点击并选择删除(当前集群未配置) ；如果已选择集群，则选择从集群 "cluster_name" 与命名空间 "namespace_name" 中删除。

端口转发

借助 Kubernetes 中的端口转发，您可以将计算机上的本地端口流量重定向到 Kubernetes Pod 上的端口。 PyCharm 允许您管理端口转发：您可以将一个或多个本地端口转发到远程端口，查看集群中所有活动的转发会话（在 PyCharm 中建立），停止并重新启动转发会话。

您可以通过以下任一方式配置端口转发：
- 打开服务工具窗口：选择视图(V) | 工具窗口(T) | 服务或按 Alt+8。右键点击目标 Pod 并选择转发端口。
- 在 Kubernetes 清单中点击端口转发内联提示。如果指定了目标端口（例如作为 containerPort 的值），PyCharm 会显示该内联提示。
在转发端口对话框中：
- 在地址字段中，列出要监听的地址。使用逗号分隔多个值。
- 在端口字段中，以 <local port>:<remote port> 格式指定端口。例如， 8888:5000 表示监听本地端口 8888 ，并将数据转发到/从远程端口 5000。
  PyCharm 会根据相应 Kubernetes 清单中定义的值自动建议端口映射。如果清单指定了您本地计算机上已在使用的端口，PyCharm 会逐步增加建议值，直到找到可用端口。
  如果指定的值小于 1024 ，则会在建议的本地端口值上加 8000。
  如果您手动指定了当前正被占用的本地端口，PyCharm 会在开始转发之前通知您。
点击转发。

管理端口转发会话

要查看所有活动的端口转发会话，请在服务工具窗口中，展开 Kubernetes 集群下的网络 | 端口转发。
在每个端口转发会话旁，PyCharm 会显示一个徽章，表示其当前状态。
要终止端口转发会话，右键点击该会话并选择停止端口转发，或在工具栏上点击。
要重新启动端口转发会话，右键点击该会话并选择重新启动端口转发，或在工具栏上点击。

创建 Secret

借助 PyCharm，您可以快速创建 Kubernetes Secrets。

打开服务工具窗口：选择视图(V) | 工具窗口(T) | 服务或按 Alt+8。
选择一个集群并展开配置。
右键点击 Secret 节点并选择创建新密钥。或者，选择 Secret 节点并在工具栏上点击。
在打开的创建新密钥窗口中，指定 Secret 名称、类型和命名空间。为加快 Secret 的创建，PyCharm 会根据所选的 Secret 类型添加必需的数据或注解键。
在数据和注解部分，点击值并为现有键输入值，或者您可以点击并选择提供值的方式：
- 手动添加以手动输入值。
- 使用文件数据以选择文件（例如， SSH 密钥文件或 Docker config.json ），将文件内容用作该值。

您可以在服务工具窗口中，在配置下查看所有 Secret。要编辑 Secret，请右键点击它并选择编辑 Secret ，或在工具栏上点击。

创建 Secret 后，您可以在 Pod 配置文件的 secretName 字段中开始输入其名称。这将触发对集群或项目中可用的 Secret 名称的补全。

在处理引用 Secret 的 YAML 文件时，PyCharm 提供内联提示，包含可帮助您快速检查或复用 Secret 值的操作。

显示：在弹出窗口中显示引用的 Secret 的解码值。
复制：将解码后的 Secret 值复制到您的剪贴板以供临时使用。

这两项操作访问并显示 Secret 中定义的真实值，而不是 YAML 中的编码值或占位符文本。

如果您的帐户权限不足，点击该按钮会显示相应的工具提示。这可防止受限数据意外泄露。

保持您的集群信息为最新

要使 PyCharm 与您的集群保持同步，请使用以下操作：

重新加载配置以获取 kubeconfig 文件中的最新更改。
刷新资源以获取 Kubernetes 资源中的最新更改。这通常会自动完成，前提是您具有必要的权限。

重新加载配置

默认情况下，配置会在您更改 kubeconfig 文件时自动重新加载。您仍然可以手动重新加载。

打开服务工具窗口：选择视图(V) | 工具窗口(T) | 服务或按 Alt+8。
右键点击某个集群并选择更多 | 重新加载配置。

如果您想要禁用自动重新加载，请清除自动重新加载配置选项。

您也可以在 IDE 设置（Ctrl+Alt+S ）的构建、执行、部署 | Kubernetes | 自动重新加载配置中检查此设置。

手动刷新集群资源

如果您已连接到集群，您对其资源所做的任何更改都会在 IDE 中自动反映出来。如果您的资源未自动更新（由于您的集群角色缺少权限），将在服务工具窗口中显示自动刷新被禁止的消息。在这种情况下，您可以手动刷新资源。

打开服务工具窗口：选择视图(V) | 工具窗口(T) | 服务或按 Alt+8。
右键点击一组资源并选择刷新，或点击 Ctrl+F5。

查看日志

借助 PyCharm，您可以查看集群日志和来自所选资源的日志。您可以按日期、来源以及日志消息中的特定值对其进行筛选。

在编辑器中打开资源日志

打开服务工具窗口：选择视图(V) | 工具窗口(T) | 服务或按 Alt+8。
通过以下任一方式选择日志来源：
- 要查看所有资源的日志，请选择您的 Kubernetes 集群，并在服务工具窗口的工具栏上点击（关注日志）。
- 要查看某个资源的日志，请选择该资源，并在服务工具窗口的工具栏上点击（关注日志）。或者，右键点击某个资源并选择关注日志。
  如果 Pod 中存在多个容器，请在显示的容器列表中选择您要跟随其日志的容器。

这将使用 --follow=true 标志实时跟随所选资源的日志，并在编辑器的新选项卡中打开它们。

管理日志

当查看集群日志或所选资源的日志时，您可以使用主工具栏 (1) 或浮动工具栏 (2) 来处理日志输出。浮动工具栏提供对常用操作的快速访问。

(滚动到末尾 )：跳至日志输出末尾。
(自动换行 )：当调整编辑器大小时，为日志条目启用软换行。
(下载筛选后的日志 )：下载当前在编辑器中打开的日志，并考虑任何已应用的筛选器。
(清除显示的日志 )：清除在编辑器中显示的日志条目。此操作仅影响当前视图。当您为同一资源重新打开日志时，这些条目会重新出现。

筛选日志

在打开日志后，您可以使用编辑器顶部的以下筛选器来细化日志列表：

(打开模式匹配 )：输入或选择您希望日志数据匹配的值或模式。例如，如果您的日志包含级别信息，您可以选择 warn、 error 或其他级别值，以仅显示与这些级别相对应的日志。
(选择日志源 )：选择您希望显示其日志的集群资源。
(按日期和时间筛选 )：选择您希望显示日志的时间范围。
(选择日志字段 )：选择是否显示日志时间戳、来源和消息。
您可以配置日志字段的可见性，在 IDE 设置（Ctrl+Alt+S ）的构建、执行、部署 | Kubernetes | 日志 | 默认在日志中显示的字段下。
在输入字段顶部的编辑器选项卡上，输入日志消息中的值。点击以使用正则表达式，点击以使搜索区分大小写。

(清除所有日志筛选器 )：丢弃所有已应用的筛选器（来源除外），并显示所有日志。

下载单个容器的日志

打开服务工具窗口：选择视图(V) | 工具窗口(T) | 服务或按 Alt+8。
选择一个资源，并在右侧工具栏上点击（下载日志）以保存日志文件。

配置日志保存选项

您可以在 IDE 设置（Ctrl+Alt+S ）的构建、执行、部署 | Kubernetes | 日志下配置日志保存选项：

如果您想要保存日志的位置不是 Scratches ，请在下载日志的路径中指定目录。或者，选择下载前询问日志的保存位置以在每次保存日志时提示您选择位置。
如果您想要在文件名中包含日志时间戳，请选择将时间戳附加到日志文件名。

自定义资源定义支持

如果您扩展 Kubernetes 集群以使用自定义资源，PyCharm 可以使用自定义资源定义（CRD）规范对其进行验证。

指定 CRD 规范的路径

按 Ctrl+Alt+S 打开设置，然后选择语言与框架 | Kubernetes。
点击并选择本地 CRD 文件或指定 URL。然后点击确定(O)。

使用和重新排列 CRD 文件列表。这将定义冲突定义的优先级：如果某项在多个文件中都有定义，PyCharm 将使用位于列表最底部的那个。

默认情况下，CRD 仅应用于当前项目。如果您希望某个 CRD 在此 IDE 实例中打开的任何项目中可用，请将作用域：选项更改为 IDE。

要从正在运行的 Kubernetes 集群加载 CRD，请启用使用活动集群中的API 架构(如果可用)。

您可以在服务工具窗口的 Kubernetes 节点下查看当前集群的 CRD，包括其所有已应用的资源。

Kubernetes 插件支持以下类型的 CRD 文件：

YAML 中的 CustomResourceDefinition 文件

以下示例展示了一个简单的 CustomResourceDefinition 规范，适用于类型为 CronTab 的自定义资源 stable.example.com/v1。用于标识资源的必填字段为 metadata.name、 spec.group、 spec.versions 和 spec.names。

                apiVersion: apiextensions.k8s.io/v1beta1
                kind: CustomResourceDefinition
                metadata:
                  name: crontabs.stable.example.com # Obligatory field to identify the resource
                spec:
                  group: stable.example.com # Obligatory field to identify the resource
                  versions: # Obligatory field to identify the resource
                    - name: v1
                      served: true
                      storage: true
                  scope: Namespaced
                  names: # Obligatory field to identify the resource
                    plural: crontabs
                    singular: crontab
                    kind: CronTab
                    shortNames:
                      - ct
                validation:
                  openAPIV3Schema: # Schema for validating custom objects
                    properties:
                      spec:
                        properties:
                          cronSpec:
                            type: string
                            pattern: '^(\d+|\*)(/\d+)?(\s+(\d+|\*)(/\d+)?){4}$' # not supported for validation
                          replicas:
                            type: integer
                            minimum: 1 # not supported for validation
                            maximum: 10 # not supported for validation
            
   

JSON 中的 OpenAPI v2.0 架构

以下示例展示了一个简单的 OpenAPI v2.0 架构，包含一个 CRD 规范，适用于类型为 Config 的自定义资源 sample/v1。自定义资源的根定义必须包含带有指定组、版本和类型的 x-kubernetes-group-version-kind 字段。在示例中， root.Definition 对象使用 build 属性来引用 some.Definition 对象。

                {
                    "swagger": "2.0",
                    "info": {
                        "title": "Sample Schema",
                        "version": "sample/v1"
                    },
                    "paths": {},
                    "definitions": {
                        "some.Definition": {
                            "description": "Example of a definition.",
                            "properties": {
                                "someProperty": {
                                    "type": "string"
                                }
                            }
                        },
                        "root.Definition": {
                            "description": "This is the root definition for the resource",
                            "properties": {
                                "build": {
                                    "$ref": "#/definitions/some.Definition"
                                }
                            },
                            "x-kubernetes-group-version-kind": [
                                {
                                    "group": "sample",
                                    "kind": "Config",
                                    "version": "v1"
                                }
                            ]
                        }
                    }
                }
            
   

CRD 验证限制

PyCharm 不支持以下 OpenAPI v3 架构功能：

multipleOf
maximum
exclusiveMaximum
minimum
exclusiveMinimum
maxLength
minLength
pattern
maxItems
minItems
uniqueItems
maxProperties
minProperties
allOf
oneOf
anyOf
not
format
default
nullable
readOnly
writeOnly
xml
externalDocs
example
deprecated

效率提示

如果您经常使用此处介绍的功能，以下提示可能会对您有所帮助：

分配快捷键

您可以为 Kubernetes 操作分配键盘快捷键。

在设置对话框（Ctrl+Alt+S ）中，选择按键映射。
在搜索字段中输入 kubernetes ，然后双击一个操作以为其设置快捷键。

或者，您可以使用查找操作对话框 Ctrl+Shift+A ，输入所需的操作，然后按 Alt+Enter。

例如，您可以为与集群交互分配一个快捷键，以便在修改资源配置文件时快速打开上下文菜单。

配置代码折叠

默认情况下，PyCharm 使用代码折叠来渲染 Helm 模板中的值引用以及 Kubernetes 配置文件中的定义为实际值。您可以点击该值以展开它，或按 Ctrl+NumPad + 和 Ctrl+NumPad - 切换折叠。如果您希望默认展开引用和定义，请执行以下操作：

在设置对话框（Ctrl+Alt+S ）中，选择编辑器 | 常规 | 代码折叠。
在代码折叠页面上，清除必要的复选框：
- Kubernetes：Helm 模板中的值引用
- Kubernetes：YAML 文件中的 EnvVar 定义
- Kubernetes：YAML 文件中的 ExecAction 定义

最后修改日期： 2025年 12月 2日