Skip to main content

Use Git as Storage for Stacks

Styra supports using Git as storage for policies. Each stack can be configured with its own Git repository as storage.

git-storage is an internal functionality that coordinates all the activities between the Git repository and Styra DAS.

Using Git as storage also enables the following features:

  • Embrace the policy-as-code philosophy, allowing you to leverage the same source of truth for your policies that you have for your code: A Git repository.

  • Rollback policy changes using the same machinery you do for your other code: update the tip of main branch to a previous workable state.

  • Implement change control via peer-review using the Git-workflow provided by your organization.

Once you configure Git, you can use Styra DAS the same way you always have, except when you want to promote policies for distribution to OPA.

The following shows the policy-authoring flow without configuring git-storage:

  1. Make a policy change in the Styra editor.
  2. Promote the change. Styra stores the new policy in its backend.
  3. Styra distributes new policy to OPAs.

The following shows the policy-authoring flow when git-storage is configured, it assumes that main is the branch that is configured for tracking:

  1. Make a policy change in the Styra editor.
  2. Promote the change. Styra pushes this policy to a review branch on your private Git branch. This branch is named styra-{repo-path}-{basebranch}-stack-{user@domain.com}, where {repo-path} is the path configured for git, {basebranch} is the base branch name (typically "main"), and {user@domain.com} is the email of the user who created the branch.
  3. The team can review, test, and merge the private branch into main branch.
  4. Styra picks up the change in main branch and distributes the new policy to OPAs.
Figure 1 - Architecture with Git as a Policy BackendFigure 1 - Architecture with Git as a Policy Backend

Policy Versions​

The policy editor shows the following three different versions of policy with git-storage:

  • A main branch (called Enforced).
  • A private branch (called Branch).
  • A draft (called Draft).

The following shows the restrictions on the policy versions:

  • The Enforced and Branch versions are read-only. The read-only permission allows you to see the policy versions as they exist in the outside world. If required, you can also compare the policy versions. This acts as a starting point to write new policies.

  • Before you have a Draft, if you look at either the Enforced or Branch versions, and you try to make changes, then you must create a Draft with your changes.

  • When you already have a Draft, you must either publish it to your private branch or discard it before creating a new draft.

Transition to-and-from git-storage​

If you either enable git-storage or disable git-storage, there will be no disruption to the policies being distributed to the OPAs.

The following section shows you how to transition to-and-from git-storage.

Turn On git-storage​

  1. If you have already written, published, and distributed policies to OPA without git-storage.
  2. Enable git-storage on Styra.
  3. Styra fetches the tip of the main branch. If policies exist, then it copies them to the (non-Git) Styra policy backend. For Kubernetes, Styra copies the admission_control.rego and test.rego files.
  4. Styra always distributes the policy in the Styra backend to all OPAs. If your policy is already in the main branch, then that policy is distributed to the OPAs. If those policies are not already in the main branch, then your existing policy continues to be distributed to the OPAs.
info

When enabling git-storage, Styra does NOT automatically push the current policy into Git. But, you can use the Styra policy editor to push your current policy onto your private branch, and then use the standard Git workflow to merge the private branch into the main branch. Only once you can merge your private branch into the main branch. The main branch is distributed to OPA; until this distribution happens, the source of truth for policy is still the Styra backend."

Turn Off git-storage​

  1. If you have policies stored in Git, then it represents the main branch policies are distributed to OPAs.
  2. Disable git-storage on Styra.
  3. Styra will not copy the tip of the main branch into its (non-Git) policy backend. The policy in the main branch remains as the policy being distributed to the OPAs.
  4. If you make any more policy changes, then they are promoted directly to the non-Git policy backend, which makes them the version of policy distributed to the OPAs.

Git Configuration Options​

DAS allows you to configure a stack to use its own Git repository or to use the same repository as the Workspace.

Every stack has the option to configure with the Workspace Git repository settings. The changes to each stack’s policies are stored in the Workspace repository along with other Workspace files such as the labels and features policies for each system. If the Workspace is not configured to use a Git repository, then the FetchDB repository will be used to store these files instead. For more information, see using Git as storage in the Workspace level.

If you want stacks to use the Workspace repository, follow these instructions to configure each stack individually.

  • Under STACKS, select the stack you want to configure.
  • Click Settings tab.
  • Click Git Repository.
  • Enable the toggle switch Use workspace Git repository settings.
  • Configure Git Authentication.

If you want stacks to use a separate Git repository instead of the Workspace repository, follow these instructions to configure each stack individually.

  • Under STACKS, select the stack you want to configure.
  • Click Settings tab.
  • Click Git Repository.
  • Disable the toggle switch Use workspace Git repository settings.
  • Configure Git Authentication.

Configure Git Authentication​

Styra DAS supports either HTTPS or SSH authentication for Git. You can navigate to the Git settings dialog and select the Git authentication mode HTTPS or SSH.

HTTPS

  • Git username (required): Your Git username.

  • Git secret (required): The secret corresponding to your Git username.

  • Git repository (required): A Git HTTPS URL to your Git repository. For example: https://github.com/hooli/foo.git.

  • Git reference: Specify a tag or branch reference (defaults to refs/heads/master—the main branch).

  • Git commit SHA: Specify a commit SHA.

  • Repository path: (Optional) The subdirectory where you want to save the policies.

SSH

  • SSH key (required): A private SSH key. For example: The contents of ~/.ssh/id_rsa.

  • SSH key passphrase: (Optional) The passphrase specified at the time the private SSH key was created.

  • Git repository (required): A Git SSH URL to your Git repository. For example: git@github.com:hooli/foo.git.

  • Git reference: Specify a tag or branch reference (defaults to refs/heads/master—the main branch).

  • Git commit SHA: Specify a commit SHA.

  • Repository path: (Optional) The subdirectory where you want to save the policies.

Click the Save changes button.

important
  • Git reference and Git commit SHA are mutually exclusive, only one can be submitted per Git configuration.
  • For SSH configuration, the corresponding SSH public key must be configured on the Git service (GitHub, Bitbucket, and so on) in order for authentication to work.

Now, create a stack using the instructions listed on Create a Stack page. Once created, your stack is located under STACKS in the left panel of the Styra DAS GUI.

The following shows how to publish your stack policies to Git:

  1. Under STACKS, click the stack name for which you want to save policies in Git.

  2. Click the Settings tab.

  3. Check if the toggle switch is enabled for Git Repository to Use workspace settings.

  4. Modify one of the policies.

  5. Click the Publish button.

  6. Click the Push changes to review branch button.

  7. In the Push changes to review branch pop-up window, enter the commit message in the Summary and Details fields.

  8. Click the Push changes button.

  9. To review the branch, click on Branch button.

  10. Navigate to your repository to create a new pull request.

  11. Now, merge the pull request to view the policies for your stack-type in the policy folder located in your repository. In this case, you can view the validating policies for your stack-type in the policy folder.

Configure GitHub Repositories​

Use the following tips to find the required configuration for a GitHub repository:

  • Git secret: Styra recommends to use a GitHub Personal access token. You can generate a token at github.com/settings/token or by clicking through Your-picture and navigate to Settings >> Developer Settings >> Personal access tokens.

  • Git repository: To create a new Git repository, navigate to github.com/settings/token and click your profile icon located on the top-right of the page. To view your repositories, click Your repositories.

    • To add a new repository, click the New button.

    • In the new repository, enter the name of your new repository in the Repository name field, the Description field is optional.

    • Select Public (Anyone on the internet can see this repository and you can choose who can commit) or Private (You choose who can see and commit to this repository) based on your requirement.

    • Click the Create repository button.

tip

Navigate your repository on GitHub and copy the link provided for Clone with HTTPS. For example, navigate to github.com/hooli/policyrepoand click the Clone or Download button to copy the link provided for Clone with HTTPS.

Directory Layout in Git​

To add files directly to Git for a stack (Kubernetes or Envoy):

  • Configure git-storage as described above.
  • Merge files into Git while adhering to the directory structure in this section.

The package names for the Rego files mirror the directories to which they belong. For a given stack (Envoy stack or Kubernetes stack), the package inside of rules/rules.rego is called package rules, and the package inside of test/test.rego is called package test.

The synchronization mechanism for git-storage inspects the linked Git repository to detect any *.rego files present under preset paths. The path presets vary based on the type of each individual stack. The following section shows the directory layout in Git for git-storage to work in a stack.

caution

The synchronization mechanism ignores any files or packages present in the Git repository outside the well-known paths for the configured stack.

Stack-type Layouts​

This section shows the directory layout in Git for git-storage to work in a stack. All stacks are stored under the root directory stacks. The layout within each stack depends on the type of that stack (Kubernetes or Envoy)

The first stack below ca67cb... is a Kubernetes System. The second stack ea7787... is an Envoy System.

├── stacks
|   ├── ca67cb608bcc4354ae9c773369fc24a0      # Kubernetes system
│   │   ├── com.styra.kubernetes.mutating
│   │   |   ├── rules
│   │   │   |   └── rules
│   │   │   |       └── mutating.rego
│   │   |   └──test
│   │   |   |   └──test
│   │   |   |       └── test.rego
│   │   └── com.styra.kubernetes.validating
│   |   |   ├── rules
│   |   │   |   └── rules
│   |   │   |   |   └── validating.rego
│   |   |   |   └──test
│   |   |   |   |   └──test
│   |   |   |   |   |   └── test.rego
|   ├── ea778774e2b44e58899cc478edfed9d8      # Envoy system
|   |   └── selectors
|   |       └── selector.rego
|   |   ├── com.styra.envoy.egress
│   |   |   ├── rules
│   │   |   |   └── rules
│   │   |   |   |   └── rules.rego
│   |   |   └──test
│   |   |   |  └──test
│   |   |   |  |  └── test.rego
|   |   ├── com.styra.envoy.ingress
│   |   |   ├── rules
│   │   |   |   └── rules
│   │   |   |   |   └── rules.rego
│   |   |   └──test
│   |   |   |  └──test
│   |   |   |  |  └── test.rego

Create a Git-backed Stack through the API​

To create a Git-backed stack through the API:

  1. Create credentials with v1/secret. Setup a secret that allows Styra to read and write to your Git repository.

    • Navigate to https://github.com/settings/tokens and click on the Personal access tokens button.

    • Click the generate new token button and confirm your authentication.

    • In the New personal access token page, go to the Note field and enter text to indicate what this token is used for.

    • In the Select scopes field, check the box for repo and workflow.

    • Click the Generate token button.

      Your personal access token is now generated. Make sure to copy your new personal access token and save it in a file for future reference.

      Now, navigate to your workspace name >> Settings >> Git Repository >> Git secret and paste your personal access token/secret. To create a new Git repository, follow the instructions listed in the Configure GitHub Repositories section. Copy-paste the new Git repository URL in the Git repository field, for example: github.com/hooli/foo.git. It is optional to specify a tag or branch in the Git reference field. Enter the subdirectory where you want to save the policies in the Repository path field. Now, click the Save changes button.

  2. Update the Workspace to use a Git repository.

    • Go to the Update Workspace API docs.

    • In the right navigation panel, go to source_control and click the + symbol next to origin. The following fields must be filled, except the optional reference field.

      • credentials: Your credentials with v1 secret.

      • path: Your repository path which is the subdirectory where you want to save the policies.

      • reference: (Optional) You can specify a tag or branch. The default is the main branch.

      • url: The full path to your Git repository. For example: github.com/hooli/foo.git.