Configuration

The BCX 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

BCX 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. "bcx" 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, 80 by default.

To configure the BCX issue of the temporary data upload tokens, use the following options:

kaa:
  bcx:
    tokens:
      key-file: <string>  # Location of the PEM-encoded RSA private key used for signing and validating tokens. "/run/rsa/private.pem" by default. Also can be set with the KAA_BCX_TOKENS_KEY_FILE environment variable.
      expiration: <int>   # Temporary token validity duration in seconds. 3600 (1 hour) by default. Also can be set with the KAA_BCX_TOKENS_EXPIRATION environment variable.

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

kaa:
  applications:
    <application 1 name>:
      versions:
        <application 1 version 1 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_v2:
        kettle_v3:

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

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

Data persistence interface

BCX uses PostgreSQL for persisting binary data blobs metadata. The actual data blob payloads can be stored in AWS S3 or in RAM (development mode only).

The following values configure the BCX persistence:

kaa:
  bcx:
    storage:
      backend: <string>         # Backend to use for binary data blobs storage ("aws-s3" or "ram"). "aws-s3" by default. Also can be set with the KAA_BCX_STORAGE_BACKEND environment variable.
  postgresql:
    host: <string>           # PostgreSQL host. "bcx-postgresql" by default. Also can be set with the KAA_POSTGRESQL_HOST environment variable.
    port: <int>              # PostgreSQL port. 5432 by default. Also can be set with the KAA_POSTGRESQL_PORT environment variable.
    username: <string>       # PostgreSQL username. "bcx" by default. Also can be set with the KAA_POSTGRESQL_USERNAME environment variable.
    password: <string>       # PostgreSQL password. "bcx" by default. Also can be set with the KAA_POSTGRESQL_PASSWORD environment variable.
    database: <string>       # PostgreSQL database. "bcx" by default. Also can be set with the KAA_POSTGRESQL_DATABASE environment variable.
    sslMode: <string>        # PostgreSQL SSL mode ("disable", "require", "verify-ca", "verify-full"). "disable" by default. Also can be set with the KAA_POSTGRESQL_SSL_MODE environment variable.
    max-open-connections: <int>   # Maximum number of open connections to PostgreSQL. 100 by default. Also can be set with the KAA_POSTGRESQL_MAX_OPEN_CONNECTIONS environment variable.

NOTE: For security reasons, AWS S3 access credentials must be sourced from the environment variables (see variables starting with AWS).

NATS

The below parameters configure BCX’s connection to NATS. Note that for security reasons NATS username and password are sourced from the environment variables.

nats:
  urls: <comma separated list of URL>  # NATS connection URLs.

Authentication, authorization, and multi-tenancy

BCX’s REST API security is implemented according to OAuth2 protocol with a 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][Tenant Manager]. When multi-tenancy is disabled, all authentication and authorization is conducted in the default system tenant (“kaa”).

BCX 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: <string>        # OAuth 2.0 issuer 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.

Management

To control the BCX 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

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