Skip to content

Latest commit

 

History

History
405 lines (313 loc) · 17.4 KB

ocm.md

File metadata and controls

405 lines (313 loc) · 17.4 KB
Raw

ocm — Open Component Model Command Line Client

Synopsis

ocm [<options>] <sub command> ...

Options

  -X, --attribute stringArray     attribute setting
      --ca-cert stringArray       additional root certificate authorities (for signing certificates)
      --config stringArray        configuration file
      --config-set strings        apply configuration set
  -C, --cred stringArray          credential setting
  -h, --help                      help for ocm
  -I, --issuer stringArray        issuer name or distinguished name (DN) (optionally for dedicated signature) ([<name>:=]<dn>)
      --logJson                   log as json instead of human readable logs
      --logconfig string          log config
  -L, --logfile string            set log file
      --logkeys stringArray       log tags/realms(with leading /) to be enabled ([/[+]]name{,[/[+]]name}[=level])
  -l, --loglevel string           set log level
  -K, --private-key stringArray   private key setting
  -k, --public-key stringArray    public key setting
  -v, --verbose                   deprecated: enable logrus verbose logging
      --version                   show version

Description

The Open Component Model command line client supports the work with OCM artifacts, like Component Archives, Common Transport Archive, Component Repositories, and Component Versions.

Additionally it provides some limited support for the docker daemon, OCI artifacts and registries.

It can be used in two ways:

  • verb/operation first: here the sub commands follow the pattern <verb> <object kind> <arguments>
  • area/kind first: here the area and/or object kind is given first followed by the operation according to the pattern [<area>] <object kind> <verb/operation> <arguments>

The command accepts some top level options, they can only be given before the sub commands.

A configuration according to ocm configfile is read from a .ocmconfig file located in the HOME directory. With the option --config other file locations can be specified. If nothing is specified and no file is found at the default location a default configuration is composed according to known type specific configuration files.

The following configuration sources are used:

  • The docker configuration file at ~/.docker/config.json is read to feed in the configured credentials for OCI registries.

  • The npm configuration file at ~/.npmrc is read to feed in the configured credentials for NPM registries.

With the option --cred it is possible to specify arbitrary credentials for various environments on the command line. Nevertheless it is always preferable to use the cli config file. Every credential setting is related to a dedicated consumer and provides a set of credential attributes. All this can be specified by a sequence of --cred options.

Every option value has the format

--cred [:]<attr>=<value>

Consumer identity attributes are prefixed with the colon ':'. A credential settings always start with a sequence of at least one identity attributes, followed by a sequence of credential attributes. If a credential attribute is followed by an identity attribute a new credential setting is started.

The first credential setting may omit identity attributes. In this case it is used as default credential, always used if no dedicated match is found.

For example:

--cred :type=OCIRegistry --cred :hostname=ghcr.io --cred username=mandelsoft --cred password=xyz

With the option -X it is possible to pass global settings of the form

-X <attribute>=<value>

The --log* options can be used to configure the logging behaviour. For details see ocm logging.

There is a quick config option --logkeys to configure simple tag/realm based condition rules. The comma-separated names build an AND rule. Hereby, names starting with a slash (/) denote a realm (without the leading slash). A realm is a slash separated sequence of identifiers. If the realm name starts with a plus (+) character the generated rule will match the realm and all its sub-realms, otherwise, only the dedicated realm is affected. For example /+ocm=trace will enable all log output of the OCM library.

A tag directly matches the logging tags. Used tags and realms can be found under topic ocm logging. The ocm coding basically uses the realm ocm. The default level to enable is info. Separated by an equal sign (=) optionally a dedicated level can be specified. Log levels can be (error, warn, info, debug and trace. The default level is warn. The --logconfig* options can be used to configure a complete logging configuration (yaml/json) via command line. If the argument starts with an @, the logging configuration is taken from a file.

The value can be a simple type or a JSON/YAML string for complex values (see ocm attributes). The following attributes are supported:

  • github.com/mandelsoft/logforward [logfwd]: logconfig Logging config structure used for config forwarding

    This attribute is used to specify a logging configuration intended to be forwarded to other tools. (For example: TOI passes this config to the executor)

  • github.com/mandelsoft/oci/cache [cache]: string

    Filesystem folder to use for caching OCI blobs

  • github.com/mandelsoft/ocm/compat [compat]: bool

    Compatibility mode: Avoid generic local access methods and prefer type specific ones.

  • github.com/mandelsoft/ocm/hasher: JSON

    Preferred hash algorithm to calculate resource digests. The following digesters are supported:

    • NO-DIGEST
    • SHA-256 (default)
    • SHA-512

  • github.com/mandelsoft/ocm/keeplocalblob [keeplocalblob]: bool

    Keep local blobs when importing OCI artifacts to OCI registries from localBlob access methods. By default, they will be expanded to OCI artifacts with the access method ociRegistry. If this option is set to true, they will be stored as local blobs, also. The access method will still be localBlob but with a nested ociRegistry access method for describing the global access.

  • github.com/mandelsoft/ocm/mapocirepo [mapocirepo]: bool|YAML

    When uploading an OCI artifact blob to an OCI based OCM repository and the artifact is uploaded as OCI artifact, the repository path part is shortened, either by hashing all but the last repository name part or by executing some prefix based name mappings.

    If a boolean is given the short hash or none mode is enabled. The YAML flavor uses the following fields:

    • mode string: hash, shortHash, prefixMapping or none. If unset, no mapping is done.
    • prefixMappings: map[string]string repository path prefix mapping.
    • prefix: string repository prefix to use (replaces potential sub path of OCM repo). or none.
    • prefixMapping: map[string]string repository path prefix mapping.

    Notes:

    • The mapping only occurs in transfer commands and only when transferring to OCI registries (e.g. when transferring to a CTF archive this option will be ignored).
    • The mapping in mode prefixMapping requires a full prefix of the composed final name. Partial matches are not supported. The host name of the target will be skipped.
    • The artifact name of the component-descriptor is not mapped.
    • If the mapping is provided on the command line it must be JSON format and needs to be properly escaped (see example below).

    Example:

    Assume a component named github.com/my_org/myexamplewithalongname and a chart name echo in the Charts.yaml of the chart archive. The following input to a resource.yaml creates a component version:

    name: mychart
type: helmChart
input:
  type: helm
  path: charts/mychart.tgz
---
name: myimage
type: ociImage
version: 0.1.0
input:
  type: ociImage
  repository: ocm/ocm.software/ocmcli/ocmcli-image
  path: ghcr.io/acme/ocm/ocm.software/ocmcli/ocmcli-image:0.1.0

    The following command:

    ocm "-X mapocirepo={\"mode\":\"mapping\",\"prefixMappings\":{\"acme/github.com/my_org/myexamplewithalongname/ocm/ocm.software/ocmcli\":\"acme/cli\", \"acme/github.com/my_org/myexamplewithalongnameabc123\":\"acme/mychart\"}}" transfer ctf -f --copy-resources ./ctf ghcr.io/acme

    will result in the following artifacts in ghcr.io/my_org:

    mychart/echo
cli/ocmcli-image

    Note that the host name part of the transfer target ghcr.io/acme is excluded from the prefix but the path acme is considered.

    The same using a config file .ocmconfig:

    type: generic.config.ocm.software/v1
configurations:
...
- type: attributes.config.ocm.software
  attributes:
	...
	mapocirepo:
	  mode: mapping
	  prefixMappings:
	    acme/github.com/my\_org/myexamplewithalongname/ocm/ocm.software/ocmcli: acme/cli
		acme/github.com/my\_org/myexamplewithalongnameabc123: acme/mychart

    ocm transfer ca -f --copy-resources ./ca ghcr.io/acme

  • github.com/mandelsoft/ocm/ociuploadrepo [ociuploadrepo]: oci base repository ref

    Upload local OCI artifact blobs to a dedicated repository.

  • github.com/mandelsoft/ocm/plugindir [plugindir]: plugin directory

    Directory to look for OCM plugin executables.

  • github.com/mandelsoft/ocm/rootcerts [rootcerts]: JSON

    General root certificate settings given as JSON document with the following format:

    {
  "rootCertificates": [
     {
       "data": ""<base64>"
     },
     {
       "path": ""<file path>"
     }
  ]
}

    One of following data fields are possible:

    • data: base64 encoded binary data
    • stringdata: plain text data
    • path: a file path to read the data from

  • github.com/mandelsoft/ocm/signing: JSON

    Public and private Key settings given as JSON document with the following format:

    {
  "publicKeys": [
     "<provider>": {
       "data": ""<base64>"
     }
  ],
  "privateKeys"": [
     "<provider>": {
       "path": ""<file path>"
     }
  ]
}

    One of following data fields are possible:

    • data: base64 encoded binary data
    • stringdata: plain text data
    • path: a file path to read the data from

  • github.com/mandelsoft/tempblobcache [blobcache]: string Foldername for temporary blob cache

    The temporary blob cache is used to accessing large blobs from remote systems. The are temporarily stored in the filesystem, instead of the memory, to avoid blowing up the memory consumption.

  • ocm.software/cliconfig [cliconfig]: cliconfig Configuration Object passed to command line plugin.

  • ocm.software/compositionmode [compositionmode]: bool (default: false)

    Composition mode decouples a component version provided by a repository implementation from the backend persistence. Added local blobs will and other changes will not be forwarded to the backend repository until an AddVersion is called on the component. If composition mode is disabled blobs will directly be forwarded to the backend and descriptor updated will be persisted on AddVersion or closing a provided existing component version.

  • ocm.software/signing/sigstore [sigstore]: sigstore config Configuration to use for sigstore based signing.

    The following fields are used.

For several options (like -X) it is possible to pass complex values using JSON or YAML syntax. To pass those arguments the escaping of the used shell must be used to pass quotes, commas, curly brackets or newlines. for the bash the easiest way to achieve this is to put the complete value into single quotes.

-X 'mapocirepo={"mode": "shortHash"}'.

Alternatively, quotes and opening curly brackets can be escaped by using a backslash (\). Often a tagged value can also be substituted from a file with the syntax

<attr>=@<filepath>

The --public-key and --private-key options can be used to define public and private keys on the command line. The options have an argument of the form <name>=<filepath>. The name is the name of the key and represents the context is used for (For example the signature name of a component version)

Alternatively a key can be specified as base64 encoded string if the argument start with the prefix ! or as direct string with the prefix =.

With --issuer it is possible to declare expected issuer constraints for public key certificates provided as part of a signature required to accept the provisioned public key (besides the successful validation of the certificate). By default, the issuer constraint is derived from the signature name. If it is not a formal distinguished name, it is assumed to be a plain common name.

With --ca-cert it is possible to define additional root certificates for signature verification, if public keys are provided by a certificate delivered with the signature.

SEE ALSO

Sub Commands
  • ocm add — Add elements to a component repository or component version
  • ocm bootstrap — bootstrap components
  • ocm check — check components in OCM repository
  • ocm clean — Cleanup/re-organize elements
  • ocm controller — Commands acting on the ocm-controller
  • ocm create — Create transport or component archive
  • ocm describe — Describe various elements by using appropriate sub commands.
  • ocm download — Download oci artifacts, resources or complete components
  • ocm execute — Execute an element.
  • ocm get — Get information about artifacts and components
  • ocm hash — Hash and normalization operations
  • ocm install — Install new OCM CLI components
  • ocm list — List information about components
  • ocm set — Set information about OCM repositories
  • ocm show — Show tags or versions
  • ocm sign — Sign components or hashes
  • ocm transfer — Transfer artifacts or components
  • ocm verify — Verify component version signatures
  • ocm version — displays the version
Area Overview
  • ocm cache — Cache related commands
  • ocm credentials — Commands acting on credentials
  • ocm oci — Dedicated command flavors for the OCI layer
  • ocm ocm — Dedicated command flavors for the Open Component Model
  • ocm toi — Dedicated command flavors for the TOI layer
Additional Help Topics