1. Documentation
    2. Page history / Open an issue
×

Mapping and splitting traffic for different revisions of a service

With each update to the configuration of a service, a new revision for the service is created. The service route points all traffic to the latest ready revision by default. You can change this behavior by defining which revisions gets a portion of the traffic.

Knative services allow for traffic mapping, which means that revisions of a service can be mapped to an allocated portion of traffic. Traffic mapping also provides an option to create unique URLs for particular revisions.

Splitting traffic between revisions using the Developer perspective

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.

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.

Procedure

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

  1. Click the serverless resource service, indicated by the quadrilateral, 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 the Set Traffic Distribution button 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

Managing and splitting traffic by using the Knative CLI

kn provides commands that help you to control traffic mapping and how traffic is split between revisions.

You can use the kn service update command with the --traffic flag to update the traffic. This flag uses the following syntax:

--traffic RevisionName=Percent

where * The --traffic flag requires two values separated by separated by an equals sign (=). * The RevisionName string refers to the name of the revision. * Percent integer denotes the traffic portion assigned to the revision.

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.
Procedure

  • Update the percentage of traffic to be routed to a revision:

    $ kn service update --traffic <@revision_name>=<percent_integer>

    You can use the identifier @latest for the revision name, to refer to the latest ready revision of the service. You can use this identifier only once per command with the --traffic flag.

Assigning tag revisions

A tag in a traffic block of service creates a custom URL, which points to a referenced revision. A user can define a unique tag for an available revision of a service which creates a custom URL by using the format http(s)://TAG-SERVICE.DOMAIN.

A given tag must be unique to its traffic block of the service. kn supports assigning and unassigning custom tags for revisions of services as part of the kn service update command.

If you have assigned a tag to a particular revision, a user can reference the revision by its tag in the --traffic flag as --traffic Tag=Percent.
Procedure

  • Use the following command:

    $ kn service update svc --tag @latest=candidate --tag svc-vwxyz=current

--tag RevisionName=Tag uses the following syntax:

  • --tag flag requires two values separated by a =.

  • RevisionName string refers to name of the Revision.

  • Tag string denotes the custom tag to be given for this Revision.

  • Use the identifier @latest for the RevisionName to refer to the latest ready revision of the service. You can use this identifier only once with the --tag flag.

  • If the service update command is updating the configuration values for the Service (along with tag flags), @latest reference will be pointed to the created Revision after applying the update.

  • --tag flag can be specified multiple times.

  • --tag flag may assign different tags to the same revision.

Unassigning tag revisions

Tags assigned to revisions in a traffic block can be unassigned. Unassigning tags removes the custom URLs.

If a revision is untagged and it is assigned 0% of the traffic, it is removed from the traffic block entirely.
Procedure

  • A user can unassign the tags for revisions using the kn service update command:

    $ kn service update svc --untag candidate

--untag Tag uses the following syntax:

  • The --untag flag requires one value.

  • The tag string denotes the unique tag in the traffic block of the service which needs to be unassigned. This also removes the respective custom URL.

  • The --untag flag can be specified multiple times.

Traffic flag operation 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.

Traffic splitting flags by using the Knative CLI

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