Skip to content

Commit ac7999c

Browse files
committed
Addressing comments
including blurb recommending using multi resource object references if there is a chance it will be used that way.
1 parent bda0f50 commit ac7999c

File tree

1 file changed

+5
-2
lines changed

1 file changed

+5
-2
lines changed

contributors/devel/sig-architecture/api-conventions.md

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -934,7 +934,7 @@ objects expand, and therefore are backwards compatible.
934934
For example, it is possible to go from a single resource type to multiple resource types without
935935
a breaking change in the schema.
936936

937-
#### References to a single resource type
937+
#### Single resource reference
938938

939939
A single kind object reference is straightforward in that the controller can hard-code most qualifiers needed to identify the object. As such as the only value needed to be provided is the name (and namespace, although cross-namespace references are discouraged):
940940

@@ -948,11 +948,14 @@ secretRef:
948948
namespace: foo-namespace
949949
```
950950

951+
This schema should only be used when the intention is to always have the reference only be to a single resource.
952+
If extending to multiple resource types is possible, use the [multiple resource reference](#multiple-resource-reference).
953+
951954
##### Controller behavior
952955

953956
The operator is expected to know the version, group, and resource name of the object it needs to retrieve the value from, and can use the discovery client or construct the API path directly.
954957

955-
#### References which can point to multiple resource types
958+
#### Multiple resource reference
956959

957960
Multi-kind object references are used when there is a bounded set of valid resource types that a reference can point to.
958961

0 commit comments

Comments
 (0)