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 CI/CD is used to implement, and deliver code changes more frequently and reliably.

Styra's policies can be evaluated during a CI/CD pipeline, similar to 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.

Installing Policy Checks into a CI/CD Pipeline

Install the policy checks into your CI/CD pipeline.

  1. Create an API Token.

    For example, if the 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.

  4. Configure the the policy rules for Enforce mode.

  5. Promote the policy for the Styra CLI to download that particular policy version.

  6. 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://<das-id>.styra.com.
    • files is the list of globs describing the files you want to run against policy.
  7. 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.

  8. 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 Styra CLI page.

  9. (Optional) 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 <das-id>.styra.com -t <from step1>

    The $HOME directory is mounted into /home/styra inside the Docker container. The Styra CLI stores your input <das-id> and token inside the $HOME directory.

  10. Run policy checks.

    Validate Kubernetes configuration files in your repository. If you are not using .styra.yaml, set the following environment variables: STYRA_ORGANIZATION_ID and STYRA_TOKEN.

    For example:

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

    If you want to use a configuration file, mount your home directory to /home/styra inside the container. Mount your repository anywhere by using your token from the Styra CLI. Run the Styra CLI validate check-local command with the -r parameter to specify the location on your mounted repository.

    When you run the Styra 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.
  11. 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, in order to run the Styra CLI.

name: styra validate unit-test
description: 'exec styra validate unit-test'
runs:
using: docker
image: styra/cli:0.7.0
args:
- validate
- unit-test
- -d

Save your .yaml files in the repository path: .github/actions/styra.action.yaml.

Workflow

caution

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

Save your .yaml files in the repository path: .github/workflows/acme.styra.com.yaml.

important

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 the GitHub actions creating encrypted secrets section.

Additional Information

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 command 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.