Skip to content

You are viewing documentation for Immuta version 2023.1.

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

Automation through Declarative, Source-Controlled Files and the Immuta Command Line Interface

Prerequisites: Before using this walkthrough, please ensure that you’ve first completed


While the Immuta user interface is a powerful tool to demonstrate to legal, compliance, and other leadership what and how policy is being enforced in a human-consumable manner, data engineering teams do not want to spend time clicking buttons in a user interface.

Instead, data engineering teams want policy enforcement to fit cleanly into their existing automation workflows. Immuta enables this through what we term policy-as-code. This is very similar to the infrastructure-as-code concepts you may be familiar with. With Immuta policy-as-code, customers can construct declarative files that represent Immuta state, store those in a Git repo where changes can be managed through pull requests, and push those files to Immuta through the Immuta CLI.

Business Value

This feature allows data engineering teams to build automation around all they do with policy while at the same time proving compliance through the Immuta user interface (without having to actually touch the user interface to manage policy).

Because of this, the business reaps

  • Increased revenue: accelerate data access / time-to-data, all processes around policy can be automated.
  • Decreased cost: operating efficiently at scale, automation, automation, and more automation!
  • Decreased risk: reduces humans-in-the-loop through code automation which decreases errors.

Using the Immuta CLI

Assumptions: Your user has the following permissions in Immuta (note you should have these by default if you were the initial user on the Immuta install):

  • GOVERNANCE: in order to build policy on any table.

First let’s install the CLI:

  1. Navigate to the Immuta Releases page and log in with your Immuta Account credentials. If you get an access denied, please contact your Immuta support team to ensure you have the proper access level.
  2. Scroll to the All Archives section and use the username and password displayed there to log in to the Immuta Archives site.
  3. Select the folder of the current release and download the binary zip file corresponding to your system architecture.
  4. Unzip the file and add the binary to a directory in your system's $PATH.

Now let’s configure the CLI:

  1. First create an API key in Immuta.
    1. Log in to Immuta with your user with GOVERNANCE permission.
    2. Click on your profile icon in the upper right corner. (It should be the first letter of your first name.)
    3. Click Profile.
    4. Click the API keys tab.
    5. Click Generate Key.
    6. Select Current Project (none) for your project.
    7. Name the key CLI.
    8. Copy the API key and save it for the next step.
  2. Open a terminal and run immuta configure.
  3. Enter the URL of your Immuta instance in the interactive prompt.
  4. Enter your Immuta API Key from the previous step in the interactive prompt.
  5. You can see your configuration by examining the file saved at ~/.immutacfg.yaml.

For full details on how to use the Immuta CLI/API please refer to the Immuta documentation, but here’s a simple walkthrough:

  1. Since we already have an Immuta instance set up we can use the immuta clone command to save all your data sources, projects, policies, and purposes as payloads. Options you can specify to get more information about this command include h or --help:
    1. From the terminal, run immuta clone <outputDirPath>
  2. You can look in that directory and see there are four folders: data, policy, project, purpose.
  3. Go look at all the files in the policy folder.
  4. Remember, before starting this walkthrough we asked that you complete the Separating Policy Definition from Role Definition: Dynamic Attributes walkthrough. Assuming you did, you should at minimum see the following file: RLS-Walkthrough.yaml.
    • Note: If you named that policy something different in the walkthrough, the file name will be that instead of RLS-Walkthrough.
  5. Open the RLS-Walkthrough.yaml file in your editor of choice.
  6. Edit the file to change staged: false to staged: true.
  7. Save the file.

Now let’s push that change to your Immuta instance:

  1. From the terminal, run immuta policy save <outputDirPath/policy/RLS-Walkthrough.yaml>.
  2. Now go back to the Immuta UI.
  3. Click the Policies icon in the left sidebar.
  4. Look at the RLS Walkthrough policy; it should now be staged.
  5. Now, rather than changing that policy back to active in the UI, do it through the yaml file to ensure that those files remain your single source of truth:
    1. Open the RLS-Walkthrough.yaml file in your editor of choice.
    2. Edit the file to change staged: true to staged: false.
    3. Save the file.
    4. From the terminal, run immuta policy save <outputDirPath/policy/RLS-Walkthrough.yaml>.

It’s recommended that you source control these files and push when necessary through the Immuta CLI using automated CI/CD workflows.


McKinsey has a great article that describes this anti-pattern and the need for automation:

  • Anti-pattern: “Existing cybersecurity architectures and operating models break down as companies adopt public-cloud platforms. Why? Almost all breaches in the cloud stem from misconfiguration, rather than from attacks that compromise the underlying cloud infrastructure.”

  • Solution: “Security as Code (SaC) requires highly automated services that developers can consume via APIs. This, in turn, requires behavioral changes in security, infrastructure, and application-development teams. The security organization must move from a reactive, request-based model to one in which they engineer highly automated security products.”

  • Benefits:

    • "The first benefit of SaC is speed. To fully realize the business benefits of the cloud, security teams must move at a pace they are unaccustomed to in on-premises environments. Manual intervention introduces friction that slows down development and erodes the cloud’s overall value proposition to the business."

    • "The second benefit is risk reduction. On-premises security controls simply don’t account for the nuances of the cloud. Cloud security requires controls to move with a workload throughout its entire life cycle. The only way to achieve this level of embedded security is through SaC."

    • "Finally, SaC is a business enabler. Security and compliance requirements are becoming increasingly central to businesses’ core products and services. In this respect, SaC not only expedites time to market but expands opportunities for innovation and product creativity without compromising security.”

Next Steps

Feel free to return to the POV Guide to move on to your next topic.