In a Knative application, traffic can be managed by creating a traffic split. A traffic split is configured as part of a route, which is managed by a Knative service.
Configuring a route allows requests to be sent to different revisions of a service. This routing is determined by the traffic
spec of the Service
object.
A traffic
spec declaration consists of one or more revisions, each responsible for handling a portion of the overall traffic. The percentages of traffic routed to each revision must add up to 100%, which is ensured by a Knative validation.
The revisions specified in a traffic
spec can either be a fixed, named revision, or can point to the “latest” revision, which tracks the head of the list of all revisions for the service. The "latest" revision is a type of floating reference that updates if a new revision is created. Each revision can have a tag attached that creates an additional access URL for that revision.
The traffic
spec can be modified by:
Editing the YAML of a Service
object directly.
Using the Knative (kn
) CLI --traffic
flag.
Using the OpenShift Container Platform web console.
When you create a Knative service, it does not have any default traffic
spec settings.
The following example shows a traffic
spec where 100% of traffic is routed to the latest revision of the service. Under status
, you can see the name of the latest revision that latestRevision
resolves to:
apiVersion: serving.knative.dev/v1
kind: Service
metadata:
name: example-service
namespace: default
spec:
...
traffic:
- latestRevision: true
percent: 100
status:
...
traffic:
- percent: 100
revisionName: example-service
The following example shows a traffic
spec where 100% of traffic is routed to the revision tagged as current
, and the name of that revision is specified as example-service
. The revision tagged as latest
is kept available, even though no traffic is routed to it:
apiVersion: serving.knative.dev/v1
kind: Service
metadata:
name: example-service
namespace: default
spec:
...
traffic:
- tag: current
revisionName: example-service
percent: 100
- tag: latest
latestRevision: true
percent: 0
The following example shows how the list of revisions in the traffic
spec can be extended so that traffic is split between multiple revisions. This example sends 50% of traffic to the revision tagged as current
, and 50% of traffic to the revision tagged as candidate
. The revision tagged as latest
is kept available, even though no traffic is routed to it:
apiVersion: serving.knative.dev/v1
kind: Service
metadata:
name: example-service
namespace: default
spec:
...
traffic:
- tag: current
revisionName: example-service-1
percent: 50
- tag: candidate
revisionName: example-service-2
percent: 50
- tag: latest
latestRevision: true
percent: 0
The Knative (kn
) CLI supports traffic operations on the traffic block of a service as part of the kn service update
command.
The following table displays a summary of traffic splitting flags, value formats, and the operation the flag performs. The Repetition column denotes whether repeating the particular value of flag is allowed in a kn service update
command.
Flag | Value(s) | Operation | Repetition |
---|---|---|---|
|
|
Gives |
Yes |
|
|
Gives |
Yes |
|
|
Gives |
No |
|
|
Gives |
Yes |
|
|
Gives |
No |
|
|
Removes |
Yes |
All traffic-related flags can be specified using a single kn service update
command. kn
defines the precedence of these flags. The order of the flags specified when using the command is not taken into account.
The precedence of the flags as they are evaluated by kn
are:
--untag
: All the referenced revisions with this flag are removed from the traffic block.
--tag
: Revisions are tagged as specified in the traffic block.
--traffic
: The referenced revisions are assigned a portion of the traffic split.
You can add tags to revisions and then split traffic according to the tags you have set.
Assigning a --tag
flag to a service by using the kn service update
command creates a custom URL for the revision that is created when you update the service. The custom URL follows the pattern https://<tag>-<service_name>-<namespace>.<domain>
or http://<tag>-<service_name>-<namespace>.<domain>
.
The --tag
and --untag
flags use the following syntax:
Require one value.
Denote a unique tag in the traffic block of the service.
Can be specified multiple times in one command.
The following example assigns the tag latest
to a revision named example-revision
:
$ kn service update <service_name> --tag @latest=example-tag
You can remove a tag to remove the custom URL, by using the --untag
flag.
If a revision has its tags removed, and it is assigned 0% of the traffic, the revision is removed from the traffic block entirely. |
The following command removes all tags from the revision named example-revision
:
$ kn service update <service_name> --untag example-tag
Using the Knative (kn
) CLI to create traffic splits provides a more streamlined and intuitive user interface over modifying YAML files directly. You can use the kn service update
command to split traffic between revisions of a service.
The OpenShift Serverless Operator and Knative Serving are installed on your cluster.
You have installed the Knative (kn
) CLI.
You have created a Knative service.
Specify the revision of your service and what percentage of traffic you want to route to it by using the --traffic
tag with a standard kn service update
command:
$ kn service update <service_name> --traffic <revision>=<percentage>
Where:
<service_name>
is the name of the Knative service that you are configuring traffic routing for.
<revision>
is the revision that you want to configure to receive a percentage of traffic. You can either specify the name of the revision, or a tag that you assigned to the revision by using the --tag
flag.
<percentage>
is the percentage of traffic that you want to send to the specified revision.
Optional: The --traffic
flag can be specified multiple times in one command. For example, if you have a revision tagged as @latest
and a revision named stable
, you can specify the percentage of traffic that you want to split to each revision as follows:
$ kn service update example-service --traffic @latest=20,stable=80
If you have multiple revisions and do not specify the percentage of traffic that should be split to the last revision, the --traffic
flag can calculate this automatically. For example, if you have a third revision named example
, and you use the following command:
$ kn service update example-service --traffic @latest=10,stable=60
The remaining 30% of traffic is split to the example
revision, even though it was not specified.
After you create a serverless application, the application is displayed in the Topology view of the Developer perspective in the OpenShift Container Platform web console. The application revision is represented by the node, and the Knative service is indicated by a quadrilateral around the node.
Any new change in the code or the service configuration creates a new revision, which is a snapshot of the code at a given time. For a service, you can manage the traffic between the revisions of the service by splitting and routing it to the different revisions as required.
The OpenShift Serverless Operator and Knative Serving are installed on your cluster.
You have logged in to the OpenShift Container Platform web console.
To split traffic between multiple revisions of an application in the Topology view:
Click the Knative service to see its overview in the side panel.
Click the Resources tab, to see a list of Revisions and Routes for the service.