Configuration

Topaz requires a configuration file to run. By default, the location of the config file is $XDG_CONFIG_HOME/topaz/cfg/config.yaml, if the $XDG_CONFIG_HOME environment variable is not set it will be set in $HOME/.config/topaz/cfg/config.yaml.

The templates install command automatically creates the right configuration file. To obtain more control over the generated configuration file, use topaz config subcommands.

Managing topaz configurations

The topaz config set of subcommands allows users to:

select a topaz configuration file that will be used in the future Topaz CLI interactions
generate new configuration files
list existing Topaz configuration files
rename configuration files
delete a Topaz configuration file

Usage: topaz config <command> [flags]

configure topaz service

Commands:
  config use       set active configuration
  config new       create new configuration
  config list      list configurations
  config rename    rename configuration
  config delete    delete configuration
  
Flags:
  -h, --help        Show context-sensitive help.
  -N, --no-check    disable local container status check ($TOPAZ_NO_CHECK)
  -L, --log         log level

Generating a config file

topaz config new generates a configuration file with the most common options.

Flags:
  -h, --help                         Show context-sensitive help.
  -N, --no-check                     disable local container status check ($TOPAZ_NO_CHECK)
  -L, --log=0                        log level

  -n, --name=STRING                  config name
  -l, --local-policy-image=STRING    local policy image name
  -r, --resource=STRING              resource url
  -p, --stdout                       print to stdout
  -d, --edge-directory               enable edge directory
  -f, --force                        skip confirmation prompt

Example:

To generate a configuration file for the demo "todo" policy using the public OCI image for that policy (from GHCR), use the following command:

topaz config new -d -r ghcr.io/aserto-policies/policy-todo:latest -n todo

To generate a configuration file for a local OCI image, use the following command:

topaz config new -d -l my-image:latest -n todo

Named configurations

Topaz CLI allows the user to have multiple configuration files and easily switch between them when running the topaz container.

When using templates the generated configuration file uses the name of the template (ex. for todo template it will generate a $XDG_CONFIG_HOME/topaz/cfg/todo.yaml).

To see available configuration files you can use the topaz config list command, this will also highlight the current active configuration file.

If you want to start topaz with a different configuration file, you can just specify the name of the configuration you want to use in the topaz start/run -n=<name_of_configuration> command. This will automatically switch you active configuration file to the one you used.

Note: The default config.yaml file will keep the container name as topaz. Any named configurations (ex. any installed template) will use the topaz-<config_name> as the container name.

Topaz CLI paths and environment variables

By default the Topaz CLI uses XDG_CONFIG_HOME and XDG_DATA_HOME to store the topaz configuration files, local directory files and cert files. These values can be easily overwritten using the Topaz specific environment variables TOPAZ_CERTS_DIR and TOPAZ_DB_DIR (used in newly generated configuration files).

Depending on the OS if these are not set the default paths used are:

Linux and Darwin/MacOS

- $HOME/.local/share/topaz/db - directory files
- $HOME/.local/share/topaz/certs - cert files
- $HOME/.config/topaz/cfg - config files

Windows

- $HOME\AppData\Local\topaz\certs - cert files
- $HOME\AppData\Local\topaz\db - directory files
- $HOME\.config\topaz\cfg - config files

If you used previous versions of Topaz, your configuration, database and cert files were stored in $HOME/.config/topaz If you want to keep using the same location to store your files with any newly generated configuration you can export

export TOPAZ_CERTS_DIR=$HOME/.config/topaz/certs
export TOPAZ_DB_DIR=$HOME/.config/topaz/db

The topaz CLI could display the following warnings if you had older configuration setup:

You still have old db files in /home/<user>/.config/topaz/db ! 
Please see documentation on how to update your configuration: https://www.topaz.sh/docs/command-line-interface/topaz-cli/configuration

In this scenario you still have database files in the location used by the previous versions of Topaz CLI. To resolve this warning please move the files to the new location and update the matching configuration file or set the TOPAZ_DB_DIR environment variable as shown above.

This configuration file still uses TOPAZ_DIR environment variable. Please change to using the new TOPAZ_DB_DIR and TOPAZ_CERTS_DIR environment variables.

In this scenario you will need to update the configuration file to use the new TOPAZ_DB_DIR and TOPAZ_CERTS_DIR environment variables. The easiest method is to re-run the configure command to generate a new configuration file.

Config file documentation

A full description of the config format is available here.

Managing Topaz at scale

The Aserto Control Plane provides the central capabilities for managing policies, life-cycle management, identity data, and audit logs for the edge authorizer instances running as close to your application as possible. To connect to the Aserto Control Plane, Topaz is able to be deployed as an Aserto Edge Authorizer.

The easiest method to configure Topaz as an Edge Authorizer is to use the aserto CLI.

Annotated example

Below is an annotated sample of a config.yaml file.

# yaml-language-server: $schema=https://topaz.sh/schema/config.json
---
# config schema version
version: 2

logging:
  prod: true
  log_level: info

directory:
  db_path: ${TOPAZ_DB_DIR}/directory.db
  request_timeout: 5s # set as default, 5 secs.
  seed_metadata: false # deprecated in v3, with the introduction of manifest files, this always defaults to false.

# remote directory is used to resolve the identity for the authorizer.
remote_directory:
  address: "0.0.0.0:9292" # set as default, it should be the same as the reader as we resolve the identity from the local directory service.
  insecure: true

# default jwt validation configuration
jwt:
  acceptable_time_skew_seconds: 5 # set as default, 5 secs

api:
  health:
    listen_address: "0.0.0.0:9494"
  metrics:
    listen_address: "0.0.0.0:9696"
    zpages: true
  services:
    # configure the console service    
    console:
      gateway:
        listen_address: "0.0.0.0:8080"
        allowed_origins:
        - http://localhost
        - http://localhost:*
        - https://localhost
        - https://localhost:*
        - https://0.0.0.0:*
        - https://*.aserto.com
        - https://*aserto-console.netlify.app
        certs:
          tls_key_path: "${TOPAZ_CERTS_DIR}/gateway.key"
          tls_cert_path: "${TOPAZ_CERTS_DIR}/gateway.crt"
          tls_ca_cert_path: "${TOPAZ_CERTS_DIR}/gateway-ca.crt"
      grpc:
        listen_address: "0.0.0.0:8081"
        certs:
          tls_key_path: "${TOPAZ_CERTS_DIR}/grpc.key"
          tls_cert_path: "${TOPAZ_CERTS_DIR}/grpc.crt"
          tls_ca_cert_path: "${TOPAZ_CERTS_DIR}/grpc-ca.crt"
    # configure the reader interface
    reader:
      grpc:
        listen_address: "0.0.0.0:9292"
        # if certs are not specified default certs will be generate with the format reader_grpc.*
        certs:
          tls_key_path: "${TOPAZ_CERTS_DIR}/grpc.key"
          tls_cert_path: "${TOPAZ_CERTS_DIR}/grpc.crt"
          tls_ca_cert_path: "${TOPAZ_CERTS_DIR}/grpc-ca.crt"
      gateway:
        listen_address: "0.0.0.0:9393"
        # if not specified, the allowed_origins includes localhost by default
        allowed_origins:
        - http://localhost
        - http://localhost:*
        - https://localhost
        - https://localhost:*
        - https://0.0.0.0:*
        - https://*.aserto.com
        - https://*aserto-console.netlify.app
        # if no certs are specified, the gateway will have the http flag enabled (http: true)
        certs:
          tls_key_path: "${TOPAZ_CERTS_DIR}/gateway.key"
          tls_cert_path: "${TOPAZ_CERTS_DIR}/gateway.crt"
          tls_ca_cert_path: "${TOPAZ_CERTS_DIR}/gateway-ca.crt"
        http: false
        read_timeout: 2s # default 2 seconds
        read_header_timeout: 2s
        write_timeout: 2s
        idle_timeout: 30s # default 30 seconds  
    # configure the writer interface    
    writer:
      grpc:
        listen_address: "0.0.0.0:9292"
        certs:
          tls_key_path: "${TOPAZ_CERTS_DIR}/grpc.key"
          tls_cert_path: "${TOPAZ_CERTS_DIR}/grpc.crt"
          tls_ca_cert_path: "${TOPAZ_CERTS_DIR}/grpc-ca.crt"
      gateway:
        listen_address: "0.0.0.0:9393"
        allowed_origins:
        - http://localhost
        - http://localhost:*
        - https://localhost
        - https://localhost:*
        - https://*.aserto.com
        - https://*aserto-console.netlify.app
        certs:
          tls_key_path: "${TOPAZ_CERTS_DIR}/gateway.key"
          tls_cert_path: "${TOPAZ_CERTS_DIR}/gateway.crt"
          tls_ca_cert_path: "${TOPAZ_CERTS_DIR}/gateway-ca.crt"
        http: false
        read_timeout: 2s
        read_header_timeout: 2s
        write_timeout: 2s
        idle_timeout: 30s
    # configure the model interface    
    model:
      grpc:
        listen_address: "0.0.0.0:9292"
        certs:
          tls_key_path: "${TOPAZ_CERTS_DIR}/grpc.key"
          tls_cert_path: "${TOPAZ_CERTS_DIR}/grpc.crt"
          tls_ca_cert_path: "${TOPAZ_CERTS_DIR}/grpc-ca.crt"
      gateway:
        listen_address: "0.0.0.0:9393"
        allowed_origins:
        - http://localhost
        - http://localhost:*
        - https://localhost
        - https://localhost:*
        - https://*.aserto.com
        - https://*aserto-console.netlify.app
        certs:
          tls_key_path: "${TOPAZ_CERTS_DIR}/gateway.key"
          tls_cert_path: "${TOPAZ_CERTS_DIR}/gateway.crt"
          tls_ca_cert_path: "${TOPAZ_CERTS_DIR}/gateway-ca.crt"
        http: false
        read_timeout: 2s
        read_header_timeout: 2s
        write_timeout: 2s
        idle_timeout: 30s
    # configure the exporter service    
    exporter:
      grpc:
        listen_address: "0.0.0.0:9292"
        certs:
          tls_key_path: "${TOPAZ_CERTS_DIR}/grpc.key"
          tls_cert_path: "${TOPAZ_CERTS_DIR}/grpc.crt"
          tls_ca_cert_path: "${TOPAZ_CERTS_DIR}/grpc-ca.crt"
      gateway:
        listen_address: "0.0.0.0:9393"
        allowed_origins:
        - http://localhost
        - http://localhost:*
        - https://localhost
        - https://localhost:*
        - https://*.aserto.com
        - https://*aserto-console.netlify.app
        certs:
          tls_key_path: "${TOPAZ_CERTS_DIR}/gateway.key"
          tls_cert_path: "${TOPAZ_CERTS_DIR}/gateway.crt"
          tls_ca_cert_path: "${TOPAZ_CERTS_DIR}/gateway-ca.crt"
        http: false
        read_timeout: 2s
        read_header_timeout: 2s
        write_timeout: 2s
        idle_timeout: 30s
    # configure the importer service    
    importer:
      grpc:
        listen_address: "0.0.0.0:9292"
        certs:
          tls_key_path: "${TOPAZ_CERTS_DIR}/grpc.key"
          tls_cert_path: "${TOPAZ_CERTS_DIR}/grpc.crt"
          tls_ca_cert_path: "${TOPAZ_CERTS_DIR}/grpc-ca.crt"
      gateway:
        listen_address: "0.0.0.0:9393"
        allowed_origins:
        - http://localhost
        - http://localhost:*
        - https://localhost
        - https://localhost:*
        - https://*.aserto.com
        - https://*aserto-console.netlify.app
        certs:
          tls_key_path: "${TOPAZ_CERTS_DIR}/gateway.key"
          tls_cert_path: "${TOPAZ_CERTS_DIR}/gateway.crt"
          tls_ca_cert_path: "${TOPAZ_CERTS_DIR}/gateway-ca.crt"
        http: false
        read_timeout: 2s
        read_header_timeout: 2s
        write_timeout: 2s
        idle_timeout: 30s

    # configure the authorizer    
    authorizer:
      needs:
        - reader
      grpc:
        connection_timeout_seconds: 2
        listen_address: "0.0.0.0:8282"
        certs:
          tls_key_path: "${TOPAZ_CERTS_DIR}/grpc.key"
          tls_cert_path: "${TOPAZ_CERTS_DIR}/grpc.crt"
          tls_ca_cert_path: "${TOPAZ_CERTS_DIR}/grpc-ca.crt"
      gateway:
        listen_address: "0.0.0.0:8383"
        allowed_origins:
        - http://localhost
        - http://localhost:*
        - https://localhost
        - https://localhost:*
        - https://0.0.0.0:*
        - https://*.aserto.com
        - https://*aserto-console.netlify.app
        certs:
          tls_key_path: "${TOPAZ_CERTS_DIR}/gateway.key"
          tls_cert_path: "${TOPAZ_CERTS_DIR}/gateway.crt"
          tls_ca_cert_path: "${TOPAZ_CERTS_DIR}/gateway-ca.crt"
        http: false
        read_timeout: 2s
        read_header_timeout: 2s
        write_timeout: 2s
        idle_timeout: 30s

# provide configuration for OPA
opa:
  instance_id: "-"
  graceful_shutdown_period_seconds: 2
  # max_plugin_wait_time_seconds: 30 set as default
  local_bundles:
    # you can specify a directory to read local rego files
    paths: []
    skip_verification: true
  config:
    services:
      # configure the GitHub Container Registry as a bundle source
      ghcr:
        url: https://ghcr.io
        type: "oci"
        response_header_timeout_seconds: 5
    bundles:
      # configure the "todo" bundle
      todo:
        service: ghcr
        # OCI image path
        resource: "ghcr.io/aserto-policies/policy-todo:latest"
        persist: false
        config:
          # how often to poll for a new image version
          polling:
            min_delay_seconds: 60
            max_delay_seconds: 120

Managing topaz configurations​

Generating a config file​

Named configurations​

Topaz CLI paths and environment variables​

Config file documentation​

Managing Topaz at scale​

Annotated example​