Docs

source-configuration

Usage

ocm add source-configuration [<options>] <target> {<configfile> | <var>=<value>}

Options

      --access YAML                         blob access specification (YAML)
      --accessHostname string               hostname used for access
      --accessPackage string                package or object name
      --accessRegistry string               registry base URL
      --accessRepository string             repository URL
      --accessType string                   type of blob access specification
      --accessVersion string                version for access specification
      --body string                         body of a http request
      --bucket string                       bucket name
      --commit string                       git commit id
      --digest string                       blob digest
      --extra <name>=<value>                source extra identity (default [])
      --globalAccess YAML                   access specification for global access
      --header <name>:<value>,<value>,...   http headers (default {})
  -h, --help                                help for source-configuration
      --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
      --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
      --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
      --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 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. 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. The denoted images, as well as the wrapping image index is 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 ociArtifact

    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 “/”.

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

    • 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: –accessPackage, –accessRepository, –accessVersion

  • 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 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: –accessPackage, –accessRegistry, –accessVersion

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

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": "github.com/open-component-model/ocm", "commit": "xyz" }'

See Also

  • ocm add — Add elements to a component repository or component version
Prev
rsakeypair
Next
sources