Skip to content

Latest commit

 

History

History
172 lines (137 loc) · 10.6 KB

README.md

File metadata and controls

172 lines (137 loc) · 10.6 KB
Raw

Introduction

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. A program that uses the library and runs in a k8s pod meant to be inside k8s cluster. If you simply run examples in your pc/mac or server, it meant outside k8s cluster. Both of inside and outside k8s cluster are supported by the library.

There are three kind handler:

  • 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.
  • dynamic handler. Its a universal handler that create/update/delete/patch/get/list k8s resources by the underlying dynamic client.
  • 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.).

To 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.

The kubeconfig precedence is:

  • kubeconfig variable passed.
  • KUBECONFIG environment variable pointing at a file.
  • $HOME/.kube/config if exists.
  • In-cluster config if running in cluster.

The 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:

namespace := "test"
newNamespace := "test-new"
// Inside cluster. the program run within k8s pod.
handler, _ := deployment.New(ctx, "", namespace)
// handler is only allowed to create/update/delete deployment in namespace/test.
handler.Create(filename)
// handler is only allowed to create/update/delete deployment in namespace/test-new.
handler.WithNamespace(newNamespace).Create(filename)
// handler is only allowed to create/update/delete deployment in namespace/test (not namespace/test-new).
handler.Create(filename)
handler.ResetNamespace(newNamespace)
// handler is only allowed to create/update/delete deployment in namespace/test-new (not namespace/test).
handler.Create(filename)

The namespace precedence is:

  • namespace defined in yaml file or json file.

  • namespace specified by WithNamespace() or MultiNamespace() method.

  • namespace specified in New() or NewOrDie() funciton.

  • namespace will be ignored if k8s resource is cluster scope.

  • if namespace is empty, default to "default" namespace.

The 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.

For furthermore examples of how to use this library, see examples.

Installation

go get github.com/forbearing/k8s@v0.12.4

Documents

k8s handler examples:

Its 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.

Dynamic handler examples:

Its a universal handler that create/update/apply/patch/delete/get/list/watch k8s resources by the underlying dynamic client.

Deployment handler examples:

Its a typed handler that use typed client(clientset) to create/update/apply/patch/delete/get/list/watch typed resources(such as deployments, pods, etc.).

Pod handler examples:

More examples:

TODO

  • https://github.com/kubernetes/kubectl/tree/master/pkg
  • Simplify the use of client-go informer, lister
  • create/delete/update/delete/get ... all kinds of k8s resources by dyanmic client.
  • Support crate/update/delete/get... Event resources
  • Support crate/update/delete/get... Endpoint resources
  • Support crate/update/delete/get... EndpointSlice resources
  • Support crate/update/delete/get... LimitRange resources
  • Support crate/update/delete/get... PriorityClass resources
  • Support crate/update/delete/get... ResourceQuota resources
  • Support crate/update/delete/get... Lease resources
  • Add variables: GVK, GVR, Kind, Group, Version, Resource.
  • signal handler
  • Finalizers
  • controller and owner
  • UpdateStatus: update Deployment/StatefulSet... status
  • UpdateScale: scale Deployment/StatefulSet...
  • DeleteCollection
  • Leader Election
  • Recoder
  • Replace interface{} -> any
  • fack client
  • EnvTest
  • healthz
  • metrics
  • port-forward for pod, deployment and service
  • proxy
  • all handler support Patch() method to patch k8s resource.
  • operators refer to https://sdk.operatorframework.io/docs/building-operators/golang/references/client/
  • Has/Get/GetAll/Set/Remove/RemoveAll Labels and Annotations
  • Add MultiNamespace() method to create/update/delete k8s resource in multi namespaces at once.
  • create/update/delete/apply muitlple k8s resource at once.
  • k8s handler create/update/delete/apply k8s resource by the underling dynamic but get/list from listers.
  • Admission Webhook: validating admission webhook, mutating admission webhook.
  • 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.
  • ForVersion()
  • Create()/Update()/Apply() support metav1.Object
  • 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.
  • Add WithCustomBackoff(), WithCustomeHttpClient(), WithCustomeRetry(), WithCustomLogger() to generate a OptionFunc as the handler's options. before: deployment.New(ctx, kubeconfig, namespace) -> deployment.New(ctx, kubeconfig, namespace, options ...OptionFunc)