Docs

resources

Usage

ocm download resources [<options>]  <component> {<name> { <key>=<value> }}

Options

      --check-verified              enable verification store
  -c, --constraints constraints     version constraint
  -d, --download-handlers           use download handler if possible
      --downloader <name>=<value>   artifact downloader (<name>[:<artifact type>[:<media type>[:<priority>]]]=<JSON target config>) (default [])
  -x, --executable                  download executable for local platform
  -h, --help                        help for resources
      --latest                      restrict component versions to latest
      --lookup stringArray          repository name or spec for closure lookup fallback
  -O, --outfile string              output file or directory
  -r, --recursive                   follow component reference nesting
      --repo string                 repository name or spec
  -t, --type stringArray            resource type filter
      --verified string             file used to remember verifications for downloads (default "~/.ocm/verified")
      --verify                      verify downloads

Description

Download resources of a component version. Resources are specified by identities. An identity consists of a name argument followed by optional <key>=<value> arguments.

The option -O is used to declare the output destination. For a single resource to download, this is the file written for the resource blob. If multiple resources are selected, a directory structure is written into the given directory for every involved component version as follows:

<component>/<version>{/<nested component>/<version>}

The resource files are named according to the resource identity in the component descriptor. If this identity is just the resource name, this name is used. If additional identity attributes are required, this name is append by a comma separated list of <name>=<>value> pairs separated by a “-” from the plain name. This attribute list is alphabetical order:

<resource name>[-[<name>=<>value>]{,<name>=<>value>}]

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

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

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

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

  • helm/artifact: download helm chart resources

    The helm downloader is able to download helm chart resources as helm chart packages. Thus, the downloader may perform transformations. For example, if the helm chart is currently stored as an oci artifact, the downloader performs the necessary extraction to provide the helm chart package from within that oci artifact.

    The following artifact media types are supported:

    • application/vnd.oci.image.manifest.v1+tar+gzip
    • application/vnd.cncf.helm.chart.content.v1.tar+gzip

    It accepts no config.

  • landscaper/blueprint: uploading an OCI artifact to an OCI registry

    The artifact downloader is able to transfer OCI artifact-like resources into an OCI registry given by the combination of the download target and the registration config.

    If no config is given, the target must be an OCI reference with a potentially omitted repository. The repo part is derived from the reference hint provided by the resource’s access specification.

    If the config is given, the target is used as repository name prefixed with an optional repository prefix given by the configuration.

    The following artifact media types are supported:

    • application/vnd.docker.distribution.manifest.v2+tar
    • application/vnd.docker.distribution.manifest.v2+tar+gzip
    • application/vnd.gardener.landscaper.blueprint.layer.v1.tar
    • application/vnd.gardener.landscaper.blueprint.layer.v1.tar+gzip
    • application/vnd.gardener.landscaper.blueprint.v1+tar
    • application/vnd.gardener.landscaper.blueprint.v1+tar+gzip
    • application/vnd.oci.image.manifest.v1+tar
    • application/vnd.oci.image.manifest.v1+tar+gzip
    • application/x-tar
    • application/x-tar+gzip
    • application/x-tgz

    It accepts a config with the following fields:

    • ociConfigTypes: a list of accepted OCI config archive mime types defaulted by application/vnd.gardener.landscaper.blueprint.config.v1.

    This handler is by default registered for the following artifact types: landscaper.gardener.cloud/blueprint,blueprint

  • oci/artifact: downloading an OCI artifact and optionally re-uploading to an OCI registry

    The artifact download resources stored as oci artifact. Furthermore, it allows to specify another OCI registry as download destination, thereby, providing a kind of transfer functionality.

    If no config is given, the target must be an OCI reference with a potentially omitted repository. The repo part is derived from the reference hint provided by the resource’s access specification.

    If the config is given, the target is used as repository name prefixed with an optional repository prefix given by the configuration.

    The following artifact media types are supported:

    • application/vnd.oci.image.manifest.v1+tar+gzip
    • application/vnd.oci.image.index.v1+tar+gzip

    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

  • ocm/dirtree: downloading directory tree-like resources

    The dirtree downloader is able to download directory-tree like resources as directory structure (default) or archive. The following artifact media types are supported:

    • application/vnd.oci.image.manifest.v1+tar+gzip
    • application/x-tgz
    • application/x-tar+gzip
    • application/x-tar

    By default, it is registered for the following resource types:

    • directoryTree
    • filesystem

    It accepts a config with the following fields:

    • asArchive: flag to request an archive download
    • ociConfigTypes: a list of accepted OCI config archive mime types defaulted by application/vnd.oci.image.config.v1+json.

  • plugin: [downloaders provided by plugins]

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

See ocm ocm-downloadhandlers for further details on using download handlers.

The library supports some downloads with semantics based on resource types. For example a helm chart can be download directly as helm chart archive, even if stored as OCI artifact. This is handled by download handler. Their usage can be enabled with the –download-handlers option. Otherwise the resource as returned by the access method is stored.

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 verification store is enabled, resources downloaded from signed or verified component versions are verified against their digests provided by the component version.(not supported for using downloaders for the resource download).

The usage of the verification store is enabled by –check-verified or by specifying a verification file with –verified.

See Also

  • ocm download — Download oci artifacts, resources or complete components
Prev
resources
Next
resources