Deployment

• Customizing the Deployment Environment
• Custom Deployment Preconditions
  • Environment Deployment Precondition Example
  • Metadata Precondition Example
  • Approval Process Precondition Example
• Custom Deployment Pipeline
• Custom Buttons Triggering web_trigger Events
• Deployment Permissions Explanation

Deployment Method: You can click the "Deploy" button on the repository's tag list page, select the deployment environment type, and trigger the deployment pipeline to execute the deployment task.

Deployment Event Name: It starts with tag_deploy. and is followed by the environment name. For example, if the environment name is development, the event name will be tag_deploy.development.

Users can customize the deployment environment and deployment pipeline:

Customizing the Deployment Environment

Add a .cnb/tag_deploy.yml file in the root directory of the repository to configure the deployment environment. The example below defines three environments: development, staging, and production. Users can select the desired environment type on the page for deployment.

# .cnb/tag_deploy.yml
environments:
  - name: development
    description: Development environment
    # Environment variables (when triggering the pipeline, environment variables will be passed into the pipeline, including deployment pipeline, web_trigger pipeline)
    env:
      name: development
      # CNB_BRANCH: Environment variable, in deployment events, it is the tag name
      tag_name: $CNB_BRANCH

  - name: staging
    description: Staging environment
    env:
      name: staging
      # CNB_BRANCH: Environment variable, in deployment events, it is the tag name
      tag_name: $CNB_BRANCH

  - name: production
    description: Production environment
    # Environment variables (when triggering the pipeline, environment variables will be passed into the pipeline, including deployment pipeline, web_trigger pipeline)
    env:
      name: production
      # CNB_BRANCH: Environment variable, in deployment events, it is the tag name
      tag_name: $CNB_BRANCH
    button:
      - name: Create Approval Form
        # If exists, it will be used as the pipeline title, otherwise the pipeline uses the default title
        description: Automatically create an approval form process
        # Need to customize web_trigger_approval event pipeline in .cnb.yml
        event: web_trigger_approval
        # Environment variables passed to the web_trigger_approval event pipeline
        # Can inherit environment variables from the previous level, with higher priority than the previous level environment variables
        env:
          name1: value1
          name2: value2

    # Deployment preconditions check (support checking environment, metadata, approval process), all preconditions must be met before deployment operation can be performed
    require:
      # 1 Check if the deployment environment meets the requirements

      # 1.1 Require deployment in development environment to be successful
      - environmentName: development

      # 1.2 Require deployment in staging environment to be successful 30 minutes later
      - environmentName: staging
        after: 1800

      # 2 Check if metadata meets the requirements

      # 2.1 The value corresponding to key1 should not be empty, i.e., it has a value
      - annotation: key1

      # 2.2 The value corresponding to key1 should be equal to value1
      - annotation: key1
        expect:
          eq: value1

      # 2.3 The value corresponding to key2 should be greater than 1 and less than 10
      - annotation: key2
        expect:
          and:
            gt: 1
            lt: 10
        # Custom button, click to trigger execution of web_trigger_annotation event.
        # Can define button events related to require information, hide button when require is met
        button:
          - name: Generate Metadata
            event: web_trigger_annotation
            # If exists, it will be used as the pipeline title, otherwise the pipeline uses the default title
            description: Generate metadata process
            # Environment variables passed to the web_trigger_annotation event pipeline
            # Can inherit environment variables from the previous level, with higher priority than the previous level environment variables
            env:
              name1: value1
              name2: value2

      # 3 Check if the approval process meets the requirements (can customize the approval process as follows)
      # - Approval order: The following 1, 2, 3 approval processes must be carried out in sequence, i.e., approval 1 must be passed before approval 2 can be carried out. All 1, 2, 3 approval processes must be passed to be considered as passing the approval
      # - Approval operation: Include agree, reject. One person's agreement is considered as passing. If rejected, other approvers cannot operate until the rejecting approver modifies the approval result to agree

      # 3.1 Approve by username, one approver's approval is sufficient
      - approver:
          users:
            - user1
            - user2
            - user3
        title: Test Approval

      # 3.2 Approve by role, one approver's approval is sufficient
      - approver:
          roles:
            - developer
            - master
        title: Development Approval

      # 3.3 Approve by username or role (one of the approvers meeting users or roles is sufficient), one approver's approval is required
      - approver:
          users:
            - user4
            - user5
          roles:
            - master
            - owner
        title: Operations Approval

    # Custom deployment button (default: display one deployment button)
    # Use case: When there are multiple different modules (e.g., repository, CI, artifact library, etc.) that need to be deployed separately, you can configure multiple different buttons
    # Note: The deployment pipeline needs to distinguish which module it is, which can be done by passing environment variables to the pipeline
    deploy:
      - name: Deployment Button Name 1
        description: Deployment button description
        # Environment variables (when triggering the deployment pipeline, environment variables will be passed into the pipeline), with higher priority than the previous level env
        env:
          name1: value1
          name2: value2
      - name: Deployment Button Name 2
        description: Deployment button description
        # Environment variables (when triggering the deployment pipeline, environment variables will be passed into the pipeline), with higher priority than the previous level env
        env:
          name1: value1
          name2: value2

• name: Required, unique environment name.

• description: Optional, environment description.

• env: Optional, environment variables passed to the deployment pipeline. Users can pass in the required environment variables according to their needs.

• button: Optional, array of objects format, custom button. Clicking the button can trigger the cloud native build pipeline to execute the event corresponding to the parameter event.

  • name: Required, button name.
  • description: Optional, button description. If exists, it will be used as the pipeline title, otherwise the pipeline uses the default title.
  • event: Required, custom event, only supports web_trigger events.
  • env: Optional, environment variables passed to the web_trigger pipeline, can inherit environment variables from the previous level, with higher priority than the previous level environment variables.

• deploy: Optional, array of objects format, custom deployment button. Clicking the button can trigger the cloud native build pipeline to execute the deployment event (tag_deploy.*).

  • name: Required, button name.
  • description: Optional, button description.
  • env: Optional, environment variables passed to the deployment pipeline, with higher priority than the previous level env.

• require: Optional, array of objects format. Deployment preconditions, deployment operation can only be performed after all preconditions (deployment environment requirements, metadata requirements, approval process) are met.

  1、Parameters for deployment environment requirements include

  • environmentName: Required. Environment name.

  • after: Optional. Time, in seconds (s). Indicates that the environmentName environment must be deployed successfully after after time to meet the precondition.

  • description: Optional. require description information, to help users understand the content of require requirements.

  • button: Optional. Custom button, click to trigger execution of event passed in. Can define button events related to require information, note: hide button when require is met.

    • name: Required, button name.
    • event: Required, custom event, only supports web_trigger_* events.
    • description: Optional, button description. If exists, it will be used as the pipeline title, otherwise the pipeline uses the default title.
    • env: Optional, environment variables passed to the web_trigger pipeline, can inherit environment variables from the previous level, with higher priority than the previous level environment variables.

  2、Parameters for metadata requirements include

  • annotation: Required. Metadata key value.

  • expect: Optional. Requirements for the value of the metadata. Object format, supports eq, ne, gt, lt, gte, lte, and, or, reg operators.

    • eq: Equal to
    • ne: Not equal to
    • gt: Greater than
    • lt: Less than
    • gte: Greater than or equal to
    • lte: Less than or equal to
    • and: And
    • or: Or
    • reg: Can match regular expression

  • description: Optional. require description information, to help users understand the content of require requirements.

  • button: Optional. Custom button, click to trigger execution of event passed in. Can define button events related to require information, note: hide button when require is met.

    • name: Required, button name.
    • description: Optional, button description. If exists, it will be used as the pipeline title, otherwise the pipeline uses the default title.
    • event: Required, custom event, only supports web_trigger events.
    • env: Optional, environment variables passed to the web_trigger pipeline, can inherit environment variables from the previous level, with higher priority than the previous level environment variables.

  3、Parameters for approval process requirements include

  • approver: Required, approver definition, one of the approvers in users or role must approve to pass.
    • users: Array of usernames. Can define multiple approvers.
    • roles: Array of repository roles. Can define multiple repository roles.
  • title: Optional, approval title, such as Test Approval.

Custom Deployment Preconditions

For each environment, deployment preconditions can be defined, and deployment operations can only be performed after all preconditions are met. The following three types of preconditions can be defined:

• Environment deployment requirements: Requires the specified environment to be deployed successfully, and meet the after deployment success time requirement
• Metadata value requirements: Requires the value corresponding to the specified metadata to meet the requirements
• Approval process requirements: Can customize the approval process to specify approvers and perform approval operations, when all approval processes are approved, it is considered as meeting the requirements

Environment Deployment Precondition Example

# .cnb/tag_deploy.yml
environments:
  - name: development
    description: Development environment
    env:
      name: development
      tag_name: $CNB_BRANCH

  - name: staging
    description: Staging environment
    env:
      name: staging
      tag_name: $CNB_BRANCH
    require:
      # Require deployment in development environment to be successful
      - environmentName: development

  - name: production
    description: Production environment
    require:
      # Require deployment in staging environment to be successful 30 minutes later
      - environmentName: staging
        after: 1800

Metadata Precondition Example

# .cnb/tag_deploy.yml
environments:
  - name: production
    description: Production environment
    require:
      # Check if metadata meets the requirements

      # The value corresponding to key1 should not be empty, i.e., it has a value
      - annotation: key1

      # The value corresponding to key2 should be equal to value1
      - annotation: key2
        expect:
          eq: value2

      # The value corresponding to key3 should be greater than 1 and less than 10
      - annotation: key3
        expect:
          and:
            gt: 1
            lt: 10
        # Custom button, click to trigger execution of web_trigger_annotation event.
        # Can define button events related to require information, note: hide button when require is met
        button:
          - name: Generate Metadata
            event: web_trigger_annotation
            # If exists, it will be used as the pipeline title, otherwise the pipeline uses the default title
            description: Generate metadata process
            # Environment variables passed to the web_trigger_annotation event pipeline
            # Can inherit environment variables from the previous level, with higher priority than the previous level environment variables
            env:
              name1: value1
              name2: value2

Approval Process Precondition Example

Can customize the approval process and specify approvers. Approvers with permissions can perform approval operations (agree, reject). All processes must be approved before the requirement is considered met.

# .cnb/tag_deploy.yml
environments:
  - name: production
    description: Production environment
    require:
      # Check if the approval process meets the requirements (can customize the approval process as follows)
      # - Approval order: The following 1, 2, 3 approval processes must be carried out in sequence, i.e., approval 1 must be passed before approval 2 can be carried out. All 1, 2, 3 approval processes must be passed to be considered as passing the approval
      # - Approval operation: Include agree, reject. One person's agreement is considered as passing. If rejected, other approvers cannot operate until the rejecting approver modifies the approval result to agree

      # Approve by username, one approver's approval is sufficient
      - approver:
          users:
            - user1
            - user2
            - user3
        title: Test Approval

      # Approve by role, one approver's approval is sufficient
      - approver:
          roles:
            - developer
            - master
        title: Development Approval

      # Approve by username or role (one of the approvers meeting users or roles is sufficient), one approver's approval is required
      - approver:
          users:
            - user4
            - user5
          roles:
            - master
            - owner
        title: Operations Approval

Custom Deployment Pipeline

The following example defines the deployment event pipeline for three environments, When deploying the development environment on the page, the tag_deploy.development event is triggered. The pipeline deploys based on the code corresponding to the current tag.

# .cnb.yml
$:
  tag_deploy.development:
    - name: dev
      stages:
        - name: Deploy Environment Name
          script: echo $name
        - name: Tag Name
          script: echo $tag_name
  tag_deploy.staging:
    - name: staging
      stages:
        - name: Deploy Environment Name
          script: echo $name
        - name: Tag Name
          script: echo $tag_name
  tag_deploy.production:
    - name: production
      stages:
        - name: Deploy Environment Name
          script: echo $name
        - name: Tag Name
          script: echo $tag_name

The correspondence between the example pipeline event names and deployment environment types is as follows:

• tag_deploy.development: development
• tag_deploy.staging: staging
• tag_deploy.production: production

Custom Buttons Triggering web_trigger Events

The custom buttons defined in tag_deploy.yml only support triggering web_trigger events. In the following pipeline configuration, when the web_trigger_annotation event is executed, it performs annotation upload operations.

# .cnb.yml
$:
  # Custom buttons triggering events
  web_trigger_annotation:
    - stages:
        - name: Upload annotation
          image: cnbcool/annotations:latest
          settings:
            data: |
              key1=value1
              key2=value2

Deployment Permissions Explanation

Users must have repository write access and push tag permissions to perform deployment operations.