sources

Usage

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

Options

      --access YAML                         blob access specification (YAML)
      --accessComponent string              component for access specification
      --accessHostname string               hostname used for access
      --accessRepository string             repository or registry URL
      --accessType string                   type of blob access specification
      --accessVersion string                version for access specification
      --addenv                              access environment for templating
      --artifactId string                   maven artifact id
      --body string                         body of a http request
      --bucket string                       bucket name
      --classifier string                   maven classifier
      --commit string                       git commit id
      --digest string                       blob digest
      --dry-run                             evaluate and print source specifications
      --extension string                    maven extension name
      --extra <name>=<value>                source extra identity (default [])
  -F, --file string                         target file/directory (default "component-archive")
      --globalAccess YAML                   access specification for global access
      --groupId string                      maven group id
      --header <name>:<value>,<value>,...   http headers (default {})
  -h, --help                                help for sources
      --hint string                         (repository) hint for local artifacts
      --identityPath {<name>=<value>}       identity path for specification
      --input YAML                          blob input specification (YAML)
      --inputComponent string               component name
      --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
      --inputFormattedJson YAML             JSON formatted text
      --inputHelmRepository string          helm repository base URL
      --inputIncludes stringArray           includes (path) for inputs
      --inputJson YAML                      JSON formatted text
      --inputLibraries stringArray          library path for inputs
      --inputPath filepath                  path field for input
      --inputPlatforms stringArray          input filter for image platforms ([os]/[architecture])
      --inputPreserveDir                    preserve directory in archive for inputs
      --inputRepository string              repository or registry 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 string                 version info for inputs
      --inputYaml YAML                      YAML formatted text
      --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
      --noredirect                          http redirect behavior
  -O, --output string                       output file for dry-run
      --package string                      package or object name
      --reference string                    reference name
      --region string                       region name
  -R, --replace                             replace existing elements
  -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
      --url string                          artifact or server url
      --verb string                         http request method
      --version string                      source version

Description

Add information about the sources, e.g. commits in a Github repository, that have been used to create the resources 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 processed by the selected template engine.)

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. The OCI image will contain an informational back link to the component version using the manifest annotation software.ocm/component-version.
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 (see https://ocm.software/docs/tutorials/best-practices/#building-multi-architecture-images). The denoted images, as well as the wrapping image index, are packed as OCI artifact set. They will contain an informational back link to the component version using the manifest annotation software.ocm/component-version.
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 path to the file 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 or a chart name in a helm chart repository. The denoted chart is packed as an OCI artifact set. For the filesystem version additional provider info is taken from a file with the same name and the suffix .prov.
If the chart should just be stored as plain archive, please use the type file or dir, instead.
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 version 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.
- helmRepository string
  This OPTIONAL property can be set, if the helm chart should be loaded from a helm repository instead of the local filesystem. It describes the base URL of the chart repository. If specified, the path field must describe the name of the chart in the chart repository, and version must describe the version of the chart imported from the chart repository
- 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 “/”.
- caCertFile string
  This OPTIONAL property can be used to specify a relative filename for the TLS root certificate used to access a helm repository.
- caCert string
  This OPTIONAL property can be used to specify a TLS root certificate used to access a helm repository.
Options used to configure fields: –hint, –inputCompress, –inputHelmRepository, –inputPath, –inputVersion, –mediaType
Input type maven
The repoUrl is the url pointing either to the http endpoint of a maven repository (e.g. https://repo.maven.apache.org/maven2/) or to a file system based maven repository (e.g. file://local/directory).
This blob type specification supports the following fields:
- repoUrl string
  This REQUIRED property describes the url from which the resource is to be accessed.
- groupId string
  This REQUIRED property describes the groupId of a maven artifact.
- artifactId string
  This REQUIRED property describes artifactId of a maven artifact.
- version string
  This REQUIRED property describes the version of a maven artifact.
- classifier string
  This OPTIONAL property describes the classifier of a maven artifact.
- extension string
  This OPTIONAL property describes the extension of a maven artifact.
Options used to configure fields: –artifactId, –classifier, –extension, –groupId, –inputPath, –inputVersion, –url
Input type npm
The registry is the url pointing to the npm registry from which a resource is downloaded.
This blob type specification supports the following fields:
- registry string
  This REQUIRED property describes the url from which the resource is to be downloaded.
- package string
  This REQUIRED property describes the name of the package to download.
- version string
  This is an OPTIONAL property describing the version of the package to download. If not defined, latest will be used automatically.
Options used to configure fields: –inputRepository, –inputVersion, –package
Input type ociArtifact
This input type is used to import an OCI image from an OCI registry. If it is a multi-arch image the set of platforms to be imported can be filtered using the “platforms” attribute. The path must denote an OCI image reference.
This blob type specification supports the following fields:
- path string
  This REQUIRED property describes the OCI 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 “/”.
- platforms []string
  This OPTIONAL property can be used to filter index artifacts to include only images for dedicated operating systems/architectures. Elements must meet the syntax [<os>]/[<architecture>].
Options used to configure fields: –hint, –inputCompress, –inputPath, –inputPlatforms, –mediaType
Input type ociImage
DEPRECATED: This type is deprecated, please use ociArtifact instead.
Options used to configure fields: –hint, –inputCompress, –inputPath, –inputPlatforms, –mediaType
Input type ocm
This input type allows to get a resource artifact from an OCM repository.
This blob type specification supports the following fields:
- ocmRepository repository specification
  This REQUIRED property describes the OCM repository specification
- component string
  This REQUIRED property describes the component na,e
- version string
  This REQUIRED property describes the version of a maven artifact.
- resourceRef relative resource reference
  This REQUIRED property describes the resource reference for the desired resource relative to the given component version .
Options used to configure fields: –identityPath, –inputComponent, –inputRepository, –inputVersion
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 path to the file 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 settings 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.
- json JSON or JSON string interpreted as JSON
  The content emitted as JSON.
- formattedJson YAML/JSON or JSON/YAML string interpreted as JSON
  The content emitted as formatted JSON.
- yaml AML/JSON or JSON/YAML string interpreted as YAML
  The content emitted as YAML.
- 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, –inputFormattedJson, –inputJson, –inputText, –inputYaml, –mediaType
Input type wget
The url is the url pointing to the http endpoint from which a resource is downloaded. The mimeType can be used to specify the MIME type of the resource.
This blob type specification supports the following fields:
- url string
  This REQUIRED property describes the url from which the resource is to be downloaded.
- mediaType string
  This OPTIONAL property describes the media type of the resource to be downloaded. If omitted, ocm tries to read the mediaType from the Content-Type header of the http response. If the mediaType cannot be set from the Content-Type header as well, ocm tries to deduct the mediaType from the URL. If that is not possible either, the default media type is defaulted to application/octet-stream.
- header map[string][]string
  This OPTIONAL property describes the http headers to be set in the http request to the server.
- verb string
  This OPTIONAL property describes the http verb (also known as http request method) for the http request. If omitted, the http verb is defaulted to GET.
- body []byte
  This OPTIONAL property describes the http body to be included in the request.
- noredirect bool
  This OPTIONAL property describes whether http redirects should be disabled. If omitted, it is defaulted to false (so, per default, redirects are enabled).
Options used to configure fields: –body, –header, –mediaType, –noredirect, –url, –verb

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 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 helm
This method implements the access of a Helm chart stored in a Helm repository.
The following versions are supported:
- Version v1
  The type specific specification fields are:
  - helmRepository string
    Helm repository URL.
  - helmChart string
    The name of the Helm chart and its version separated by a colon.
  - version string
    The version of the Helm chart if not specified as part of the chart name.
  - caCert string
    An optional TLS root certificate.
  - keyring string
    An optional keyring used to verify the chart.
  It uses the consumer identity type HelmChartRepository with the fields for a hostpath identity matcher (see ocm get credentials).
Options used to configure fields: –accessRepository, –accessVersion, –package
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 maven
This method implements the access of a Maven artifact in a Maven repository.
The following versions are supported:
- Version v1
  The type specific specification fields are:
  - repoUrl string
    URL of the Maven repository
  - groupId string
    The groupId of the Maven artifact
  - artifactId string
    The artifactId of the Maven artifact
  - version string
    The version name of the Maven artifact
  - classifier string
    The optional classifier of the Maven artifact
  - extension string
    The optional extension of the Maven artifact
Options used to configure fields: –accessRepository, –accessVersion, –artifactId, –classifier, –extension, –groupId
Access type none
dummy resource with no access
Access type npm
This method implements the access of an NPM package in an NPM registry.
The following versions are supported:
- Version v1
  The type specific specification fields are:
  - registry string
    Base URL of the NPM registry.
  - package string
    The name of the NPM package
  - version string
    The version name of the NPM package
Options used to configure fields: –accessRepository, –accessVersion, –package
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
Access type ocm
This method implements the access of any resource artifact stored in an OCM repository. Only repository types supporting remote access should be used.
The following versions are supported:
- Version v1
  The type specific specification fields are:
  - ocmRepository json
    The repository spec for the OCM repository
  - component string
    (Optional) The name of the component. The default is the own component.
  - version string
    (Optional) The version of the component. The default is the own component version.
  - resourceRef relative resource ref
    The resource reference of the denoted resource relative to the given component version.
  It uses the consumer identity and credentials for the intermediate repositories and the final resource access.
Options used to configure fields: –accessComponent, –accessRepository, –accessVersion, –identityPath
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
  - version (optional) string
    The key of the desired blob
  - mediaType (optional) string
    The media type of the content
- Version v2
  The type specific specification fields are:
  - region (optional) string
    OCI repository reference (this artifact name used to store the blob).
  - bucketName string
    The name of the S3 bucket containing the blob
  - objectKey string
    The key of the desired blob
  - version (optional) string
    The key of the desired blob
  - mediaType (optional) string
    The media type of the content
Options used to configure fields: –accessVersion, –bucket, –mediaType, –reference, –region
Access type wget
This method implements access to resources stored on an http server.
The following versions are supported:
- Version v1
  The url is the url pointing to the http endpoint from which a resource is downloaded. The mimeType can be used to specify the MIME type of the resource.
  This blob type specification supports the following fields:
  - url string
  This REQUIRED property describes the url from which the resource is to be downloaded.
  - mediaType string
  This OPTIONAL property describes the media type of the resource to be downloaded. If omitted, ocm tries to read the mediaType from the Content-Type header of the http response. If the mediaType cannot be set from the Content-Type header as well, ocm tries to deduct the mediaType from the URL. If that is not possible either, the default media type is defaulted to application/octet-stream.
  - header map[string][]string
  This OPTIONAL property describes the http headers to be set in the http request to the server.
  - verb string
  This OPTIONAL property describes the http verb (also known as http request method) for the http request. If omitted, the http verb is defaulted to GET.
  - body []byte
  This OPTIONAL property describes the http body to be included in the request.
  - noredirect bool
  This OPTIONAL property describes whether http redirects should be disabled. If omitted, it is defaulted to false (so, per default, redirects are enabled).
Options used to configure fields: –body, –header, –mediaType, –noredirect, –url, –verb

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.

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

Docs

Open Component Model

Title here

sources

Usage

Options

Description

Examples

See Also

sources

Usage#

Options#

Description#

Examples#

See Also#

Usage

Options

Description

Examples

See Also