Merge pull request #2925 from nrb/doc-replicated-types

📖 Document data types that are replicated

docs/content/CONTRIBUTING.md

@@ -156,6 +156,33 @@ All of the built-in types for `kcp` are `CustomResourceDefinitions`, and we gene
 
 When adding a field that requires validation, custom annotations are used to translate this logic into the generated OpenAPI spec. [This doc](https://book.kubebuilder.io/reference/markers/crd-validation.html) gives an overview of possible validations. These annotations map directly to concepts in the [OpenAPI Spec](https://swagger.io/specification/#data-type-format) so, for instance, the `format` of strings is defined there, not in kubebuilder. Furthermore, Kubernetes has forked the OpenAPI project [here](https://github.com/kubernetes/kube-openapi/tree/master/pkg/validation) and extends more formats in the extensions-apiserver [here](https://github.com/kubernetes/kubernetes/blob/master/staging/src/k8s.io/apiextensions-apiserver/pkg/apis/apiextensions/v1/types_jsonschema.go#L27).
 
+
+### Replicated Data Types
+
+Some objects are replicated and cached amongst shards when `kcp` is run in a sharded configuration. When writing code to list or get these objects, be sure to reference both shard-local and cache informers. To make this more convenient, wrap the look up in a function pointer.
+
+For example:
+
+```Golang
+
+func NewController(ctx,
+  localAPIExportInformer, cacheAPIExportInformer apisinformers.APIExportClusterInformer
+) (*controller, error) {
+  ...
+  return &controller{
+  listAPIExports: func(clusterName logicalcluster.Name) ([]apisv1apha1.APIExport, error) {
+    exports, err := localAPIExportInformer.Cluster(clusterName).Lister().List(labels.Everything())
+    if err != nil {
+      return cacheAPIExportInformer.Cluster(clusterName).Lister().List(labels.Everything())
+    }
+    return exports, nil
+  ...
+  }
+}
+```
+
+A full list of replicated resources is currently outlined in the [replication controller](https://github.com/kcp-dev/kcp/blob/main/pkg/reconciler/cache/replication/replication_controller.go).
+
 ### Getting your PR Merged
 
 The `kcp` project uses `OWNERS` files to denote the collaborators who can assist you in getting your PR merged.  There