Add a table that lists supported field selectors by API type

[torenware]

Current documentation for Field Selectors says:

Supported field selectors vary by Kubernetes resource type. All resource types support the metadata.name and metadata.namespace fields. Using unsupported field selectors produces an error.

The "supported" fields are not discoverable; right now, short of spelunking in the source, it's unclear what selectors are legal. This is particularly a problem for filtering events, where there are a fair number of undocumented selectors (see pkg/apis/events/v1/conversion.go).

Proposed solution: add a table that lists supported selectors by type. Again, the table will not be that long, judging by what I saw in the sources.

[dipesh-rawat]

Page: https://kubernetes.io/docs/concepts/overview/working-with-objects/field-selectors/

/language en

[torenware]

@dipesh-rawat writes:

Page: https://kubernetes.io/docs/concepts/overview/working-with-objects/field-selectors/

/language en

Yes, and how exactly does that page help in what I'm asking here? Without looking at the source, how would you know that for events, the following are supported:

func AddFieldLabelConversionsForEvent(scheme *runtime.Scheme) error {
  mapping := map[string]string{
    "reason":                    "reason",
    "regarding.kind":            "involvedObject.kind",            // map events.k8s.io field to fieldset returned by ToSelectableFields
    "regarding.namespace":       "involvedObject.namespace",       // map events.k8s.io field to fieldset returned by ToSelectableFields
    "regarding.name":            "involvedObject.name",            // map events.k8s.io field to fieldset returned by ToSelectableFields
    "regarding.uid":             "involvedObject.uid",             // map events.k8s.io field to fieldset returned by ToSelectableFields
    "regarding.apiVersion":      "involvedObject.apiVersion",      // map events.k8s.io field to fieldset returned by ToSelectableFields
    "regarding.resourceVersion": "involvedObject.resourceVersion", // map events.k8s.io field to fieldset returned by ToSelectableFields
    "regarding.fieldPath":       "involvedObject.fieldPath",       // map events.k8s.io field to fieldset returned by ToSelectableFields
    "reportingController":       "reportingComponent",             // map events.k8s.io field to fieldset returned by ToSelectableFields
    "type":                      "type",
    "metadata.namespace":        "metadata.namespace",
    "metadata.name":             "metadata.name",
  }
  return scheme.AddFieldLabelConversionFunc(SchemeGroupVersion.WithKind("Event"),
    func(label, value string) (string, string, error) {
      mappedLabel, ok := mapping[label]
      if !ok {
        return "", "", fmt.Errorf("field label not supported: %s", label)
      }
      return mappedLabel, value, nil
    },
  )
}

Unless you are suggesting that "reading the source" is adequate documentation for this, this is the kind of info that needs to be discoverable. Docs are all we have for this; this is why I suggest a table.

[sftim]

/retitle Add a table that lists supported field selectors by API type /kind feature

[torenware]

This is not guaranteed to be complete (I don't know the status of StatefulSets), but's here a list for future reference.

Pods	`metadata.name`, `metadata.namespace`, `spec.nodeName`, `spec.restartPolicy`, `spec.schedulerName`, `spec.serviceAccountName`, `status.phase`, `status.podIP`, `status.podIPs`, `status.nominatedNodeName`
Node	`metadata.name` `spec.unschedulable`
RC	`metadata.name`, `metadata.namespace`, `status.replicas`
Events	`involvedObject.kind`, `involvedObject.namespace`, `involvedObject.name`, `involvedObject.uid`, `involvedObject.apiVersion`, `involvedObject.resourceVersion`, `involvedObject.fieldPath`, `reason`, `reportingComponent`, `source`, `type`, `metadata.namespace`, `metadata.name`
namespace	`status.phase`, `metadata.name`
Secret	`type`, `metadata.namespace`, `metadata.name`
CSR	`metadata.name`, `spec.signerName`
Jobs	`metadata.name`, `metadata.namespace`, `status.successful`

[tengqm]

/triage accepted

[sftim]

Some more:

CronJob

status.successful

ClusterTrustBundle

spec.signerName

[k8s-triage-robot]

This issue has not been updated in over 1 year, and should be re-triaged.

You can:

• Confirm that this issue is still relevant with /triage accepted (org members only)
• Close this issue with /close

For more details on the triage process, see https://www.kubernetes.dev/docs/guide/issue-triage/

/remove-triage accepted