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.

General

KPC uses its service instance name and replica ID for communication with other services and load balancing across replicas (for example, see 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.

The REST API server is controlled with the following options.

server:
  port: <integer>           # Server port used to expose the REST API at, 8008 by default.

MQTT transport

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 plain MQTT transport; true by default. Also can be set by the KAA_KPC_TRANSPORTS_MQTT_TCP_ENABLED environment variable.
          port: <unsigned short integer>    # Port number to expose the plain MQTT interface at; 1883 by default. Also can be set by the KAA_KPC_TRANSPORTS_MQTT_TCP_PORT environment variable.

        tls:
          # MQTT over TLS transport configuration.
          enabled: <boolean>                # Enables MQTT/TLS transport; false by default. Also can be set by the KAA_KPC_TRANSPORTS_MQTT_TLS_ENABLED environment variable.
          port: <unsigned short integer>    # Port number to expose the MQTT/TLS interface at; 8883 by default. Also can be set by the KAA_KPC_TRANSPORTS_MQTT_TLS_PORT environment variable.
          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:
            enabled: <bool>                # Whether to enable X.509 certificate-based client authentication. When enabled, KPC performs standard client certificate verification against the configured trust store if such certificate is provided by client. Additionally, KPC uses the configured authentication interface to perform an additional certificate check (see the "Authentication interface for clients" section). Whether to require mandatory client X.509 authentication is controlled on a per-tenant basis. False by default. Also can be set by the KAA_KPC_TRANSPORTS_MQTT_TLS_CLIENT_AUTH_ENABLED environment variable.
            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. Also can be set by the KAA_KPC_TRANSPORTS_MQTT_WS_ENABLED environment variable.
          port: <unsigned short integer>    # Port number to expose the MQTT/Websocket interface at; 9001 by default. Also can be set by the KAA_KPC_TRANSPORTS_MQTT_WS_PORT environment variable.

    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, which must respect the timeout. Value of 0 indicates no expiration. 10,000 (10 seconds) by default.

HTTP transport

KPC implements 1/KP protocol over plain HTTP. The supported request HTTP method is POST. The request URL following the initial / must obey the structure of the 1/KP resource path (note the special handling of the request ID for MQTT in 1/KP). A compliant HTTP request is equivalent to an MQTT publish message with the same resource path and payload. For example, a POST request on /kp1/kettle-v1/dcx/mytoken/json will be interpreted as a 1/KP message in kettle-v1 application version to extension service instance dcx using endpoint token mytoken and extension-specific resource path /json.

Unlike MQTT, HTTP binding is synchronous: it follows the request-response communication pattern and does not support server message push. Where with MQTT 1/KP responses are delivered to specifically reserved topics, HTTP transport delivers responses synchronously.

Below are the most important transport configuration options.

kaa:
  kpc:
    transports:
      http:
        tcp:
          # Plain HTTP over TCP transport configuration.
          enabled: <boolean>                # Enables plain HTTP transport; true by default. Also can be set by the KAA_KPC_TRANSPORTS_HTTP_TCP_ENABLED environment variable.
          port: <unsigned short integer>    # Port number to expose the plain HTTP interface at; 80 by default. Also can be set by the KAA_KPC_TRANSPORTS_HTTP_TCP_PORT environment variable.

HTTP transport also uses kaa.kpc.client-message.timeout configuration option to control the maximum allowed processing duration for any requests. Upon expiration, the 504 Gateway Timeout response is returned.

Extension instances

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.
  ...

Kaa applications

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 kaa.applications. Alternatively, the application-specific configuration can be sourced from Kaa Tekton. See the Tekton configuration section to find out how to configure such integration.

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
      ...

For example:

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 (_).

Tekton

KPC supports integration with Kaa Tekton for centralized application configuration management. The below configuration options set up the integration interface.

kaa:
  tekton:
    enabled: <boolean>    # Enables Tekton integration. False by default. Also can be set with the KAA_TEKTON_ENABLED environment variable.
    url: <string>         # URL of the Tekton service. "http://tekton" by default. Also can be set with the KAA_TEKTON_URL environment variable.
  scmp.consumer:
    provider.service-instance-name: <string>  # Service instance name of the Tekton service. "tekton" by default.
    queue-length: <uint>                      # Maximum queue length for 17/SCMP messages from Tekton. 256 by default.

For the Tekton integration to function, there must be no kaa.applications key in the configuration file. Such configuration, when present, takes precedence over the Tekton-supplied application-specific configs.

Identification interface for endpoints

KPC uses the endpoint identification interface to identify endpoints by their tokens. Use the below parameters to configure this interface.

kaa.eap.consumer:
  provider:
    service-instance-name: <service instance name>  # Instance name of the service used to authenticate endpoints. "cm" by default.
    timeout: <uint>                                 # Request timeout in milliseconds for all requests to EAP Provider. 10,000 (10 seconds) by default.

Authentication interface for clients

KPC uses the client authentication interface to authenticate clients by their basic or X.509 credentials. Use the below parameters to configure this interface.

kaa.cap.consumer:
  provider:
    service-instance-name: <service instance name>  # Instance name of the service used to authenticate clients. "ccm" by default.
    timeout: <uint>                                 # Request timeout in milliseconds for all requests to CAP Provider. 10,000 (10 seconds) by default.

Basic client authentication can be made mandatory in KPC on a per-tenant basis, separately for each transport. Currently, KPC supports basic client authentication on MQTT-based transports. To toggle basic client authentication, use the following configuration structure:

kaa.tenants:
  <tenant ID>:                        # Tenant ID, for which to configure basic client authentication.
    config.transports.mqtt:
      tcp.basic-auth.required: <bool> # Whether to require the basic client authentication on the plain MQTT transport. False by default.
      tls.basic-auth.required: <bool> # Whether to require the basic client authentication on the MQTT/TLS transport. False by default.
      ws.basic-auth.required: <bool>  # Whether to require the basic client authentication on the MQTT/WebSocket transport. False by default.

X.509 certificate-based client authentication can also be made mandatory in KPC on a per-tenant basis. Currently, KPC supports X.509 client authentication on MQTT/TLS transport. To toggle X.509 client authentication, use the following configuration structure:

kaa.tenants:
  <tenant ID>:                        # Tenant ID, for which to configure X.509 client authentication.
    config.transports.mqtt:
      tls.x509-auth.required: <bool>  # Whether to require the X.509 client authentication on the MQTT/TLS transport. False by default.

NATS

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.

Authentication, authorization, and multi-tenancy

KPC supports two integrations for security:

  • OAuth2 protocol with a UMA profile. Enabled when kaa.security.enabled is true and kaa.security.iamcore.enabled is false.
  • iamcore. Enabled when both kaa.security.enabled and kaa.security.iamcore.enabled are true.

OAuth2 with UMA profile

Authentication and authorization is handled within the scope of a given Kaa tenant. Each tenant has a separate OAuth 2.0 issuer, managed by the Kaa Tenant Manager. When multi-tenancy is disabled, all authentication and authorization is conducted in the default system tenant (“kaa”).

KPC OAuth2 with UMA profile security is controlled with the following configuration options (for security reasons it is advised to set these via environment variables).

kaa:
  security:
    enabled: <boolean>      # Enables authentication and authorization. False by default.
    issuer:
      public-url: <string>  # OAuth 2.0 issuer public URL for the system tenant ("kaa").
      private-url: <string> # OAuth 2.0 issuer private URL for the system tenant ("kaa").
    client-id: <string>     # Client ID for making requests in the system tenant scope.
    client-secret: <string> # Client secret for making requests in the system tenant scope.
    multitenancy:
      enabled: <boolean>    # Enables multitenancy via integration with the Kaa Tenant Manager. Only effective when kaa.security.enabled is set to true. False by default.
      tenant-manager:
        url: <string>       # URL of the Kaa Tenant Manager that provides security configurations for tenants. "http://tenant-manager" by default.

iamcore

Authentication and authorization is handled by iamcore.

KPC iamcore security is controlled with the following configuration options (for security reasons it is advised to set these via environment variables).

kaa:
  security:
    enabled: <boolean>      # Enables authentication and authorization. False by default.
    iamcore:
      enabled: <boolean>    # Enables iamcore integration. False by default.
      api-key: <string>     # iamcore API KEY
      url: <string>         # iamcore server URL. "https://cloud.iamcore.io" by default.
      application: <string> # iamcore application. "kaa" by default

Endpoint lifecycle messages receiver

KPC listens to 9/ELCE endpoint connected events from other replicas of its own instance. This is necessary for detecting endpoint roaming across client connections and properly managing the message routing.

The 9/ELCE receiver interface has the following configuration options:

kaa.elce.receiver:
  concurrency: <uint>   # The maximum amount of concurrent goroutines to read and process incoming 9/ELCE NATS messages. 8 by default.
  queue-length: <uint>  # The maximum amount of messages in the ELCE receiver queue. When the queue is full, new messages will be dropped. 16 * concurrency by default.

Monitoring

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.

Logging

KPC writes logs to stdout. 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.

Traffic monitoring

The KPC tracks the amount of received/sent traffic from/to endpoints and periodically reports collected statistic over the 9/ELCE protocol. Also, KPC controls the number of received/sent messages from/to endpoints and if it exceeds the configured quota, immediately suspends token of such endpoints. To configure the KPC traffic monitoring, use the following configuration options.

kaa.kpc.traffic.monitoring:
  cron: <string>                              # cron for traffic report publishing and monitoring. Default "* * * * *" - every minute
  queue-length: <uint>                        # The maximum amount of pending messages of traffic events in the underlying reporter's queue. Must be between 3 and 500 inclusively.
  total-received-message-count-quota: <uint>  # quota of total received message count in cron period. 0 means no quota is applied. Default 0
  total-sent-message-count-quota: <uint>      # quota of total sent message count in cron period. 0 means no quota is applied. Default 0

Default configuration

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

server:
  port: 8008

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:
            enabled: false
            trust-store-file: "/run/ssl/ca.crt"

        ws:
          enabled: false
          port: 9001

        basic-auth.required: false

      http:
        tcp:
          enabled: true
          port: 80

    client-message:
      timeout: 10000 # milliseconds

    reporting:
      traffic:
        cron: "* * * * *" # every minute
        queue-length: 50
        
  eap.consumer:
    provider:
      service-instance-name: cm
      timeout: 10000 # milliseconds

  cap.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