source-configuration

Usage

ocm add source-configuration [<options>] <target> {<configfile> | <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
      --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
      --extension string                    maven extension name
      --extra <name>=<value>                source extra identity (default [])
      --globalAccess YAML                   access specification for global access
      --groupId string                      maven group id
      --header <name>:<value>,<value>,...   http headers (default {})
  -h, --help                                help for source-configuration
      --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
      --package string                      package or object name
      --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)
      --type string                         source type
      --url string                          artifact or server url
      --verb string                         http request method
      --version string                      source version

Description

Add a source specification to a source config file used by ocm add sources.

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. Elements must follow the resource meta data description scheme of the component descriptor.

If not specified anywhere the artifact type will be defaulted to directoryTree.

If expressions/templates are used in the specification file an appropriate templater and the required settings might be required to provide a correct input validation.

This command accepts additional source specification files describing the sources to add to a component version.

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

  • 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

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}"
    

Examples


$ ocm add source-config sources.yaml --name sources --type filesystem --access '{ "type": "gitHub", "repoUrl": "ocm.software/ocm", "commit": "xyz" }'

See Also

  • ocm add — Add elements to a component repository or component version