localize

README

Localization Tools

This package (pkg/contexts/ocm/util/localize) contains some yaml format definitions, (format.go) given by a Go structure. and functions usable for the modification of filesystem snapshots.

It covers

• OCM based localization descriptions used to describe image location substitution and the
• merging with configuration input.

This mechanism is intended to support the mapping of generic filesystem snapshots containing deployment descriptions or manifests to an installation specific snapshot incorporating the local location of container images based on OCM component versions and installation specific configuration values.

The description format describes two basic specifications that incorporate external information provided by a component version or some user config.

• struct/format Localization describe a specification to inject/modify image locations based on the information provided by a component version. The substitution descriptions use relative resources references to specify the resource whose image reference is used as basis for the substituted value.

  This specification is intended to be stored as part of a resource artifact in a component version which is then used to apply it. Thereby the contained relative resource reference are evaluated against the component version containing the specification to resolve the final image location.

• struct/format Configuration describes a specification for applying a dedicated config value taken from a configuration source to a filesytem snapshot.

The function Localize and Configure accept a list of such specifications and map them into an environment agnostic set of Substitution specifications, which contain resolved data values, only. A third function Substitute takes those environment agnostic specifications and apply them to a filesystem.

Finally, a compound specification InstantiationRules is provided, that combines all those descriptions with the specification of the snapshot resource and further helper parts, like json scheme validation for config files.

Such a specification object can be applied by the function Instantiate together with configuration values to a component version. As substitution result it returns a virtual filesystem with the snapshot according to the resolved substitutions. To get access to the template resource containing the filesystem snapshot to be instantiated, the configured downloaders (package pkg/context/ocm/download) is used. Therefore, this method can be used together with any own resource type as long as an appropriate downloader is configured.

Additionally, there is a set of more basic types and methods, which can be used to describe end execute localizations for single data objects (see ImageMappings, LocalizeMappings and SubstituteMappings).

Documentation

Index

• func Instantiate(rules *InstantiationRules, cv ocm.ComponentVersionAccess, ...) error
• func Substitute(subs Substitutions, fs vfs.FileSystem) error
• func SubstituteMappings(subs ValueMappings, target subst.SubstitutionTarget) error
• func SubstituteMappingsForData(subs ValueMappings, data []byte) ([]byte, error)
• type Configuration
• type ImageMapping
  • func (m *ImageMapping) Evaluate(idx int, cv ocm.ComponentVersionAccess, resolver ocm.ComponentVersionResolver) (ValueMappings, error)
• type ImageMappings
• type InstantiationRules
• type Localization
• type Substitution
  • func (s *Substitution) GetValue() (interface{}, error)
• type Substitutions
  • func Configure(mappings []Configuration, cursubst []Substitution, ...) (Substitutions, error)
  • func Localize(mappings []Localization, cv ocm.ComponentVersionAccess, ...) (Substitutions, error)
  • func (s *Substitutions) Add(name, file, path string, value interface{}) error
  • func (s *Substitutions) AddValueMapping(m *ValueMapping, file string)
• type ValueMapping
  • func NewValueMapping(name, path string, value interface{}) (*ValueMapping, error)
• type ValueMappings
  • func LocalizeMappings(mappings ImageMappings, cv ocm.ComponentVersionAccess, ...) (ValueMappings, error)
  • func (s *ValueMappings) Add(name, path string, value interface{}) error

Functions

func Instantiate

func Instantiate(rules *InstantiationRules, cv ocm.ComponentVersionAccess, resolver ocm.ComponentVersionResolver, config []byte, fs vfs.FileSystem, types ...string) error

func Substitute

func Substitute(subs Substitutions, fs vfs.FileSystem) error

func SubstituteMappings

func SubstituteMappings(subs ValueMappings, target subst.SubstitutionTarget) error

SubstituteMappings substitutes value mappings for a dedicated substitution target.

func SubstituteMappingsForData

func SubstituteMappingsForData(subs ValueMappings, data []byte) ([]byte, error)

SubstituteMappingsForData substitutes value mappings for some data.

Types

type Configuration

type Configuration Substitution

Configuration is a request to substitute a configuration value. The specification describes substitution targets given by the file path and the YAML/JSON value paths of the elements in this file. The substitution value is calculated by the value expression (spiff) based on given config data. It has the same structure as Substitution, but is a request based on external configuration data, while a Substitution describes a fixed target value.

type ImageMapping

type ImageMapping struct {
	// The optional but unique(!) name of the mapping to support referencing mapping entries
	Name string `json:"name,omitempty"`

	// The resource reference used to resolve the substitution
	v1.ResourceReference `json:",inline"`

	// Path in target to substitute by the image tag/digest
	Tag string `json:"tag,omitempty"`
	// Path in target to substitute the image repository
	Repository string `json:"repository,omitempty"`
	// Path in target to substitute the complete image
	Image string `json:"image,omitempty"`
}

ImageMapping describes a dedicated substitution of parts of container image names based on a relative OCM resource reference.

func (*ImageMapping) Evaluate

func (m *ImageMapping) Evaluate(idx int, cv ocm.ComponentVersionAccess, resolver ocm.ComponentVersionResolver) (ValueMappings, error)

type ImageMappings

type ImageMappings []ImageMapping

type InstantiationRules

type InstantiationRules struct {
	Template          v1.ResourceReference   `json:"templateResource,omitempty"`
	LocalizationRules []Localization         `json:"localizationRules,omitempty"`
	ConfigRules       []Configuration        `json:"configRules,omitempty"`
	ConfigScheme      json.RawMessage        `json:"configScheme,omitempty"`
	ConfigTemplate    json.RawMessage        `json:"configTemplate,omitempty"`
	ConfigLibraries   []v1.ResourceReference `json:"configLibraries,omitempty"`
}

InstantiationRules bundle the localization of a filesystem resource covering image localization and applying instance configuration.

type Localization

type Localization struct {
	// The path of the file for the substitution
	FilePath string `json:"file"`
	// The image mapping request
	ImageMapping `json:",inline"`
}

Localization is a request to substitute an image location. The specification describes substitution targets given by the file path and the YAML/JSON value paths of the elements in this file. The substitution value is calculated from the access specification of the given resource provided by the actual component version.

type Substitution

type Substitution struct {
	// The path of the file for the substitution
	FilePath string `json:"file"`
	// The field mapping toapply to given file path
	ValueMapping `json:",inline"`
}

Substitution is a request to substitute the YAML/JSON element given by the value path in the given file path by the given direct value.

func (*Substitution) GetValue

func (s *Substitution) GetValue() (interface{}, error)

type Substitutions

type Substitutions []Substitution

func Configure

func Configure(
	mappings []Configuration, cursubst []Substitution,
	cv ocm.ComponentVersionAccess, resolver ocm.ComponentVersionResolver,
	template []byte, config []byte, libraries []metav1.ResourceReference, schemedata []byte,
) (Substitutions, error)

func Localize

func Localize(mappings []Localization, cv ocm.ComponentVersionAccess, resolver ocm.ComponentVersionResolver) (Substitutions, error)

Localize maps a list of filesystem related localization requests to an appropriate set of substitution requests.

func (*Substitutions) Add

func (s *Substitutions) Add(name, file, path string, value interface{}) error

func (*Substitutions) AddValueMapping

func (s *Substitutions) AddValueMapping(m *ValueMapping, file string)

type ValueMapping

type ValueMapping struct {
	// The optional but unique(!) name of the mapping to support referencing mapping entries
	Name string `json:"name,omitempty"`
	// The target path for the value substitution
	ValuePath string `json:"path"`
	// The value to set
	Value json.RawMessage `json:"value"`
}

func NewValueMapping

func NewValueMapping(name, path string, value interface{}) (*ValueMapping, error)

type ValueMappings

type ValueMappings []ValueMapping

func LocalizeMappings

func LocalizeMappings(mappings ImageMappings, cv ocm.ComponentVersionAccess, resolver ocm.ComponentVersionResolver) (ValueMappings, error)

LocalizeMappings maps a set of pure image mappings into an appropriate set of value mapping request for a single data object.

func (*ValueMappings) Add

func (s *ValueMappings) Add(name, path string, value interface{}) error