Skip to content

Commit 6315f90

Browse files
abrennan89abrennan89
authored
Merge pull request #36233 from abrennan89/greenblue
SRVKS-604: traffic mgmt docs update
2 parents e38a727 + 9fc740f commit 6315f90

14 files changed

+337
-154
lines changed

‎_topic_map.yml‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3115,10 +3115,10 @@ Topics:
31153115
# Autoscaling
31163116
- Name: Configuring Knative Serving autoscaling
31173117
File: configuring-knative-serving-autoscaling
3118+
- Name: Traffic management
3119+
File: serverless-traffic-management
31183120
- Name: Cluster logging with OpenShift Serverless
31193121
File: cluster-logging-serverless
3120-
- Name: Splitting traffic between revisions
3121-
File: splitting-traffic-between-revisions-knative
31223122
# Tracing
31233123
- Name: Tracing requests using Jaeger
31243124
File: serverless-tracing

‎images/knative-service-architecture.png‎

44.2 KB
Loading

‎modules/odc-splitting-traffic-between-revisions-using-developer-perspective.adoc‎

Lines changed: 5 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,18 +1,15 @@
1-
// Module is included in the following assemblies:
2-
//
3-
// serverless/splitting-traffic-between-revisions-knative.adoc
4-
51
[id="odc-splitting-traffic-between-revisions-using-developer-perspective_{context}"]
6-
= Splitting traffic between revisions using the Developer perspective
2+
= Managing traffic between revisions by using the {product-title} web console
73

8-
After you create a serverless application, the serverless application is displayed in the *Topology* view of the *Developer* perspective. The application revision is represented by the node and the serverless resource service is indicated by a quadrilateral around the node.
4+
After you create a serverless application, the application is displayed in the *Topology* view of the *Developer* perspective in the {product-title} web console. The application revision is represented by the node, and the Knative service is indicated by a quadrilateral around the node.
95

10-
Any new change in the code or the service configuration triggers a revision, 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.
6+
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.
117

128
.Procedure
9+
1310
To split traffic between multiple revisions of an application in the *Topology* view:
1411

15-
. Click the serverless resource service, indicated by the quadrilateral, to see its overview in the side panel.
12+
. Click the Knative service to see its overview in the side panel.
1613
. Click the *Resources* tab, to see a list of *Revisions* and *Routes* for the service.
1714
+
1815
.Serverless application

‎modules/serverless-blue-green-deploy.adoc‎

Lines changed: 123 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,123 @@
1+
[id="serverless-blue-green-deploy_{context}"]
2+
= Routing and managing traffic by using a blue-green deployment strategy
3+
4+
You can safely reroute traffic from a production version of an app to a new version, by using a link:https://en.wikipedia.org/wiki/Blue-green_deployment[blue-green deployment strategy].
5+
6+
.Procedure
7+
8+
. Create and deploy an app as a Knative service.
9+
10+
. Find the name of the first revision that was created when you deployed the service, by viewing the output from the following command:
11+
+
12+
[source,terminal]
13+
----
14+
$ oc get ksvc <service_name> -o=jsonpath='{.status.latestCreatedRevisionName}'
15+
----
16+
+
17+
.Example command
18+
[source,terminal]
19+
----
20+
$ oc get ksvc example-service -o=jsonpath='{.status.latestCreatedRevisionName}'
21+
----
22+
+
23+
.Example output
24+
[source,terminal]
25+
----
26+
$ example-service-00001
27+
----
28+
29+
. Add the following YAML to the service `spec` to send inbound traffic to the revision:
30+
+
31+
[source,yaml]
32+
----
33+
...
34+
spec:
35+
traffic:
36+
- revisionName: <first_revision_name>
37+
percent: 100 # All traffic goes to this revision
38+
...
39+
----
40+
41+
. Verify that you can view your app at the URL output you get from running the following command:
42+
+
43+
[source,terminal]
44+
----
45+
$ oc get ksvc <service_name>
46+
----
47+
48+
. Deploy a second revision of your app by modifying at least one field in the `template` spec of the service and redeploying it. For example, you can modify the `image` of the service, or an `env` environment variable. You can redeploy the service by applying the service YAML file, or by using the `kn service update` command if you have installed the `kn` CLI.
49+
50+
. Find the name of the second, latest revision that was created when you redeployed the service, by running the command:
51+
+
52+
[source,terminal]
53+
----
54+
$ oc get ksvc <service_name> -o=jsonpath='{.status.latestCreatedRevisionName}'
55+
----
56+
+
57+
At this point, both the first and second revisions of the service are deployed and running.
58+
59+
. Update your existing service to create a new, test endpoint for the second revision, while still sending all other traffic to the first revision:
60+
+
61+
.Example of updated service spec with test endpoint
62+
[source,yaml]
63+
----
64+
...
65+
spec:
66+
traffic:
67+
- revisionName: <first_revision_name>
68+
percent: 100 # All traffic is still being routed to the first revision
69+
- revisionName: <second_revision_name>
70+
percent: 0 # No traffic is routed to the second revision
71+
tag: v2 # A named route
72+
...
73+
----
74+
+
75+
After you redeploy this service by reapplying the YAML resource, the second revision of the app is now staged. No traffic is routed to the second revision at the main URL, and Knative creates a new service named `v2` for testing the newly deployed revision.
76+
77+
. Get the URL of the new service for the second revision, by running the following command:
78+
+
79+
[source,terminal]
80+
----
81+
$ oc get ksvc <service_name> --output jsonpath="{.status.traffic[*].url}"
82+
----
83+
+
84+
You can use this URL to validate that the new version of the app is behaving as expected before you route any traffic to it.
85+
86+
. Update your existing service again, so that 50% of traffic is sent to the first revision, and 50% is sent to the second revision:
87+
+
88+
.Example of updated service spec splitting traffic 50/50 between revisions
89+
[source,yaml]
90+
----
91+
...
92+
spec:
93+
traffic:
94+
- revisionName: <first_revision_name>
95+
percent: 50
96+
- revisionName: <second_revision_name>
97+
percent: 50
98+
tag: v2
99+
...
100+
----
101+
102+
. When you are ready to route all traffic to the new version of the app, update the service again to send 100% of traffic to the second revision:
103+
+
104+
.Example of updated service spec sending all traffic to the second revision
105+
[source,yaml]
106+
----
107+
...
108+
spec:
109+
traffic:
110+
- revisionName: <first_revision_name>
111+
percent: 0
112+
- revisionName: <second_revision_name>
113+
percent: 100
114+
tag: v2
115+
...
116+
----
117+
+
118+
[TIP]
119+
====
120+
You can remove the first revision instead of setting it to 0% of traffic if you do not plan to roll back the revision. Non-routeable revision objects are then garbage-collected.
121+
====
122+
123+
. Visit the URL of the first revision to verify that no more traffic is being sent to the old version of the app.

‎modules/serverless-custom-revision-urls.adoc‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
[id="serverless-custom-revision-urls_{context}"]
2+
= Custom URLs for revisions
3+
4+
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>`.
5+
6+
The `--tag` and `--untag` flags use the following syntax:
7+
8+
* Require one value.
9+
* Denote a unique tag in the traffic block of the service.
10+
* Can be specified multiple times in one command.
11+
12+
[id="serverless-custom-revision-urls-assign_{context}"]
13+
== Example: Assign a tag to a revision
14+
15+
The following example assigns the tag `latest` to a revision named `example-revision`:
16+
17+
[source,terminal]
18+
----
19+
$ kn service update <service_name> --tag @latest=example-tag
20+
----
21+
22+
[id="serverless-custom-revision-urls-remove_{context}"]
23+
== Example: Remove a tag from a revision
24+
25+
You can remove a tag to remove the custom URL, by using the `--untag` flag.
26+
27+
[NOTE]
28+
====
29+
If a revision has its tags removed, and it is assigned 0% of the traffic, the revision is removed from the traffic block entirely.
30+
====
31+
32+
The following command removes all tags from the revision named `example-revision`:
33+
34+
[source,terminal]
35+
----
36+
$ kn service update <service_name> --untag example-tag
37+
----

‎modules/serverless-traffic-management-kn.adoc‎

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
[id="serverless-traffic-management-kn_{context}"]
2+
= Traffic management using the Knative CLI
3+
4+
You can use the `kn service update` command to split traffic between revisions of a service.
5+
6+
.Example command
7+
[source,terminal]
8+
----
9+
$ kn service update <service_name> --traffic <revision>=<percent>
10+
----
11+
12+
Where:
13+
14+
* `<service_name>` is the name of the Knative service that you are configuring traffic routing for.
15+
* `<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.
16+
* `<percent>` is the percentage of traffic that you want to send to the specified revision.
17+
18+
[id="serverless-traffic-management-kn-precedence_{context}"]
19+
== Multiple flags and order precedence
20+
21+
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.
22+
23+
The precedence of the flags as they are evaluated by `kn` are:
24+
25+
. `--untag`: All the referenced revisions with this flag are removed from the traffic block.
26+
. `--tag`: Revisions are tagged as specified in the traffic block.
27+
. `--traffic`: The referenced revisions are assigned a portion of the traffic split.
28+
+
29+
[IMPORTANT]
30+
====
31+
The `--traffic` flag can be specified multiple times in one command, and is valid only if the sum of the `Percent` values in all flags totals 100.
32+
====
33+
34+
You can add tags to revisions and then split traffic according to the tags you have set.
35+
36+
[id="serverless-traffic-management-kn-example_{context}"]
37+
== Example traffic management commands
38+
39+
In the following command, the `@latest` tag means that `blue` resolves to the latest revision of the service:
40+
41+
[source,terminal]
42+
----
43+
$ kn service update example-service --tag green=revision-0001 --tag blue=@latest
44+
----
45+
46+
After the `green` and `blue` tags have been applied, you can run the following command to split traffic for the service named `example-service`, by sending 80% of traffic to the revision `green` and 20% of traffic to the revision `blue`:
47+
48+
[source,terminal]
49+
----
50+
$ kn service update example-service --traffic green=80 --traffic blue=20
51+
----
52+
53+
Alternatively, you could use the following command to send 80% of traffic to the latest revision and 20% to a revision named `v1`, without using tags:
54+
55+
[source,terminal]
56+
----
57+
$ kn service update example-service --traffic @latest=80 --traffic v1=20
58+
----
59+
60+
[NOTE]
61+
====
62+
You can only use the identifier `@latest` once per command with the `--traffic` flag.
63+
====

‎modules/serverless-traffic-routing-examples.adoc‎

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
[id="serverless-traffic-routing-examples_{context}"]
2+
= Traffic routing examples
3+
4+
When you create a Knative service, it does not have any default `traffic` spec settings. By setting the `traffic` spec, you can split traffic over any number of fixed revisions, or send traffic to the latest revision.
5+
6+
[id="serverless-traffic-routing-examples-multiple-revisions_{context}"]
7+
== Traffic routing between multiple revisions
8+
9+
The following example shows how the list of revisions in the `traffic` spec can be extended so that traffic is split between multiple revisions.
10+
11+
This example sends 50% of traffic to the revision tagged as `current`, and 50% of traffic to the revision tagged as `candidate`:
12+
13+
[source,yaml]
14+
----
15+
apiVersion: serving.knative.dev/v1
16+
kind: Service
17+
metadata:
18+
name: example-service
19+
namespace: default
20+
spec:
21+
...
22+
traffic:
23+
- tag: current
24+
revisionName: example-service-1
25+
percent: 50
26+
- tag: candidate
27+
revisionName: example-service-2
28+
percent: 50
29+
- tag: latest
30+
latestRevision: true
31+
percent: 0
32+
----
33+
34+
[id="serverless-traffic-routing-examples-latest-revision_{context}"]
35+
== Traffic routing to the latest revision
36+
37+
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:
38+
39+
[source,yaml]
40+
----
41+
apiVersion: serving.knative.dev/v1
42+
kind: Service
43+
metadata:
44+
name: example-service
45+
namespace: default
46+
spec:
47+
...
48+
traffic:
49+
- latestRevision: true
50+
percent: 100
51+
status:
52+
...
53+
traffic:
54+
- percent: 100
55+
revisionName: example-service
56+
----
57+
58+
[id="serverless-traffic-routing-examples-current-revision_{context}"]
59+
== Traffic routing to the current revision
60+
61+
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:
62+
63+
[source,yaml]
64+
----
65+
apiVersion: serving.knative.dev/v1
66+
kind: Service
67+
metadata:
68+
name: example-service
69+
namespace: default
70+
spec:
71+
...
72+
traffic:
73+
- tag: current
74+
revisionName: example-service
75+
percent: 100
76+
- tag: latest
77+
latestRevision: true
78+
percent: 0
79+
----

‎modules/serverless-workflow-tag-revisions-assign.adoc‎

Lines changed: 0 additions & 44 deletions
This file was deleted.

0 commit comments

Comments
 (0)