ocm-downloadhandlers

Description#

A download handler can be used to process resources to be downloaded from on OCM repository. By default, the blobs provided from the access method (see ocm ocm-accessmethods) are used to store the resource content in the local filesystem. Download handlers can be used to tweak this process. They get access to the blob content and decide on their own what to do with it, or how to transform it into files stored in the file system.

For example, a pre-registered helm download handler will store OCI-based helm artifacts as regular helm archives in the local file system.

Handler Registration#

Programmatically any kind of handlers can be registered for various download conditions. But this feature is available as command-line option, also. New handlers can be provided by plugins. In general available handlers, plugin-based or as part of the CLI coding are nameable using an hierarchical namespace. Those names can be used by a –downloader option to register handlers for various conditions for CLI commands like ocm download resources (implicitly registered download handlers can be enabled using the option -d).

Besides the activation constraints (resource type and media type of the resource blob), it is possible to pass handler configuration controlling the exact behaviour of the handler for selected artifacts.

The following handler names are possible:

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

See Also#