Kubernetes

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

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

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

安装 Kubernetes 插件

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

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

指定 kubectl 的自定义路径

PhpStorm 使用由 PATH 环境变量指定的默认 kubectl（以及如果使用的话则包括 helm ）可执行文件。

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

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

使用自定义 Kubernetes 配置文件

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

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

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

配置 Kubernetes API 版本

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

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

资源配置文件

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

支持的功能

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

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

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

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

创建资源文件

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

在 Project 工具窗口 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 模式验证

PhpStorm 根据 Kubernetes API 模式验证您的 Kubernetes 文件。这包括检查其所需的关键字或可能的资源类型。

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

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

管理您的集群

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

添加集群

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

打开服務工具窗口：选择视图(V) | 工具窗口(T) | 服务或按 Alt+8。
在服务工具窗口中右键单击一个 Kubernetes 节点并选择添加集群。或者，单击并选择 Kubernetes | 添加集群。
接下来，选择要添加的 Kubernetes 集群的来源：
- 来自默认目录：从默认位置获取集群（通常为 $HOME/.kube/config）。
- 来自自定义 kubeconfigs ：从您的计算机中选择任意 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 命名空间允许您在集群内逻辑隔离资源。借助 PhpStorm，您可以快速切换命名空间。

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

选择当前集群

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

当您在本地修改或创建资源文件时，您可以通过单击选择要应用资源的集群。您也可以提前选择它。

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

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

修改集群资源

打开服務工具窗口：选择视图(V) | 工具窗口(T) | 服务或按 Alt+8。
右键点击资源并选择查看YAML。
这将会在编辑器的新选项卡中打开所选资源的配置文件。当您更改字段时，修改后的行会在边距中突出显示。您可以点击页边空白处的高亮区域快速预览或回滚更改。
单击将更改应用到当前集群和命名空间。

当您修改资源配置文件时，工具栏会出现在右上角。它允许您应用更改、删除资源、预览差异及回滚更改。

查看资源详细信息

PhpStorm 可让您快速查看 Kubernetes 资源的详细信息，而无需手动运行任何命令。

在服务工具窗口中，选择一个资源以查看其详细信息。

删除资源

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

在服务工具窗口中，右键点击资源并选择删除(当前集群未配置)。
在服务工具窗口中，选择一个资源并在工具栏上点击（删除资源）。
如果资源 YAML 文件在编辑器中打开，请将鼠标悬停在其上并点击。您还可以单击此处的更改要删除资源的集群。

转发端口

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

打开服務工具窗口：选择视图(V) | 工具窗口(T) | 服务或按 Alt+8。右键点击目标 pod 并选择转发端口。
在转发端口对话框中：
- 在地址字段中，列出需要监听的地址。使用逗号分隔多个值。
- 在端口字段中，以 <local port>:<remote port> 格式指定端口。例如， 8888:5000 表示监听本地端口 8888 并将数据转发至远程端口 5000。
  PhpStorm 会根据对应 Kubernetes 清单中定义的值自动建议端口映射。如果清单中指定的端口在您的本地计算机上已被使用，PhpStorm 会按递增方式调整建议值，直到找到可用端口。
  如果指定的值小于 1024 ，则会在建议的本地端口值中加上 8000。
  如果您手动指定了一个当前已被占用的本地端口，PhpStorm 会在开始转发前提示您。
点击转发。

管理端口转发会话

要查看所有活动的端口转发会话，请在服务工具窗口中，在 Kubernetes 集群下展开网络｜端口转发。
要终止端口转发会话，请右键点击该会话并选择停止端口转发，或点击工具栏中的。
要重新启动端口转发会话，请右键点击该会话并选择重新启动端口转发，或点击工具栏中的。

创建 secret

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

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

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

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

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

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

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

重新加载配置

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

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

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

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

手动刷新集群资源

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

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

查看日志

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

在编辑器中打开资源日志

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

指定 CRD 规格路径

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

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

默认情况下，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 校验限制

PhpStorm 不支持以下 OpenAPI v3 模式功能：

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

提高效率的提示

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

分配快捷键

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

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

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

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

配置代码折叠

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

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

最后修改日期： 2025年 9月 26日