Resource pruning

Recommendations for pruning resources

Overview

Operators can create Jobs or Pods as part of their normal operation, and when those Jobs or Pods complete, they can remain on the Kubernetes cluster if not specifically removed. These resources can consume valuable cluster resources like disk storage (e.g. etcd). These resources are not tied to a Custom Resource using an ownerReference.

Operator authors have traditionally had two pruning options:

  • leave the resource cleanup to a system admin to perform
  • implement some form of pruning within their operator solution

For our purposes when we say, prune, we mean to remove a resource (e.g. kubectl delete) from a Kubernetes cluster for a given namespace.

This documentation describes the pattern and library useful for implementing a solution within an operator.

operator-lib prune library

A simple pruning implementation can be found in the operator-lib prune package. This package is written in Go and is meant to be used within Go-based operators. This package was developed to include common pruning strategies as found in common operators. The package also allow for customization of hooks and strategies.

Pruning Configuration

Users can configure the pruning library by creating code similar to this example:

  1. cfg = Config{
  2. Log: logf.Log.WithName("prune"),
  3. DryRun: false,
  4. Clientset: client,
  5. LabelSelector: "app=churro",
  6. Resources: []schema.GroupVersionKind{
  7. {Group: "", Version: "", Kind: PodKind},
  8. },
  9. Namespaces: []string{"default"},
  10. Strategy: StrategyConfig{
  11. Mode: MaxCountStrategy,
  12. MaxCountSetting: 1,
  13. },
  14. PreDeleteHook: myhook,
  15. }
Config FieldDescription
Loga logr.Logger. It is optional if a logger is provided through the context to the Execute method, which is the case with the context of the Reconcile function of operator-sdk and controller-runtime
DryRuna boolean determines whether to actually remove resources; true means to execute but not to remove resources
Clientseta client-go Kubernetes ClientSet that will be used for Kube API calls by the library
LabelSelectorKubernetes label selector expression used to find resources to prune
ResourcesKube resource Kinds, currently PodKind and JobKind are supported by the library
Namespacesa list of Kube Namespaces to search for resources
Strategyspecifies the pruning strategy to execute
Strategy.Modecurrently MaxCountStrategy, MaxAgeStrategy, or CustomStrategy are supported
Strategy.MaxCountSettinginteger value for maxcount strategy, specifies how many resources should remain after pruning executes
Strategy.MaxAgeSettinggolang time.Duration string value (e.g. 48h), specifies age of resources to prune
Strategy.CustomSettingsa golang map of values that can be passed into a Custom strategy function
PreDeleteHookoptionally specifies a golang function to call before pruning a resource
CustomStrategyoptionally specifies a golang function that implements a custom pruning strategy

Pruning Execution

Users can invoke the pruning by running the Execute function on the pruning configuration as follows:

  1. err := cfg.Execute(ctx)

Users might want to implement pruning execution by means of a cron package or simply call the prune library based on some other triggering event.

If a logger has been configured in the Config structure it takes precedence on the one provided through ctx. Adding a logger.Logger to the context can be done with logr.NewContext.

Pruning Strategies

maxcount Strategy

A strategy of leaving a finite set of resources is implemented called maxcount. This strategy seeks to leave a specific number of resources, sorted by latest, on your cluster. For example, if you have 10 resources that would be pruned, and you specified a maxcount value of 4, then 6 resources would be pruned (removed) from your cluster starting with the oldest resources.

maxage Strategy

A strategy of removing resources greater than a specific time is called maxage. This strategy seeks to remove resources older than a specified maxage duration. For example, a library user might specify a value of 48h to indicate that any resource older than 48 hours would be pruned. Durations are specified using golang’s time.Duration formatting (e.g. 48h).

Pruning Customization

preDelete Hook

Users can provide a preDelete hook when using the operator-lib prune package.
This hook function will be called by the library before removing a resource. This provides a means to examine the resource logs for example, extracting any valued content, before the resource is removed from the cluster.

Here is an example of a preDelete hook:

  1. func myhook(ctx context.Context, cfg Config, res ResourceInfo) error {
  2. log := prune.Logger(ctx, cfg)
  3. log.V(4).Info("pre-deletion", "GVK", res.GVK, "namespace", res.Namespace, "name", res.Name)
  4. if res.GVK.Kind == PodKind {
  5. req := cfg.Clientset.CoreV1().Pods(res.Namespace).GetLogs(res.Name, &v1.PodLogOptions{})
  6. podLogs, err := req.Stream(context.Background())
  7. if err != nil {
  8. return err
  9. }
  10. defer podLogs.Close()
  11. buf := new(bytes.Buffer)
  12. _, err = io.Copy(buf, podLogs)
  13. if err != nil {
  14. return err
  15. }
  16. log.V(4).Info("pod log before removing is", "log", buf.String())
  17. }
  18. return nil
  19. }

Note if your custom hook returns an error, then the resource will not be removed by the prune library.

Custom Strategy

Library users can also write their own custom pruning strategy function to support advanced cases. Custom strategy functions are passed in the prune configuration and a list of resources selected by the library. The custom strategy builds up a list of resources to be removed, returning the list to the prune library which performs the actual resource removal. Here is an example custom strategy:

  1. func myStrategy(ctx context.Context, cfg Config, resources []ResourceInfo) (resourcesToRemove []ResourceInfo, err error) {
  2. log := Logger(ctx, cfg)
  3. log.V(4).Info("myStrategy called", "resources", resources, "config", cfg)
  4. if len(resources) != 3 {
  5. return resourcesToRemove, fmt.Errorf("count of resources did not equal our expectation")
  6. }
  7. return resourcesToRemove, nil
  8. }

To have your custom strategy invoked, you will specify your function within the prune configuration as follows:

  1. cfg.Strategy.Mode = CustomStrategy
  2. cfg.Strategy.CustomSettings = make(map[string]interface{})
  3. cfg.CustomStrategy = myStrategy

Notice that you can optionally pass in settings to your custom function as a map using the cfg.Strategy.CustomSettings field.

Last modified March 30, 2022: Documents operator-lib PR #100. (#5515) (472b4517)