Project / Rollout Strategies /

Update service rollout configuration

Updates the traffic split of the active gradual rollout. Only percentage based rollouts can be reconfigured. Setting the canary to 100% promotes the rollout.

Required permission

Project > Services > General > Update

Path parameters

projectId
string required
ID of the project
serviceId
string required
ID of the service

Request body

{object}
The traffic split to apply to the active rollout.

canaryPercentage
integer required
Percentage of traffic to route to the canary deployment. Must sum to 100 with stablePercentage.
min
0
max
100
stablePercentage
integer required
Percentage of traffic to route to the stable deployment. Must sum to 100 with canaryPercentage.
min
0
max
100

Response body

{object}
Response object.

data
{object} required
Result data.

strategyId
string | null required
ID of the gradual rollout strategy this rollout was created from. Null if the strategy has since been deleted.
type
string required
Type of the gradual rollout strategy.
one of
canary
promoted
boolean required
Whether the canary has been promoted to stable. A promoted rollout serves all traffic from the canary deployment and can no longer be reconfigured.
createdAt
string required
Time the rollout started.
updatedAt
string required
Time the rollout was last changed.
options
{object}
Options inherited from the gradual rollout strategy.

triggers
{object}
Conditions under which a new release automatically starts a gradual rollout.

releaseFromTemplate
boolean | null
releaseFromReleaseFlow
boolean | null
releaseFromCD
boolean | null
releaseFromUI
boolean | null
releaseFromApi
boolean | null

blockDeploymentOnActiveRollout
boolean | null
Whether new deployments are blocked while this rollout is in progress.

details
{object} required
Traffic configuration of the rollout.

canaryStrategy
string required
How traffic is split between the stable and canary deployments.
one of
percentage, header
config
(multiple options: oneOf) required
Configuration for the active canary strategy.

{object}

canaryPercentage
integer required
Percentage of traffic to route to the canary deployment. Must sum to 100 with stablePercentage.
min
0
max
100
stablePercentage
integer required
Percentage of traffic to route to the stable deployment. Must sum to 100 with canaryPercentage.
min
0
max
100

{object}

canaryHeader
{object} required
Header that routes traffic to the canary deployment.

headerName
string required
headerValue
string required

stableHeader
{object} required
Header that routes traffic to the stable deployment.

headerName
string required
headerValue
string required

stableDeployment
{object} | null required
The deployment currently serving stable traffic.

id
string required
Identifier of the deployment. Use this as the rollback target.
name
string | null
Display name of the deployment. Null until the first pod of the deployment has been observed.
createdAt
string required
Time the deployment was created.
active
boolean
Whether the deployment is currently serving traffic. During a gradual rollout both the stable and the canary deployment are active.
releaseType
string
Current role of the deployment in the gradual rollout. This is mutable: promoting a canary deployment changes its release type to `stable`, so it does not record how the deployment was originally created. Absent for services that do not use a gradual rollout strategy.
one of
stable, canary
image
{object}
The image this deployment is running.

imagePath
string
Full path of the deployed image.
image
string
Name of the deployed image.
tag
string
Tag of the deployed image.
sha
string
Digest of the deployed image.

commit
{object}
The source commit this deployment was built from, for git backed services.

sha
string
Commit the deployed image was built from.
message
string
Commit message.
author
string
Login of the commit author.
date
(multiple options: anyOf)
Time the commit was authored.

string

instances
number | null
Number of instances the deployment was created with.
reason
{object}
What triggered the deployment.

id
string required
Why the deployment was created.
user
{object}
The user that caused the deployment, when it was user initiated.

name
string
Name of the acting user.
email
string
Email of the acting user.

canaryDeployment
{object} | null required
The deployment currently serving canary traffic.

id
string required
Identifier of the deployment. Use this as the rollback target.
name
string | null
Display name of the deployment. Null until the first pod of the deployment has been observed.
createdAt
string required
Time the deployment was created.
active
boolean
Whether the deployment is currently serving traffic. During a gradual rollout both the stable and the canary deployment are active.
releaseType
string
Current role of the deployment in the gradual rollout. This is mutable: promoting a canary deployment changes its release type to `stable`, so it does not record how the deployment was originally created. Absent for services that do not use a gradual rollout strategy.
one of
stable, canary
image
{object}
The image this deployment is running.

imagePath
string
Full path of the deployed image.
image
string
Name of the deployed image.
tag
string
Tag of the deployed image.
sha
string
Digest of the deployed image.

commit
{object}
The source commit this deployment was built from, for git backed services.

sha
string
Commit the deployed image was built from.
message
string
Commit message.
author
string
Login of the commit author.
date
(multiple options: anyOf)
Time the commit was authored.

string

instances
number | null
Number of instances the deployment was created with.
reason
{object}
What triggered the deployment.

id
string required
Why the deployment was created.
user
{object}
The user that caused the deployment, when it was user initiated.

name
string
Name of the acting user.
email
string
Email of the acting user.

history
[array] required
Previous traffic configurations of this rollout, oldest first.

{object}

config
(multiple options: anyOf) required
The traffic split or header configuration that was replaced.

{object}

canaryPercentage
integer required
Percentage of traffic to route to the canary deployment. Must sum to 100 with stablePercentage.
min
0
max
100
stablePercentage
integer required
Percentage of traffic to route to the stable deployment. Must sum to 100 with canaryPercentage.
min
0
max
100

{object}

canaryHeader
{object} required
Header that routes traffic to the canary deployment.

headerName
string required
headerValue
string required

stableHeader
{object} required
Header that routes traffic to the stable deployment.

headerName
string required
headerValue
string required

updatedAt
string required
Time the split was applied.

API

CLI

JS Client

POST /v1/projects/{projectId}/services/{serviceId}/rollout/configuration

POST /v1/teams/{teamId}/projects/{projectId}/services/{serviceId}/rollout/configuration

Example request

Request body

curl --header "Content-Type: application/json" \
  --header "Authorization: Bearer NORTHFLANK_API_TOKEN" \
  --request POST \
  --data '{"canaryPercentage":20,"stablePercentage":80}' \
  https://api.northflank.com/v1/projects/{projectId}/services/{serviceId}/rollout/configuration

Example response

200 OK

The rollout after the configuration was applied.

JSON

{
  "data": {
    "strategyId": "example-gradual-rollout-strategy",
    "type": "canary",
    "promoted": false,
    "createdAt": "2024-01-15T10:30:00.000Z",
    "updatedAt": "2024-01-15T11:30:00.000Z",
    "details": {
      "canaryStrategy": "percentage",
      "config": {
        "canaryPercentage": 20,
        "stablePercentage": 80
      }
    },
    "stableDeployment": {
      "id": "6560a1b2c3d4e5f6a7b8c9d0",
      "name": "example-service-7d9f8b6c5d",
      "createdAt": "2024-01-15T10:30:00.000Z",
      "active": true,
      "releaseType": "canary",
      "image": {
        "imagePath": "nginx:latest",
        "image": "nginx",
        "tag": "latest",
        "sha": "sha256:9c8f8d"
      },
      "commit": {
        "sha": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0",
        "message": "fix: handle empty payload",
        "author": "octocat"
      },
      "instances": 2,
      "reason": {
        "id": "service-updated",
        "user": {
          "name": "Jane Doe",
          "email": "jane@example.com"
        }
      }
    },
    "canaryDeployment": {
      "id": "6560a1b2c3d4e5f6a7b8c9d0",
      "name": "example-service-7d9f8b6c5d",
      "createdAt": "2024-01-15T10:30:00.000Z",
      "active": true,
      "releaseType": "canary",
      "image": {
        "imagePath": "nginx:latest",
        "image": "nginx",
        "tag": "latest",
        "sha": "sha256:9c8f8d"
      },
      "commit": {
        "sha": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0",
        "message": "fix: handle empty payload",
        "author": "octocat"
      },
      "instances": 2,
      "reason": {
        "id": "service-updated",
        "user": {
          "name": "Jane Doe",
          "email": "jane@example.com"
        }
      }
    },
    "history": [
      {
        "config": {
          "canaryPercentage": 20,
          "stablePercentage": 80
        },
        "updatedAt": "2024-01-15T10:45:00.000Z"
      }
    ]
  }
}

Example response

404 Not Found

The service does not have an active gradual rollout.

Example response

409 Conflict

The rollout has been promoted, splits traffic by header, or the canary deployment is not ready.