Skip to main content
Version: v4.13

Manage Cyral with GitOps

Overview​

You can enforce security as code using Cyral and Terraform. Cyral provides a high-level GitOps-style workflow, based on Terraform, that can be adapted to any Git-based continuous integration / continuous delivery (CI/CD) platform. Your organization can automate data security management (for example, managing data repository access rules, datamaps, and policies) with a GitOps-style workflow that drives the Cyral Terraform Provider to configure Cyral.

Typical actions include:

  • Tracking data repositories
  • Defining a data map for a repository's sensitive data.
  • Defining a policy to enforce access to that sensitive data.

The Cyral Terraform Provider allows you to define the resources and configuration in your Cyral Control Plane as code using the Terraform's configuration language.

Advantages​

The key advantages of managing Cyral using a GitOps approach include:

  • Enhanced Collaboration: The declarative nature of the GitOps approach means Cyral configurations can be written as a set of facts directly within source code as a "single source of truth." With this approach, security engineering and DevSecOps teams can increase collaboration while maintaining the highest standards for security and compliance. With the declaration of your Cyral configurations serving as your canonical source of truth, you have an ultimate repository from which everything is derived and driven. If errors or mishaps occur, Cyral configurations can be simply rolled back ensuring that all commits on the main branch act as a change log for auditing.

  • Improved Productivity: With continuous integration tooling productivity increases because security engineering and DevSecOps teams can focus on automation rather than investing their efforts on tedious, manual tasks. GitOps-style workflows improve the security team’s experience since team members can use whichever language and tools they would like before pushing updates. As a result, there is a low barrier to entry, empowering anyone - from new hires to tenured team members - to become productive quickly and easily.

A GitOps-style workflow for Cyral​

A pull-request driven GitOps-style workflow for Cyral will typically follow this pattern:

Cyral's GitOps-style workflow can be used with any CI/CD automation platform (such as GitHub Actions, GitLab CI/CD, BitBucket Pipelines, CircleCI, etc.).

The workflow starts with a source code repository containing some Terraform configuration on a single main branch. This can exist in any source code repository such as GitLab, GitHub, etc. Any changes made to the configuration are made on short-lived feature branches. A pull-request is created for each feature branch when the change is ready to be reviewed. At that point, the workflow runs a formatting and validation checks on the configuration, followed by a terraform plan. The results of the plan are added back to the pull-request as a feedback comment, so developers can review the output and ensure everything looks good. Once the PR is approved and merged to the main branch, the workflow applies the configuration by running terraform apply. This step actually creates all the resources defined in the configuration on the Cyral platform.

Managing Terraform State​

A Terraform-based environment relies on the Terraform State file (terraform.tfstate) to manage its current configuration state. Terraform requires the latest version of this state file when executing terraform plan and terraform apply to ensure accurate results. Each time one of these commands are run, Terraform pulls the latest state file from storage and uses it to evaluate the work it needs to do.

Different organizations use different approaches for storing the Terraform state file. For example, if your organization already uses AWS, you may want to store it in S3. In the Cyral GitOps Quickstart GitHub example, we generate and store the Terraform State file (terraform.tfstate) in Terraform Cloud for simplicity. In the GitLab example, we utilize GitLab's native Terraform integration. You can use any Terraform backend that suits your organization and workflow to manage your Terraform state.

While Cyral does not have any dependency on the Terraform backend you chose, we (and HashiCorp themselves) strongly recommend using remote state management, as opposed to managing the state as a local file. While there is nothing inherently wrong with the local file option, in most scenarios you probably don't want to do this and instead should opt for a remote state option. This will allow better collaboration between developers, as well as more secure storage of any sensitive information contained within the state file.

Cyral GitOps Quickstart​

Cyral provides a Terraform-based GitOps Quickstart in our cyral-quickstart GitHub organization as an example that you can copy and use in your source code repository to understand the automated workflow. We currently have specific examples for automated CI/CD workflows using GitHub actions and GitLab CI/CD, however the Quickstart can also be used as a general way to understand the Cyral Terraform Provider so that you can integrate it with any CI/CD platform of your choice.

Prerequisites for a Cyral GitOps integration​

Before you set up provisioning with a Cyral GitOps integration, make sure you have the following prerequisites in place:

  • A functional Cyral deployment. If you don't have one, please register for a free trial.
  • A set of Cyral API client credentials (client ID and secret).
  • An account in your source code repository with permission to commit
  • An account on your CI/CD platform

The following prerequisites are optional, but recommended:

  • A Cyral sidecar, deployed and functional.
  • A database which you want to be protected by the sidecar.

See below for details on the prerequisites.

Cyral API client credentials​

Using the Cyral Terraform Provider requires Cyral API client credentials. To generate the API client credentials, go to your Cyral Control Plane and navigate to "API Client Credentials" on the left-hand navigation bar. Then click the "+" button to create a new set of credentials, and provide a given name and set of permissions. For this specific quickstart, the API client used requires the following permissions:

  • View Datamaps
  • Modify Policies
  • View Sidecars and Repositories
  • Modify Sidecars and Repositories

Once the API client is created, the client ID and secret will be displayed on the screen. Save these values because they will be inaccessible from the Control Plane later and must be regenerated if lost.

Accounts in your source code repository and CI/CD platforms​

GitOps-style workflows use your source code repository and its CI/CD infrastructure for configuration storage, triggering, and state storage. Make sure you have accounts and API credentials for these. For example, the Cyral GitOps Terraform Quickstart GitHub example uses GitHub, GitHub Actions, and Terraform Cloud, so it requires a GitHub account, Terraform Cloud account and API token. You should expect similar requirements for other CI/CD platforms.

Typical GitOps-style workflow setup and use​

A GitOps-style workflow in Cyral relies on commits in your source code repository to trigger Cyral configuration changes, such as data access policy updates. Below, we provide an overview of the set steps and daily operational workflow.

Setup and operations can be accomplished with any source code repository and CI / CD platform. (As an example, Cyral's quickstart-gitops-terraform shows how to set up the workflow in GitHub and GitLab.)

Setup steps​

Setting up your Cyral GitOps integration consists of the following main steps. The exact steps will depend on your choice of source code repository and CI / CD platform.

  1. Commit your Terraform configuration to your source code repository. See quickstart-gitops-terraform for a typical inventory of files including main.tf which specifies the Cyral configuration.

  2. Configure the following source code repository secrets:

    • CYRAL_CONTROL_PLANE - the address of your Cyral control plane, in the format <hostname>:<port>
    • CYRAL_CLIENT_ID - the Cyral API credentials client ID
    • CYRAL_CLIENT_SECRET - the Cyral API credentials client secret
    • API_TOKEN for cloud storage, if you will store Terraform state there.

  3. Modify the Terraform configuration to suit your environment. Usually you'll do this in a new branch. Make any needed changes in main.tf:

For example, if you'll use Terraform Cloud to store Terraform state, then change the organization value in the cloud block to your Terraform Cloud organization.

Optionally, make any other desired changes, such as providing the host/port of a data repository you wish to track, or changing the details of the policy included in the configuration.

  1. Create a pull request with your changes

  2. Inspect the output of terraform plan in the pull request.

  3. Merge the pull request to the main branch to trigger the terraform apply

  4. Inspect the Cyral control plane to see that the resources were created by Terraform.

Daily operations​

Once your Cyral GitOps integration is set up, you can manage Cyral via CI / CD as follows:

  1. Check out the main.tf template and make your desired configuration changes. For example, you might add the details of a new database to be protected or update a policy.

  2. Create a pull request with your changes.

  3. Inspect the output of terraform plan in the pull request.

  4. Merge the pull request to the main branch to trigger the terraform apply

  5. Inspect the Cyral control plane to see that the resources were created by Terraform.

Next Steps​

Use the Cyral GitOps Quickstart as a foundation for managing your Cyral infrastructure and security configuration as code, or create your own workflow to apply changes via the Cyral Terraform Provider. The Terraform configuration from the Quickstart can also be combined with existing Terraform infrastructure you may have, such as configuration to stand up resources in AWS. You can take this further by standing up your cloud resources (such as databases) and protecting them with Cyral within the same Terraform configuration. Also, you can experiment with the overall GitOps-style workflow, for example to add enforcement measures like required approvals for access, or other security policies.