setters2

package
v0.14.3 Latest Latest
Warning

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

 Go to latest Published: Jun 13, 2023 License: Apache-2.0 Imports: 17 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 K8sCliExtensionKey = "x-k8s-cli"

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

Variables

This section is empty.

Functions

func CheckRequiredSettersSet added in v0.3.3 

func CheckRequiredSettersSet(settersSchema *spec.Schema) error

CheckRequiredSettersSet iterates through all the setter definitions in openAPI schema and returns error if any of the setter has required field true and isSet false

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

func SubstReferringDefinition added in v0.6.1 

func SubstReferringDefinition(definitions *yaml.RNode, key string) string

SubstReferringDefinition check if the definition used in substitution and return the substitution name if true

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

	// ListValues are the value of a list setter.
	ListValues []string

	// Type is the type of the setter value
	Type string

	// Count is the number of fields the setter applies to
	Count int

	SettersSchema *spec.Schema
}

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 # {"$openapi":"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 # {"$openapi":"replicas"}
spec:
  replicas: 3 # {"$openapi":"replicas"}

func (*Add) Filter 

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

Filter implements yaml.Filter

type CliExtension added in v0.2.0 

type CliExtension struct {
	Setter       *setter       `yaml:"setter,omitempty" json:"setter,omitempty"`
	Substitution *substitution `yaml:"substitution,omitempty" json:"substitution,omitempty"`
}

func GetExtFromSchema added in v0.2.0 

func GetExtFromSchema(schema *spec.Schema) (*CliExtension, error)

GetExtFromSchema returns the cliExtension openAPI extension if it is present in schema

type Delete added in v0.3.1 

type Delete struct {
	// Name is the name of the openAPI definition to delete.
	Name string

	// DefinitionPrefix is the prefix of the OpenAPI definition type
	DefinitionPrefix string

	SettersSchema *spec.Schema
}

Delete delete openAPI definition references from resource fields.

func (*Delete) Filter added in v0.3.1 

func (d *Delete) Filter(object *yaml.RNode) (*yaml.RNode, error)

Filter implements yaml.Filter

type DeleterDefinition added in v0.3.1 

type DeleterDefinition struct {
	// Name is the name of the openAPI definition to delete.
	Name string `yaml:"name"`

	// DefinitionPrefix is the prefix of the OpenAPI definition type
	DefinitionPrefix string `yaml:"definitionPrefix"`
}

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

func (DeleterDefinition) DeleteFromFile added in v0.3.1 

func (dd DeleterDefinition) DeleteFromFile(path string) error

func (DeleterDefinition) Filter added in v0.3.1 

func (dd DeleterDefinition) Filter(object *yaml.RNode) (*yaml.RNode, error)

type List 

type List struct {
	Name string

	OpenAPIFileName string

	Setters []SetterDefinition

	Substitutions []SubstitutionDefinition

	SettersSchema *spec.Schema
}

List lists the setters specified in the OpenAPI excludes the subpackages which contain file with name OpenAPIFileName in them

func (*List) ListSetters added in v0.1.10 

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

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

func (*List) ListSubst added in v0.1.10 

func (l *List) ListSubst(openAPIPath string) error

ListSubst initializes l.Substitutions with the substitutions 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

	// SetAll if set to true will set all setters regardless of name
	SetAll bool

	SettersSchema *spec.Schema
}

Set sets resource field values from an OpenAPI setter

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"`

	IsSet bool `yaml:"isSet"`
}

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"`

	// Schema is the openAPI schema for setter constraints.
	Schema string `yaml:"schema,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"`

	// Required indicates that the setter must be set by package consumer before
	// live apply/preview. This field is added to the setter definition to record
	// the package publisher's intent to make the setter required to be set.
	Required bool `yaml:"required,omitempty"`

	// IsSet indicates the specified field has been explicitly assigned.
	IsSet bool `yaml:"isSet,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.