Getting Started Guide: Show the standard behaviour with server-side generated revisions name

[rhuss]

Describe the change you'd like to see

In the Getting started guide when creating the first service, the user is pointed to user client-side revision names by e.g. providing the --revision-name option (or a name for the revision template in the YAML). Client-side revision names have several drawbacks so that the client has switched to server-side naming by default since Knative 0.21:

• Original client issue discussion of the change in default behavior
• Longer discussion in this serving issue about benefits/drawbacks of client-side revision naming
• Client release notes with some description of real-world issues with client-side revisions names
• Pull request which switched to server-side naming for the client by default.

As pointed out by @mkedwards in this comment there is one valid use case for client-side naming though, as part of an automation process where you already have a unique identifier that can correlate the revision names to e.g a CI build-id directly (which however could also be done via meta-data like labels/annotations, but it's more convenient to have it in the name for visualizing in tooling). But still, this is an advanced use case that goes far beyond a 'My First Service' experience.

I would propose to guide the user along the default UX path by not providing client-side revision names and using server-side revisions for the initial examples (which makes it easier to understand as fewer concepts need to be explained and avoids forward references to "revisions" in the "first service example"). We can add client-side naming later as an alternative approach, but IMO it does not make sense to describe the non-default behavior first which also adds a focus on a deprecated feature (which even might disappear eventually in the future).

Additional context

The client-side revision ("hello-world" and "hello-knative") are also referenced in the scale-to-zero example and the traffic-split part, so those would need to be updated as well.

Could be added to the Epic #4553 if we can agree on this change.

[snneji]

Hi @rhuss, I agree that we should not have an advanced use case in the getting started guide. Better to replace this with the standard procedure as you mentioned in your comment. I also agree that we don't need to add client-side naming later in the getting started guide as an alternative approach, but maybe could be mentioned elsewhere in the docs.

I'm going to add this to our epic to improve the getting started guide.

[csantanapr]

we use revision name to be able to get revision name for the command on traffic split

kn service update hello \
--env TARGET=Knative \
--revision-name=knative

kn service update hello \
--traffic hello-world=50 \
--traffic @latest=50

We could switch to using tags then the commands would be like
create:

kn service update hello \
--env TARGET=Knative \
--tag v2

split:

kn service update hello \
--traffic v2=50 \
--traffic @latest=50

Maybe this means we need to introduce tags for the user to be able to find the revision to affect.

[csantanapr]

/assign

[csantanapr]

/close
The tutorial is now updated with PR #4815

[knative-prow]

@csantanapr: Closing this issue.

In response to this:

/close
The tutorial is now updated with PR #4815

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository.