Specify SAN validation precedence over Hostname validation

[kl52752]

What type of PR is this?

/kind documentation

What this PR does / why we need it:
Documentation for BackendTLSPolicy is not complete regarding SAN validation.
Which issue(s) this PR fixes:

Relates to #3979

Does this PR introduce a user-facing change?:

NONE

[kl52752]

/assign @candita @robscott @shaneutt

[candita]

/approve
/lgtm
/hold cancel

[robscott]

The wording here is tricky to get right. Trying to make the distinction between "hostname" as a concept, and as a field.

Suggested change

	// 3. If SubjectAltNames are specified, Hostname MUST NOT be used for authentication,
	// even if this would cause a failure in the case that the SubjectAltNames do not match.
	// If you want to use Hostname for authentication, you must add Hostname to the SubjectAltNames list.
	// 3. If SubjectAltNames are specified, only the values in that list will be used for authentication. The
	// value of the Hostname field MUST NOT be used for authentication. If you want to use the value
	// of the Hostname field for authentication, you MUST add it to the SubjectAltNames list.

@youngnick might have a better suggestion here.

[youngnick]

I think the trick is to put the field Hostname in backticks, and use the capitalized form, and use "hostname" for the concept.

How about this:

Suggested change

	// 3. If SubjectAltNames are specified, Hostname MUST NOT be used for authentication,
	// even if this would cause a failure in the case that the SubjectAltNames do not match.
	// If you want to use Hostname for authentication, you must add Hostname to the SubjectAltNames list.
	// 3. If SubjectAltNames are specified, `Hostname` MUST NOT be used for authentication, and the list of hostnames
	// included in SubjectAltNames MUST be used instead.
	// Generally, users SHOULD include the value of `Hostname` in their SubjectAltNames list unless they have a good reason not to.

[robscott]

Yeah, that's great, thanks @youngnick!

[kl52752]

I rephrased it and used wording from GEP-3155

[kl52752]

@youngnick @robscott PTAL

[youngnick]

I added a suggestion here, but it's a small optimization, I think that either option is fine, and this change LGTM.

[robscott]

Thanks @kl52752!

/lgtm
/hold cancel

[youngnick]

/approve

[k8s-ci-robot]

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: candita, kl52752, youngnick

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:

• OWNERS [youngnick]

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