1 // Copyright 2019 The Kubernetes Authors. 2 // SPDX-License-Identifier: Apache-2.0 3 4 // Package framework contains a framework for writing functions in Go. The function specification 5 // is defined at: https://github.com/kubernetes-sigs/kustomize/blob/master/cmd/config/docs/api-conventions/functions-spec.md 6 // 7 // Functions are executables that generate, modify, delete or validate Kubernetes resources. 8 // They are often used used to implement abstractions ("kind: JavaSpringBoot") and 9 // cross-cutting logic ("kind: SidecarInjector"). 10 // 11 // Functions may be run as standalone executables or invoked as part of an orchestrated 12 // pipeline (e.g. kustomize). 13 // 14 // Example function implementation using framework.SimpleProcessor with a struct input 15 // 16 // import ( 17 // "sigs.k8s.io/kustomize/kyaml/errors" 18 // "sigs.k8s.io/kustomize/kyaml/fn/framework" 19 // "sigs.k8s.io/kustomize/kyaml/kio" 20 // "sigs.k8s.io/kustomize/kyaml/yaml" 21 // ) 22 // 23 // type Spec struct { 24 // Value string `yaml:"value,omitempty"` 25 // } 26 // type Example struct { 27 // Spec Spec `yaml:"spec,omitempty"` 28 // } 29 // 30 // func runFunction(rlSource *kio.ByteReadWriter) error { 31 // functionConfig := &Example{} 32 // 33 // fn := func(items []*yaml.RNode) ([]*yaml.RNode, error) { 34 // for i := range items { 35 // // modify the items... 36 // } 37 // return items, nil 38 // } 39 // 40 // p := framework.SimpleProcessor{Config: functionConfig, Filter: kio.FilterFunc(fn)} 41 // err := framework.Execute(p, rlSource) 42 // return errors.Wrap(err) 43 // } 44 // 45 // Architecture 46 // 47 // Functions modify a slice of resources (ResourceList.Items) which are read as input and written 48 // as output. The function itself may be configured through a functionConfig 49 // (ResourceList.FunctionConfig). 50 // 51 // Example function input: 52 // 53 // kind: ResourceList 54 // items: 55 // - kind: Deployment 56 // ... 57 // - kind: Service 58 // .... 59 // functionConfig: 60 // kind: Example 61 // spec: 62 // value: foo 63 // 64 // The functionConfig may be specified declaratively and run with 65 // 66 // kustomize fn run DIR/ 67 // 68 // Declarative function declaration: 69 // 70 // kind: Example 71 // metadata: 72 // annotations: 73 // # run the function by creating this container and providing this 74 // # Example as the functionConfig 75 // config.kubernetes.io/function: | 76 // container: 77 // image: image/containing/function:impl 78 // spec: 79 // value: foo 80 // 81 // The framework takes care of serializing and deserializing the ResourceList. 82 // 83 // Generated ResourceList.functionConfig -- ConfigMaps 84 // Functions may also be specified imperatively and run using: 85 // 86 // kustomize fn run DIR/ --image image/containing/function:impl -- value=foo 87 // 88 // When run imperatively, a ConfigMap is generated for the functionConfig, and the command 89 // arguments are set as ConfigMap data entries. 90 // 91 // kind: ConfigMap 92 // data: 93 // value: foo 94 // 95 // To write a function that can be run imperatively on the commandline, have it take a 96 // ConfigMap as its functionConfig. 97 // 98 // Mutator and Generator Functions 99 // 100 // Functions may add, delete or modify resources by modifying the ResourceList.Items slice. 101 // 102 // Validator Functions 103 // 104 // A function may emit validation results by setting the ResourceList.Result 105 // 106 // Configuring Functions 107 // 108 // Functions may be configured through a functionConfig (i.e. a client-side custom resource), 109 // or through flags (which the framework parses from a ConfigMap provided as input). 110 // 111 // Functions may also access environment variables set by the caller. 112 // 113 // Building a container image for the function 114 // 115 // The go program may be built into a container and run as a function. The framework 116 // can be used to generate a Dockerfile to build the function container. 117 // 118 // # create the ./Dockerfile for the container 119 // $ go run ./main.go gen ./ 120 // 121 // # build the function's container 122 // $ docker build . -t gcr.io/my-project/my-image:my-version 123 package framework 124