Canary Gate is a tool created for integration with Flagger that offers detailed management of Canary deployments, rather than depending entirely on automated metric analysis. Although it works alongside metrics analysis, the ultimate decision for each phase will be made using this tool.
Flagger will provide the webhook for each canary phase. The tool will communicate with Flagger and return either the advance or halt command to Flagger.
.─. ┌───────────────┐ ┌──────────┐
( )──────▶│confirm-rollout│───────open─────────────────────▶│ rollout │◀───────┐
`─' └───────────────┘ ┌──close────────└──────────┘ │
deploy │ │ │ │
close ▼ │ │
│ .─. open │
▼ ( ) │ │
.─. `─' ▼ │
( ) pause .─. │
`─' ┌──────────────────────────────────────( ) │
pause │ `─' │
errors check .─.
│ metrics ( ) increase
│ │ `─' traffic
│ │ ▲
│ ▼ │
│ ┌────────────────┐ │
│ .─. │confirm-traffic-│ │
│ ( )◀────close─────│ increase │ │
│ `─' └────────────────┘ │
│ pause │ close
│ open │
│ │ │
▼ ▼ │
.─. ┌────────────┐ │
rollback ( █ )◀───────────────────open───────│ rollback │───────┘
`─' └────────────┘
▲ │
│ promoting
│ │
│ ▼
.─. .─. ┌─────────────────┐
( )◀──errors───( )◀──close────│confirm-promotion│
`─' `─' └─────────────────┘
check pause │
metrics open
│
▼
.─.
( █ )
`─'
promote
Each gate controls the flow of the Flagger Canary process.
-
When a new version is detected, it will check the
<confirm-rollout>gate.- If the gate is open, it will proceed to the next stage.
- If the gate is closed, it will halt the process and wait until the gate is opened.
-
Next, it will check the
<pre-rollout>gate. This stage is not depicted in the diagram.- If the gate is open, it will proceed to the next stage.
- If the gate is closed, it will halt the process and wait until the gate is opened.
-
Flagger will begin increasing traffic based on the configuration in CanaryGate. Before each traffic increase, it will check the
<rollout>and<confirm-traffic-increase>gates.- If
<rollout>is open, it will proceed to the next stage. - If
<rollout>is closed, it will halt the process and continue monitoring metrics. If metrics indicate failure, it will initiate a rollback. - If
<confirm-traffic-increase>is open, it will continue to increase traffic and proceed to the next stage. - If
<confirm-traffic-increase>is closed, it will halt the process.
- If
-
After increasing traffic until it reaches the maximum weight, it will check the
<confirm-promotion>gate.- If the gate is open, it will proceed to promote to the new version.
- If the gate is closed, it will halt the process and continue monitoring metrics. If metrics indicate failure, it will initiate a rollback.
-
Flagger will copy the canary deployment specification template over to the primary. After promotion is finalized, the
<post-rollout>gate is checked. This stage is not depicted in the diagram.- If the gate is open, the process is completed.
- If the gate is closed, the process is pending finalization.
-
The
<rollback>gate is continuously monitored throughout the process.- If the gate is open, the rollback process is initiated.
- If the gate is closed, the rollout process continues.
First, you will need to install Flagger on your Kubernetes cluster.
Install Flagger CRD
kubectl apply -f https://raw.githubusercontent.com/fluxcd/flagger/main/artifacts/flagger/crd.yamlFlagger requires the installation of Istio or another service mesh to manage traffic effectively. It is recommended to set up Istio before continuing with the installation of Flagger in the next step. The metric server can be omitted at this stage. Please check the Flagger metrics documentation for a list of supported providers.
Deploy Flagger
helm repo add flagger https://flagger.app
helm upgrade -i flagger flagger/flagger \
--namespace=flagger \
--set crd.create=false \
--set meshProvider=istio \
--create-namespaceSee full installation detail from https://docs.flagger.app/install/flagger-install-on-kubernetes
- Run helm chart install
helm -n canary-gate install \
canary-gate oci://ghcr.io/kongz/helm-charts/canary-gate \
--version 0.1.3If you encounter problems with the installed Custom Resource Definition (CRD) file, you may need to install the CRD prior to continuing with the Helm installation.
kubectl apply -f https://raw.githubusercontent.com/KongZ/canary-gate/main/docs/canarygate-crd.yaml
helm -n canary-gate install \
canary-gate oci://ghcr.io/kongz/helm-charts/canary-gate \
--set crd.create=false \
--namespace=canary-gate \
--create-namespaceAssume that you already have an application deployment named demo within the demo-ns namespace.
apiVersion: piggysec.com/v1alpha1
kind: CanaryGate
metadata:
name: demo
spec:
target:
namespace: demo-ns
name: demo
flagger:
targetRef:
apiVersion: apps/v1
kind: Deployment
name: demo
service:
port: 8080
skipAnalysis: false
analysis:
interval: 10s
threshold: 2
maxWeight: 40
stepWeight: 10
stepWeightPromotion: 100Canary Gate contains target and flagger
target:
namespace: demo-ns
name: demoThe target specifies the location of the Canary object. The CanaryGate will replicate all content under flagger to the Canary object upon execution. You can find the description and configuration instructions for Canary https://docs.flagger.app/usage/how-it-works.
Use can the command-line tool to open/close gates.
If you use Homebrew you can install by these command
brew tap KongZ/homebrew-tap
brew install canary-gateIt installs the canary-gate binary to the default location
curl -sSL https://raw.githubusercontent.com/KongZ/canary-gate/refs/heads/main/docs/install.sh | sudo bashIf you want to install the binary to a different directory (e.g., /opt/bin), you can set the INSTALL_PATH environment variable.
curl -sSL https://raw.githubusercontent.com/KongZ/canary-gate/refs/heads/main/docs/install.sh | sudo INSTALL_PATH=/opt/bin bashTo remove the binary, pass the uninstall parameter to the script.
curl -sSL https://raw.githubusercontent.com/KongZ/canary-gate/refs/heads/main/docs/install.sh | sudo bash -s -- uninstallIf you installed it to a custom path, you must provide the same INSTALL_PATH variable during uninstallation.
curl -sSL https://raw.githubusercontent.com/KongZ/canary-gate/refs/heads/main/docs/install.sh | sudo INSTALL_PATH=/opt/bin bash -s -- uninstallYou can download the binary files from releases.
Please select the appropriate version and operating system for your download.
To clone the project to your local machine, use the following command:
git clone https://github.com/KongZ/canary-gate.gitAfter cloning, execute the following command to build the CLI:
make build-cliThe makefile will compile the CLI binary for all platforms and place it in the bin folder.
You can find more sample from Flagger documents. There are few examples can be found in this repository.
The CanaryGate configuration
apiVersion: piggysec.com/v1alpha1
kind: CanaryGate
metadata:
name: demo
spec:
confirm-rollout: closed
target:
namespace: demo-ns
name: demo
flagger:
targetRef:
apiVersion: apps/v1
kind: Deployment
name: demo
service:
port: 8080
skipAnalysis: false
analysis:
interval: 10s
threshold: 2
maxWeight: 40
stepWeight: 10
stepWeightPromotion: 100This example sets confirm-rollout: closed. During the deployment, this configuration will pause the rollout process.
No new version will be deployed until confirm-rollout is set to opened.
The CanaryGate configuration
apiVersion: piggysec.com/v1alpha1
kind: CanaryGate
metadata:
name: demo
spec:
confirm-rollout: opened
rollout: opened
confirm-traffic-increase: opened
confirm-promotion: closed
target:
namespace: demo-ns
name: demo
flagger:
targetRef:
apiVersion: apps/v1
kind: Deployment
name: demo
service:
port: 8080
skipAnalysis: false
analysis:
interval: 10s
threshold: 2
maxWeight: 20
stepWeight: 20
stepWeightPromotion: 100This example sets confirm-promotion: closed. During the deployment, the rollout process will continue until the new version captures 20% of the traffic from a total of 100%. At that stage, the promotion will be paused. While paused, the new version will still receive 20% of the traffic, while the old version will receive 80%. The process will stay paused until confirm-traffic-increase is set to opened.
Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0/
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
The original Go gopher was designed by Renee French. The design is licensed under the Creative Commons 4.0 Attributions license.