setters2

package
v0.1.3 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Mar 28, 2020 License: Apache-2.0 Imports: 11 Imported by: 0

Documentation

Overview

Copyright 2019 The Kubernetes Authors. SPDX-License-Identifier: Apache-2.0

Package setters2 contains libraries for setting resource field values from OpenAPI setter extensions.

Setters

Setters are used to programmatically set configuration field values -- e.g. through a cli or ui.

Setters are defined through OpenAPI definitions using the x-k8s-cli extension. Note: additional OpenAPI definitions may be registered through openapi.AddSchema([]byte)

Example OpenAPI schema containing a setter: 

{
  "definitions": {
    "io.k8s.cli.setters.replicas": {
      "x-k8s-cli": {
        "setter": {
          "name": "replicas",
          "value": "4"
        }
      }
    }
  }
}

Setter fields: 

x-k8s-cli.setter.name: name of the setter
x-k8s-cli.setter.value: value of the setter that should be applied to fields

The setter definition key must be of the form "io.k8s.cli.setters.NAME", where NAME matches the value of "x-k8s-cli.setter.name".

When Set.Filter is called, the named setter will have its value applied to all resource fields referencing it.

Fields may reference setters through a yaml comment containing the serialized JSON OpenAPI.

Example Deployment resource with a "spec.replicas" field set by the "replicas" setter: 

apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-deployment
spec:
  replicas: 4 # {"$ref": "#/definitions/io.k8s.cli.setters.replicas"}

If the OpenAPI io.k8s.cli.setters.replicas x-k8s-cli.setter.value was changed from "4" to "5", then calling Set{Name: "replicas"}.Filter(deployment) would update the Deployment spec.replicas value from 4 to 5.

Updated OpenAPI: 

{
  "definitions": {
    "io.k8s.cli.setters.replicas": {
      "x-k8s-cli": {
        "setter": {
          "name": "replicas",
          "value": "5"
        }
      }
    }
  }
}

Updated Deployment Configuration: 

apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-deployment
spec:
  replicas: 5 # {"$ref": "#/definitions/io.k8s.cli.setters.replicas"}

Substitutions

Substitutions are used to programmatically set configuration field values using multiple setters which are substituted into a pattern string.

Substitutions may be used when a field value does not cleanly map to a single setter, but instead matches some string pattern where setters may be substituted in.

Fields may reference substitutions the same way they do setters, however substitutions reference setters from which they are derived.

Example OpenAPI schema containing a substitution derived from 2 setters: 

{
  "definitions": {
    "io.k8s.cli.setters.image-name": {
      "x-k8s-cli": {
        "setter": {
          "name": "image-name",
          "value": "nginx"
        }
      }
    },
    "io.k8s.cli.setters.image-tag": {
      "x-k8s-cli": {
        "setter": {
          "name": "image-tag",
          "value": "1.8.1"
        }
      }
    },
    "io.k8s.cli.substitutions.image-name-tag": {
      "x-k8s-cli": {
        "substitution": {
          "name": "image-name-tag",
          "pattern": "IMAGE_NAME:IMAGE_TAG",
          "values": [
              {"marker": "IMAGE_NAME", "ref": "#/definitions/io.k8s.cli.setters.image-name"}
              {"marker": "IMAGE_TAG", "ref": "#/definitions/io.k8s.cli.setters.image-tag"}
          ]
        }
      }
    }
  }
}

Substitution Fields. 

x-k8s-cli.substitution.name: name of the substitution
x-k8s-cli.substitution.pattern: string pattern to substitute markers into
x-k8s-cli.substitution.values.marker: the marker substring within pattern to replace
x-k8s-cli.substitution.values.ref: the setter ref containing the value to replace the marker with

The substitution is composed of a "pattern" containing markers, and a list of setter "values" which are substituted into the markers.

Example Deployment with substitution: 

apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-deployment
spec:
  template:
    spec:
      containers:
      - name: nginx
        image: nginx:1.8.1 # {"$ref": "#/definitions/io.k8s.cli.substitutions.image-name-tag"}

spec.template.spec.containers[name=nginx].image is set by the "image" substitution any time either "image-name" or "image-tag" is set. Whenever any setter referenced by a substitution is set, the substitution will be recalculated by substituting its values into its pattern.

If the OpenAPI io.k8s.cli.setters.image-name x-k8s-cli.setter.value was changed from "1.8.1" to "1.8.2", then calling either Set{Name: "image-name"}.Filter(deployment) or Set{Name: "image-tag"}.Filter(deployment) would update the Deployment field spec.template.spec.container[name=nginx].image from "nginx:1.8.1" to "nginx:1.8.2".

Adding Field References

References to setters and substitutions may be added to fields using the Add Filter. Add will write a JSON OpenAPI string as a comment to any fields matching the specified FieldName add FieldValue.

Index

Examples

Constants

View Source 
const (
	// CLIDefinitionsPrefix is the prefix for cli definition keys.
	CLIDefinitionsPrefix = "io.k8s.cli."

	// SetterDefinitionPrefix is the prefix for setter definition keys.
	SetterDefinitionPrefix = CLIDefinitionsPrefix + "setters."

	// SubstitutionDefinitionPrefix is the prefix for substitution definition keys.
	SubstitutionDefinitionPrefix = CLIDefinitionsPrefix + "substitutions."

	// DefinitionsPrefix is the prefix used to reference definitions in the OpenAPI
	DefinitionsPrefix = "#/definitions/"
)
View Source 
const K8sCliExtensionKey = "x-k8s-cli"

K8sCliExtensionKey is the name of the OpenAPI field containing the setter extensions

Variables

This section is empty.

Functions

func SetAll added in v0.1.2 

func SetAll(s *Set) kio.Filter

SetAll applies the set filter for all yaml nodes and only returns the nodes whose corresponding file has at least one node with input setter

Types

type Add 

type Add struct {
	// FieldValue if set will add the OpenAPI reference to fields if they have this value.
	// Optional.  If unspecified match all field values.
	FieldValue string

	// FieldName if set will add the OpenAPI reference to fields with this name or path
	// FieldName may be the full name of the field, full path to the field, or the path suffix.
	// e.g. all of the following would match spec.template.spec.containers.image --
	// [image, containers.image, spec.containers.image, template.spec.containers.image,
	//  spec.template.spec.containers.image]
	// Optional.  If unspecified match all field names.
	FieldName string

	// Ref is the OpenAPI reference to set on the matching fields as a comment.
	Ref string
}

Add creates or updates setter or substitution references from resource fields. Requires that at least one of FieldValue and FieldName have been set.

Example (FieldName)

ExampleAdd demonstrates adding a setter reference to fields. 

deployment := `
apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-deployment
  annotations:
    something: 3
spec:
  replicas: 3
`

object := yaml.MustParse(deployment) // parse the configuration
err := object.PipeE(&Add{
	Ref:       "#/definitions/io.k8s.cli.setters.replicas",
	FieldName: "replicas",
})
if err != nil {
	panic(err)
}

// Print the object with the update value
fmt.Println(object.MustString())

Output:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-deployment
  annotations:
    something: 3
spec:
  replicas: 3 # {"$ref":"#/definitions/io.k8s.cli.setters.replicas"}
Example (FieldValue)

ExampleAdd demonstrates adding a setter reference to fields. 

deployment := `
apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-deployment
  annotations:
    something: 3
spec:
  replicas: 3
`

object := yaml.MustParse(deployment) // parse the configuration
err := object.PipeE(&Add{
	Ref:        "#/definitions/io.k8s.cli.setters.replicas",
	FieldValue: "3",
})
if err != nil {
	panic(err)
}

// Print the object with the update value
fmt.Println(object.MustString())

Output:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-deployment
  annotations:
    something: 3 # {"$ref":"#/definitions/io.k8s.cli.setters.replicas"}
spec:
  replicas: 3 # {"$ref":"#/definitions/io.k8s.cli.setters.replicas"}

func (*Add) Filter 

func (a *Add) Filter(object *yaml.RNode) (*yaml.RNode, error)

Filter implements yaml.Filter

type List 

type List struct {
	Name string

	Setters []SetterDefinition
}

List lists the setters specified in the OpenAPI

func (*List) List 

func (l *List) List(openAPIPath, resourcePath string) error

List initializes l.Setters with the setters from the OpenAPI definitions in the file

type Set 

type Set struct {
	// Name is the name of the setter to set on the object.  i.e. matches the x-k8s-cli.setter.name
	// of the setter that should have its value applied to fields which reference it.
	Name string

	// Count is the number of fields that were updated by calling Filter
	Count int
}

Set sets resource field values from an OpenAPI setter

Example

ExampleSet demonstrates using Set to replace the current field value in an object 

openapi.ResetOpenAPI()

// OpenAPI definitions with setter extensions on definitions
schema := `
{
  "definitions": {
    "io.k8s.cli.setters.replicas": {
      "x-k8s-cli": {
        "setter": {
          "name": "replicas",
          "value": "4"
        }
      }
    }
  }
}
`
// Resource with field referencing OpenAPI definition
deployment := `
apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-deployment
spec:
  replicas: 3 # {"$ref": "#/definitions/io.k8s.cli.setters.replicas"}
`
_, err := openapi.AddSchema([]byte(schema)) // add the schema definitions
if err != nil {
	panic(err)
}
object := yaml.MustParse(deployment)       // parse the configuration
err = object.PipeE(&Set{Name: "replicas"}) // set replicas from the setter
if err != nil {
	panic(err)
}

fmt.Println(object.MustString())

Output:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-deployment
spec:
  replicas: 4 # {"$ref": "#/definitions/io.k8s.cli.setters.replicas"}
Example (Substitution)

ExampleSet_Substitution demonstrates using Set to substitute a value into the field of an object. Only part of the field value is modified. 

openapi.ResetOpenAPI()

// set the version setter
schema := `
{
  "definitions": {
    "io.k8s.cli.setters.version": {
      "x-k8s-cli": {
        "setter": {
          "name": "version",
          "value": "1.8.1"
        }
      }
    },
    "io.k8s.cli.substitutions.image": {
      "x-k8s-cli": {
        "substitution": {
          "name": "image",
          "pattern": "nginx:VERSION",
          "values": [
            {"marker": "VERSION", "ref": "#/definitions/io.k8s.cli.setters.version"}
          ]
        }
      }
    }
  }
}`

deployment := `
apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-deployment
spec:
  template:
    spec:
      containers:
      - name: nginx
        image: nginx:1.7.9 # {"$ref": "#/definitions/io.k8s.cli.substitutions.image"}
`

_, err := openapi.AddSchema([]byte(schema)) // add the schema definitions
if err != nil {
	panic(err)
}
object := yaml.MustParse(deployment)      // parse the configuration
err = object.PipeE(&Set{Name: "version"}) // set replicas from the setter
if err != nil {
	panic(err)
}

// Print the object with the update value
fmt.Println(object.MustString())

Output:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-deployment
spec:
  template:
    spec:
      containers:
      - name: nginx
        image: nginx:1.8.1 # {"$ref": "#/definitions/io.k8s.cli.substitutions.image"}

func (*Set) Filter 

func (s *Set) Filter(object *yaml.RNode) (*yaml.RNode, error)

Filter implements Set as a yaml.Filter

type SetOpenAPI 

type SetOpenAPI struct {
	// Name is the name of the setter to add
	Name string `yaml:"name"`
	// Value is the current value of the setter
	Value string `yaml:"value"`

	// ListValue is the current value for a list of items
	ListValues []string `yaml:"listValue"`

	Description string `yaml:"description"`

	SetBy string `yaml:"setBy"`
}

SetOpenAPI updates a setter value

func (SetOpenAPI) Filter 

func (s SetOpenAPI) Filter(object *yaml.RNode) (*yaml.RNode, error)

func (SetOpenAPI) UpdateFile 

func (s SetOpenAPI) UpdateFile(path string) error

UpdateFile updates the OpenAPI definitions in a file with the given setter value.

type SetterDefinition 

type SetterDefinition struct {
	// Name is the name of the setter to create or update.
	Name string `yaml:"name"`

	// Value is the value of the setter.
	Value string `yaml:"value"`

	// ListValues are the value of a list setter.
	ListValues []string `yaml:"listValues,omitempty"`

	// SetBy is the person or role that last set the value.
	SetBy string `yaml:"setBy,omitempty"`

	// Description is a description of the value.
	Description string `yaml:"description,omitempty"`

	// Count is the number of fields set by this setter.
	Count int `yaml:"count,omitempty"`

	// Type is the type of the setter value.
	Type string `yaml:"type,omitempty"`

	// EnumValues is a map of possible setter values to actual field values.
	// If EnumValues is specified, then the value set the by user 1) MUST
	// be present in the enumValues map as a key, and 2) the map entry value
	// MUST be used as the value to set in the configuration (rather than the key)
	// Example -- may be used for t-shirt sizing values by allowing cpu to be
	// set to small, medium or large, and then mapping these values to cpu values -- 0.5, 2, 8
	EnumValues map[string]string `yaml:"enumValues,omitempty"`
}

SetterDefinition may be used to update a files OpenAPI definitions with a new setter.

func (SetterDefinition) AddToFile 

func (sd SetterDefinition) AddToFile(path string) error

func (SetterDefinition) Filter 

func (sd SetterDefinition) Filter(object *yaml.RNode) (*yaml.RNode, error)

type SubstitutionDefinition 

type SubstitutionDefinition struct {
	// Name is the name of the substitution to create or update
	Name string `yaml:"name"`

	// Pattern is the substitution pattern into which setter values are substituted
	Pattern string `yaml:"pattern"`

	// Values are setters which are substituted into pattern to produce a field value
	Values []Value `yaml:"values"`
}

SetterDefinition may be used to update a files OpenAPI definitions with a new substitution.

func (SubstitutionDefinition) AddToFile 

func (sd SubstitutionDefinition) AddToFile(path string) error

func (SubstitutionDefinition) Filter 

func (sd SubstitutionDefinition) Filter(object *yaml.RNode) (*yaml.RNode, error)

type Value 

type Value struct {
	// Marker is the string marker in pattern that is replace by the referenced setter.
	Marker string `yaml:"marker"`

	// Ref is a reference to a setter to pull the replacement value from.
	Ref string `yaml:"ref"`
}

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.