API Reference
Packages
apps.emqx.io/v2beta1
Package v2beta1 contains API Schema definitions for the apps v2beta1 API group
Resource Types
BootstrapAPIKey
Appears in:
| Field | Description |
|---|---|
key string | |
secret string |
Config
Appears in:
| Field | Description |
|---|---|
mode string | |
data string | EMQX config, HOCON format, like etc/emqx.conf file |
EMQX
EMQX is the Schema for the emqxes API
Appears in:
| Field | Description |
|---|---|
apiVersion string | apps.emqx.io/v2beta1 |
kind string | EMQX |
metadata ObjectMeta | Refer to Kubernetes API documentation for fields of metadata. |
spec EMQXSpec | Spec defines the desired identities of EMQX nodes in this set. |
status EMQXStatus | Status is the current status of EMQX nodes. This data may be out of date by some window of time. |
EMQXCoreTemplate
Appears in:
| Field | Description |
|---|---|
metadata ObjectMeta | Refer to Kubernetes API documentation for fields of metadata. |
spec EMQXCoreTemplateSpec | Specification of the desired behavior of the EMQX core node. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#spec-and-status |
EMQXCoreTemplateSpec
Appears in:
| Field | Description |
|---|---|
nodeSelector object (keys:string, values:string) | NodeSelector is a selector which must be true for the pod to fit on a node. Selector which 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 | NodeName is a 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 | If specified, the pod's tolerations. The pod this Toleration is attached to tolerates any taint that matches the triple <key,value,effect> using the matching operator . TODO: should use tolerations instead, this field just for compatible with old version, will delete in future. |
tolerations Toleration array | If specified, the pod's tolerations. The pod this Toleration is attached to tolerates any taint that matches the triple <key,value,effect> using the matching operator . |
replicas integer | Replicas is the desired number of replicas of the given Template. These are replicas in the sense that they are instantiations of the same Template, but individual replicas also have a consistent identity. Defaults to 2. |
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. Cannot be updated. 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. Cannot be updated. |
env EnvVar array | List of environment variables to set in the container. Cannot be updated. |
envFrom EnvFromSource array | List of sources to populate environment variables 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. Cannot be updated. |
resources ResourceRequirements | Compute Resources required by this container. Cannot be updated. More info: https://kubernetes.io/docs/concepts/config/manage-resources-containers/ |
podSecurityContext PodSecurityContext | SecurityContext holds pod-level security attributes and common container settings. |
containerSecurityContext SecurityContext | SecurityContext defines the 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. Init containers cannot currently be added or removed. Cannot be updated. More info: https://kubernetes.io/docs/concepts/workloads/pods/init-containers/ |
extraContainers Container array | ExtraContainers represents extra containers to be added to the pod. See https://github.com/emqx/emqx-operator/issues/252 |
extraVolumes Volume array | See https://github.com/emqx/emqx-operator/pull/72 |
extraVolumeMounts VolumeMount array | See https://github.com/emqx/emqx-operator/pull/72 |
livenessProbe Probe | Periodic probe of container liveness. Container will be restarted if the probe fails. Cannot be updated. More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#container-probes |
readinessProbe Probe | Periodic probe of container service readiness. Container will be removed from service endpoints if the probe fails. Cannot be updated. More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#container-probes |
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. This cannot be updated. 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. Cannot be updated. |
volumeClaimTemplates PersistentVolumeClaimSpec | VolumeClaimTemplates is a list of claims that pods are allowed to reference. The StatefulSet controller is responsible for mapping network identities to claims in a way that maintains the identity of a pod. Every claim in this list must have at least one matching (by name) volumeMount in one container in the template. A claim in this list takes precedence over any volumes in the template, with the same name. More than EMQXReplicantTemplateSpec |
EMQXList
EMQXList contains a list of EMQX
| Field | Description |
|---|---|
apiVersion string | apps.emqx.io/v2beta1 |
kind string | EMQXList |
metadata ListMeta | Refer to Kubernetes API documentation for fields of metadata. |
items EMQX array |
EMQXNode
Appears in:
| Field | Description |
|---|---|
controllerUID UID | |
podUID UID | |
node string | EMQX node name, example: emqx@127.0.0.1 |
node_status string | EMQX node status, example: Running |
otp_release string | Erlang/OTP version used by EMQX, example: 24.2/12.2 |
version string | EMQX version |
role string | EMQX cluster node role, enum: "core" "replicant" |
edition string | EMQX cluster node edition, enum: "Opensource" "Enterprise" |
uptime integer | EMQX node uptime, milliseconds |
connections integer | In EMQX's API of /api/v5/nodes, the connections field means the number of MQTT session count, |
live_connections integer | In EMQX's API of /api/v5/nodes, the live_connections field means the number of connected MQTT clients. THe live_connections just work in EMQX 5.1 or later. |
EMQXNodesStatus
Appears in:
| Field | Description |
|---|---|
replicas integer | |
readyReplicas integer | |
currentRevision string | |
currentReplicas integer | |
updateRevision string | |
updateReplicas integer | |
collisionCount integer |
EMQXReplicantTemplate
Appears in:
| Field | Description |
|---|---|
metadata ObjectMeta | Refer to Kubernetes API documentation for fields of metadata. |
spec EMQXReplicantTemplateSpec | Specification of the desired behavior of the EMQX replicant node. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#spec-and-status |
EMQXReplicantTemplateSpec
Appears in:
| Field | Description |
|---|---|
nodeSelector object (keys:string, values:string) | NodeSelector is a selector which must be true for the pod to fit on a node. Selector which 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 | NodeName is a 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 | If specified, the pod's tolerations. The pod this Toleration is attached to tolerates any taint that matches the triple <key,value,effect> using the matching operator . TODO: should use tolerations instead, this field just for compatible with old version, will delete in future. |
tolerations Toleration array | If specified, the pod's tolerations. The pod this Toleration is attached to tolerates any taint that matches the triple <key,value,effect> using the matching operator . |
replicas integer | Replicas is the desired number of replicas of the given Template. These are replicas in the sense that they are instantiations of the same Template, but individual replicas also have a consistent identity. Defaults to 2. |
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. Cannot be updated. 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. Cannot be updated. |
env EnvVar array | List of environment variables to set in the container. Cannot be updated. |
envFrom EnvFromSource array | List of sources to populate environment variables 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. Cannot be updated. |
resources ResourceRequirements | Compute Resources required by this container. Cannot be updated. More info: https://kubernetes.io/docs/concepts/config/manage-resources-containers/ |
podSecurityContext PodSecurityContext | SecurityContext holds pod-level security attributes and common container settings. |
containerSecurityContext SecurityContext | SecurityContext defines the 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. Init containers cannot currently be added or removed. Cannot be updated. More info: https://kubernetes.io/docs/concepts/workloads/pods/init-containers/ |
extraContainers Container array | ExtraContainers represents extra containers to be added to the pod. See https://github.com/emqx/emqx-operator/issues/252 |
extraVolumes Volume array | See https://github.com/emqx/emqx-operator/pull/72 |
extraVolumeMounts VolumeMount array | See https://github.com/emqx/emqx-operator/pull/72 |
livenessProbe Probe | Periodic probe of container liveness. Container will be restarted if the probe fails. Cannot be updated. More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#container-probes |
readinessProbe Probe | Periodic probe of container service readiness. Container will be removed from service endpoints if the probe fails. Cannot be updated. More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#container-probes |
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. This cannot be updated. 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. Cannot be updated. |
EMQXSpec
EMQXSpec defines the desired state of EMQX
Appears in:
| Field | Description |
|---|---|
image string | EMQX image name. More info: https://kubernetes.io/docs/concepts/containers/images |
imagePullPolicy PullPolicy | Image pull policy. One of Always, Never, IfNotPresent. Defaults to Always if :latest tag is specified, or IfNotPresent otherwise. Cannot be updated. 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 | Service Account Name This associates the ReplicaSet or StatefulSet with the specified Service Account for authentication purposes. More info: https://kubernetes.io/docs/concepts/security/service-accounts |
bootstrapAPIKeys BootstrapAPIKey array | EMQX bootstrap user Cannot be updated. |
config Config | EMQX config |
clusterDomain string | |
revisionHistoryLimit integer | The number of old ReplicaSets, old StatefulSet and old PersistentVolumeClaim to retain to allow rollback. This is a pointer to distinguish between explicit zero and not specified. Defaults to 3. |
updateStrategy UpdateStrategy | UpdateStrategy is the object that describes the EMQX blue-green update strategy |
coreTemplate EMQXCoreTemplate | CoreTemplate is the object that describes the EMQX core node that will be created |
replicantTemplate EMQXReplicantTemplate | ReplicantTemplate is the object that describes the EMQX replicant node that will be created |
dashboardServiceTemplate ServiceTemplate | DashboardServiceTemplate is the object that describes the EMQX dashboard service that will be created This service always selector the EMQX core node |
listenersServiceTemplate ServiceTemplate | ListenersServiceTemplate is the object that describes the EMQX listener service that will be created If the EMQX replicant node exist, this service will selector the EMQX replicant node Else this service will selector EMQX core node |
EMQXStatus
EMQXStatus defines the observed state of EMQX
Appears in:
| Field | Description |
|---|---|
conditions Condition array | Represents the latest available observations of a EMQX Custom Resource current state. |
coreNodes EMQXNode array | |
coreNodesStatus EMQXNodesStatus | |
replicantNodes EMQXNode array | |
replicantNodesStatus EMQXNodesStatus | |
nodEvacuationsStatus NodeEvacuationStatus array |
EvacuationStrategy
Appears in:
| Field | Description |
|---|---|
waitTakeover integer | |
connEvictRate integer | Just work in EMQX Enterprise. |
sessEvictRate integer | Just work in EMQX Enterprise. |
NodeEvacuationStats
Appears in:
| Field | Description |
|---|---|
initial_sessions integer | |
initial_connected integer | |
current_sessions integer | |
current_connected integer |
NodeEvacuationStatus
Appears in:
| Field | Description |
|---|---|
node string | |
stats NodeEvacuationStats | |
state string | |
session_recipients string array | |
session_goal integer | |
session_eviction_rate integer | |
connection_goal integer | |
connection_eviction_rate integer |
Rebalance
Rebalance is the Schema for the rebalances API
Appears in:
| Field | Description |
|---|---|
apiVersion string | apps.emqx.io/v2beta1 |
kind string | Rebalance |
metadata ObjectMeta | Refer to Kubernetes API documentation for fields of metadata. |
spec RebalanceSpec | |
status RebalanceStatus |
RebalanceCondition
RebalanceCondition describes current state of a EMQX rebalancing job.
Appears in:
| Field | Description |
|---|---|
type RebalanceConditionType | Status of rebalance condition type. one of Processing, Complete, Failed. |
status ConditionStatus | Status of the condition, one of True, False, Unknown. |
lastUpdateTime Time | The last time this condition was updated. |
lastTransitionTime Time | Last time the condition transitioned from one status to another. |
reason string | The reason for the condition's last transition. |
message string | A human readable message indicating details about the transition. |
RebalanceConditionType
Underlying type: string
Appears in:
RebalanceList
RebalanceList contains a list of Rebalance
| Field | Description |
|---|---|
apiVersion string | apps.emqx.io/v2beta1 |
kind string | RebalanceList |
metadata ListMeta | Refer to Kubernetes API documentation for fields of metadata. |
items Rebalance array |
RebalancePhase
Underlying type: string
Appears in:
RebalanceSpec
RebalanceSpec defines the desired state of Rebalance
Appears in:
| Field | Description |
|---|---|
instanceKind string | InstanceKind is used to distinguish between EMQX and EMQXEnterprise. When it is set to "EMQX", it means that the EMQX CR is v2beta1, and when it is set to "EmqxEnterprise", it means that the EmqxEnterprise CR is v1beta4. |
instanceName string | InstanceName represents the name of EMQX CR, just work for EMQX Enterprise |
rebalanceStrategy RebalanceStrategy | RebalanceStrategy represents the strategy of EMQX rebalancing More info: https://docs.emqx.com/en/enterprise/v4.4/advanced/rebalancing.html#rebalancing |
RebalanceState
Rebalance defines the observed Rebalancing state of EMQX
Appears in:
| Field | Description |
|---|---|
state string | State represents the state of emqx cluster rebalancing. |
session_eviction_rate integer | SessionEvictionRate represents the node session evacuation rate per second. |
recipients string array | Recipients represent the target node for rebalancing. |
node string | Node represents the rebalancing scheduling node. |
donors string array | Donors represent the source nodes for rebalancing. |
coordinator_node string | CoordinatorNode represents the node currently undergoing rebalancing. |
connection_eviction_rate integer | ConnectionEvictionRate represents the node session evacuation rate per second. |
RebalanceStatus
RebalanceStatus represents the current state of Rebalance
Appears in:
| Field | Description |
|---|---|
conditions RebalanceCondition array | The latest available observations of an object's current state. When Rebalance fails, the condition will have type "Failed" and status false. When Rebalance is in processing, the condition will have a type "Processing" and status true. When Rebalance is completed, the condition will have a type "Complete" and status true. |
phase RebalancePhase | Phase represents the phase of Rebalance. |
rebalanceStates RebalanceState array | |
startedTime Time | StartedTime Represents the time when rebalance job start. |
completedTime Time | CompletedTime Represents the time when the rebalance job was completed. |
RebalanceStrategy
RebalanceStrategy represents the strategy of EMQX rebalancing
Appears in:
| Field | Description |
|---|---|
connEvictRate integer | ConnEvictRate represents the source node client disconnect rate per second. same to conn-evict-rate in EMQX Rebalancing The value must be greater than 0 |
sessEvictRate integer | SessEvictRate represents the source node session evacuation rate per second. same to sess-evict-rate in EMQX Rebalancing The value must be greater than 0 Defaults to 500. |
waitTakeover integer | WaitTakeover represents the time in seconds to wait for a client to reconnect to take over the session after all connections are disconnected. same to wait-takeover in EMQX Rebalancing The value must be greater than 0 Defaults to 60 seconds. |
waitHealthCheck integer | WaitHealthCheck represents the time (in seconds) to wait for the LB to remove the source node from the list of active backend nodes. After the specified waiting time is exceeded,the rebalancing task will start. same to wait-health-check in EMQX Rebalancing The value must be greater than 0 Defaults to 60 seconds. |
absConnThreshold integer | AbsConnThreshold represents the absolute threshold for checking connection balance. same to abs-conn-threshold in EMQX Rebalancing The value must be greater than 0 Defaults to 1000. |
relConnThreshold string | RelConnThreshold represents the relative threshold for checkin connection balance. same to rel-conn-threshold in EMQX Rebalancing the usage of float highly discouraged, as support for them varies across languages. So we define the RelConnThreshold field as string type and you not float type The value must be greater than "1.0" Defaults to "1.1". |
absSessThreshold integer | AbsSessThreshold represents the absolute threshold for checking session connection balance. same to abs-sess-threshold in EMQX Rebalancing The value must be greater than 0 Default to 1000. |
relSessThreshold string | RelSessThreshold represents the relative threshold for checking session connection balance. same to rel-sess-threshold in EMQX Rebalancing the usage of float highly discouraged, as support for them varies across languages. So we define the RelSessThreshold field as string type and you not float type The value must be greater than "1.0" Defaults to "1.1". |
ServiceTemplate
Appears in:
| Field | Description |
|---|---|
enabled boolean | EMQX Operator will create a service for EMQX nodes. This is a pointer to distinguish between false and not specified. |
metadata ObjectMeta | Refer to Kubernetes API documentation for fields of metadata. |
spec ServiceSpec | Spec defines the behavior of a service. https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#spec-and-status |
UpdateStrategy
Appears in:
| Field | Description |
|---|---|
type string | |
initialDelaySeconds integer | Number of seconds before evacuation connection start. |
evacuationStrategy EvacuationStrategy | Number of seconds before evacuation connection timeout. |