mirror of https://github.com/knative/client.git
150 lines
7.5 KiB
Markdown
150 lines
7.5 KiB
Markdown
# Traffic Operations
|
|
|
|
`kn` supports the following traffic operations on traffic block of a Service as
|
|
part of `kn service update` command.
|
|
|
|
## Split Traffic
|
|
|
|
Every time you update the Service's template, a new Revision is created with
|
|
100% traffic routing to it. With every update to the Configuration of the
|
|
Service, a new Revision is created with Service route pointing all the traffic
|
|
to the latest ready Revision by default. However, we can change this behavior by
|
|
defining which Revision gets what portion of the traffic. For example, you might
|
|
want to carefully roll out 10% of traffic to your new Revision before putting
|
|
all traffic on it.
|
|
|
|
Updating the traffic is performed by `kn service update` with the `--traffic`
|
|
flag.
|
|
|
|
**`--traffic RevisionName=Percent`**
|
|
|
|
- `--traffic` flag requires two values separated by a `=`
|
|
- `RevisionName` string refers to name of Revision and `Percent` integer denotes
|
|
the traffic portion to assign for this Revision
|
|
- `Percent` integer denotes the traffic portion to assign to the this Revision
|
|
- Use identifier `@latest` for RevisionName to refer to the latest ready
|
|
Revision of the service, you can use this identifier only once with
|
|
`--traffic` flag
|
|
- If the `service update` command is updating the Configuration values for the
|
|
Service (along with traffic flags), `@latest` reference will be pointed to the
|
|
created Revision after applying the update
|
|
- `--traffic` flag can be specified multiple times and is valid only if the sum
|
|
of `Percent` values in all flags add up to 100
|
|
- Example: `kn service update svc --traffic @latest=10 --traffic svc-vwxyz=90`
|
|
|
|
### Tag Revisions
|
|
|
|
A tag in traffic block of Service creates a custom URL, which points to the
|
|
referenced Revision. A user can define a unique tag for an available Revision of
|
|
the Service thereby generating a custom URL of format
|
|
`http(s)://TAG-SERVICE.DOMAIN`. A given tag must be unique in traffic block of
|
|
the Service. `kn` supports assigning and unassigning custom tags for revisions
|
|
of the Service as part of `kn service update` command as follow:
|
|
|
|
**`--tag RevisionName=Tag`**
|
|
|
|
- `--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 identifier `@latest` for RevisionName to refer to the latest ready
|
|
Revision of the service, you can use this identifier only once with `--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 same Revision, repeat the flag with
|
|
same Revision name and different tags
|
|
- Example:
|
|
`kn service update svc --tag @latest=candidate --tag svc-vwxyz=current`
|
|
|
|
_Note_:
|
|
|
|
- If you have assigned a tag to a particular Revision, a user can reference the
|
|
Revision by its tag in `--traffic` flag as `--traffic Tag=Percent`.
|
|
- User can specify `--traffic` and `--tag` flags in same `service update`
|
|
command and allowed to use the new tag for Revision reference for eg:
|
|
`kn service update svc --tag echo-abcde=stable --traffic stable=100`.
|
|
|
|
### Untag Revisions:
|
|
|
|
Assigned tags to revisions in traffic block can be unassigned, thereby removing
|
|
any custom URLs. A user can unassign the tags for revisions as part of
|
|
`kn service update` command as follow:
|
|
|
|
**`--untag Tag`**
|
|
|
|
- `--untag` flag requires one value
|
|
- `tag` string denotes the unique tag in traffic block of the Service which
|
|
needs to be unassigned and thereby also removing respective custom URL
|
|
- `--untag` flag can be specified multiple times
|
|
- Example: `kn service update svc --untag candidate`
|
|
|
|
**_NOTE_**:
|
|
|
|
- If a Revision is untagged and it is assigned 0% of the traffic, it is removed
|
|
from the traffic block entirely.
|
|
|
|
## Flag operation precedence
|
|
|
|
- All the traffic-related flags can bespecified together in a single
|
|
`kn service update` command, thus `kn` defines the precedence of these flags
|
|
in which operations are evaluated.
|
|
- The order of the flags specified in the command are **not** taken into
|
|
account.
|
|
- The precedence of flag(s) as they are evaluated by `kn`:
|
|
|
|
1. `--untag`: First, all the referenced tags by this flag are removed from the
|
|
traffic block
|
|
2. `--tag`: Second, all the revisions are tagged as specified in the traffic
|
|
block
|
|
3. `--traffic`: Third, all the referenced revisions (or tags) are assigned given
|
|
portion of traffic split
|
|
|
|
**_NOTE_**:
|
|
|
|
- Use comma separated value pairs or separate value pairs: For example:
|
|
`--tag echo-v1=v1,echo-v2=v2` is same as `--tag echo-v1=v1 --tag echo-v2=v2`
|
|
similarly, `--traffic v1=50,v2=50` is same as
|
|
`--traffic v1=50 --traffic v2=50` also, `--untag v1,v2` is same
|
|
`--untag v1 --untag v2`
|
|
- `--untag` flag's action takes first precedence. If `--untag` and `--tag` flags
|
|
specified together for revisions, all the mentioned tags will be unassigned
|
|
from revisions first, followed by tagging them.
|
|
- Updating a tag for Revision requires untagging its existing tag and assigning
|
|
a new tag. For example, to update tag from 'testing' to 'staging' for Revision
|
|
'echo-v1': `--untag testing --tag staging`
|
|
- If a tag is assigned to a Revision and user tries to use same tag for another
|
|
Revision, an error is raised.
|
|
- If a tag is assigned to a Revision and user tries to tag the same Revision
|
|
with a new tag again, a new target is created with 0% traffic and new tag.
|
|
- To assign multiple tags to same Revision, do
|
|
`--tag sameRevisionName=tagName1 --tag sameRevisionName=tagName2`.
|
|
- Repetition of `@latest` identifier for `--traffic` and `--tag` flags is not
|
|
allowed.
|
|
- Repetition of revisionName or tagName for `--traffic` flag is not allowed;
|
|
- If you want to have same revision present in multiple targets, use different
|
|
tags to uniquely identify targets, and use unique tag names to assign
|
|
traffic portions. For example:
|
|
`kn service update svc --tag echo-v1=v1,echo-v2=v2, --traffic v1=50,v2=50`
|
|
- If one traffic block target has revisionName which matches tagName of another
|
|
target, tagName is looked up first for assigning traffic. For example,
|
|
`--traffic targetRef:percent` will assign mentioned `percent` to target where
|
|
tag is `targetRef`. **Tags are unique** in traffic block, **RevisionNames are
|
|
not**, use tag reference in such scenarios.
|
|
|
|
## Summary
|
|
|
|
Following table shows quick summary for traffic splitting flags, their value
|
|
formats, operation to perform and _Repetition_ column denotes if repeating the
|
|
particular value of flag is allowed in a `kn service update` command.
|
|
|
|
| Flag | Value(s) | Operation | Repetition |
|
|
| :---------- | :--------------------: | :-------------------------------------------------- | :----------------------: |
|
|
| `--traffic` | `RevisionName=Percent` | Give `Percent` traffic to `RevisionName` | :heavy_check_mark: |
|
|
| `--traffic` | `Tag=Percent` | Give `Percent` traffic to the Revision having `Tag` | :heavy_check_mark: |
|
|
| `--traffic` | `@latest=Percent` | Give `Percent` traffic to the latest ready Revision | :heavy_multiplication_x: |
|
|
| `--tag` | `RevisionName=Tag` | Give `Tag` to `RevisionName` | :heavy_check_mark: |
|
|
| `--tag` | `@latest=Tag` | Give `Tag` to the latest ready Revision | :heavy_multiplication_x: |
|
|
| `--untag` | `Tag` | Remove `Tag` from Revision | :heavy_check_mark: |
|