Atlas CLI#

The Starburst Atlas command line interface (CLI) provides a terminal-based interface for registering types and metadata objects to Apache Atlas.

Requirements#

The Atlas CLI requires Java version 17 or later on the PATH. The CLI is distributed as a self-executing JAR file, which means it acts like a normal UNIX executable.

Installation#

  1. To download the Atlas CLI file, contact Starburst Support.

  2. Support provides access to a JAR file named starburst-atlas-cli-nnn-executable.jar where nnn is the version number.

  3. Rename this file to atlas-cli.

  4. Make it executable with chmod +x atlas-cli.

  5. Place it in a directory on the PATH, such as ~/bin, or /usr/local/bin.

Run the CLI with the help option to see the available commands. For details on each command, use one of help types, help cluster, or help catalog.

Authentication#

Specify your Atlas username with the --user option. If your Atlas service requires password authentication, use the --password option to have the CLI prompt for a password. You can set the ATLAS_PASSWORD environment variable with the password value to avoid the prompt.

TLS/HTTPS#

If your Atlas server is TLS-enabled, uses a globally trusted certificate, and does not require client certificates, then the Atlas CLI can connect to it by specifying only the server’s https:// URL, along with the --user and --password parameters.

If your Atlas server uses a site-specific certificate, or does require client certificates, then provide an additional --ssl-configuration-file parameter that specifies the path to a required XML configuration file. The format of the XML file is the same as the one described for the Atlas plugin.

Kerberos#

If your Atlas server uses Kerberos authentication, specify the three --krb5* parameters like the following:

...
--krb5-config-path=/etc/krb5.conf \
--krb5-keytab-path=/etc/admin_atlas.keytab \
--krb5-principal=admin/atlas.cluster@EXAMPLE.COM

Commands#

The Atlas CLI implements the following commands.

Types create#

Use the types create command to upload Atlas type definitions for SEP objects onto your Atlas server. You can override existing definitions with the --override option.

atlas-cli types create --server https://atlas.example.com:21000 --user admin --password

Atlas types are YAML files that define the structure of a data or metadata object. The atlas-cli command keeps an internal registry of Atlas-format types that describe SEP objects. The types create command uploads these eight types into the Atlas server.

Starburst defines Atlas types for the following SEP objects:

  • starburst_cluster

  • starburst_catalog

  • starburst_schema

  • starburst_schema_ddl

  • starburst_table

  • starburst_column

  • starburst_query

  • starburst_column_lineage

Once loaded, the web-based Atlas UI can select or search for these types, as shown in the following image:

Atlas UI showing SEP types

Cluster register#

Use the cluster register command to register a running SEP cluster’s name with your Atlas server. Specify the cluster name with the --cluster-name option; the name must match the atlas.cluster.name property you configured for your cluster.

atlas-cli cluster register --server https://atlas.example.com:21000 \
  --user admin --password --cluster-name fastqueries

Catalog register#

Use the catalog register command to load details about catalogs, schemas, tables, and columns onto your Atlas server. This is typically run initially to establish the SEP assets you want tracked. Thereafter, it is the role of the Atlas plugin to notify Atlas of changes in SEP objects. You can also re-register an asset to update its definition; if you specify an object that is already registered, the new command overrides and replaces the same object.

You must successfully run both types create and cluster register before running this catalog register command.

This command requires both the URL of the Atlas server and the JDBC URL for your SEP coordinator. For example:

atlas-cli catalog register --server https://atlas.example.com:21000 \
  --cluster-name fastqueries --user admin --password \
  --starburst-jdbc-url "jdbc:trino://cluster.example.com:8080?user=starburst_service" \
  --catalog example --schema customer --table nation

If the SEP cluster is TLS-enabled, specify additional attributes at the end of the starburst-jdbc-url parameter:

...8080?user=starburst_service&password=starburst_service_password&SSL=true

You can append further JDBC parameters to the starburst-jdbc-url as required.

The --schema and --table parameters are optional. That is, a single command can register an entire catalog, in which case, all schemas and tables in that catalog are registered. Or you can specify an individual catalog.schema, or down to a catalog.schema.table.

Options for catalog register#

Option name

Description

Required

user

Atlas username.

yes

password

Specifies whether to prompt for the Atlas username password.

no

cluster-name

Name of the SEP cluster. Must match the value of the atlas.cluster.name configuration property.

yes

starburst-jdbc-url

JDBC URL for the SEP cluster.

yes

catalog

Name of the catalog to load into Atlas.

yes

schema

Pattern of schema names to load into Atlas.

no

table

Pattern of table names to load into Atlas.

no

ssl-configuration-file

Path to a TLS configuration XML file as described for the Atlas plugin.

no

krb5-config-path

Path to a Kerberos configuration file. Default: etc/krb5.conf.

no

krb5-keytab-path

Path to a Kerberos key table file. Default: etc/krb5.keytab.

no

krb5-principal

Principal name on the Atlas server in standard Kerberos format.

no