Add persist_resource_version documentation to k8sobjects receiver README

- Added persist_resource_version to example configurations
- Documented persist_resource_version configuration property
- Added dedicated "ResourceVersion Persistence" section with:
  - Key features and benefits
  - Complete configuration example with storage extension
  - Storage key format explanation
  - Deployment considerations with PVC example
- Updated ConfigMap and Deployment examples to include persistence setup

Co-Authored-By: Dhruv Shah <dhruv.shah@sumologic.com>

Author: dhruv-shah-sumo

receiver/k8sobjectsreceiver/README.md

@@ -26,6 +26,7 @@ The following is example configuration
 ```yaml
   k8sobjects:
     auth_type: serviceAccount
+    storage: file_storage
     k8s_leader_elector: k8s_leader_elector
     objects:
       - name: pods
@@ -39,6 +40,7 @@ The following is example configuration
         mode: watch
         group: events.k8s.io
         namespaces: [default]
+        persist_resource_version: true
 ```
 
 Brief description of configuration properties:
@@ -67,8 +69,8 @@ use this config to specify the group to select. By default, it will select the f
 For example, `events` resource is available in both `v1` and `events.k8s.io/v1` APIGroup. In
 this case, it will select `v1` by default.
 - `k8s_leader_elector` (default: none): if specified, will enable Leader Election by using `k8sleaderelector` extension
-- `storage` (default: none): if specified, will enable the receiver to store the last resource version seen in a file. The resource version will be 
-persisted when the watch mode is configured for the given object.
+- `storage` (default: none): specifies the storage extension to use for persisting resourceVersions. Required when `persist_resource_version` is enabled.
+- `persist_resource_version` (default: `false`): When set to `true` (watch-mode only), the receiver persists the resourceVersion after processing each event. On restart, the receiver resumes watching from the persisted resourceVersion, preventing duplicate events. Requires a `storage` extension to be configured.
 
 
 The full list of settings exposed for this receiver are documented in [config.go](./config.go)
@@ -97,6 +99,90 @@ The `k8sobjectsreceiver` supports collecting a wide range of standard Kubernetes
 
 This receiver supports both `pull` and `watch` modes, allowing for flexible and real-time monitoring of these objects. Please note that custom resources are supported only if their CRDs are available in the cluster.
 
+### ResourceVersion Persistence
+
+When using `watch` mode, the receiver can persist the resourceVersion after processing each event. This ensures that on collector restart, the receiver resumes from where it left off, preventing duplicate events from being collected.
+
+#### Key Features
+- **Prevents Duplicate Events**: On restart, watches resume from the last persisted resourceVersion
+- **Per-Namespace Tracking**: Separate resourceVersions are maintained for each namespace
+- **410 Gone Error Recovery**: Automatically handles expired resourceVersions by fetching a fresh one
+- **Opt-in**: Disabled by default; enable via `persist_resource_version: true`
+
+#### Configuration Example
+
+To enable resourceVersion persistence, you need:
+1. A storage extension (e.g., `file_storage`)
+2. The `storage` field pointing to the extension
+3. `persist_resource_version: true` on objects you want to persist
+
+```yaml
+extensions:
+  file_storage:
+    directory: /var/lib/otelcol/storage
+    timeout: 1s
+
+receivers:
+  k8sobjects:
+    auth_type: serviceAccount
+    storage: file_storage  # Reference to storage extension
+    objects:
+      - name: pods
+        mode: watch
+        namespaces: [default, production]
+        persist_resource_version: true  # Enable persistence
+      - name: events
+        mode: watch
+        group: events.k8s.io
+        persist_resource_version: true
+
+exporters:
+  debug:
+    verbosity: detailed
+
+service:
+  extensions: [file_storage]  # Must include the extension
+  pipelines:
+    logs:
+      receivers: [k8sobjects]
+      exporters: [debug]
+```
+
+#### Storage Key Format
+
+The receiver stores resourceVersions with the following key format:
+- **Namespace-specific watches**: `latestResourceVersion/{objectType}.{namespace}`
+  - Example: `latestResourceVersion/pods.default`, `latestResourceVersion/events.production`
+- **Cluster-wide watches**: `latestResourceVersion/{objectType}`
+  - Example: `latestResourceVersion/nodes`, `latestResourceVersion/namespaces`
+
+#### Deployment Considerations
+
+When using persistence:
+- Ensure the storage directory is mounted to a persistent volume so data survives pod restarts
+- The storage extension must be listed in the `service.extensions` array
+- Only applicable for `watch` mode; `pull` mode does not use persistence
+
+```yaml
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: otelcontribcol
+spec:
+  template:
+    spec:
+      containers:
+      - name: otelcontribcol
+        image: otel/opentelemetry-collector-contrib:latest
+        volumeMounts:
+        - name: storage
+          mountPath: /var/lib/otelcol/storage
+      volumes:
+      - name: storage
+        persistentVolumeClaim:
+          claimName: otel-storage-pvc
+```
+
 ### Configuration
 
 Create a ConfigMap with the config for `otelcontribcol`. Replace `OTLP_ENDPOINT`
@@ -112,20 +198,29 @@ metadata:
     app: otelcontribcol
 data:
   config.yaml: |
+    extensions:
+      file_storage:
+        directory: /var/lib/otelcol/storage
+
     receivers:
       k8sobjects:
+        auth_type: serviceAccount
+        storage: file_storage
         objects:
           - name: pods
             mode: pull
           - name: events
             mode: watch
+            persist_resource_version: true
+
     exporters:
       otlp_grpc:
         endpoint: <OTLP_ENDPOINT>
         tls:
           insecure: true
 
     service:
+      extensions: [file_storage]
       pipelines:
         logs:
           receivers: [k8sobjects]
@@ -212,7 +307,22 @@ Create a [Deployment](https://kubernetes.io/docs/concepts/workloads/controllers/
 Note: This receiver must be deployed as one replica, otherwise it'll be producing duplicated data.
 
 ```bash
-<<EOF | kubectl apply -f -
+# First, create a PersistentVolumeClaim for storage (if using persistence)
+cat <<EOF | kubectl apply -f -
+apiVersion: v1
+kind: PersistentVolumeClaim
+metadata:
+  name: otel-storage-pvc
+spec:
+  accessModes:
+  - ReadWriteOnce
+  resources:
+    requests:
+      storage: 1Gi
+EOF
+
+# Then create the Deployment
+cat <<EOF | kubectl apply -f -
 apiVersion: apps/v1
 kind: Deployment
 metadata:
@@ -239,11 +349,16 @@ spec:
         volumeMounts:
         - name: config
           mountPath: /etc/config
+        - name: storage
+          mountPath: /var/lib/otelcol/storage
         imagePullPolicy: IfNotPresent
       volumes:
         - name: config
           configMap:
             name: otelcontribcol
+        - name: storage
+          persistentVolumeClaim:
+            claimName: otel-storage-pvc
 EOF
 ```