API Reference (v2)

Packages

• apps.emqx.io/v2

apps.emqx.io/v2

package v2 contains API Schema definitions for the apps v2 API group.

Resource Types

• EMQX

BootstrapAPIKey

Appears in:

• EMQXSpec

Field	Description	Default	Validation
key string			Pattern: ^[a-zA-Z\d-_]+$
secret string			MaxLength: 128 MinLength: 3
secretRef SecretRef	Reference to a Secret entry containing the EMQX API Key.

Config

Appears in:

• EMQXSpec

Field	Description	Default	Validation
mode string	Determines how configuration updates are applied. * Merge: Merge the new configuration into the existing configuration. * Replace: Replace the whole configuration.	Merge	Enum: [Merge Replace]
data string	EMQX configuration, in HOCON format. This configuration will be supplied as base.hocon to the container. See respective documentation.

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/v2
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 ObjectMeta	Refer to Kubernetes API documentation for fields of metadata.
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/config/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/config/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.
replicas integer	Desired number of instances. In case of core nodes, each instance has a consistent identity.	2	Minimum: 0
minAvailable IntOrString	An eviction is allowed if at least "minAvailable" pods selected by "selector" will still be available after the eviction, i.e. even in the absence of the evicted pod. So for example you can prevent all voluntary evictions by specifying "100%".		XIntOrString: {}
maxUnavailable IntOrString	An eviction is allowed if at most "maxUnavailable" pods selected by "selector" are unavailable after the eviction, i.e. even in absence of the evicted pod. For example, one can prevent all voluntary evictions by specifying 0. This is a mutually exclusive setting with "minAvailable".		XIntOrString: {}
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
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.
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/config/manage-resources-containers/
podSecurityContext PodSecurityContext	Pod-level security attributes and common container settings.	{ fsGroup:1000 fsGroupChangePolicy:Always runAsGroup:1000 runAsUser:1000 supplementalGroups:[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/	{ runAsGroup:1000 runAsNonRoot:true runAsUser:1000 }
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. More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#container-probes	{ failureThreshold:12 httpGet:map[path:/status port:dashboard] initialDelaySeconds:10 periodSeconds:5 }
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.
volumeClaimTemplates PersistentVolumeClaimSpec	PVC specification for a core node data storage. Note: this field named inconsistently, it is actually just a PersistentVolumeClaimSpec.

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"
sessions integer	Number of MQTT sessions
connections integer	Number of connected MQTT clients

EMQXNodesStatus

Appears in:

• EMQXStatus

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

EMQXReplicantTemplate

Appears in:

• EMQXSpec

Field	Description	Default	Validation
metadata ObjectMeta	Refer to Kubernetes API documentation for fields of metadata.
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

EMQXReplicantTemplateSpec

Appears in:

• EMQXCoreTemplateSpec
• 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/config/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/config/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.
replicas integer	Desired number of instances. In case of core nodes, each instance has a consistent identity.	2	Minimum: 0
minAvailable IntOrString	An eviction is allowed if at least "minAvailable" pods selected by "selector" will still be available after the eviction, i.e. even in the absence of the evicted pod. So for example you can prevent all voluntary evictions by specifying "100%".		XIntOrString: {}
maxUnavailable IntOrString	An eviction is allowed if at most "maxUnavailable" pods selected by "selector" are unavailable after the eviction, i.e. even in absence of the evicted pod. For example, one can prevent all voluntary evictions by specifying 0. This is a mutually exclusive setting with "minAvailable".		XIntOrString: {}
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
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.
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/config/manage-resources-containers/
podSecurityContext PodSecurityContext	Pod-level security attributes and common container settings.	{ fsGroup:1000 fsGroupChangePolicy:Always runAsGroup:1000 runAsUser:1000 supplementalGroups:[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/	{ runAsGroup:1000 runAsNonRoot:true runAsUser:1000 }
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. More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#container-probes	{ failureThreshold:12 httpGet:map[path:/status port:dashboard] initialDelaySeconds:10 periodSeconds:5 }
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 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
bootstrapAPIKeys BootstrapAPIKey array	Bootstrap API keys to access EMQX API. Cannot be updated.
config Config	EMQX Configuration.
clusterDomain string	Kubernetes cluster domain.	cluster.local
revisionHistoryLimit integer	Number of old ReplicaSets, old StatefulSets and old PersistentVolumeClaims to retain to allow rollback.	3
updateStrategy UpdateStrategy	Cluster upgrade strategy settings.	{ type:Recreate }
coreTemplate EMQXCoreTemplate	Template for Pods running EMQX core nodes.	{ spec:map[replicas:2] }
replicantTemplate EMQXReplicantTemplate	Template for Pods running EMQX replicant nodes.
dashboardServiceTemplate ServiceTemplate	Template for Service exposing the EMQX Dashboard. Dashboard Service always points to the set of EMQX core nodes.
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.
coreNodes EMQXNode array	Status of each core node in the cluster.
coreNodesStatus EMQXNodesStatus	Summary status of the set of core nodes.
replicantNodes EMQXNode array	Status of each replicant node in the cluster.
replicantNodesStatus EMQXNodesStatus	Summary status of the set of replicant nodes.
nodeEvacuationsStatus NodeEvacuationStatus array	Status of active node evacuations in the cluster.
dsReplication DSReplicationStatus	Status of EMQX Durable Storage replication.

EvacuationStrategy

Appears in:

• UpdateStrategy

Field	Description	Default	Validation
connEvictRate integer	Client disconnect rate (number per second). Same as conn-evict-rate in EMQX Node Evacuation.	1000	Minimum: 1
sessEvictRate 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

KeyRef

Appears in:

• SecretRef

Field	Description	Default	Validation
secretName string	Name of the Secret object.
secretKey string	Entry within the Secret data.		Pattern: ^[a-zA-Z\d-_]+$

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

SecretRef

Appears in:

• BootstrapAPIKey

Field	Description	Default	Validation
key KeyRef	Reference to a Secret entry containing the EMQX API Key.
secret KeyRef	Reference to a Secret entry containing the EMQX API Key's secret.

ServiceTemplate

Appears in:

• EMQXSpec

Field	Description	Default	Validation
enabled boolean	Specifies whether the Service should be created.	true
metadata ObjectMeta	Refer to Kubernetes API documentation for fields of metadata.
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

UpdateStrategy

Appears in:

• EMQXSpec

Field	Description	Default	Validation
type string	Determines how cluster upgrade is performed. * Recreate: Perform blue-green upgrade.	Recreate	Enum: [Recreate]
initialDelaySeconds integer	Number of seconds before connection evacuation starts.	10	Minimum: 0
evacuationStrategy EvacuationStrategy	Evacuation strategy settings.