airshipctl/krm-functions/replacement-transformer/README.md

Replacement Transformer

This plugin is written in go and uses the kyaml and airshipctl libraries for parsing the input and writing the output.

Function implementation

The function is implemented as an image, and built using make image. Function reads configuration, a collection of input resources, and performs values replacement based on configuration.

Function invocation

The function is invoked by authoring a local Resource with metadata.annotations.[config.kubernetes.io/function] and running:

kustomize config run local-resource/

This exits non-zero if there is an error.

Running the Example

Run Replacement Transformer with:

kustomize fn run local-resource --dry-run

Value of spec.version in resource KubeadmControlPlane (v1.18.6) will be replaced with value of kubernetes field defined in VariableCatalogue resource

Configuration file format

Replacement Transformer configuration resource is represented as a standard k8s resource with Group, Version, Kind and Metadata header. Replacement configuration is defined under replacements field which contains a list of object with following structure.

source:
  objref:
    group: airshipit.org
    version: v1alpha1
    kind: Clusterctl
    name: resource-name
    namespace: capm3
  value: "string value"
  fieldref: {.data.host}
target:
  objref:
    group: airshipit.org
    version: v1alpha1
    kind: KubeConfig
    name: resource-name
    namespace: capi-system
  fieldrefs:
    - {.config.kind}

• source defines where a substitution is from. It can from two different kinds of sources from a field of one resource or from a string.
  • objref refers to a kubernetes object by Group, Version, Kind, Name and Namespace. Each field can be omitted or be an empty string.
  • value static string value to substitute into target.
  • fieldref JSON path to particular object field. This field essentially represents JSON query with syntax used in kubectl executed with flag --jsonpath. JSON path syntax end elements is defined by https://goessner.net/articles/JsonPath/
• target defines a substitution target.
  • objref specifies a set of resources. Any resource that matches intersection of all conditions (Group, Version, Kind, Name and Namespace) is included in this set.
  • fieldrefs list of JSON path strings which identify target field to substitute into. Field reference may have include pattern which is used as a replacement variable. For example in following query {.metadata.name}%NAME% string surrounded by % symbols (i.e. NAME) is considered as a pattern inside a field value identified by JSON path metadata.name. Therefore if value of metadata.name is some-NAME-of-the-pod only NAME substring is replaced with the string defined by substitution source.