We recommend that you test your Sentinel policies extensively before deploying them within HCP Terraform. An important part of this process is mocking the data that you wish your policies to operate on.
Note: HCP Terraform Free edition includes one policy set of up to five policies. In HCP Terraform Plus and Premium editions, you can connect a policy set to a version control repository or create policy set versions with the API. Refer to HCP Terraform pricing for details.
Due to the highly variable structure of data that can be produced by an individual Terraform configuration, HCP Terraform provides the ability to generate mock data from existing configurations. This can be used to create sample data for a new policy, or data to reproduce issues in an existing one.
Testing policies is done using the Sentinel CLI. More general information on testing Sentinel policies can be found in the Testing section of the Sentinel runtime documentation.
Be careful! Mock data generated by HCP Terraform directly exposes any and all data within the configuration, plan, and state. Terraform attempts to scrub sensitive data from these mocks, but we do not guarantee 100% accuracy. Treat this data with care, and avoid generating mocks with live sensitive data when possible. Access to this information requires permission to download Sentinel mocks for the workspace where the data was generated.
Mock data can be generated using the UI by expanding the plan status section of the run page, and clicking on the Download Sentinel mocks button.
For more information on creating a run, see the Terraform Runs and Remote Operations section of the docs.
If the button is not visible, then the plan is ineligible for mock generation or the user doesn't have the necessary permissions. See Mock Data Availability for more details.
Mock data can also be created with the Plan Export API.
Multiple steps are required for mock generation. The export process is asynchronous, so you must monitor the request to know when the data is generated and available for download.
id of the plan object within the relationships section of the return data.sentinel-mock-bundle-v0.finished, the data is ready for download.Note: The v2 mock files are only available on Terraform 0.12 and higher.
Mock data is supplied as a bundled tarball, containing the following files:
mock-tfconfig.sentinel # tfconfig mock data
mock-tfconfig-v2.sentinel # tfconfig/v2 mock data
mock-tfplan.sentinel # tfplan mock data
mock-tfplan-v2.sentinel # tfplan/v2 mock data
mock-tfstate.sentinel # tfstate mock data
mock-tfstate-v2.sentinel # tfstate/v2 mock data
mock-tfrun.sentinel # tfrun mock data
sentinel.hcl # sample configuration file
The sample sentinel.hcl file contains mappings to the mocks so that you can get started testing with sentinel apply right away. For sentinel test, however, we recommend a more detailed layout.
We recommend placing the files for sentinel test in a subdirectory of the repository holding your policies, so they don't interfere with the command's automatic policy detection. While the test data is Sentinel code, it's not a policy and will produce errors if evaluated like one.
.
├── foo.sentinel
├── sentinel.hcl
├── test
│ └── foo
│ ├── fail.hcl
│ └── pass.hcl
└── testdata
├── mock-tfconfig.sentinel
├── mock-tfconfig-v2.sentinel
├── mock-tfplan.sentinel
├── mock-tfplan-v2.sentinel
├── mock-tfstate.sentinel
├── mock-tfstate-v2.sentinel
└── mock-tfrun.sentinel
Each configuration that needs access to the mock should reference the mock data files within the mock block in the Sentinel configuration file.
For sentinel apply, this path is relative to the working directory. Assuming you always run this command from the repository root, the sentinel.hcl configuration file would look like:
mock "tfconfig" {
module {
source = "testdata/mock-tfconfig.sentinel"
}
}
mock "tfconfig/v1" {
module {
source = "testdata/mock-tfconfig.sentinel"
}
}
mock "tfconfig/v2" {
module {
source = "testdata/mock-tfconfig-v2.sentinel"
}
}
mock "tfplan" {
module {
source = "testdata/mock-tfplan.sentinel"
}
}
mock "tfplan/v1" {
module {
source = "testdata/mock-tfplan.sentinel"
}
}
mock "tfplan/v2" {
module {
source = "testdata/mock-tfplan-v2.sentinel"
}
}
mock "tfstate" {
module {
source = "testdata/mock-tfstate.sentinel"
}
}
mock "tfstate/v1" {
module {
source = "testdata/mock-tfstate.sentinel"
}
}
mock "tfstate/v2" {
module {
source = "testdata/mock-tfstate-v2.sentinel"
}
}
mock "tfrun" {
module {
source = "testdata/mock-tfrun.sentinel"
}
}
For sentinel test, the paths are relative to the specific test configuration file. For example, the contents of pass.hcl, asserting that the result of the main rule was true, would be:
mock "tfconfig" {
module {
source = "../../testdata/mock-tfconfig.sentinel"
}
}
mock "tfconfig/v1" {
module {
source = "../../testdata/mock-tfconfig.sentinel"
}
}
mock "tfconfig/v2" {
module {
source = "../../testdata/mock-tfconfig-v2.sentinel"
}
}
mock "tfplan" {
module {
source = "../../testdata/mock-tfplan.sentinel"
}
}
mock "tfplan/v1" {
module {
source = "../../testdata/mock-tfplan.sentinel"
}
}
mock "tfplan/v2" {
module {
source = "../../testdata/mock-tfplan-v2.sentinel"
}
}
mock "tfstate" {
module {
source = "../../testdata/mock-tfstate.sentinel"
}
}
mock "tfstate/v1" {
module {
source = "../../testdata/mock-tfstate.sentinel"
}
}
mock "tfstate/v2" {
module {
source = "../../testdata/mock-tfstate-v2.sentinel"
}
}
mock "tfrun" {
module {
source = "../../testdata/mock-tfrun.sentinel"
}
}
test {
rules = {
main = true
}
}
The following factors can prevent you from generating mock data:
If a plan cannot have its mock data exported due to any of these reasons, the Download Sentinel mocks button within the plan status section of the UI will not be visible.
Note: Only a successful plan is required for mock generation. Sentinel can still generate the data if apply or policy checks fail.
RetroSearch is an open source project built by @garambo | Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.4