API Reference (v3beta1)

Packages

• apps.emqx.io/v3beta1

apps.emqx.io/v3beta1

Package v3beta1 contains API Schema definitions for the apps.emqx.io v3beta1 API group.

Resource Types

• EMQX

Config

Appears in:

• EMQXSpec

Field	Description	Default	Validation
roots ConfigRoots	Top-level EMQX configuration roots. Values must be JSON-compatible. The Operator serializes runtime-applicable roots into base.hocon and settings that take effect when EMQX starts into emqx.conf. HOCON-only syntax such as includes, substitutions, and duplicate declarations is not supported. Removing a root relinquishes Operator ownership; it does not delete values persisted by EMQX. The node.cookie path is reserved for the Operator and must not be specified here.

ConfigRoots

Underlying type: JSON

Appears in:

• Config

ConfigStatus

ConfigStatus contains controller-owned reconciliation checkpoints. These fields are informational implementation details and may change.

Appears in:

• EMQXStatus

Field	Description	Default	Validation
desiredRevision string	Revision of the complete desired configuration in spec.config.roots.
runtimeRevision string	Revision of runtime configuration most recently accepted by the EMQX API. Before initial startup, it is the revision staged for cluster bootstrap.
desiredStartupRevision string	Revision of the desired settings that take effect when EMQX starts.
activeStartupRevisions string array	Revisions of startup configuration used by ready Pods. Multiple revisions indicate that ready Pods started with different versions of those settings.

CoreNodesStatus

CoreNodesStatus is the summary status of core nodes managed by a single StatefulSet.

Appears in:

• EMQXStatus

Field	Description	Default	Validation
readyReplicas integer	Number of ready replicas.
updatedReplicas integer	Number of replicas already updated to the desired pod template.
currentReplicas integer	Number of replicas still running the previous pod template.

DSDBReplicationStatus

Appears in:

• DSReplicationStatus

Field	Description	Default	Validation
name string	Name of the database
numShards integer	Number of shards of the database
numShardReplicas integer	Total number of shard replicas
lostShardReplicas integer	Total number of shard replicas belonging to lost sites
numTransitions integer	Current number of shard ownership transitions
minReplicas integer	Minimum replication factor among database shards
maxReplicas integer	Maximum replication factor among database shards

DSReplicationStatus

Summary of DS replication status per database.

Appears in:

• EMQXStatus

Field	Description	Default	Validation
dbs DSDBReplicationStatus array

EMQX

Custom Resource representing an EMQX cluster.

Field	Description	Default	Validation
apiVersion string	apps.emqx.io/v3beta1
kind string	EMQX
metadata ObjectMeta	Refer to Kubernetes API documentation for fields of metadata.
spec EMQXSpec	Specification of the desired state of the EMQX cluster.
status EMQXStatus	Current status of the EMQX cluster.

EMQXCoreTemplate

Appears in:

• EMQXSpec

Field	Description	Default	Validation
metadata TemplateObjectMeta	Metadata applied to objects generated from this template.
spec EMQXCoreTemplateSpec	Specification of the desired state of a core node. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#spec-and-status	{ }

EMQXCoreTemplateSpec

Appears in:

• EMQXCoreTemplate

Field	Description	Default	Validation
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
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.
replicas integer	Desired number of Core nodes. Each instance has a consistent identity.	1	Minimum: 0
persistentVolumeClaimSpec PersistentVolumeClaimSpec	PVC specification for a core node data storage.

EMQXNode

Appears in:

• EMQXStatus

Field	Description	Default	Validation
name string	Node name
podName string	Corresponding pod name
status string	Node status
otpRelease string	Erlang/OTP version node is running on
version string	EMQX version
role string	Node role, either "core" or "replicant", omitted when unknown
sessions integer	Number of MQTT sessions
connections integer	Number of connected MQTT clients

EMQXReplicantTemplate

Appears in:

• EMQXSpec

Field	Description	Default	Validation
metadata TemplateObjectMeta	Metadata applied to objects generated from this template.
spec EMQXReplicantTemplateSpec	Specification of the desired state of a replicant node. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#spec-and-status	{ replicas:0 }

EMQXReplicantTemplateSpec

Appears in:

• EMQXReplicantTemplate

Field	Description	Default	Validation
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
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.
replicas integer	Desired number of Replicant nodes.	0	Minimum: 0

EMQXSpec

EMQXSpec defines the desired state of EMQX.

Appears in:

• EMQX

Field	Description	Default	Validation
image string	EMQX container image. More info: https://kubernetes.io/docs/concepts/containers/images
imagePullPolicy PullPolicy	Container image pull policy. One of Always, Never, IfNotPresent. Defaults to Always if :latest tag is specified, or IfNotPresent otherwise. More info: 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 Configuration.
clusterDomain string	Kubernetes cluster domain.	cluster.local
revisionHistoryLimit integer	Number of old ReplicaSets to retain to allow rollback.	3
updateStrategy UpdateStrategy	Cluster upgrade strategy settings.	{ type:RollingUpdate }
coreTemplate EMQXCoreTemplate	Template for Pods running EMQX core nodes.	{ spec:map[persistentVolumeClaimSpec:map[accessModes:[ReadWriteOnce] resources:map[requests:map[storage:500Mi]]] replicas:1] }
replicantTemplate EMQXReplicantTemplate	Template for Pods running EMQX replicant nodes.	{ spec:map[replicas:0] }
dashboardServiceTemplate ServiceTemplate	Template for Service exposing the EMQX Dashboard. Dashboard Service always points to the set of EMQX core nodes. A port named dashboard or dashboard-https in the template overrides the corresponding generated Service port. Its port may expose the listener on a different Service port, but its targetPort must resolve to the corresponding Dashboard listener. Prefer the reserved named target port so it follows changes to the listener bind.
listenersServiceTemplate ServiceTemplate	Template for Service exposing enabled EMQX listeners. Listeners Service points to the set of EMQX replicant nodes if they are enabled and exist. Otherwise, it points to the set of EMQX core nodes.

EMQXStatus

EMQXStatus defines the observed state of EMQX

Appears in:

• EMQX

Field	Description	Default	Validation
conditions Condition array	Conditions representing the current status of the EMQX Custom Resource.
coreReplicas integer	Observed replica count for the core set.
coreSelector string	Serialized label selector matching core pods.
replicantReplicas integer	Observed replica count for the replicant set pods. Used by the scale subresource.
replicantSelector string	Serialized label selector matching replicant pods. Used by the scale subresource for HPA pod discovery.
coreNodesStatus CoreNodesStatus	Summary status of the set of core nodes.
replicantNodesStatus ReplicantNodesStatus	Summary status of the set of replicant nodes.
clusterNodes EMQXNode array	Observed cluster nodes, including nodes whose role is unknown.
nodeEvacuations NodeEvacuationStatus array	Status of active node evacuations in the cluster.
dsReplication DSReplicationStatus	Status of EMQX Durable Storage replication.
config ConfigStatus	Declarative EMQX configuration reconciliation status. Fields are informational implementation details. Prefer the ConfigApplied condition to determine configuration lifecycle state.

EvacuationStrategy

Appears in:

• UpdateStrategy

Field	Description	Default	Validation
type EvacuationStrategyType	Type of the evacuation policy.	NodeEvacuation	Enum: [NodeEvacuation Disabled]
connectionEvictionRate integer	Client disconnect rate (number per second). Same as conn-evict-rate in EMQX Node Evacuation.	1000	Minimum: 1
sessionEvictionRate integer	Session evacuation rate (number per second). Same as sess-evict-rate in EMQX Node Evacuation.	1000	Minimum: 1
waitTakeover integer	Amount of time (in seconds) to wait before starting session evacuation. Same as wait-takeover in EMQX Node Evacuation.	10	Minimum: 0
waitHealthCheck integer	Duration (in seconds) during which the node waits for the Load Balancer to remove it from the active backend node list. Same as wait-health-check in EMQX Node Evacuation.	60	Minimum: 0

EvacuationStrategyType

Underlying type: string

Appears in:

• EvacuationStrategy

Field	Description
NodeEvacuation
Disabled

NodeEvacuationStatus

Appears in:

• EMQXStatus

Field	Description	Default	Validation
nodeName string	Evacuated node name
state string	Evacuation state
sessionRecipients string array	Session recipients
sessionEvictionRate integer	Session eviction rate, in sessions per second.
connectionEvictionRate integer	Connection eviction rate, in connections per second.
initialSessions integer	Initial number of sessions on this node
initialConnections integer	Initial number of connections to this node

ReplicantNodesStatus

ReplicantNodesStatus is the summary status of the set of replicant nodes. The multi-ReplicaSet pattern requires revision tracking at the CR level.

Appears in:

• EMQXStatus

Field	Description	Default	Validation
readyReplicas integer	Number of ready replicas.
currentRevision string	Current revision of the replicant set.
currentReplicas integer	Number of replicas running current revision.
updateRevision string	Update revision of the replicant set. When different from the current revision, the set is being updated.
updateReplicas integer	Number of replicas running update revision.
collisionCount integer

ReplicantsUpdateStrategy

ReplicantsUpdateStrategy controls the pace of replicant ReplicaSet rollouts. Semantics mirror apps/v1 Deployment.spec.strategy.rollingUpdate.

Appears in:

• UpdateStrategy

Field	Description	Default	Validation
maxUnavailable IntOrString	MaxUnavailable is the maximum number of old replicant pods that may be drained (evacuating, terminating, or marked for deletion) at once during a replicant ReplicaSet rollout. Integers are absolute counts; strings are percentages of desired replicant replicas (e.g. "25%"). Defaults to 1 (serial drain).		XIntOrString: {}
maxSurge IntOrString	MaxSurge is the number of extra replicant pods allowed above the desired replica count on the new ReplicaSet during a template rollout. Integers are absolute; strings are percentages of desired replicas. Defaults to 0.		XIntOrString: {}

ServiceTemplate

Appears in:

• EMQXSpec

Field	Description	Default	Validation
enabled boolean	Specifies whether the Service should be created.	true
metadata TemplateObjectMeta	Metadata applied to objects generated from this template.
spec ServiceSpec	Specification of the desired state of a Service. https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#spec-and-status

TemplateObjectMeta

TemplateObjectMeta contains metadata propagated to objects created from a template.

Appears in:

• EMQXCoreTemplate
• EMQXReplicantTemplate
• ServiceTemplate

Field	Description	Default	Validation
labels object (keys:string, values:string)	Labels applied to generated objects.
annotations object (keys:string, values:string)	Annotations applied to generated objects.

UpdateStrategy

Appears in:

• EMQXSpec

Field	Description	Default	Validation
type string	Determines how cluster upgrade is performed. * RollingUpdate: Perform a rolling upgrade, updating pods gradually; core pods are always updated one at a time, updating of replicants is controlled by replicants strategy.	RollingUpdate	Enum: [RollingUpdate]
evacuationStrategy EvacuationStrategy	Evacuation strategy settings.	{ type:NodeEvacuation }
replicants ReplicantsUpdateStrategy	Parameters of the rolling update for replicant ReplicaSet rollouts.