structemplate

README

Structemplate

A structured data template rendering engine for K8s objects that supports defining flexible dynamic parameters to modify arbitrary fields in the template.

Structured data template

Structured data simply means some data structured with a common serializing method like json or yaml.

In Kubernetes manifests, there are often some fields that needs to be specified dynamically according to different scenarios while most of them don't need to change.

Reusing the manifests can increase efficiency of cloud-native deployments, which is Helm is doing.

Structemplate is different from Helm. It uses a precise way to define the variational parts of a manifest template and use values list to render a template afterwards.

Structemplate is designed for managing manifest templates with dynamic parameters in a cloud native service platform which should support friendly Web UI.

Structemplate can also be used for rendering a values.yaml for automatically installing a Helm chart.

Dynamic Parameter

A dynamic parameter is a well-defined variable in the structured data template.

For example:

name: ${OBJ_NAME:=Job}
annotations:
  foo: bar

the variable OBJ_NAME is a dynamic parameter that can be replaced with a specific value while rendering. There is also a default value defined in the template which can be used while rendering if the value of this variable is not provided.

More complicated situation is about dynamic maps and arrays in the template which can be located and assigned with json path.

We can use a well-defined dynamic parameter to manage the variables and the rendering procedure in a system.

Usage

For general string templates (not only yaml/json or k8s manifests) StrSlots parameters can be used.

For K8s manifests StrSlot and JsonPath params can be used.

go get github.com/linkinghack/structemplate

Documentation

Index

• Constants
• func AppendArrayField(obj *unstructured.Unstructured, keyPath string, value interface{}) error
• func AppendMapForUnstructuredObj(obj *unstructured.Unstructured, mapParamJsonPathKey string, key string, ...) error
• func DeepCopyJSONValue(x interface{}) interface{}
• func GetValueOfNestedField(object map[string]interface{}, jsonPath string) (interface{}, error)
• func ParseJsonPathArrayIndex(idxExp string) (int64, error)
• func ParseKeyPath(keyPath string) []string
• func RenderJsonPathParamForUnstructuredObj(obj *unstructured.Unstructured, valueInjectTarget *JsonPathParamTarget, ...) error
• func RenderJsonPathParams(objsMap map[schema.GroupVersionKind][]*unstructured.Unstructured, ...) error
• func RenderStrSlotTemplate(tmpl string, valuesMapOfInterface map[string]interface{}, ...) (result string, missingKeys []string, err error)
• func SetNestedField(object map[string]interface{}, jsonPath string, value interface{}, ...) error
• func SetValueOfUnstructredObj(obj *unstructured.Unstructured, jsonPathKey string, value interface{}) error
• func SplitParamsByType(params []TemplateDynamicParam) ([]*TemplateDynamicParam, []*TemplateDynamicParam, ...)
• type JsonPathParamTarget
• type ParamValuesMap
• type TemplateDynamicParam

Constants

const (
	ParamTypeStrSlot  = "StrSlot"
	ParamTypeJsonPath = "JsonPath"
)

Functions

func AppendArrayField

func AppendArrayField(obj *unstructured.Unstructured, keyPath string, value interface{}) error

AppendArrayField 为指定Unstructured对象的数组类型字段增加值 *将自动判断keyPath指定对象是否为数组类型，或为空时自动创建数组 *若keyPath位置的值不是数组类型，则抛出错误

func AppendMapForUnstructuredObj

func AppendMapForUnstructuredObj(obj *unstructured.Unstructured, mapParamJsonPathKey string, key string, value interface{}) error

AppendMapForUnstructuredObj 为Unstructured对象指定属性设置指定value，针对map对象添加属性支持带有'.'的key

func DeepCopyJSONValue

func DeepCopyJSONValue(x interface{}) interface{}

func GetValueOfNestedField

func GetValueOfNestedField(object map[string]interface{}, jsonPath string) (interface{}, error)

GetValueOfNestedField gets the value of field specified by `jsonPath` from the target object.

func ParseJsonPathArrayIndex

func ParseJsonPathArrayIndex(idxExp string) (int64, error)

func ParseKeyPath

func ParseKeyPath(keyPath string) []string

func RenderJsonPathParamForUnstructuredObj

func RenderJsonPathParamForUnstructuredObj(obj *unstructured.Unstructured, valueInjectTarget *JsonPathParamTarget, value interface{}) error

RenderJsonPathParamForUnstructuredObj 为一个Unstructured Object渲染一个参数，自动识别label selector并过滤

func RenderJsonPathParams

func RenderJsonPathParams(objsMap map[schema.GroupVersionKind][]*unstructured.Unstructured, paramsDef []TemplateDynamicParam, valuesMap map[string]interface{}) error

RenderJsonPathParams 为一个Unstructured对象渲染一组JsonPath param

func RenderStrSlotTemplate

func RenderStrSlotTemplate(tmpl string, valuesMapOfInterface map[string]interface{}, valuesMapOfString map[string]string) (result string, missingKeys []string, err error)

RenderStrSlotTemplate Rendering a string template containing StrSlot params with the values map. @Param tmpl The template string @Param valuesMapOfInterface (optional) values of parameters @Param valuesMapOfString (optional) value of parameters @Return result Rendered string result @Return missingKeys missing keys that defined in the template without default value and no value is provided @Return err Other errors

func SetNestedField

func SetNestedField(object map[string]interface{}, jsonPath string, value interface{}, appendArray bool) error

SetNestedField sets a value in the structure of object @Param appendArray: the element to operating is an array and the value should be appended in the array @Param value: the value to inject. When append array is true, and value is an array, the elements in `value` will all be appended to the template.

func SetValueOfUnstructredObj

func SetValueOfUnstructredObj(obj *unstructured.Unstructured, jsonPathKey string, value interface{}) error

SetValueOfUnstructredObj 为指定的Unstructured对象在keyPath指定的位置上设置任意值 keyPath: `.spec.name1.name2` 格式的json path表达式 value: 需要设置的任意值

为Unstructured对象指定属性设置指定value，不支持嵌套map中使用带'.'的key

func SplitParamsByType

func SplitParamsByType(params []TemplateDynamicParam) ([]*TemplateDynamicParam, []*TemplateDynamicParam, map[string]*TemplateDynamicParam)

SplitParamsByType splits an array of TemplateDynamicParams into two groups by their type (StrSlot or JsonPath) and builds a params map with ParamCodes as keys. Returns: StrSlot Params, JsonPath Params, Params Map

Types

type JsonPathParamTarget

type JsonPathParamTarget struct {
	TargetGVK           schema.GroupVersionKind `json:"targetGVK,omitempty"`           // 对于JsonPath类型参数，指定要设置的目标模板对象, 若存在多个同种对象,需要增加label来标识
	ParamJsonPath       string                  `json:"paramJsonPath,omitempty"`       // .param1.param-sub1
	ObjectLabelSelector map[string]string       `json:"objectDistinctLabel,omitempty"` // 用于区分同一个模板中同一种GVK定义的多个不同对象
	// 对于jsonPath类型参数，处理对象和数组的方式
	AppendArray bool   `json:"appendArray"` // 当JsonPath指向一个数组类型时, 进行替换还是追加
	MapKey      string `json:"mapKey"`      // 当JsonPath指向目标为Map类型时，将在此map中增加一个KV对，此值不为空时表示中增加的KV对中的key
}

type ParamValuesMap

type ParamValuesMap map[string]interface{}

Dynamic param values type

type TemplateDynamicParam

type TemplateDynamicParam struct {
	ParamCode string `json:"paramCode"` // 参数唯一标识，用于模板中引用一个确定的值
	ParamName string `json:"paramName"` // 用户可读的变量名称，易于分辨变量功能
	Brief     string `json:"brief"`     // 参数解释

	FunctionScope      string                `json:"functionScope"` // 作用范围 设定系统参数或用户可自定义
	ParamType          string                `json:"paramType"`     // StrSlot, JsonPath  支持两种动态参数设置方式. 基于字符串替换的StrSlot和自定义JsonPath
	ValueInjectTargets []JsonPathParamTarget `json:"valueInjectTargets"`
	Optional           bool                  `json:"optional"` // 是否为可选参数
	Default            interface{}           `json:"default"`
	Order              int                   `json:"order"` // 顺序参考值，对比同时应用的其他动态参数，值越小越先被执行；仅用于JsonPath类型

	AvailableOptions []interface{} `json:"availableOptions"` // 预设可选值
	Customizable     bool          `json:"customizable"`     // 是否允许用户自定义。为false时仅支持设定AvailableOptions中预设的值
	ValueDataType    string        `json:"dataType"`         // int, string, float, boolean, object, array[string] 当前仅用于类型提示
}

TemplateDynamicParam Defines a dynamic param that referenced by param code in a template. Param values can be referenced by dynamic param definition for multiple times within one template. Multiple dynamic params of different param type may be defined with same ParamCode to reference same param value. Value for StrSlot param must be of type string while value for JsonPath must have correct data type (interface{} to execute yaml/json marshal). StrSlot renderer should accept interface{} value.