…metry#47555)

#### Description

Adds Kubernetes PersistentVolume (PV) and PersistentVolumeClaim (PVC)
support to the k8s_cluster receiver, including metrics, entity events,
and metadata.

**New metrics** (all disabled by default, `development` stability):

| Metric | Type | Unit | Description |
|--------|------|------|-------------|
| `k8s.persistentvolume.status.phase` | Sum (non-monotonic) |
`{persistentvolume}` | Current phase (1 for active, 0 for others).
Phases: Pending, Available, Bound, Released, Failed |
| `k8s.persistentvolume.storage.capacity` | Sum (non-monotonic) | `By` |
Storage capacity in bytes |
| `k8s.persistentvolumeclaim.status.phase` | Sum (non-monotonic) |
`{persistentvolumeclaim}` | Current phase (1 for active, 0 for others).
Phases: Pending, Bound, Lost |
| `k8s.persistentvolumeclaim.storage.request` | Sum (non-monotonic) |
`By` | Requested storage in bytes |
| `k8s.persistentvolumeclaim.storage.capacity` | Sum (non-monotonic) |
`By` | Provisioned capacity in bytes (only when bound) |

References for enums -
- **PV phase:**
[`PersistentVolumePhase`](https://pkg.go.dev/k8s.io/[email protected]/core/v1#PersistentVolumePhase)
- Pending, Available, Bound, Released, Failed (noticed that the
[concepts
doc](https://kubernetes.io/docs/concepts/storage/persistent-volumes#phase)
omits Pending, but it is defined in the API)
- **PVC phase:**
[`PersistentVolumeClaimPhase`](https://pkg.go.dev/k8s.io/[email protected]/core/v1#PersistentVolumeClaimPhase)
- Pending, Bound, Lost
- **PV reclaim policy:**
[`PersistentVolumeReclaimPolicy`](https://pkg.go.dev/k8s.io/[email protected]/core/v1#PersistentVolumeReclaimPolicy)
- Delete, Recycle, Retain

**New entities** (`development` stability):
- `k8s.persistentvolume` - identity: `uid`, description: name,
storageclass, reclaim_policy
- `k8s.persistentvolumeclaim` - identity: `uid`, description: name,
extra: namespace, storageclass

**RBAC:** Requires `persistentvolumes` and `persistentvolumeclaims`
verbs `get`, `list`, `watch` in the collector's ClusterRole.

Semantic conventions:
open-telemetry/semantic-conventions#3376

Additional implementation details -
- Labels, annotations, and creation timestamp are emitted as entity
event attributes and via metadata, not as metric resource attributes -
following the existing pattern for other resource types. PVC entities
also include `k8s.persistentvolume.name` when bound.
- Informers are only activated when at least one metric is enabled or
metadata/entity exporters are configured.
- `storage.capacity` for PVC is only emitted when bound
(`Status.Capacity` is populated).
- `k8s.storageclass.name` is omitted when no StorageClass is set (e.g.,
manually provisioned static PVs or stuck/pending PVCs in clusters
without a default StorageClass).
- `Transform()` strips the
`kubectl.kubernetes.io/last-applied-configuration` annotation (contains
a full JSON copy of the manifest).

#### Link to tracking issue

Fixes
open-telemetry#47453

#### Testing

- **Unit tests:** Golden file tests for PV (default, optional attrs with
`reclaim_policy`, no-capacity) and PVC (default bound, pending).
`RecordMetrics` and `GetMetadata` coverage for all phases and edge
cases.
- **Watcher tests:** `TestObjMetadata` entries for PV and PVC.
`TestSyncMetadataAndEmitEntityEventsForPV` and
`TestSyncMetadataAndEmitEntityEventsForPVC` verify
entity_state/entity_delete lifecycle.
- **E2E metrics:** PV/PVC metrics validated in `TestE2EClusterScoped`
(cluster-wide: PV + PVC) and `TestE2ENamespaceScoped` (namespace-scoped:
PVC only) against golden files.
- **E2E entities:** `TestE2EPVCEntity` creates a PVC in Kind and
validates entity event log output against a golden file.

#### Documentation

- `documentation.md` updated automatically by mdatagen with new metrics,
resource attributes, and entity definitions.
- `README.md` updated with PV/PVC RBAC requirements.

…metry#47555)

#### Description

Adds Kubernetes PersistentVolume (PV) and PersistentVolumeClaim (PVC)
support to the k8s_cluster receiver, including metrics, entity events,
and metadata.

**New metrics** (all disabled by default, `development` stability):

| Metric | Type | Unit | Description |
|--------|------|------|-------------|
| `k8s.persistentvolume.status.phase` | Sum (non-monotonic) |
`{persistentvolume}` | Current phase (1 for active, 0 for others).
Phases: Pending, Available, Bound, Released, Failed |
| `k8s.persistentvolume.storage.capacity` | Sum (non-monotonic) | `By` |
Storage capacity in bytes |
| `k8s.persistentvolumeclaim.status.phase` | Sum (non-monotonic) |
`{persistentvolumeclaim}` | Current phase (1 for active, 0 for others).
Phases: Pending, Bound, Lost |
| `k8s.persistentvolumeclaim.storage.request` | Sum (non-monotonic) |
`By` | Requested storage in bytes |
| `k8s.persistentvolumeclaim.storage.capacity` | Sum (non-monotonic) |
`By` | Provisioned capacity in bytes (only when bound) |

References for enums -
- **PV phase:**
[`PersistentVolumePhase`](https://pkg.go.dev/k8s.io/[email protected]/core/v1#PersistentVolumePhase)
- Pending, Available, Bound, Released, Failed (noticed that the
[concepts
doc](https://kubernetes.io/docs/concepts/storage/persistent-volumes#phase)
omits Pending, but it is defined in the API)
- **PVC phase:**
[`PersistentVolumeClaimPhase`](https://pkg.go.dev/k8s.io/[email protected]/core/v1#PersistentVolumeClaimPhase)
- Pending, Bound, Lost
- **PV reclaim policy:**
[`PersistentVolumeReclaimPolicy`](https://pkg.go.dev/k8s.io/[email protected]/core/v1#PersistentVolumeReclaimPolicy)
- Delete, Recycle, Retain

**New entities** (`development` stability):
- `k8s.persistentvolume` - identity: `uid`, description: name,
storageclass, reclaim_policy
- `k8s.persistentvolumeclaim` - identity: `uid`, description: name,
extra: namespace, storageclass

**RBAC:** Requires `persistentvolumes` and `persistentvolumeclaims`
verbs `get`, `list`, `watch` in the collector's ClusterRole.

Semantic conventions:
open-telemetry/semantic-conventions#3376

Additional implementation details -
- Labels, annotations, and creation timestamp are emitted as entity
event attributes and via metadata, not as metric resource attributes -
following the existing pattern for other resource types. PVC entities
also include `k8s.persistentvolume.name` when bound.
- Informers are only activated when at least one metric is enabled or
metadata/entity exporters are configured.
- `storage.capacity` for PVC is only emitted when bound
(`Status.Capacity` is populated).
- `k8s.storageclass.name` is omitted when no StorageClass is set (e.g.,
manually provisioned static PVs or stuck/pending PVCs in clusters
without a default StorageClass).
- `Transform()` strips the
`kubectl.kubernetes.io/last-applied-configuration` annotation (contains
a full JSON copy of the manifest).

#### Link to tracking issue

Fixes
open-telemetry#47453

#### Testing

- **Unit tests:** Golden file tests for PV (default, optional attrs with
`reclaim_policy`, no-capacity) and PVC (default bound, pending).
`RecordMetrics` and `GetMetadata` coverage for all phases and edge
cases.
- **Watcher tests:** `TestObjMetadata` entries for PV and PVC.
`TestSyncMetadataAndEmitEntityEventsForPV` and
`TestSyncMetadataAndEmitEntityEventsForPVC` verify
entity_state/entity_delete lifecycle.
- **E2E metrics:** PV/PVC metrics validated in `TestE2EClusterScoped`
(cluster-wide: PV + PVC) and `TestE2ENamespaceScoped` (namespace-scoped:
PVC only) against golden files.
- **E2E entities:** `TestE2EPVCEntity` creates a PVC in Kind and
validates entity event log output against a golden file.

#### Documentation

- `documentation.md` updated automatically by mdatagen with new metrics,
resource attributes, and entity definitions.
- `README.md` updated with PV/PVC RBAC requirements.