Setup Tools

This guide describes how to use the setup command to manage Apache Polaris configuration using an infrastructure-as-code approach. Define your Polaris configuration in a single YAML file and apply it with a single command.

This command supports bootstrapping new environments and exporting existing configurations for reuse or version control.

Exporting Your Configurationđź”—

If you already have an Apache Polaris environment, you can export its current state to a YAML file using the export subcommand:

1polaris setup export > polaris_bootstrap.yaml

This generates a readable YAML file containing principals, principal roles, catalogs, and their associated namespaces and catalog roles.

Applying a Configurationđź”—

Use the apply subcommand to bootstrap a new environment or extend an existing one. The command reads your YAML file and performs the necessary create and grant operations in the correct order.

Example Configurationđź”—

The following example simple-setup-config.yaml demonstrates the structure of a setup configuration file. For a complete reference of all supported options, see reference-setup-config.yaml.

 1# ==================================
 2#        Global Entities
 3# ==================================
 4principals:
 5  quickstart_user:
 6    roles:
 7      - quickstart_user_role
 8
 9principal_roles:
10  - quickstart_user_role
11
12# ==================================
13#     Catalog-Specific Entities
14# ==================================
15catalogs:
16  - name: "quickstart_catalog"
17    storage_type: "file"
18    default_base_location: "file:///var/tmp/quickstart_catalog/"
19    allowed_locations:
20      - "file:///var/tmp/quickstart_catalog/"
21    roles:
22      quickstart_catalog_role:
23        assign_to:
24          - quickstart_user_role
25        privileges:
26          catalog:
27            - CATALOG_MANAGE_CONTENT
28    namespaces:
29      - dev_namespace

Applying the Setupđź”—

Before making any changes, you can preview what will be executed using the --dry-run flag:

1polaris setup apply --dry-run site/content/guides/assets/polaris/simple-setup-config.yaml

Once satisfied, run the command to apply the changes:

1polaris setup apply site/content/guides/assets/polaris/simple-setup-config.yaml

Known Limitationsđź”—

The current implementation focuses on simplifying initial setup, with a few limitations to be aware of:

  • Non-declarative updates: The command is create-only. If an entity already exists, it will be skipped rather than updated. There is no state reconciliation yet.
  • Policy attachment export: Policy attachments are not included in setup export due to performance considerations. However, they can still be defined in YAML and applied during setup apply.
  • External catalog testing: Support for external catalogs (e.g., Hive Metastore) exists, but full end-to-end testing has not yet been completed. It is recommended to validate configurations in a non-production environment first.