This quick start demonstrates a simple GitOps workflow which can be used to configure and manage Cyral using Terraform and Cyral's Terraform Provider. The example includes using Terraform to:
- Track a data repository.
- Define a data map for the repository's sensitive data.
- Define 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.
Ultimately, this quick start will help you enforce security as code using Cyral and Terraform.
This quickstart demonstrates how to use Terraform alongside a CI/CD platform to manage Cyral infrastructure as code. Two CI/CD examples are provided in this quickstart: GitHub Actions and GitLab CI/CD. Note that while only these two platforms are demonstrated here, 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.).
This quick start can be copied and used in a standalone GitHub or GitLab repository to take advantage of the automated workflow. Alternatively, if you just want to play with the Cyral Terraform provider, or have another CI/CD platform that you want to adapt this workflow to, please feel free to use this code as a baseline to build from.
- 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).
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.
The following prerequisites are optional, but recommended:
- A Cyral sidecar, deployed and functional.
- A database which you want to be protected by the sidecar.
Finally, both the GitLab and GitHub examples have their own
prerequisites, so please see the README for each example for details.
If you don't want to use the GitHub Actions or GitLab CI/CD workflows, feel free to run Terraform by hand or in some other task runner / CI/CD engine, (and optionally remove the Terraform Cloud configuration if desired). The workflow outlined below is standard enough to run on any CI/CD platform.
This quickstart presents an example of a simple automated, pull-request driven GitOps workflow:
The general principles and steps should apply to any CI/CD automation platform (GitLab CI/CD, BitBucket Pipelines, CircleCI, etc.).
The workflow starts with a source code repository containing some
Terraform configuration on a single main branch. 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.
Note that the Terraform State file (terraform.tfstate) is generated and
stored in Terraform Cloud in the GitHub Actions example,
and on GitLab's Terraform backend for the GitLab example.
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 the respective
storage and uses it to evaluate the work it needs to do.
You can configure the Terraform state storage however you want when using these examples. However, 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 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.
Feel free to use this quick start as a foundation for managing your Cyral infrastructure and security configuration as code. The Terraform configuration here can also be combined with any existing Terraform you may have, such as configuration to stand up resources in AWS, etc. 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 GitOps workflow, perhaps adding concepts required approvals, etc. It's really up to your imagination!
Please view the Cyral documentation for more details on how you can use Cyral to protect your data.