Kubernetes

Kubernetes 是一个用于部署、扩展和管理容器化应用程序的容器编排引擎。安装并启用 WebStorm 的 Kubernetes 插件，以添加以下功能来管理您的 Kubernetes 集群：

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

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

安装 Kubernetes 插件

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

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

指定 kubectl 的自定义路径

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

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

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

使用自定义 Kubernetes 配置文件

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

在设置对话框（Ctrl+Alt+S ）中，选择构建、执行、部署｜ Kubernetes。
在配置下，点击并指定到 kubeconfig 文件的路径。
如果您想在所有项目中使用配置文件，请在全局列中选择范围。要仅在当前项目中使用，请保留项目范围。

当您添加文件时，WebStorm 会验证其语法并报告错误（如果有）。

配置 Kubernetes API 版本

WebStorm 提供配置键值的代码补全功能、通过边栏图标导航到相关的选择器和定义、检查过时的值和必需键的专门检查，以及其他辅助功能。这些取决于您正在使用的 API 版本。 Kubernetes 插件支持 Kubernetes 版本 1.26 到 1.34。默认情况下，WebStorm 会将其设置为最新版本。但是，如果您的资源使用的是较早的版本，您可以更改它。

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

资源配置文件

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

支持的功能

功能	YAML	JSON
自动补全	支持	支持
快速文档	支持	支持
检查和快速修复	无效、缺失和重复键不可编辑（只读）键和值不推荐使用的键值和资源无效的整数和枚举键值	无效、缺失和重复的属性
实时模板	预定义的通用资源类型模板	没有预定义的实时模板
智能完成	支持	不支持
自定义资源定义	支持	不支持
标签定义及选择器	使用装订区域图标导航、查找用法和重命名	不支持
原始 Kubernetes 模型的改进	在适用的地方使用枚举而不是普通字符串	无

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

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

如果这两个字段都出现在 YAML 或 JSON 文件中，WebStorm 将使用相应的 Kubernetes 图标标记该文件并启用所有可用功能。

创建资源文件

使用 WebStorm，您可以快速创建 Kubernetes 中一些最最受欢迎的资源的配置文件。

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

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

kconfigmap ：Kubernetes ConfigMap
kcronjob ：Kubernetes 定时任务
kdeployment ：Kubernetes 部署
kingress ：Kubernetes Ingress
kpod ：Kubernetes Pod
kresource ：从零开始的 Kubernetes 资源
kservice ：Kubernetes 服务

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

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

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

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

禁用 Kubernetes 模式验证

WebStorm 根据 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 文件。要更改此操作打开的默认文件，您可以在 Path to kubeconfig file中指定另一个文件的路径。

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

在命名空间之间切换

Kubernetes 命名空间允许您在集群内逻辑隔离资源。借助 WebStorm，您可以快速切换命名空间。

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

选择当前集群

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

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

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

此设置也可以在 IDE 设置中找到，位于语言 & 框架 | Kubernetes 下。

在集群中创建资源

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

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

修改集群资源

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

查看资源详细信息

借助 WebStorm，无需手动运行任何命令，您即可快速查看 Kubernetes 资源的详细信息。

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

删除资源

您可以通过以下任何一种方式删除资源：

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

转发端口

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

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

管理端口转发会话

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

创建 Secret

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

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

您可以在服务工具窗口中查看所有的 Secrets，位于配置下面。要编辑一个 Secret，右键点击它并选择编辑密钥，或者点击工具栏上的。

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

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

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

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

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

请保持您的集群信息为最新

若要使 WebStorm 与您的集群保持同步，请执行以下操作：

重新加载配置以获得 kubeconfig 文件的最新更改。
刷新资源以获取 Kubernetes 资源的最新更改。通常情况下，只要您拥有必要的权限，这些操作会自动完成。

重新加载配置

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

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

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

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

手动刷新集群资源

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

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

查看日志

使用 WebStorm，您可以查看集群日志和选定资源的日志。您可以按日期、来源和日志消息中的特定值筛选日志。

在编辑器中打开资源日志

打开服務工具窗口：选择视图(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 集群，WebStorm 可以通过自定义资源定义 (CRD) 规范对它们进行验证。

指定 CRD 规格路径

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

使用和重新排列 CRD 文件列表。当存在冲突的定义时，此项会定义优先级：WebStorm 将使用最低优先级的定义，如果它在多个文件中定义。

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

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

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

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

YAML 中的 CustomResourceDefinition 文件

以下示例展示了一种简单的 CustomResourceDefinition规范，用于一种自定义资源 stable.example.com/v1 的类型 CronTab。标识资源的必填字段是 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
            
   

OpenAPI v2.0 模式（JSON格式）

以下示例展示了一个简单的 OpenAPI v2.0模式，其中包含了自定义资源 sample/v1 的 Config 的 CRD 规范。自定义资源的根定义必须包含 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 校验限制

WebStorm 不支持以下 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。

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

配置代码折叠

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

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

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