- Service configuration structure
- Default configuration
The KPC loads configuration data from a file (typically backed by a Kubernetes config map). The location of the configuration file is sourced from an environment variable. If the service is unable to retrieve the configuration data, it will not start. Refer to the configuration for details.
Service configuration structure
The recommended configuration format is YAML. The below sections describe the officially supported configuration options that influence various aspects of the service functionality. The service may support options other than the ones listed below, but those are not a part of the public API and may be changed or deleted at any time.
KPC uses its service instance name and replica ID for communication with other services and load balancing across replicas (for example, see [3/ISM][3/ISM]). You can control the values with the following configuration options:
service: instance: name: <string> # Service instance name, should be unique cluster-wide. "kpc" by default. replica.id: <string> # Service instance replica ID, should be unique cluster-wide. Random string by default. graceful-shutdown: <uint> # Allowed service graceful shutdown period in seconds. 30 seconds by default.
KPC implements 1/KP protocol over MQTT that can be exposed plain, over TLS, and over websockets.
Only plain MQTT is enabled by default, but you can configure up to all three interfaces to function concurrently, if necessary.
MQTT over websocket interface processes client connections on
/ws path of the configured port.
Below are the most important configuration options.
kaa: kpc: transports: mqtt: tcp: # Plain MQTT over TCP transport configuration. enabled: <boolean> # Enables MQTT transport; true by default. port: <unsigned short integer> # Port number to expose the MQTT interface at; 1883 by default. tls: # MQTT over TLS transport configuration. enabled: <boolean> # Enables MQTT/TLS transport; false by default. port: <unsigned short integer> # Port number to expose the MQTT/TLS interface at; 8883 by default. cert-file: <string> # Location of a PEM-encoded server certificate file; "/run/ssl/tls.crt" by default. cert-key-file: <string> # Location of a PEM-encoded server certificate key file; "/run/ssl/tls.key" by default. client-auth: required: <bool> # Whether to require certificate-base client authentication. In addition to the standard client's certificate validity verification, KPC will use the configured [authentication interface](/KPC/docs/current/Overview/#authentication) to perform an additional certificate check. False by default. trust-store-file: <string> # Location of a PEM-encoded server trust store file; "/run/ssl/ca.crt" by default. ws: # MQTT over Websocket transport configuration. enabled: <boolean> # Enables MQTT/Websocket transport; false by default. port: <unsigned short integer> # Port number to expose the MQTT/Websocket interface at; 9001 by default. plain-auth.required: <bool> # Whether to require the client plain (username / password) configuration authentication. Applies to all MQTT-based transport. False by default. client-message: timeout: # The maximum allowed message processing duration in milliseconds, after which client message expires. KPC sets this timeout in [downstream messages to other services](https://github.com/kaaproject/kaa-rfcs/blob/master/0003/README.targeted-message-common-fields), which must respect the timeout. Value of 0 indicates no expiration. 10,000 (10 seconds) by default.
Extension instances configuration is necessary for KPC to know which extension service instances are endpoint-aware, and which ones are not. By default, extensions are considered endpoint-aware. KPC will not allow endpoint communication to extensions not listed here.
kaa.kpc.extensions: # List of extension instances <extension instance name>: # Extension service instance name endpoint-aware: <boolean> # Specifies whether the extension is endpoint-aware. True by default. ...
Many Kaa services can be configured for different behavior depending on the application version of the endpoint the processed data relates to.
This is called appversion-specific behavior and is handled in service configurations under
KPC supports configuring a whitelist of allowed extension services per each application version. KPC will only allow endpoints to communicate to extension service instances listed in their application version. This configuration is optional, and no filtering occurs if the list of extensions is not configured.
kaa: applications: <application 1 name>: versions: <application 1 version 1 name>: allowed-extension-instances: # List of names of extension service instances that endpoints in this application version are allowed to # communicate with. Optional. - <service instance name> <application 1 version 2 name>: # Multiple application versions can be configured under the "versions" key ... <application 2 name>: # Multiple applications can be configured under the "applications" key ...
kaa: applications: smart_kettle: versions: kettle_v1: # "kettle_v1" application version is configured with no filtering by extensions kettle_v2: # "kettle_v2" only allows "dcx" and "epmx" extension instances allowed-extension-instances: - dcx - epmx kettle_v3: # "kettle_v3" explicitly specifies no restriction for extension instances. No filtering occurs. allowed-extension-instances:
Due to the various compatibility reasons the application and application version names must be limited to lowercase latin letters (
a-z), digits (
0-9), dashes (
-) and underscores (
Authentication interface for clients and endpoints
KPC uses the authentication interface to authenticate clients and endpoints. Use the below parameters to configure this interface.
kaa.ecap.consumer: provider: service-instance-name: <service instance name> # Instance name of the service used to authenticate clients and endpoints. "cm" by default. timeout: <uint> # Request timeout in milliseconds for all requests to ECAP Provider. 10,000 (10 seconds) by default.
The below parameters configure KPC’s connection to NATS broker, as well as the NATS message adapters used by KPC. Note that, for security reasons, in case the NATS connection requires credentials, you should set it with the environment variables.
nats.urls: <comma separated list of URL> # NATS connection URLs. "nats://nats:4222" by default. kaa: esp: client: concurrency: <uint> # Number of concurrent workers to read NATS-based messages from extension service. 16 by default. queue-length: <uint> # The maximum amount of messages in the ESP server queue. When the queue is full, new messages will be dropped. 64 * `kaa.esp.client.concurrency` by default.
Consider configuring concurrency options to at least match the number of CPUs available on your infrastructure.
To control the KPC management interface, use the following configuration options.
service.monitoring: disabled: <boolean> # Disables the monitoring interface entirely. False by default (enabled). port: <uint> # TCP port to expose the monitoring server on. 8080 by default.
KPC writes logs to
By default, the service only produces logs at startup, shutdown, or in case of errors.
To enable debug level logging, use the following option:
service: debug: <boolean> # Enables debug level logging, false by default (disabled).
Keep in mind that enabling debug level logging will produce significantly more log output and degrade the service performance.
Summarizing the above, the default KPC configuration is as follows. Note that no Kaa applications are defined by default—you have to configure those for any specific Kaa-based solution.
service: instance: name: "kpc" replica.id: "<random string generated on boot>" monitoring: disabled: false port: 8080 graceful-shutdown: 30 # seconds debug: false kaa: kpc: transports: mqtt: tcp: enabled: true port: 1883 tls: enabled: false port: 8883 cert-file: "/run/ssl/tls.crt" cert-key-file: "/run/ssl/tls.key" client-auth: required: false trust-store-file: "/run/ssl/ca.crt" ws: enabled: false port: 9001 plain-auth.required: false client-message: timeout: 10000 # milliseconds ecap.consumer: provider: service-instance-name: cm timeout: 10000 # milliseconds applications: # none; at least one must be configured to start esp: client: concurrency: 16 queue-length: 1024 nats.urls: nats://nats:4222