README
¶
pkg/k8s/indexer
Resource indexing and filtering.
Overview
Indexes Kubernetes resources by configurable keys for efficient lookup.
License
See main repository for license information.
Documentation
¶
Overview ¶
Package indexer provides functionality for extracting index keys from Kubernetes resources and filtering fields based on JSONPath expressions.
This package is used by the store implementations to: - Extract index keys for O(1) lookups - Remove unnecessary fields to reduce memory usage
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func ConvertResource ¶
ConvertResource converts an unstructured resource to a map with floats converted to ints.
This function is used during resource storage to ensure all resources are stored in a template-friendly format. The conversion happens once when resources are added/updated in stores, rather than on every access during template rendering.
The returned map can be used directly in templates for field access like:
resource["metadata"]["name"] resource["spec"]["rules"]
Returns nil if the resource type is not supported.
func ValidateJSONPath ¶
ValidateJSONPath validates a JSONPath expression syntax without executing it.
This is a generic validation function that can be used anywhere JSONPath validation is needed. It only checks syntax correctness and does not require a resource to evaluate against.
The expression should follow JSONPath syntax without the surrounding braces. For example: "metadata.namespace" or "metadata.labels['app']"
Parameters:
- expr: The JSONPath expression to validate
Returns:
- An error if the expression syntax is invalid
- nil if the expression is valid
Example:
err := indexer.ValidateJSONPath("metadata.namespace")
if err != nil {
slog.Error("Invalid JSONPath", "error", err)
}
Types ¶
type Config ¶
type Config struct {
// IndexBy specifies JSONPath expressions for extracting index keys.
// At least one expression is required.
IndexBy []string
// IgnoreFields specifies JSONPath patterns for fields to remove.
// These fields are removed from resources before storage.
IgnoreFields []string
}
Config configures the indexer behavior.
type FieldFilter ¶
type FieldFilter struct {
// contains filtered or unexported fields
}
FieldFilter removes fields from Kubernetes resources based on JSONPath expressions.
This is used to reduce memory usage by removing unnecessary fields before storing resources in the index (e.g., metadata.managedFields).
func NewFieldFilter ¶
func NewFieldFilter(patterns []string) *FieldFilter
For example: "metadata.managedFields", "metadata.annotations".
func (*FieldFilter) Filter ¶
func (f *FieldFilter) Filter(resource any) error
Filter removes matching fields from the resource.
The resource is modified in-place for efficiency. Returns an error if filtering fails.
Example:
filter := NewFieldFilter([]string{"metadata.managedFields"})
err := filter.Filter(resource)
type FieldSelectorMatcher ¶
type FieldSelectorMatcher struct {
// contains filtered or unexported fields
}
FieldSelectorMatcher filters resources by evaluating a field selector expression. It parses expressions in the format "field.path=value" and uses client-side JSONPath evaluation to determine if a resource matches.
func NewFieldSelectorMatcher ¶
func NewFieldSelectorMatcher(expression string) (*FieldSelectorMatcher, error)
NewFieldSelectorMatcher creates a new matcher for the given field selector expression.
The expression must be in the format "field.path=value" where:
- field.path is a JSONPath expression (e.g., "spec.ingressClassName")
- value is the expected string value (e.g., "haproxy-internal")
Example: "spec.ingressClassName=haproxy-internal"
Returns an error if the expression format is invalid or the JSONPath is malformed.
func (*FieldSelectorMatcher) ExpectedValue ¶
func (m *FieldSelectorMatcher) ExpectedValue() string
ExpectedValue returns the expected value portion of the expression.
func (*FieldSelectorMatcher) Expression ¶
func (m *FieldSelectorMatcher) Expression() string
Expression returns the original field selector expression.
func (*FieldSelectorMatcher) FieldPath ¶
func (m *FieldSelectorMatcher) FieldPath() string
FieldPath returns the field path portion of the expression.
func (*FieldSelectorMatcher) Matches ¶
func (m *FieldSelectorMatcher) Matches(resource any) (bool, error)
Matches returns true if the resource matches the field selector expression.
Returns:
- (true, nil) if the field exists and its value matches the expected value
- (false, nil) if the field doesn't exist or the value doesn't match
- (false, error) only for unexpected evaluation errors
A missing field is treated as a non-match (not an error), allowing resources without the field to be filtered out gracefully.
type FilterError ¶
FilterError represents an error during field filtering.
func (*FilterError) Error ¶
func (e *FilterError) Error() string
func (*FilterError) Unwrap ¶
func (e *FilterError) Unwrap() error
type IndexError ¶
IndexError represents an error during index key extraction.
func (*IndexError) Error ¶
func (e *IndexError) Error() string
func (*IndexError) Unwrap ¶
func (e *IndexError) Unwrap() error
type Indexer ¶
type Indexer struct {
// contains filtered or unexported fields
}
Indexer extracts index keys from Kubernetes resources and filters fields.
It combines JSONPath evaluation for key extraction with field filtering for memory optimization.
func New ¶
New creates a new Indexer with the provided configuration.
Returns an error if:
- IndexBy is empty
- Any JSONPath expression is invalid (fail-fast)
Example:
indexer, err := indexer.New(indexer.Config{
IndexBy: []string{
"metadata.namespace",
"metadata.name",
},
IgnoreFields: []string{
"metadata.managedFields",
},
})
func (*Indexer) ExtractKeys ¶
ExtractKeys extracts index keys from the resource using configured JSONPath expressions.
Returns:
- A slice of string keys in the order of IndexBy configuration
- An error if key extraction fails
Example:
// For IndexBy: ["metadata.namespace", "metadata.name"] keys, err := indexer.ExtractKeys(ingress) // keys = ["default", "my-ingress"]
func (*Indexer) FilterFields ¶
FilterFields removes fields from the resource based on IgnoreFields configuration.
The resource is modified in-place for efficiency. Returns an error if filtering fails.
Example:
err := indexer.FilterFields(ingress) // ingress.Metadata.ManagedFields is now removed
func (*Indexer) IndexExpressions ¶
IndexExpressions returns the JSONPath expressions used for key extraction.
func (*Indexer) Process ¶
func (idx *Indexer) Process(resource any) (*ProcessResult, error)
Process filters fields, extracts keys, and converts the resource for template use.
This is the most common usage pattern: filter the resource to reduce memory, extract keys for indexing, and convert for template access.
Returns:
- ProcessResult containing index keys and converted resource
- An error if any operation fails
The original resource is modified in-place by field filtering.
Example:
result, err := indexer.Process(ingress)
if err != nil {
return err
}
store.Add(result.ConvertedResource, result.Keys)
type JSONPathError ¶
JSONPathError represents an error during JSONPath evaluation.
func (*JSONPathError) Error ¶
func (e *JSONPathError) Error() string
func (*JSONPathError) Unwrap ¶
func (e *JSONPathError) Unwrap() error
type JSONPathEvaluator ¶
type JSONPathEvaluator struct {
// contains filtered or unexported fields
}
JSONPathEvaluator evaluates JSONPath expressions against Kubernetes resources.
func NewJSONPathEvaluator ¶
func NewJSONPathEvaluator(expression string) (*JSONPathEvaluator, error)
NewJSONPathEvaluator creates a new JSONPath evaluator for the given expression.
The expression should follow JSONPath syntax without the surrounding braces. For example: "metadata.namespace" or "metadata.labels['app']"
Returns an error if the expression is invalid (fail-fast).
func (*JSONPathEvaluator) Evaluate ¶
func (e *JSONPathEvaluator) Evaluate(resource any) (string, error)
Evaluate executes the JSONPath expression against the provided resource.
Returns:
- The extracted value as a string
- An error if evaluation fails or the result is not a string
If the expression matches multiple values, only the first is returned.
func (*JSONPathEvaluator) Expression ¶
func (e *JSONPathEvaluator) Expression() string
Expression returns the JSONPath expression used by this evaluator.
type ProcessResult ¶
type ProcessResult struct {
// Keys are the index keys for store lookups.
Keys []string
// ConvertedResource is the resource with floats converted to ints,
// ready for use in templates. This is stored instead of the original
// unstructured.Unstructured to avoid conversion on every access.
ConvertedResource map[string]any
}
ProcessResult contains the results of processing a resource for storage.
Source Files