Home / Platform management / Pipelines / Platform Engineering CI/CD / Pipeline Policies

Pipeline Policies

Overview

A Pipeline Policy is a pivotal feature offered by Platform Engineering CI/CD, designed to aid platform teams in the proficient management and oversight of the software delivery process of business teams. By establishing and enforcing a comprehensive array of rules and policies, platform teams can uniformly manage the safety and compliance of software delivery, thereby enhancing its quality.

This document delves into the definition of policies, the scope of policy constraints, and provides relevant examples, elucidating the process of crafting and utilizing policies to regulate the processes and delivery quality on the business side.

Policy Definition

The specific logic for policy constraint assessment is determined by the referenced rules. When defining a policy, it is crucial to understand the relationship between policies and rules, as well as the application of policy fields.

Policies and Rules

Each policy may encompass one or more rules, within which conditions and requirements constraining pipeline usage behavior are specified. For detailed definitions and explanations of rules, please refer to Pipeline Rules .
When subjected to multiple policies, the pipelines within a namespace must concurrently comply with every rule in each policy.
Policy Definition Example:

apiVersion: policies.katanomi.dev/v1alpha1
kind: Policy # Resource Type
metadata:
  name: policy-sonar-analysis # Resource Name
spec:
  phases:
    - BuildRunResultChanged
  scopes:
    - apiVersion: builds.katanomi.dev/v1alpha1
      kind: BuildRun
      nameRegex: .*
  checks: # Rule Checks
    - ruleRef:
        kind: ClusterRule
        name: sonarqube-analysis-coverage # Referenced Rule Name
      params:
        - name: coverage # Defined Variable Parameter Name in Rule
          value: 60.0

Policy Field Descriptions

A policy primarily comprises three configuration segments: spec.scopes, spec.checks, and spec.phases. Within spec.scopes, the resource types are specified via kind and apiVersion, while specific resources are filtered using nameRegex and selector.
If both nameRegex and selector rules exist, resources must meet both criteria. If neither nameRegex nor selector is provided, no validation against resources will occur.
Concurrent filtering for multiple resources is supported. When scope configuration is present, both kind and apiVersion are mandatory fields.

When defining a policy, ascertain resource definitions based on usage scenarios. For instance, if the policy is to constrain pipelines, set kind to Delivery.
PolicyRun CloudEvent for different resources and stages contains varying resource definitions. Detailed information is presented in the table below:

Resource	Phase	Description	Other	ResourceDefinition
Build	BuildRunDefinitionReady	Build definition complete when ready	Default Policy	Build + BuildSpec (Build resource and build process details)
Build	BuildRunResultChanged	Output is updated when complete		BuildRun
Build	BuildRunCompleted	Build task as ended		BuildRun
Pipeline	DeliveryRunDefinitionReady	Delivery definition complete when ready	Default Policy	Delivery + DeliverySpec (Delivery resource and delivery process details)

Within spec.checks, multiple policy check rules can be specified, which operate on a logical AND basis. Each check comprises ruleRef, all, and any configurations. These configurations can coexist and are processed as logical AND relationships for resource rule validation. Each defined rule corresponds to a clusterRule. When using ruleRef to specify a clusterRule, kind and name are mandatory.
If params need to be provided, the parameter name is mandatory.

In spec.phases, specify the phases during which the policy is effective. Currently, for builds and pipelines, supported phases correspond to those listed in the above table.

Multiple phases can be defined in phases, indicating that the policy will be effective during these stages. Consider the following configuration scenarios for phases:

On definition ready completion: Used to constrain whether the pipeline employs predefined templates.
On result generation: Used to check the results of task execution and apply constraints. If a task result fails to meet policy constraints during execution, the execution will fail.
On build completion: Constrains whether a certain task (i.e., whether a certain type of result has been produced) has been used.

Scope of Constraints and Resource Distribution

Upon defining the content of the policy, it is imperative to delineate its scope of constraints. This encompasses identifying which projects and namespaces within the pipeline will fall under the purview of the specified policy. Furthermore, the resources that have been created must be disseminated to the relevant clusters to become effective. The policies and rule resources that are constructed need to be synchronously distributed to the business clusters where they are conceived. Likewise, the pipeline policies and rules require synchronization to the global cluster.

The platform uses the labelSelector to filter the spec.namespaces within the ResourceSyncer resource to determine the namespaces that need policy resource synchronization, thereby establishing the constraint scope.
Multiple labelSelector operate in a logical OR relationship, meaning that a namespace will be synchronized if it matches any one of the labelSelectors. The operations supported by labelSelector can be reviewed in the official documentation .
Labels associated with namespaces and projects are presented as follows. When allocating resources to project-associated namespaces, the following labels can be utilized:
- cpaas.io/project: Namespaces associated with a project will contain this label, with the value being the project name.
- cpaas.io/inner-namespace: Namespaces named the same as the project within the global cluster will contain this label, with the value being the project name.
The use of labelSelector can achieve the following common scenarios:

Enforcing policies on pipelines under namespaces of all platform projects, with newly created projects and their namespaces automatically falling under the policy constraints:

spec:
  # The labelSelector under namespaces follows an OR relationship.
  namespaces:
    # Use labelSelector to filter relevant namespaces. Each condition inside labelSelector follows an AND relationship.
    # For more details, refer to: https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/#resources-that-support-set-based-requirements
    # Filter namespaces containing labels where the key is cpaas.io/project and the value is either devops or ait.
    - matchExpressions:
        - key: cpaas.io/project
          operator: In
          values:
            - devops
            - ait

    # Use labelSelector to filter relevant namespaces. Each condition inside labelSelector follows an AND relationship.
    # For more details, refer to: https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/#resources-that-support-set-based-requirements
    # Filter namespaces containing labels where the key is cpaas.io/inner-namespace and the value is either devops or ait.
    - matchExpressions:
        - key: cpaas.io/inner-namespace
          operator: In
          values:
            - devops
            - ait

Constraints on pipelines under specific project namespaces, with newly created namespaces within the projects also being automatically governed by the policy:

spec:
  # The labelSelector under namespaces follows an OR relationship.
  namespaces:
    # Use labelSelector to filter relevant namespaces. Each condition inside labelSelector follows an AND relationship.
    # For more details, refer to: https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/#resources-that-support-set-based-requirements
    # Filter namespaces containing labels where the key is cpaas.io/project.
    - matchExpressions:
        - key: cpaas.io/project
          operator: Exists

    # Use labelSelector to filter relevant namespaces. Each condition inside labelSelector follows an AND relationship.
    # For more details, refer to: https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/#resources-that-support-set-based-requirements
    # Filter namespaces containing labels where the key is cpaas.io/inner-namespace.
    - matchExpressions:
        - key: cpaas.io/inner-namespace
          operator: Exists

Policy Scenario Example

Example 1: The platform team mandates that the test coverage for all platform business units must exceed 60% to meet the company’s code quality standards

Operational Workflow:

Create Rule: Administrators should refer to Pipeline Rules to create a test coverage constraint rule. Save the YAML rule file in the code repository.
Distribute Rule Resources: Administrators should navigate to the Platform Management view, select Clusters > Config > Create Sync Rules, choose the code repository where the rule is saved > the branch containing the rule file > select the resource file > choose the source directory > configure the target cluster for synchronization > create, and then distribute the rule resources to the target cluster.
Create Policy: Administrators define the constraint range for the entire platform, specifying the policy and including the test coverage constraint rule with a coverage threshold set at 60.0. Save the YAML file from the example below in the code repository.
Distribute Policy Resources: Administrators navigate to the Platform Management view, select Clusters > Config > Create Sync Rules, choose the code repository where the policy is saved > the branch containing the policy file > select the resource file > choose the source directory > configure the target cluster for synchronization > create, and distribute the policy resources to the target cluster.
Policy Enforcement: Once synchronized successfully, business personnel executing the pipeline within the constraint scope will undergo policy verification.

Note: It is recommended to place rule resource files and policy resource files in different directories for easier management.

apiVersion: operator.alauda.io/v1alpha1
kind: ResourceSyncer
metadata:
  annotations:
    cpaas.io/description: Disseminate execution policies to relevant namespaces
  name: policy-sonar-analysis
spec:
  # Label selectors within namespaces are treated with an OR relationship
  namespaces:
    # Utilize labelSelector to filter pertinent namespaces. Each condition within the labelSelector is treated with an AND relationship
    # Refer to: https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/#resources-that-support-set-based-requirements
    # Select namespaces containing labels with the key cpaas.io/project
    - matchExpressions:
        - key: cpaas.io/project
          operator: Exists

    # Utilize labelSelector to filter pertinent namespaces. Each condition within the labelSelector is treated with an AND relationship
    # Refer to: https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/#resources-that-support-set-based-requirements
    # Select namespaces containing labels with the key cpaas.io/inner-namespace
    # If the Global cluster does not require synchronization of resources, this configuration is unnecessary
    - matchExpressions:
        - key: cpaas.io/inner-namespace
          operator: Exists

  # Configure the policy resources to be synchronized. Only namespace-level resources are supported
  resource:
    apiVersion: policies.katanomi.dev/v1alpha1
    kind: Policy
    metadata:
      name: policy-sonar-analysis
    spec:
      phases:
        - BuildRunResultChanged
      scopes:
        - apiVersion: builds.katanomi.dev/v1alpha1
          kind: BuildRun
          nameRegex: .*
      checks:
        - ruleRef:
            kind: ClusterRule
            name: sonarqube-analysis-coverage # Name of the referenced rule
          params:
            - name: coverage # Variable parameter name defined within the rule
              value: 60.0

Example Two: The platform team mandates that the Builds process of a business-side team must utilize the pipeline template defined by the platform team

Operational Workflow:

The administrator defines the pipeline template, referencing the documentation in the DevOps “User Manual” under “CI/CD > Build > Custom Tasks and Templates > Define a custom template”.
The administrator saves the template to the code repository and assigns the saved template to the business team using Source Management. For a guide on Source Management, refer to the documentation .
The administrator delineates the policy constraint scope, incorporates the built-in rule template-gitsource-resolver-check in the policy, and saves the policy to the code repository.
Refer to the operation flow in Example One to synchronize the policy resources to the target cluster.
Upon successful synchronization, business members will undergo policy checks during the pipeline processes within the specified constraint scope.

Note: The rules provided out-of-the-box by the platform can be directly referenced in the policies, eliminating the need to manually create the rules; simply creating the policy resources suffices.

apiVersion: operator.alauda.io/v1alpha1
kind: ResourceSyncer
metadata:
  annotations:
    cpaas.io/description: Disseminate execution policies to relevant namespaces
  name: policy-template
spec:
  # labels in namespaces are matched using a logical OR operation
  namespaces:
    # The labelSelector filters relevant namespaces, each condition in the labelSelector is combined with a logical AND operation
    # For more details, refer to: https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/#resources-that-support-set-based-requirements
    # Filters namespaces with a label key cpaas.io/project and value project-a
    - matchExpressions:
        - key: cpaas.io/project
          operator: In
          values:
            - project-a

    # The labelSelector filters relevant namespaces, each condition in the labelSelector is combined with a logical AND operation
    # For more details, refer to: https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/#resources-that-support-set-based-requirements
    # Filters namespaces with a label key cpaas.io/inner-namespace and value project-a
    # No need to add this configuration if the Global cluster does not require resource synchronization
    - matchExpressions:
        - key: cpaas.io/inner-namespace
          operator: In
          values:
            - project-a

  # Configure the resources to be synchronized, only supports namespace level resources
  resource:
    apiVersion: policies.katanomi.dev/v1alpha1
    kind: Policy
    metadata:
      name: policy-reference-template
    spec:
      scopes:
        - kind: Build
          apiVersion: builds.katanomi.dev/v1alpha1
          nameRegex: .*
      checks:
        - all:
            - ruleRef:
                kind: ClusterRule
                name: template-gitsource-resolver-check # The name of the built-in rule, which constrains the use of custom templates from specific sources
              params: # Specifies the parameters in the rule
                - name: url
                  value: https://gitlab.com/group/repository # The code repository where the source resides
                - name: revision
                  value: refs/heads/main # The branch where the template resides
                - name: pathInRepo
                  value: a-go-template.yaml # The template definition file