github.com/wmuizelaar/kpt@v0.0.0-20221018115725-bd564717b2ed/site/book/02-concepts/03-functions.md (about)

     1  A kpt function (also called a _KRM function_) is a containerized program that
     2  can perform CRUD operations on KRM resources stored on the local filesystem. kpt
     3  functions are the extensible mechanism to automate mutation and validation of
     4  KRM resources. Some example use cases:
     5  
     6  - Enforce all `Namespace` resources to have a `cost-center` label.
     7  - Add a label to resources based on some filtering criteria
     8  - Use a `Team` custom resource to generate a `Namespace` and associated
     9    organization-mandated defaults (e.g. `RBAC`, `ResourceQuota`, etc.) when
    10    bootstraping a new team
    11  - Bulk transformation of all `PodSecurityPolicy` resources to improve the
    12    security posture.
    13  - Inject a sidecar container (service mesh, mysql proxy, logging) in a workload
    14    resource (e.g. `Deployment`)
    15  
    16  Since functions are containerized, they can encapsulate different toolchains,
    17  languages, and runtimes. For example, the function container image can
    18  encapsulate:
    19  
    20  - A binary built using kpt's official Go or Typescript SDK
    21  - Wrap an existing KRM tool such as `kubeval`
    22  - Invoke a bash script performing low-level operations
    23  - The interpreter for "executable configuration" such as `Starlark` or `Rego`
    24  
    25  To astute readers, this model will sound familiar: functions are the client-side
    26  analog to Kubernetes controllers:
    27  
    28  |                  | Client-side              | Server-side       |
    29  | ---------------- | ------------------------ | ----------------- |
    30  | **Orchestrator** | kpt                      | Kubernetes        |
    31  | **Data**         | YAML files on filesystem | resources on etcd |
    32  | **Programs**     | functions                | controllers       |
    33  
    34  Just as Kubernetes system orchestrates server-side containers, kpt CLI
    35  orchestrates client-side containers operating on configuration. By standardizing
    36  the input and output of the function containers, and how the containers are
    37  executed, kpt can provide the following guarantees:
    38  
    39  - Functions are interoperable
    40  - Functions can be chained together
    41  - Functions are hermetic. For correctness, security and speed, it's desirable to
    42    be able to run functions hermetically without any privileges; preventing
    43    out-of-band access to the host filesystem and networking.
    44  
    45  We will discuss the KRM Functions Specification Standard in detail in Chapter 5.
    46  At a high level, a function execution looks like this:
    47  
    48  ![img](/static/images/func.svg)
    49  
    50  where:
    51  
    52  - `input items`: The input list of KRM resources to operate on.
    53  - `output items`: The output list obtained from adding, removing, or modifying
    54    items in the input.
    55  - `functionConfig`: An optional meta resource containing the arguments to this
    56    invocation of the function.
    57  - `results`: An optional meta resource emitted by the function for observability
    58    and debugging purposes.
    59  
    60  Naturally, functions can be chained together in a pipeline:
    61  
    62  ![img](/static/images/pipeline.svg)
    63  
    64  There are two different CLI commands that execute functions corresponding to two
    65  fundamentally different approaches:
    66  
    67  - `kpt fn render`: Executes the pipeline of functions declared in the package
    68    and its subpackages. This is a declarative way to run functions.
    69  - `kpt fn eval`: Executes a given function on the package. The image to run and
    70    the `functionConfig` is specified as CLI argument. This is an imperative way
    71    to run functions. Since the function is provided explicitly by the user, an
    72    imperative invocation can be more privileged and low-level than an declarative
    73    invocation. For example, it can have access to the host system.
    74  
    75  We will discuss how to run functions in Chapter 4 and how to develop functions
    76  in Chapter 5.