Add example values for initial scale cluster flags

[taragu]

Fixes #7682

Proposed Changes

• Add initial scale cluster flags to examples

Release Note

Users can specify the size of the initial deployment with both cluster-wide flag initial-scale, and annotation "autoscaling.internal.knative.dev/initialScale". Cluster-wide flag allow-zero-initial-scale controls whether the cluster-wide and revision initial scale can be zero.

[markusthoemmes]

Can you please create (and link) a docs PR in the same go? (cc @abrennan89)

[knative-test-reporter-robot]

The following jobs failed:

Test name	Triggers	Retries
pull-knative-serving-unit-tests		0/3

Failed non-flaky tests preventing automatic retry of pull-knative-serving-unit-tests:

pkg/apis/config.TestStoreLoadWithContext
pkg/apis/config.TestStoreLoadWithContextOrDefaults
pkg/apis/config.TestStoreImmutableConfig
pkg/autoscaler/config.TestOurConfig
pkg/reconciler/autoscaling/config.TestStoreLoadWithContext
pkg/reconciler/autoscaling/config.TestStoreImmutableConfig
pkg/reconciler/revision/config.TestStoreLoadWithContext
pkg/reconciler/revision/config.TestStoreImmutableConfig

[taragu]

@markusthoemmes sure! @abrennan89 where would the doc belong? I was checking the docs repo, and it seems there are only high level concepts below https://github.com/knative/docs/tree/master/docs/serving/autoscaling

[markusthoemmes]

https://github.com/knative/docs/blob/master/docs/serving/autoscaling/scale-bounds.md maybe?

[vagababov]

so we permit to create a revision with autoscaling.knative.dev/initialScale==0 when feature is off, rather than just default with cluster wide value?

[taragu]

no we don't permit creating a new revision with autoscaling.knative.dev/initialScale==0, but if there's an existing revision with initialScale 0, we will default with cluster wide value

[vagababov]

it doesn't make sense :-) Existing revision is exempt from these policies, since they only apply at creation :)

[taragu]

ahh yeah that's true. so then we will just block new revision creation, and there won't be a problem with existing revisions.

[yanweiguo]

Here we are saying cluster wide value to override autoscaling.knative.dev/initialScale of a revision if autoscaling.knative.dev/initialScale==0 when allow-zero-initial-scale is false? But int allow-zero-initial-scale section we are saying new revision creation with autoscaling.knative.dev/initialScale==0 will not succeed if allow-zero-initial-scale is false. They are conflict.

[taragu]

@yanweiguo yes you are correct. i haven't made the update to the PR yet, but override autoscaling.knative.dev/initialScale of a revision if autoscaling.knative.dev/initialScale==0 when allow-zero-initial-scale is false should be removed.

[julz]

I think this isn't quite true. If allow-zero-initial-scale is false and the annotation value is zero, the cluster-wide default is used, which may be >1 if it was changed. (I'm not really sure how big an issue any of this really is since initial scale only applies once per revision anyway so "changing" initial scale for an existing revision only means something in some pretty small edge cases, but 🤷).

Also, stating both that true allows and false disallows seems redundant and this is already quite a lot of text. Maybe we could lose the "If this is set to true" paragraph and tighten the wording a bit, something like this (unless there's a nuance I missed)?

Suggested change

	# allow-zero-initial-scale is the cluster-wide flag to indicate whether
	# initial-scale is allowed to be 0.
	# If this is set to true, both the cluster-wide flag initial-scale and
	# the annotation "autoscaling.knative.dev/initialScale" are allowed
	# to be set to 0.
	# If this is set to false, the cluster-wide initial-scale value is not
	# allowed to be set to 0. If user attemps to deploy a new revision with
	# "autoscaling.knative.dev/initialScale" annotation set to 0,
	# the new revision will not be successfully created. If there's an existing
	# revision with "autoscaling.knative.dev/initialScale" annotation
	# set to 0, while allow-zero-initial-scale is changed from true to false,
	# the default value 1 will be used.
	# allow-zero-initial-scale controls whether either the cluster-wide initial-scale flag,
	# or the "autoscaling.knative.dev/initialScale" annotation, can be set to 0.
	# If this value is changed from true to false, existing "autoscaling.knative.dev/initialScale"
	# annotations with value 0 will be ignored.

[taragu]

Right, technically the cluster value will be used in this case of the cluster value changing from true to false, but since the initial scale only applies for new revisions. Yes sounds good, the true case is pretty self-explanatory so we can lose it.

[julz]

Reading through the rest of this configmap, I don't see anywhere else where we've talked about the overriding annotation in this much detail (or at all, in fact :-)), even though pretty much every value in the config map can be overridden in the same way. Would we miss anything important if we just said:

initial-scale is the cluster-wide default value for the initial target scale of a revision
after creation, unless overridden by the "autoscaling.knative.dev/initialScale" annotation.
This value must be greater than 0 unless allow-zero-initial-scale is true.

(and leave the existing description of allow-zero-initial-scale to cover the edge case where that changes true->false).

[taragu]

Yeah this is much simpler and I don't think we would be missing anything.

[yanweiguo]

/lgtm

[vagababov]

/lgtm
/approve

I think this is fine and if needed we can iterate.

[knative-prow-robot]

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: taragu, vagababov

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Needs approval from an approver in each of these files:

• config/OWNERS [vagababov]

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment