[GEP-1911] Update BackendRef with GEP details

[dprotaso]

/kind gep
/kind documentation

What this PR does / why we need it:

• This takes GEP-1911 and updates the godoc for BackendRef
• Mention users can signal backend protocol using ServicePort.protocol

Which issue(s) this PR fixes:

Fixes #

Does this PR introduce a user-facing change?:

NONE

[dprotaso]

cc @andrew-su

/assign @robscott @shaneutt @youngnick

[dprotaso]

What's the equivalent of <gateway:experimental> ? I didn't want to add it to the godoc otherwise it would have marked BackendRef experimental which it's not

[robscott]

@dprotaso fortunately we actually added something for that recently:

gateway-api/apis/v1beta1/shared_types.go

Lines 174 to 176 in 18506b7

	// <gateway:experimental:description>
	// * Service (Mesh conformance profile, experimental, ClusterIP Services only)
	// </gateway:experimental:description>

[dprotaso]

hmm.. it didn't update HTTPRoute in the experimental channel 🤔

[dprotaso]

Random guess is the generator mutates the CRD - so we should be generating experimental types first (no mutations) then standard one)

[dprotaso]

Oddly we call DeepCopy() so 🤔

[dprotaso]

/hold

[dprotaso]

Following up - looks like the text is not updated on the HTTPRoute is because of how controller-tools works

Because BackendRef is inlined with HTTPBackendRef - the godoc present at the top level HTTPBackendRef is not present and neither is the godoc on BackendRef

For example this block doesn't appear in the CRD docs for HTTPRoute

gateway-api/apis/v1beta1/httproute_types.go

Lines 1115 to 1149 in 18506b7

	// BackendRef is a reference to a backend to forward matched requests to.
	//
	// A BackendRef can be invalid for the following reasons. In all cases, the
	// implementation MUST ensure the `ResolvedRefs` Condition on the Route
	// is set to `status: False`, with a Reason and Message that indicate
	// what is the cause of the error.
	//
	// A BackendRef is invalid if:
	//
	// * It refers to an unknown or unsupported kind of resource. In this
	// case, the Reason must be set to `InvalidKind` and Message of the
	// Condition must explain which kind of resource is unknown or unsupported.
	//
	// * It refers to a resource that does not exist. In this case, the Reason must
	// be set to `BackendNotFound` and the Message of the Condition must explain
	// which resource does not exist.
	//
	// * It refers a resource in another namespace when the reference has not been
	// explicitly allowed by a ReferenceGrant (or equivalent concept). In this
	// case, the Reason must be set to `RefNotPermitted` and the Message of the
	// Condition must explain which cross-namespace reference is not allowed.
	//
	// * It refers to a Kubernetes Service that has an incompatible appProtocol
	// for the given Route type
	//
	// Support: Core for Kubernetes Service
	//
	// Support: Implementation-specific for any other resource
	//
	// Support for weight: Core
	//
	// Support for Kubernetes Service appProtocol: Extended
	//
	// +optional
	BackendRef `json:",inline"`

Instead what shows up in the CRD description is just the HTTPBackendRef godoc

gateway-api/apis/v1beta1/httproute_types.go

Lines 1113 to 1114 in 18506b7

	// HTTPBackendRef defines how a HTTPRoute should forward an HTTP request.
	type HTTPBackendRef struct {

@robscott @shaneutt @youngnick not sure what we want here - do you have opinions?

If we are strict about wanting this documentation to appear on the crd descriptions we'll have to duplicate the godoc and add it to the top of HTTPBackendRef

[dprotaso]

If we're otherwise good with the docs as they are on the types then feel free to drop the /hold

[robscott]

Thanks @dprotaso! I actually ended up with more questions this time around as I dug into it a bit more, hopefully these make sense.

[youngnick]

LGTM so I'll hit the approve button, @robscott up to you after that.

/approve

[k8s-ci-robot]

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: dprotaso, 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

[robscott]

Thanks @dprotaso! Just a few more nits but otherwise LGTM.

[robscott]

Thanks @dprotaso!

/lgtm
/hold cancel

[robscott]

One non-blocking thing I missed, do you mind adding a release note to the release note block of this PR @dprotaso? (Can happen post-merge, just helps us not miss anything when we're generating the changelog).