Skip to content

Commit ffe1263

Browse files
use underscores for compiled input and use correct code snippet titles (#146)
1 parent dbd21c3 commit ffe1263

File tree

1 file changed

+15
-15
lines changed

1 file changed

+15
-15
lines changed

docs/guides/modules/config-policies/pages/config-policy-management-overview.adoc

Lines changed: 15 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -369,13 +369,13 @@ Writing policies for CircleCI `version 2.1` configuration introduces some challe
369369

370370
Before executing any pipelines, config `version 2.1` is compiled into config `version 2.0`. This compilation expands all parameters and reusable config blocks (jobs, executors, commands, orbs) into workflows and jobs.
371371

372-
To write highly effective policies, it is essential to reference the _compiled_ version of the config (`input.compiled`).
372+
To write highly effective policies, it is essential to reference the _compiled_ version of the config (`++input._compiled_++`).
373373

374374
[#example]
375375
=== Example
376376
Consider the following example policy and configuration:
377377

378-
**Policy**
378+
.Policy
379379
[source,rego]
380380
----
381381
import future.keywords
@@ -392,7 +392,7 @@ enforce_not_large_resource[reason] {
392392
}
393393
----
394394

395-
**Configuration with reusable executor**
395+
.Configuration with reusable executor
396396
[source,yaml]
397397
----
398398
version: 2.1
@@ -421,7 +421,7 @@ This example is problematic because once the configuration is compiled, the job
421421

422422
Another way this policy could be unintentionally bypassed is by using parameters. Consider the following configuration, which uses a parameter to set the resource class for an executor:
423423

424-
**Configuration using a parameter**
424+
.Configuration using a parameter
425425
[source,yaml]
426426
----
427427
version: 2.1
@@ -450,18 +450,18 @@ However, once the config is compiled, the job test will have a `resource_class =
450450

451451
To resolve both of these issues, it is important to acknowledge that we want to apply the policy to all jobs, which is a configuration `version: 2.0` construct, and write the policy to target the compiled version accordingly, as follows:
452452

453-
**Policy rule that inspects compiled configuration**
453+
.Policy rule that inspects compiled configuration
454454
[source,rego]
455455
----
456456
# check all jobs in the compiled config and if any use a resource_class equal to "large" return a violation message.
457457
enforce_not_large_resource[reason] {
458-
some job_name, job in input.compiled.jobs
458+
some job_name, job in input._compiled_.jobs
459459
job.resource_class == "large"
460460
reason = sprintf("job %s using banned large resource class", [job_name])
461461
}
462462
----
463463

464-
Notice the rule now validates `input.compiled.jobs`. Regardless of parameters or reusable blocks (executors in this example), the policy is applied to all compiled jobs and functions as intended.
464+
Notice the rule now validates `++input._compiled_.jobs++`. Regardless of parameters or reusable blocks (executors in this example), the policy is applied to all compiled jobs and functions as intended.
465465

466466
[#policing-config-constructs]
467467
=== Policing config 2.1 constructs
@@ -470,7 +470,7 @@ Writing policies against config version 2.1 constructs (orbs, executors, jobs, c
470470

471471
Consider another example to illustrate this:
472472

473-
**Policy to ban orbs from a specific namespace**
473+
.Policy to ban orbs from a specific namespace
474474
[source,rego]
475475
----
476476
import future.keywords
@@ -487,7 +487,7 @@ ban_bad_orb_namespace[reason] {
487487
}
488488
----
489489

490-
**Configuration**
490+
.Configuration
491491
[source,yaml]
492492
----
493493
version: 2.1
@@ -504,11 +504,11 @@ orbs:
504504

505505
In the above example, the rule does not raise a violation because the string `<< pipeline.parameters.evil_orb >>` does not have the `bad/` prefix that the policy aims to detect.
506506

507-
We cannot rely on `input.compiled` because orbs are compiled away at that stage.
507+
We cannot rely on `++input._compiled_++` because orbs are compiled away at that stage.
508508

509509
The best approach here is to detect if an orb reference is a parameterized expression and raise a violation accordingly. To do this we can use the `is_parameterized_expression` xref:config-policy-reference.adoc#is_parameterized_expression[helper].
510510

511-
**Policy to ban orbs from a specific namespace and detect parameterized orb references**
511+
.Policy to ban orbs from a specific namespace and detect parameterized orb references
512512
[source,rego]
513513
----
514514
import future.keywords
@@ -541,15 +541,15 @@ Policies and their rules can be categorized into two main types:
541541
542542
When working with configuration `version 2.1` constructs and parameterization, it is crucial to understand how these two rule types interact with your policies.
543543

544-
* **Banlist** rules are susceptible to being bypassed using parameterization and reusable constructs. This is because the literal parameter value is unlikely to match the banned value, and during config compilation, the values intended to be banned can be reintroduced. All parameterization examples provided above fall into this category. To address this, you can either utilize `input.compiled` or detect parameterization and handle it appropriately.
544+
* **Banlist** rules are susceptible to being bypassed using parameterization and reusable constructs. This is because the literal parameter value is unlikely to match the banned value, and during config compilation, the values intended to be banned can be reintroduced. All parameterization examples provided above fall into this category. To address this, you can either utilize `++input._compiled_++` or detect parameterization and handle it appropriately.
545545
546546
* **Allowlist** rules are incompatible with parameterization. They reject configurations that could otherwise be considered valid but do not cause invalid configurations to pass.
547547
548548
Consider an example to illustrate this:
549549

550-
NOTE: This example is artificial and for illustration purposes only. The appropriate policy for enforcing job resource classes should target the compiled input (`input.compiled`). This ensures proper validation against the resolved values.
550+
NOTE: This example is artificial and for illustration purposes only. The appropriate policy for enforcing job resource classes should target the compiled input (`++input._compiled_++`). This ensures proper validation against the resolved values.
551551

552-
**Policy using an allowlist to restrict resource classes**
552+
.Policy using an allowlist to restrict resource classes
553553
[source,rego]
554554
----
555555
import future.keywords
@@ -566,7 +566,7 @@ restrict_resource_classes[reason] {
566566
}
567567
----
568568

569-
**Configuration**
569+
.Configuration
570570
[source,yaml]
571571
----
572572
version: 2.1

0 commit comments

Comments
 (0)