Skip to main content

Styra Link Workflow

The Styra Link Workflow is focused on the lifecycle of policies in a Styra DAS system. First, a new System is initialized and installed. Then policy code cycles through authoring, testing, validating, and deployment. Styra Link provides commands to facilitate each step of this workflow.

Initialize the System​

After you have installed and configured the Styra CLI (see the installation page), you are ready to get started with Styra Link. The first step is to initialize a System, linking your local policies with a Styra DAS System. You can link either a new System or an existing System.

important

Before you run the first command, though, you must make sure you are sitting in a directory dedicated to this styra link project. In the most common scenario—where you intend to integrate with git—this would just be the root of your git repository.

To initialize a System, run this to start an interactive dialog:

styra link init

Alternatively, you can provide all the answers via command-line flags rather than responding to interactive prompts.

  • Name: The name of the Styra Link project. This will also be the name of your System in Styra DAS. If you are linking an existing System, the name must match the System's name in Styra DAS so that Styra Link can find and connect to it.
  • Type: The type of project you create (for example, Envoy, Kubernetes, or Terraform). The interactive prompt will provide a list of options to choose from.
  • Policy Storage Path: The directory path where your policy code will live inside your repository. A directory is created with this name, and all policies are contained within it. Styra Link is designed to live within a larger code base, for example, an application or Terraform project. You can choose any path or use the default directory authorization.
  • Git Integration: You can configure Styra DAS Git integration at initialization time, or you can set it up later using the styra link config git command.

Once your project is initialized, you will see a new .styra directory and the policy directory you chose (in this example, authorization). The .styra directory contains a project-specific configuration file (config) and resources Styra Link needs to connect your local project with Styra DAS.

note

This .styra directory is project-specific to this Styra Link project, and the config file within points to your Styra Link project. This is distinct from the global .styra directory in your home directory that was created by the styra configure command, and which points to your DAS tenant.

Inside your policy directory (located at the policy storage path you chose), you will see both a bundle folder and a src folder.

  • bundle: A local copy of the bundle that Styra DAS sends to OPA. This includes any policy code from Stacks or Libraries. The bundle directory is added to .gitignore.
  • src: The directory where you author your policies.
note

Run styra link bundle update to apply changes from your ‘src’ directory to the local bundle. This is done automatically when running commands like ‘test’ and ‘validate’. If you have modified the bundle in Styra DAS (for example, adding a Stack to the System or adding a new Data Source), run styra link bundle update -r to refresh your local copy with a fresh one from Styra DAS.

Install the System​

A project initialized with a new System must be installed. Installing a System allows Styra DAS to manage policy decisions through OPA. The requirements will differ among System types. For example, an Envoy System requires running kubectl commands to add OPA and Envoy sidecars, while a Terraform System requires downloading a configuration file to use when validating the output of a Terraform plan. Each System has specific installation instructions.

To get installation instructions for your System run the following command:

styra link config install

Installation instructions are organized into different categories. Categories represent the different ways a System can be installed (for example, in a Kubernetes System you can install the System using kubectl, helm, helm3, or kustomize). Instructions are filterable by category, or you can use the --interactive flag to select an installation category interactively.

note

To uninstall your System styra link config uninstall provides the required commands. These are organized into categories similar to the install instructions. Depending on the installation category you used, use the corresponding uninstallation category when available to ensure everything is properly uninstalled.

Author Policies​

To author policies, you create, update, or delete Rego files inside the src directory using a code editor.

The CLI tool also supports adding library rules provided by Styra DAS with the styra link rules command. The search subcommand allows you to search through and get information about available rules, while the use subcommand will output the Rego snippet, which can be copied into your policy files. You can use the --interactive flag on either subcommand to interactively find an available rule.

To search for rules applicable to your System, run the following command:

styra link rules search

To use a rule you found by running search, run the following command:

styra link rules use [flags]

Unit Test your Policies​

Once you have updated your policy code, Styra Link allows you to run any unit tests you have authored without publishing the modified code to your Styra DAS System. Styra Link runs your unit tests in the context of your full policy bundle, including any Stack or Library Rego code.

To run your policy unit tests, run the following command:

styra link test

Validate Your Changes​

Validating policy changes against previously made decisions provides additional confidence in your Rego code. Styra DAS collects decisions from OPA and stores them. With Styra Link, you can evaluate the input from stored decisions against your locally updated policy code. This provides insight into what decisions would have been different if the new policy code had been in place at the time of the decisions.

To run previous decisions against your latest policy code, run the following command:

styra link validate decisions

Deploy New Policies​

Styra Link uses Styra DAS Git integration for policy deployment. Git integration can be configured when a System is initialized or set up using the styra link config git command.

To configure Git integration you will need a local Git repository, a remote Git repository (for example, GitHub), and your credentials for the remote repository (either HTTPS or SSH). Your local repository must reside at the root of your project alongside your .styra/ directory. This is how Styra Link understands the mapping of your authored policy files into Styra DAS. Styra Link Git configuration works best if your local repository already has the remote repository added before configuring Styra DAS Git integration.

To configure Git integration for a Styra Link project, run the following command:

styra link config git

  • URL: The remote repository URL. This can be either HTTPS or SSH style, depending on the type of authentication you choose.
  • Username: The username for an HTTPS Git connection.
  • Secret: The password or token for an HTTPS Git connection.
  • Private Key File Path: The location of the SSH private key file for an SSH Git connection.
  • Passphrase: The private key passphrase for an SSH Git connection. Leave this blank or use the --skip-passphrase flag if your key does not require one.
  • Git Reference (how to sync your policies): You can have Styra DAS track a Git branch, use a specific Git SHA hash, or use a Git tag when syncing policies.

Once your System is configured for Git, your policies are compiled into a bundle and sent to all configured OPAs based on your chosen Git reference. If you configure a ‘branch’ reference, any changes pushed to that branch will trigger a new bundle build. If you configure a Git commit SHA hash or a tag, you must update the configuration to use a new hash or tag. Once the configuration is updated, Styra DAS will build and deploy a new bundle.

To update your Git reference, you do not need to provide Git credentials again. The --update-ref flag allows reconfiguration of the reference used only. When this option is used, all URL and credential input is ignored.

To reconfigure your git reference only, run the following command:

styra link config git --update-ref

note

If you try to initialize a System with Styra Link that already has Git configuration, it will fail. The Styra Link workflow expects a specific setup for Git. If you would like to reconfigure a System to work with Styra Link, you will first need to remove the current Git configuration, initialize the System with Styra Link, and then configure Git syncing. This ensures file mappings for Styra DAS are correct in the Git repository.

Compliance Validation​

If you are using Styra Link with a System type that supports compliance monitoring (for example, Kubernetes), you can run a compliance check against your locally updated files by running the following command:

styra link validate compliance

note

Compliance checks your System’s resources against the currently authored rules set to monitor or enforce mode. If a resource exists that would have been denied by any of those rules, it will show up as a compliance violation. To validate compliance against a specific standard, author rules to enforce that standard and then use the compliance tooling to check the current state of your System against those rules.

Releasing policy code using CI/CD​

You can use Styra Link within a continuous deployment system using the styra link publish command. This example uses GitHub actions, but this concept can be adapted for most available continuous deployment systems.

To deploy code on publish using GitHub actions, first create a new GitHub workflow in your project:

.github/workflows/release-policy.yaml

name: Deploy updated policy code

on:
  release:
  types: [published]

env:
  STYRA_ORGANIZATION_ID: example.styra.com
  STYRA_TOKEN: ${{ secrets.STYRA_TOKEN }}
  STYRA_URL: https://example.styra.com

jobs:
  deploy-policy:
  runs-on: ubuntu-latest
  steps:
    - uses: actions/checkout@v3
    - name: deploy-policy
      uses: docker://styra/cli:latest
      with:
        args: link config git --update-ref --tag ${{  github.ref_name }}

This simple workflow configures the Styra CLI using environment variables. The Styra CLI Docker container runs the Styra Link command, which updates the Git reference to the newly published release tag. Note that it is best not to use the ‘latest’ tag in your workflow. You should use the tag corresponding to the Styra CLI version you have tested with your project. Once the workflow is defined, commit it to your GitHub remote repository.

With the workflow in place at GitHub, whenever a new release is published the workflow runs and updates the Styra DAS Git reference to track the release tag. Standard Git tags not associated with a GitHub release will not deploy new policy code.