DOCSEARCHbyAlgolia
Submit Docs

Topaz Documentation

repository·main·Indexed 23 days ago

https://github.com/aserto-dev/topaz

Documentation for Topaz, featuring the topazd service and topaz CLI. Includes guides on configuration via YAML and environment variables, deployment using Docker Compose, and the use of the topaz-backup utility for BoltDB storage. Covers the Aserto Edge sync plugin, Topaz File Decision Logger, and experimental features like Edit Mode enabled via the TOPAZ_FFLAG environment variable.

Tokens
20.3K
Snippets
20
Records
173
Agent score
80%

What's inside Topaz

  1. Overview of the XDG package

    main
    The xdg package provides an adaptation of the adrg/xdg library. It is designed to handle Unix directory locations, specifically optimized for use on macOS. Developers can use this package to resolve standard XDG base directory paths (such as config, cache, and data directories) in a way that respects platform-specific conventions.

  3. Configure Topaz using environment variables

    main

    The topazd service uses the spf13/viper library, which allows you to override any configuration parameter using environment variables.

    By default, configuration files generated by the topaz CLI use the TOPAZ_ prefix for these variables.

    Warning: The TOPAZ_DIR environment variable, which was used as the root location in older versions of Topaz, is no longer supported.

  4. Understand Topaz configuration structure

    main

    Topaz configuration is organized into three main sections:

    1. Common configuration: Core settings for the Topaz service.
    2. Auth configuration (optional): Settings related to authentication and authorization.
    3. Topaz File Decision Logger configuration (optional): Settings for the decision logging component.

  5. Create a new Topaz configuration template

    main

    You can generate a new configuration file using the topaz CLI. This is useful for creating a starting template based on a specific resource and policy. Use the --stdout flag to output the configuration to the terminal instead of writing it to a file.

    topaz config new --name my-topaz --resource ghcr.io/aserto-policies/policy-rebac:latest --policy rebac --stdout

  6. Enable Topaz Edit Mode using feature flags

    main

    Topaz Edit Mode allows you to construct inline JSON request payloads using a text editor instead of typing them directly in the terminal.

    To use this feature, you must meet these requirements:

    1. Version: Topaz version 0.32.6 or higher.
    2. Feature Flag: You must set the TOPAZ_FFLAG environment variable to 1.

    When enabled, commands that support the --edit or -e flag will open the request template in your configured editor. Once you save and close the editor, the request is parsed and sent to the service.

    export TOPAZ_FFLAG=1
topaz directory check --edit --insecure

  7. Discover Topaz directory locations

    main

    Use the topaz CLI to inspect your current environment settings and discover where Topaz is looking for configuration, data, and runtime files.

    To see the resulting directory locations based on your current environment variables, run:

    topaz config info environment

    To see a full breakdown of environment, configuration, runtime, and service settings, run:

    topaz config info
    topaz config info environment

topaz config info

  9. Use Edit Mode with Directory, Authorizer, and Config commands

    main

    When TOPAZ_FFLAG=1 is set, the following command groups support the --edit or -e flag to open a request template in your editor:

    Directory Commands

    • topaz directory get object [--edit | e]
    • topaz directory set object [--edit | e]
    • topaz directory delete object [--edit | e]
    • topaz directory list objects [--edit | e]
    • topaz directory get relation [--edit | e]
    • topaz directory set relation [--edit | e]
    • topaz directory delete relation [--edit | e]
    • topaz directory list relations [--edit | e]
    • topaz directory check [--edit | e]
    • topaz directory search [--edit | e]

    Authorizer Commands

    • topaz authorizer eval [--edit | e]
    • topaz authorizer query [--edit | e]
    • topaz authorizer decisiontree [--edit | e]
    • topaz authorizer get-policy [--edit | e]
    • topaz authorizer list-policies [--edit | e]

    Config Commands

    The topaz config edit command allows viewing and updating configuration files directly in your editor:

    • topaz config edit [ config name | defaults ] (defaults to the active config)
    • topaz config <config-name> (e.g., topaz config gdrive opens the gdrive configuration file)
    • topaz config defaults (opens the topaz.json file containing default settings)

  10. Migrate from aserto_decision_log to topaz_file_decision_logger

    main

    If you are upgrading from the deprecated aserto_decision_log plugin, you must perform two steps:

    1. Replace the plugins.aserto_decision_log section with the plugins.topaz_file_decision_logger section.
    2. Remove the top-level decision_logger section entirely.

    Deprecated Configuration Example:

    opa:
  config:
    plugins:
      aserto_decision_log:
        enabled: true
        policy_info:
          policy_id: ""
          policy_name: "rebac"
          instance_label: ""
          registry_service: "ghcr.io"
          registry_image: "aserto-policies/policy-rebac"
          registry_tag: "latest"
          digest: ""

decision_logger:
  type: file
  config:
    log_file_path: "/tmp/decisions-0.33.12.json"
    max_file_size_mb: 100
    max_file_count: 2
    # New configuration structure
opa:
  config:
    plugins:
      topaz_file_decision_logger:
        enabled: true
        # ... other settings

  11. Use Topaz Feature Flags via TOPAZ_FFLAG

    main

    Topaz uses the TOPAZ_FFLAG environment variable to enable experimental or in-development features. This variable accepts an unsigned 64-bit integer bitmask.

    To enable the current available feature (editor options), set TOPAZ_FFLAG=1.

    export TOPAZ_FFLAG=1

  12. Execute a backup using the boltdb plugin

    main

    To perform a backup of a BoltDB database, use the boltdb command with the --db-file and --backup-dir flags.

    Important Requirements:

    • The topaz-backup command MUST be executed on the same machine where the topazd process is running.
    • Because topazd holds an exclusive read-write connection to the database, topaz-backup opens a read-only connection to copy the content to a new backup file and flushes the state to disk upon completion.
    topaz-backup boltdb \
--db-file ~/.local/share/topaz/db/gdrive-v33.db \
--backup-dir ~/.local/share/topaz/backup