1. Home
  2. Extending Keboola
  3. Common Interface
  4. Environment

Environment Specification

Components use several channels to exchange information with Keboola, primarily through structured folders and configuration files. Each component has full access to the external network (network type bridge), unless explicitly changed to none in the Developer Portal. Below are the specific aspects of the environment in which your component operates.

Environment Variables

The following environment variables are injected into the container:

  • KBC_DATADIR: Always /data/ in Keboola; use this variable during component development to create development and testing environments.
  • KBC_RUNID: The RunId from Storage; links all events within an API call (useful for logging).
  • KBC_PROJECTID: The ID of the project in Keboola within a Keboola stack.
  • KBC_STACKID: The ID of the Keboola stack.
  • KBC_CONFIGID: The ID of the configuration, or a hash of configuration data if the configuration is not named (e.g., when configData is used in an API call).
  • KBC_CONFIGVERSION: The version of the configuration, or empty if unnamed (whne configData is used in the API call).
  • KBC_COMPONENTID: The ID of the component.
  • KBC_CONFIGROWID: The ID of the configuration row, if available.
  • KBC_BRANCHID: The ID of the development branch.
  • KBC_STAGING_FILE_PROVIDER: Either aws or azure, depending on the type of stack the container is running. This value refers to the file storage used during file import/export operations.
  • KBC_PROJECT_FEATURE_GATES: A comma-separated list of feature gates activated for the current project. Feature gates are considered internal and may change or disappear without notice. We recommend checking with our support team before relying on any feature gates.
  • KBC_COMPONENT_RUN_MODE: Either run or debug. The value debug is used when the job is run in debug mode (learn more). This variable can be helpful, for example, to enable more verbose logging.
  • KBC_DATA_TYPE_SUPPORT: Either authoritative, hints, or none:
    • authoritative: The component generates columns with data types in the schema node.
    • hints: The component generates columns without data types in the schema node.
    • none: The component generates only column names in the columns node.

Additional Variables for Forwarded Token and Token Details

The following variables are available only if “Forwards token” and “Forwards token details” are enabled in the component configuration (and approved by Keboola):

  • KBC_PROJECTNAME: The name of the project in Keboola.
  • KBC_TOKENID: The ID of the token running the container.
  • KBC_TOKENDESC: A description of the token (e.g., user name or token name).
  • KBC_TOKEN: The token itself.
  • KBC_URL: The Storage API URL.
  • KBC_REALUSER: The user ID provided by SAML authentication.

Additional Variables for GELF Logger

The following variables are available when the GELF Logger is enabled in the component configuration:

  • KBC_LOGGER_ADDR: The IP address of the GELF server.
  • KBC_LOGGER_PORT: The port of the GELF server.

Return Values

The script defined in the Dockerfile’s ENTRYPOINT or CMD should provide an exit status. The following rules apply:

  • exit code = 0: The execution is considered successful.
  • exit code = 1: The execution fails with a User Error. Both STDOUT and STDERR are sent to Storage API Events.
  • exit code > 1: The execution fails with an Application Error. Both STDOUT and STDERR are logged internally.

Modifying Error Behavior

To report all errors as User Errors regardless of the exit code, set no_application_errors in the component configuration. See the implementation notes for tips on distinguishing between User Errors and Application Errors.