references

Usage#

ocm add references [<options>] [<target>] {<referencefile> | <var>=<value>}

Options#

      --addenv                 access environment for templating
      --component string       component name
      --dry-run                evaluate and print reference specifications
      --extra <name>=<value>   reference extra identity (default [])
  -F, --file string            target file/directory (default "component-archive")
  -h, --help                   help for references
      --label <name>=<YAML>    reference label (leading * indicates signature relevant, optional version separated by @)
      --name string            reference name
  -O, --output string          output file for dry-run
  -P, --preserve-signature     preserve existing signatures
      --reference YAML         reference meta data (yaml)
  -R, --replace                replace existing elements
  -s, --settings stringArray   settings file with variable settings (yaml)
      --templater string       templater to use (go, none, spiff, subst) (default "subst")
      --version string         reference version

Description#

Add aggregation information specified in a reference file to a component version. So far only component archives are supported as target.

This command accepts reference specification files describing the references to add to a component version. Elements must follow the reference meta data description scheme of the component descriptor.

The description file might contain:

• a single reference
• a list of references under the key references
• a list of yaml documents with a single reference or reference list

It is possible to describe a single reference via command line options. The meta data of this element is described by the argument of option –reference, which must be a YAML or JSON string. Alternatively, the name and version can be specified with the options –name and –version. With the option –extra it is possible to add extra identity attributes. Explicitly specified options override values specified by the –reference option. (Note: Go templates are not supported for YAML-based option values. Besides this restriction, the finally composed element description is still processed by the selected template engine.)

The component name can be specified with the option –component. Therefore, basic references not requiring any additional labels or extra identities can just be specified by those simple value options without the need for the YAML option.

All yaml/json defined resources can be templated. Variables are specified as regular arguments following the syntax <name>=<value>. Additionally settings can be specified by a yaml file using the –settings option. With the option –addenv environment variables are added to the binding. Values are overwritten in the order environment, settings file, command line settings.

Note: Variable names are case-sensitive.

Example:

<command> <options> -- MY_VAL=test <args>

There are several templaters that can be selected by the –templater option:

• go go templating supports complex values.

    key:
      subkey: "abc {{.MY_VAL}}"
  

• none do not do any substitution.

• spiff spiff templating.

  It supports complex values. the settings are accessible using the binding values.

    key:
      subkey: "abc (( values.MY_VAL ))"
  

• subst simple value substitution with the drone/envsubst templater.

  It supports string values, only. Complex settings will be json encoded.

    key:
      subkey: "abc ${MY_VAL}"
  

The –replace option allows users to specify whether adding an element with the same name and extra identity but different version as an existing element, append (false) or replace (true) the existing element.

The –preserve-signature option prohibits changes of signature relevant elements.

All yaml/json defined resources can be templated. Variables are specified as regular arguments following the syntax <name>=<value>. Additionally settings can be specified by a yaml file using the –settings option. With the option –addenv environment variables are added to the binding. Values are overwritten in the order environment, settings file, command line settings.

Note: Variable names are case-sensitive.

Example:

<command> <options> -- MY_VAL=test <args>

There are several templaters that can be selected by the –templater option:

• go go templating supports complex values.

    key:
      subkey: "abc {{.MY_VAL}}"
  

• none do not do any substitution.

• spiff spiff templating.

  It supports complex values. the settings are accessible using the binding values.

    key:
      subkey: "abc (( values.MY_VAL ))"
  

• subst simple value substitution with the drone/envsubst templater.

  It supports string values, only. Complex settings will be json encoded.

    key:
      subkey: "abc ${MY_VAL}"
  

Examples#

Add a reference directly by options
$ ocm add references --file path/to/ca --name myref --component github.com/my/component --version ${VERSION}

Add a reference by a description file:

*references.yaml*:
---
name: myref
component: github.com/my/component
version: ${VERSION]
$ ocm add references  path/to/ca  references.yaml VERSION=1.0.0

See Also#

• ocm add — Add elements to a component repository or component version