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

[k8s-triage-robot]

The Kubernetes project currently lacks enough contributors to adequately respond to all issues.

This bot triages un-triaged issues according to the following rules:

• After 90d of inactivity, lifecycle/stale is applied
• After 30d of inactivity since lifecycle/stale was applied, lifecycle/rotten is applied
• After 30d of inactivity since lifecycle/rotten was applied, the issue is closed

You can:

• Mark this issue as fresh with /remove-lifecycle stale
• Close this issue with /close
• Offer to help out with Issue Triage

Please send feedback to sig-contributor-experience at kubernetes/community.

/lifecycle stale

[k8s-triage-robot]

The Kubernetes project currently lacks enough active contributors to adequately respond to all issues.

This bot triages un-triaged issues according to the following rules:

• After 90d of inactivity, lifecycle/stale is applied
• After 30d of inactivity since lifecycle/stale was applied, lifecycle/rotten is applied
• After 30d of inactivity since lifecycle/rotten was applied, the issue is closed

You can:

• Mark this issue as fresh with /remove-lifecycle rotten
• Close this issue with /close
• Offer to help out with Issue Triage

Please send feedback to sig-contributor-experience at kubernetes/community.

/lifecycle rotten