System.exit(1);
}
}
}
with jndi.properties:
connectionfactory.myFactoryLookup = amqps://messaging-route-hostname:443?transport.trustAll=true&transport.verifyHost=false
queue.myQueueLookup = myqueue
You can use the following Rhea JavaScript Client example to connect your application to EnMasse. This example assumes you have created an address of type queue
named myqueue
.
var container = require('rhea');
container.on('connection_open', function (context) {
context.connection.open_receiver('myqueue');
context.connection.open_sender('myqueue');
});
container.on('message', function (context) {
console.log(context.message.body);
context.connection.close();
});
container.on('sendable', function (context) {
context.sender.send({body:'Hello World!'});
context.sender.detach();
});
container.connect({username: 'username', password: 'password', port:443, host:'messaging-route-hostname', transport:'tls', rejectUnauthorized:false});
var container = require('rhea');
var WebSocket = require('ws');
container.on('connection_open', function (context) {
context.connection.open_receiver('myqueue');
context.connection.open_sender('myqueue');
});
container.on('message', function (context) {
console.log(context.message.body);
context.connection.close();
});
container.on('sendable', function (context) {
context.sender.send({body:'Hello World!'});
context.sender.detach();
});
var ws = container.websocket_connect(WebSocket);
container.connect({username: 'username', password: 'password', connection_details: ws("wss://messaging-route-hostname:443", ["binary"], {rejectUnauthorized: false})});
The C++ client has equivalent simple_recv
and simple_send
examples with the same options as Python. However, the C++ library does not perform the same level of processing on the URL; in particular it will not accept amqps://
to imply using TLS, so the example needs to be modified as follows:
#include <proton/connection.hpp>
#include <proton/container.hpp>
#include <proton/default_container.hpp>
#include <proton/delivery.hpp>
#include <proton/message.hpp>
#include <proton/messaging_handler.hpp>
#include <proton/ssl.hpp>
#include <proton/thread_safe.hpp>
#include <proton/tracker.hpp>
#include <proton/url.hpp>
#include <iostream>
#include "fake_cpp11.hpp"
class hello_world : public proton::messaging_handler {
private:
proton::url url;
public:
hello_world(const std::string& u) : url(u) {}
void on_container_start(proton::container& c) OVERRIDE {
proton::connection_options co;
co.ssl_client_options(proton::ssl_client_options());
c.client_connection_options(co);
c.connect(url);
}
void on_connection_open(proton::connection& c) OVERRIDE {
c.open_receiver(url.path());
c.open_sender(url.path());
}
void on_sendable(proton::sender &s) OVERRIDE {
proton::message m("Hello World!");
s.send(m);
s.close();
}
void on_message(proton::delivery &d, proton::message &m) OVERRIDE {
std::cout << m.body() << std::endl;
d.connection().close();
}
};
int main(int argc, char **argv) {
try {
std::string url = argc > 1 ? argv[1] : "messaging-route-hostname:443/myqueue";
hello_world hw(url);
proton::default_container(hw).run();
return 0;
} catch (const std::exception& e) {
std::cerr << e.what() << std::endl;
}
return 1;
}
A known issue exists where creating a subscriber on a hierarchical topic in EnMasse causes the broker to instead create it as a competing consumer (handling the address like a queue rather than a topic).
The workaround involves setting the capability "topic"
in the source.
In the topic_receive.cpp
file, edit the code so that it is similar to what is shown in this example:
void on_container_start(proton::container& cont) override {
proton::connection conn = cont.connect(conn_url_);
proton::receiver_options opts {};
proton::source_options sopts {};
sopts.capabilities(std::vector<proton::symbol> { "topic" });
opts.source(sopts);
conn.open_receiver(address_, opts);
}
You can use the following AMQP.Net Lite example to connect your application to EnMasse. This example assumes you have created an address of type queue
named myqueue
.
using System;
using Amqp;
namespace Test
{
public class Program
{
public static void Main(string[] args)
{
String url = (args.Length > 0) ? args[0] : "amqps://messaging-route-hostname:443";
String address = (args.Length > 1) ? args[1] : "myqueue";
Connection.DisableServerCertValidation = true;
Connection connection = new Connection(new Address(url));
Session session = new Session(connection);
SenderLink sender = new SenderLink(session, "test-sender", address);
Message messageSent = new Message("Test Message");
sender.Send(messageSent);
ReceiverLink receiver = new ReceiverLink(session, "test-receiver", address);
Message messageReceived = receiver.Receive(TimeSpan.FromSeconds(2));
Console.WriteLine(messageReceived.Body);
receiver.Accept(messageReceived);
sender.Close();
receiver.Close();
session.Close();
connection.Close();
}
}
}
The IoT guide provides resources on how to set up and manage EnMasse IoT features.
The following information describes how to set up and manage EnMasse IoT features.
The Internet of Things (IoT) connectivity feature enables EnMasse to be used for managing and connecting devices with back-end applications. In a typical IoT application, devices have different requirements than ordinary messaging applications. Instead of using arbitrary addresses and security configurations that are typically available, developers can use the IoT services to handle device identities and security configurations explicitly, support multiple protocols often used in the IoT space, and provide uniform support for expected device communication patterns.
One of the key concepts is a device registry, which developers use to register devices and provide their credentials. With these credentials, devices can then connect to protocol adapters using one of the supported protocols: HTTP, MQTT, LoRaWAN, and SigFox. Once connected, devices can send and receive messages from back-end applications using one of the following messaging semantics:
Telemetry: Allows devices to send non-durable data to back-end applications, so messages are sent using the multicast
address type. This option is best for sending non-critical sensor readings.
Events: Allows devices to send durable data to the back-end applications, so messages are sent using the queue
address type. This option is best for sending more important device data such as alerts and notifications.
Back-end applications can also send Command messages to devices. Commands can be used to trigger actions on devices. Examples include updating a configuration property, installing a software component, or switching the state of an actuator.
The simplest way to install EnMasse is to use the predefined YAML bundles.
Create the namespace where you want to deploy EnMasse:
kubectl create namespace enmasse-infra kubectl config set-context $(kubectl config current-context) --namespace=enmasse-infra
Change the directory to the location of the downloaded release files.
Deploy using the enmasse
bundle:
kubectl apply -f install/bundles/enmasse
(Optional) Install the example plans and infrastructure configuration:
kubectl apply -f install/components/example-plans
(Optional) Install the example roles:
kubectl apply -f install/components/example-roles
(Optional) Install the standard
authentication service:
kubectl apply -f install/components/example-authservices/standard-authservice.yaml
To get started using the IoT feature on EnMasse, you must first install the IoT services.
(Optional) If you want to deploy to a project other than enmasse-infra
you must run the following command and substitute enmasse-infra
in subsequent steps:
sed -i 's/enmasse-infra/my-project/' install/preview-bundles/iot/*.yaml
Deploy the IoT bundles:
kubectl apply -f install/preview-bundles/iot
Create certificates for IoT services. For testing purposes, you can create a self-signed certificate:
./install/components/iot/examples/k8s-tls/create ./install/components/iot/examples/k8s-tls/deploy
You can override the namespace to which the deploy
script installs the keys and certificates by
setting the environment variable NAMESPACE
when calling the script. For example:
NAMESPACE=my-namespace ./install/components/iot/examples/k8s-tls/deploy
|
If your cluster is not running on CLUSTER=x.x.x.x.nip.io install/components/iot/examples/k8s-tls/create |
(Optional) Install the PostgreSQL server and create database:
kubectl apply -f install/components/iot/examples/postgresql/deploy
You may skip this step if you already have a PostgreSQL instance and created a database with a user to access to it.
Apply database schema:
You will need to execute the following SQL files on the database instance you created. Depenending on your setup, this may require database admin privileges:
install/components/iot/examples/postgresql/create.sql
install/components/iot/examples/postgresql/create.devcon.sql
You can execute the SQL file using the psql
command, connected to
your database. The following shows an example, how to execute psql
from inside the container, when you installed PostgreSQL as described
in the previous step:
kubectl exec -ti deployment/postgresql -- bash -c "PGPASSWORD=user12 psql device-registry registry" < install/components/iot/examples/postgresql/create.sql kubectl exec -ti deployment/postgresql -- bash -c "PGPASSWORD=user12 psql device-registry registry" < install/components/iot/examples/postgresql/create.devcon.sql
Install an example IoT infrastructure configuration:
kubectl apply -f install/components/iot/examples/iot-config-k8s.yaml
After installing the IoT services, you create an IoT project.
Create a managed IoT project:
kubectl create namespace myapp kubectl config set-context $(kubectl config current-context) --namespace=myapp kubectl create -f install/components/iot/examples/iot-project-managed.yaml
Wait for the resources to be ready:
kubectl get addressspace iot kubectl get iotproject iot
Make sure that the Phase field shows Ready status for both resources.
|
Create a messaging consumer user:
kubectl create -f install/components/iot/examples/iot-user.yaml
After installing the IoT services and creating an IoT project, you can create an IoT device for the device you want to monitor.
To create a new device, you must first register the device.
Export the device registry host:
export REGISTRY_HOST=$(kubectl -n enmasse-infra get service iot-device-registry-external -o jsonpath={.status.loadBalancer.ingress[0].hostname}):31443
Export the device registry access token:
export TOKEN=$(kubectl -n enmasse-infra describe secret $(kubectl -n enmasse-infra get secret | grep default-token | awk '{print $1}') | grep token: | awk '{print $2}')
This token is used to authenticate against the device registry management API.
Register a device with a defined ID (this example uses 4711
):
curl --insecure -X POST -i -H 'Content-Type: application/json' -H "Authorization: Bearer ${TOKEN}" https://$REGISTRY_HOST/v1/devices/myapp.iot/4711
(Optional) If you need to provide additional registration information, do so as follows:
curl --insecure -X POST -i -H 'Content-Type: application/json' -H "Authorization: Bearer ${TOKEN}" --data-binary '{ "via": ["gateway1"] }' https://$REGISTRY_HOST/v1/devices/myapp.iot/4711
After registering a new device, you must set the user name and password credentials for the device.
Add the credentials for a device:
curl --insecure -X PUT -i -H 'Content-Type: application/json' -H "Authorization: Bearer ${TOKEN}" --data-binary '[{ "type": "hashed-password", "auth-id": "sensor1", "secrets": [{ "pwd-plain":"'hono-secret'" }] }]' https://$REGISTRY_HOST/v1/credentials/myapp.iot/4711
Download the Eclipse Hono command-line client.
Obtain the messaging endpoint certificate:
kubectl -n myapp get addressspace iot -o jsonpath={.status.caCert} | base64 --decode > tls.crt
Export the messaging endpoint host and port:
export MESSAGING_HOST=$(kubectl get -n myapp addressspace iot -o jsonpath='{.status.endpointStatuses[?(@.name=="messaging")].externalHost}') export MESSAGING_PORT=443
|
If you are running Kubernetes in a development environment without a proper load balancer, you need to export the IP address of your local cluster and the port number of the appropriate service, for example: export MESSAGING_HOST=localhost export MESSAGING_PORT=5671 |
You can send telemetry data such as sensor readings, for example, from a device to the cloud. To do this, you must first start the telemetry consumer by running the customer application.
Run the customer application to receive telemetry:
java -jar hono-cli-*-exec.jar --hono.client.host=$MESSAGING_HOST --hono.client.port=$MESSAGING_PORT --hono.client.username=consumer --hono.client.password=foobar --tenant.id=myapp.iot --hono.client.trustStorePath=tls.crt --message.type=telemetry
You can send telemetry from a device to the cloud using the HTTP protocol.
Send telemetry using the HTTP protocol:
curl --insecure -X POST -i -u sensor1@myapp.iot:hono-secret -H 'Content-Type: application/json' --data-binary '{"temp": 5}' https://$(kubectl -n enmasse-infra get service iot-http-adapter-external -o jsonpath={.status.loadBalancer.ingress[0].hostname}):30443/telemetry
Service administrators typically install and configure the Internet of Things (IoT) services for EnMasse.
Deploying EnMasse monitoring also allows you to monitor the IoT-related components of EnMasse. No additional configuration is required.
For more information about EnMasse monitoring, see Monitoring EnMasse.
For detailed information about the available metrics specific to IoT, see IoT-specific metrics.
By default, the IoT components of EnMasse use a conservative logging configuration for the infrastructure services to preserve resources for normal operation.
EnMasse also allows operation-level tracing using Jaeger, for more in-depth tracing scenarios.
For IoT components, it might be necessary to increase the logging output at the following application levels, listed in order from lowest priority to highest priority:
A default log level for all IoT components
A default configuration for specific log channels
A service specific default log level
A service specific configuration for specific log channels
A service specific custom log configuration file
All configuration is part of the IoTConfig
instance and the EnMasse Operator applies the configuration to the services.
The only exception is the service specific
log configuration file, which can either be provided through the IoTConfig
resource
or by creating an entry in the service specific ConfigMap
resource.
The following log levels are available, listed in order from most severe to least severe:
Error conditions. Indicates an unexpected condition, which may impact the stability of the system. Displays only error messages.
Warning conditions. Indicates an expected condition, which may impact the current operation or stability of the system. Displays only warning and error messages.
Informational messages. Indicates an expected event, which may impact the current operation. Displays only informational, warning, and error messages.
Displays debug messages, in addition to all of the above.
Displays all messages.
EnMasse allows application-level tracing in the IoT infrastructure using Jaeger. This feature allows service administrators to gain insight into the inner workings of the IoT services to analyze system performance and issues.
By default, tracing support is not enabled and needs to be activated manually. For more information, see Configuring tracing.
For more information about Jaeger tracing, see: https://www.jaegertracing.io/.
The IoT components of EnMasse store all device related information in a service called "device registry". This makes the device registry an important component of the overall IoT functionality, so it might be necessary to tweak the configuration of the device registry.
|
Although the device registry storage backend can be configured in different ways, once the configuration has been made, and IoT tenants have been created, the storage configuration must not be change. Otherwise this may result in the loss of data, in data inconsistencies, or other kinds of unexpected behavior. |
The configuration of the device registry can be changed by editing the global IoTConfig
custom resource object. Any changes made to this custom resource, will be applied by the
EnMasse operator.
The database backed device registry, named "JDBC", can be configured to either use an existing, "external", database.
By default only PostgreSQL is supported. However it is possible to extend the installation, by providing custom JDBC drivers and custom SQL statements to the configuration. This allows to integrate with database, other than PostgreSQL.
To get started using the IoT feature on EnMasse, you must first install the IoT services.
(Optional) If you want to deploy to a project other than enmasse-infra
you must run the following command and substitute enmasse-infra
in subsequent steps:
sed -i 's/enmasse-infra/my-project/' install/preview-bundles/iot/*.yaml
Deploy the IoT bundles:
kubectl apply -f install/preview-bundles/iot
Create certificates for IoT services. For testing purposes, you can create a self-signed certificate:
./install/components/iot/examples/k8s-tls/create ./install/components/iot/examples/k8s-tls/deploy
You can override the namespace to which the deploy
script installs the keys and certificates by
setting the environment variable NAMESPACE
when calling the script. For example:
NAMESPACE=my-namespace ./install/components/iot/examples/k8s-tls/deploy
|
If your cluster is not running on CLUSTER=x.x.x.x.nip.io install/components/iot/examples/k8s-tls/create |
(Optional) Install the PostgreSQL server and create database:
kubectl apply -f install/components/iot/examples/postgresql/deploy
You may skip this step if you already have a PostgreSQL instance and created a database with a user to access to it.
Apply database schema:
You will need to execute the following SQL files on the database instance you created. Depenending on your setup, this may require database admin privileges:
install/components/iot/examples/postgresql/create.sql
install/components/iot/examples/postgresql/create.devcon.sql
You can execute the SQL file using the psql
command, connected to
your database. The following shows an example, how to execute psql
from inside the container, when you installed PostgreSQL as described
in the previous step:
kubectl exec -ti deployment/postgresql -- bash -c "PGPASSWORD=user12 psql device-registry registry" < install/components/iot/examples/postgresql/create.sql kubectl exec -ti deployment/postgresql -- bash -c "PGPASSWORD=user12 psql device-registry registry" < install/components/iot/examples/postgresql/create.devcon.sql
Install an example IoT infrastructure configuration:
kubectl apply -f install/components/iot/examples/iot-config-k8s.yaml
Using an external database requires you to create a database instance and create the required tables and indices.
|
Although it should technically be possible to use any database which provides a JDBC driver and support SQL, at the moment, only PostgreSQL is supported by EnMasse. Unless explicitly mentioned, this documentation will assume your are using PostgreSQL. If you do not, then you might need to adapter provided commands, and SQL statements. |
In order to set up a JDBC based device registry, you need to perform the following steps:
The JDBC based device registry supports the following data models:
Flat JSON
Hierarchical JSON
Plain tables
The JSON based data models require no locking or foreign keys. However they do rely on PostgreSQL support for JSONB. The flat JSON model is more flexible when it comes to storing different types of credentials. The hierarchical JSON model has better performance over the flat JSON model, but requires dedicated indices for each credentials type in order to achieve this performance.
The plain table model does not require any JSON specific database support, but require multiple tables, linked with foreign keys, and will need support for locking when making changes. On the other side it will have better read performance in most cases.
The default choice is the hierarchical JSON model.
| It is not possible to change the data model later on without loosing all data or manual data migration. |
First you need to create a database instance. It is recommended that you also create at least two types of users. One for administrating the database and one for accessing the device registry specific tables. In the following sections the former user is assumed to be named "admin", and the latter "registry".
Created a database instance
Have access credentials for the "admin" database user
Connect to your database instance using the admin user
Review and deploy the SQL schema templates/iot/examples/postgresql/create.sql
In order to enable the external JDBC device registry implementation, you will
need to configure the section .spec.services.deviceRegistry.jdbc.server.external
,
and provide the chosen data model, database connection information and access credentials.
For an example see Configuration for JDBC with external PostgreSQL.
If the default logging settings are not sufficient, the following sections describe different methods for configuring the logging system.
The global logging configuration is applied to all services that do not have any explicit logging configuration.
By default, the global log level is info
.
Edit the IoTConfig
instance named default
:
kubectl edit iotconfig default
Configure the logging options, save and exit the editor:
apiVersion: iot.enmasse.io/v1alpha1
kind: IoTConfig
metadata:
namespace: enmasse-infra
name: default
spec:
logging:
level: info (1)
loggers: (2)
io.enmasse: debug (3)
io.netty: error (4)
| 1 | The default global log level. If omitted, info is used. |
| 2 | The section for log channel specific entries. |
| 3 | Lowers the filtering to debug level for messages in the channel io.enmasse . |
| 4 | Raises the filtering to error level for messages in the channel io.netty . |
The operator applies the logging configuration and re-deploys all required components.
In the example above:
An info
message for the logger org.eclipse.hono
would be logged because the logger does not match any explicit configuration and the global default is info
.
An info
message for the logger io.enmasse
would be logged because the configuration for io.enmasse
is debug
and the info
message is of higher severity.
A warn
message for the logger io.netty
would be dropped
because the configuration for io.netty
is set to only display error
messages.
To override the global defaults, you can configure logging specifically for an IoT service.
Edit the IoTConfig
instance named default
:
kubectl edit iotconfig default
Configure the logging options, save and exit the editor:
apiVersion: iot.enmasse.io/v1alpha1
kind: IoTConfig
metadata:
namespace: enmasse-infra
name: default
spec:
adapters:
mqtt:
containers:
adapter:
logback:
level: info (1)
loggers: (2)
io.enmasse: debug (3)
io.netty: error (4)
| 1 | The application global log level. If omitted, the default global level is used. |
| 2 | The section for log channel specific entries. If omitted and the application global log level is also omitted, the default log channel configuration of the infrastructure is used. If the application global log level is set, it is considered an empty set, and no log channel specific configuration is applied. |
| 3 | Lowers the filtering to debug level for messages in the channel io.enmasse . |
| 4 | Raises the filtering to error level for messages in the channel io.netty . |
The operator applies the logging configuration and re-deploys all required components.
For containers running applications using the Logback logging implementation, it is possible to provide a custom, XML-based, logback configuration file. This will override any other logging configuration in the system.
| The logging configuration is not checked by EnMasse. Providing an incorrect configuration may result in the loss of performance, stability, or may lead to a total system failure. |
For more information about configuring Logback, see http://logback.qos.ch/manual/configuration.html.
Create the content of an XML-based logback configuration file.
IoTConfig
resourceYou can apply the configuration using the IoTConfig
resource.
Edit the IoTConfig
instance named default
:
kubectl edit iotconfig default
Configure the logging options, save and exit the editor:
apiVersion: iot.enmasse.io/v1alpha1
kind: IoTConfig
metadata:
namespace: enmasse-infra
name: default
spec:
adapters:
mqtt:
containers:
adapter:
logback:
logback: | (1)
<configuration>
<appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
<encoder>
<pattern>%d{HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n</pattern>
</encoder>
</appender>
<root level="debug">
<appender-ref ref="STDOUT" />
</root>
</configuration>
| 1 | The full XML-based logback configuration. |
The operator applies the logging configuration and re-deploys all required components.
ConfigMap
resourceIn addition to providing the custom configuration using the
IoTConfig
, it is possible to put the custom logging
configuration into the service’s ConfigMap
source.
Edit the ConfigMap
instance for the service. For example, iot-http-adapter-config
for the HTTP protocol adapter.
kubectl edit cm iot-http-adapter-config
Add the XML-based logback configuration in the data section with the key logback-custom.xml
:
apiVersion: v1
kind: ConfigMap
metadata:
namespace: enmasse-infra
name: iot-http-adapter-config
data:
application.yaml: … (1)
logback-spring.xml: … (2)
logback-custom.xml: | (3)
<configuration>
<appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
<encoder>
<pattern>%d{HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n</pattern>
</encoder>
</appender>
<root level="debug">
<appender-ref ref="STDOUT" />
</root>
</configuration>
| 1 | The application specific configuration file. The operator generates this file and overwrites any changes. |
| 2 | The effective logback configuration, applied by the system. Do not change this, as it will be overwritten by the operator. |
| 3 | The full XML-based logback configuration. |
The operator detects changes on the ConfigMap
resource, applies
the logging configuration and re-deploys all required components.
The "Jaeger Operator" from OperatorHub is installed in the EnMasse namespace.
An instance of Jaeger is deployed using the operator in the EnMasse namespace.
Know whether the Jaeger instance was deployed using the "sidecar" or "daemonset" agent.
Edit the IoTConfig
instance named default
:
kubectl edit iotconfig default
Modify the configuration according to your Jaeger agent configuration:
If the Jaeger instance is deployed with the "sidecar" agent, add the following configuration:
apiVersion: iot.enmasse.io/v1alpha1
kind: IoTConfig
metadata:
namespace: enmasse-infra
name: default
spec:
tracing:
strategy: (1)
sidecar: {} (2)
| 1 | The field to select the strategy. Only one strategy must be configured. |
| 2 | Enables the "sidecar" strategy. The use of an empty empty object ({} ) is intentional. |
If the Jaeger instance is deployed with the "daemonset" agent, add the following configuration:
apiVersion: iot.enmasse.io/v1alpha1
kind: IoTConfig
metadata:
namespace: enmasse-infra
name: default
spec:
tracing:
strategy: (1)
daemonset: {} (2)
| 1 | The field to select the strategy. Only one strategy must be configured. |
| 2 | Enables the "daemonset" strategy. The use of an empty empty object ({} ) is intentional. |
Save and exit the editor.
The operator applies the tracing configuration and re-deploys all required components.
This IoT configuration example shows only the required options to create an iotConfig
.
kind: IoTConfig
apiVersion: iot.enmasse.io/v1alpha1
metadata:
name: default
spec:
services:
deviceRegistry:
infinispan:
server:
external: (1)
host: infinispan
port: 11222
username: app
password: test12
saslServerName: hotrod
saslRealm: ApplicationRealm
adapters:
mqtt:
endpoint:
secretNameStrategy:
secretName: iot-mqtt-adapter-tls
| 1 | The Infinispan service must be provided. |
This IoT configuration example shows how the protocol adapters can be individually tuned.
kind: IoTConfig
apiVersion: iot.enmasse.io/v1alpha1
metadata:
name: default
spec:
services:
deviceRegistry:
infinispan:
server:
external:
host: infinispan
port: 11222
username: app
password: test12
saslServerName: hotrod
saslRealm: ApplicationRealm
adapters:
mqtt:
enabled: true (1)
replicas: 1
options:
tenantIdleTimeout: 30m (2)
maxPayloadSize: 2048
http:
enabled: true
replicas: 1 (4)
options:
tenantIdleTimeout: 30m
maxPayloadSize: 2048 (3)
containers:
adapter:
resources: (4)
limits:
memory: 128Mi
cpu: 500m
lorawan:
enabled: false
sigfox:
enabled: false
| 1 | Protocol adapters can be disabled if necessary. The default value is true . |
| 2 | Specifies the duration to keep alive the client connection. |
| 3 | Specifies the maximum allowed size of an incoming message in bytes. |
| 4 | Container resources and instances can be adjusted if necessary. |
kind: IoTConfig
apiVersion: iot.enmasse.io/v1alpha1
metadata:
name: default
spec:
services:
deviceRegistry:
jdbc:
server:
external:
url: jdbc://postgresql.namespace.svc:5432/database-name (1)
username: app (2)
password: test12 (3)
| 1 | The JDBC URL to the PostgreSQL database. This includes the hostname, port, and database name. For more information also see: https://jdbc.postgresql.org/documentation/head/connect.html |
| 2 | The username used to connect to the PostgreSQL server |
| 3 | The password used to connect to the PostgreSQL server |
The IoT-specific components of EnMasse provide the metrics described in this section.
The following tags are available on all IoT-related components:
| Tag | Value | Description |
|---|---|---|
host |
string |
Specifies the name of the host that the component reporting the metric is running on. |
component-type |
|
Specifies the type of component reporting the metric. |
component-name |
string |
The name of the component reporting the metric. For a list of components, see the following table. |
| Component | component-name |
|---|---|
HTTP protocol adapter |
|
MQTT protocol adapter |
|
LoRaWAN protocol adapter |
|
Sigfox protocol adapter |
|
Protocol adapters, components of type adapter
, have some additional tags.
.Protocol adapter tags
| Name | Value | Description |
|---|---|---|
direction |
|
Specifies the direction in
which a Command & Control message is being sent: |
qos |
|
Indicates the quality of service used for a
telemetry or event message: |
status |
|
Indicates the
processing status of a message. |
tenant |
string |
Specifies the identifier of the tenant that the metric is being reported on. |
ttd |
|
Indicates the status of the
outcome of processing a TTD value contained in a message received from a
device. |
type |
|
Indicates the type of (downstream) message for the metric. |
| Metric | Type | Tags | Description |
|---|---|---|---|
hono.commands.received |
Timer |
host, component-type, component-name, tenant, type, status, direction |
Indicates the amount of time it took to process a message conveying a command or a response to a command. |
hono.commands.payload |
DistributionSummary |
host, component-type, component-name, tenant, type, status, direction |
Indicates the number of bytes conveyed in the payload of a command message. |
hono.connections.authenticated |
Gauge |
host, component-type, component-name, tenant |
Current number of connected, authenticated devices. NOTE: This metric is only supported by protocol adapters that maintain a connection state with authenticated devices. In particular, the HTTP adapter does not support this metric. |
hono.connections.unauthenticated |
Gauge |
host, component-type, component-name |
Current number of connected, unauthenticated devices. NOTE: This metric is only supported by protocol adapters that maintain a connection state with authenticated devices. In particular, the HTTP adapter does not support this metric. |
hono.messages.received |
Timer |
host, component-type, component-name, tenant, type, status, qos, ttd |
Indicates the amount of time it took to process a message conveying a telemetry or event message. |
hono.messages.payload |
DistributionSummary |
host, component-type, component-name, tenant, type, status |
Indicates the number of bytes conveyed in the payload of a telemetry or event message. |
IoTProject
stuck in terminationWhen an IoTProject
instance is deleted, the resource will not be deleted immediately.
It is only marked for deletion and necessary cleanup operations will be performed in the background.
The resource will automatically be deleted once the cleanup has been performed successfully.
In some situations it might be that, due do to infrastructure issues, the clean-up operation
cannot be performed at this point in time. The IoTProject
will still be kept, and the
operator will re-try periodically to clean up the resources. The cleanup will succeed once
the infrastructure is back in operational state.
In the case that the infrastructure is not expected to function ever again, it might be desirable
to force the destruction of the IoTProject
resources.
| Manually removing the resource cleanup finalizer will skip the cleanup process, and prevent the system from properly cleaning up. |
Evaluate if the project is stuck in the termination state using the kubectl
tool:
kubectl get iotproject iot -n myapp NAME IOT TENANT DOWNSTREAM HOST DOWNSTREAM PORT TLS PHASE iot myapp.iot messaging-be482a6.enmasse-infra.svc 5671 true Terminating
The output should show the project in the state "Terminating". In addition, verify that the cleanup finalizer is still present:
kubectl get iotproject iot -n myapp -ojsonpath='{range .metadata.finalizers[*]}{..}{"\n"}{end}' iot.enmasse.io/deviceRegistryCleanup
If the list contains an entry of iot.enmasse.io/deviceRegistryCleanup
, then resource cleanup process
is still pending.
Manually remove the finalizer iot.enmasse.io/deviceRegistryCleanup
from the list of finalizers:
kubectl edit iotproject iot -n myapp
This will open up a text editor with the content of the resource:
apiVersion: iot.enmasse.io/v1alpha1
kind: IoTProject
metadata:
creationTimestamp: "2019-12-09T15:00:00Z"
deletionTimestamp: "2019-12-09T16:00:00Z"
finalizers:
- iot.enmasse.io/deviceRegistryCleanup (1)
name: iot
namespace: myapp
| 1 | The line with the finalizer to delete |
Delete the line of the finalizer. Save and exit the editor. This will automatically trigger an update
on the server, and the system will continue deleting the IoTProject
resource.
After the finalizer has been removed, the resource should be deleted and disappear from the system.
IoT projects define the messaging resources an IoT tenant can consume.
This IoT project configuration example relies on EnMasse to manage the messaging infrastructure used by IoT traffic.
The EnMasse standard
address space and address plans are used.
kind: IoTProject
apiVersion: iot.enmasse.io/v1alpha1
metadata:
name: user-1
spec:
downstreamStrategy:
managedStrategy: (1)
addressSpace:
name: iot-user-1
plan: standard-unlimited (2)
type: standard (4)
addresses:
telemetry:
plan: standard-small-anycast (3)
type: standard (5)
event:
plan: standard-small-queue (3)
command:
plan: standard-small-anycast (3)
| 1 | The managedStrategy value refers to a messaging infrastructure managed by EnMasse. |
| 2 | Specifies the address space plan, defining the resource usage of the address space. Each IoT tenant must have its own address space. |
| 3 | Each address must be associated with a valid address plan. |
| 4 | Specifies the type of address space. The default value is standard .
For more information, see Managing address spaces. |
| 5 | Specifies the type of address.
For more information, see Managing address spaces. |
This IoT configuration example shows how an external messaging infrastructure can be configured.
kind: IoTProject
apiVersion: iot.enmasse.io/v1alpha1
metadata:
name: user-1
spec:
downstreamStrategy:
externalStrategy:
host: messaging-hono-default.enmasse-infra.svc
port: 5672
username: http
tls: true
password: http-secret
Device managers are typically responsible for creating and managing device identities and credentials in the system.
To access the device management API, you must obtain a token to authenticate yourself to the API.
Access to an IoT tenant’s devices is mapped by the device registry based on access to
the IoTProject
resource. If an account has read access to the IoTProject
, this
account can also execute read operations on the device registry for this IoT tenant.
The token has to be presented to the API as a bearer token by adding
an HTTP header value: Authorization: Bearer <token>
. For more information,
see RFC 6750.
In the following configuration examples, replace ${TOKEN}
with the actual token.
If you want to use the token of the current Kubernetes, you can extract the token.
You must be logged in to your Kubernetes instance as a user that supports tokens.
Extract the token for the current user:
kubectl config view -o json| jq -r '.users[] as $users | ."current-context" as $ctx | .contexts[] | select (.name==$ctx).context.user as $user | $users | select (.name==$user).user.token'
| User tokens have a limited lifetime, so it may be necessary to renew the token after it has expired. |
Perform the following steps to create a new service account and extract the token.
You must be logged in to your Kubernetes instance with permissions to create new service accounts, roles and role bindings.
Create a new service account:
apiVersion: v1
kind: ServiceAccount
metadata:
name: my-device-manager-account (1)
| 1 | The name of the service account. |
Create a new role, allowing access to the IoTProject
:
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
name: device-manager-role (1)
rules: (2)
- apiGroups: ["iot.enmasse.io"]
resources: ["iotprojects"]
verbs: ["create", "update", "get", "list", "delete"]
| 1 | The name of the role. |
| 2 | The access rules, which must grant CRUD access to the IoTProject . |
This example grants access to all IoTProjects
in a namespace.
To further restrict access, use more specific rules.
Create a new role binding, assigning the role to the service account:
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
name: my-device-manager-account-role-binding
roleRef:
apiGroup: rbac.authorization.k8s.io
kind: Role
name: device-manager-role (1)
subjects:
- kind: ServiceAccount
name: my-device-manager-account (2)
| 1 | The name of the role. |
| 2 | The name of the service account. |
Retrieve the token from the service account:
kubectl get secret $(kubectl get sa my-device-manager-account -o json | jq -r '.secrets[] | select(.name | contains("-token-")).name') -o json | jq -r .data.token
After installing the IoT services and creating an IoT project, you can create an IoT device for the device you want to monitor.
To create a new device, you must first register the device.
Export the device registry host:
export REGISTRY_HOST=$(kubectl -n enmasse-infra get service iot-device-registry-external -o jsonpath={.status.loadBalancer.ingress[0].hostname}):31443
Export the device registry access token:
export TOKEN=$(kubectl -n enmasse-infra describe secret $(kubectl -n enmasse-infra get secret | grep default-token | awk '{print $1}') | grep token: | awk '{print $2}')
This token is used to authenticate against the device registry management API.
Register a device with a defined ID (this example uses 4711
):
curl --insecure -X POST -i -H 'Content-Type: application/json' -H "Authorization: Bearer ${TOKEN}" https://$REGISTRY_HOST/v1/devices/myapp.iot/4711
(Optional) If you need to provide additional registration information, do so as follows:
curl --insecure -X POST -i -H 'Content-Type: application/json' -H "Authorization: Bearer ${TOKEN}" --data-binary '{ "via": ["gateway1"] }' https://$REGISTRY_HOST/v1/devices/myapp.iot/4711
After registering a new device, you must set the user name and password credentials for the device.
Add the credentials for a device:
curl --insecure -X PUT -i -H 'Content-Type: application/json' -H "Authorization: Bearer ${TOKEN}" --data-binary '[{ "type": "hashed-password", "auth-id": "sensor1", "secrets": [{ "pwd-plain":"'hono-secret'" }] }]' https://$REGISTRY_HOST/v1/credentials/myapp.iot/4711
IoT solution developers are typically responsible for writing IoT cloud applications.
Download the Eclipse Hono command-line client.
Obtain the messaging endpoint certificate:
kubectl -n myapp get addressspace iot -o jsonpath={.status.caCert} | base64 --decode > tls.crt
Export the messaging endpoint host and port:
export MESSAGING_HOST=$(kubectl get -n myapp addressspace iot -o jsonpath='{.status.endpointStatuses[?(@.name=="messaging")].externalHost}') export MESSAGING_PORT=443
|
If you are running Kubernetes in a development environment without a proper load balancer, you need to export the IP address of your local cluster and the port number of the appropriate service, for example: export MESSAGING_HOST=localhost export MESSAGING_PORT=5671 |
You can send telemetry data such as sensor readings, for example, from a device to the cloud. To do this, you must first start the telemetry consumer by running the customer application.
Run the customer application to receive telemetry:
java -jar hono-cli-*-exec.jar --hono.client.host=$MESSAGING_HOST --hono.client.port=$MESSAGING_PORT --hono.client.username=consumer --hono.client.password=foobar --tenant.id=myapp.iot --hono.client.trustStorePath=tls.crt --message.type=telemetry
You can send events, such as alerts and other important data, from a device to a consumer application. To do this, you must first start the events consumer by running the customer application.
Run the customer application to receive events:
java -jar hono-cli-*-exec.jar --hono.client.host=$MESSAGING_HOST --hono.client.port=$MESSAGING_PORT --hono.client.username=consumer --hono.client.password=foobar --tenant.id=myapp.iot --hono.client.trustStorePath=tls.crt --message.type=events
You can send commands from a cloud to the device. To do this, you must start the command sender by running the customer application.
Run the customer application to send commands to a device with an ID of 4711
:
java -jar hono-cli-*-exec.jar --hono.client.host=$MESSAGING_HOST --hono.client.port=$MESSAGING_PORT --hono.client.username=consumer --hono.client.password=foobar --tenant.id=myapp.iot --hono.client.trustStorePath=tls.crt --device.id=4711 --spring.profiles.active=command
Follow the instructions for entering the command’s name, payload, and content type. For example:
>>>>>>>>> Enter name of command for device [4711] in tenant [myapp.iot] (prefix with 'ow:' to send one-way command): ow:setVolume >>>>>>>>> Enter command payload: {"level": 50} >>>>>>>>> Enter content type: application/json INFO org.eclipse.hono.cli.app.Commander - Command sent to device
Device developers are typically responsible for either connecting existing devices to the cloud platform or writing software for devices. This information describes how to connect devices using one of the supported protocols.
You can send telemetry from a device to the cloud using the HTTP protocol.
Send telemetry using the HTTP protocol:
curl --insecure -X POST -i -u sensor1@myapp.iot:hono-secret -H 'Content-Type: application/json' --data-binary '{"temp": 5}' https://$(kubectl -n enmasse-infra get service iot-http-adapter-external -o jsonpath={.status.loadBalancer.ingress[0].hostname}):30443/telemetry
You can send an event message from the customer application to the device using the HTTP protocol.
Send events using the HTTP protocol:
curl --insecure -X POST -i -u sensor1@myapp.iot:hono-secret -H 'Content-Type: application/json' --data-binary '{"temp": 5}' https://$(kubectl -n enmasse-infra get service iot-http-adapter-external -o jsonpath={.status.loadBalancer.ingress[0].hostname}):30443/events
You can send commands from the cloud to a device using the HTTP protocol.
Send a telemetry message using the HTTP protocol, specifying the hono-ttd
parameter indicating how long the client will wait for the command:
curl --insecure -X POST -i -u sensor1@myapp.iot:hono-secret -H 'Content-Type: application/json' --data-binary '{"temp": 5}' https://$(kubectl -n enmasse-infra get service iot-http-adapter-external -o jsonpath={.status.loadBalancer.ingress[0].hostname}):30443/telemetry?hono-ttd=600
Run the customer application to send commands to a device with an ID of 4711
:
java -jar hono-cli-*-exec.jar --hono.client.host=$MESSAGING_HOST --hono.client.port=$MESSAGING_PORT --hono.client.username=consumer --hono.client.password=foobar --tenant.id=myapp.iot --hono.client.trustStorePath=tls.crt --device.id=4711 --spring.profiles.active=command
Follow the instructions for entering the command’s name, payload, and content type. For example:
>>>>>>>>> Enter name of command for device [4711] in tenant [myapp.iot] (prefix with 'ow:' to send one-way command): ow:setVolume >>>>>>>>> Enter command payload: {"level": 50} >>>>>>>>> Enter content type: application/json INFO org.eclipse.hono.cli.app.Commander - Command sent to device
The client receives the command in the HTTP response:
HTTP/1.1 200 OK hono-command: setVolume content-type: application/json content-length: 13 {"level": 50}
You can send telemetry from a device to the cloud using the MQTT protocol.
Send telemetry using the MQTT protocol:
mosquitto_pub -d -h $(kubectl -n enmasse-infra get service iot-mqtt-adapter-external -o jsonpath={.status.loadBalancer.ingress[0].hostname}) -p 30883 -u<EMAIL_ADDRESS>-P hono-secret -t telemetry -m '{"temp": 5}' -i 4711 --cafile install/components/iot/examples/k8s-tls/build/iot-mqtt-adapter-fullchain.pem
You can send an event message from the customer application to the device using the MQTT protocol.
Send events using the MQTT protocol:
mosquitto_pub -d -h $(kubectl -n enmasse-infra get service iot-mqtt-adapter-external -o jsonpath={.status.loadBalancer.ingress[0].hostname}) -p 30883 -u<EMAIL_ADDRESS>-P hono-secret -t events -m '{"temp": 5}' -i 4711 --cafile install/components/iot/examples/k8s-tls/build/iot-mqtt-adapter-fullchain.pem
You can send commands from the cloud to a device using the MQTT protocol.
Use the MQTT client to subscribe to the MQTT topic for receiving commands:
mosquitto_sub -v -d -h $(kubectl -n enmasse-infra get service iot-mqtt-adapter-external -o jsonpath={.status.loadBalancer.ingress[0].hostname}) -p 443 -u<EMAIL_ADDRESS>-P hono-secret -t command/+/+/req/# -i 4711 --cafile install/components/iot/examples/k8s-tls/build/iot-mqtt-adapter-fullchain.pem
Run the customer application to send commands to a device with an ID of 4711
:
java -jar hono-cli-*-exec.jar --hono.client.host=$MESSAGING_HOST --hono.client.port=$MESSAGING_PORT --hono.client.username=consumer --hono.client.password=foobar --tenant.id=myapp.iot --hono.client.trustStorePath=tls.crt --device.id=4711 --spring.profiles.active=command
Follow the instructions for entering the command’s name, payload, and content type. For example:
>>>>>>>>> Enter name of command for device [4711] in tenant [myapp.iot] (prefix with 'ow:' to send one-way command): ow:setVolume >>>>>>>>> Enter command payload: {"level": 50} >>>>>>>>> Enter content type: application/json INFO org.eclipse.hono.cli.app.Commander - Command sent to device
The client receives the command in the MQTT message:
Client 4711 received PUBLISH (d0, q0, r0, m0, 'command///req//setVolume', ... (13 bytes)) command///req//setVolume {"level": 50}
After installing the IoT services and creating an IoT project, you can configure the Sigfox backend integration.
TLS is properly deployed in your cluster. The Sigfox protocol adapter endpoint must be properly validated with TLS.
An account at https://backend.sigfox.com must be set up and your Sigfox devices registered.
Familiarity with the Sigfox backend. After you are logged in to the Sigfox backend, for more information see the Sigfox documentation.
The Sigfox backend is set up in EnMasse as a gateway device.
The credentials assigned to this device are required for the configuration of the "callback" in the Sigfox backend.
The actual devices are configured to use this gateway device as their transport.
In step 3 of this procedure, specify sigfox-backend
as the ID.
Set up password credentials for this device (for example, sigfox-user
/ sigfox-password
).
Locate the device ID for the Sigfox device you want to register. You obtain this ID as part of the registration process in the Sigfox backend.
Specify the device ID as the name (for example, 1AB2C3
) and specify the name of the gateway device in the via
field,
as part of the registration information (for example, {"via": ["sigfox-backend"]}
).
| Do not set a password for this device. |
Prepare the following connection information, which is used in the Creating a new callback in the Sigfox backend procedure.
The name of the IoT tenant consists of the Kubernetes namespace and the name
of the IoT project resource, for example, namespace.iotproject
.
For the Sigfox backend to authenticate, you must convert the username and password combination of the gateway device into an HTTP "Basic Authorization" header. Be sure to specify the full user name using the following syntax: authentication id @IoT tenant name
.
Example<EMAIL_ADDRESS>The basic authentication header value can be generated on the command line using the following command:
echo "Basic $(echo -n "sigfox-user@namespace.iotproject:password" | base64)"
The URL pattern consists of the URL to the Sigfox protocol adapter and Sigfox-specific query parameters:
https://<ADAPTER URL>/data/telemetry/<TENANT>?device={device}&data={data}
Run the following command to obtain the URL of the protocol adapter:
echo "https://$(kubectl -n enmasse-infra get service iot-sigfox-adapter-external -o jsonpath={.status.loadBalancer.ingress[0].hostname}):31443"
The path segment /data/telemetry
indicates to the protocol adapter
to handle messages as telemetry data. You can use /data/event
to instead process messages as events.
{device} and {data} are literal values and must not be replaced.
|
Log in to https://backend.sigfox.com.
In the Device Type
open a type for editing and switch to the Callbacks
section.
Create a new "Custom" callback, with the following settings:
DATA
– UPLINK
URL
The URL pattern. For example, https://iot-sigfox-adapter.my.cluster/data/telemetry/<TENANT>?device={device}&data={data}
GET
Authorization
– Basic…
☑ (Enabled)
Log in to https://backend.sigfox.com.
In the Device Type
open the type for editing and switch to the Callbacks
section.
Edit the callback configuration for which you want to enable command and control.
Switch to DATA
– BIDIR
Add the ack
parameter. For example, https://iot-sigfox-adapter.my.cluster/data/telemetry/<TENANT>?device={device}&data={data}&ack={ack}
The following troubleshooting information provides solutions to common problems when running EnMasse. Certain steps in the procedures might require service administrator privileges.
Retrieve the uuid for the address space:
kubectl get addressspace myspace -o jsonpath='{.metadata.annotations.enmasse\.io/infra-uuid}'
Find all pods with a matching infraUuid
label:
kubectl get pods -l infraUuid=uuid
Determine the enmasse-operator
pod name:
kubectl get pods | grep enmasse-operator
Print the VERSION
environment of the enmasse-operator
pod:
kubectl rsh enmasse-operator-.... env | grep VERSION
The VERSION
corresponds to the major.minor version of EnMasse, whereas MAVEN_VERSION
corresponds to the build number.
Ensure that the address space plan was created in the namespace where EnMasse is installed.
Ensure that the address space plan has passed validation and is in the Active
phase:
kubectl get addressspaceplans -o wide -n enmasse-infra
Ensure that the address plan was created in the namespace where EnMasse is installed.
Ensure that the address plan has passed validation and is in the Active
phase:
kubectl get addressplans -o wide -n enmasse-infra
Check the address space status message for errors:
kubectl get addressspace myspace -o wide
Check address space controller logs for errors:
kubectl logs deployment/address-space-controller
Check the address status message for errors:
kubectl get address myspace.myaddress -o wide
If using the brokered
address space, check the agent
pod logs for errors:
kubectl logs deployment/agent.uuid
If using the standard
address space, check the admin
pod logs for errors:
kubectl logs deployment/admin.uuid -c standard-controller kubectl logs deployment/admin.uuid -c agent
The following table describes the EnMasse resources that pertain to the service administrator role.
| Resource | Description |
|---|---|
|
Specifies the address plan. |
|
Specifies the address space plan. |
|
Defines the service characteristics available to an |
|
Specifies the infrastructure configuration for brokered address spaces. For more information see Brokered infrastructure configuration fields table. |
|
Specifies the infrastructure configuration for standard address spaces. For more information see Standard infrastructure configuration fields table. |
The following table describes the EnMasse resources that pertain to the messaging tenant role.
| Resource | Description |
|---|---|
|
Specifies the address. |
|
Specifies the address space. |
|
Specifies the authorization policy that controls which addresses may be used and the operations that may be performed on those addresses. |
This table shows the fields available for the brokered infrastructure configuration and a brief description.
Field |
Description |
|
Specifies the EnMasse version used. When upgrading, EnMasse uses this field to determine whether to upgrade the infrastructure to the requested version. |
|
Specifies the amount of memory allocated to the admin Pod. |
|
Specifies the labels added to the admin Pod. |
|
Specifies the affinity settings for the admin Pod so you can specify where on particular nodes a Pod runs, or if it cannot run together with other instances. |
|
Specifies the priority class to use for the admin Pod so you can prioritize admin Pods over other Pods in the Kubernetes cluster. |
|
Specifies the toleration settings for the admin Pod, which allows this Pod to run on certain nodes that other Pods cannot run on. |
|
Specifies the action taken when a queue is full: |
|
Specifies the maximum amount of memory used for queues in the broker. |
|
Specifies the amount of memory allocated to the broker. |
|
Specifies the amount of storage requested for the broker. |
|
Specifies the labels added to the broker Pod. |
|
Specifies the affinity settings for the broker Pod so you can specify where on particular nodes a Pod runs, or if it cannot run together with other instances. |
|
Specifies the priority class to use for the broker Pod so you can prioritize broker Pods over other Pods in the Kubernetes cluster. |
|
Specifies the toleration settings for the broker Pod, which allows this Pod to run on certain nodes that other Pods cannot run on. |
|
Specifies the security context for the broker Pod. |
|
Specifies environment variables for the broker Pod. |
|
Specifies the number of times that Kubernetes tries when a broker Pod starts and the probe fails before restarting the container. |
|
Specifies the probe delay value in seconds for the broker Pod. |
|
Specifies the probe timeout value in seconds for the broker Pod. |
|
Specifies the number of times that Kubernetes tries when a broker Pod starts and the probe fails before the Pod is marked |
|
Specifies the probe delay value in seconds for the broker Pod. |
|
Specifies the probe timeout value in seconds for the broker Pod. |
|
Specifies broker Pod resource requests and limits for CPU and memory. |
|
Specifies what storage class to use for the persistent volume for the broker. |
|
If the persistent volume supports resizing, setting this value to |
This table shows the fields available for the standard infrastructure configuration and a brief description.
Field |
Description |
|
Specifies the EnMasse version used. When upgrading, EnMasse uses this field to determine whether to upgrade the infrastructure to the requested version. |
|
Specifies the amount of memory allocated to the admin Pod. |
|
Specifies the labels added to the admin Pod. |
|
Specifies the affinity settings for the admin Pod so you can specify where on particular nodes a Pod runs, or if it cannot run together with other instances. |
|
Specifies the priority class to use for the admin Pod so you can prioritize admin pods over other Pods in the Kubernetes cluster. |
|
Specifies the toleration settings for the admin Pod, which allow this Pod to run on certain nodes on which other Pods cannot run. |
|
Specifies the action taken when a queue is full: |
|
Specifies the maximum amount of memory used for queues in the broker. |
|
Specifies the amount of memory allocated to the broker. |
|
Specifies the amount of storage requested for the broker. |
|
Specifies the labels added to the broker Pod. |
|
Specifies the affinity settings for the broker Pod so you can specify where on particular nodes a Pod runs, or if it cannot run together with other instances. |
|
Specifies the priority class to use for the broker Pod so you can prioritize broker Pods over other Pods in the Kubernetes cluster. |
|
Specifies the toleration settings for the broker Pod, which allow this Pod to run on certain nodes on which other Pods cannot run. |
|
Specifies the security context for the broker Pod. |
|
Specifies environment variables for the broker Pod. |
|
Specifies the number of times that Kubernetes tries when a broker Pod starts and the probe fails before restarting the container. |
|
Specifies the probe delay value in seconds for the broker Pod. |
|
Specifies the probe timeout value in seconds for the broker Pod. |
|
Specifies the number of times that Kubernetes tries when a broker Pod starts and the probe fails before the Pod is marked |
|
Specifies the probe delay value in seconds for the broker Pod. |
|
Specifies the probe timeout value in seconds for the broker Pod. |
|
Specifies broker Pod resource requests and limits for CPU and memory. |
|
Specifies the AMQP idle timeout to use for connection to router. |
|
Specifies the number of worker threads of the connection to the router. |
|
Specifies what storage class to use for the persistent volume for the broker. |
|
If the persistent volume supports resizing, setting this value to |
|
Specifies the amount of memory allocated to the router. |
|
Specifies the default number of credits issued on AMQP links for the router. |
|
Specifies the amount of time in seconds to wait for the secure handshake to be initiated. |
|
Specifies the minimum number of router Pods to run; a minimum of two are required for high availability (HA) configuration. |
|
Specifies the labels added to the router Pod. |
|
Specifies the affinity settings for the router Pod so you can specify where on particular nodes a pod runs, or if it cannot run together with other instances. |
|
Specifies the priority class to use for the router Pod so you can prioritize router pods over other pods in the Kubernetes cluster. |
|
Specifies the toleration settings for the router Pod, which allow this Pod to run on certain nodes on which other Pods cannot run. |
|
Specifies the security context for the router Pod. |
|
Specifies the environment variables for the router Pod. |
|
Specifies the number of times that Kubernetes tries when a router Pod starts and the probe fails before restarting the container. |
|
Specifies the probe delay value in seconds for the router Pod. |
|
Specifies the probe timeout value in seconds for the router Pod. |
|
Specifies the number of times that Kubernetes tries when a router Pod starts and the probe fails before the Pod is marked |
|
Specifies the probe delay value in seconds for the router Pod. |
|
Specifies the probe timeout value in seconds for the router Pod. |
|
Specifies router Pod resource requests and limits for CPU and memory. |
|
Specifies the AMQP idle timeout to use for all router listeners. |
|
Specifies the number of worker threads to use for the router. |
|
Specifies the maximum number of router connections allowed. |
|
Specifies the maximum number of router connections allowed per user. |
|
Specifies the maximum number of router connections allowed per host. |
|
Specifies the maximum number of sessions allowed per router connection. |
|
Specifies the maximum number of senders allowed per router connection. |
|
Specifies the maximum number of receivers allowed per router connection. |
This is the EnMasse API specification.
Version : 0.32
Schemes : HTTPS
addresses : Operating on Addresses.
addressplans : Operating on AddressPlans.
addressspaceplans : Operating on AddressSpacePlans.
addressspaces : Operate on AddressSpaces
brokeredinfraconfigs : Operating on BrokeredInfraConfigs.
messagingusers : Operating on MessagingUsers.
standardinfraconfigs : Operating on StandardInfraConfigs.
Description : Find out more about EnMasse
URL : https://enmasse.io/documentation/
create an AddressSpacePlan
| Type | Name | Description | Schema |
|---|---|---|---|
Path |
namespace |
object name and auth scope, such as for teams and projects |
string |
Body |
body |
| HTTP Code | Description | Schema |
|---|---|---|
200 |
OK |
|
201 |
Created |
|
401 |
Unauthorized |
No Content |
application/json
application/json
addressspaceplan
admin
enmasse_v1beta2
list objects of kind AddressSpacePlan
| Type | Name | Description | Schema |
|---|---|---|---|
Path |
namespace |
object name and auth scope, such as for teams and projects |
string |
Query |
labelSelector |
A selector to restrict the list of returned objects by their labels. Defaults to everything. |
string |
| HTTP Code | Description | Schema |
|---|---|---|
200 |
OK |
|
401 |
Unauthorized |
No Content |
application/json
addressspaceplan
admin
enmasse_v1beta2
read the specified AddressSpacePlan
| Type | Name | Description | Schema |
|---|---|---|---|
Path |
name |
Name of AddressSpacePlan to read. |
string |
Path |
namespace |
object name and auth scope, such as for teams and projects |
string |
| HTTP Code | Description | Schema |
|---|---|---|
200 |
OK |
|
401 |
Unauthorized |
No Content |
404 |
Not found |
No Content |
application/json
application/json
addressspaceplan
admin
enmasse_v1beta2
replace the specified AddressSpacePlan
| Type | Name | Description | Schema |
|---|---|---|---|
Path |
name |
Name of AddressSpacePlan to replace. |
string |
Path |
namespace |
object name and auth scope, such as for teams and projects |
string |
Body |
body |
| HTTP Code | Description | Schema |
|---|---|---|
200 |
OK |
|
201 |
Created |
|
401 |
Unauthorized |
No Content |
application/json
addressspaceplan
admin
enmasse_v1beta2
delete an AddressSpacePlan
| Type | Name | Description | Schema |
|---|---|---|---|
Path |
name |
Name of AddressSpacePlan to delete. |
string |
Path |
namespace |
object name and auth scope, such as for teams and projects |
string |
| HTTP Code | Description | Schema |
|---|---|---|
200 |
OK |
|
401 |
Unauthorized |
No Content |
404 |
Not found |
No Content |
application/json
addressspaceplan
admin
enmasse_v1beta2
create an Address
| Type | Name | Description | Schema |
|---|---|---|---|
Path |
namespace |
object name and auth scope, such as for teams and projects |
string |
Body |
body |
| HTTP Code | Description | Schema |
|---|---|---|
200 |
OK |
|
201 |
Created |
|
401 |
Unauthorized |
No Content |
application/json
application/json
addresses
enmasse_v1beta1
list objects of kind Address
| Type | Name | Description | Schema |
|---|---|---|---|
Path |
namespace |
object name and auth scope, such as for teams and projects |
string |
Query |
labelSelector |
A selector to restrict the list of returned objects by their labels. Defaults to everything. |
string |
| HTTP Code | Description | Schema |
|---|---|---|
200 |
OK |
|
401 |
Unauthorized |
No Content |
application/json
addresses
enmasse_v1beta1
read the specified Address
| Type | Name | Description | Schema |
|---|---|---|---|
Path |
name |
Name of Address to read |
string |
Path |
namespace |
object name and auth scope, such as for teams and projects |
string |
| HTTP Code | Description | Schema |
|---|---|---|
200 |
OK |
|
401 |
Unauthorized |
No Content |
404 |
Not found |
No Content |
application/json
application/json
addresses
enmasse_v1beta1
replace the specified Address
| Type | Name | Description | Schema |
|---|---|---|---|
Path |
name |
Name of Address to replace |
string |
Path |
namespace |
object name and auth scope, such as for teams and projects |
string |
Body |
body |
| HTTP Code | Description | Schema |
|---|---|---|
200 |
OK |
|
201 |
Created |
|
401 |
Unauthorized |
No Content |
application/json
addresses
enmasse_v1beta1
delete an Address
| Type | Name | Description | Schema |
|---|---|---|---|
Path |
name |
Name of Address to delete |
string |
Path |
namespace |
object name and auth scope, such as for teams and projects |
string |
| HTTP Code | Description | Schema |
|---|---|---|
200 |
OK |
|
401 |
Unauthorized |
No Content |
404 |
Not found |
No Content |
application/json
addresses
enmasse_v1beta1
patches (RFC6902) the specified Address
| Type | Name | Description | Schema |
|---|---|---|---|
Path |
name |
Name of Address to replace |
string |
Path |
namespace |
object name and auth scope, such as for teams and projects |
string |
Body |
body |
| HTTP Code | Description | Schema |
|---|---|---|
200 |
OK |
|
401 |
Unauthorized |
No Content |
application/json-patch+json
application/json
addresses
enmasse_v1beta1
create an AddressSpace
| Type | Name | Description | Schema |
|---|---|---|---|
Path |
namespace |
object name and auth scope, such as for teams and projects |
string |
Body |
body |
| HTTP Code | Description | Schema |
|---|---|---|
200 |
OK |
|
201 |
Created |
|
401 |
Unauthorized |
No Content |
application/json
application/json
addressspaces
enmasse_v1beta1
list objects of kind AddressSpace
| Type | Name | Description | Schema |
|---|---|---|---|
Path |
namespace |
object name and auth scope, such as for teams and projects |
string |
Query |
labelSelector |
A selector to restrict the list of returned objects by their labels. Defaults to everything. |
string |
| HTTP Code | Description | Schema |
|---|---|---|
200 |
OK |
|
401 |
Unauthorized |
No Content |
application/json
addressspaces
enmasse_v1beta1
read the specified AddressSpace
| Type | Name | Description | Schema |
|---|---|---|---|
Path |
name |
Name of AddressSpace to read |
string |
Path |
namespace |
object name and auth scope, such as for teams and projects |
string |
| HTTP Code | Description | Schema |
|---|---|---|
200 |
OK |
|
401 |
Unauthorized |
No Content |
404 |
Not found |
No Content |
application/json
application/json
addressspaces
enmasse_v1beta1
replace the specified AddressSpace
| Type | Name | Description | Schema |
|---|---|---|---|
Path |
name |
Name of AddressSpace to replace |
string |
Path |
namespace |
object name and auth scope, such as for teams and projects |
string |
Body |
body |
| HTTP Code | Description | Schema |
|---|---|---|
200 |
OK |
|
201 |
Created |
|
401 |
Unauthorized |
No Content |
application/json
addressspaces
enmasse_v1beta1
delete an AddressSpace
| Type | Name | Description | Schema |
|---|---|---|---|
Path |
name |
Name of AddressSpace to delete |
string |
Path |
namespace |
object name and auth scope, such as for teams and projects |
string |
| HTTP Code | Description | Schema |
|---|---|---|
200 |
OK |
|
401 |
Unauthorized |
No Content |
404 |
Not found |
No Content |
application/json
addressspaces
enmasse_v1beta1
patches (RFC6902) the specified AddressSpace
| Type | Name | Description | Schema |
|---|---|---|---|
Path |
name |
Name of AddressSpace to replace |
string |
Path |
namespace |
object name and auth scope, such as for teams and projects |
string |
Body |
body |
| HTTP Code | Description | Schema |
|---|---|---|
200 |
OK |
|
401 |
Unauthorized |
No Content |
application/json-patch+json
application/json
addressspaces
enmasse_v1beta1
create a MessagingUser
| Type | Name | Description | Schema |
|---|---|---|---|
Path |
namespace |
object name and auth scope, such as for teams and projects |
string |
Body |
body |
| HTTP Code | Description | Schema |
|---|---|---|
200 |
OK |
|
201 |
Created |
|
401 |
Unauthorized |
No Content |
application/json
application/json
auth
enmasse_v1beta1
user
list objects of kind MessagingUser
| Type | Name | Description | Schema |
|---|---|---|---|
Path |
namespace |
object name and auth scope, such as for teams and projects |
string |
Query |
labelSelector |
A selector to restrict the list of returned objects by their labels. Defaults to everything. |
string |
| HTTP Code | Description | Schema |
|---|---|---|
200 |
OK |
|
401 |
Unauthorized |
No Content |
application/json
auth
enmasse_v1beta1
user
read the specified MessagingUser
| Type | Name | Description | Schema |
|---|---|---|---|
Path |
name |
Name of MessagingUser to read. Must include addressSpace and dot separator in the name (that is, 'myspace.user1'). |
string |
Path |
namespace |
object name and auth scope, such as for teams and projects |
string |
| HTTP Code | Description | Schema |
|---|---|---|
200 |
OK |
|
401 |
Unauthorized |
No Content |
404 |
Not found |
No Content |
application/json
application/json
auth
enmasse_v1beta1
user
replace the specified MessagingUser
| Type | Name | Description | Schema |
|---|---|---|---|
Path |
name |
Name of MessagingUser to replace. Must include addressSpace and dot separator in the name (that is, 'myspace.user1'). |
string |
Path |
namespace |
object name and auth scope, such as for teams and projects |
string |
Body |
body |
| HTTP Code | Description | Schema |
|---|---|---|
200 |
OK |
|
201 |
Created |
|
401 |
Unauthorized |
No Content |
application/json
auth
enmasse_v1beta1
user
delete a MessagingUser
| Type | Name | Description | Schema |
|---|---|---|---|
Path |
name |
Name of MessagingUser to delete. Must include addressSpace and dot separator in the name (that is, 'myspace.user1'). |
string |
Path |
namespace |
object name and auth scope, such as for teams and projects |
string |
| HTTP Code | Description | Schema |
|---|---|---|
200 |
OK |
|
401 |
Unauthorized |
No Content |
404 |
Not found |
No Content |
application/json
auth
enmasse_v1beta1
user
patches (RFC6902) the specified MessagingUser
| Type | Name | Description | Schema |
|---|---|---|---|
Path |
name |
Name of MessagingUser to replace. Must include addressSpace and dot separator in the name (that is, 'myspace.user1' |
string |
Path |
namespace |
object name and auth scope, such as for teams and projects |
string |
Body |
body |
| HTTP Code | Description | Schema |
|---|---|---|
200 |
OK |
|
401 |
Unauthorized |
No Content |
application/json-patch+json
application/json
auth
enmasse_v1beta1
user
| Name | Schema |
|---|---|
document |
object |
patch |
< Patch > array |
ObjectMeta is metadata that all persisted resources must have, which includes all objects users must create.
| Name | Schema |
|---|---|
name |
string |
namespace |
string |
| Name | Description | Schema |
|---|---|---|
from |
Required for operations copy, replace |
string |
op |
enum (add, remove, replace, move, copy, test) |
|
path |
Slash separated format |
string |
value |
Required for operations add, replace, test |
string |
Status is a return value for calls that do not return other objects.
| Name | Description | Schema |
|---|---|---|
code |
Suggested HTTP return code for this status, 0 if not set. |
integer (int32) |
| Name | Schema |
|---|---|
apiVersion |
enum (admin.enmasse.io/v1beta1) |
kind |
enum (BrokeredInfraConfig) |
metadata |
|
spec |
| Name | Schema |
|---|---|
apiVersion |
enum (admin.enmasse.io/v1beta1) |
items |
|
kind |
enum (BrokeredInfraConfigList) |
| Name | Schema |
|---|---|
admin |
|
broker |
|
networkPolicy |
|
version |
string |
networkPolicy
| Name | Schema |
|---|---|
egress |
|
ingress |
| Name | Schema |
|---|---|
podTemplate |
|
resources |
resources
| Name | Schema |
|---|---|
memory |
string |
| Name | Schema |
|---|---|
addressFullPolicy |
enum (PAGE, BLOCK, FAIL) |
podTemplate |
|
resources |
|
storageClassName |
string |
updatePersistentVolumeClaim |
boolean |
resources
| Name | Schema |
|---|---|
memory |
string |
storage |
string |
| Name | Schema |
|---|---|
metadata |
|
spec |
metadata
| Name | Schema |
|---|---|
labels |
object |
spec
| Name | Schema |
|---|---|
affinity |
object |
containers |
< containers > array |
priorityClassName |
string |
securityContext |
object |
tolerations |
< object > array |
containers
| Name | Schema |
|---|---|
resources |
object |
| Name | Schema |
|---|---|
apiVersion |
enum (admin.enmasse.io/v1beta1) |
kind |
enum (StandardInfraConfig) |
metadata |
|
spec |
| Name | Schema |
|---|---|
apiVersion |
enum (admin.enmasse.io/v1beta1) |
items |
|
kind |
enum (StandardInfraConfigList) |
| Name | Schema |
|---|---|
admin |
|
broker |
|
networkPolicy |
|
router |
|
version |
string |
networkPolicy
| Name | Schema |
|---|---|
egress |
|
ingress |
| Name | Schema |
|---|---|
podTemplate |
|
resources |
resources
| Name | Schema |
|---|---|
memory |
string |
| Name | Schema |
|---|---|
addressFullPolicy |
enum (PAGE, BLOCK, FAIL) |
connectorIdleTimeout |
integer |
connectorWorkerThreads |
integer |
podTemplate |
|
resources |
|
storageClassName |
string |
updatePersistentVolumeClaim |
boolean |
resources
| Name | Schema |
|---|---|
memory |
string |
storage |
string |
| Name | Schema |
|---|---|
idleTimeout |
integer |
initialHandshakeTimeout |
integer |
linkCapacity |
integer |
minAvailable |
integer |
minReplicas |
integer |
podTemplate |
|
policy |
|
resources |
|
workerThreads |
integer |
policy
| Name | Schema |
|---|---|
maxConnections |
integer |
maxConnectionsPerHost |
integer |
maxConnectionsPerUser |
integer |
maxReceiversPerConnection |
integer |
maxSendersPerConnection |
integer |
maxSessionsPerConnection |
integer |
resources
| Name | Schema |
|---|---|
memory |
string |
| Name | Schema |
|---|---|
apiVersion |
enum (admin.enmasse.io/v1beta2) |
kind |
enum (AddressPlan) |
metadata |
|
spec |
| Name | Schema |
|---|---|
apiVersion |
enum (admin.enmasse.io/v1beta2) |
items |
< io.enmasse.admin.v1beta2.AddressPlan > array |
kind |
enum (AddressPlanList) |
| Name | Schema |
|---|---|
addressType |
string |
displayName |
string |
displayOrder |
integer |
longDescription |
string |
partitions |
integer |
resources |
|
shortDescription |
string |
resources
| Name | Schema |
|---|---|
broker |
number |
router |
number |
| Name | Schema |
|---|---|
apiVersion |
enum (admin.enmasse.io/v1beta2) |
kind |
enum (AddressSpacePlan) |
metadata |
|
spec |
| Name | Schema |
|---|---|
apiVersion |
enum (admin.enmasse.io/v1beta2) |
items |
|
kind |
enum (AddressSpacePlanList) |
| Name | Schema |
|---|---|
addressPlans |
< string > array |
addressSpaceType |
string |
displayName |
string |
displayOrder |
integer |
infraConfigRef |
string |
longDescription |
string |
resourceLimits |
|
shortDescription |
string |
resourceLimits
| Name | Schema |
|---|---|
aggregate |
number |
broker |
number |
router |
number |
| Name | Schema |
|---|---|
apiVersion |
enum (user.enmasse.io/v1beta1) |
kind |
enum (MessagingUser) |
metadata |
|
spec |
| Name | Schema |
|---|---|
apiVersion |
enum (user.enmasse.io/v1beta1) |
items |
< io.enmasse.user.v1beta1.MessagingUser > array |
kind |
enum (MessagingUserList) |
| Name | Schema |
|---|---|
authentication |
|
authorization |
< authorization > array |
username |
string |
authentication
| Name | Description | Schema |
|---|---|---|
federatedUserid |
User id of the user to federate when 'federated' type is specified. |
string |
federatedUsername |
User name of the user to federate when 'federated' type is specified. |
string |
password |
Base64 encoded value of password when 'password' type is specified. |
string |
provider |
Name of provider to use for federated identity when 'federated' type is specified. |
string |
type |
enum (password, serviceaccount) |
| Name | Schema |
|---|---|
addresses |
< string > array |
operations |
< enum (send, recv, view, manage) > array |
| Name | Schema |
|---|---|
apiVersion |
enum (enmasse.io/v1beta1) |
kind |
enum (Address) |
metadata |
|
spec |
|
status |
| Name | Description | Schema |
|---|---|---|
apiVersion |
Default : |
enum (enmasse.io/v1beta1) |
items |
< io.enmasse.v1beta1.Address > array |
|
kind |
enum (AddressList) |
| Name | Schema |
|---|---|
apiVersion |
enum (enmasse.io/v1beta1) |
kind |
enum (AddressSpace) |
metadata |
|
spec |
|
status |
| Name | Description | Schema |
|---|---|---|
apiVersion |
Default : |
enum (enmasse.io/v1beta1) |
items |
< io.enmasse.v1beta1.AddressSpace > array |
|
kind |
enum (AddressSpaceList) |
| Name | Description | Schema |
|---|---|---|
authenticationService |
||
connectors |
List of connectors to create. |
|
endpoints |
< endpoints > array |
|
networkPolicy |
||
plan |
string |
|
type |
authenticationService
| Name | Schema |
|---|---|
name |
string |
overrides |
|
type |
string |
overrides
| Name | Schema |
|---|---|
host |
string |
port |
integer |
realm |
string |
endpoints
| Name | Schema |
|---|---|
cert |
|
exports |
< exports > array |
expose |
|
name |
string |
service |
string |
cert
| Name | Schema |
|---|---|
provider |
string |
secretName |
string |
tlsCert |
string |
tlsKey |
string |
exports
| Name | Schema |
|---|---|
kind |
enum (ConfigMap, Secret, Service) |
name |
string |
expose
| Name | Schema |
|---|---|
annotations |
object |
loadBalancerPorts |
< string > array |
loadBalancerSourceRanges |
< string > array |
routeHost |
string |
routeServicePort |
string |
routeTlsTermination |
string |
type |
enum (route, loadbalancer) |
networkPolicy
| Name | Schema |
|---|---|
egress |
|
ingress |
| Name | Description | Schema |
|---|---|---|
addresses |
Addresses to make be accessible via this address space. |
< addresses > array |
credentials |
Credentials used when connecting to endpoints. Either 'username' and 'password', or 'secret' must be defined. |
|
endpointHosts |
List of hosts that should be connected to. Must contain at least 1 entry. |
< endpointHosts > array |
name |
Name of the connector. |
string |
tls |
TLS settings for the connectors. If not specified, TLS will not be used. |
addresses
| Name | Description | Schema |
|---|---|---|
name |
Identifier of address pattern. Used to uniquely identify a pattern |
string |
pattern |
Pattern used to match addresses. The pattern will be prefixed by the connector name and a forward slash ('myconnector/'). A pattern consists of one or more tokens separated by a forward slash /. A token can be one of the following: a * character, a # character, or a sequence of characters that do not include /, *, or #. The * token matches any single token. The # token matches zero or more tokens. * has higher precedence than #, and exact match has the highest precedence. |
string |
credentials
| Name | Description | Schema |
|---|---|---|
password |
Password to use for connector. Either 'value' or 'secret' must be specified. |
|
username |
Username to use for connector. Either 'value' or 'secret' must be specified. |
password
| Name | Schema |
|---|---|
value |
string |
valueFromSecret |
valueFromSecret
| Name | Description | Schema |
|---|---|---|
key |
Key to use for looking up password entry. |
string |
name |
Name of Secret containing password. |
string |
username
| Name | Schema |
|---|---|
value |
string |
valueFromSecret |
valueFromSecret
| Name | Description | Schema |
|---|---|---|
key |
Key to use for looking up username entry. |
string |
name |
Name of Secret containing username. |
string |
endpointHosts
| Name | Description | Schema |
|---|---|---|
host |
Host to connect to. |
string |
port |
Port to connect to. |
integer |
tls
| Name | Description | Schema |
|---|---|---|
caCert |
CA certificate to be used by the connector. Either 'value' or 'secret'. |
|
clientCert |
Client certificate to be used by the connector. Either 'value' or 'secret'. |
caCert
| Name | Description | Schema |
|---|---|---|
value |
PEM encoded value of CA certificate |
string |
valueFromSecret |
Secret containing CA certificate to be used by the connector. |
valueFromSecret
| Name | Description | Schema |
|---|---|---|
key |
Key to use for looking up CA certificate entry. |
string |
name |
Name of Secret containing CA certificate. |
string |
clientCert
| Name | Description | Schema |
|---|---|---|
value |
PEM encoded value of client certificate |
string |
valueFromSecret |
Secret containing client certificate to be used by the connector. |
valueFromSecret
| Name | Description | Schema |
|---|---|---|
key |
Key to use for looking up client certificate entry. |
string |
name |
Name of Secret containing client certificate. |
string |
| Name | Description | Schema |
|---|---|---|
connectors |
List of connectors with status. |
|
endpointStatuses |
< endpointStatuses > array |
|
isReady |
boolean |
|
messages |
< string > array |
endpointStatuses
| Name | Schema |
|---|---|
cert |
string |
externalHost |
string |
externalPorts |
< externalPorts > array |
name |
string |
serviceHost |
string |
servicePorts |
< servicePorts > array |
externalPorts
| Name | Schema |
|---|---|
name |
string |
port |
integer |
servicePorts
| Name | Schema |
|---|---|
name |
string |
port |
integer |
| Name | Description | Schema |
|---|---|---|
isReady |
'true' if connector is operating as expected, 'false' if not. |
boolean |
messages |
Messages describing the connector state. |
< string > array |
name |
Name of connector. |
string |
AddressSpaceType is the type of address space (standard, brokered). Each type supports different types of addresses and semantics for those types.
Type : enum (standard, brokered)
| Name | Description | Schema |
|---|---|---|
address |
string |
|
forwarders |
List of forwarders to enable for this address. |
< io.enmasse.v1beta1.AddressSpecForwarder > array |
plan |
string |
|
type |
| Name | Description | Schema |
|---|---|---|
direction |
Direction of forwarder. 'in' means pulling from 'remoteAddress' into this address. 'out' means pushing from this address to 'remoteAddress'. |
enum (in, out) |
name |
Name of forwarder. |
string |
remoteAddress |
Remote address to send/receive messages to. |
string |
| Name | Description | Schema |
|---|---|---|
forwarders |
List of forwarders with status. |
|
isReady |
boolean |
|
messages |
< string > array |
|
phase |
enum (Pending, Configuring, Active, Failed, Terminating) |
| Name | Description | Schema |
|---|---|---|
isReady |
'true' if forwarder is operating as expected, 'false' if not. |
boolean |
messages |
Messages describing the forwarder state. |
< string > array |
name |
Name of forwarder. |
string |
Type of address (queue, topic, …). Each address type support different kinds of messaging semantics.
Type : enum (queue, topic, anycast, multicast)
IPBlock describes a particular CIDR (Ex. "<IP_ADDRESS>/24") that is allowed to the pods matched by a NetworkPolicySpec’s podSelector. The except entry describes CIDRs that should not be included within this rule.
| Name | Description | Schema |
|---|---|---|
cidr |
CIDR is a string representing the IP Block Valid examples are "<IP_ADDRESS>/24" |
string |
except |
Except is a slice of CIDRs that should not be included within an IP Block Valid examples are "<IP_ADDRESS>/24" Except values will be rejected if they are outside the CIDR range |
< string > array |
NetworkPolicyEgressRule describes a particular set of traffic that is allowed out of pods matched by a NetworkPolicySpec’s podSelector. The traffic must match both ports and to. This type is beta-level in 1.8
| Name | Description | Schema |
|---|---|---|
ports |
List of destination ports for outgoing traffic. Each item in this list is combined using a logical OR. If this field is empty or missing, this rule matches all ports (traffic not restricted by port). If this field is present and contains at least one item, then this rule allows traffic only if the traffic matches at least one port in the list. |
|
to |
List of destinations for outgoing traffic of pods selected for this rule. Items in this list are combined using a logical OR operation. If this field is empty or missing, this rule matches all destinations (traffic not restricted by destination). If this field is present and contains at least one item, this rule allows traffic only if the traffic matches at least one item in the to list. |
NetworkPolicyIngressRule describes a particular set of traffic that is allowed to the pods matched by a NetworkPolicySpec’s podSelector. The traffic must match both ports and from.
| Name | Description | Schema |
|---|---|---|
from |
List of sources which should be able to access the pods selected for this rule. Items in this list are combined using a logical OR operation. If this field is empty or missing, this rule matches all sources (traffic not restricted by source). If this field is present and contains at least on item, this rule allows traffic only if the traffic matches at least one item in the from list. |
|
ports |
List of ports which should be made accessible on the pods selected for this rule. Each item in this list is combined using a logical OR. If this field is empty or missing, this rule matches all ports (traffic not restricted by port). If this field is present and contains at least one item, then this rule allows traffic only if the traffic matches at least one port in the list. |
NetworkPolicyPeer describes a peer to allow traffic from. Only certain combinations of fields are allowed
| Name | Description | Schema |
|---|---|---|
ipBlock |
IPBlock defines policy on a particular IPBlock. If this field is set then neither of the other fields can be. |
|
namespaceSelector |
Selects Namespaces using cluster-scoped labels. This field follows standard label selector semantics; if present but empty, it selects all namespaces. If PodSelector is also set, then the NetworkPolicyPeer as a whole selects the Pods matching PodSelector in the Namespaces selected by NamespaceSelector. Otherwise it selects all Pods in the Namespaces selected by NamespaceSelector. |
|
podSelector |
This is a label selector which selects Pods. This field follows standard label selector semantics; if present but empty, it selects all pods. If NamespaceSelector is also set, then the NetworkPolicyPeer as a whole selects the Pods matching PodSelector in the Namespaces selected by NamespaceSelector. Otherwise it selects the Pods matching PodSelector in the policy’s own Namespace. |
NetworkPolicyPort describes a port to allow traffic on
| Name | Description | Schema |
|---|---|---|
port |
The port on the given protocol. This can either be a numerical or named port on a pod. If this field is not provided, this matches all port names and numbers. |
|
protocol |
The protocol (TCP or UDP) which traffic must match. If not specified, this field defaults to TCP. |
string |
A label selector is a label query over a set of resources. The result of matchLabels and matchExpressions are ANDed. An empty label selector matches all objects. A null label selector matches no objects.
| Name | Description | Schema |
|---|---|---|
matchExpressions |
matchExpressions is a list of label selector requirements. The requirements are ANDed. |
|
matchLabels |
matchLabels is a map of {key,value} pairs. A single {key,value} in the matchLabels map is equivalent to an element of matchExpressions, whose key field is "key", the operator is "In", and the values array contains only "value". The requirements are ANDed. |
< string, string > map |
A label selector requirement is a selector that contains values, a key, and an operator that relates the key and values.
| Name | Description | Schema |
|---|---|---|
key |
key is the label key that the selector applies to. |
string |
operator |
operator represents a key’s relationship to a set of values. Valid operators are In, NotIn, Exists and DoesNotExist. |
string |
values |
values is an array of string values. If the operator is In or NotIn, the values array must be non-empty. If the operator is Exists or DoesNotExist, the values array must be empty. This array is replaced during a strategic merge patch. |
< string > array |
IntOrString is a type that can hold an int32 or a string. When used in JSON or YAML marshalling and unmarshalling, it produces or consumes the inner type. This allows you to have, for example, a JSON field that can accept a name or number.
Type : string (int-or-string)
This API defines how to manage Devices and their Credentials.
GET /credentials/{tenantId}/{deviceId}
Get credentials set of a device.
Get the credentials set of a device. As long as the device is registered and the user has read access to it, this call should never return \"not found\". Depending on its implementation (or configuration), the device registry can either return all credentials information including full secret details or secret metadata along with the generated identifier (an id
property). The identifier can be used for the follow-up update
operation).
| Name | Description | Required | Default | Pattern |
|---|---|---|---|---|
tenantId |
The ID of the tenant |
X |
null |
|
deviceId |
The ID of the device |
X |
null |
array[TypedCredentials]
application/json
| Code | Message | Datatype |
|---|---|---|
200 |
Operation successful |
List[TypedCredentials] |
400 |
Malformed request |
|
401 |
Authentication credentials are required, but missing. |
<<>> |
404 |
Object not found. This may also be returned for some operations if the user misses read access for the object. |
PUT /credentials/{tenantId}/{deviceId}
Update credentials set for registered device
If the device registry is handling full secret details, the updated credential set will be an exact match of the provided content. If it is using secret metadata, data will be merged in based on the secret identities.
| Name | Description | Required | Default | Pattern |
|---|---|---|---|---|
tenantId |
The ID of the tenant |
X |
null |
|
deviceId |
The ID of the device |
X |
null |
| Name | Description | Required | Default | Pattern |
|---|---|---|---|---|
TypedCredentials |
X |
| Name | Description | Required | Default | Pattern |
|---|---|---|---|---|
If-Match |
The expected resource version |
- |
null |
-
application/json
| Code | Message | Datatype |
|---|---|---|
204 |
Object updated. |
<<>> |
400 |
Malformed request |
|
401 |
Authentication credentials are required, but missing. |
<<>> |
403 |
Operation not allowed. If the user does not have read access for this object, then `404` will be returned instead. |
|
404 |
Object not found. This may also be returned for some operations if the user misses read access for the object. |
|
412 |
Expected resource version does not match current. This can only happen when the request header `If-Match` was set. |
POST /devices/{tenantId}
Create new device registration with auto-generated ID
| Name | Description | Required | Default | Pattern |
|---|---|---|---|---|
tenantId |
The ID of the tenant |
X |
null |
| Name | Description | Required | Default | Pattern |
|---|---|---|---|---|
Device |
New device Device |
- |
application/json
| Code | Message | Datatype |
|---|---|---|
201 |
Object created. |
|
400 |
Malformed request |
|
401 |
Authentication credentials are required, but missing. |
<<>> |
403 |
Operation not allowed. If the user does not have read access for this object, then `404` will be returned instead. |
POST /devices/{tenantId}/{deviceId}
Create new device registration
| Name | Description | Required | Default | Pattern |
|---|---|---|---|---|
tenantId |
The ID of the tenant |
X |
null |
|
deviceId |
The ID of the device |
X |
null |
| Name | Description | Required | Default | Pattern |
|---|---|---|---|---|
Device |
New device Device |
- |
application/json
| Code | Message | Datatype |
|---|---|---|
201 |
Object created. |
|
400 |
Malformed request |
|
401 |
Authentication credentials are required, but missing. |
<<>> |
403 |
Operation not allowed. If the user does not have read access for this object, then `404` will be returned instead. |
|
409 |
Object already exists. If the user has no read access for the existing object, then `403` should be returned instead. |
DELETE /devices/{tenantId}/{deviceId}
Delete device registration
| Name | Description | Required | Default | Pattern |
|---|---|---|---|---|
tenantId |
The ID of the tenant |
X |
null |
|
deviceId |
The ID of the device |
X |
null |
| Name | Description | Required | Default | Pattern |
|---|---|---|---|---|
If-Match |
The expected resource version |
- |
null |
-
application/json
| Code | Message | Datatype |
|---|---|---|
204 |
Object deleted. |
<<>> |
401 |
Authentication credentials are required, but missing. |
<<>> |
403 |
Operation not allowed. If the user does not have read access for this object, then `404` will be returned instead. |
|
404 |
Object not found. This may also be returned for some operations if the user misses read access for the object. |
|
412 |
Expected resource version does not match current. This can only happen when the request header `If-Match` was set. |
GET /devices/{tenantId}/{deviceId}
Get device registration information
| Name | Description | Required | Default | Pattern |
|---|---|---|---|---|
tenantId |
The ID of the tenant |
X |
null |
|
deviceId |
The ID of the device |
X |
null |
application/json
| Code | Message | Datatype |
|---|---|---|
200 |
operation successful |
|
400 |
Malformed request |
|
401 |
Authentication credentials are required, but missing. |
<<>> |
404 |
Object not found. This may also be returned for some operations if the user misses read access for the object. |
PUT /devices/{tenantId}/{deviceId}
Update existing device registration
| Name | Description | Required | Default | Pattern |
|---|---|---|---|---|
tenantId |
The ID of the tenant |
X |
null |
|
deviceId |
The ID of the device |
X |
null |
| Name | Description | Required | Default | Pattern |
|---|---|---|---|---|
Device |
Updated device registration Device |
X |
| Name | Description | Required | Default | Pattern |
|---|---|---|---|---|
If-Match |
The expected resource version |
- |
null |
-
application/json
| Code | Message | Datatype |
|---|---|---|
204 |
Object updated. |
<<>> |
400 |
Malformed request |
|
401 |
Authentication credentials are required, but missing. |
<<>> |
403 |
Operation not allowed. If the user does not have read access for this object, then `404` will be returned instead. |
|
404 |
Object not found. This may also be returned for some operations if the user misses read access for the object. |
|
412 |
Expected resource version does not match current. This can only happen when the request header `If-Match` was set. |
| Field Name | Required | Type | Description | Format |
|---|---|---|---|---|
type |
X |
String |
||
auth-id |
X |
String |
||
enabled |
Boolean |
|||
ext |
Map of [object] |
Allows arbitrary properties as extension to the ones specified by the Hono API. |
| Field Name | Required | Type | Description | Format |
|---|---|---|---|---|
id |
String |
The device registry can assign an identity to the secret. This value can be used to update secrets based on their metadata. |
||
enabled |
Boolean |
|||
not-before |
Date |
date-time |
||
not-after |
Date |
date-time |
||
comment |
String |
| Field Name | Required | Type | Description | Format |
|---|---|---|---|---|
enabled |
Boolean |
|||
defaults |
Map of [object] |
Defaults for properties defined on the tenant and device level. |
||
via |
List of [string] |
The device IDs of the gateways that are registered to act on behalf of this device. Note that "via" and "memberOf" must not be set at the same time. |
||
viaGroups |
List of [string] |
The IDs of the gateway groups that are registered to act on behalf of this device. Note that "viaGroups" and "memberOf" must not be set at the same time. |
||
memberOf |
List of [string] |
The IDs of the gateway groups that this device is a member of. Note that "via" and "memberOf" must not be set at the same time. The same applies for "viaGroups" and "memberOf" which must be set at the same time too. The reason is that Eclipse Hono does not support groups of gateway groups. |
||
ext |
Map of [object] |
Allows arbitrary properties as extension to the ones specified by the Hono API. |
| Field Name | Required | Type | Description | Format |
|---|---|---|---|---|
error |
X |
String |
A human readable error message of what went wrong. |
| Field Name | Required | Type | Description | Format |
|---|---|---|---|---|
id |
X |
String |
The ID of the created object |
| Field Name | Required | Type | Description | Format |
|---|---|---|---|---|
type |
X |
String |
||
auth-id |
X |
String |
||
enabled |
Boolean |
|||
ext |
Map of [object] |
Allows arbitrary properties as extension to the ones specified by the Hono API. |
||
secrets |
List of PSKSecret |
| Field Name | Required | Type | Description | Format |
|---|---|---|---|---|
secrets |
List of PSKSecret |
| Field Name | Required | Type | Description | Format |
|---|---|---|---|---|
id |
String |
The device registry can assign an identity to the secret. This value can be used to update secrets based on their metadata. |
||
enabled |
Boolean |
|||
not-before |
Date |
date-time |
||
not-after |
Date |
date-time |
||
comment |
String |
|||
key |
X |
byte[] |
byte |
| Field Name | Required | Type | Description | Format |
|---|---|---|---|---|
key |
X |
byte[] |
byte |
| Field Name | Required | Type | Description | Format |
|---|---|---|---|---|
type |
X |
String |
||
auth-id |
X |
String |
||
enabled |
Boolean |
|||
ext |
Map of [object] |
Allows arbitrary properties as extension to the ones specified by the Hono API. |
||
secrets |
List of PasswordSecret |
| Field Name | Required | Type | Description | Format |
|---|---|---|---|---|
secrets |
List of PasswordSecret |
| Field Name | Required | Type | Description | Format |
|---|---|---|---|---|
id |
String |
The device registry can assign an identity to the secret. This value can be used to update secrets based on their metadata. |
||
enabled |
Boolean |
|||
not-before |
Date |
date-time |
||
not-after |
Date |
date-time |
||
comment |
String |
|||
hash-function |
String |
The name of the hash function used to create the password hash (defined in `pwd-hash` property). If the password is defined using a `pwd-plain` property, this value will be ignored by the device registry. This property should be empty when returning passwords from the device registry using only secret metadata. In this case the id field must be set instead. |
||
pwd-hash |
byte[] |
The password hash created using the `hash-function` and optional `salt` values. If the password is defined using a `pwd-plain` property, this value will be ignored by the device registry. This property should be empty when returning passwords from the device registry using only secret metadata. In this case the id field must be set instead. |
byte |
|
salt |
byte[] |
The Base64 encoding of the salt used in the password hash (defined in the `pwd-hash` property). If the password is defined using a `pwd-plain` property, this value will be ignored by the device registry. This property should be empty when returning passwords from the device registry using only secret metadata. In this case the id field must be set instead. |
byte |
|
pwd-plain |
byte[] |
The clear text value of the password to be hashed by the device registry. If this property is specified, the device registry will ignore user-provided hash properties (`hash-function`, `pwd-hash` and `salt`). This property must never be stored by the device registry. This property must be empty when returning passwords from the device registry. |
byte |
| Field Name | Required | Type | Description | Format |
|---|---|---|---|---|
hash-function |
String |
The name of the hash function used to create the password hash (defined in `pwd-hash` property). If the password is defined using a `pwd-plain` property, this value will be ignored by the device registry. This property should be empty when returning passwords from the device registry using only secret metadata. In this case the id field must be set instead. |
||
pwd-hash |
byte[] |
The password hash created using the `hash-function` and optional `salt` values. If the password is defined using a `pwd-plain` property, this value will be ignored by the device registry. This property should be empty when returning passwords from the device registry using only secret metadata. In this case the id field must be set instead. |
byte |
|
salt |
byte[] |
The Base64 encoding of the salt used in the password hash (defined in the `pwd-hash` property). If the password is defined using a `pwd-plain` property, this value will be ignored by the device registry. This property should be empty when returning passwords from the device registry using only secret metadata. In this case the id field must be set instead. |
byte |
|
pwd-plain |
byte[] |
The clear text value of the password to be hashed by the device registry. If this property is specified, the device registry will ignore user-provided hash properties (`hash-function`, `pwd-hash` and `salt`). This property must never be stored by the device registry. This property must be empty when returning passwords from the device registry. |
byte |
| Field Name | Required | Type | Description | Format |
|---|---|---|---|---|
type |
X |
String |
||
auth-id |
X |
String |
||
enabled |
Boolean |
|||
ext |
Map of [object] |
Allows arbitrary properties as extension to the ones specified by the Hono API. |
||
secrets |
List of X509CertificateSecret |
| Field Name | Required | Type | Description | Format |
|---|---|---|---|---|
type |
X |
String |
||
auth-id |
X |
String |
||
enabled |
Boolean |
|||
ext |
Map of [object] |
Allows arbitrary properties as extension to the ones specified by the Hono API. |
||
secrets |
List of X509CertificateSecret |
| Field Name | Required | Type | Description | Format |
|---|---|---|---|---|
secrets |
List of X509CertificateSecret |
| Field Name | Required | Type | Description | Format |
|---|---|---|---|---|
id |
String |
The device registry can assign an identity to the secret. This value can be used to update secrets based on their metadata. |
||
enabled |
Boolean |
|||
not-before |
Date |
date-time |
||
not-after |
Date |
date-time |
||
comment |
String |