Merge pull request #118299 from rexagod/kep-2305

KEP-2305: introduce allow-metric-labels-manifest

staging/src/k8s.io/component-base/go.mod

@@ -24,6 +24,7 @@ require (
 	go.opentelemetry.io/otel/trace v1.10.0
 	go.uber.org/zap v1.19.0
 	golang.org/x/sys v0.10.0
+	gopkg.in/yaml.v2 v2.4.0
 	k8s.io/apimachinery v0.0.0
 	k8s.io/client-go v0.0.0
 	k8s.io/klog/v2 v2.100.1
@@ -77,7 +78,6 @@ require (
 	google.golang.org/grpc v1.54.0 // indirect
 	google.golang.org/protobuf v1.31.0 // indirect
 	gopkg.in/inf.v0 v0.9.1 // indirect
-	gopkg.in/yaml.v2 v2.4.0 // indirect
 	gopkg.in/yaml.v3 v3.0.1 // indirect
 	k8s.io/api v0.0.0 // indirect
 	k8s.io/kube-openapi v0.0.0-20230905202853-d090da108d2f // indirect

staging/src/k8s.io/component-base/metrics/metric.go

@@ -166,7 +166,7 @@ func (r *lazyMetric) Create(version *semver.Version) bool {
 	if deprecatedV != nil {
 		dv = deprecatedV.String()
 	}
-	registeredMetrics.WithLabelValues(string(sl), dv).Inc()
+	registeredMetricsTotal.WithLabelValues(string(sl), dv).Inc()
 	return r.IsCreated()
 }
 

staging/src/k8s.io/component-base/metrics/options.go

@@ -31,6 +31,7 @@ type Options struct {
 	ShowHiddenMetricsForVersion string
 	DisabledMetrics             []string
 	AllowListMapping            map[string]string
+	AllowListMappingManifest    string
 }
 
 // NewOptions returns default metrics options
@@ -81,6 +82,10 @@ func (o *Options) AddFlags(fs *pflag.FlagSet) {
 		"The map from metric-label to value allow-list of this label. The key's format is <MetricName>,<LabelName>. "+
 			"The value's format is <allowed_value>,<allowed_value>..."+
 			"e.g. metric1,label1='v1,v2,v3', metric1,label2='v1,v2,v3' metric2,label1='v1,v2,v3'.")
+	fs.StringVar(&o.AllowListMappingManifest, "allow-metric-labels-manifest", o.AllowListMappingManifest,
+		"The path to the manifest file that contains the allow-list mapping. "+
+			"The format of the file is the same as the flag --allow-metric-labels. "+
+			"Note that the flag --allow-metric-labels will override the manifest file.")
 }
 
 // Apply applies parameters into global configuration of metrics.
@@ -97,6 +102,8 @@ func (o *Options) Apply() {
 	}
 	if o.AllowListMapping != nil {
 		SetLabelAllowListFromCLI(o.AllowListMapping)
+	} else if len(o.AllowListMappingManifest) > 0 {
+		SetLabelAllowListFromManifest(o.AllowListMappingManifest)
 	}
 }
 
@@ -122,7 +129,7 @@ func validateAllowMetricLabel(allowListMapping map[string]string) error {
 	for k := range allowListMapping {
 		reg := regexp.MustCompile(metricNameRegex + `,` + labelRegex)
 		if reg.FindString(k) != k {
-			return fmt.Errorf("--allow-metric-labels must has a list of kv pair with format `metricName:labelName=labelValue, labelValue,...`")
+			return fmt.Errorf("--allow-metric-labels must have a list of kv pair with format `metricName:labelName=labelValue, labelValue,...`")
 		}
 	}
 	return nil

staging/src/k8s.io/component-base/metrics/opts.go

@@ -18,13 +18,18 @@ package metrics
 
 import (
 	"fmt"
+	"os"
+	"path/filepath"
 	"strings"
 	"sync"
 	"time"
 
 	"github.com/prometheus/client_golang/prometheus"
+	"gopkg.in/yaml.v2"
+
 	"k8s.io/apimachinery/pkg/util/sets"
 	promext "k8s.io/component-base/metrics/prometheusextension"
+	"k8s.io/klog/v2"
 )
 
 var (
@@ -319,6 +324,7 @@ func (allowList *MetricLabelAllowList) ConstrainToAllowedList(labelNameList, lab
 		if allowValues, ok := allowList.labelToAllowList[name]; ok {
 			if !allowValues.Has(value) {
 				labelValueList[index] = "unexpected"
+				cardinalityEnforcementUnexpectedCategorizationsTotal.Inc()
 			}
 		}
 	}
@@ -329,6 +335,7 @@ func (allowList *MetricLabelAllowList) ConstrainLabelMap(labels map[string]strin
 		if allowValues, ok := allowList.labelToAllowList[name]; ok {
 			if !allowValues.Has(value) {
 				labels[name] = "unexpected"
+				cardinalityEnforcementUnexpectedCategorizationsTotal.Inc()
 			}
 		}
 	}
@@ -354,3 +361,20 @@ func SetLabelAllowListFromCLI(allowListMapping map[string]string) {
 		}
 	}
 }
+
+func SetLabelAllowListFromManifest(manifest string) {
+	allowListLock.Lock()
+	defer allowListLock.Unlock()
+	allowListMapping := make(map[string]string)
+	data, err := os.ReadFile(filepath.Clean(manifest))
+	if err != nil {
+		klog.Errorf("Failed to read allow list manifest: %v", err)
+		return
+	}
+	err = yaml.Unmarshal(data, &allowListMapping)
+	if err != nil {
+		klog.Errorf("Failed to parse allow list manifest: %v", err)
+		return
+	}
+	SetLabelAllowListFromCLI(allowListMapping)
+}

staging/src/k8s.io/component-base/metrics/registry.go

@@ -37,7 +37,7 @@ var (
 	registriesLock      sync.RWMutex
 	disabledMetrics     = map[string]struct{}{}
 
-	registeredMetrics = NewCounterVec(
+	registeredMetricsTotal = NewCounterVec(
 		&CounterOpts{
 			Name:           "registered_metrics_total",
 			Help:           "The count of registered metrics broken by stability level and deprecation version.",
@@ -61,6 +61,14 @@ var (
 			StabilityLevel: BETA,
 		},
 	)
+
+	cardinalityEnforcementUnexpectedCategorizationsTotal = NewCounter(
+		&CounterOpts{
+			Name:           "cardinality_enforcement_unexpected_categorizations_total",
+			Help:           "The count of unexpected categorizations during cardinality enforcement.",
+			StabilityLevel: ALPHA,
+		},
+	)
 )
 
 // shouldHide be used to check if a specific metric with deprecated version should be hidden
@@ -379,7 +387,8 @@ func NewKubeRegistry() KubeRegistry {
 }
 
 func (r *kubeRegistry) RegisterMetaMetrics() {
-	r.MustRegister(registeredMetrics)
+	r.MustRegister(registeredMetricsTotal)
 	r.MustRegister(disabledMetricsTotal)
 	r.MustRegister(hiddenMetricsTotal)
+	r.MustRegister(cardinalityEnforcementUnexpectedCategorizationsTotal)
 }