{"id":26445524,"url":"https://github.com/cisco-open/k8s-objectmatcher","last_synced_at":"2025-05-15T06:08:15.411Z","repository":{"id":41888778,"uuid":"183584478","full_name":"cisco-open/k8s-objectmatcher","owner":"cisco-open","description":"A Kubernetes object matcher library to avoid unnecessary K8s object updates","archived":false,"fork":false,"pushed_at":"2025-03-13T02:15:50.000Z","size":446,"stargazers_count":159,"open_issues_count":9,"forks_count":29,"subscribers_count":11,"default_branch":"master","last_synced_at":"2025-05-15T04:54:39.748Z","etag":null,"topics":["k8s","kubernetes","operators"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cisco-open.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":".github/CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":".github/CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-04-26T07:56:50.000Z","updated_at":"2025-04-17T18:00:30.000Z","dependencies_parsed_at":"2024-02-08T02:28:38.053Z","dependency_job_id":"c9a2b351-3728-404e-b1e7-7b8eea9188ff","html_url":"https://github.com/cisco-open/k8s-objectmatcher","commit_stats":null,"previous_names":[],"tags_count":24,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cisco-open%2Fk8s-objectmatcher","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cisco-open%2Fk8s-objectmatcher/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cisco-open%2Fk8s-objectmatcher/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cisco-open%2Fk8s-objectmatcher/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cisco-open","download_url":"https://codeload.github.com/cisco-open/k8s-objectmatcher/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254283350,"owners_count":22045141,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["k8s","kubernetes","operators"],"created_at":"2025-03-18T11:19:05.549Z","updated_at":"2025-05-15T06:08:15.391Z","avatar_url":"https://github.com/cisco-open.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Kubernetes object matcher\n\n![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/cisco-open/k8s-objectmatcher/ci.yaml?style=flat-square)\n[![go.dev reference](https://img.shields.io/badge/go.dev-reference-007d9c?logo=go\u0026logoColor=white\u0026style=flat-square)](https://pkg.go.dev/mod/github.com/cisco-open/k8s-objectmatcher)\n\nK8S-ObjectMatcher is a Golang library which helps to match Kubernetes objects.\n\n### Motivation\n\nHere at Banzai Cloud we love and write lots of Kubernetes [operators](https://github.com/banzaicloud?utf8=✓\u0026q=operator\u0026type=\u0026language=). 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.\n\n### Legacy version deprecation notice\n\nThere is a legacy version of the lib, that is now deprecated and documented here: [docs/legacy.md](docs/legacy.md)\n\n### How does it work?\n\nThe 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.\nHowever 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\nnot keep track of our previously submitted object versions, but we can put it into an annotation like `kubectl apply` does.\nNext time we query the `current` state of the object from the API Server we can extract the `original` version from the annotation.\n\nOnce we have the the `original`, the `current` and our new `modified` object in place the library will take care of the rest.\n\n#### Example steps demonstrated on a v1.Service object\n\nCreate a new object, annotate it, then submit normally\n```go\noriginal := \u0026v1.Service{\n  ...\n}\n\nif err := patch.DefaultAnnotator.SetLastAppliedAnnotation(original); err != nil {\n  ...\n}\n\nclient.CoreV1().Services(original.GetNamespace()).Create(original)\n```\n\nNext time we check the diff and set the last applied annotation in case we have to update\n```go\nmodified := \u0026v1.Service{\n  ...\n}\n\ncurrent, err := client.CoreV1().Services(modified.GetNamespace()).Get(modified.GetName(), metav1.Getoptions{})\n\npatchResult, err := patch.DefaultPatchMaker.Calculate(current, modified)\nif err != nil {\n  return err\n}\n\nif !patchResult.IsEmpty() {\n  if err := patch.DefaultAnnotator.SetLastAppliedAnnotation(modified); err != nil {\n  \t...\n  }\n  client.CoreV1().Services(modified.GetNamespace()).Update(modified)\n}\n\n```\n\n### CalculateOptions\n\nIn certain cases there is a need to filter out certain fields when the patch generated by the library is false positive.\nTo help in these scenarios there are the following options to be used when calculating diffs:\n- `IgnoreStatusFields`\n- `IgnoreVolumeClaimTemplateTypeMetaAndStatus`\n- `IgnoreField(\"field-name-to-ignore\")`\n\nExample:\n```\n\topts := []patch.CalculateOption{\n\t\tpatch.IgnoreStatusFields(),\n\t}\n\n\tpatchResult, err := patch.DefaultPatchMaker.Calculate(existing.(runtime.Object), newObject.(runtime.Object), opts...)\n\tif err != nil {\n\t\treturn err\n\t}\n```\n\n#### IgnoreStatusFields\n\nThis CalculateOptions removes status fields from both objects before comparing.\n\n#### IgnoreVolumeClaimTemplateTypeMetaAndStatus\n\nThis CalculateOption clears volumeClaimTemplate fields from both objects before comparing (applies to statefulsets).\n\n#### IgnoreField(\"field-name-to-ignore\")\n\nThis 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.\n\n\n## Contributing\n\nIf you find this project useful here's how you can help:\n\n- Send a pull request with your new features and bug fixes\n- Help new users with issues they may encounter\n- Support the development of this project and star this repo!\n\n## License\n\nCopyright (c) 2017-2019 [Banzai Cloud, Inc.](https://banzaicloud.com)\n\nLicensed under the Apache License, Version 2.0 (the \"License\");\nyou may not use this file except in compliance with the License.\nYou may obtain a copy of the License at\n\n[http://www.apache.org/licenses/LICENSE-2.0](http://www.apache.org/licenses/LICENSE-2.0)\n\nUnless required by applicable law or agreed to in writing, software\ndistributed under the License is distributed on an \"AS IS\" BASIS,\nWITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\nSee the License for the specific language governing permissions and\nlimitations under the License.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcisco-open%2Fk8s-objectmatcher","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcisco-open%2Fk8s-objectmatcher","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcisco-open%2Fk8s-objectmatcher/lists"}