You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
= Creating a traffic split by using the Knative CLI
8
+
9
+
Using the `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.
10
+
11
+
.Prerequisites
12
+
13
+
* The {ServerlessOperatorName} and Knative Serving are installed on your cluster.
14
+
* You have installed the `kn` CLI.
15
+
* You have created a Knative service.
16
+
17
+
.Procedure
18
+
19
+
* 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:
20
+
+
21
+
.Example command
22
+
[source,terminal]
23
+
----
24
+
$ kn service update <service_name> --traffic <revision>=<percentage>
25
+
----
26
+
+
27
+
Where:
28
+
+
29
+
**`<service_name>` is the name of the Knative service that you are configuring traffic routing for.
30
+
**`<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.
31
+
**`<percentage>` is the percentage of traffic that you want to send to the specified revision.
32
+
33
+
* 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:
34
+
+
35
+
.Example command
36
+
[source,terminal]
37
+
----
38
+
$ kn service update example-service --traffic @latest=20,stable=80
39
+
----
40
+
+
41
+
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:
42
+
+
43
+
.Example command
44
+
[source,terminal]
45
+
----
46
+
$ kn service update example-service --traffic @latest=10,stable=60
47
+
----
48
+
+
49
+
The remaining 30% of traffic is split to the `example` revision, even though it was not specified.
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.
55
+
56
+
The precedence of the flags as they are evaluated by `kn` are:
57
+
58
+
. `--untag`: All the referenced revisions with this flag are removed from the traffic block.
59
+
. `--tag`: Revisions are tagged as specified in the traffic block.
60
+
. `--traffic`: The referenced revisions are assigned a portion of the traffic split.
61
+
62
+
You can add tags to revisions and then split traffic according to the tags you have set.
// TODO later: consider splitting this into a conceptual module about revisions; would need to plan where these conceptual topics would be included in docs
10
-
A _revision_ is a point-in-time snapshot of the code and configuration for each modification made to a Knative service. Each time the configuration of a service is updated, a new revision for the service is created. Revisions are immutable objects and can be retained for as long as they are required or used. Knative Serving revisions can be automatically scaled up and down according to incoming traffic.
9
+
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.
11
10
12
-
You can manage traffic routing to different revisions of a Knative service by modifying the `traffic` spec of the service resource.
11
+
image::knative-service-architecture.png[Traffic management for a Knative application]
13
12
14
-
image::knative-service-architecture.png[Knative service architecture]
13
+
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.
14
+
// add additional resources link to knative services /apps docs
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.
17
+
18
+
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.
19
+
20
+
The `traffic` spec can be modified by:
21
+
22
+
* Editing the YAML of a `Service` object directly.
23
+
* Using the `kn` CLI `--traffic` flag.
24
+
* Using the {product-title} web console.
25
+
26
+
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:
32
+
33
+
[source,yaml]
34
+
----
35
+
apiVersion: serving.knative.dev/v1
36
+
kind: Service
37
+
metadata:
38
+
name: example-service
39
+
namespace: default
40
+
spec:
41
+
...
42
+
traffic:
43
+
- latestRevision: true
44
+
percent: 100
45
+
status:
46
+
...
47
+
traffic:
48
+
- percent: 100
49
+
revisionName: example-service
50
+
----
51
+
52
+
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:
53
+
54
+
[source,yaml]
55
+
----
56
+
apiVersion: serving.knative.dev/v1
57
+
kind: Service
58
+
metadata:
59
+
name: example-service
60
+
namespace: default
61
+
spec:
62
+
...
63
+
traffic:
64
+
- tag: current
65
+
revisionName: example-service
66
+
percent: 100
67
+
- tag: latest
68
+
latestRevision: true
69
+
percent: 0
70
+
----
71
+
72
+
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:
# move this to services / apps docs eventually, also include diagram again there
110
+
111
+
Each time the configuration of a service is updated, a new revision for the service is created.
112
+
113
+
A revision is a point-in-time snapshot of the code and configuration for each modification made to a Knative service. Revisions are immutable objects and can be retained for as long as they are required or used. Knative Serving revisions can be automatically scaled up and down according to incoming traffic.
0 commit comments