{"id":41884907,"url":"https://github.com/forbearing/k8s","last_synced_at":"2026-01-25T13:21:25.198Z","repository":{"id":41654826,"uuid":"508896968","full_name":"forbearing/k8s","owner":"forbearing","description":"The library implements various handlers to more easier create/update/apply/patch/delete/get/list/watch k8s resources such as pods, deployments, etc.  inside or outside k8s cluster.","archived":false,"fork":false,"pushed_at":"2022-11-15T23:57:18.000Z","size":2116,"stargazers_count":72,"open_issues_count":0,"forks_count":5,"subscribers_count":2,"default_branch":"main","last_synced_at":"2024-11-16T01:22:51.270Z","etag":null,"topics":["client","client-go","go","golang","k8s","kubernetes","operator"],"latest_commit_sha":null,"homepage":"https://pkg.go.dev/github.com/forbearing/k8s","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/forbearing.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2022-06-30T01:39:13.000Z","updated_at":"2024-01-03T07:50:12.000Z","dependencies_parsed_at":"2022-07-12T18:18:15.666Z","dependency_job_id":null,"html_url":"https://github.com/forbearing/k8s","commit_stats":null,"previous_names":[],"tags_count":44,"template":false,"template_full_name":null,"purl":"pkg:github/forbearing/k8s","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/forbearing%2Fk8s","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/forbearing%2Fk8s/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/forbearing%2Fk8s/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/forbearing%2Fk8s/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/forbearing","download_url":"https://codeload.github.com/forbearing/k8s/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/forbearing%2Fk8s/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28753415,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-25T10:25:12.305Z","status":"ssl_error","status_checked_at":"2026-01-25T10:25:11.933Z","response_time":113,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":["client","client-go","go","golang","k8s","kubernetes","operator"],"created_at":"2026-01-25T13:21:24.614Z","updated_at":"2026-01-25T13:21:25.189Z","avatar_url":"https://github.com/forbearing.png","language":"Go","funding_links":[],"categories":["Go"],"sub_categories":[],"readme":"## Introduction\n\n\n\nThe library implements various handlers to more easier create/update/apply/patch/delete/get/list/watch k8s resources such as pods, deployments, etc, inside or outside k8s cluster. A program that uses the library and runs in a k8s pod meant to be inside k8s cluster. If you simply run [examples](./examples) in your pc/mac or server, it meant outside k8s cluster. Both of inside and outside k8s cluster are supported by the library.\n\nThere are three kind handler:\n\n- k8s handler. Its a universal handler that simply invoke dynamic handler to create/update/patch/delete k8s resources and get/list k8s resources from listers instead of accessing the API server directly.\n- dynamic handler. Its a universal handler that create/update/delete/patch/get/list k8s resources by the underlying dynamic client.\n- typed handler such as deployment/pod handler. Its a typed handler that use typed client(clientset) to create/update/patch/delete/get/list typed resources(such as deployments, pods, etc.).\n\nTo create a handler for outside or inside cluster just call `deployment.New(ctx, \"\", namespace)`. The `New()` function will find the kubeconfig file or the file pointed to by the variable `KUBECONFIG`. If neither is found, it will use the default kubeconfig filepath `$HOME/.kube/config`. `New()` will create a deployment handler for the outside cluster if kubeconfig is found . If no kubeconfig file is found, `New()` will create an in-cluster rest.Config to create the deployment handler.\n\nThe kubeconfig precedence is:\n* kubeconfig variable passed.\n* KUBECONFIG environment variable pointing at a file.\n* $HOME/.kube/config if exists.\n* In-cluster config if running in cluster.\n\nThe variable `namespace` is used to limit the scope of the handler. If `namespace=test`, the handler is only allowed to create/update/delete deployments in namespace/test. Of course, handler.WithNamespace(newNamespace) returns a new temporary handler that allowed to create/update/delete deployments in the new namespace, for examples:\n\n```go\nnamespace := \"test\"\nnewNamespace := \"test-new\"\n// Inside cluster. the program run within k8s pod.\nhandler, _ := deployment.New(ctx, \"\", namespace)\n// handler is only allowed to create/update/delete deployment in namespace/test.\nhandler.Create(filename)\n// handler is only allowed to create/update/delete deployment in namespace/test-new.\nhandler.WithNamespace(newNamespace).Create(filename)\n// handler is only allowed to create/update/delete deployment in namespace/test (not namespace/test-new).\nhandler.Create(filename)\nhandler.ResetNamespace(newNamespace)\n// handler is only allowed to create/update/delete deployment in namespace/test-new (not namespace/test).\nhandler.Create(filename)\n```\n\nThe namespace precedence is:\n\n- namespace defined in yaml file or json file.\n\n- namespace specified by `WithNamespace()` or `MultiNamespace()` method.\n\n- namespace specified in `New()` or `NewOrDie()` funciton.\n\n- namespace will be ignored if k8s resource is cluster scope.\n\n- if namespace is empty, default to \"default\" namespace.\n\nThe library is used by another open source project that used to backup pv/pvc data attached by deployments/statefulsets/daemosnets/pods running in k8s cluster.\n\nFor furthermore examples of how to use this library, see [examples](./examples).\n\n## Installation\n\n`go get github.com/forbearing/k8s@v0.12.4`\n\n## Documents\n\n### k8s handler examples:\n\nIts a universal handler that simply invoke dynamic handler to create/update/apply/patch/delete/watch k8s resources and get/list k8s resources from listers instead of accessing the API server directly.\n\n- [How to create k8s resources.](./examples/k8s/k8s_create.go)\n- [How to update k8s resources.](./examples/k8s/k8s_update.go)\n- [How to apply k8s resources.](./examples/k8s/k8s_apply.go)\n- [How to delete k8s resources.](./examples/k8s/k8s_delete.go)\n- [How to get k8s resources.](./examples/k8s/k8s_get.go)\n- How to list k8s resources.\n- Howt to watch k8s resources.\n- informer usage.\n\n### Dynamic handler examples:\n\nIts a universal handler that create/update/apply/patch/delete/get/list/watch k8s resources by the underlying dynamic client.\n\n- [How to create k8s resources inside cluster or outside cluster.](./examples/dynamic/dynamic_create.go)\n- [How to update k8s resources.](./examples/dynamic/dynamic_update.go)\n- [How to apply k8s resources.](./examples/dynamic/dynamic_apply.go)\n- [How to patch k8s resource.](./examples/dynamic/dynamic_patch.go)\n- [How to delete k8s resources.](./examples/dynamic/dynamic_delete.go)\n- [How to get k8s resources.](./examples/dynamic/dynamic_get.go)\n- [How to list k8s resources.](./examples/dynamic/dynamic_list.go)\n- [How to watch a single k8s resources with specified kind.](./examples/dynamic/dynamic_watch_single.go)\n- [How to watch a single or multiple k8s resource with specified kind and selected by label.](./examples/dynamic/dynamic_watch_label.go)\n- [How to watch a single or multiple k8s resource with specified kind and selected by field.](./examples/dynamic/dynamic_watch_field.go)\n- [How to watch all k8s resources in the specified namespace.](./examples/dynamic/dynamic_watch_namespace.go)\n- [How to watch all k8s resources.](./examples/dynamic/dynamic_watch_all.go)\n- dynamic informer usage.\n\n### Deployment handler examples:\n\nIts a typed handler that use typed client(clientset) to create/update/apply/patch/delete/get/list/watch typed resources(such as deployments, pods, etc.).\n\n- [How to create deployment resources inside cluster or outside cluster.](./examples/deployment/deployment_create.go)\n- [How to update deployment resources inside cluster or outside cluster.](./examples/deployment/deployment_update.go)\n- [How to apply deployment resources.](./examples/deployment/deployment_apply.go)\n- [How to patch deployment resources.](./examples/deployment/deployment_patch.go)\n- [How to delete deployment resources.](./examples/deployment/deployment_delete.go)\n- [How to get deployment resources.](./examples/deployment/deployment_get.go)\n- [How to list deployment resources.](./examples/deployment/deployment_list.go)\n- [How to watch a single deployment resources.](./examples/deployment/deployment_watch_single.go)\n- [How to watch a single or multiple deployment resources selected by label.](./examples/deployment/deployment_watch_label.go)\n- [How to watch a single or multiple deployment resources selected by field.](./examples/deployment/deployment_watch_field.go)\n- [How to watch all deployment resources in the specified namespace.](./examples/deployment/deployment_watch_namespace.go)\n- [How to watch all deployment resources.](./examples/deployment/deployment_watch_all.go)\n- [How to change the number of deployment replicas.](./examples/deployment/deployment_scale.go)\n- [Deployment informer.](./examples/deployment/deployment_informer.go)\n- [More usage for informer.](./deployment/informer.go)\n- [Deployment tools.](./examples/deployment/deployment_tools.go)\n    - GetPods(): get all pods ownerd by a deployment\n    - GetRS(): get all replicaset ownerd by a deployment\n    - GetPVC()/GetPV(): Get PVC/PV mounted by a deployment\n    - IsReady(): check if a deployment is ready/available/rollout update finished.\n    - WaitReady(): block here until a deployment is ready/available/rollout update finished.\n\n### Pod handler examples:\n\n- [How to execute command within pod.](./examples/pod/pod_execute.go)\n- [How to port-forward a local port to pod.](./examples/port-forward/portforward_pod.go)\n- [How to get pod logs](./examples/pod/pod_logs.go)\n\n### More examples:\n\n- [ApplyF()/DeleteF() apply/delete various k8s resource from a yaml file.](./k8s_test.go)\n- [Check whether the k8s resources has the specifed label, Get/Set/Remove labels of k8s resources](./examples/labels/main.go)\n- [Check whether the k8s resources has the specifed annotation, Get/Set/Remove labels of k8s annotations](./examples/annotations/main.go)\n- [Find k8s resource's GroupVersionKind from yaml file, json file, bytes data, map[string]interface{}, etc.](./examples/restmapper/find_gvk.go)\n- [Find k8s resource's GroupVersionResources from yaml file, json file, bytes data, map[string]interface{}, etc.](./examples/restmapper/find_gvr.go)\n- [Check if the k8s resource is namespace scope from yaml file, json file, bytes data, map[string]interface{}, etc.](./examples/restmapper/is_namespaced.go)\n\n## TODO\n\n- [ ] https://github.com/kubernetes/kubectl/tree/master/pkg\n- [x] Simplify the use of client-go informer, lister\n- [x] create/delete/update/delete/get ... all kinds of k8s resources by dyanmic client.\n- [ ] Support crate/update/delete/get... `Event` resources\n- [ ] Support crate/update/delete/get... `Endpoint` resources\n- [ ] Support crate/update/delete/get... `EndpointSlice` resources\n- [ ] Support crate/update/delete/get... `LimitRange` resources\n- [ ] Support crate/update/delete/get... `PriorityClass` resources\n- [ ] Support crate/update/delete/get... `ResourceQuota` resources\n- [ ] Support crate/update/delete/get... `Lease` resources\n- [x] Add variables: GVK, GVR, Kind, Group, Version, Resource.\n- [x] signal handler\n- [x] Finalizers\n- [x] controller and owner\n- [ ] UpdateStatus: update Deployment/StatefulSet... status\n- [ ] UpdateScale: scale Deployment/StatefulSet...\n- [ ] DeleteCollection\n- [ ] Leader Election\n- [ ] Recoder\n- [ ] Replace interface{} -\u003e any\n- [ ] fack client\n- [ ] EnvTest\n- [ ] healthz\n- [ ] metrics\n- [x] port-forward for pod, deployment and service\n- [ ] proxy\n- [x] all handler support Patch() method to patch k8s resource.\n- [ ] operators refer to https://sdk.operatorframework.io/docs/building-operators/golang/references/client/\n- [x] Has/Get/GetAll/Set/Remove/RemoveAll Labels and Annotations\n- [ ] Add MultiNamespace() method to create/update/delete k8s resource in multi namespaces at once.\n- [ ] create/update/delete/apply muitlple k8s resource at once.\n- [ ] k8s handler create/update/delete/apply k8s resource by the underling dynamic but get/list from listers.\n- [ ] Admission Webhook: validating admission webhook, mutating admission webhook.\n- [ ] AutoVersion() find appropriate resource version for your kubernetes cluster and return a dynamic.Handler to create/update/apply/patch/delete/get/list/watch current k8s object, for example: cronjob version is v1beta1 in k8s v1.19.x.\n- [ ] ForVersion()\n- [x] Create()/Update()/Apply() support metav1.Object\n- [ ] Typed handler and dynamc handler add function NewWithOptions() and NewWithOptionsOrDie() to create new Handler with custom options, such like QPS, Burst, RateLimter that defined in rest.Config, etc.\n- [ ] Add WithCustomBackoff(), WithCustomeHttpClient(), WithCustomeRetry(), WithCustomLogger() to generate a OptionFunc as the handler's options. before: deployment.New(ctx, kubeconfig, namespace) -\u003e deployment.New(ctx, kubeconfig, namespace, options ...OptionFunc)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fforbearing%2Fk8s","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fforbearing%2Fk8s","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fforbearing%2Fk8s/lists"}