## Function Basics

### Synopsis

  `kustomize fn` enables encapsulating function for manipulating Resource
  configuration inside containers, which are run using `run`.

  First fetch the kustomize repository, which contains a collection of example
  functions

	git clone https://github.com/kubernetes-sigs/kustomize
	cd kustomize/functions/examples/

### Templating -- CockroachDB

  This section demonstrates how to leverage templating based solutions from
  `kustomize fn`.  The templating function is implemented as a `bash` script
  using a `heredoc`.

  #### 1: Generate the Resources

  `cd` into the `kustomize/functions/examples/template-heredoc-cockroachdb/`
  directory, and invoke `run` on the `local-resource/` directory.

    cd template-heredoc-cockroachdb/

    # view the Resources
    kustomize cfg tree local-resource/ --name --image --replicas

    # run the function
    kustomize fn run local-resource/

    # view the generated Resources
    kustomize cfg tree local-resource/ --name --image --replicas

  `run` generated the directory ` local-resource/config` containing the generated
  Resources.

  #### 2. Modify the Generated Resources

  - modify the generated Resources by adding an annotation, sidecar container, etc.
  - modify the `local-resource/example-use.yaml` by changing the replicas

  re-run `run`.  this will apply the updated replicas to the generated Resources,
  but keep the fields that you manually added to the generated Resource configuration.

    # run the function
    kustomize fn run local-resource/

  `run` facilitates a non-destructive *smart templating* approach that allows templating
  to be composed with manual modifications directly to the template output, as well as
  composition with other functions which may appy validation or injection of values.

  #### 3. Function Implementation

  the function implementation is located under the `image/` directory as a `Dockerfile`
  and a `bash` script.

### Templating -- Nginx

  The steps in this section are identical to the CockroachDB templating example,
  but the function implementation is very different, and implemented as a `go`
  program rather than a `bash` script.

  #### 1: Generate the Resources

  `cd` into the `kustomize/functions/examples/template-go-nginx/`
  directory, and invoke `run` on the `local-resource/` directory.

    cd template-go-nginx/

    # view the Resources
    kustomize cfg tree local-resource/ --name --image --replicas

    # run the function
    kustomize fn run local-resource/

    # view the generated Resources
    kustomize cfg tree local-resource/ --name --image --replicas

  `run` generated the directory ` local-resource/config` containing the generated
  Resources.  this time it put the configuration in a single file rather than multiple
  files.  The mapping of Resources to files is controlled by the function itself through
  annotations on the generated Resources.

  #### 2. Modify the Generated Resources

  - modify the generated Resources by adding an annotation, sidecar container, etc.
  - modify the `local-resource/example-use.yaml` by changing the replicas

  re-run `run`.  this will apply the updated replicas to the generated Resources,
  but keep the fields that you manually added to the generated Resource configuration.

    # run the function
    kustomize fn run local-resource/

  Just like in the preceding section, the function is implemented using a non-destructive
  approach which merges the generated Resources into previously generated instances.

  #### 3. Function Implementation

  the function implementation is located under the `image/` directory as a `Dockerfile`
  and a `go` program.

### Validation -- resource reservations

  This section uses `run` to perform validation rather than generate Resources.

  #### 1: Run the Validator

  `cd` into the `kustomize/functions/examples/validator-resource-requests`
  directory, and invoke `run` on the `local-resource/` directory.

    # run the function
    kustomize fn run local-resource/
    cpu-requests missing for a container in Deployment nginx (example-use.yaml [1])
    Error: exit status 1
    Usage:
    ...

  #### 2: Fix the validation issue

  The command will fail complaining that the nginx Deployment is missing `cpu-requests`,
  and print the name of the file + Resource index.  Edit the file and uncomment the resources,
  then re-run the functions.

    kustomize fn run local-resource/

  The validation now passes.

### Injection -- resource reservations

  This section uses `run` to perform injection of field values based off annotations
  on the Resource.

  #### 1: Run the Injector

  `cd` into the `kustomize/functions/examples/inject-tshirt-sizes`
  directory, and invoke `run` on the `local-resource/` directory.

    # print the resources
    kustomize cfg tree local-resource --resources --name
    local-resource
    ├── [example-use.yaml]  Validator
    └── [example-use.yaml]  Deployment nginx
        └── spec.template.spec.containers
            └── 0
                └── name: nginx

    # run the functions
    kustomize fn run local-resource/

    # print the new resources
    kustomize cfg tree local-resource --resources --name
    ├── [example-use.yaml]  Validator
    └── [example-use.yaml]  Deployment nginx
        └── spec.template.spec.containers
            └── 0
                ├── name: nginx
                └── resources: {requests: {cpu: 4, memory: 1GiB}}

  #### 2: Change the tshirt-size

  Change the `tshirt-size` annotation from `medium` to `small` and re-run the functions.

    kustomize fn run local-resource/
    kustomize cfg tree local-resource/
    local-resource
    ├── [example-use.yaml]  Validator
    └── [example-use.yaml]  Deployment nginx
        └── spec.template.spec.containers
            └── 0
                ├── name: nginx
                └── resources: {requests: {cpu: 200m, memory: 50MiB}}

  The function has applied the reservations for the new tshirt-size

### Function Composition

Functions may be composed together.  Try putting the Injection (tshirt-size) and
Validation functions together in the same .yaml file (separated by `---`).  Run
`run` and observe that the first function in the file is applied to the Resources,
and then the second function in the file is applied.