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