https://github.com/cisco-open/k8s-objectmatcher
A Kubernetes object matcher library to avoid unnecessary K8s object updates
https://github.com/cisco-open/k8s-objectmatcher
k8s kubernetes operators
Last synced: about 1 month ago
JSON representation
A Kubernetes object matcher library to avoid unnecessary K8s object updates
- Host: GitHub
- URL: https://github.com/cisco-open/k8s-objectmatcher
- Owner: cisco-open
- License: apache-2.0
- Created: 2019-04-26T07:56:50.000Z (about 6 years ago)
- Default Branch: master
- Last Pushed: 2025-03-13T02:15:50.000Z (about 2 months ago)
- Last Synced: 2025-03-29T11:52:49.227Z (about 1 month ago)
- Topics: k8s, kubernetes, operators
- Language: Go
- Homepage:
- Size: 436 KB
- Stars: 158
- Watchers: 11
- Forks: 29
- Open Issues: 9
-
Metadata Files:
- Readme: README.md
- Contributing: .github/CONTRIBUTING.md
- License: LICENSE
- Code of conduct: .github/CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
# Kubernetes object matcher
[](https://pkg.go.dev/mod/github.com/cisco-open/k8s-objectmatcher)
K8S-ObjectMatcher is a Golang library which helps to match Kubernetes objects.
### Motivation
Here at Banzai Cloud we love and write lots of Kubernetes [operators](https://github.com/banzaicloud?utf8=✓&q=operator&type=&language=). While writing some complex operators as the [Istio](https://github.com/banzaicloud/istio-operator) , [Vault](https://github.com/banzaicloud/bank-vaults) or [Kafka](https://github.com/banzaicloud/kafka-operator) operator, we encountered a huge amount of **unnecessary Kubernetes object updates**. Most of the operators out there are using `reflect.DeepEquals` to match the given object's `Spec`. Unfortunately, this solution is not perfect because every Kubernetes object is amended with different default values while submitted. This library aims to provide finer object matching capabilities to avoid unnecessary updates and more observability on the client side.
### Legacy version deprecation notice
There is a legacy version of the lib, that is now deprecated and documented here: [docs/legacy.md](docs/legacy.md)
### How does it work?
The library uses the same method that `kubectl apply` does under the hood to calculate a patch using the [three way merge](http://www.drdobbs.com/tools/three-way-merging-a-look-under-the-hood/240164902) method.
However for this to work properly we need to keep track of the last applied version of our object, let's call it the `original`. Unfortunately Kubernetes does
not keep track of our previously submitted object versions, but we can put it into an annotation like `kubectl apply` does.
Next time we query the `current` state of the object from the API Server we can extract the `original` version from the annotation.
Once we have the the `original`, the `current` and our new `modified` object in place the library will take care of the rest.
#### Example steps demonstrated on a v1.Service object
Create a new object, annotate it, then submit normally
```go
original := &v1.Service{
...
}
if err := patch.DefaultAnnotator.SetLastAppliedAnnotation(original); err != nil {
...
}
client.CoreV1().Services(original.GetNamespace()).Create(original)
```
Next time we check the diff and set the last applied annotation in case we have to update
```go
modified := &v1.Service{
...
}
current, err := client.CoreV1().Services(modified.GetNamespace()).Get(modified.GetName(), metav1.Getoptions{})
patchResult, err := patch.DefaultPatchMaker.Calculate(current, modified)
if err != nil {
return err
}
if !patchResult.IsEmpty() {
if err := patch.DefaultAnnotator.SetLastAppliedAnnotation(modified); err != nil {
...
}
client.CoreV1().Services(modified.GetNamespace()).Update(modified)
}
```
### CalculateOptions
In certain cases there is a need to filter out certain fields when the patch generated by the library is false positive.
To help in these scenarios there are the following options to be used when calculating diffs:
- `IgnoreStatusFields`
- `IgnoreVolumeClaimTemplateTypeMetaAndStatus`
- `IgnoreField("field-name-to-ignore")`
Example:
```
opts := []patch.CalculateOption{
patch.IgnoreStatusFields(),
}
patchResult, err := patch.DefaultPatchMaker.Calculate(existing.(runtime.Object), newObject.(runtime.Object), opts...)
if err != nil {
return err
}
```
#### IgnoreStatusFields
This CalculateOptions removes status fields from both objects before comparing.
#### IgnoreVolumeClaimTemplateTypeMetaAndStatus
This CalculateOption clears volumeClaimTemplate fields from both objects before comparing (applies to statefulsets).
#### IgnoreField("field-name-to-ignore")
This CalculateOption removes the field provided (as a string) in the call before comparing them. A common usage might be to remove the metadata fields by using the `IgnoreField("metadata")` option.
## Contributing
If you find this project useful here's how you can help:
- Send a pull request with your new features and bug fixes
- Help new users with issues they may encounter
- Support the development of this project and star this repo!
## License
Copyright (c) 2017-2019 [Banzai Cloud, Inc.](https://banzaicloud.com)
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
[http://www.apache.org/licenses/LICENSE-2.0](http://www.apache.org/licenses/LICENSE-2.0)
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.