Update Quickstart: ProviderNamingFormat & ImageConfig (#42)

* update quickstart to detail ownerRefs and image path rewriting

* update quickstart to detail resolving of duplicate family providers

Author: veera-adithya-d

docs/quickstart.md

@@ -12,19 +12,23 @@ The first provider installed of a family also installs an extra provider-family
 > [!NOTE]
 > Always install the family provider first to ensure anticipated/right version of image is pulled. Installing sub-provider first creates a missing dependency issue, which the crossplane package-manager always resolves by pulling latest family provider image. It might lead to unexpected behavior. 
  
+> [!IMPORTANT]
+> Adhere to the following naming format for providers as: `(organization)-(provider-name)`, eg: oracle-samples-provider-family-oci. 
+> When pulling the image from a registry, crossplane formats the name as `registry.io/organization/provider-name:tags`, eg: ghcr.io/oracle-samples/provider-family-oci:v0.0.1-alpha.1-amd64.
+> Crossplane behavior and corresponding steps to resolve conflict detailed in section: [Owner references conflict](#owner-references-conflict)
 ```
 cat <<EOF | kubectl apply -f -
 apiVersion: pkg.crossplane.io/v1
 kind: Provider
 metadata:
-  name: provider-oci-family
+  name: oracle-samples-provider-family-oci
 spec:
   package: ghcr.io/oracle-samples/provider-family-oci:v0.0.1-alpha.1-amd64
 ---
 apiVersion: pkg.crossplane.io/v1
 kind: Provider
 metadata:
-  name: provider-oci-objectstorage
+  name: oracle-samples-provider-oci-objectstorage
 spec:
   package: ghcr.io/oracle-samples/provider-oci-objectstorage:v0.0.1-alpha.1-amd64
 EOF
@@ -44,6 +48,37 @@ provider-oci-objectstorage   True        True      ghcr.io/oracle-samples/provid
 
 It may take up to 5 minutes to report `HEALTHY`.
 
+### Optional: Pulling images from private registry
+If you are required to pull images from private registries instead of `ghcr.io`. Mirror the images into, for example `registry1.io`, then utilize the following `ImageConfig` sample to rewrite image paths and configure a pull secret. 
+
+[The official crossplane documents](https://docs.crossplane.io/latest/packages/image-configs/#rewriting-image-paths) covers the rewrite image paths in more details.
+```
+---
+apiVersion: pkg.crossplane.io/v1beta1
+kind: ImageConfig
+metadata:
+  name: private-registry-rewrite
+spec:
+  matchImages:
+    - prefix: ghcr.io
+  rewriteImage:
+    prefix: registry1.io
+
+# Configure pull secrets for registry1.io
+---
+apiVersion: pkg.crossplane.io/v1beta1
+kind: ImageConfig
+metadata:
+  name: private-registry-auth
+spec:
+  matchImages:
+    - type: Prefix
+      prefix: registry1.io
+  registry:
+    authentication:
+      pullSecretRef:
+        name: private-registry-credentials
+```
 ## Configure family provider for OCI
 
 The official provider-family requires credentials to create and manage OCI resources.
@@ -182,4 +217,42 @@ $ kubectl delete providers/provider-oci-family
 
 > [!Warning]
 > Never delete a family provider before deleting its sub-providers. Deleting a family provider while sub-providers are still installed can lead to unexpected behavior and potential errors.
-  
+
+## Owner references conflict
+Crossplane’s package manager establishes an ownership chain between a family Provider (parent) and each sub‑provider (child) using metadata.ownerReferences on the child’s ProviderRevision. The owner reference encodes the parent Provider’s “package identity” as a name that the package manager expects to persist:
+
+```
+$ kubectl describe providerrevisions/provider-family-oci...
+
+  <TRUNCATED OUTPUT>
+  Owner References:
+    API Version:           pkg.crossplane.io/v1
+    Block Owner Deletion:  true
+    Controller:            true
+    Kind:                  Provider
+    Name:                  oracle-samples-provider-family-oci
+    UID:                   ...
+```
+
+What can go wrong
+- If the family Provider is deleted or reinstalled with a different metadata.name while any sub‑providers or their ProviderRevisions still exist, Crossplane will attempt to satisfy the outstanding owner reference by automatically pulling a Provider with the name encoded in the ownerReferences (from the same registry as the sub‑provider’s image).
+- This results in two family Providers trying to coexist (the one you applied and the one auto‑installed to satisfy the ownerRef), which leads to unhealthy/competing ProviderRevisions and confusing state during upgrades.
+
+Typical symptoms
+- An unexpected Provider with name - appears after you delete or rename your family Provider.
+- providerrevisions stuck in Unhealthy/Inactive with messages about conflicting ownership or multiple controlling owners.
+- Repeated reconcile loops pulling a family image you did not specify explicitly.
+
+### Resolving duplicate family providers 
+
+Proceed with clean up of managed resource(s) and providers in order. Refer to the sections: [Delete the managed resource](#delete-the-managed-resource) and [Delete the providers](#delete-the-providers).
+
+After deletion, check for the existence of duplicate family provider by 
+```
+$ kubectl get providers
+```
+
+If exists, delete the duplicated family provider by
+```
+$ kubectl delete providers/<duplicate-provider-name>
+```