You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/guides/modules/config-policies/pages/config-policy-management-overview.adoc
+15-15Lines changed: 15 additions & 15 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -369,13 +369,13 @@ Writing policies for CircleCI `version 2.1` configuration introduces some challe
369
369
370
370
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.
371
371
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_++`).
373
373
374
374
[#example]
375
375
=== Example
376
376
Consider the following example policy and configuration:
@@ -421,7 +421,7 @@ This example is problematic because once the configuration is compiled, the job
421
421
422
422
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:
423
423
424
-
**Configuration using a parameter**
424
+
.Configuration using a parameter
425
425
[source,yaml]
426
426
----
427
427
version: 2.1
@@ -450,18 +450,18 @@ However, once the config is compiled, the job test will have a `resource_class =
450
450
451
451
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:
452
452
453
-
**Policy rule that inspects compiled configuration**
453
+
.Policy rule that inspects compiled configuration
454
454
[source,rego]
455
455
----
456
456
# check all jobs in the compiled config and if any use a resource_class equal to "large" return a violation message.
457
457
enforce_not_large_resource[reason] {
458
-
some job_name, job in input.compiled.jobs
458
+
some job_name, job in input._compiled_.jobs
459
459
job.resource_class == "large"
460
460
reason = sprintf("job %s using banned large resource class", [job_name])
461
461
}
462
462
----
463
463
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.
465
465
466
466
[#policing-config-constructs]
467
467
=== Policing config 2.1 constructs
@@ -470,7 +470,7 @@ Writing policies against config version 2.1 constructs (orbs, executors, jobs, c
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.
506
506
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.
508
508
509
509
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].
510
510
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
512
512
[source,rego]
513
513
----
514
514
import future.keywords
@@ -541,15 +541,15 @@ Policies and their rules can be categorized into two main types:
541
541
542
542
When working with configuration `version 2.1` constructs and parameterization, it is crucial to understand how these two rule types interact with your policies.
543
543
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.
545
545
546
546
* **Allowlist** rules are incompatible with parameterization. They reject configurations that could otherwise be considered valid but do not cause invalid configurations to pass.
547
547
548
548
Consider an example to illustrate this:
549
549
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.
551
551
552
-
**Policy using an allowlist to restrict resource classes**
552
+
.Policy using an allowlist to restrict resource classes
0 commit comments