Functions

Functions Developer Guide

Config functions are conceptually similar to Kubernetes controllers and validating webhooks – they are programs which read resources as input, then write resources as output (creating, modifying, deleting, or validating resources).

Unlike controllers and validating webhooks, config functions can be run outside of the Kubernetes control plane. This allows them to run in more contexts or embedded in other systems. For example, functions could be:

• manually run locally
• automatically run locally as part of make, mvn, go generate, etc
• automatically run in CI/CD systems
• run by controllers as reconcile implementations

The following function runtimes are available in kpt:

Additionally, the following libraries are available to create config functions:

Input / Output

Functions read a ResourceList, modify it, and write it back out. The ResourceList contains:

• (input+output) a list of resource items
• (input) configuration for the function
• (output) validation results

ResourceList.items

Items are resources read from some source – such as a package directory – using a source function – such as kpt fn source or helm-template.

After a function adds, deletes or modifies items, the items will be written to a sink directory using a sink function – such as kpt fn sink. In most cases the sink directory will be the same as the source directory.

kind: ResourceList
items:
- apiVersion: apps/v1
  kind: Deployment
  spec:
  ...
- apiVersion: v1
  kind: Service
  spec:
  ...

ResourceList.functionConfig

Functions may optionally be configured using the ResourceList.functionConfig field. functionConfig is analogous to a Deployment, and items is analogous to the set of all resources in the Deployment controller in-memory cache (e.g. all the resources in the cluster) – this includes the ReplicaSets created, updated and deleted for that Deployment.

kind: ResourceList
functionConfig:
  apiVersion: example.com/v1alpha1
  kind: Foo
  spec:
    foo: bar
    ...
items:
  ...

ResourceList.results

Functions may define validation results through the results field. When functions are run using the --results-dir, each function’s results field will be written to a file under the specified directory.

kind: ResourceList
functionConfig:
  apiVersion: example.com/v1alpha1
  kind: Foo
  spec:
    foo: bar
    ...
results:
- name: "kubeval"
  items:
  - severity: error # one of ["error", "warn", "info"] -- error code should be non-0 if there are 1 or more errors
    tags: # arbitrary metadata about the result
      error-type: "field"
    message: "Value exceeds the namespace quota, reduce the value to make the pod schedulable"
    resourceRef: # key to lookup the resource
      apiVersion: apps/v1
      kind: Deployment
      name: foo
      namespace: bar
    file:
      # optional if present as annotation
      path: deploy.yaml # read from annotation if present
      # optional if present as annotation
      index: 0 # read from annotation if present
    field:
      path: "spec.template.spec.containers[3].resources.limits.cpu"
      currentValue: "200" # number | string | boolean
      suggestedValue: "2" # number | string | boolean
  - severity: warn
    ...
- name: "something else"
  items:
  - severity: info
     ...

Next Steps

• Learn how to run functions.
• Find out how to structure a pipeline of functions from the functions concepts page.
• Consult the fn command reference.