✨ metrics: add generator for kube-state-metrics customresource configuration

[chrischdi]

This adds a generator to generate a customresource configuration file for kube-state-metrics from markers.

With that configuration it is possible to get metrics for CRs like kube-state-metrics exposes for core resources.
(xref)

Example usage:

controller-gen metrics output:metrics:stdout \
     paths=./api/...\
     > crd-config.yaml

Introduced markers:

$ controller-gen metrics -ww

Metric type Gauge


+Metrics:gauge type
	defines a Gauge metric and uses the implicit path to the field joined by the provided JSONPath as path for the metric configuration.
	[JSONPath=<string>]      specifies the relative path from this marker.                                          
	[help=<string>]          specifies the help text for the metric.                                                
	[labelFromKey=<string>]  specifies a label which will be added to the metric having the object's key as value.  
	[labelsFromPath=<>]      specifies additional labels where the value is taken from the given JSONPath.          
	name=<string>            specifies the Name of the metric.                                                      
	[nilIsZero=<bool>]       specifies to treat a not-existing field as zero value.                                 
	[valueFrom=<string>]     specifies the JSONPath to a numeric field that will be the metric value.               

+Metrics:gauge field
	defines a Gauge metric and uses the implicit path to the field joined by the provided JSONPath as path for the metric configuration.
	[JSONPath=<string>]      specifies the relative path from this marker.                                          
	[help=<string>]          specifies the help text for the metric.                                                
	[labelFromKey=<string>]  specifies a label which will be added to the metric having the object's key as value.  
	[labelsFromPath=<>]      specifies additional labels where the value is taken from the given JSONPath.          
	name=<string>            specifies the Name of the metric.                                                      
	[nilIsZero=<bool>]       specifies to treat a not-existing field as zero value.                                 
	[valueFrom=<string>]     specifies the JSONPath to a numeric field that will be the metric value.               

Metric type Info


+Metrics:info type
	defines a Info metric and uses the implicit path to the field as path for the metric configuration.
	[JSONPath=<string>]      specifies the relative path from this marker.                                          
	[help=<string>]          specifies the help text for the metric.                                                
	[labelFromKey=<string>]  specifies a label which will be added to the metric having the object's key as value.  
	[labelsFromPath=<>]      specifies additional labels where the value is taken from the given JSONPath.          
	name=<string>            specifies the Name of the metric.                                                      

+Metrics:info field
	defines a Info metric and uses the implicit path to the field as path for the metric configuration.
	[JSONPath=<string>]      specifies the relative path from this marker.                                          
	[help=<string>]          specifies the help text for the metric.                                                
	[labelFromKey=<string>]  specifies a label which will be added to the metric having the object's key as value.  
	[labelsFromPath=<>]      specifies additional labels where the value is taken from the given JSONPath.          
	name=<string>            specifies the Name of the metric.                                                      

Metric type StateSet


+Metrics:stateset type
	defines a StateSet metric and uses the implicit path to the field as path for the metric configuration.
	[JSONPath=<string>]   specifies the path to the field which gets used as value to compare against the list for equality.  
	[help=<string>]       specifies the help text for the metric.                                                             
	[labelName=<string>]  specifies the key of the label which is used for each entry in List to expose the value.            
	[labelsFromPath=<>]   specifies additional labels where the value is taken from the given JSONPath.                       
	list=<[]string>       specifies a list of values to compare the given JSONPath against.                                   
	name=<string>         specifies the Name of the metric.                                                                   

+Metrics:stateset field
	defines a StateSet metric and uses the implicit path to the field as path for the metric configuration.
	[JSONPath=<string>]   specifies the path to the field which gets used as value to compare against the list for equality.  
	[help=<string>]       specifies the help text for the metric.                                                             
	[labelName=<string>]  specifies the key of the label which is used for each entry in List to expose the value.            
	[labelsFromPath=<>]   specifies additional labels where the value is taken from the given JSONPath.                       
	list=<[]string>       specifies a list of values to compare the given JSONPath against.                                   
	name=<string>         specifies the Name of the metric.                                                                   

Metrics


+Metrics:gvk type
	enables the creation of a custom resource configuration entry and uses the given prefix for the metrics if configured.
	[namePrefix=<string>]  specifies the prefix for all metrics of this resource.  

+Metrics:labelFromPath type
	specifies additional labels for all metrics of this field or type.
	JSONPath=<string>  specifies the relative path to the value for the label.  
	name=<string>      specifies the name of the label.                         

+Metrics:labelFromPath field
	specifies additional labels for all metrics of this field or type.
	JSONPath=<string>  specifies the relative path to the value for the label.  
	name=<string>      specifies the name of the label.                         

Example usage: kubernetes-sigs/cluster-api#9347

[chrischdi]

If wanted, I can volunteer to maintain this part of controller-gen (and/or also help on other parts of controller-tools) :-)

[sbueringer]

We'll get back to this eventually, just low bandwith at the moment

[k8s-triage-robot]

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

This bot triages PRs 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 PR is closed

You can:

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

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

/lifecycle stale

[sbueringer]

/remove-lifecycle stale

[k8s-ci-robot]

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by: chrischdi
Once this PR has been reviewed and has the lgtm label, please assign vincepri for approval. For more information see the Code Review Process.

The full list of commands accepted by this bot can be found here.

Needs approval from an approver in each of these files:

• OWNERS

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

[k8s-triage-robot]

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

This bot triages PRs 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 PR is closed

You can:

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

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

/lifecycle rotten

[k8s-triage-robot]

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

This bot triages PRs 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 PR is closed

You can:

• Reopen this PR with /reopen
• Mark this PR as fresh with /remove-lifecycle rotten
• Offer to help out with Issue Triage

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

/close

[k8s-ci-robot]

@k8s-triage-robot: Closed this PR.

In response to this:

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

This bot triages PRs 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 PR is closed

You can:

• Reopen this PR with /reopen
• Mark this PR as fresh with /remove-lifecycle rotten
• Offer to help out with Issue Triage

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

/close

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository.

[chrischdi]

/reopen

[k8s-ci-robot]

@chrischdi: Reopened this PR.

In response to this:

/reopen

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository.

[chrischdi]

/remove-lifecycle rotten

[sbueringer]

@JoelSpeed If you're fine with this in general (already discussed this with Vince+Alvaro in the past and they are okay with it as long as we mark it experimental in some way for now) + we all have time to push this towards completion. Happy to invest time in reviews

[JoelSpeed]

I'm not going to have time to do a deep dive on this until next week, but at the high level this seems like a reasonable addition.

Would like to have some discussion (maybe at the DV subproject meeting) about precedence for similar markers, and the patterns for defining the markers so that we can be somewhat consistent

[sbueringer]

I'm not going to have time to do a deep dive on this until next week, but at the high level this seems like a reasonable addition.

Sounds good, no rush!

Would like to have some discussion (maybe at the DV subproject meeting) about precedence for similar markers, and the patterns for defining the markers so that we can be somewhat consistent

Sounds reasonable. @chrischdi would be good if you could bring this up and drive forward.
Depending on bandwidth of course (don't want to just assume that you currently have the right bandwidth/priority mix for this :)). The meeting Joel is referring to is this one: https://docs.google.com/document/d/1cYXfDHZpalzoew-PKfgh1XHQB_6JjiEsidsM4zYGAzc/edit?pli=1&tab=t.0#heading=h.xf24wnv1ochq (bi-weekly Tuesday, next ocurrence next week)

[sbueringer]

🧵 Marker prefix

Follow-up to the discussion in the meeting.

I think we should go with a k8s:controller-gen prefix.

I think it clearly identifies that these markers belong to conroller-gen. The name of this binary will remain the same, independent of in which repository it is hosted.

I thought a bit about if it's worth renaming the repo to make controller-gen easier to find.
I would not do it:

• we host some other tools in this repo
• we might want to host additional tools in this repo going forward
• it's a breaking change for setup-envtest as it uses release artifacts from this repo
• it's disruptive in general and requires a bunch of effort

I think overall it's not worth it just to make it slightly easier for users to find controller-gen to open issues. It's in general not hard to find controller-gen. A similar situation exists for e.g. kubeadm.

I see how kuberbuilder was misleading as a marker prefix. I think the same problem does not exist in the same way for controller-gen

@chrischdi @JoelSpeed WDYT?

[chrischdi]

I agree. I think mostly controller-gen get's either installed via go install or downloaded from the release page. So should be good enough to find the repo with that prefix.