kustomize/cmd/config/docs/api-conventions/config-fn.md

# Configuration Functions API Semantics

  Configuration Functions are functions packaged as executables in containers which enable
  **shift-left practices**.  They configure applications and infrastructure through
  Kubernetes style Resource Configuration, but run locally pre-commit.

  Configuration functions enable shift-left practices (client-side) through:

  - Pre-commit / delivery validation and linting of configuration
    - e.g. Fail if any containers don't have PodSecurityPolicy or CPU / Memory limits
  - Implementation of abstractions as client actuated APIs (e.g. templating)
    - e.g. Create a client-side *"CRD"* for generating configuration checked into git
  - Aspect Orient configuration / Injection of cross-cutting configuration
    - e.g. T-Shirt size containers by annotating Resources with `small`, `medium`, `large`
      and inject the cpu and memory resources into containers accordingly.
    - e.g. Inject `init` and `side-car` containers into Resources based off of Resource
      Type, annotations, etc.

  Performing these on the client rather than the server enables:

  - Configuration to be reviewed prior to being sent to the API server
  - Configuration to be validated as part of the CD pipeline
  - Configuration for Resources to validated holistically rather than individually
    per-Resource -- e.g. ensure the `Service.selector` and `Deployment.spec.template` labels
    match.
    - MutatingWebHooks are scoped to a single Resource instance at a time.
  - Low-level tweaks to the output of high-level abstractions -- e.g. add an `init container`
    to a client *"CRD"* Resource after it was generated.
  - Composition and layering of multiple functions together
    - Compose generation, injection, validation together

  Configuration Functions are implemented as executable programs published in containers which:

  - Accept as input (stdin):
    - A list of Resource Configuration
    - A Function Configuration (to configure the function itself)
  - Emit as output (stdout + exit):
    - A list of Resource Configuration
    - An exit code for success / failure

### Function Specification

  - Functions **SHOULD** be published as container images containing a `CMD` invoking an executable.
  - Functions **MUST** accept input on STDIN a `ResourceList` containing the Resources and
    `functionConfig`.
  - Functions **MUST** emit output on STDOUT a `ResourceList` containing the modified
    Resources.
  - Functions **MUST** exit non-0 on failure, and exit 0 on success.
  - Functions **MAY** emit output on STDERR with error messaging.
  - Functions performing validation **SHOULD** exit failure and emit error messaging
    on a validation failure.
  - Functions generating Resources **SHOULD** retain non-conflicting changes on the
    generated Resources -- e.g. 1. the function generates a Deployment, but doesn't
    specify `cpu`, 2. the user sets the `cpu` on the generated Resource, 3. the
    function should keep the `cpu` when regenerating the Resource a second time.
  - Functions **SHOULD** be usable outside `kustomize config run` -- e.g. though pipeline
    mechanisms such as Tekton.

#### Input Format

  Functions must accept on STDIN:

  `ResourceList`:
  - contains `items` field, same as `List.items`
  - contains `functionConfig` field -- a single item with the configuration for the function itself

  Example `ResourceList` Input:

    apiVersion: config.kubernetes.io/v1alpha1
    kind: ResourceList
    functionConfig:
      apiVersion: example.com/v1beta1
      kind: Nginx
      metadata:
        name: my-instance
        annotations:
          config.kubernetes.io/local-config: "true"
      spec:
        replicas: 5
    items:
    -  apiVersion: apps/v1
       kind: Deployment
       metadata:
         name: my-instance
       spec:
         replicas: 3
         ...
    - apiVersion: v1
      kind: Service
      metadata:
        name: my-instance
      spec:
        ...

#### Output Format

  Functions must emit on STDOUT:

  `ResourceList`:
  - contains `items` field, same as `List.items`

  Example `ResourceList` Output:

    apiVersion: config.kubernetes.io/v1alpha1
    kind: ResourceList
    items:
    -  apiVersion: apps/v1
       kind: Deployment
       metadata:
         name: my-instance
       spec:
         replicas: 5
         ...
    - apiVersion: v1
      kind: Service
      metadata:
        name: my-instance
      spec:
        ...

#### Container Environment

  When run by `kustomize config run`, functions are run in containers with the
  following environment:

  - Network: `none`
  - User: `nobody`
  - Security Options: `no-new-privileges`
  - Volumes: the volume containing the `functionConfig` yaml is mounted under `/local` as `ro`

### Example Function Implementation

  Following is an example for implementing an nginx abstraction using a config
  function.

#### `nginx-template.sh`

  `nginx-template.sh` is a simple bash script which uses a *heredoc* as a templating solution
  for generating Resources from the functionConfig input fields.

  The script wraps itself using `config run wrap -- $0` which will:

  1. Parse the `ResourceList.functionConfig` (provided to the container stdin) into env vars
  2. Merge the stdout into the original list of Resources
  3. Defaults filenames for newly generated Resources (if they are not set as annotations)
     to `config/NAME_KIND.yaml`
  4. Format the output

    #!/bin/bash
    # script must run wrapped by `kustomize config run wrap`
    # for parsing input the functionConfig into env vars
    if [ -z ${WRAPPED} ]; then
      export WRAPPED=true
      config run wrap -- $0
      exit $?
    fi

    cat <<End-of-message
    apiVersion: v1
    kind: Service
    metadata:
      name: ${NAME}
      labels:
        app: nginx
        instance: ${NAME}
    spec:
      ports:
      - port: 80
        targetPort: 80
        name: http
      selector:
        app: nginx
        instance: ${NAME}
    ---
    apiVersion: apps/v1
    kind: Deployment
    metadata:
      name: ${NAME}
      labels:
        app: nginx
        instance: ${NAME}
    spec:
      replicas: ${REPLICAS}
      selector:
        matchLabels:
          app: nginx
          instance: ${NAME}
      template:
        metadata:
          labels:
            app: nginx
            instance: ${NAME}
        spec:
          containers:
          - name: nginx
            image: nginx:1.7.9
            ports:
            - containerPort: 80
    End-of-message

#### `Dockerfile`

  `Dockerfile` installs `kustomize config` and copies the script into the container image.

    FROM golang:1.13-stretch
    RUN go get sigs.k8s.io/kustomize/cmd/config
    RUN mv /go/bin/config /usr/bin/config
    COPY nginx-template.sh /usr/bin/nginx-template.sh
    CMD ["nginx-template.sh]

### Example Function Usage

Following is an example of running the `kustomize config run` using the preceding API.

#### `nginx.yaml` (Input)

  `dir/nginx.yaml` contains a reference to the Function.  The contents of `nginx.yaml`
  are passed to the Function through the `ResourceList.functionConfig` field.

    apiVersion: example.com/v1beta1
    kind: Nginx
    metadata:
      name: my-instance
      annotations:
        config.kubernetes.io/local-config: "true"
      configFn:
        container:
          image: gcr.io/example-functions/nginx-template:v1.0.0
    spec:
      replicas: 5

  - `configFn.container.image`: the image to use for this API
  - `annotations[config.kubernetes.io/local-config]`: mark this as not a Resource that should
    be applied

#### `kustomize config run dir/` (Output)

  `dir/my-instance_deployment.yaml` contains the Deployment:

    apiVersion: apps/v1
    kind: Deployment
    metadata:
      name: my-instance
      labels:
        app: nginx
        instance: my-instance
    spec:
      replicas: 5
      selector:
        matchLabels:
          app: nginx
          instance: my-instance
      template:
        metadata:
          labels:
            app: nginx
            instance: my-instance
        spec:
          containers:
          - name: nginx
            image: nginx:1.7.9
            ports:
            - containerPort: 80

  `dir/my-instance_service.yaml` contains the Service:

    apiVersion: v1
    kind: Service
    metadata:
      name: my-instance
      labels:
        app: nginx
        instance: my-instance
    spec:
      ports:
      - port: 80
        targetPort: 80
        name: http
      selector:
        app: nginx
        instance: my-instance