Docs

componentversions

Usage

ocm add componentversions [<options>] [--version <version>] [<ctf archive>] {<component-constructor.yaml>}

Options

      --addenv                    access environment for templating
  -C, --complete                  include all referenced component version
  -L, --copy-local-resources      transfer referenced local resources by-value
  -V, --copy-resources            transfer referenced resources by-value
  -c, --create                    (re)create archive
      --dry-run                   evaluate and print component specifications
  -F, --file string               target file/directory (default "transport-archive")
  -f, --force                     remove existing content
  -h, --help                      help for componentversions
      --lookup stringArray        repository name or spec for closure lookup fallback
  -O, --output string             output file for dry-run
  -R, --replace                   replace existing elements
  -S, --scheme string             schema version (default "v2")
  -s, --settings stringArray      settings file with variable settings (yaml)
      --templater string          templater to use (go, none, spiff, subst) (default "subst")
  -t, --type string               archive format (directory, tar, tgz) (default "directory")
      --uploader <name>=<value>   repository uploader (<name>[:<artifact type>[:<media type>]]=<JSON target config) (default [])
  -v, --version string            default version for components

Description

Add component versions specified by a constructor file to a Common Transport Archive. The archive might be either a directory prepared to host component version content or a tar/tgz file (see option –type).

If option –create is given, the archive is created first. An additional option –force will recreate an empty archive if it already exists.

If option –complete is given all component versions referenced by the added one, will be added, also. Therefore, the –lookup is required to specify an OCM repository to lookup the missing component versions. If additionally the -V is given, the resources of those additional components will be added by value.

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 source, resource and reference list can be composed according to the commands ocm add sources, ocm add resources, ocm add references, respectively.

The description file might contain:

  • a single component as shown in the example
  • a list of components under the key components
  • a list of yaml documents with a single component or component list

The optional field meta.configuredSchemaVersion for a component entry can be used to specify a dedicated serialization format to use for the component descriptor. If given it overrides the –schema option of the command. By default, v2 is used.

Various elements support to add arbitrary information by using labels (see ocm ocm-labels).

The –type option accepts a file format for the target archive to use. It is only evaluated if the target archive does not exist yet. The following formats are supported:

  • directory
  • tar
  • tgz

The default format is directory.

If the option –scheme is given, the specified component descriptor format is used/generated.

The following schema versions are supported for explicit conversions:

  • ocm.software/v3alpha1
  • v2 (default)

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


If a component lookup for building a reference closure is required the –lookup option can be used to specify a fallback lookup repository. By default, the component versions are searched in the repository holding the component version for which the closure is determined. For Component Archives this is never possible, because it only contains a single component version. Therefore, in this scenario this option must always be specified to be able to follow component references.

It the option –copy-resources is given, all referential resources will potentially be localized, mapped to component version local resources in the target repository. It the option –copy-local-resources is given, instead, only resources with the relation local will be transferred. This behaviour can be further influenced by specifying a transfer script with the script option family.

If the –uploader option is specified, appropriate uploader handlers are configured for the operation. It has the following format

<name>:<artifact type>:<media type>=<yaml target config>

The uploader name may be a path expression with the following possibilities:

  • ocm/npmPackage: uploading npm artifacts

    The ocm/npmPackage uploader is able to upload npm artifacts as artifact archive according to the npm package spec. If registered the default mime type is: application/x-tgz

    It accepts a plain string for the URL or a config with the following field: ‘url’: the URL of the npm repository.

  • ocm/mavenPackage: uploading maven artifacts

    The ocm/mavenPackage uploader is able to upload maven artifacts (whole GAV only!) as artifact archive according to the maven artifact spec. If registered the default mime type is: application/x-tgz

    It accepts a plain string for the URL or a config with the following field: ‘url’: the URL of the maven repository.

  • plugin: [downloaders provided by plugins]

    sub namespace of the form <plugin name>/<handler>

  • ocm/ociArtifacts: downloading OCI artifacts

    The ociArtifacts downloader is able to download OCI artifacts as artifact archive according to the OCI distribution spec. The following artifact media types are supported:

    • application/vnd.oci.image.manifest.v1+tar
    • application/vnd.oci.image.manifest.v1+tar+gzip
    • application/vnd.oci.image.index.v1+tar
    • application/vnd.oci.image.index.v1+tar+gzip
    • application/vnd.docker.distribution.manifest.v2+tar
    • application/vnd.docker.distribution.manifest.v2+tar+gzip
    • application/vnd.docker.distribution.manifest.list.v2+tar
    • application/vnd.docker.distribution.manifest.list.v2+tar+gzip

    By default, it is registered for these mimetypes.

    It accepts a config with the following fields:

    • namespacePrefix: a namespace prefix used for the uploaded artifacts
    • ociRef: an OCI repository reference
    • repository: an OCI repository specification for the target OCI registry

    Alternatively, a single string value can be given representing an OCI repository reference.

See ocm ocm-uploadhandlers for further details on using upload handlers.

Examples


$ ocm add componentversions --file ctf --version 1.0 component-constructor.yaml

and a file <code>component-constructor.yaml</code>:

name: ocm.software/demo/test
version: 1.0.0
provider:
  name: ocm.software
  labels:
    - name: city
      value: Karlsruhe
labels:
  - name: purpose
    value: test

resources:
  - name: text
    type: PlainText
    input:
      type: file
      path: testdata
  - name: data
    type: PlainText
    input:
      type: binary
      data: IXN0cmluZ2RhdGE=


The resource <code>text</code> is taken from a file <code>testdata</code> located
next to the description file.

See Also

  • ocm add — Add elements to a component repository or component version
Prev
componentarchive
Next
componentversions