Canary Release: Use health checks - Plugin

Use health checksv1.0+

Use Upstream health checks to skip applying the canary upstream if it doesn’t have at least one healthy target. If the canary is unhealthy, traffic falls back to the primary upstream service.

Prerequisites

An Upstream entity configured with active or passive health checks

Environment variables

UPSTREAM_ENTITY_NAME: The name of an Upstream entity to route the canary to.

Set up the plugin

Add this section to your kong.yaml configuration file:

_format_version: "3.0"
plugins:
  - name: canary
    config:
      percentage: 50
      upstream_host: ${{ env "DECK_UPSTREAM_ENTITY_NAME" }}
      upstream_port: 80
      upstream_fallback: true

Make the following request:

curl -i -X POST http://localhost:8001/plugins/ \
    --header "Accept: application/json" \
    --header "Content-Type: application/json" \
    --data '
    {
      "name": "canary",
      "config": {
        "percentage": 50,
        "upstream_host": "'$UPSTREAM_ENTITY_NAME'",
        "upstream_port": 80,
        "upstream_fallback": true
      }
    }
    '

Make the following request:

curl -X POST https://{region}.api.konghq.com/v2/control-planes/{controlPlaneId}/core-entities/plugins/ \
    --header "accept: application/json" \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer $KONNECT_TOKEN" \
    --data '
    {
      "name": "canary",
      "config": {
        "percentage": 50,
        "upstream_host": "'$UPSTREAM_ENTITY_NAME'",
        "upstream_port": 80,
        "upstream_fallback": true
      }
    }
    '

Make sure to replace the following placeholders with your own values:

region: Geographic region where your Kong Konnect is hosted and operates.
controlPlaneId: The id of the control plane.
KONNECT_TOKEN: Your Personal Access Token (PAT) associated with your Konnect account.

See the Konnect API reference to learn about region-specific URLs and personal access tokens.

Prerequisite: Configure your Personal Access Token

terraform {
  required_providers {
    konnect = {
      source  = "kong/konnect"
    }
  }
}

provider "konnect" {
  personal_access_token = "$KONNECT_TOKEN"
  server_url            = "https://us.api.konghq.com/"
}

Add the following to your Terraform configuration to create a Konnect Gateway Plugin:

resource "konnect_gateway_plugin_canary" "my_canary" {
  enabled = true

  config = {
    percentage = 50
    upstream_host = var.upstream_entity_name
    upstream_port = 80
    upstream_fallback = true
  }

  control_plane_id = konnect_gateway_control_plane.my_konnect_cp.id
}

This example requires the following variables to be added to your manifest. You can specify values at runtime by setting TF_VAR_name=value.

variable "upstream_entity_name" {
  type = string
}

Add this section to your kong.yaml configuration file:

_format_version: "3.0"
plugins:
  - name: canary
    service: serviceName|Id
    config:
      percentage: 50
      upstream_host: ${{ env "DECK_UPSTREAM_ENTITY_NAME" }}
      upstream_port: 80
      upstream_fallback: true

Make sure to replace the following placeholders with your own values:

serviceName|Id: The id or name of the service the plugin configuration will target.

Make the following request:

curl -i -X POST http://localhost:8001/services/{serviceName|Id}/plugins/ \
    --header "Accept: application/json" \
    --header "Content-Type: application/json" \
    --data '
    {
      "name": "canary",
      "config": {
        "percentage": 50,
        "upstream_host": "'$UPSTREAM_ENTITY_NAME'",
        "upstream_port": 80,
        "upstream_fallback": true
      }
    }
    '

Make sure to replace the following placeholders with your own values:

serviceName|Id: The id or name of the service the plugin configuration will target.

Make the following request:

curl -X POST https://{region}.api.konghq.com/v2/control-planes/{controlPlaneId}/core-entities/services/{serviceId}/plugins/ \
    --header "accept: application/json" \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer $KONNECT_TOKEN" \
    --data '
    {
      "name": "canary",
      "config": {
        "percentage": 50,
        "upstream_host": "'$UPSTREAM_ENTITY_NAME'",
        "upstream_port": 80,
        "upstream_fallback": true
      }
    }
    '

Make sure to replace the following placeholders with your own values:

region: Geographic region where your Kong Konnect is hosted and operates.
controlPlaneId: The id of the control plane.
KONNECT_TOKEN: Your Personal Access Token (PAT) associated with your Konnect account.
serviceId: The id of the service the plugin configuration will target.

See the Konnect API reference to learn about region-specific URLs and personal access tokens.

Prerequisite: Configure your Personal Access Token

terraform {
  required_providers {
    konnect = {
      source  = "kong/konnect"
    }
  }
}

provider "konnect" {
  personal_access_token = "$KONNECT_TOKEN"
  server_url            = "https://us.api.konghq.com/"
}

Add the following to your Terraform configuration to create a Konnect Gateway Plugin:

resource "konnect_gateway_plugin_canary" "my_canary" {
  enabled = true

  config = {
    percentage = 50
    upstream_host = var.upstream_entity_name
    upstream_port = 80
    upstream_fallback = true
  }

  control_plane_id = konnect_gateway_control_plane.my_konnect_cp.id
  service = {
    id = konnect_gateway_service.my_service.id
  }
}

This example requires the following variables to be added to your manifest. You can specify values at runtime by setting TF_VAR_name=value.

variable "upstream_entity_name" {
  type = string
}

Add this section to your kong.yaml configuration file:

_format_version: "3.0"
plugins:
  - name: canary
    route: routeName|Id
    config:
      percentage: 50
      upstream_host: ${{ env "DECK_UPSTREAM_ENTITY_NAME" }}
      upstream_port: 80
      upstream_fallback: true

Make sure to replace the following placeholders with your own values:

routeName|Id: The id or name of the route the plugin configuration will target.

Make the following request:

curl -i -X POST http://localhost:8001/routes/{routeName|Id}/plugins/ \
    --header "Accept: application/json" \
    --header "Content-Type: application/json" \
    --data '
    {
      "name": "canary",
      "config": {
        "percentage": 50,
        "upstream_host": "'$UPSTREAM_ENTITY_NAME'",
        "upstream_port": 80,
        "upstream_fallback": true
      }
    }
    '

Make sure to replace the following placeholders with your own values:

routeName|Id: The id or name of the route the plugin configuration will target.

Make the following request:

curl -X POST https://{region}.api.konghq.com/v2/control-planes/{controlPlaneId}/core-entities/routes/{routeId}/plugins/ \
    --header "accept: application/json" \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer $KONNECT_TOKEN" \
    --data '
    {
      "name": "canary",
      "config": {
        "percentage": 50,
        "upstream_host": "'$UPSTREAM_ENTITY_NAME'",
        "upstream_port": 80,
        "upstream_fallback": true
      }
    }
    '

Make sure to replace the following placeholders with your own values:

region: Geographic region where your Kong Konnect is hosted and operates.
controlPlaneId: The id of the control plane.
KONNECT_TOKEN: Your Personal Access Token (PAT) associated with your Konnect account.
routeId: The id of the route the plugin configuration will target.

See the Konnect API reference to learn about region-specific URLs and personal access tokens.

Prerequisite: Configure your Personal Access Token

terraform {
  required_providers {
    konnect = {
      source  = "kong/konnect"
    }
  }
}

provider "konnect" {
  personal_access_token = "$KONNECT_TOKEN"
  server_url            = "https://us.api.konghq.com/"
}

Add the following to your Terraform configuration to create a Konnect Gateway Plugin:

resource "konnect_gateway_plugin_canary" "my_canary" {
  enabled = true

  config = {
    percentage = 50
    upstream_host = var.upstream_entity_name
    upstream_port = 80
    upstream_fallback = true
  }

  control_plane_id = konnect_gateway_control_plane.my_konnect_cp.id
  route = {
    id = konnect_gateway_route.my_route.id
  }
}

This example requires the following variables to be added to your manifest. You can specify values at runtime by setting TF_VAR_name=value.

variable "upstream_entity_name" {
  type = string
}

Canary Release

Use health checksv1.0+

Prerequisites

Environment variables

Set up the plugin

Help us make these docs great!

Still need help