×

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.

You can manage traffic routing to different revisions of a Knative service by modifying the traffic spec of the service resource.

Knative service architecture

Traffic routing examples

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.

Traffic routing between multiple revisions

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:

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

Traffic routing to the latest revision

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

Traffic routing to the current revision

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

Managing traffic between revisions by using the OpenShift Container Platform web console

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.

Procedure

To split traffic between multiple revisions of an application in the Topology view:

  1. Click the Knative service to see its overview in the side panel.

  2. Click the Resources tab, to see a list of Revisions and Routes for the service.

    odc serverless app
    Figure 1. Serverless application
  3. Click the service, indicated by the S icon at the top of the side panel, to see an overview of the service details.

  4. Click the YAML tab and modify the service configuration in the YAML editor, and click Save. For example, change the timeoutseconds from 300 to 301 . This change in the configuration triggers a new revision. In the Topology view, the latest revision is displayed and the Resources tab for the service now displays the two revisions.

  5. In the Resources tab, click Set Traffic Distribution to see the traffic distribution dialog box:

    1. Add the split traffic percentage portion for the two revisions in the Splits field.

    2. Add tags to create custom URLs for the two revisions.

    3. Click Save to see two nodes representing the two revisions in the Topology view.

      odc serverless revisions
      Figure 2. Serverless application revisions

Traffic management using the Knative CLI

You can use the kn service update command to split traffic between revisions of a service.

Example command
$ kn service update <service_name> --traffic <revision>=<percent>

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.

  • <percent> is the percentage of traffic that you want to send to the specified revision.

Multiple flags and order precedence

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:

  1. --untag: All the referenced revisions with this flag are removed from the traffic block.

  2. --tag: Revisions are tagged as specified in the traffic block.

  3. --traffic: The referenced revisions are assigned a portion of the traffic split.

    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.

You can add tags to revisions and then split traffic according to the tags you have set.

Example traffic management commands

In the following command, the @latest tag means that blue resolves to the latest revision of the service:

$ kn service update example-service --tag green=revision-0001 --tag blue=@latest

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:

$ kn service update example-service --traffic green=80 --traffic blue=20

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:

$ kn service update example-service --traffic @latest=80 --traffic v1=20

You can only use the identifier @latest once per command with the --traffic flag.

Knative CLI traffic management flags

The 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

--traffic

RevisionName=Percent

Gives Percent traffic to RevisionName

Yes

--traffic

Tag=Percent

Gives Percent traffic to the revision having Tag

Yes

--traffic

@latest=Percent

Gives Percent traffic to the latest ready revision

No

--tag

RevisionName=Tag

Gives Tag to RevisionName

Yes

--tag

@latest=Tag

Gives Tag to the latest ready revision

No

--untag

Tag

Removes Tag from revision

Yes

Custom URLs for revisions

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.

Example: Assign a tag to a revision

The following example assigns the tag latest to a revision named example-revision:

$ kn service update <service_name> --tag @latest=example-tag

Example: Remove a tag from a revision

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

Routing and managing traffic by using a blue-green deployment strategy

You can safely reroute traffic from a production version of an app to a new version, by using a blue-green deployment strategy.

Procedure
  1. Create and deploy an app as a Knative service.

  2. Find the name of the first revision that was created when you deployed the service, by viewing the output from the following command:

    $ oc get ksvc <service_name> -o=jsonpath='{.status.latestCreatedRevisionName}'
    Example command
    $ oc get ksvc example-service -o=jsonpath='{.status.latestCreatedRevisionName}'
    Example output
    $ example-service-00001
  3. Add the following YAML to the service spec to