API 参考（v3beta1）

包

• apps.emqx.io/v3beta1

apps.emqx.io/v3beta1

v3beta1 包包含 apps.emqx.io v3beta1 API 组的 API Schema 定义。

资源类型

• EMQX

Config

出现于：

• EMQXSpec

字段	说明	默认值	校验规则
roots ConfigRoots	EMQX 的顶层配置根项。值必须与 JSON 兼容。Operator 会将可在运行时应用的根项序列化到 base.hocon， 并将 EMQX 启动时生效的设置序列化到 emqx.conf。 不支持 include、替换和重复声明等仅适用于 HOCON 的语法。 删除根项表示 Operator 不再管理该配置，但不会删除 EMQX 已持久化的值。 node.cookie 路径由 Operator 保留，不得在此处指定。

ConfigRoots

底层类型： JSON

出现于：

• Config

ConfigStatus

ConfigStatus 包含由控制器管理的协调检查点。 这些字段仅用于提供实现信息，将来可能会发生变化。

出现于：

• EMQXStatus

字段	说明	默认值	校验规则
desiredRevision string	spec.config.roots 中完整预期配置的修订版本。
runtimeRevision string	EMQX API 最近接受的运行时配置修订版本。 首次启动前，该值表示为集群引导暂存的修订版本。
desiredStartupRevision string	EMQX 启动时生效的预期设置修订版本。
activeStartupRevisions string array	Ready Pod 所使用的启动配置修订版本。 存在多个修订版本表示 Ready Pod 使用了不同版本的启动设置。

CoreNodesStatus

CoreNodesStatus 是单个 StatefulSet 所管理的 Core 节点的汇总状态。

出现于：

• EMQXStatus

字段	说明	默认值	校验规则
readyReplicas integer	Ready 副本数。
updatedReplicas integer	已更新为预期 Pod 模板的副本数。
currentReplicas integer	仍在运行旧 Pod 模板的副本数。

DSDBReplicationStatus

出现于：

• DSReplicationStatus

字段	说明	默认值	校验规则
name string	数据库名称
numShards integer	数据库的分片数
numShardReplicas integer	分片副本总数
lostShardReplicas integer	属于已丢失站点的分片副本总数
numTransitions integer	当前正在转移所有权的分片数
minReplicas integer	数据库各分片的最小复制因子
maxReplicas integer	数据库各分片的最大复制因子

DSReplicationStatus

各数据库的 Durable Storage 复制状态摘要。

出现于：

• EMQXStatus

字段	说明	默认值	校验规则
dbs DSDBReplicationStatus array

EMQX

表示 EMQX 集群的自定义资源。

字段	说明	默认值	校验规则
apiVersion string	apps.emqx.io/v3beta1
kind string	EMQX
metadata ObjectMeta	有关 metadata 的字段，请参阅 Kubernetes API 文档。
spec EMQXSpec	EMQX 集群的预期状态规格。
status EMQXStatus	EMQX 集群的当前状态。

EMQXCoreTemplate

出现于：

• EMQXSpec

字段	说明	默认值	校验规则
metadata TemplateObjectMeta	应用于此模板所生成对象的元数据。
spec EMQXCoreTemplateSpec	Core 节点的预期状态规格。 更多信息：https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#spec-and-status	{ }

EMQXCoreTemplateSpec

出现于：

• EMQXCoreTemplate

字段	说明	默认值	校验规则
nodeSelector object (keys:string, values:string)	Selector which must be true for the pod to fit on a node. Must match a node's labels for the pod to be scheduled on that node. More info: https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node/
nodeName string	Request to schedule this pod onto a specific node. If it is non-empty, the scheduler simply schedules this pod onto that node, assuming that it fits resource requirements.
affinity Affinity	Affinity for pod assignment ref: https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node/#affinity-and-anti-affinity
tolerations Toleration array	Pod tolerations. If specified, Pod tolerates any taint that matches the triple <key,value,effect> using the matching operator.
topologySpreadConstraints TopologySpreadConstraint array	Specifies how to spread matching pods among the given topology.
dnsConfig PodDNSConfig	Specifies the DNS parameters of a pod. Parameters specified here will be merged to the generated DNS configuration based on DNSPolicy (always ClusterFirst). More info: https://kubernetes.io/docs/concepts/services-networking/dns-pod-service/#pod-dns-config
replicas integer	预期实例数。 对于 Core 节点，每个实例都具有稳定的标识。	1	Minimum: 0
minReadySeconds integer	MinReadySeconds is the minimum time (seconds) a pod must be Ready before it counts as available. For core nodes this is applied to the StatefulSet (mirrors apps/v1 StatefulSetSpec.minReadySeconds); for replicants, to the ReplicaSet (mirrors apps/v1 ReplicaSetSpec.minReadySeconds). Omitted or zero matches the apps/v1 default (0).		Minimum: 0
command string array	Entrypoint array. Not executed within a shell. The container image's ENTRYPOINT is used if this is not provided. Variable references $(VAR_NAME) are expanded using the container's environment. If a variable cannot be resolved, the reference in the input string will be unchanged. Double $$ are reduced to a single $, which allows for escaping the $(VAR_NAME) syntax: i.e. $$(VAR_NAME) will produce the string literal $(VAR_NAME). Escaped references will never be expanded, regardless of whether the variable exists or not. Cannot be updated. More info: https://kubernetes.io/docs/tasks/inject-data-application/define-command-argument-container/#running-a-command-in-a-shell		Optional: {}
args string array	Arguments to the entrypoint. The container image's CMD is used if this is not provided. Variable references $(VAR_NAME) are expanded using the container's environment. If a variable cannot be resolved, the reference in the input string will be unchanged. Double $$ are reduced to a single $, which allows for escaping the $(VAR_NAME) syntax: i.e. $$(VAR_NAME) will produce the string literal $(VAR_NAME). Escaped references will never be expanded, regardless of whether the variable exists or not. More info: https://kubernetes.io/docs/tasks/inject-data-application/define-command-argument-container/#running-a-command-in-a-shell
ports ContainerPort array	List of ports to expose from the container. Exposing a port here gives the system additional information about the network connections a container uses, but is primarily informational. Not specifying a port here DOES NOT prevent that port from being exposed. Any port which is listening on the default 0.0.0.0 address inside a container will be accessible from the network. Port names dashboard and dashboard-https are reserved by the Operator and cannot be supplied in the template. The Operator derives these named ports from spec.config.roots.dashboard.listeners for probes, Services, and per-Pod API requests. Change their container port by changing the corresponding listener bind instead.
env EnvVar array	List of environment variables to set in the container.
envFrom EnvFromSource array	List of sources to populate environment variables from in the container. The keys defined within a source must be a C_IDENTIFIER. All invalid keys will be reported as an event when the container is starting. When a key exists in multiple sources, the value associated with the last source will take precedence. Values defined by an Env with a duplicate key will take precedence.
resources ResourceRequirements	Compute Resources required by this container. More info: https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/
podSecurityContext PodSecurityContext	Pod-level security attributes and common container settings.	{ fsGroup:1000 fsGroupChangePolicy:Always runAsGroup:1000 runAsNonRoot:true runAsUser:1000 }
containerSecurityContext SecurityContext	Security options the container should be run with. If set, the fields of SecurityContext override the equivalent fields of PodSecurityContext. More info: https://kubernetes.io/docs/tasks/configure-pod-container/security-context/
initContainers Container array	List of initialization containers belonging to the pod. Init containers are executed in order prior to containers being started. If any init container fails, the pod is considered to have failed and is handled according to its restartPolicy. The name for an init container or normal container must be unique among all containers. Init containers may not have Lifecycle actions, Readiness probes, Liveness probes, or Startup probes. The resourceRequirements of an init container are taken into account during scheduling by finding the highest request/limit for each resource type, and then using the max of of that value or the sum of the normal containers. Limits are applied to init containers in a similar fashion. More info: https://kubernetes.io/docs/concepts/workloads/pods/init-containers/
extraContainers Container array	Additional containers to run alongside the main container.
extraVolumes Volume array	Additional volumes to provide to a Pod.
extraVolumeMounts VolumeMount array	Specifies how additional volumes are mounted into the main container.
livenessProbe Probe	Periodic probe of container liveness. Container will be restarted if the probe fails. More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#container-probes	{ failureThreshold:3 httpGet:map[path:/status port:dashboard] initialDelaySeconds:60 periodSeconds:30 }
readinessProbe Probe	Periodic probe of container service readiness. Container will be removed from service endpoints if the probe fails. Strongly advised to keep the current default: it takes into account ongoing node evacuations managed by the Operator as part of scaling operations and rolling updates. More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#container-probes	{ failureThreshold:1 httpGet:map[path:/api/v5/load_rebalance/availability_check port:dashboard] initialDelaySeconds:10 periodSeconds:5 timeoutSeconds:3 }
startupProbe Probe	StartupProbe indicates that the Pod has successfully initialized. If specified, no other probes are executed until this completes successfully. If this probe fails, the Pod will be restarted, just as if the livenessProbe failed. This can be used to provide different probe parameters at the beginning of a Pod's lifecycle, when it might take a long time to load data or warm a cache, than during steady-state operation. More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#container-probes
lifecycle Lifecycle	Actions that the management system should take in response to container lifecycle events.
persistentVolumeClaimSpec PersistentVolumeClaimSpec	Core 节点数据存储的 PVC 规格。

EMQXNode

出现于：

• EMQXStatus

字段	说明	默认值	校验规则
name string	节点名称
podName string	对应的 Pod 名称
status string	节点状态
otpRelease string	节点所运行的 Erlang/OTP 版本
version string	EMQX 版本
role string	节点角色，取值为 core 或 replicant
sessions integer	MQTT 会话数
connections integer	已连接的 MQTT 客户端数

EMQXReplicantTemplate

出现于：

• EMQXSpec

字段	说明	默认值	校验规则
metadata TemplateObjectMeta	应用于此模板所生成对象的元数据。
spec EMQXReplicantTemplateSpec	Replicant 节点的预期状态规格。 更多信息：https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#spec-and-status

EMQXReplicantTemplateSpec

出现于：

• EMQXCoreTemplateSpec
• EMQXReplicantTemplate

字段	说明	默认值	校验规则
nodeSelector object (keys:string, values:string)	Selector which must be true for the pod to fit on a node. Must match a node's labels for the pod to be scheduled on that node. More info: https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node/
nodeName string	Request to schedule this pod onto a specific node. If it is non-empty, the scheduler simply schedules this pod onto that node, assuming that it fits resource requirements.
affinity Affinity	Affinity for pod assignment ref: https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node/#affinity-and-anti-affinity
tolerations Toleration array	Pod tolerations. If specified, Pod tolerates any taint that matches the triple <key,value,effect> using the matching operator.
topologySpreadConstraints TopologySpreadConstraint array	Specifies how to spread matching pods among the given topology.
dnsConfig PodDNSConfig	Specifies the DNS parameters of a pod. Parameters specified here will be merged to the generated DNS configuration based on DNSPolicy (always ClusterFirst). More info: https://kubernetes.io/docs/concepts/services-networking/dns-pod-service/#pod-dns-config
replicas integer	预期实例数。 对于 Core 节点，每个实例都具有稳定的标识。	1	Minimum: 0
minReadySeconds integer	MinReadySeconds is the minimum time (seconds) a pod must be Ready before it counts as available. For core nodes this is applied to the StatefulSet (mirrors apps/v1 StatefulSetSpec.minReadySeconds); for replicants, to the ReplicaSet (mirrors apps/v1 ReplicaSetSpec.minReadySeconds). Omitted or zero matches the apps/v1 default (0).		Minimum: 0
command string array	Entrypoint array. Not executed within a shell. The container image's ENTRYPOINT is used if this is not provided. Variable references $(VAR_NAME) are expanded using the container's environment. If a variable cannot be resolved, the reference in the input string will be unchanged. Double $$ are reduced to a single $, which allows for escaping the $(VAR_NAME) syntax: i.e. $$(VAR_NAME) will produce the string literal $(VAR_NAME). Escaped references will never be expanded, regardless of whether the variable exists or not. Cannot be updated. More info: https://kubernetes.io/docs/tasks/inject-data-application/define-command-argument-container/#running-a-command-in-a-shell		Optional: {}
args string array	Arguments to the entrypoint. The container image's CMD is used if this is not provided. Variable references $(VAR_NAME) are expanded using the container's environment. If a variable cannot be resolved, the reference in the input string will be unchanged. Double $$ are reduced to a single $, which allows for escaping the $(VAR_NAME) syntax: i.e. $$(VAR_NAME) will produce the string literal $(VAR_NAME). Escaped references will never be expanded, regardless of whether the variable exists or not. More info: https://kubernetes.io/docs/tasks/inject-data-application/define-command-argument-container/#running-a-command-in-a-shell
ports ContainerPort array	List of ports to expose from the container. Exposing a port here gives the system additional information about the network connections a container uses, but is primarily informational. Not specifying a port here DOES NOT prevent that port from being exposed. Any port which is listening on the default 0.0.0.0 address inside a container will be accessible from the network. Port names dashboard and dashboard-https are reserved by the Operator and cannot be supplied in the template. The Operator derives these named ports from spec.config.roots.dashboard.listeners for probes, Services, and per-Pod API requests. Change their container port by changing the corresponding listener bind instead.
env EnvVar array	List of environment variables to set in the container.
envFrom EnvFromSource array	List of sources to populate environment variables from in the container. The keys defined within a source must be a C_IDENTIFIER. All invalid keys will be reported as an event when the container is starting. When a key exists in multiple sources, the value associated with the last source will take precedence. Values defined by an Env with a duplicate key will take precedence.
resources ResourceRequirements	Compute Resources required by this container. More info: https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/
podSecurityContext PodSecurityContext	Pod-level security attributes and common container settings.	{ fsGroup:1000 fsGroupChangePolicy:Always runAsGroup:1000 runAsNonRoot:true runAsUser:1000 }
containerSecurityContext SecurityContext	Security options the container should be run with. If set, the fields of SecurityContext override the equivalent fields of PodSecurityContext. More info: https://kubernetes.io/docs/tasks/configure-pod-container/security-context/
initContainers Container array	List of initialization containers belonging to the pod. Init containers are executed in order prior to containers being started. If any init container fails, the pod is considered to have failed and is handled according to its restartPolicy. The name for an init container or normal container must be unique among all containers. Init containers may not have Lifecycle actions, Readiness probes, Liveness probes, or Startup probes. The resourceRequirements of an init container are taken into account during scheduling by finding the highest request/limit for each resource type, and then using the max of of that value or the sum of the normal containers. Limits are applied to init containers in a similar fashion. More info: https://kubernetes.io/docs/concepts/workloads/pods/init-containers/
extraContainers Container array	Additional containers to run alongside the main container.
extraVolumes Volume array	Additional volumes to provide to a Pod.
extraVolumeMounts VolumeMount array	Specifies how additional volumes are mounted into the main container.
livenessProbe Probe	Periodic probe of container liveness. Container will be restarted if the probe fails. More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#container-probes	{ failureThreshold:3 httpGet:map[path:/status port:dashboard] initialDelaySeconds:60 periodSeconds:30 }
readinessProbe Probe	Periodic probe of container service readiness. Container will be removed from service endpoints if the probe fails. Strongly advised to keep the current default: it takes into account ongoing node evacuations managed by the Operator as part of scaling operations and rolling updates. More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#container-probes	{ failureThreshold:1 httpGet:map[path:/api/v5/load_rebalance/availability_check port:dashboard] initialDelaySeconds:10 periodSeconds:5 timeoutSeconds:3 }
startupProbe Probe	StartupProbe indicates that the Pod has successfully initialized. If specified, no other probes are executed until this completes successfully. If this probe fails, the Pod will be restarted, just as if the livenessProbe failed. This can be used to provide different probe parameters at the beginning of a Pod's lifecycle, when it might take a long time to load data or warm a cache, than during steady-state operation. More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#container-probes
lifecycle Lifecycle	Actions that the management system should take in response to container lifecycle events.

EMQXSpec

EMQXSpec 定义 EMQX 的预期状态。

出现于：

• EMQX

字段	说明	默认值	校验规则
image string	EMQX 容器镜像。 更多信息：https://kubernetes.io/docs/concepts/containers/images
imagePullPolicy PullPolicy	容器镜像拉取策略。 可取值为 Always、Never 或 IfNotPresent。 指定 :latest 标签时默认为 Always，否则默认为 IfNotPresent。 更多信息：https://kubernetes.io/docs/concepts/containers/images#updating-images
imagePullSecrets LocalObjectReference array	ImagePullSecrets is an optional list of references to secrets in the same namespace to use for pulling any of the images used by this PodSpec. If specified, these secrets will be passed to individual puller implementations for them to use. More info: https://kubernetes.io/docs/concepts/containers/images#specifying-imagepullsecrets-on-a-pod
serviceAccountName string	ServiceAccount name. Managed ReplicaSets and StatefulSets are associated with the specified ServiceAccount for authentication purposes. More info: https://kubernetes.io/docs/concepts/security/service-accounts
config Config	EMQX 配置。
clusterDomain string	Kubernetes 集群域名。	cluster.local
revisionHistoryLimit integer	为支持回滚而保留的旧 ReplicaSet 数量。	3
updateStrategy UpdateStrategy	集群升级策略设置。	{ type:RollingUpdate }
coreTemplate EMQXCoreTemplate	运行 EMQX Core 节点的 Pod 模板。	{ spec:map[persistentVolumeClaimSpec:map[accessModes:[ReadWriteOnce] resources:map[requests:map[storage:500Mi]]] replicas:1] }
replicantTemplate EMQXReplicantTemplate	运行 EMQX Replicant 节点的 Pod 模板。
dashboardServiceTemplate ServiceTemplate	用于公开 EMQX Dashboard 的 Service 模板。 Dashboard Service 始终指向 EMQX Core 节点集。 模板中名为 dashboard 或 dashboard-https 的端口会覆盖对应的自动生成 Service 端口。 可通过 port 在其他 Service 端口上公开监听器，但 targetPort 必须解析到对应的 Dashboard 监听器。 建议使用保留的命名目标端口，使其能够跟随监听器绑定地址的变化。
listenersServiceTemplate ServiceTemplate	用于公开已启用 EMQX 监听器的 Service 模板。 如果已启用且存在 Replicant 节点，Listeners Service 将指向 EMQX Replicant 节点集； 否则指向 EMQX Core 节点集。

EMQXStatus

EMQXStatus 定义观测到的 EMQX 状态。

出现于：

• EMQX

字段	说明	默认值	校验规则
conditions Condition array	表示 EMQX 自定义资源当前状态的条件。
coreReplicas integer	观测到的 Core 节点集副本数。
coreSelector string	与 Core Pod 匹配的序列化标签选择器。
replicantReplicas integer	观测到的 Replicant 节点集 Pod 副本数。 供 scale 子资源使用。
replicantSelector string	与 Replicant Pod 匹配的序列化标签选择器。 供 scale 子资源发现 HPA Pod。
coreNodes EMQXNode array	集群中各 Core 节点的状态。
coreNodesStatus CoreNodesStatus	Core 节点集的汇总状态。
replicantNodes EMQXNode array	集群中各 Replicant 节点的状态。
replicantNodesStatus ReplicantNodesStatus	Replicant 节点集的汇总状态。
nodeEvacuations NodeEvacuationStatus array	集群中正在进行的节点疏散状态。
dsReplication DSReplicationStatus	EMQX Durable Storage 复制状态。
config ConfigStatus	声明式 EMQX 配置的协调状态。 这些字段仅提供实现信息。请优先使用 ConfigApplied 条件 判断配置的生命周期状态。

EvacuationStrategy

出现于：

• UpdateStrategy

字段	说明	默认值	校验规则
type EvacuationStrategyType	节点疏散策略的类型。	NodeEvacuation	Enum: [NodeEvacuation Disabled]
connectionEvictionRate integer	客户端断开连接速率（每秒数量）。 与 EMQX 节点疏散中的 conn-evict-rate 相同。	1000	Minimum: 1
sessionEvictionRate integer	会话疏散速率（每秒数量）。 与 EMQX 节点疏散中的 sess-evict-rate 相同。	1000	Minimum: 1
waitTakeover integer	开始疏散会话前的等待时间（秒）。 与 EMQX 节点疏散中的 wait-takeover 相同。	10	Minimum: 0
waitHealthCheck integer	节点等待负载均衡器将其从活动后端节点列表中移除的时间（秒）。 与 EMQX 节点疏散中的 wait-health-check 相同。	60	Minimum: 0

EvacuationStrategyType

底层类型： string

出现于：

• EvacuationStrategy

字段	说明
NodeEvacuation
Disabled

NodeEvacuationStatus

出现于：

• EMQXStatus

字段	说明	默认值	校验规则
nodeName string	被疏散的节点名称
state string	疏散状态
sessionRecipients string array	会话接收节点
sessionEvictionRate integer	会话疏散速率，单位为会话数/秒。
connectionEvictionRate integer	连接疏散速率，单位为连接数/秒。
initialSessions integer	此节点的初始会话数
initialConnections integer	此节点的初始连接数

ReplicantNodesStatus

ReplicantNodesStatus 是 Replicant 节点集的汇总状态。 多 ReplicaSet 模式要求在 CR 级别跟踪修订版本。

出现于：

• EMQXStatus

字段	说明	默认值	校验规则
readyReplicas integer	Ready 副本数。
currentRevision string	Replicant 节点集的当前修订版本。
currentReplicas integer	运行当前修订版本的副本数。
updateRevision string	Replicant 节点集的更新修订版本。 如果与当前修订版本不同，表示正在更新该节点集。
updateReplicas integer	运行更新修订版本的副本数。
collisionCount integer

ReplicantsUpdateStrategy

ReplicantsUpdateStrategy 控制 Replicant ReplicaSet 的发布速度。 其语义与 apps/v1 Deployment.spec.strategy.rollingUpdate 一致。

出现于：

• UpdateStrategy

字段	说明	默认值	校验规则
maxUnavailable IntOrString	Replicant ReplicaSet 发布期间，允许同时排空（正在疏散、终止或标记为删除）的旧 Replicant Pod 最大数量。 整数表示绝对数量；字符串表示预期 Replicant 副本数的百分比，例如 "25%"。 默认值为 1，即逐个排空。		XIntOrString: {}
maxSurge IntOrString	模板发布期间，新 ReplicaSet 中允许超出预期副本数的额外 Replicant Pod 数量。 整数表示绝对数量；字符串表示预期副本数的百分比。默认值为 0。		XIntOrString: {}

ServiceTemplate

出现于：

• EMQXSpec

字段	说明	默认值	校验规则
enabled boolean	是否创建此 Service。	true
metadata TemplateObjectMeta	应用于此模板所生成对象的元数据。
spec ServiceSpec	Service 的预期状态规格。 https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#spec-and-status

TemplateObjectMeta

TemplateObjectMeta 包含要传播到模板所创建对象的元数据。

出现于：

• EMQXCoreTemplate
• EMQXReplicantTemplate
• ServiceTemplate

字段	说明	默认值	校验规则
labels object (keys:string, values:string)	应用于所生成对象的标签。
annotations object (keys:string, values:string)	应用于所生成对象的注解。

UpdateStrategy

出现于：

• EMQXSpec

字段	说明	默认值	校验规则
type string	确定集群升级的执行方式。 * RollingUpdate：通过逐步更新 Pod 来执行滚动升级；Core Pod 始终逐个更新， Replicant 的更新由 replicants 策略控制。	RollingUpdate	Enum: [RollingUpdate]
evacuationStrategy EvacuationStrategy	节点疏散策略设置。	{ type:NodeEvacuation }
replicants ReplicantsUpdateStrategy	Replicant ReplicaSet 滚动更新的参数。