Configure a Release promotion pipeline

This page will walk through how to set up a Release promotion pipeline to begin managing Product upgrades in Apollo.

Prerequisites

Before configuring the Release promotion pipeline, you should publish an initial Product Release to Apollo.

You should also create any custom Release Channels that you would like to include in your promotion pipeline.

Define rollout criteria

You can define requirements for promotion by selecting Edit product settings from the Actions dropdown on the Product home page.

Navigate to the Upgrades tab to specify health requirements and maintenance windows.

Health requirements for Release promotion

Apollo computes two durations during promotion evaluation:

• Healthy duration: The amount of time that a promotion is considered healthy. A time period is considered healthy when all the nodes are live and their health states are either HEALTHY or DEFERRING.
• Unhealthy duration: The amount of time that a promotion is considered unhealthy. A time period is considered unhealthy when at least one of the live nodes has an ERROR health state.

You can define two threshold values based on the healthy and unhealthy durations. The values for these thresholds must be between zero and one.

• Healthy threshold: The minimum percentage of time that an Entity must be healthy for Apollo to consider a rollout successful. The default value for this threshold is 0.95.
• Unhealthy threshold: The maximum percentage of time that an Entity can be unhealthy for Apollo to consider a rollout unsuccessful or as having problems that must be addressed before further roll out. The default value for this threshold is 0.05.

Configure a promotion pipeline

To configure a promotion pipeline, navigate to the Releases tab of the Product home page and select Edit from the Promotion pipeline box.

You can also select Edit promotion pipeline from the Actions dropdown.

This will open the promotion pipeline configuration window.

A promotion stage refers to the transition between two Release Channels. Select Add stage to add a pipeline stage and the cross to the right of a stage to remove a promotion stage.

For each promotion stage you will define the following Release Channels:

• Source channel: The Release Channel that Apollo will promote the Release from.
• Target channel: The Release Channel that Apollo will promote the Release to.

Two types of promotion are available:

• Timed promotion: The Release is promoted to the target channel after a defined period of time.
• Canary promotion: The Release is promoted to the target channel based on criteria evaluated on a chosen set of test Environments.

Changes to a Product's promotion pipeline take effect at the next evaluation, which happens every minute.

Timed promotion stage

When you select Timed promotion, Apollo will use time-based promotion evaluation. You can define the following parameter for time-based promotion:

• Duration: The amount of time that a Release must spend on the source Release Channel before being promoted to the target Release Channel. The duration can be set to any value between 0 seconds and 31 days.

Canary promotion stage

When you select Canary promotion, Apollo will use canary-based promotion evaluation. During canary-based promotion evaluation, Apollo will select test Environments using configured Entity filters. It will evaluate the Release on these test Environment based on the conditions that you define. The Release is promoted to the target Release Channel when all conditions are satisfied.

Entity filters

Entity filters define the pool of Entities from which Apollo will choose test Environments. The available filters are:

• Environments with Label: Choose Entities on Environments with the specified label.
  • The label must be present on the Environment.
  • If no label values are specified, Apollo will check for the existence of the label on the Environment.
  • If label values are specified, Apollo will check for the existence of the label and its value on the Environment.
• Environments without Label: Choose Entities on Environments without the specified label.
  • The label must be absent on the Environment.
  • If no label values are specified, Apollo will check for the absence of the label on the Environment.
  • If label values are specified, Apollo will check for the absence of the label and its value on the Environment.
• Choose Environments: Choose Entities from a discrete set of environments.
• Exclude Environments: Choose Entities that are not in the discrete set of environments.

Conditions

Conditions define the requirements that Releases must satisfy before being promoted to the target Release Channel.

• Promote when healthy: Promote the Release once the specified number of Entities have soaked for at least the specified duration and satisfy the healthy threshold from the rollout criteria defined in the Upgrades tab.
  • The number of Entities can be defined as a count or as a percentage of the selected Entities.
  • The duration can be set to any duration between 0 seconds and 13 days.
• Recall when unhealthy: Recall the Release if the specified number of Entities have soaked for at least the specified duration and satisfy the unhealthy threshold from the rollout criteria defined in the Upgrades tab.
  • The number of Entities can be defined as a count or as a percentage of the selected Entities.
  • The duration can be set to any duration between 0 seconds and 13 days.
• Minimum entity count: Promote only if the number of selected Entities is above the specified count.
• Require Product Release label: Promote only if the Release satisfies the label requirement.
  • The label must be present on the Release.
  • If no label values are specified, Apollo will check for the existence of the label on the Release.
  • If label values are specified, Apollo will check for the existence of the label and its value on the Release.

Select Confirm when you are finished editing the promotion pipeline.

Explore the Release promotion pipeline

You can view the Release promotion pipeline that you configured on the Product overview page.

In the example above, all Releases of the helm-chart-operator Product will follow this promotion pipeline once they are published.

You can also view a Release promotion pipeline graph for each Product release by selecting a Release from the Releases tab of the Product overview page. This graph includes details on the promotion evaluation status and promotion results at each pipeline stage.

Learn more about tracking Product Releases.