Skip to content

You are viewing documentation for Immuta version 2023.4.

For the latest version, view our documentation for Immuta SaaS or the latest self-hosted version.

cancel

Manage Your Immuta Instance

Audience: Data Owners and Governors

Content Summary: This page details the immuta command, its subcommands and arguments, and the workflow for cloning an instance and using the Immuta API.

Command Overview: immuta

This command allows you to manage your instance of Immuta by creating data sources, projects, policies, and purposes. The table below illustrates the immuta subcommands and arguments.

Subcommands Description Argument(s)
api Make an authenticated Immuta API request. endpoint
clone Clone all data sources, projects, purposes, and policies information into files. directory path
completion Generate shell completion scripts for Immuta CLI commands. bash, zsh, fish, or powershell
configure Specify an Immuta instance url and API Key to be saved to the Immuta configuration file. instance url and Immuta API key
datasource Manage data sources. list, delete, rename, and save
policy Manage Global Policies. list, delete, rename, and save
project Manage projects. list, delete, rename, and save
purpose Manage purposes. list, delete, and save
version The version of the Immuta CLI. n/a

To view a list of the commands available in your current Immuta CLI version, run immuta with no additional arguments.

Options

Options you can specify with the immuta command include

  • --config string: Specify the configuration file name and where it will be saved. (The default is $HOME/.immutacfg.yaml.)
  • -h or --help: Get more information about the command.
  • -p or --profile string: Specify the profile for what instance or API the CLI will use.

Clone Your Instance: immuta clone

GOVERNANCE Permission

You need the GOVERNANCE permission in Immuta to run this command.

If you have an Immuta instance that was set up without using the API, you can use the immuta clone command to save all your data sources, projects, policies, and purposes as payloads:

immuta clone <outputDirPath>

This command will create valid V2 API YAML files for all your data sources, projects, policies, and purposes. Within these files, database passwords and user files (such as a BigQuery auth file) will be removed; instead passwords will appear as {{EnvVar "dbPass"}}. The CLI will then read the environment variable dbPass to fill in the password if you use the cloned payload to create or update a data source. File contents will appear as {{ReadFile "<filePath>"}}, and then the CLI will read the file at the path and replace the value when commands are run.

Options

  • --force: Overwrite existing output directory targets. If this flag is omitted, you will receive an error when the output directory exists and is not empty.
  • -h or --help: Get details about the command.

Limitations

  • Tags for data sources and projects are not returned.
  • Data sources will not have the sources field, so if these payloads are used in create commands, all possible tables will be created as data sources.

immuta api

This command makes an authenticated HTTP(s) request to the Immuta API and prints the response. The default HTTP request method is GET, but POST is used if any parameters were added. You can override the method with --method:

immuta api <endPoint> [--method httpMethod] [--input <filePath>] [--body body] [--data key=value] [--raw-data key=value] [--header key:value] [--query key=value] [--path-param key=value] [--outputTemplate string]

Options

  • -b, --body string: Unmodified string to be sent as payload body.
  • -d, --data key=value: Add a typed parameter in key=value format. The --data flag behaves like --raw-data, with type conversion based on the format of the value. Literal values, true, false, null, and integers are converted to appropriate JSON types. This will be sent in as the request payload.
  • --data-raw key=value: Add a string parameter in key=value format. The --data flag behaves like --raw-data, with type conversion based on the format of the value. Literal values, true, false, null, and integers are converted to appropriate JSON types. This will be sent in as the request payload.
  • -H, --header key:value: Add an HTTP request header in key:value format.
  • -h, --help: Get details about the command.
  • --input <filepath>: A raw request body may be passed from the outside via the file specified to use as body for the HTTP request. Pass in '-' for standard input.
  • -X, --method string: The HTTP method for the request (default GET).
  • -P, --path-param key=value: Add a string parameter in key=value format. Will replace {key} in the url with value.
  • -q, --query key=value: Add a string parameter in key=value format. The key value pairs are serialized into URL query parameters.
  • -t, --outputTemplate string: Format the response using a Go template. The provided Go template is rendered using the JSON data as input. For the syntax of Go templates, see this document.

Examples

The documentation below provides descriptions and examples of immuta api options.

# list tags
$ immuta api tag

# list tags use query string to filter results
$ immuta api tag -q searchText=Discovered -q limit=10

# template the response using a Go template. This will print all tags new line separated.
$ immuta api tag -q limit=10 --template \
    '{{range .}}{{.name}}{{"\n"}}{{end}}'

# Run column detection on specified table
$ immuta api dataSource/detectRemoteChanges -X PUT -d table=tableName -d schema=schemaName

# the above command is the same as
$ immuta api dataSource/detectRemoteChanges -X PUT --body '{"table": "tableName", "schema", "schemaName"}'

# set a user's current project - replace templated values in path
$ immuta api project/current/{projectId} -P projectId=1 -X POST

# the above command is the same as
$ immuta api project/current/1 -X POST