[chore] document metrics for allocatable_types_to_report setting (#42539)

<!--Ex. Fixing a bug - Describe the bug and how this fixes the issue.
Ex. Adding a feature - Explain what this achieves.-->
#### Description
Document the metrics produced by the `allocatable_types_to_report`
setting in the k8scluster receiver.

- Add an explicit table mapping allocatable types to metric names in
README.
- Clarify that `storage` is not part of Kubernetes Node Allocatable and
remove it from the listed types.
-
https://kubernetes.io/docs/tasks/administer-cluster/reserve-compute-resources/#node-allocatable
- Add a reference to Kubernetes Node Allocatable docs for clarity.

<!-- Issue number (e.g. #1234) or full URL to issue, if applicable. -->
#### Link to tracking issue
Fixes #42311 

<!--Describe what testing was performed and which tests were added.-->
#### Testing

Deployed `opentelemetry-collector-contrib` v0.133.0 via the official
Helm chart(`mode=deployment`, `presets.clusterMetrics=true`) and enabled
allocatable metrics in the `k8s_cluster` receiver as follows:

```yaml
config:
  receivers:
    k8s_cluster:
      auth_type: serviceAccount
      collection_interval: 30s
      allocatable_types_to_report:
        - cpu
        - memory
        - ephemeral-storage
        - storage
        - pods
        
  exporters:
    prometheus:
      endpoint: "0.0.0.0:8889"
```

With this configuration, the following metrics were observed on
/metrics:
 
```
# HELP k8s_node_allocatable_cpu Amount of cpu allocatable on the node
# TYPE k8s_node_allocatable_cpu gauge
k8s_node_allocatable_cpu{otel_scope_name="github.com/open-telemetry/opentelemetry-collector-contrib/receiver/k8sclusterreceiver",otel_scope_schema_url="",otel_scope_version="0.133.0"} 1.93
# HELP k8s_node_allocatable_ephemeral_storage_bytes Amount of ephemeral-storage allocatable on the node
# TYPE k8s_node_allocatable_ephemeral_storage_bytes gauge
k8s_node_allocatable_ephemeral_storage_bytes{otel_scope_name="github.com/open-telemetry/opentelemetry-collector-contrib/receiver/k8sclusterreceiver",otel_scope_schema_url="",otel_scope_version="0.133.0"} 7.6224326324e+10
# HELP k8s_node_allocatable_memory_bytes Amount of memory allocatable on the node
# TYPE k8s_node_allocatable_memory_bytes gauge
k8s_node_allocatable_memory_bytes{otel_scope_name="github.com/open-telemetry/opentelemetry-collector-contrib/receiver/k8sclusterreceiver",otel_scope_schema_url="",otel_scope_version="0.133.0"} 5.54446848e+08
# HELP k8s_node_allocatable_pods Amount of pods allocatable on the node
# TYPE k8s_node_allocatable_pods gauge
k8s_node_allocatable_pods{otel_scope_name="github.com/open-telemetry/opentelemetry-collector-contrib/receiver/k8sclusterreceiver",otel_scope_schema_url="",otel_scope_version="0.133.0"} 4
```

<!--Describe the documentation added.-->
#### Documentation

<!--Please delete paragraphs that you did not use before submitting.-->

Signed-off-by: jaehanbyun <[email protected]>
Co-authored-by: Christos Markou <[email protected]>

Author: jaehanbyun

receiver/k8sclusterreceiver/README.md

@@ -54,12 +54,21 @@ by the cluster. Currently supported versions are `kubernetes` and `openshift`. S
 the value to `openshift` enables OpenShift specific metrics in addition to standard
 kubernetes ones.
 - `allocatable_types_to_report` (default = `[]`): An array of allocatable resource types this receiver should report.
-The following allocatable resource types are available.
+The following allocatable resource types are available (see Node Allocatable in [Kubernetes docs](https://kubernetes.io/docs/tasks/administer-cluster/reserve-compute-resources/#node-allocatable)):
   - cpu
   - memory
   - ephemeral-storage
-  - storage
   - pods
+
+When enabled, this setting produces the following node-level metrics (one per selected type):
+
+| allocatable type | metric name                      | unit     | type  | value type |
+| ---------------- | -------------------------------- | -------- | ----- | ---------- |
+| cpu              | k8s.node.allocatable_cpu         | {cpu}    | Gauge | Double     |
+| memory           | k8s.node.allocatable_memory      | By       | Gauge | Double     |
+| ephemeral-storage| k8s.node.allocatable_ephemeral_storage | By | Gauge | Double     |
+| pods             | k8s.node.allocatable_pods        | {pod}    | Gauge | Int        |
+
 - `metrics`: Allows to enable/disable metrics.
 - `resource_attributes`: Allows to enable/disable resource attributes.
 - `namespace` (deprecated, use `namespaces` instead): Allows to observe resources for a particular namespace only. If this option is set to a non-empty string, `Nodes`, `Namespaces` and `ClusterResourceQuotas` will not be observed.

receiver/k8sclusterreceiver/config.go

@@ -24,7 +24,7 @@ type Config struct {
 	// here: https://kubernetes.io/docs/concepts/architecture/nodes/#condition.
 	NodeConditionTypesToReport []string `mapstructure:"node_conditions_to_report"`
 	// Allocate resource types to report. See all resource types, see
-	// here: https://kubernetes.io/docs/concepts/architecture/nodes/#capacity
+	// here: https://kubernetes.io/docs/tasks/administer-cluster/reserve-compute-resources/#node-allocatable
 	AllocatableTypesToReport []string `mapstructure:"allocatable_types_to_report"`
 	// List of exporters to which metadata from this receiver should be forwarded to.
 	MetadataExporters []string `mapstructure:"metadata_exporters"`