Skip to main content

Policy Checks in CI/CD

This page describes an overview of the Continuous Integration and Continuous Delivery (CI/CD) pipeline, provides installation instructions to set up your own CI/CD pipeline to run policy checks by using Styra's pre-built integrations for GitHub and CircleCI, and explains the GitHub actions.

Overview

The Continuous Integration and Continuous Delivery (CI/CD) pipeline is one of the best practices for teams to implement, and deliver code changes more frequently and reliably.

Styra's policies can be evaluated during a CI/CD pipeline like a unit test.

For example, you can do the following in the Kubernetes use case.

  • Embrace GitOps and check the resources into Git, instead of giving application developers direct access to Kubernetes.
  • Check policies as a part of the CI/CD process, instead of checking the policy in the Kubernetes API server.

When changes are made on the files located in a repository, the CI/CD pipeline runs policy checks against the files in that repository and outputs the errors.

Install the Policy Checks

To install the policy checks into your CI/CD pipeline, do the following:

  1. Create an API Token.

    If this API token is used in a system with id abc123xyz, then you can restrict access to that particular system by setting the Allowed API paths value to ^/systems/abc123xyz$ and ^/bundles/systems/abc123xyz$.

  2. Create a Kubernetes System in the Styra DAS.

  3. Apply the policy rules. Now, check if the policy rules are in Enforce mode. Then promote the policy for the Styra CLI to download that particular policy version.

  4. Add .styra.yaml file to your Git repository that describes what policies you want to run over which files.

    For example:

    checks:
    all_envs:
    system_id: b52e42c6ab574d9ab8bc5e7a86ce72ea
    files:
    - k8s/*/*.yaml
    prod_and_staging_deployments:
    system_id: e57e9eb7d87d49ec83b95d4e4deeae87
    files:
    - k8s/prod/*-deployment.yaml
    - k8s/staging/*-deployment.yaml
    • all_envs and prod_and_staging_deployments are the names given to the policy checks. You can have many checks.
    • system_id is the name of the Styra system, which is displayed on the Settings tab located in https://styra-das-id.styra.com.
    • files is the list of globs describing the files you want to run against policy.
  5. The file path match reports whether the name matches with the shell file name pattern used in .styra.yaml. The following shows the pattern syntax:

    pattern:
    { term }
    term:
    '*' matches any sequence of non-Separator characters
    '?' matches any single non-Separator character
    '[' [ '^' ] { character-range } ']'
    character class (must be non-empty)
    c matches character c (c != '*', '?', '\\', '[')
    '\\' c matches character c
    character-range:
    c matches character c (c != '\\', '-', ']')
    '\\' c matches character c
    lo '-' hi matches character c for lo <= c <= hi

    The file path match requires pattern to match all of name, not just a substring.The only possible returned error is ErrBadPattern, when pattern is malformed.

6. Download the Styra CLI.

  • The container is located on hub.docker.com/r/styra/cli.

  • To download the Styra CLI, run the following command or equivalent.

    docker pull styra/cli

  • To see all the options, run the following command or equivalent.

    docker run styra/cli

  • Alternatively, you can also download the CLI binaries from the instructions listed on the CLI binaries page.

7. Optionally, you can create a Styra CLI configuration file with the token you created earlier. Choose one of the following ways to configure the Styra CLI.

Use environment variables
Use a configuration file

In a CI/CD system, Styra recommends using environment variables. However, for local use or if files are easier for your system, you can use the configure command to write a configuration file.

For example:

docker run -ti -v $HOME:/home/styra styra/cli configure -i styra-das-id.styra.com -t <from step1>

Here, you are mounting your $HOME directory into /home/styra inside the docker container. The CLI will store your input TENANT and token inside your $HOME directory.

8. Run policy checks.

Now, validate Kubernetes configuration files in your repository. If you are not using the configuration file created in Step 6, then you must set two environment variables: STYRA_ORGANIZATION_ID and STYRA_TOKEN.

For example:

docker run -it -v `pwd`:/repo -e 'STYRA_ORGANIZATION_ID=styra-das-id.styra.com' -e 'STYRA_TOKEN=<from step1>' validate check-local -r /repo

If you want to use a configuration file, then you must mount your home directory to /home/styra inside the container. Now, you can mount your repository anywhere by using your token from the CLI. Now, run the CLI’s validate check-local command with -r parameter to specify the location on your mounted repository.

    # When you run the CLI from the root of your repository:
docker run -ti -v $HOME:/home/styra -v `pwd`:/repo styra/cli validate check-local -r /repo

The following errors are reported:

    Check `prod_and_staging_deployments` failed

Found errors in the following files:
* k8s/prod/app-deployment.yaml
* k8s/prod/db-deployment.yaml

Error: 1 Check Failed

To display the full details to a JSON document, use the -o output-file.json flag.

When all checks pass, the following output is reported:

    Check `all_envs` passed: 138 files checked. All documents passed policy checks.
Check `prod_and_staging_deployments` passed: 26 files checked. All documents passed policy checks.

9. Check for error status.

If violations occur, the Styra CLI returns a 1; if there are no violations, it returns a 0.

echo $?

GitHub Actions

This section covers the definition and workflow for GitHub actions.

Definition

A GitHub action definition is a service provided by GitHub. You must copy and paste the following action definition into your repository, inorder to run the Styra CLI.

name: styra validate unit-test
description: 'exec styra validate unit-test'
runs:
using: docker
image: styra/cli:0.4.0-rc.1
args:
- validate
- unit-test
- -d

You can save your .yaml files in the repository path: .github/actions/styra.action.yaml.

Workflow

warning

The following workflow is specific to unit tests only.

The following shows the workflow for GitHub actions definition.

name: acme.styra.com
on:
pull_request:
types:
- opened
- synchronize
- reopened
jobs:
unit-tests:
name: unit-tests
runs-on: ubuntu-latest
env:
STYRA_ORGANIZATION_ID: acme.styra.com
STYRA_TOKEN: ${{ secrets.styra_token }}
steps:
- uses: actions/checkout@v2.1.0
- uses: ./.github/actions/styra_validate_unit-test

You can save your .yaml files in the repository path:.github/workflows/acme.styra.com.yaml.

!!! Important You must define the ENV variables based on your organization's ID. For example, if your organization's ID is XYZ, then change acme.styra.com to XYZ.styra.com

To create your secrets, see creating encrypted secrets section.

Further Reading

Styra policies are portable, this signifies you can run them at different enforcement points throughout your stack. You could run them on Kubernetes, in the CI/CD pipeline, and even on developer laptops. Decisions made by the validate check-local CLI are treated the same way as the decisions made by Kubernetes: they are visible in the decision log, are used in policy validation, and can be replayed through the UI. The CircleCI integration is available as an Orb packages: Styra-orb.

For detailed instructions on how to setup the Orb, see Styra Orb documentation.