Document that providers MUST validate references are in the same namespace

[detiber]

Goals

1. Replace current uses of corev1.ObjectReference with more appropriate types

Non-Goals/Future Work

1. Modify other types used

User Story

As a consumer of Cluster API I would like to have fields that are currently using corev1.ObjectReference to use more appropriate data types so that it is clear which fields are used (all of them) vs having to guess which fields are in use.

Detailed Description

Upstream documentation discourages the use of corev1.ObjectReference: https://godoc.org/k8s.io/api/core/v1#ObjectReference. In order to align better with upstream convention we should adopt types that are more fitting for their purpose.

When the referenced type is constant and in the same namespace, we should likely use corev1.LocalObjectReference instead.

When we also need type information for the referenced resource and that resource is in the same namespace, we should likely use corev1.TypedLocalReference

If for some reason we need to cross namespaces with a reference, we should likely create our own type that is a subset of corev1.ObjectReference

To ease this transition, we should gracefully handle the conversions within the conversion webhooks.

Contract changes [optional]

Any type that is currently using corev1.ObjectReference would be updated to a more appropriate type.

Data model changes [optional]

Any type that is currently using corev1.ObjectReference would be updated to a more appropriate type.

/kind proposal

[vincepri]

We really should just have one type with

    // API version of the referent.
    // +optional
    APIVersion string `json:"apiVersion,omitempty" protobuf:"bytes,5,opt,name=apiVersion"`
    // Kind of the referent.
    // More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds
    // +optional
    Kind string `json:"kind,omitempty" protobuf:"bytes,1,opt,name=kind"`
    // Namespace of the referent.
    // More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/
    // +optional
    Namespace string `json:"namespace,omitempty" protobuf:"bytes,2,opt,name=namespace"`
    // Name of the referent.
    // More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names
    // +optional
    Name string `json:"name,omitempty" protobuf:"bytes,3,opt,name=name"`

We can have it in our own types?

[detiber]

I'd rather avoid having a Namespace field where we do not allow cross-namespace references, otherwise it's just an extra thing we need to validate and adds potential for a poor user experience.

I would say the same thing for references that are known types (Secret, ConfigMap, etc), for similar reasons.

[enxebre]

cross referencing PR kubernetes/kubernetes#87459 to provide more context.

[detiber]

Also relevant PR to update the api conventions doc: kubernetes/community#4705

[vincepri]

/kind cleanup
/area api