Use Git as Storage for Libraries

Styra supports using Git as storage for policies. Each library 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 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 master 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.
3. The team can review, test, and merge the private branch into master branch.
4. Styra picks up the change in master branch and distributes the new policy to OPAs.

Figure 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 master 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 master 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 master branch, then that policy is distributed to the OPAs. If those policies are not already in the master 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 master branch. Only once you can merge your private branch into the master branch. The master 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 master branch policies are distributed to OPAs.
2. Disable git-storage on Styra.
3. Styra will not copy the tip of the master branch into its (non-Git) policy backend. The policy in the master 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 library to use its own Git repository or to use the same repository as the Workspace.

By default, every library is configured to share the Workspace Git repository settings. The changes to each library’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 a library to use a separate Git repository instead of the Workspace repository, follow these instructions to configure each library individually.

• Under LIBRARIES, select the library you want to configure.
• Click Settings >> General tab.

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

info

• 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 library by clicking the ( ⨁ ) plus icon next to the LIBRARIES heading. Once created, your library is located under LIBRARIES in the left panel of the Styra DAS GUI.

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

When setting up a Library in Styra DAS, it is important to set up of the following:

• The directory structure in the Git repository
• The package naming in the Rego files
• The Datapath parameter in DAS
• The Repository path parameter in DAS

For more information on mounting Git repositories for libraries, see the Global Library page

Configure using the GUI

You can configure a library from the DAS UI by clicking the ( ⨁ ) plus icon in the left pane. To configure the different settings, see mounting a Git repository through the GUI. It is important to set the Datapath and Repository path correctly.

Configure using the API

export <das-id>="alice.styra.com"  # the tenant URL of SaaS Styra DAS or an on-premises URL
export API_TOKEN="abcdefg"         # this is generated in the workspace admin settings
# replace newlines in the key with \n

Create a secret with the private key used to access Git. This is for access using SSH keys, alternatively you can use an HTTP username and password. In that case, name should be the username and the password goes in secret. In the SSH case, name is not significant.

Replace all newlines in your private key with \n.

curl -X PUT "https://${<das-id>}/v1/secrets/git-pk" \
  --header 'Content-Type: application/json' \
  --header "Authorization: Bearer $API_TOKEN" \
  --data-raw '
{
  "description": "SSH Private Key",
  "name": "git-pk",
  "secret": "-----BEGIN OPENSSH PRIVATE KEY-----\n<\n-----END OPENSSH PRIVATE KEY-----"
}'

Create the Library by referencing the secret created in the previous step. Replace repository URL with your fork.

curl -X PUT "https://${<das-id>}/v1/datasources/global/jwt" \
  --header 'Content-Type: application/json' \
  --header "Authorization: Bearer $API_TOKEN" \
  --data-raw '
{
    "category": "git/rego",
    "url": "git@github.com:alice/das-demo.git",
    "path": "policy/library/global/jwt",
    "reference": "refs/heads/main",
    "ssh_credentials":
    {
        "private_key": "git-pk"
    }
}

Configure using the Function

See the policy/system/gateway/policy/com.styra.envoy.ingress/rules/rules/ingress.rego rule for an example on how to actually call the Library function from a system's rule.

The Library's code will be available under the configured Datapath which is data.global.jwt.

info

The Datapath should always be data.global and only the path after this is configurable.

jwt = {"valid": valid, "payload": payload} {
    token := data.global.jwt.parse_bearer_token(http_request)
    valid := io.jwt.verify_<token>(token)

    [_, payload, _] := io.jwt.decode(token)
}

Add Files to Git

To add files directly to Git for a library:

• 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. The synchronization mechanism for git-storage inspects the linked Git repository to detect all *.rego files.