componentversions

Usage#

ocm transfer componentversions [<options>] {<component-reference>} <target>

Options#

  -B, --bom-file string             file name to write the component version BOM
  -c, --constraints constraints     version constraint
  -L, --copy-local-resources        transfer referenced local resources by-value
  -V, --copy-resources              transfer referenced resources by-value
      --copy-sources                transfer referenced sources by-value
      --disable-uploads             disable standard upload handlers for transport
      --enforce                     enforce transport as if target version were not present
  -h, --help                        help for componentversions
      --latest                      restrict component versions to latest
      --lookup stringArray          repository name or spec for closure lookup fallback
      --no-update                   don't touch existing versions in target
  -N, --omit-access-types strings   omit by-value transfer for resource types
  -f, --overwrite                   overwrite existing component versions
  -r, --recursive                   follow component reference nesting
      --repo string                 repository name or spec
      --script string               config name of transfer handler script
  -s, --scriptFile string           filename of transfer handler script
  -E, --stop-on-existing            stop on existing component version in target repository
  -t, --type string                 archive format (directory, tar, tgz) (default "directory")
      --uploader <name>=<value>     repository uploader (<name>[:<artifact type>[:<media type>]]=<JSON target config) (default [])

Description#

Transfer all component versions specified to the given target repository. If only a component (instead of a component version) is specified all versions are transferred.

If the option –constraints is given, and no version is specified for a component, only versions matching the given version constraints (semver https://github.com/Masterminds/semver) are selected. With –latest only the latest matching versions will be selected.

If the –repo option is specified, the given names are interpreted relative to the specified repository using the syntax

<component>[:<version>]

If no –repo option is specified the given names are interpreted as located OCM component version references:

[<repo type>::]<host>[:<port>][/<base path>]//<component>[:<version>]

Additionally there is a variant to denote common transport archives and general repository specifications

[<repo type>::]<filepath>|<spec json>[//<component>[:<version>]]

The –repo option takes an OCM repository specification:

[<repo type>::]<configured name>|<file path>|<spec json>

For the Common Transport Format the types directory, tar or tgz is possible.

Using the JSON variant any repository types supported by the linked library can be used:

Dedicated OCM repository types:

• ComponentArchive: v1

OCI Repository types (using standard component repository to OCI mapping):

• CommonTransportFormat: v1
• OCIRegistry: v1
• oci: v1
• ociRegistry

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.

With the option –recursive the complete reference tree of a component reference is traversed.

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.

If the option –overwrite is given, component versions in the target repository will be overwritten, if they already exist, but with different digest. If the option –enforce is given, component versions in the target repository will be transported as if they were not present on the target side, regardless of their state (this is independent on their actual state, even identical versions are re-transported).

With the option –no-update existing versions in the target repository will not be touched at all. An additional specification of the option –overwrite is ignored. By default, updates of volatile (non-signature-relevant) information is enabled, but the modification of non-volatile data is prohibited unless the overwrite option is given.

If the option –copy-resources is given, all referential resources will potentially be localized, mapped to component version local resources in the target repository. If 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 option –copy-sources is given, all referential sources will potentially be localized, mapped to component version local resources in the target repository. This behaviour can be further influenced by specifying a transfer script with the script option family.

If the option –omit-access-types is given, by-value transfer is omitted completely for the given resource types.

If the option –stop-on-existing is given together with the –recursive option, the recursion is stopped for component versions already existing in the target repository. 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/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.

• 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/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.

• plugin: [downloaders provided by plugins]

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

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

It is possible to use a dedicated transfer script based on spiff. The option –scriptFile can be used to specify this script by a file name. With –script it can be taken from the CLI config using an entry of the following format:

type: scripts.ocm.config.ocm.software
scripts:
  <name>: 
    path: <filepath> 
    script:
      <scriptdata>

Only one of the fields path or script can be used.

If no script option is given and the cli config defines a script default this one is used.

Examples#

$ ocm transfer components -t tgz ghcr.io/mandelsoft/kubelink ctf.tgz
$ ocm transfer components -t tgz --repo OCIRegistry::ghcr.io mandelsoft/kubelink ctf.tgz

See Also#

• ocm transfer — Transfer artifacts or components