Command: add sources

Usage

ocm add sources [<options>] [<target>] {<resourcefile> | <var>=<value>}

Options

      --access YAML                  blob access specification (YAML)
      --accessHostname string        hostname used for access
      --accessRepository string      repository URL
      --accessType string            type of blob access specification
      --accessVersion string         version for access specification
      --addenv                       access environment for templating
      --bucket string                bucket name
      --commit string                git commit id
      --digest string                blob digest
      --dry-run                      evaluate and print source specifications
      --extra <name>=<value>         source extra identity (default [])
  -F, --file string                  target file/directory (default "component-archive")
      --globalAccess YAML            access specification for global access
  -h, --help                         help for sources
      --hint string                  (repository) hint for local artifacts
      --input YAML                   blob input specification (YAML)
      --inputCompress                compress option for input
      --inputData !bytesBase64       data (string, !!string or !<base64>
      --inputExcludes stringArray    excludes (path) for inputs
      --inputFollowSymlinks          follow symbolic links during archive creation for inputs
      --inputIncludes stringArray    includes (path) for inputs
      --inputLibraries stringArray   library path for inputs
      --inputPath string             path field for input
      --inputPreserveDir             preserve directory in archive for inputs
      --inputText string             utf8 text
      --inputType string             type of blob input specification
      --inputValues YAML             YAML based generic values for inputs
      --inputVariants stringArray    (platform) variants for inputs
      --inputVersion stringArray     version info for inputs
      --label <name>=<YAML>          source label (leading * indicates signature relevant, optional version separated by @)
      --mediaType string             media type for artifact blob representation
      --name string                  source name
  -O, --output string                output file for dry-run
      --reference string             reference name
      --region string                region name
  -s, --settings stringArray         settings file with variable settings (yaml)
      --size int                     blob size
      --source YAML                  source meta data (yaml)
      --templater string             templater to use (go, none, spiff, subst) (default "subst")
      --type string                  source type
      --version string               source version

Description

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

This command accepts source specification files describing the sources to add to a component version. Elements must follow the source meta data description scheme of the component descriptor. Besides referential sources using the access attribute to describe the access method, it is possible to describe local sources fed by local data using the input field (see below).

The description file might contain:

a single source
a list of sources under the key sources
a list of yaml documents with a single source or source list

It is possible to describe a single source via command line options. The meta data of this element is described by the argument of option –source, 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 –source option. (Note: Go templates are not supported for YAML-based option values. Besides this restriction, the finally composed element description is still processd by the selected templater.)

The source type can be specified with the option –type. Therefore, the minimal required meta data for elements can be completely specified by dedicated options and don’t need the YAML option.

To describe the content of this element one of the options –access or –input must be given. They take a YAML or JSON value describing an attribute set, also. The structure of those values is similar to the access or input fields of the description file format.

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 resource specification supports the following blob input types, specified with the field type in the input field:

Input type binary
This blob type is used to provide base64 encoded binary content. The specification supports the following fields:
- data []byte
  The binary data to provide.
- mediaType string
  This OPTIONAL property describes the media type to store with the local blob. The default media type is application/octet-stream and application/gzip if compression is enabled.
- compress bool
  This OPTIONAL property describes whether the content should be stored compressed or not.
Options used to configure fields: –inputCompress, –inputData, –mediaType
Input type dir
The path must denote a directory relative to the resources file, which is packed with tar and optionally compressed if the compress field is set to true. If the field preserveDir is set to true the directory itself is added to the tar. If the field followSymLinks is set to true, symbolic links are not packed but their targets files or folders. With the list fields includeFiles and excludeFiles it is possible to specify which files should be included or excluded. The values are regular expression used to match relative file paths. If no includes are specified all file not explicitly excluded are used.
This blob type specification supports the following fields:
- path string
  This REQUIRED property describes the file path to directory relative to the resource file location.
- mediaType string
  This OPTIONAL property describes the media type to store with the local blob. The default media type is application/x-tar and application/gzip if compression is enabled.
- compress bool
  This OPTIONAL property describes whether the file content should be stored compressed or not.
- preserveDir bool
  This OPTIONAL property describes whether the specified directory with its basename should be included as top level folder.
- followSymlinks bool
  This OPTIONAL property describes whether symbolic links should be followed or included as links.
- excludeFiles list of regex
  This OPTIONAL property describes regular expressions used to match files that should NOT be included in the tar file. It takes precedence over the include match.
- includeFiles list of regex
  This OPTIONAL property describes regular expressions used to match files that should be included in the tar file. If this option is not given all files not explicitly excluded are used.
Options used to configure fields: –inputCompress, –inputExcludes, –inputFollowSymlinks, –inputIncludes, –inputPath, –inputPreserveDir, –mediaType
Input type docker
The path must denote an image tag that can be found in the local docker daemon. The denoted image is packed as OCI artifact set.
This blob type specification supports the following fields:
- path string
  This REQUIRED property describes the image name to import from the local docker daemon.
- repository string
  This OPTIONAL property can be used to specify the repository hint for the generated local artifact access. It is prefixed by the component name if it does not start with slash “/”.
Options used to configure fields: –hint, –inputPath
Input type dockermulti
This input type describes the composition of a multi-platform OCI image. The various variants are taken from the local docker daemon. They should be built with the buildx command for cross platform docker builds. The denoted images, as well as the wrapping image index is packed as OCI artifact set.
This blob type specification supports the following fields:
- variants []string
  This REQUIRED property describes a set of image names to import from the local docker daemon used to compose a resulting image index.
- repository string
  This OPTIONAL property can be used to specify the repository hint for the generated local artifact access. It is prefixed by the component name if it does not start with slash “/”.
Options used to configure fields: –hint, –inputVariants
Input type file
The path must denote a file relative the resources file. The content is compressed if the compress field is set to true.
This blob type specification supports the following fields:
- path string
  This REQUIRED property describes the file path to the helm chart relative to the resource file location.
- mediaType string
  This OPTIONAL property describes the media type to store with the local blob. The default media type is application/octet-stream and application/gzip if compression is enabled.
- compress bool
  This OPTIONAL property describes whether the content should be stored compressed or not.
Options used to configure fields: –inputCompress, –inputPath, –mediaType
Input type helm
The path must denote an helm chart archive or directory relative to the resources file. The denoted chart is packed as an OCI artifact set. Additional provider info is taken from a file with the same name and the suffix .prov.
If the chart should just be stored as archive, please use the type file or dir.
This blob type specification supports the following fields:
- path string
  This REQUIRED property describes the file path to the helm chart relative to the resource file location.
- version string
  This OPTIONAL property can be set to configure an explicit version hint. If not specified the versio from the chart will be used. Basically, it is a good practice to use the component version for local resources This can be achieved by using templating for this attribute in the resource file.
Options used to configure fields: –inputCompress, –inputPath, –inputVersion, –mediaType
Input type ociImage
The path must denote an OCI image reference.
This blob type specification supports the following fields:
- path string
  This REQUIRED property describes the OVI image reference of the image to import.
- repository string
  This OPTIONAL property can be used to specify the repository hint for the generated local artifact access. It is prefixed by the component name if it does not start with slash “/”.
Options used to configure fields: –hint, –inputCompress, –inputPath, –mediaType
Input type spiff
The path must denote a spiff template relative the resources file. The content is compressed if the compress field is set to true.
This blob type specification supports the following fields:
- path string
  This REQUIRED property describes the file path to the helm chart relative to the resource file location.
- mediaType string
  This OPTIONAL property describes the media type to store with the local blob. The default media type is application/octet-stream and application/gzip if compression is enabled.
- compress bool
  This OPTIONAL property describes whether the content should be stored compressed or not.
- values map[string]any
  This OPTIONAL property describes an additional value binding for the template processing. It will be available under the node inputvalues.
- libraries []string
  This OPTIONAL property describes a list of spiff libraries to include in template processing.
The variable settigs from the command line are available as binding, also. They are provided under the node values.
Options used to configure fields: –inputCompress, –inputLibraries, –inputPath, –inputValues, –mediaType
Input type utf8
This blob type is used to provide inline text based content (UTF8). The specification supports the following fields:
- text string
  The utf8 string content to provide.
- mediaType string
  This OPTIONAL property describes the media type to store with the local blob. The default media type is application/octet-stream and application/gzip if compression is enabled.
- compress bool
  This OPTIONAL property describes whether the content should be stored compressed or not.
Options used to configure fields: –inputCompress, –inputText, –mediaType

The following list describes the supported access methods, their versions and specification formats. Typically there is special support for the CLI artifact add commands. The access method specification can be put below the access field. If always requires the field type describing the kind and version shown below.

Access type S3
This method implements the access of a blob stored in an S3 bucket.
The following versions are supported:
- Version v1
  The type specific specification fields are:
  - region (optional) string
    OCI repository reference (this artifact name used to store the blob).
  - bucket string
    The name of the S3 bucket containing the blob
  - key string
    The key of the desired blob
  Options used to configure fields: –accessVersion, –bucket, –mediaType, –reference, –region
Access type gitHub
This method implements the access of the content of a git commit stored in a GitHub repository.
The following versions are supported:
- Version v1
  The type specific specification fields are:
  - repoUrl string
    Repository URL with or without scheme.
  - ref (optional) string
    Original ref used to get the commit from
  - commit string
    The sha/id of the git commit
  Options used to configure fields: –accessHostname, –accessRepository, –commit
Access type localBlob
This method is used to store a resource blob along with the component descriptor on behalf of the hosting OCM repository.
Its implementation is specific to the implementation of OCM repository used to read the component descriptor. Every repository implementation may decide how and where local blobs are stored, but it MUST provide an implementation for this method.
Regardless of the chosen implementation the attribute specification is defined globally the same.
The following versions are supported:
- Version v1
  The type specific specification fields are:
  - localReference string
    Repository type specific location information as string. The value may encode any deep structure, but typically just an access path is sufficient.
  - mediaType string
    The media type of the blob used to store the resource. It may add format information like +tar or +gzip.
  - referenceName (optional) string
    This optional attribute may contain identity information used by other repositories to restore some global access with an identity related to the original source.
    For example, if an OCI artifact originally referenced using the access method ociArtifact is stored during some transport step as local artifact, the reference name can be set to its original repository name. An import step into an OCI based OCM repository may then decide to make this artifact available again as regular OCI artifact.
  - globalAccess (optional) access method specification
    If a resource blob is stored locally, the repository implementation may decide to provide an external access information (independent of the OCM model).
    For example, an OCI artifact stored as local blob can be additionally stored as regular OCI artifact in an OCI registry.
    This additional external access information can be added using a second external access method specification.
  Options used to configure fields: –globalAccess, –hint, –mediaType, –reference
Access type none
dummy resource with no access
Access type ociArtifact
This method implements the access of an OCI artifact stored in an OCI registry.
The following versions are supported:
- Version v1
  The type specific specification fields are:
  - imageReference string
    OCI image/artifact reference following the possible docker schemes:
    - <repo>/<artifact>:<digest>@<tag>
    - [<port>]/<repo path>/<artifact>:<version>@<tag>
  Options used to configure fields: –reference
Access type ociBlob
This method implements the access of an OCI blob stored in an OCI repository.
The following versions are supported:
- Version v1
  The type specific specification fields are:
  - imageReference string
    OCI repository reference (this artifact name used to store the blob).
  - mediaType string
    The media type of the blob
  - digest string
    The digest of the blob used to access the blob in the OCI repository.
  - size integer
    The size of the blob
  Options used to configure fields: –digest, –mediaType, –reference, –size

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


$ ocm add sources --file path/to/cafile sources.yaml

add

clean

create

describe

download

get

show

sign

transfer

verify

OCM Controller

Replication Controller

API Reference

Command: add sources

Usage

Options

Description

Examples

See Also

Command: add sources

Usage #

Options #

Description #

Examples #

See Also #

Usage

Options

Description

Examples

See Also