From dcc5b3af1049879c4778749d5771a657eaea308a Mon Sep 17 00:00:00 2001 From: Hilmar Falkenberg Date: Mon, 12 Aug 2024 17:33:11 +0200 Subject: [PATCH 01/45] new GHA workflow --- .github/workflows/verify-md.yml | 35 +++++++++++++++++++++++++++++++++ 1 file changed, 35 insertions(+) create mode 100644 .github/workflows/verify-md.yml diff --git a/.github/workflows/verify-md.yml b/.github/workflows/verify-md.yml new file mode 100644 index 0000000000..efe49318e1 --- /dev/null +++ b/.github/workflows/verify-md.yml @@ -0,0 +1,35 @@ +name: Markdown + +on: + push: + branches: + - main + pull_request: + branches: + - main + paths: + - '**/*.md' + +jobs: + lint-markdown: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - name: Markdown Linting + uses: nosborn/github-action-markdown-cli@v3 + with: + files: . + dot: true + config_file: .markdownlint.yml + ignore_path: .markdownignore + verify-links: + name: verify-links + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - name: Markdown verify links + uses: gaurav-nelson/github-action-markdown-link-check@v1 + with: + use-quiet-mode: yes + use-verbose-mode: no + config-file: .markdown-link-check.json From 5b7272fb40663506329c126c348b0b6abe495600 Mon Sep 17 00:00:00 2001 From: Hilmar Falkenberg Date: Mon, 12 Aug 2024 17:35:00 +0200 Subject: [PATCH 02/45] config files --- .markdown-link-check.json | 8 ++++++++ .markdownignore | 3 +++ .markdownlint.yml | 4 ++++ 3 files changed, 15 insertions(+) create mode 100644 .markdown-link-check.json create mode 100644 .markdownignore create mode 100644 .markdownlint.yml diff --git a/.markdown-link-check.json b/.markdown-link-check.json new file mode 100644 index 0000000000..9a2ab70be6 --- /dev/null +++ b/.markdown-link-check.json @@ -0,0 +1,8 @@ +{ "replacementPatterns": [ + { "pattern": "^/", "replacement": "/github/workspace/" } + ], + "ignorePatterns": [ + { "pattern": "^http[s]*://localhost.*" } + ,{ "pattern": "^{{.*}}$" } + ] +} diff --git a/.markdownignore b/.markdownignore new file mode 100644 index 0000000000..61874c2a7a --- /dev/null +++ b/.markdownignore @@ -0,0 +1,3 @@ +examples/lib/tour/0* +docs/reference +docs/pluginreference diff --git a/.markdownlint.yml b/.markdownlint.yml new file mode 100644 index 0000000000..b0e187739f --- /dev/null +++ b/.markdownlint.yml @@ -0,0 +1,4 @@ +default: true + +MD013: false #Line length - https://github.com/DavidAnson/markdownlint/blob/HEAD/doc/Rules.md#md013 +MD033: false #Inline HTML - https://github.com/DavidAnson/markdownlint/blob/HEAD/doc/Rules.md#md033 From 0749084fc95267562118f754ea662b4150c87d68 Mon Sep 17 00:00:00 2001 From: Hilmar Falkenberg Date: Mon, 12 Aug 2024 17:35:36 +0200 Subject: [PATCH 03/45] fix one first finding --- examples/lib/tour/04-working-with-config/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/examples/lib/tour/04-working-with-config/README.md b/examples/lib/tour/04-working-with-config/README.md index fa816ee178..bc1ac0d845 100644 --- a/examples/lib/tour/04-working-with-config/README.md +++ b/examples/lib/tour/04-working-with-config/README.md @@ -395,7 +395,7 @@ If you have provided your OCI credentials with #### Templating The configuration library function does not only read the -ocm config file, it also applies [*spiff*](github.com/mandelsoft/spiff) +ocm config file, it also applies [*spiff*](https://github.com/mandelsoft/spiff) processing to the provided YAML/JSON content. *Spiff* is an in-domain yaml-based templating engine. Therefore, you can use any spiff dynaml expression to define values or even complete From dd972dbb61cc3c8265f2e21a464542d6055cecf8 Mon Sep 17 00:00:00 2001 From: Hilmar Falkenberg Date: Tue, 13 Aug 2024 12:53:06 +0200 Subject: [PATCH 04/45] Spellcheck --- .github/workflows/verify-md.yml | 14 ++- .spellcheck.yml | 20 +++++ .wordlist.txt | 153 ++++++++++++++++++++++++++++++++ 3 files changed, 186 insertions(+), 1 deletion(-) create mode 100644 .spellcheck.yml create mode 100644 .wordlist.txt diff --git a/.github/workflows/verify-md.yml b/.github/workflows/verify-md.yml index efe49318e1..47b534da56 100644 --- a/.github/workflows/verify-md.yml +++ b/.github/workflows/verify-md.yml @@ -13,6 +13,7 @@ on: jobs: lint-markdown: runs-on: ubuntu-latest + name: Lint steps: - uses: actions/checkout@v4 - name: Markdown Linting @@ -23,7 +24,7 @@ jobs: config_file: .markdownlint.yml ignore_path: .markdownignore verify-links: - name: verify-links + name: Verify links runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 @@ -33,3 +34,14 @@ jobs: use-quiet-mode: yes use-verbose-mode: no config-file: .markdown-link-check.json + spellcheck: + name: Spellcheck + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - name: Spellcheck + uses: rojopolis/spellcheck-github-actions@v0 + with: + task_name: Markdown + output_file: spellcheck-output.txt + diff --git a/.spellcheck.yml b/.spellcheck.yml new file mode 100644 index 0000000000..950ed2770a --- /dev/null +++ b/.spellcheck.yml @@ -0,0 +1,20 @@ +matrix: +- name: Markdown + aspell: + lang: en + dictionary: + wordlists: + - .wordlist.txt + encoding: utf-8 + pipeline: + - pyspelling.filters.markdown: + markdown_extensions: + - pymdownx.superfences + - pyspelling.filters.html: + comments: false + ignores: + - code + - pre + sources: + - '**/*.md' + default_encoding: utf-8 diff --git a/.wordlist.txt b/.wordlist.txt new file mode 100644 index 0000000000..fdf55ad270 --- /dev/null +++ b/.wordlist.txt @@ -0,0 +1,153 @@ +aggregative +API +ArtifactId +AWS +backend +backends +basename +bool +boolean +CAs +CLI +CLIs +closable +CNCF +ConsumerId +crypto +CTF +CTFs +CVs +dependabot +deserializable +deserialization +deserialize +deserialized +digesters +DNS +DockerConfig +downloader +downloaders +dry-run +echoserver +entrypoint +executables +extensibility +filepath +filesystem +finalizer +finalizers +foldername +GAV +getter +Github +gitignore +GitOps +globals +gofmt +golang +golangci +goreleaser +gosec +goutils +GroupId +gzip +HashiCorp +Homebrew +html +http +https +ImageMapping +inlined +installable +instantiation +io +iterable +JSON +keyless +keyring +kubebuilder +kubeconfig +Kubernetes +lifecycle +linter +linters +lister +listers +localizations +lookups +Makefile +makefiles +mandelsoft +matcher +matchers +mavenArtifact +mavenPackage +mavenRepository +mimetype +multiarch +mutex +mvn +namespace +namespaces +npm +npmrc +NpmRegistry +oauth +OCI +ociArtifact +ociRegistry +OCM +OCMBot +OS +parameterization +Podinfo +Podman +predefine +programmatically +PRs +PubSub +README +readonly +resolvers +routings +RSA +runtime +SBOD +SBOM +SDK +SemVer +sequent +serializable +SHA +SPDX +srcRefs +stderr +stdin +stdout +storable +struct +subchart +subcharts +tempfile +templated +templater +templaters +templating +TGZ +TLS +TOI +toiExecutor +transportarchive +typename +unmodifiable +untrusted +uploader +uploaders +URL +urls +UTF +util +utils +wget +XML +YAML From ed2d1b0a49bc0b3d4685d8614b17ade73c7bbf1a Mon Sep 17 00:00:00 2001 From: Hilmar Falkenberg Date: Tue, 13 Aug 2024 12:57:03 +0200 Subject: [PATCH 05/45] md lint --- api/config/README.md | 107 ++++---- docs/adrs/0002-panic-handlers.md | 28 +- docs/command-plugins.md | 66 ++--- examples/lib/config.md | 246 +++++++++--------- examples/lib/creds.md | 67 ++--- .../tour/docsrc/01-getting-started/README.md | 6 +- .../README.md | 19 +- .../03-working-with-credentials/README.md | 10 +- .../docsrc/04-working-with-config/README.md | 20 +- .../README.md | 4 +- examples/lib/transfer.md | 115 ++++---- 11 files changed, 348 insertions(+), 340 deletions(-) diff --git a/api/config/README.md b/api/config/README.md index 7a5bab9873..4bb0586595 100644 --- a/api/config/README.md +++ b/api/config/README.md @@ -5,34 +5,34 @@ The `config` context provides a generic configuration feature for data contexts ```go type Context interface { - datacontext.Context + datacontext.Context - AttributesContext() datacontext.AttributesContext + AttributesContext() datacontext.AttributesContext - // Info provides the context for nested configuration evaluation - Info() string - // WithInfo provides the same context with additional nesting info - WithInfo(desc string) Context + // Info provides the context for nested configuration evaluation + Info() string + // WithInfo provides the same context with additional nesting info + WithInfo(desc string) Context - ConfigTypes() ConfigTypeScheme + ConfigTypes() ConfigTypeScheme - // GetConfigForData deserialize configuration objects for known - // configuration types. - GetConfigForData(data []byte, unmarshaler runtime.Unmarshaler) (Config, error) + // GetConfigForData deserialize configuration objects for known + // configuration types. + GetConfigForData(data []byte, unmarshaler runtime.Unmarshaler) (Config, error) - // ApplyData applies the config given by a byte stream to the config store - // If the config type is not known, a generic config is stored and returned. - // In this case an unknown error for kind KIND_CONFIGTYPE is returned. - ApplyData(data []byte, unmarshaler runtime.Unmarshaler, desc string) (Config, error) - // ApplyConfig applies the config to the config store - ApplyConfig(spec Config, desc string) error + // ApplyData applies the config given by a byte stream to the config store + // If the config type is not known, a generic config is stored and returned. + // In this case an unknown error for kind KIND_CONFIGTYPE is returned. + ApplyData(data []byte, unmarshaler runtime.Unmarshaler, desc string) (Config, error) + // ApplyConfig applies the config to the config store + ApplyConfig(spec Config, desc string) error - GetConfigForType(generation int64, typ string) (int64, []Config) - GetConfigForName(generation int64, name string) (int64, []Config) - GetConfig(generation int64, selector ConfigSelector) (int64, []Config) + GetConfigForType(generation int64, typ string) (int64, []Config) + GetConfigForName(generation int64, name string) (int64, []Config) + GetConfig(generation int64, selector ConfigSelector) (int64, []Config) - Generation() int64 - ApplyTo(gen int64, target interface{}) (int64, error) + Generation() int64 + ApplyTo(gen int64, target interface{}) (int64, error) } ``` @@ -45,9 +45,9 @@ A `Config` object must implement the `Config` interface: ```go type Config interface { - runtime.VersionedTypedObject + runtime.VersionedTypedObject - ApplyTo(Context, interface{}) error + ApplyTo(Context, interface{}) error } ``` @@ -77,14 +77,14 @@ It can be set by the context constructor: ```go func newContext(shared datacontext.AttributesContext, configctx config.Context, reposcheme RepositoryTypeScheme, logger logging.Context) Context { - c := &_context{ - sharedattributes: shared, - updater: cfgcpi.NewUpdate(configctx), - knownRepositoryTypes: reposcheme, - ... - } - c.Context = datacontext.NewContextBase(c, CONTEXT_TYPE, key, shared.GetAttributes(), logger) - return c + c := &_context{ + sharedattributes: shared, + updater: cfgcpi.NewUpdate(configctx), + knownRepositoryTypes: reposcheme, + ... + } + c.Context = datacontext.NewContextBase(c, CONTEXT_TYPE, key, shared.GetAttributes(), logger) + return c } ``` @@ -94,11 +94,11 @@ called by methods based on configuration settings: ```go func (c *_context) ConfigContext() config.Context { - return c.updater.GetContext() + return c.updater.GetContext() } func (c *_context) Update() error { - return c.updater.Update(c) + return c.updater.Update(c) } ``` @@ -114,9 +114,9 @@ It must implement the interface: ```go type Config interface { - runtime.VersionedTypedObject + runtime.VersionedTypedObject - ApplyTo(Context, interface{}) error + ApplyTo(Context, interface{}) error } ``` @@ -130,41 +130,41 @@ The following snipped shows a typical pattern, how to implement this. const ( - MyConfigType = "my.config" + common.TypeGroupSuffix - MyConfigTypeV1 = MyConfigType + runtime.VersionSeparator + "v1" + MyConfigType = "my.config" + common.TypeGroupSuffix + MyConfigTypeV1 = MyConfigType + runtime.VersionSeparator + "v1" ) func init() { - config.RegisterConfigType(MyConfigType, config.NewConfigType(MyConfigType, &ConfigSpec{})) - config.RegisterConfigType(MyConfigTypeV1, config.NewConfigType(MyConfigTypeV1, &ConfigSpec{})) + config.RegisterConfigType(MyConfigType, config.NewConfigType(MyConfigType, &ConfigSpec{})) + config.RegisterConfigType(MyConfigTypeV1, config.NewConfigType(MyConfigTypeV1, &ConfigSpec{})) } // ConfigSpec describes a memory based repository interface. type ConfigSpec struct { - runtime.ObjectVersionedType `json:",inline"` - // Any configuration settings - ... + runtime.ObjectVersionedType `json:",inline"` + // Any configuration settings + ... } // NewConfigSpec creates a new memory ConfigSpec func NewConfigSpec() *ConfigSpec { - return &ConfigSpec{ - ObjectVersionedType: runtime.NewVersionedObjectType(MyConfigType), - } + return &ConfigSpec{ + ObjectVersionedType: runtime.NewVersionedObjectType(MyConfigType), + } } func (a *ConfigSpec) GetType() string { - return MyConfigType + return MyConfigType } func (a *ConfigSpec) ApplyTo(ctx config.Context, target interface{}) error { - // check if applicable for target object - t, ok := target.(cpi.Context) - if !ok { - return config.ErrNoContext(MyConfigType) - } - // do the needful - return false + // check if applicable for target object + t, ok := target.(cpi.Context) + if !ok { + return config.ErrNoContext(MyConfigType) + } + // do the needful + return false } ``` @@ -178,7 +178,6 @@ the configuration context (in sub package `config`), that can be used to aggregate any kind of configuration object, that is serializable. - ```go // Config describes a memory based repository interface. type Config struct { diff --git a/docs/adrs/0002-panic-handlers.md b/docs/adrs/0002-panic-handlers.md index 8642657c82..6fda900169 100644 --- a/docs/adrs/0002-panic-handlers.md +++ b/docs/adrs/0002-panic-handlers.md @@ -30,20 +30,20 @@ function such as: func (this *DLL) Append(d *DLL) { // Add defer handling crashes defer panics.HandleCrash() // defer call all handlers. - if d.next != nil || d.prev != nil { - panic("dll element already in use") - } - if this.lock != nil { - this.lock.Lock() - defer this.lock.Unlock() - d.lock = this.lock - } - d.next = this.next - d.prev = this - if this.next != nil { - this.next.prev = d - } - this.next = d + if d.next != nil || d.prev != nil { + panic("dll element already in use") + } + if this.lock != nil { + this.lock.Lock() + defer this.lock.Unlock() + d.lock = this.lock + } + d.next = this.next + d.prev = this + if this.next != nil { + this.next.prev = d + } + this.next = d } ``` diff --git a/docs/command-plugins.md b/docs/command-plugins.md index 1ba2bb3dc5..d2d639645f 100644 --- a/docs/command-plugins.md +++ b/docs/command-plugins.md @@ -1,6 +1,7 @@ The OCM Plugin framework now supports two features to extend the CLI with new (OCM related) commands: + - definition of configuration types (consumed by the plugin) - definition of CLI commands (for the OCM CLI) @@ -13,20 +14,20 @@ Examples see coding in `cmds/cliplugin` Config types are just registered at the Plugin Object; -``` - p := ppi.NewPlugin("cliplugin", version.Get().String()) +```go + p := ppi.NewPlugin("cliplugin", version.Get().String()) ... - p.RegisterConfigType(configType) + p.RegisterConfigType(configType) ``` The argument is just the config type as registered at the ocm library, for example: -``` +```go const ConfigType = "rhabarber.config.acme.org" type Config struct { - runtime.ObjectVersionedType `json:",inline"` - ... + runtime.ObjectVersionedType `json:",inline"` + ... } func (a *Config) ApplyTo(ctx cfgcpi.Context, target interface{}) error { @@ -34,8 +35,8 @@ func (a *Config) ApplyTo(ctx cfgcpi.Context, target interface{}) error { } func init() { - configType = cfgcpi.NewConfigType[*Config](ConfigType, usage) - cfgcpi.RegisterConfigType(configType) + configType = cfgcpi.NewConfigType[*Config](ConfigType, usage) + cfgcpi.RegisterConfigType(configType) } ``` @@ -69,23 +70,22 @@ A sample code could look like this: with coding for the cobra command similar to -``` - +```go type command struct { - date string + date string } func NewCommand() *cobra.Command { - cmd := &command{} - c := &cobra.Command{ - Use: Name + " ", - Short: "determine whether we are in rhubarb season", - Long: "The rhubarb season is between march and april.", - RunE: cmd.Run, - } - - c.Flags().StringVarP(&cmd.date, "date", "d", "", "the date to ask for (MM/DD)") - return c + cmd := &command{} + c := &cobra.Command{ + Use: Name + " ", + Short: "determine whether we are in rhubarb season", + Long: "The rhubarb season is between march and april.", + RunE: cmd.Run, + } + + c.Flags().StringVarP(&cmd.date, "date", "d", "", "the date to ask for (MM/DD)") + return c } func (c *command) Run(cmd *cobra.Command, args []string) error { @@ -94,6 +94,7 @@ func (c *command) Run(cmd *cobra.Command, args []string) error { ``` If the code wants to use the config framework, for example to + - use the OCM library again - access credentials - get configured with declared config types @@ -109,10 +110,10 @@ For the cobra support this can be requested by the option `WithVerb(...)`. If the config framework is used just add the following anonymoud import for an automated configuration: -``` +```go import ( // enable mandelsoft plugin logging configuration. - _ "ocm.software/ocm/pkg/contexts/ocm/plugin/ppi/config" + _ "ocm.software/ocm/pkg/contexts/ocm/plugin/ppi/config" ) ``` @@ -120,9 +121,9 @@ The plugin code is then configured with the configuration of the OCM CLI and the can be used. If the configuration should be handled by explicit plugin code a handler can be registered with -``` +```go func init() { - command.RegisterCommandConfigHandler(yourHandler) + command.RegisterCommandConfigHandler(yourHandler) } ``` @@ -132,32 +133,33 @@ It gets a config yaml according to the config objects used by the OCM library. To get the logging configuration from the OCM CLI the plugin has be configured with -``` - p.ForwardLogging() +```go + p.ForwardLogging() ``` If the standard mandelsoft logging from the OCM library is used the configuration can be implemented directly with an anonymous import of -``` +```go import ( // enable mandelsoft plugin logging configuration. - _ "ocm.software/ocm/pkg/contexts/ocm/plugin/ppi/logging" + _ "ocm.software/ocm/pkg/contexts/ocm/plugin/ppi/logging" ) ``` + The plugin code is then configured with the logging configuration of the OCM CLI and the mandelsoft logging frame work can be used. If the logging configuration should be handled by explicit plugin code a handler can be registered with -``` +```go func init() { - cmds.RegisterLoggingConfigHandler(yourHandler) + cmds.RegisterLoggingConfigHandler(yourHandler) } ``` It gets a logging configuration yaml according to the logging config used by the OCM library (`github.com/mandelsoft/logging/config`). -#### Using Plugin command extensions from the OCM library. +#### Using Plugin command extensions from the OCM library The plugin command extensions can also be called without the OCM CLI directly from the OCM library. Therefore the plugin objects provided by the library can be used. diff --git a/examples/lib/config.md b/examples/lib/config.md index edc917c136..82ef42387e 100644 --- a/examples/lib/config.md +++ b/examples/lib/config.md @@ -20,7 +20,7 @@ is called for a desired target. The object may decide to apply itself to this target or to bypass the target object. The configuration objects are typed and should be serializable. This -enables the configuration context to use scheme objects, like the other +enables the configuration context to use scheme objects, like the other context types to reconstruct configurations from a byte stream/textual representation. @@ -32,42 +32,42 @@ applies the contained configuration in the order of their appearance. ## Using the Configuration Context with explicit Configuration Objects -A first example how to use configuration objects can be found +A first example how to use configuration objects can be found [here](config1/example.go). It just configures a configuration object provided by the credential context able to configure credential settings. ```go - cid := credentials.ConsumerIdentity{ - ociid.ID_TYPE: ociid.CONSUMER_TYPE, - ociid.ID_HOSTNAME: "ghcr.io", - ociid.ID_PATHPREFIX: "mandelsoft", - } - - // create a credential configuration object - // and configure it to provide some direct consumer credentials. - creds := ccfg.New() - creds.AddConsumer( - cid, - directcreds.NewRepositorySpec(cfg.GetCredentials().Properties()), - ) + cid := credentials.ConsumerIdentity{ + ociid.ID_TYPE: ociid.CONSUMER_TYPE, + ociid.ID_HOSTNAME: "ghcr.io", + ociid.ID_PATHPREFIX: "mandelsoft", + } + + // create a credential configuration object + // and configure it to provide some direct consumer credentials. + creds := ccfg.New() + creds.AddConsumer( + cid, + directcreds.NewRepositorySpec(cfg.GetCredentials().Properties()), + ) ``` -It just declares direct credentials for a dedicated consumer id (see the +It just declares direct credentials for a dedicated consumer id (see the [credentials example](creds.md)). The ocm context can be used to get access to the appropriate configuration context, which is used to apply the configuration object. ```go - octx := ocm.DefaultContext() - cctx := octx.ConfigContext() + octx := ocm.DefaultContext() + cctx := octx.ConfigContext() - err = cctx.ApplyConfig(creds, "explicit") - if err != nil { - return errors.Wrapf(err, "cannot apply config") - } + err = cctx.ApplyConfig(creds, "explicit") + if err != nil { + return errors.Wrapf(err, "cannot apply config") + } ``` After the object has been applied, the result can be observed on the @@ -77,18 +77,18 @@ be queried. In the example this is a credentials object valid for an OCI registry. ```go - credctx := octx.CredentialsContext() - - found, err := credctx.GetCredentialsForConsumer(cid, ociid.IdentityMatcher) - if err != nil { - return errors.Wrapf(err, "cannot extract credentials") - } - got, err := found.Credentials(credctx) - if err != nil { - return errors.Wrapf(err, "cannot evaluate credentials") - } - - fmt.Printf("found: %s\n", got) + credctx := octx.CredentialsContext() + + found, err := credctx.GetCredentialsForConsumer(cid, ociid.IdentityMatcher) + if err != nil { + return errors.Wrapf(err, "cannot extract credentials") + } + got, err := found.Credentials(credctx) + if err != nil { + return errors.Wrapf(err, "cannot evaluate credentials") + } + + fmt.Printf("found: %s\n", got) ``` The first call provides a potentially dynamic credential source for the requested consumer. This object can then be used to dtermine actual credentials valid for an actual resource access. This indirection is introduced to support dynamic just-in-time credential generation processes. @@ -97,8 +97,8 @@ The function `credentials.CredentialsForConsumer` can be used, instead, to direc ## Configurations in Configuration Files -The previous example just demonstrates the basic flow, it might not be -very useful, because the consumer could directly be configured at the +The previous example just demonstrates the basic flow, it might not be +very useful, because the consumer could directly be configured at the credential context. The complete mechanism becomes valuable, if some kind of generic @@ -150,43 +150,43 @@ example). It can be applied as whole as shown in the following code snippet: ```go - data, err := ioutil.ReadFile(CFGFILE) - if err != nil { - return errors.Wrapf(err, "cannot read configuration file %s", CFGFILE) - } - - octx := ocm.DefaultContext() - cctx := octx.ConfigContext() - - _, err = cctx.ApplyData(data, runtime.DefaultYAMLEncoding, CFGFILE) - if err != nil { - return errors.Wrapf(err, "cannot apply config data") - } + data, err := ioutil.ReadFile(CFGFILE) + if err != nil { + return errors.Wrapf(err, "cannot read configuration file %s", CFGFILE) + } + + octx := ocm.DefaultContext() + cctx := octx.ConfigContext() + + _, err = cctx.ApplyData(data, runtime.DefaultYAMLEncoding, CFGFILE) + if err != nil { + return errors.Wrapf(err, "cannot apply config data") + } ``` It uses the exactly same configuration mechanism shown in the previous example, so the query code looks all the same: ```go - cid := credentials.ConsumerIdentity{ - ociid.ID_TYPE: ociid.CONSUMER_TYPE, - ociid.ID_HOSTNAME: "ghcr.io", - ociid.ID_PATHPREFIX: "mandelsoft", - } - - // as before - credctx := octx.CredentialsContext() - - found, err := credctx.GetCredentialsForConsumer(cid, ociid.IdentityMatcher) - if err != nil { - return errors.Wrapf(err, "cannot extract credentials") - } - got, err := found.Credentials(credctx) - if err != nil { - return errors.Wrapf(err, "cannot evaluate credentials") - } - - fmt.Printf("found: %s\n", got) + cid := credentials.ConsumerIdentity{ + ociid.ID_TYPE: ociid.CONSUMER_TYPE, + ociid.ID_HOSTNAME: "ghcr.io", + ociid.ID_PATHPREFIX: "mandelsoft", + } + + // as before + credctx := octx.CredentialsContext() + + found, err := credctx.GetCredentialsForConsumer(cid, ociid.IdentityMatcher) + if err != nil { + return errors.Wrapf(err, "cannot extract credentials") + } + got, err := found.Credentials(credctx) + if err != nil { + return errors.Wrapf(err, "cannot evaluate credentials") + } + + fmt.Printf("found: %s\n", got) ``` The complete example can be found [here](config2/example.go). @@ -203,7 +203,7 @@ searched for a configuration file and applies it. If not found it looks for a docker config file and applies an appropriate setting (see example above). If the config data is already provided by some other means, it can be directly be -applied with the function +applied with the function pkg.contexts.ocm.utils.ConfigureByData(ctx ocm.Context, data []byte, info string) error @@ -217,7 +217,7 @@ a GO struct implementing the interface `credentials.cpi.Config`. The main method here is `ApplyTo(configctx Context, target interface{}) error`, which is used to apply the content to a dedicated target object. The method has to decide on its own whether it applies to the passed object (type) at all, or what part of its content -is applied. +is applied. This way it is possible to provide configuration objects that configure multiple types of targets based on the same configuration information. @@ -230,8 +230,8 @@ configuration objects, they are just ignored. The typical use-case is to configure contexts. To be able to get up-to-date with configuration settings applied after an object has been created (with some initial configuration), the methods of a target object depending on potential -configuration, have to update the target configuration prior to their -execution. This is supported by an `Update` object, which related to a +configuration, have to update the target configuration prior to their +execution. This is supported by an `Update` object, which related to a configuration context. A complete example covering the following two sections can be found @@ -245,29 +245,29 @@ data, which is matter to some configuration. ```go type Target struct { - updater cpi.Updater - value string + updater cpi.Updater + value string } func NewTarget(ctx cpi.Context) *Target { - return &Target{ - updater: cpi.NewUpdate(ctx), - } + return &Target{ + updater: cpi.NewUpdate(ctx), + } } func (t *Target) SetValue(v string) { - t.value = v + t.value = v } func (t *Target) GetValue() string { - t.updater.Update(t) - return t.value + t.updater.Update(t) + return t.value } ``` Whenever a method is called, which depends on potentially configurable information the `Update`method must be called on the updater instance. -The configuration context keeps track of a sequence of applied configuration +The configuration context keeps track of a sequence of applied configuration objects. The updater objects stored the sequence number of the latest executed update. Calling the `Update` method just replays the configuration objects applied since the last update. @@ -278,29 +278,29 @@ A configuration object then may look as follows: const TYPE = "mytype.config.mandelsoft.org" type Config struct { - runtime.ObjectVersionedType `json:",inline""` - Value string `json:"value"` + runtime.ObjectVersionedType `json:",inline""` + Value string `json:"value"` } func (c *Config) ApplyTo(context cpi.Context, i interface{}) error { - if i == nil { - return nil - } - t, ok := i.(*Target) - if !ok { - return cpi.ErrNoContext(TYPE) - } - t.SetValue(c.Value) - return nil + if i == nil { + return nil + } + t, ok := i.(*Target) + if !ok { + return cpi.ErrNoContext(TYPE) + } + t.SetValue(c.Value) + return nil } var _ cpi.Config = (*Config)(nil) func NewConfig(v string) *Config { - return &Config{ - ObjectVersionedType: runtime.NewVersionedObjectType(TYPE), - Value: v, - } + return &Config{ + ObjectVersionedType: runtime.NewVersionedObjectType(TYPE), + Value: v, + } } ``` @@ -311,26 +311,26 @@ With this preparing work, an application using the configuration context to configure this new target object could look like this: ```go - ctx := config.DefaultContext() + ctx := config.DefaultContext() - target := NewTarget(ctx) + target := NewTarget(ctx) - err := ctx.ApplyConfig(NewConfig("hello world"), "explicit1") - if err != nil { - return errors.Wrapf(err, "cannot apply config 1") - } + err := ctx.ApplyConfig(NewConfig("hello world"), "explicit1") + if err != nil { + return errors.Wrapf(err, "cannot apply config 1") + } - fmt.Printf("value is %q\n", target.GetValue()) + fmt.Printf("value is %q\n", target.GetValue()) - err = ctx.ApplyConfig(NewConfig("hello universe"), "explicit2") - if err != nil { - return errors.Wrapf(err, "cannot apply config 2") - } + err = ctx.ApplyConfig(NewConfig("hello universe"), "explicit2") + if err != nil { + return errors.Wrapf(err, "cannot apply config 2") + } - fmt.Printf("value is %q\n", target.GetValue()) + fmt.Printf("value is %q\n", target.GetValue()) - newtarget := NewTarget(ctx) - fmt.Printf("value is %q\n", newtarget.GetValue()) + newtarget := NewTarget(ctx) + fmt.Printf("value is %q\n", newtarget.GetValue()) ``` Once a connection of the target object to a configuration context is @@ -338,7 +338,7 @@ established, it does not matter, whether the object is created before or after applying a configuration to the configuration context. Therefore, a configuration can be applied long before real targets are created. -The configuration context does never refer to potential targets, therefore, +The configuration context does never refer to potential targets, therefore, the garbage collection of target objects is not blocked by the existence of a configuration context for those objects. @@ -353,7 +353,7 @@ by an `init` function: ```go func init() { - cpi.RegisterConfigType(TYPE, cpi.NewConfigType(TYPE, &Config{}, "just provide a value for Target objects")) + cpi.RegisterConfigType(TYPE, cpi.NewConfigType(TYPE, &Config{}, "just provide a value for Target objects")) } ``` @@ -373,19 +373,19 @@ configurations: to configure a dedicated context as shown in the second example: ```go - data, err := ioutil.ReadFile(CFGFILE) - if err != nil { - return errors.Wrapf(err, "cannot read configuration file %s", CFGFILE) - } - - _, err = ctx.ApplyData(data, runtime.DefaultYAMLEncoding, CFGFILE) - if err != nil { - return errors.Wrapf(err, "cannot apply config data") - } - - fmt.Printf("value is %q\n", newtarget.GetValue()) + data, err := ioutil.ReadFile(CFGFILE) + if err != nil { + return errors.Wrapf(err, "cannot read configuration file %s", CFGFILE) + } + + _, err = ctx.ApplyData(data, runtime.DefaultYAMLEncoding, CFGFILE) + if err != nil { + return errors.Wrapf(err, "cannot apply config data") + } + + fmt.Printf("value is %q\n", newtarget.GetValue()) ``` When composing a new configuration context with a context builder, it is possible to use another scheme instance than the default one, -configured by `init` functions. \ No newline at end of file +configured by `init` functions. diff --git a/examples/lib/creds.md b/examples/lib/creds.md index 27ec5336bf..df2e20df64 100644 --- a/examples/lib/creds.md +++ b/examples/lib/creds.md @@ -12,14 +12,14 @@ the credentials directly for the lookup call: ```go cfg, err := helper.ReadConfig(CFG) if err != nil { - return err + return err } repoSpec := ocireg.NewRepositorySpec("ghcr.io/mandelsoft/ocm", nil) repo, err := octx.RepositoryForSpec(repoSpec, cfg.GetCredentials()) if err != nil { - return err + return err } defer repo.Close() ``` @@ -27,6 +27,7 @@ the credentials directly for the lookup call: Credentials are given by an object of type [`credentials.Credentials`](../../api/credentials/interface.go). This is basically a set of string attributes. For OCM repositories based on OCI registries two attributes are used: + - `credentials.ATTR_USERNAME` the username - `credentials.ATTR_PASSWORD` the password @@ -37,13 +38,13 @@ access object is requested for a component in this repository. ```go comp, err := repo.LookupComponent(cfg.Component) if err != nil { - return errors.Wrapf(err, "cannot lookup component %s", cfg.Component) + return errors.Wrapf(err, "cannot lookup component %s", cfg.Component) } defer comp.Close() compvers, err := comp.NewVersion(cfg.Version, true) if err != nil { - return errors.Wrapf(err, "cannot create new version %s", cfg.Version) + return errors.Wrapf(err, "cannot create new version %s", cfg.Version) } defer compvers.Close() ``` @@ -60,18 +61,18 @@ some text. compvers.GetDescriptor().Provider = metav1.Provider{Name: "mandelsoft"} err=compvers.SetResourceBlob( - &compdesc.ResourceMeta{ - ElementMeta: compdesc.ElementMeta{ - Name: "test", - }, - Type: resourcetypes.BLOB, - Relation: metav1.LocalRelation, - }, - accessio.BlobAccessForString(mime.MIME_TEXT, "testdata"), - "", nil, + &compdesc.ResourceMeta{ + ElementMeta: compdesc.ElementMeta{ + Name: "test", + }, + Type: resourcetypes.BLOB, + Relation: metav1.LocalRelation, + }, + accessio.BlobAccessForString(mime.MIME_TEXT, "testdata"), + "", nil, ) if err != nil { - return errors.Wrapf(err, "cannot add resource") + return errors.Wrapf(err, "cannot add resource") } ``` @@ -80,7 +81,7 @@ the repository. ```go if err=comp.AddVersion(compvers); err != nil { - return errors.Wrapf(err, "cannot add new version") + return errors.Wrapf(err, "cannot add new version") } ``` @@ -91,15 +92,15 @@ The complete example can be found [here](cred1/example.go). If only a single repository is used during the access of a component version, the direct provisioning of credentials might be sufficient. -But even a read access might require credentials. A main task of a component +But even a read access might require credentials. A main task of a component version is to describe resource artifacts and provide access to the content of those artifacts. They may be located not only in the -actually used component repository but in any other kind of repository, which is +actually used component repository but in any other kind of repository, which is supported by an access method. So, accessing content of artifacts, as described in the main example, might -require access to any repository described by an access specification -used in a component version. +require access to any repository described by an access specification +used in a component version. Therefore, it might be required to access credentials deep in the functionality of the library, depending on data found during the processing. @@ -112,7 +113,7 @@ to describe access to credential stores (also called repositories in the context of this library). If some code requires access to dedicated credentials, it specifies the -required kind of credentials by a consumer id object. Such an object +required kind of credentials by a consumer id object. Such an object encapsulates the intended usage context. A consumer id is basically a set of usage context specific string attributes. All @@ -131,7 +132,7 @@ attributes are used to fully describe the usage context. (for OCI this is an OCI repository path) The credentials context now allows specifying credentials -for subsets of such identity specifications. When requesting +for subsets of such identity specifications. When requesting credentials for a repository those specifications are checked with a type specific identity matcher to find credentials best matching the desired usage context. For example, for the OCI context, the @@ -146,16 +147,16 @@ as follows: octx := ocm.DefaultContext() octx.CredentialsContext().SetCredentialsForConsumer( - credentials.ConsumerIdentity{ - identity.ID_TYPE: identity.CONSUMER_TYPE, - identity.ID_HOSTNAME: "ghcr.io", - identity.ID_PATHPREFIX: "mandelsoft", - }, - cfg.GetCredentials(), + credentials.ConsumerIdentity{ + identity.ID_TYPE: identity.CONSUMER_TYPE, + identity.ID_HOSTNAME: "ghcr.io", + identity.ID_PATHPREFIX: "mandelsoft", + }, + cfg.GetCredentials(), ) ``` -The given pattern does not specify all the possible attributes, therefore, it +The given pattern does not specify all the possible attributes, therefore, it matches, for example, for all ports. After the credentials have been configured for the used credentials context, @@ -167,12 +168,12 @@ as before. repo, err := octx.RepositoryForSpec(repoSpec) if err != nil { - return err + return err } defer repo.Close() ``` -This mechanism explicitly works for the implicit credential requests when +This mechanism explicitly works for the implicit credential requests when requesting resource content stored in foreign repositories requiring authentication as well as for the initial repository lookups. @@ -183,7 +184,7 @@ The complete example can be found [here](cred2/example.go). Instead of configuring credentials at the credentials context, it is possible to access standard credential stores, also. -Similar to the OCM context, the credentials context is capable to manage +Similar to the OCM context, the credentials context is capable to manage the access to arbitrary credential stores, as ong as their type is supported by the actual program context. Again, there are types for the repository/store specification and instantiation methods to map a specification @@ -208,7 +209,7 @@ file. _, err = octx.CredentialsContext().RepositoryForSpec(spec) if err != nil { - return errors.Wrapf(err, "cannot access default docker config") + return errors.Wrapf(err, "cannot access default docker config") } ``` @@ -223,7 +224,7 @@ repository for the credentials context additionally configures all the possible consumer ids. For more general stores, which just store credentials without a formal -type specific context, the mapping must be explicitly done as part of the +type specific context, the mapping must be explicitly done as part of the coding. This can be done by listing the found credentials by using a method on the credential repository object. The example above just ignores this result value, because it uses the auto-propagation mode. diff --git a/examples/lib/tour/docsrc/01-getting-started/README.md b/examples/lib/tour/docsrc/01-getting-started/README.md index d12704dd08..afff4b48af 100644 --- a/examples/lib/tour/docsrc/01-getting-started/README.md +++ b/examples/lib/tour/docsrc/01-getting-started/README.md @@ -1,4 +1,5 @@ # Basic Usage of OCM Repositories + {{getting-started}} This [tour](example.go) illustrates the basic usage of the API to @@ -16,6 +17,7 @@ version: 0.1.0 ``` {{getting-started-walkthrough}} + ## Walkthrough The basic entry point for using the OCM library is always @@ -130,7 +132,7 @@ and the resources described by the component version. This results in the following output (the shown version might differ, because the code always describes the latest version): -``` +```go {{execute}{go}{run}{../../01-getting-started}{}{version}} ``` @@ -198,7 +200,7 @@ closing the reader, again {{include}{../../01-getting-started/example.go}{closing reader}} ``` -Now, we just read the content and copy it to the intended +Now, we just read the content and copy it to the intended output file (`/tmp/ocmcli`). ```go diff --git a/examples/lib/tour/docsrc/02-composing-a-component-version/README.md b/examples/lib/tour/docsrc/02-composing-a-component-version/README.md index 6e00432e25..683d08a851 100644 --- a/examples/lib/tour/docsrc/02-composing-a-component-version/README.md +++ b/examples/lib/tour/docsrc/02-composing-a-component-version/README.md @@ -1,10 +1,12 @@ {{compose-compvers}} + # Composing a Component Version This tour illustrates the basic usage of the API to create/compose component versions. It covers two basic scenarios: + - [`basic`](01-basic-componentversion-creation.go) Create a component version stored in the file system - [`compose`](02-composition-version.go) Create a component version stored in memory using a non-persistent composition version. @@ -17,7 +19,7 @@ You can call the main program with the scenario as argument. Configuration is no ### Basic Component Version Creation The first variant just creates a new component version -in an OCM repository. To avoid the requirement for +in an OCM repository. To avoid the requirement for credentials a file system based repository is created, using the *Common Transport Format* (CTF). @@ -55,7 +57,7 @@ The result is a memory based representation, which is not yet persisted. Now, we can configure the component version. It only exists in memory so far, but is already connected to the repository. -The setup of the component version is put into a +The setup of the component version is put into a separate method (`setupVersion`), so it can be reused for the second variant. First, we configure the component version provider. @@ -100,7 +102,7 @@ Supported access types can be found under ``` Once we have both, the metadata and the content specification, -we can now add the resource to our component version. +we can now add the resource to our component version. The `SetResource` methods will replace an existing resource with the same identity, or add the resource, if no such resource exists in the component version. @@ -151,6 +153,7 @@ the resource as byte sequence. When storing the blob, it is possible to provide some optional additional information: + - a name of the resource described by the blob, which could be used to do a later upload into an external repository (for example the image repository of an OCI image stored @@ -168,7 +171,7 @@ version metadata in the same repository, no external repository is required. The above blob example describes the basic operations, -which can be used to compose any kind of resource +which can be used to compose any kind of resource from any kind of source. For selected use cases there are convenience helpers available, which can be used to compose a resource access object. @@ -189,6 +192,7 @@ contain all the required resource metadata. All kinds of `SetXXX` methods optionally accept options used to influence the target in the element list. It is possible to + - enforce an append (`ocm.AppendElement`) - enforce a dedicated index (`ocm.TargetIndex(n)`) - enforce the replacement of a dedicated element identity (`ocm.TargetIdentity(...)`) @@ -204,17 +208,18 @@ generated by docker builds. Here, we just compose a multi-platform image built with `buildx` from these sources (components/ocmcli) featuring two flavors. (you have to execute `make image.multi` in components/ocmcli -before executing this example. +before executing this example.) ```go {{include}{../../02-composing-a-component-version/01-basic-componentversion-creation.go}{setup by docker}} ``` {{composition-environment}} + ### Composition Environment The second variant just creates a new component version -in a memory based composition environment, no persistence is +in a memory based composition environment, no persistence is required. Like all component versions, such component versions can be added to any repository later. @@ -257,4 +262,4 @@ add the new component version. ```go {{include}{../../02-composing-a-component-version/02-composition-version.go}{add version}} -``` \ No newline at end of file +``` diff --git a/examples/lib/tour/docsrc/03-working-with-credentials/README.md b/examples/lib/tour/docsrc/03-working-with-credentials/README.md index 7598a5bb4e..0dfafdfb56 100644 --- a/examples/lib/tour/docsrc/03-working-with-credentials/README.md +++ b/examples/lib/tour/docsrc/03-working-with-credentials/README.md @@ -181,7 +181,7 @@ The used functions above are just convenience wrappers around the core type ConsumerId, which might be provided for dedicated repository/consumer technologies. Everything can be done directly with the core interface -and property name constants provided by the dedicted technologies. +and property name constants provided by the dedicted technologies. Once we have the id we can finally set the credentials for this id. @@ -190,9 +190,9 @@ id. {{include}{../../03-working-with-credentials/02-basic-credential-management.go}{set credentials}} ``` -Now, the context is prepared to provide credentials +Now, the context is prepared to provide credentials for any usage of our OCI registry -Let's test, whether it could provide credentials +Let's test, whether it could provide credentials for storing our component version. First, we get the repository object for our OCM repository. @@ -277,7 +277,7 @@ the access method as credential consumer can access the blob. The OCM toolset embraces multiple storage backend technologies, for OCM metadata as well -as for artifacts described by a component version. +as for artifacts described by a component version. All those technologies typically have their own way to configure credentials for command line tools or servers. @@ -346,7 +346,7 @@ specification. We are not interested in the repository object, so we just ignore the result. -So, if you have done the appropriate docker login for your +So, if you have done the appropriate docker login for your OCI registry, it should be possible now to get the credentials for the configured repository. diff --git a/examples/lib/tour/docsrc/04-working-with-config/README.md b/examples/lib/tour/docsrc/04-working-with-config/README.md index e5fc80c3e3..129ae46ae0 100644 --- a/examples/lib/tour/docsrc/04-working-with-config/README.md +++ b/examples/lib/tour/docsrc/04-working-with-config/README.md @@ -179,7 +179,7 @@ configuration file for the OCM ecosystem, as will be shown in the next example. Although the configuration of an OCM context can be done by a sequence of explicit calls according to the mechanisms -shown in the examples before, a simple convenience +shown in the examples before, a simple convenience library function is provided, which can be used to configure an OCM context and all related other contexts with a single call based on a central configuration file (`~/.ocmconfig`) @@ -214,7 +214,7 @@ the central configuration. One such repository type is the Docker config type. It reads a `dockerconfig.json` file and feeds in the credentials. -Because it is used for a dedicated purpose (credentials for +Because it is used for a dedicated purpose (credentials for OCI registries), it not only can feed the credentials, but also their mapping to consumer ids. @@ -359,7 +359,7 @@ converted to a form storable in the configuration object. {{include}{../../04-working-with-config/04-write-config-type.go}{setters}} ``` -The utility function `runtime.CheckSpecification` can be used to +The utility function `runtime.CheckSpecification` can be used to check a byte sequence to be a valid specification. It just checks for a valid YAML document featuring a non-empty `type` field: @@ -386,7 +386,7 @@ if the target is a credentials context it configures the credentials to be used for the described OCI repository similar to our [credential management example]({{using-cred-management}}). -But we want to accept more types of target objects. Therefore, we +But we want to accept more types of target objects. Therefore, we introduce an own interface declaring the methods required for applying some configuration settings. @@ -394,7 +394,7 @@ some configuration settings. {{include}{../../04-working-with-config/04-write-config-type.go}{config interface}} ``` -By checking the target object against this interface, we are able +By checking the target object against this interface, we are able to configure any kind of object, as long as it provides the necessary configuration methods. @@ -405,7 +405,7 @@ about the new type. This is done by an `init()` function in our config package. Here, we call a registration function, which gets called with a dedicated type object for the new config type. -A *type object* describes the config type, its type name, how +A *type object* describes the config type, its type name, how it is serialized and deserialized and some description. We use a standard type object, here, instead of implementing an own one. It is parameterized by the Go pointer type (`*ExampleConfigSpec`) for @@ -428,7 +428,7 @@ A usual, we gain access to our required contexts. {{include}{../../04-working-with-config/04-write-config-type.go}{default context}} ``` -To setup our environment we create our new config based on the actual settings +To setup our environment we create our new config based on the actual settings and apply it to the config context. ```go @@ -511,7 +511,7 @@ the config context it should use to configure itself. Therefore, our type contains an additional field `updater`. Its type `cpi.Updater` is a utility provided by the configuration -management, which holds a reference to a configuration context +management, which holds a reference to a configuration context and is able to configure an object based on a managed configuration watermark. It remembers which config objects from the @@ -571,7 +571,7 @@ to the config context. {{include}{../../04-working-with-config/05-write-config-consumer.go}{object}} ``` -If we ask now for a repository we will get the empty +If we ask now for a repository we will get the empty answer, because nothing is configured, yet. ```go @@ -600,4 +600,4 @@ the credential context. ```go {{include}{../../04-working-with-config/05-write-config-consumer.go}{credentials}} -``` \ No newline at end of file +``` diff --git a/examples/lib/tour/docsrc/05-transporting-component-versions/README.md b/examples/lib/tour/docsrc/05-transporting-component-versions/README.md index 93964a9077..69f3702c1f 100644 --- a/examples/lib/tour/docsrc/05-transporting-component-versions/README.md +++ b/examples/lib/tour/docsrc/05-transporting-component-versions/README.md @@ -33,7 +33,7 @@ targetRepository: ocmConfig: ``` -The actual version of the example just works with the file system +The actual version of the example just works with the file system target, because it is not possible to specify credentials for the target repository in this simple config file. But, if you specify an [OCM config file]({{ocm-config-file}}) you can add more predefined credential settings to make it possible to use @@ -65,7 +65,7 @@ provided by the config management: The context acts as factory for various model types based on specification descriptor serialization formats in YAML or JSON. -Access method specifications and repository specification are +Access method specifications and repository specification are examples for this feature. Now, we use the repository specification serialization format to diff --git a/examples/lib/transfer.md b/examples/lib/transfer.md index ab8ad2d451..14fba72dd5 100644 --- a/examples/lib/transfer.md +++ b/examples/lib/transfer.md @@ -47,18 +47,18 @@ call. `Close` calls can then simply be added by `finalize.Close(x)`. ## Creating a temporary orchestration environment -First, a temporary filesystem is created, which is then used to +First, a temporary filesystem is created, which is then used to create a CTF directory structure. ```go - // import "github.com/mandelsoft/vfs/pkg/memoryfs" - + // import "github.com/mandelsoft/vfs/pkg/memoryfs" + // create a temporary orchestration environment for a set of // component versions. We use a CTF here stored either // in a temporary filesystem folder or in memory. tmpfs, err := osfs.NewTempFileSystem() if err != nil { - return err + return err } finalize.With(func() error { return vfs.Cleanup(tmpfs) }) @@ -68,7 +68,7 @@ create a CTF directory structure. repo, err := ctf.Open(octx, accessobj.ACC_CREATE, "ctf", 0o700, accessio.PathFileSystem(tmpfs), accessio.FormatDirectory) if err != nil { - return errors.Wrapf(err, "cannot create CTF") + return errors.Wrapf(err, "cannot create CTF") } finalize.Close(repo) ``` @@ -79,10 +79,10 @@ Or, you can directly use a memory filesystem, if the size of the intended blobs very limited. The resulting repository can be used like any other OCM repository implementation -to orchestrate new component versions using the standard repository API of the +to orchestrate new component versions using the standard repository API of the OCM context. -This can be done as shown in the [credential examples](creds.md). +This can be done as shown in the [credential examples](creds.md). The next step then is to transfer the orchestrated content to another OCM repository. The basic functionality provided by the library is the transport of a dedicated @@ -90,17 +90,17 @@ component version (optionally by traversing all the component references). CTF objects support a Lister interface, which can be used to discover contained components. -This can be easily combined to transfer the complete content. First, we have +This can be easily combined to transfer the complete content. First, we have get access to the intended target repository: ```go uni, err := ocm.ParseRepo(cfg.Repository) if err != nil { - return errors.Wrapf(err, "invalid repo spec") + return errors.Wrapf(err, "invalid repo spec") } repoSpec, err := octx.MapUniformRepositorySpec(&uni) if err != nil { - return errors.Wrapf(err, "invalid repo spec") + return errors.Wrapf(err, "invalid repo spec") } // if you know you have an OCI registry based OCM repository @@ -112,7 +112,7 @@ get access to the intended target repository: // use credentials from config context (for example initialized by Configure above) target, err := octx.RepositoryForSpec(repoSpec) if err != nil { - return err + return err } finalize.Close(target) ``` @@ -139,58 +139,58 @@ target repository (`transferHandler, err := standard.New(standard.Overwrite())`. ```go lister := repo.ComponentLister() if lister == nil { - return fmt.Errorf("repo does not support lister") + return fmt.Errorf("repo does not support lister") } comps, err := lister.GetComponents("", true) if rerr != nil { - return errors.Wrapf(err, "cannot list components") + return errors.Wrapf(err, "cannot list components") } printer := common.NewPrinter(os.Stdout) closure := transfer.TransportClosure{} transferHandler, err := standard.New(standard.Overwrite()) if rerr != nil { - return err + return err } for _, cname := range comps { - loop := finalize.Nested() - - c, err := repo.LookupComponent(cname) - if err != nil { - return errors.Wrapf(err, "cannot get component %s", cname) - } - loop.Close(c) - - vnames, err := c.ListVersions() - if err != nil { - return errors.Wrapf(err, " cannot list versions for component %s", cname) - } - - for _, vname := range vnames { - loop := loop.Nested() - - cv, err := c.LookupVersion(vname) - if err != nil { - return errors.Wrapf(err, "cannot get version %s for component %s", vname, cname) - } - loop.Close(cv) - - err = transfer.TransferVersion(printer, closure, cv, target, transferHandler) - if err != nil { - return errors.Wrapf(err, "cannot transfer version %s for component %s", vname, cname) - } - - if err := loop.Finalize(); err != nil { - return err - } - } - if err := loop.Finalize(); err != nil { - return err - } + loop := finalize.Nested() + + c, err := repo.LookupComponent(cname) + if err != nil { + return errors.Wrapf(err, "cannot get component %s", cname) + } + loop.Close(c) + + vnames, err := c.ListVersions() + if err != nil { + return errors.Wrapf(err, " cannot list versions for component %s", cname) + } + + for _, vname := range vnames { + loop := loop.Nested() + + cv, err := c.LookupVersion(vname) + if err != nil { + return errors.Wrapf(err, "cannot get version %s for component %s", vname, cname) + } + loop.Close(cv) + + err = transfer.TransferVersion(printer, closure, cv, target, transferHandler) + if err != nil { + return errors.Wrapf(err, "cannot transfer version %s for component %s", vname, cname) + } + + if err := loop.Finalize(); err != nil { + return err + } + } + if err := loop.Finalize(); err != nil { + return err + } } ``` -With ` closure := transfer.TransportClosure{}` a shared transport store is +With `closure := transfer.TransportClosure{}` a shared transport store is created, which remembers already transported component versions. It is used for all calls of `TransferVersion` to avpid duplicate transfers. THis is especially relevant, if the transitive transfer option is set. @@ -222,19 +222,18 @@ create a nested finalizer specifically used inside a loop step: ```go for ... { - loop := finalize.Nested() - ... - loop.Close(c) - ... - if err := loop.Finalize(); err != nil { - return err - } + loop := finalize.Nested() + ... + loop.Close(c) + ... + if err := loop.Finalize(); err != nil { + return err + } } ``` The nested finalizer can be finalized at the end of the loop, but it is also executed once the function is left for the `defer` of -the root finalizer at the beginning of the function, if it is not yet +the root finalizer at the beginning of the function, if it is not yet executed. Once it has been explicitly called it is automatically removed from the next outer scope. - From 162d082c72ad81d69cff567ff54abb06f31abb78 Mon Sep 17 00:00:00 2001 From: Hilmar Falkenberg Date: Wed, 14 Aug 2024 10:37:23 +0200 Subject: [PATCH 06/45] fix some lint issues --- .github/ISSUE_TEMPLATE/user_story.md | 14 ++++++------ README.md | 6 ++--- .../extensions/accessmethods/github/README.md | 8 ++----- .../extensions/accessmethods/helm/README.md | 6 ++--- .../accessmethods/localblob/README.md | 22 +++++++++---------- .../extensions/accessmethods/maven/README.md | 15 +++++++------ .../extensions/accessmethods/npm/README.md | 5 +++-- .../accessmethods/ociartifact/README.md | 7 ++---- .../accessmethods/ociblob/README.md | 7 ++---- .../accessmethods/relativeociref/README.md | 8 +++---- api/ocm/extensions/accessmethods/s3/README.md | 7 ++---- .../extensions/repositories/ocireg/README.md | 11 +++------- .../handlers/rsa-signingservice/README.md | 11 +++++----- api/utils/compression/README.md | 4 ++-- .../README.md | 4 ++-- .../03-working-with-credentials/README.md | 9 ++++---- .../docsrc/04-working-with-config/README.md | 8 ++++++- .../README.md | 4 ++-- .../06-signing-component-versions/README.md | 10 ++++++--- examples/make/README.md | 11 +++++----- migrate.md | 5 ++--- 21 files changed, 88 insertions(+), 94 deletions(-) diff --git a/.github/ISSUE_TEMPLATE/user_story.md b/.github/ISSUE_TEMPLATE/user_story.md index 910a18d318..645631eefa 100644 --- a/.github/ISSUE_TEMPLATE/user_story.md +++ b/.github/ISSUE_TEMPLATE/user_story.md @@ -1,10 +1,8 @@ --- name: User Story about: User Story -labels: +labels: title: - Title - - --- **User Story**: The expressive title of your user story goes here @@ -15,13 +13,15 @@ As a [type of user], I want to [perform some task] so that I can [achieve some g This is a short text that just acts as an example for your user story. Please be as precise and verbose as required, so that people picking up the user story are clear about the intention and their tasks. **Epic link**: -- #410 (just mention the number of the related epic here, it will appear as clickable link later) + +- #410 (just mention the number of the related epic here, it will appear as clickable link later) **Acceptance criteria**: -- [ ] abc should have a red button in the center of the screen +- [ ] abc should have a red button in the center of the screen - [ ] on clicking the red button it should start to blink **Related issues**: -- #413 (just mention the number of the related issue here, it will appear as clickable link later) -- #414 (just mention the number of the related issue here, it will appear as clickable link later) + +- #413 (just mention the number of the related issue here, it will appear as clickable link later) +- #414 (just mention the number of the related issue here, it will appear as clickable link later) diff --git a/README.md b/README.md index e50c424715..c2c9b18e37 100644 --- a/README.md +++ b/README.md @@ -7,7 +7,7 @@ The Open Component Model (OCM) is an open standard to describe software bills of delivery (SBOD). OCM is a technology-agnostic and machine-readable format focused on the software artifacts that must be delivered for software products. -Check out the [the main OCM project web page](https://ocm.software) to find out what OCM offers you for implementing a secure software supply chain. It is your central entry point to all kind of OCM related [docs and guides](https://ocm.software/docs/overview/about), the [OCM specification](https://ocm.software/docs/overview/specification/) and all project [github repositories](https://github.com/open-component-model). It also offers a [Getting Started](https://ocm.software/docs/getting-started/) to quickly make your hands dirty with OCM, its toolset and concepts :smiley: +Check out the [the main OCM project web page](https://ocm.software) to find out what OCM offers you for implementing a secure software supply chain. It is your central entry point to all kind of OCM related [docs and guides](https://ocm.software/docs/overview/about), the [OCM specification](https://ocm.software/docs/overview/specification/) and all project [github repositories](https://github.com/open-component-model). It also offers a [Getting Started](https://ocm.software/docs/getting-started/) to quickly make your hands dirty with OCM, its tool set and concepts :smiley: ## OCM Specifications @@ -98,7 +98,7 @@ ocm --help git-url: https://aur.archlinux.org/ocm-cli.git package-url: https://aur.archlinux.org/packages/ocm-cli -``` +```sh # if not using a helper util git clone https://aur.archlinux.org/ocm-cli.git cd ocm-cli @@ -142,7 +142,7 @@ podman build -t ocm --build-arg GO_VERSION=1.22 --build-arg ALPINE_VERSION=3.19 An example of how to use the `ocm` CLI in a Makefile can be found in [`examples/make`](https://ocm.software/ocm/blob/main/examples/make/Makefile). -More comprehensive examples can be taken from the [`components`](https://ocm.software/ocm/tree/main/components) contained in this repository. [Here](components/helmdemo/README.md) a complete component build including a multi-arch image is done and finally packaged into a CTF archive which can be tranported into an OCI repository. See the readme files for details. +More comprehensive examples can be taken from the [`components`](https://ocm.software/ocm/tree/main/components) contained in this repository. [Here](components/helmdemo/README.md) a complete component build including a multi-arch image is done and finally packaged into a CTF archive which can be transported into an OCI repository. See the readme files for details. ## Contributing diff --git a/api/ocm/extensions/accessmethods/github/README.md b/api/ocm/extensions/accessmethods/github/README.md index f0aa50c031..2499d3e669 100644 --- a/api/ocm/extensions/accessmethods/github/README.md +++ b/api/ocm/extensions/accessmethods/github/README.md @@ -1,10 +1,9 @@ # Access Method `gitHub` and `github` - Github Commit Access +## Synopsis -### Synopsis - -``` +```yaml type: gitHub/v1 ``` @@ -19,8 +18,6 @@ GitHub repository. Supported specification version is `v1` - - ### Specification Versions #### Version `v1` @@ -39,7 +36,6 @@ The type specific specification fields are: The sha/id of the git commit - ### Go Bindings The go binding can be found [here](method.go) diff --git a/api/ocm/extensions/accessmethods/helm/README.md b/api/ocm/extensions/accessmethods/helm/README.md index f7d5075365..9bc70b3bdb 100644 --- a/api/ocm/extensions/accessmethods/helm/README.md +++ b/api/ocm/extensions/accessmethods/helm/README.md @@ -1,15 +1,16 @@ # Access Method `helm` - Helm Repository Access +## Synopsis -### Synopsis -``` +```yaml type: helm/v1 ``` Provided blobs use the following media type: attribute `application/vnd.cncf.helm.chart.content.v1.tar+gzip` ### Description + This method implements the access of a Helm chart stored in a Helm chart repository. Supported specification version is `v1` @@ -36,7 +37,6 @@ The type specific specification fields are: An optional keyring used to verify the chart. - ### Go Bindings The go binding can be found [here](method.go) diff --git a/api/ocm/extensions/accessmethods/localblob/README.md b/api/ocm/extensions/accessmethods/localblob/README.md index 6c265c019a..6283370f50 100644 --- a/api/ocm/extensions/accessmethods/localblob/README.md +++ b/api/ocm/extensions/accessmethods/localblob/README.md @@ -1,9 +1,9 @@ # Access Method `localBlob` - OCM Repository Local Blob Access +## Synopsis -### Synopsis -``` +```yaml type: localBlob/v1 ``` @@ -37,7 +37,7 @@ The type specific specification fields are: - **`mediaType`** *string* - The media type of the blob used to store the resource. It may add + The media type of the blob used to store the resource. It may add format information like `+tar` or `+gzip`. - **`referenceName`** (optional) *string* @@ -50,7 +50,7 @@ The type specific specification fields are: access method [`ociArtifact`](../../../../../docs/formats/accessmethods/ociArtifact.md) 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 + repository may then decide to make this artifact available again as regular OCI artifact. - **`globalAccess`** (optional) *access method specification* @@ -61,19 +61,18 @@ The type specific specification fields are: 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. - ### Go Bindings The go binding can be found [here](method.go) ### Storage Mapping -Transporting component versions by value internalizes externally -referenced content (for example OCI image references). Those +Transporting component versions by value internalizes externally +referenced content (for example OCI image references). Those resources will then be stored as local blobs using the media type provided by the original blob. @@ -84,10 +83,11 @@ by registered blob handlers. #### Provided Blob Handlers The standard tool set uses the following registered blob handlers: -- *Blob handler for importing oci artifact blobs into + +- *Blob handler for importing oci artifact blobs into an OCM repository mapped to an OCI registry* - In this case the oci artifact blobs will be expanded to a regular + In this case the oci artifact blobs will be expanded to a regular OCI artifact taking the optional `referenceName`into account. -Additional blob handlers might be registered by local incarnations. \ No newline at end of file +Additional blob handlers might be registered by local incarnations. diff --git a/api/ocm/extensions/accessmethods/maven/README.md b/api/ocm/extensions/accessmethods/maven/README.md index ecb696d7a6..1f4c9484c5 100644 --- a/api/ocm/extensions/accessmethods/maven/README.md +++ b/api/ocm/extensions/accessmethods/maven/README.md @@ -1,7 +1,8 @@ # `mvn` - Maven artifacts (Java packages, jars) in a Maven (mvn) repository (e.g. mvnrepository.com) -### Synopsis -``` +## Synopsis + +```yaml type: mvn/v1 ``` @@ -9,8 +10,8 @@ Provided blobs use the following media type: `application/x-tgz` ### Description -This method implements the access of a resource hosted by a maven repository or a -complete resource set denoted by a GAV (GroupId, ArtifactId, Version). +This method implements the access of a resource hosted by a maven repository or a +complete resource set denoted by a GAV (GroupId, ArtifactId, Version). ### Specification Versions @@ -44,8 +45,8 @@ The type specific specification fields are: The optional extension of the Maven (mvn) artifact -If classifier/extension is given a dedicated resource is described, -otherwise the complete resource set described by a GAV. +If classifier/extension is given a dedicated resource is described, +otherwise the complete resource set described by a GAV. Only complete resource sets can be uploaded again to a Maven repository. #### Examples @@ -86,7 +87,7 @@ resources: access: type: mvn repository: https://repo1.maven.org/maven2 - groupId: com.sap.cloud.sdk + groupId: com.sap.cloud.sdk artifactId: sdk-modules-bom version: 5.7.0 classifier: '' diff --git a/api/ocm/extensions/accessmethods/npm/README.md b/api/ocm/extensions/accessmethods/npm/README.md index dc69976a8c..4a4e30625c 100644 --- a/api/ocm/extensions/accessmethods/npm/README.md +++ b/api/ocm/extensions/accessmethods/npm/README.md @@ -1,7 +1,8 @@ # `npm` - NPM packages in a NPM registry (e.g. npmjs.com) -### Synopsis -``` +## Synopsis + +```yaml type: npm/v1 ``` diff --git a/api/ocm/extensions/accessmethods/ociartifact/README.md b/api/ocm/extensions/accessmethods/ociartifact/README.md index 5b3b14b547..beb5828462 100644 --- a/api/ocm/extensions/accessmethods/ociartifact/README.md +++ b/api/ocm/extensions/accessmethods/ociartifact/README.md @@ -1,10 +1,9 @@ # Access Method `ociArtifact` and `ociRegistry` - OCI Artifact Access +## Synopsis -### Synopsis - -``` +```yaml type: ociArtifact/v1 ``` @@ -24,8 +23,6 @@ This method implements the access of an OCI artifact stored in an OCI registry. Supported specification version is `v1` - - ### Specification Versions #### Version `v1` diff --git a/api/ocm/extensions/accessmethods/ociblob/README.md b/api/ocm/extensions/accessmethods/ociblob/README.md index 38eed10cb0..7a14421d27 100644 --- a/api/ocm/extensions/accessmethods/ociblob/README.md +++ b/api/ocm/extensions/accessmethods/ociblob/README.md @@ -1,9 +1,9 @@ # Access Method `ociBlob` - OCI Blob Access +## Synopsis -### Synopsis -``` +```yaml type: ociBlob/v1 ``` @@ -14,8 +14,6 @@ This method implements the access of an OCI blob stored in an OCI repository. Supported specification version is `v1` - - ### Specification Versions #### Version `v1` @@ -38,7 +36,6 @@ The type specific specification fields are: The size of the blob - ### Go Bindings The go binding can be found [here](method.go) diff --git a/api/ocm/extensions/accessmethods/relativeociref/README.md b/api/ocm/extensions/accessmethods/relativeociref/README.md index a08466d4f5..4fc93f4897 100644 --- a/api/ocm/extensions/accessmethods/relativeociref/README.md +++ b/api/ocm/extensions/accessmethods/relativeociref/README.md @@ -1,10 +1,9 @@ # Access Method `relativeOciReference` - OCI Artifact Access in OCI-registry-based OCM Repository +## Synopsis -### Synopsis - -``` +```yaml type: relativeOciReference/v1 ``` @@ -30,10 +29,9 @@ the access specification. Supported specification version is `v1` - ### Specification Versions -This access method is a legacy access method formerly used to enable +This access method is a legacy access method formerly used to enable physical replication of OCI registry content together with referenced OCI artifacts. This should basically be done by a value transport of the component versions, because it diff --git a/api/ocm/extensions/accessmethods/s3/README.md b/api/ocm/extensions/accessmethods/s3/README.md index 3ecb362d09..6198e6733b 100644 --- a/api/ocm/extensions/accessmethods/s3/README.md +++ b/api/ocm/extensions/accessmethods/s3/README.md @@ -1,8 +1,8 @@ # `s3` - Blobs in a Simple Storage System (S3) +## Synopsis -### Synopsis -``` +```yaml type: s3/v1 ``` @@ -12,7 +12,6 @@ Provided blobs use the following media type: attribute `mediaType` This method implements the access of a blob stored in an S3 bucket. - ### Specification Versions Supported specification version is `v1` @@ -32,5 +31,3 @@ The type specific specification fields are: - **`key`** *string* The key of the desired blob - - diff --git a/api/ocm/extensions/repositories/ocireg/README.md b/api/ocm/extensions/repositories/ocireg/README.md index e7df056359..2315b445d2 100644 --- a/api/ocm/extensions/repositories/ocireg/README.md +++ b/api/ocm/extensions/repositories/ocireg/README.md @@ -1,10 +1,8 @@ - # Repository `OCIRegistry` and `ociRegistry` - OCI Registry based OCM Repositories +## Synopsis -### Synopsis - -``` +```yaml type: OCIRegistry/v1 ``` @@ -15,8 +13,6 @@ a dedicated OCI repository name prefix. Supported specification version is `v1`. - - ### Specification Versions #### Version `v1` @@ -34,9 +30,8 @@ The type specific specification fields are: the OCI repository prefix used for the OCM repository. - **`componentNameMapping`** (optional) *string* (deprecated) - - the mapping algorithm used to map OCM component names to OCU repository names ( `urlPath` (default) or `sha256-digest`). + the mapping algorithm used to map OCM component names to OCU repository names ( `urlPath` (default) or `sha256-digest`). ### Go Bindings diff --git a/api/tech/signing/handlers/rsa-signingservice/README.md b/api/tech/signing/handlers/rsa-signingservice/README.md index 3cfa045350..7faa330f3b 100644 --- a/api/tech/signing/handlers/rsa-signingservice/README.md +++ b/api/tech/signing/handlers/rsa-signingservice/README.md @@ -1,6 +1,6 @@ -## Signing Service +# Signing service -The type `rsa-signingservice` forwards the signing to a +The type `rsa-signingservice` forwards the signing to a signing server. The calculated digest is sent as signing request together with the used hash algorithm @@ -11,11 +11,12 @@ It must has the field `url` with the desired server address. The required credentials are taken from the credentials context using the consumer id `Signingserver.gardener.cloud`. -If uses a hostpath matcher using the identity attrutes `scheme`, `hostname`, +It uses a host path matcher using the identity attributes `scheme`, `hostname`, `port` and `pathprefix` derived from the given server URL. The expected credential properties are: -- **`clientCert`**: the client certificate used as TLS certificate and + +- **`clientCert`**: the client certificate used as TLS certificate and to authenticate the caller. - **`privateKey`**: the private key for the client certificate. -- **`caCerts`**: the CA used to validate the identity of the signining server. \ No newline at end of file +- **`caCerts`**: the CA used to validate the identity of the signing server. diff --git a/api/utils/compression/README.md b/api/utils/compression/README.md index 0c34efee42..3111ccd82d 100644 --- a/api/utils/compression/README.md +++ b/api/utils/compression/README.md @@ -1,3 +1,3 @@ This package has been taken from github.com/containers/image and -adjusted to provide an algorithn interface instead of an internal -struct. It also transparently support an None compression. \ No newline at end of file +adjusted to provide an algorithm interface instead of an internal +struct. It also transparently support a None compression. diff --git a/examples/lib/tour/docsrc/02-composing-a-component-version/README.md b/examples/lib/tour/docsrc/02-composing-a-component-version/README.md index 683d08a851..cbc9bf0b87 100644 --- a/examples/lib/tour/docsrc/02-composing-a-component-version/README.md +++ b/examples/lib/tour/docsrc/02-composing-a-component-version/README.md @@ -1,7 +1,7 @@ -{{compose-compvers}} - # Composing a Component Version +{{compose-compvers}} + This tour illustrates the basic usage of the API to create/compose component versions. diff --git a/examples/lib/tour/docsrc/03-working-with-credentials/README.md b/examples/lib/tour/docsrc/03-working-with-credentials/README.md index 0dfafdfb56..37a4775192 100644 --- a/examples/lib/tour/docsrc/03-working-with-credentials/README.md +++ b/examples/lib/tour/docsrc/03-working-with-credentials/README.md @@ -1,12 +1,14 @@ -{{credentials}} # Working with Credentials +{{credentials}} + This tour illustrates the basic handling of credentials using the OCM library. The library provides an extensible framework to bring together credential providers and credential consunmers in a technology-agnostic way. It covers four basic scenarios: + - [`basic`](01-using-credentials.go) Writing to a repository with directly specified credentials. - [`context`](02-basic-credential-management.go) Using credentials via the credential management to publish a component version. - [`read`](02-basic-credential-management.go) Read the previously created component version using the credential management. @@ -89,6 +91,7 @@ just look up the actually added version to verify the result. The coding for `describeVersion` is similar to the one shown in the [first tour]({{describe-version}}). {{using-cred-management}} + ### Using the Credential Management Passing credentials directly at the repository @@ -115,7 +118,6 @@ As usual, we start with the default OCM context. It is now used to gain access to the appropriate credential context. - ```go {{include}{../../03-working-with-credentials/02-basic-credential-management.go}{cred context}} ``` @@ -275,7 +277,7 @@ the access method as credential consumer can access the blob. ### Providing credentials via credential repositories -The OCM toolset embraces multiple storage +The OCM tool set embraces multiple storage backend technologies, for OCM metadata as well as for artifacts described by a component version. All those technologies typically have their own @@ -297,7 +299,6 @@ credentials for dedicated OCI registries. We start again by providing access to the OCM context and the connected credential context. - ```go {{include}{../../03-working-with-credentials/03-credential-repositories.go}{context}} ``` diff --git a/examples/lib/tour/docsrc/04-working-with-config/README.md b/examples/lib/tour/docsrc/04-working-with-config/README.md index 129ae46ae0..7df66e7820 100644 --- a/examples/lib/tour/docsrc/04-working-with-config/README.md +++ b/examples/lib/tour/docsrc/04-working-with-config/README.md @@ -1,12 +1,14 @@ -{{config}} # Working with Configurations +{{config}} + This tour illustrates the basic configuration management included in the OCM library. The library provides an extensible framework to bring together configuration settings and configurable objects. It covers five basic scenarios: + - [`basic`](01-basic-config-management.go) Basic configuration management illustrating the configuration of credentials. - [`generic`](02-handle-arbitrary-config.go) Handling of arbitrary configuration. - [`ocm`](03-using-ocm-config.go) Central configuration @@ -195,6 +197,7 @@ credentials, default repositories, signing keys and any other configuration specification. {{ocm-config-file}} + #### Standard Configuration File Most important are here the credentials. @@ -240,6 +243,7 @@ default initial OCM configuration file. ``` The result should look similar to (but with reordered fields): + ```yaml type: generic.config.ocm.software configurations: @@ -296,6 +300,7 @@ config object will contain the read file content, which is hopefully a valid certificate. {{tour04-arbitrary}} + ### Providing new config object types So far, we just used existing config types to configure existing objects. @@ -489,6 +494,7 @@ for some kind of ad-hoc configuration. A complete scenario is shown in the next example. {{consume-config}} + ### Preparing Objects to be Configured by the Config Management We already have our new acme.org config object type, diff --git a/examples/lib/tour/docsrc/05-transporting-component-versions/README.md b/examples/lib/tour/docsrc/05-transporting-component-versions/README.md index 69f3702c1f..2906199306 100644 --- a/examples/lib/tour/docsrc/05-transporting-component-versions/README.md +++ b/examples/lib/tour/docsrc/05-transporting-component-versions/README.md @@ -1,6 +1,7 @@ -{{transport}} # Transporting Component Versions +{{transport}} + This [tour](example.go) illustrates the basic support for transporting content from one environment into another. @@ -115,7 +116,6 @@ be migrated to local blobs. Now, we check the result of our transport action in the target repository. - ```go {{include}{../../05-transporting-component-versions/example.go}{verify-a}} {{include}{../../05-transporting-component-versions/example.go}{verify-b}} diff --git a/examples/lib/tour/docsrc/06-signing-component-versions/README.md b/examples/lib/tour/docsrc/06-signing-component-versions/README.md index ca27322f0e..0c0e0d5d4c 100644 --- a/examples/lib/tour/docsrc/06-signing-component-versions/README.md +++ b/examples/lib/tour/docsrc/06-signing-component-versions/README.md @@ -1,10 +1,12 @@ -{{signing}} # Signing Component Versions +{{signing}} + This tour illustrates the basic functionality to sign and verify signatures. It covers two basic scenarios: + - [`sign`](01-basic-signing.go) Create, Sign, Transport and Verify a component version. - [`context`](02-using-context-settings.go) Using context settings to configure signing and verification in target repo. @@ -37,6 +39,7 @@ As usual, we start with getting access to an OCM context ```go {{include}{../../06-signing-component-versions/01-basic-signing.go}{default context}} ``` + Then, we configure this context with optional ocm config defined in our config file. See [OCM config scenario in tour 04]({{ocm-config-file}}). @@ -96,6 +99,7 @@ target version. ``` {{signing-context}} + ### Using Context Settings to Configure Signing Instead of providing all signing relevant information directly with @@ -159,7 +163,7 @@ Now, we manually add the keys to our context. ``` We are prepared now and can sign any component version without specifying further options -in any repository for the signature name `acme.org`. +in any repository for the signature name `acme.org`. Therefore, we just get the component version from the prepared repository @@ -217,4 +221,4 @@ And here is a sample output containing the public and private key. ```yaml {{execute}{go}{run}{../../06-signing-component-versions}{--config}{settings.yaml}{config}{}{ocmconfig}} -``` \ No newline at end of file +``` diff --git a/examples/make/README.md b/examples/make/README.md index 17868d3add..70d2338414 100644 --- a/examples/make/README.md +++ b/examples/make/README.md @@ -2,11 +2,12 @@ This example shows how a GitOps template can be manged via OCM tooling. -It is used to deliver deploy content and +It is used to deliver deploy content and a filesystem content template for a GitOps -environment. It additionally provides some +environment. It additionally provides some tiny tooling to manage upgrades on customer side, including + - creating a new landscape based on a GitOps template - provide new versions in the customer environment - upgrade existing landscape projects (branches) based @@ -17,7 +18,7 @@ The ops part is left blank, any environment, for example Flux can be used here. The template projects is managed with *make*. -It can be used to create new versions (patch, mino, major) -and to build a component version that can later be -by the OCM toolset on the client side to import new +It can be used to create new versions (patch, minor, major) +and to build a component version that can later be +by the OCM tool set on the client side to import new versions in a customer environment. diff --git a/migrate.md b/migrate.md index 4fce985aa4..8262d6038e 100644 --- a/migrate.md +++ b/migrate.md @@ -1,6 +1,6 @@ # Migration to the new package structure -The migration to the new package sturcture was done with the Bash script +The migration to the new package structure was done with the Bash script `migrate.sh`. It can be used to repeat the migration after changes to the original structure. Options: @@ -9,7 +9,7 @@ Options: - `--module` adapt module name (to ocm.software/ocm) - `--migrator ` create a migration script usable to migrate projects using this library -# Migrating projects using this library +## Migrating projects using this library The migration was done creating a migration script `migration.mig`. It can be used to migrate packages or whole projects using this library to the new package structure and module name. @@ -19,4 +19,3 @@ It is executed by using the same migration Bash script `migrate.sh` using the op Optionally, package paths can be added as additional arguments to the command line. By default, the complete current working directory is migrated. - From 02547f7cd50fb7393c5ec5131f799cc91b7f104a Mon Sep 17 00:00:00 2001 From: Hilmar Falkenberg Date: Wed, 14 Aug 2024 11:10:36 +0200 Subject: [PATCH 07/45] more expressive GHA job names --- .github/workflows/lint_and_test.yaml | 4 ++-- .github/workflows/reuse_helper_tool.yaml | 2 +- .github/workflows/verify-md.yml | 4 ++-- 3 files changed, 5 insertions(+), 5 deletions(-) diff --git a/.github/workflows/lint_and_test.yaml b/.github/workflows/lint_and_test.yaml index 45630abc63..08a037170f 100644 --- a/.github/workflows/lint_and_test.yaml +++ b/.github/workflows/lint_and_test.yaml @@ -39,8 +39,8 @@ jobs: run: | PATH=$PATH:$(go env GOPATH)/bin make build install-requirements test - lint: - name: Lint + go-lint: + name: Lint Golang runs-on: large_runner steps: - name: Checkout diff --git a/.github/workflows/reuse_helper_tool.yaml b/.github/workflows/reuse_helper_tool.yaml index 264144dcec..ffd49ec236 100644 --- a/.github/workflows/reuse_helper_tool.yaml +++ b/.github/workflows/reuse_helper_tool.yaml @@ -3,7 +3,7 @@ name: REUSE Compliance Check on: [push, pull_request] jobs: - test: + reuse: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 diff --git a/.github/workflows/verify-md.yml b/.github/workflows/verify-md.yml index 47b534da56..c32c900ca1 100644 --- a/.github/workflows/verify-md.yml +++ b/.github/workflows/verify-md.yml @@ -11,9 +11,9 @@ on: - '**/*.md' jobs: - lint-markdown: + markdown-lint: runs-on: ubuntu-latest - name: Lint + name: Lint Markdown steps: - uses: actions/checkout@v4 - name: Markdown Linting From cb104086fb44acfb2fd289d441f9257da3e13cca Mon Sep 17 00:00:00 2001 From: Hilmar Falkenberg Date: Wed, 14 Aug 2024 12:23:41 +0200 Subject: [PATCH 08/45] fix links --- README.md | 27 ++++++++++++--------------- 1 file changed, 12 insertions(+), 15 deletions(-) diff --git a/README.md b/README.md index c2c9b18e37..4254b8dbeb 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,8 @@ # Open Component Model [![OpenSSF Best Practices](https://bestpractices.coreinfrastructure.org/projects/7156/badge)](https://bestpractices.coreinfrastructure.org/projects/7156) -[![REUSE status](https://api.reuse.software/badge/ocm.software/ocm)](https://api.reuse.software/info/ocm.software/ocm) -[![OCM Integration Tests](https://ocm.software/ocm-integrationtest/actions/workflows/integrationtest.yaml/badge.svg?branch=main)](https://open-component-model.github.io/ocm-integrationtest/report.html) +[![REUSE status](https://api.reuse.software/badge/github.com/open-component-model/ocm)](https://api.reuse.software/info/github.com/open-component-model/ocm) +[![OCM Integration Tests](https://github.com/open-component-model/ocm-integrationtest/actions/workflows/integrationtest.yaml/badge.svg?branch=main)](https://open-component-model.github.io/ocm-integrationtest/report.html) [![Go Report Card](https://goreportcard.com/badge/ocm.software/ocm)](https://goreportcard.com/report/ocm.software/ocm) The Open Component Model (OCM) is an open standard to describe software bills of delivery (SBOD). OCM is a technology-agnostic and machine-readable format focused on the software artifacts that must be delivered for software products. @@ -11,14 +11,14 @@ Check out the [the main OCM project web page](https://ocm.software) to find out ## OCM Specifications -OCM describes delivery [artifacts](https://ocm.software/ocm-spec/tree/main/doc/01-model/02-elements-toplevel.md#artifacts-resources-and-sources) that can be accessed from many types of [component repositories](https://ocm.software/ocm-spec/tree/main/doc/01-model/01-model.md#component-repositories). It defines a set of semantic, formatting, and other types of specifications that can be found in the [`ocm-spec` repository](https://ocm.software/ocm-spec). Start learning about the core concepts of OCM elements [here](https://ocm.software/ocm-spec/tree/main/doc/01-model/02-elements-toplevel.md#model-elements). +OCM describes delivery [artifacts](https://github.com/open-component-model/ocm-spec/tree/main/doc/01-model/02-elements-toplevel.md#artifacts-resources-and-sources) that can be accessed from many types of [component repositories](https://github.com/open-component-model/ocm-spec/tree/main/doc/01-model/01-model.md#component-repositories). It defines a set of semantic, formatting, and other types of specifications that can be found in the [`ocm-spec` repository](https://github.com/open-component-model/ocm-spec). Start learning about the core concepts of OCM elements [here](https://github.com/open-component-model/ocm-spec/tree/main/doc/01-model/02-elements-toplevel.md#model-elements). ## OCM Library This project provides a Go library containing an API for interacting with the -[Open Component Model (OCM)](https://ocm.software/ocm-spec) elements and mechanisms. +[Open Component Model (OCM)](https://github.com/open-component-model/ocm-spec) elements and mechanisms. -The library currently supports the following [repository mappings](https://ocm.software/ocm-spec/tree/main/doc/03-persistence/02-mappings.md#mappings-for-ocm-persistence): +The library currently supports the following [repository mappings](https://github.com/open-component-model/ocm-spec/tree/main/doc/03-persistence/02-mappings.md#mappings-for-ocm-persistence): - **OCI**: Use the repository prefix path of an OCI repository to implement an OCM repository. @@ -36,16 +36,14 @@ Additionally, OCM provides a generic solution for how to: - Transport component versions, per reference or as values to any of the repository implementations. -## OCM CLI +## [OCM CLI](docs/reference/ocm.md) The [`ocm` CLI](docs/reference/ocm.md) may also be used to interact with OCM mechanisms. It makes it easy to create component versions and embed them in build processes. -The `ocm` CLI documentation can be found [here](<(https://ocm.software/ocm/blob/main/docs/reference/ocm.md)>). - -The code for the CLI can be found in [package `cmds/ocm`](https://ocm.software/ocm/blob/main/cmds/ocm). +The code for the CLI can be found in [package `cmds/ocm`](cmds/ocm). The OCI and OCM support can be found in packages -[`pkg/contexts/oci`](pkg/contexts/oci) and [`api/ocm`](api/ocm). +[`api/oci`](api/oci) and [`api/ocm`](api/ocm). ## Installation @@ -56,7 +54,7 @@ Install the latest release from any of - [AUR](https://aur.archlinux.org/packages/ocm-cli) - [Docker](https://www.docker.com/) - [Podman](https://podman.io/) -- [GitHub Releases](https://ocm.software/ocm/releases) +- [GitHub Releases](https://github.com/open-component-model/ocm/releases) ### Bash @@ -95,7 +93,6 @@ ocm --help ### Install from AUR (Arch Linux User Repository) -git-url: https://aur.archlinux.org/ocm-cli.git package-url: https://aur.archlinux.org/packages/ocm-cli ```sh @@ -140,9 +137,9 @@ podman build -t ocm --build-arg GO_VERSION=1.22 --build-arg ALPINE_VERSION=3.19 ## Examples -An example of how to use the `ocm` CLI in a Makefile can be found in [`examples/make`](https://ocm.software/ocm/blob/main/examples/make/Makefile). +An example of how to use the `ocm` CLI in a Makefile can be found in [`examples/make`](examples/make/Makefile). -More comprehensive examples can be taken from the [`components`](https://ocm.software/ocm/tree/main/components) contained in this repository. [Here](components/helmdemo/README.md) a complete component build including a multi-arch image is done and finally packaged into a CTF archive which can be transported into an OCI repository. See the readme files for details. +More comprehensive examples can be taken from the [`components`](components) contained in this repository. [Here](components/helmdemo/README.md) a complete component build including a multi-arch image is done and finally packaged into a CTF archive which can be transported into an OCI repository. See the readme files for details. ## Contributing @@ -154,4 +151,4 @@ OCM follows the [CNCF Code of Conduct](https://github.com/cncf/foundation/blob/m Copyright 2024 SAP SE or an SAP affiliate company and Open Component Model contributors. Please see our [LICENSE](LICENSE) for copyright and license information. -Detailed information including third-party components and their licensing/copyright information is available [via the REUSE tool](https://api.reuse.software/info/ocm.software/ocm). +Detailed information including third-party components and their licensing/copyright information is available [via the REUSE tool](https://api.reuse.software/info/github.com/open-component-model/ocm). From d6fc3fc5d9bf4af0815fbf99aa75c731215c0d7b Mon Sep 17 00:00:00 2001 From: Hilmar Falkenberg Date: Wed, 14 Aug 2024 14:19:17 +0200 Subject: [PATCH 09/45] fix lint and link issues --- api/oci/extensions/repositories/ctf/README.md | 12 +++++------- api/oci/extensions/repositories/docker/README.md | 7 +++---- api/oci/extensions/repositories/ocireg/README.md | 8 +++----- api/ocm/extensions/repositories/comparch/README.md | 7 ++----- api/ocm/extensions/repositories/ctf/README.md | 9 +++------ api/ocm/extensions/repositories/ocireg/README.md | 2 +- 6 files changed, 17 insertions(+), 28 deletions(-) diff --git a/api/oci/extensions/repositories/ctf/README.md b/api/oci/extensions/repositories/ctf/README.md index a3c0ac55ca..89d9ba47d4 100644 --- a/api/oci/extensions/repositories/ctf/README.md +++ b/api/oci/extensions/repositories/ctf/README.md @@ -1,10 +1,8 @@ - # Repository `CommonTransportFormat` - Filesystem-based Storage of OCI repositories +## Synopsis -### Synopsis - -``` +```yaml type: CommonTransportFormat/v1 ``` @@ -31,14 +29,14 @@ The type specific specification fields are: - `directory`: stored as file hierarchy in a directory - `tar`: stored as file hierarchy in a TAR file - `tgz`: stored as file hierarchy in a GNU-zipped TAR file (tgz) - + - **`accessMode`** (optional) *byte* Access mode used to access the content: - 0: write access - 1: read-only - 2: create id not existent, yet - + ### Go Bindings -The Go binding can be found [here](type.go) \ No newline at end of file +The Go binding can be found [here](type.go) diff --git a/api/oci/extensions/repositories/docker/README.md b/api/oci/extensions/repositories/docker/README.md index 6747086279..a3acbf677d 100644 --- a/api/oci/extensions/repositories/docker/README.md +++ b/api/oci/extensions/repositories/docker/README.md @@ -1,10 +1,8 @@ - # Repository `DockerDaemon` - Images stored in a Docker Daemon +## Synopsis -### Synopsis - -``` +```yaml type: DockerDaemon/v1 ``` @@ -14,6 +12,7 @@ This repository type provides a mapping of the image repository behind a docker daemon to the OCI registry access API. This is only possible with a set of limitation: + - It is only possible to store and access flat images - There is no access by digests, only by tags. - The docker image id can be used as pseudo digest (without algorithm) diff --git a/api/oci/extensions/repositories/ocireg/README.md b/api/oci/extensions/repositories/ocireg/README.md index 359fb4f032..e45a295ba2 100644 --- a/api/oci/extensions/repositories/ocireg/README.md +++ b/api/oci/extensions/repositories/ocireg/README.md @@ -1,10 +1,8 @@ +# Repository `OCIRegistry` and `ociRegistry` - OCI Registry -# Repository `OCIRegistry` and `ociRegistry` - OCI Registry +## Synopsis - -### Synopsis - -``` +```yaml type: OCIRegistry/v1 ``` diff --git a/api/ocm/extensions/repositories/comparch/README.md b/api/ocm/extensions/repositories/comparch/README.md index 0ef027dd7b..6ff5642562 100644 --- a/api/ocm/extensions/repositories/comparch/README.md +++ b/api/ocm/extensions/repositories/comparch/README.md @@ -1,10 +1,8 @@ - # Repository `ComponentArchive` - Filesystem based Storage of a Component Version +## Synopsis -### Synopsis - -``` +```yaml type: ComponentArchive/v1 ``` @@ -33,7 +31,6 @@ The type specific specification fields are: - `tar`: stored as directory structure in a tar file - `tgz`: stored as directory structure in a tar file compressed by GNU Zip - ### Go Bindings The Go binding can be found [here](type.go). diff --git a/api/ocm/extensions/repositories/ctf/README.md b/api/ocm/extensions/repositories/ctf/README.md index 22bd5f73ed..bdf0ca1d7d 100644 --- a/api/ocm/extensions/repositories/ctf/README.md +++ b/api/ocm/extensions/repositories/ctf/README.md @@ -1,10 +1,8 @@ - # Repository `CommonTransportFormat` - Filesystem based OCM Repositories +## Synopsis -### Synopsis - -``` +```yaml type: CommonTransportFormat/v1 ``` @@ -31,7 +29,6 @@ The type specific specification fields are: - `tar`: stored as directory structure in a tar file - `tgz`: stored as directory structure in a tar file compressed by GNU Zip. - ### Go Bindings -The Go binding can be found [here](../../../../../pkg/contexts/oci/repositories/ctf/type.go). +The Go binding can be found [here](type.go). diff --git a/api/ocm/extensions/repositories/ocireg/README.md b/api/ocm/extensions/repositories/ocireg/README.md index 2315b445d2..645f0fd2ce 100644 --- a/api/ocm/extensions/repositories/ocireg/README.md +++ b/api/ocm/extensions/repositories/ocireg/README.md @@ -35,4 +35,4 @@ The type specific specification fields are: ### Go Bindings -The Go binding can be found [here](../../../../../pkg/contexts/oci/repositories/ocireg/type.go). +The Go binding can be found [here](type.go). From 336ee82416bd97d28eceadb3fa4e4c8450a79fb0 Mon Sep 17 00:00:00 2001 From: Hilmar Falkenberg Date: Wed, 14 Aug 2024 16:15:38 +0200 Subject: [PATCH 10/45] fix more links --- .markdown-link-check.json | 2 +- .../accessmethods/localblob/README.md | 2 +- .../accessmethods/ociartifact/README.md | 2 +- .../accessmethods/relativeociref/README.md | 4 +- api/ocm/ocmutils/localize/README.md | 15 ++++--- examples/lib/README.md | 43 ++++++++++--------- examples/lib/creds.md | 24 +++++------ .../tour/docsrc/01-getting-started/README.md | 4 +- .../README.md | 4 +- .../03-working-with-credentials/README.md | 11 +++-- .../docsrc/04-working-with-config/README.md | 10 ++--- .../06-signing-component-versions/README.md | 4 +- examples/lib/transfer.md | 6 +-- 13 files changed, 66 insertions(+), 65 deletions(-) diff --git a/.markdown-link-check.json b/.markdown-link-check.json index 9a2ab70be6..e79bc1789a 100644 --- a/.markdown-link-check.json +++ b/.markdown-link-check.json @@ -1,5 +1,5 @@ { "replacementPatterns": [ - { "pattern": "^/", "replacement": "/github/workspace/" } + { "pattern": "^/", "replacement": "{{BASEURL}}/" } ], "ignorePatterns": [ { "pattern": "^http[s]*://localhost.*" } diff --git a/api/ocm/extensions/accessmethods/localblob/README.md b/api/ocm/extensions/accessmethods/localblob/README.md index 6283370f50..345ac11efe 100644 --- a/api/ocm/extensions/accessmethods/localblob/README.md +++ b/api/ocm/extensions/accessmethods/localblob/README.md @@ -47,7 +47,7 @@ The type specific specification fields are: related to the original source. For example, if an OCI artifact originally referenced using the - access method [`ociArtifact`](../../../../../docs/formats/accessmethods/ociArtifact.md) is stored during + access method [`ociArtifact`](../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 diff --git a/api/ocm/extensions/accessmethods/ociartifact/README.md b/api/ocm/extensions/accessmethods/ociartifact/README.md index beb5828462..fba83365e8 100644 --- a/api/ocm/extensions/accessmethods/ociartifact/README.md +++ b/api/ocm/extensions/accessmethods/ociartifact/README.md @@ -14,7 +14,7 @@ Provided blobs use the following media type: Depending on the repository appropriate docker legacy types might be used. -The artifact content is provided in the [Artifact Set Format](../../../../../pkg/contexts/oci/repositories/ctf/formatspec.md#artifact-set-archive-format). +The artifact content is provided in the [Artifact Set Format](/api/oci/extensions/repositories/ctf/formatspec.md#artifact-set-archive-format). The tag is provided as annotation. ### Description diff --git a/api/ocm/extensions/accessmethods/relativeociref/README.md b/api/ocm/extensions/accessmethods/relativeociref/README.md index 4fc93f4897..32f720b43c 100644 --- a/api/ocm/extensions/accessmethods/relativeociref/README.md +++ b/api/ocm/extensions/accessmethods/relativeociref/README.md @@ -14,7 +14,7 @@ Provided blobs use the following media type: Depending on the repository appropriate docker legacy types might be used. -The artifact content is provided in the [Artifact Set Format](../../../../../pkg/contexts/oci/repositories/ctf/formatspec.md#artifact-set-archive-format). +The artifact content is provided in the [Artifact Set Format](/api/oci/extensions/repositories/ctf/formatspec.md#artifact-set-archive-format). The tag is provided as annotation. ### Description @@ -22,7 +22,7 @@ The tag is provided as annotation. This method implements the access of an OCI artifact stored in an OCI registry, which is used to host the OCM repository the component version is retrieved from. -It works similar to the [`ociArtifact`](../../../../../pkg/contexts/ocm/accessmethods/ociartifact/README.md) access method, +It works similar to the [`ociArtifact`](../ociartifact) access method, but the used reference does not contain the OCI registry host, which is taken from the OCI registry used to host the component version containing the access specification. diff --git a/api/ocm/ocmutils/localize/README.md b/api/ocm/ocmutils/localize/README.md index 216c8d4dfb..6be8c00f35 100644 --- a/api/ocm/ocmutils/localize/README.md +++ b/api/ocm/ocmutils/localize/README.md @@ -5,7 +5,8 @@ yaml format definitions, (format.go) given by a Go structure. and functions usable for the modification of filesystem snapshots. It covers -- OCM based localization descriptions used to describe image + +- OCM based localization descriptions used to describe image location substitution and the - merging with configuration input. @@ -15,7 +16,7 @@ an installation specific snapshot incorporating the local location of container images based on OCM component versions and installation specific configuration values. -The description format describes two basic specifications that incorporate external +The description format describes two basic specifications that incorporate external information provided by a component version or some user config. - struct/format `Localization` describe a specification to @@ -26,7 +27,7 @@ information provided by a component version or some user config. This specification is intended to be stored as part of a resource artifact in a component version which is then used to apply it. Thereby the contained relative - [resource reference](../../../../docs/ocm/model.md#resource-reference) + [resource reference](https://github.com/open-component-model/ocm-spec/blob/main/doc/05-guidelines/03-references.md) are evaluated against the component version containing the specification to resolve the final image location. @@ -34,7 +35,7 @@ information provided by a component version or some user config. applying a dedicated config value taken from a configuration source to a filesytem snapshot. -The function `Localize` and `Configure` accept a list of such +The function `Localize` and `Configure` accept a list of such specifications and map them into an environment agnostic set of `Substitution` specifications, which contain resolved data values, only. A third function `Substitute` takes those environment agnostic specifications @@ -44,15 +45,15 @@ Finally, a compound specification `InstantiationRules` is provided, that combines all those descriptions with the specification of the snapshot resource and further helper parts, like json scheme validation for config files. -Such a specification object can be applied by the function `Instantiate` +Such a specification object can be applied by the function `Instantiate` together with configuration values to a component version. As substitution result it returns a virtual filesystem with the snapshot according to the resolved substitutions. To get access to the template resource containing the filesystem snapshot to be instantiated, the configured downloaders (package `pkg/context/ocm/download`) is used. -Therefore, this method can be used together with any own resource type as long as +Therefore, this method can be used together with any own resource type as long as an appropriate downloader is configured. Additionally, there is a set of more basic types and methods, which can be used to describe end execute localizations for single data objects (see `ImageMappings`, -`LocalizeMappings` and `SubstituteMappings`). \ No newline at end of file +`LocalizeMappings` and `SubstituteMappings`). diff --git a/examples/lib/README.md b/examples/lib/README.md index ae4dcd7a5d..8ff482a326 100644 --- a/examples/lib/README.md +++ b/examples/lib/README.md @@ -10,7 +10,7 @@ managed in the dedicated area. The examples shown here provide an overview of the library. A more detailed annotated tour through various aspects of the library -with ready-to work examples can be for [here](tour/READ;E.md). +with ready-to work examples can be for [here](tour). In the [comparison scenario](comparison-scenario/README.md) there is an example for an end-to-end scenario, from providing a component version @@ -22,7 +22,7 @@ as productive environment. ## Working with OCM repositories -For working with [OCM repositories](../../docs/ocm/model.md#repositories) an appropriate +For working with [OCM repositories](https://github.com/open-component-model/ocm-spec/blob/main/doc/01-model/01-model.md#component-repositories) an appropriate context, which can be used to retrieve OCM repositories, can be accessed with: ```go @@ -31,12 +31,12 @@ import "ocm.software/ocm/api/ocm" func MyFirstOCMApplication() { octx := ocm.DefaultContext() - + ... } ``` -If a decoupled environment with dedicated special settings is required, the +If a decoupled environment with dedicated special settings is required, the builder methods of the ocm package (`With...`) can be used to compose a context. @@ -46,9 +46,8 @@ It is possible to create any number of such contexts. The context can then be used to gain access to (OCM) repositories, which provide access to hosted components and component versions. - -To access a repository, a [repository specification](../../docs/formats/repositories/README.md) -is required. Every repository type extension supported by this library +To access a repository, a [repository specification](https://github.com/open-component-model/ocm-spec/blob/main/doc/01-model/01-model.md#component-repositories) +is required. Every repository type extension supported by this library uses its own package under `ocm.software/ocm/api/ocm/extensions/repositories`. To access an OCM repository based on an OCI registry the package `ocm.software/ocm/api/ocm/extensions/repositories/ocireg` @@ -78,11 +77,11 @@ Once a repository object is available it can be used to access component version ``` The component version now provides access to the described content, the -[component descriptor](../../docs/ocm/model.md#component-descriptor), -[resources](../../docs/ocm/model.md#resources), -[sources](../../docs/ocm/model.md#sources), -[component references](../../docs/ocm/model.md#references), and -[signatures](../../docs/ocm/model.md#signatures). +[component descriptor](https://github.com/open-component-model/ocm-spec/blob/main/doc/01-model/01-model.md#components-and-component-versions), +[resources](https://github.com/open-component-model/ocm-spec/blob/main/doc/01-model/02-elements-toplevel.md#resources), +[sources](https://github.com/open-component-model/ocm-spec/blob/main/doc/01-model/02-elements-toplevel.md#sources), +[component references](https://github.com/open-component-model/ocm-spec/blob/main/doc/05-guidelines/03-references.md), and +[signatures](https://github.com/open-component-model/ocm-spec/blob/main/doc/01-model/03-elements-sub.md#signatures). The component descriptor is accessible by a standardized Go representation, which is independent of the actually used serialization format. @@ -98,7 +97,7 @@ If can be encoded again in the original or any other supported scheme versions. ``` Any resource (or source) can be accessed by getting the appropriate -resource object by its resource [identity](../../docs/ocm/model.md#identity) in +resource object by its resource [identity](https://github.com/open-component-model/ocm-spec/blob/main/doc/01-model/02-elements-toplevel.md#component-identity) in the context of the component version. ```go @@ -111,9 +110,9 @@ the context of the component version. ``` The content of a described resource can be accessed using the appropriate -[access method](../../docs/ocm/model.md#artifact-access) described as part of +[access method](https://github.com/open-component-model/ocm-spec/blob/main/doc/04-extensions/02-access-types) described as part of the resource specification (another extension point of the model). -It is described by an access specification. Supported methods can be +It is described by an access specification. Supported methods can be directly be requested using the resource object. ```go @@ -139,27 +138,29 @@ Here a stream access or a byte array access is possible. ``` Besides this simple example, there are more usage scenarios, which -typicaly require more configuration: +typically require more configuration: + - [creating content and credential handling](creds.md) - [dealing with configuration](config.md) - [creating OCM content in temporary CTFs and publishing it](transfer.md) -## End-to-end Scenario. +## End-to-end Scenario In folder [`comparison-scenario`](comparison-scenario/README.md) there is an example for an end-to-end scenario, -from building a component version to publishing, consuming and deploying +from building a component version to publishing, consuming and deploying it in a separate environment. It shows the usage of the OCM library to implement all the required process steps. It builds a component version for the [podinfo helm chart](https://artifacthub.io/packages/helm/podinfo/podinfo). There are two scenarios: + - provisioning - - building a component version with a helm based deployment description + - building a component version with a helm based deployment description - signing it and - publishing it - consumption in a separate repository environment - - tranferring the component version into a separate repository environment. + - transferring the component version into a separate repository environment. - using the deployment description to localize the helm chart value - preparing values to refer to the podinfo OCI image available in the local environment. - - finally deploying it with helm. \ No newline at end of file + - finally deploying it with helm. diff --git a/examples/lib/creds.md b/examples/lib/creds.md index df2e20df64..1082e2d83a 100644 --- a/examples/lib/creds.md +++ b/examples/lib/creds.md @@ -14,7 +14,7 @@ the credentials directly for the lookup call: if err != nil { return err } - + repoSpec := ocireg.NewRepositorySpec("ghcr.io/mandelsoft/ocm", nil) repo, err := octx.RepositoryForSpec(repoSpec, cfg.GetCredentials()) @@ -54,21 +54,21 @@ not yet pushed to the repository. Using various interface methods, it is possible to configure the content for this new version. The example below just sets the provider information and adds a -single [resource artifact](../../docs/ocm/model.md#resources) consisting of +single [resource artifact](https://github.com/open-component-model/ocm-spec/blob/main/doc/01-model/02-elements-toplevel.md#resources) consisting of some text. ```go compvers.GetDescriptor().Provider = metav1.Provider{Name: "mandelsoft"} - + err=compvers.SetResourceBlob( &compdesc.ResourceMeta{ ElementMeta: compdesc.ElementMeta{ Name: "test", - }, - Type: resourcetypes.BLOB, + }, + Type: resourcetypes.BLOB, Relation: metav1.LocalRelation, - }, - accessio.BlobAccessForString(mime.MIME_TEXT, "testdata"), + }, + accessio.BlobAccessForString(mime.MIME_TEXT, "testdata"), "", nil, ) if err != nil { @@ -145,14 +145,14 @@ as follows: ```go octx := ocm.DefaultContext() - + octx.CredentialsContext().SetCredentialsForConsumer( credentials.ConsumerIdentity{ - identity.ID_TYPE: identity.CONSUMER_TYPE, - identity.ID_HOSTNAME: "ghcr.io", + identity.ID_TYPE: identity.CONSUMER_TYPE, + identity.ID_HOSTNAME: "ghcr.io", identity.ID_PATHPREFIX: "mandelsoft", - }, - cfg.GetCredentials(), + }, + cfg.GetCredentials(), ) ``` diff --git a/examples/lib/tour/docsrc/01-getting-started/README.md b/examples/lib/tour/docsrc/01-getting-started/README.md index afff4b48af..f6c1f76066 100644 --- a/examples/lib/tour/docsrc/01-getting-started/README.md +++ b/examples/lib/tour/docsrc/01-getting-started/README.md @@ -2,7 +2,7 @@ {{getting-started}} -This [tour](example.go) illustrates the basic usage of the API to +This [tour](/examples/lib/tour/01-getting-started/example.go) illustrates the basic usage of the API to access component versions in an OCM repository. ## Running the example @@ -21,7 +21,7 @@ version: 0.1.0 ## Walkthrough The basic entry point for using the OCM library is always -an [OCM Context object](../../contexts.md). It bundles all +an [OCM Context object](/examples/lib/contexts.md). It bundles all configuration settings and type registrations, like access methods, repository types, etc, and configuration settings, like credentials, diff --git a/examples/lib/tour/docsrc/02-composing-a-component-version/README.md b/examples/lib/tour/docsrc/02-composing-a-component-version/README.md index cbc9bf0b87..16eacfb461 100644 --- a/examples/lib/tour/docsrc/02-composing-a-component-version/README.md +++ b/examples/lib/tour/docsrc/02-composing-a-component-version/README.md @@ -7,8 +7,8 @@ create/compose component versions. It covers two basic scenarios: -- [`basic`](01-basic-componentversion-creation.go) Create a component version stored in the file system -- [`compose`](02-composition-version.go) Create a component version stored in memory using a non-persistent composition version. +- [`basic`](/examples/lib/tour/02-composing-a-component-version/01-basic-componentversion-creation.go) Create a component version stored in the file system +- [`compose`](/examples/lib/tour/02-composing-a-component-version/02-composition-version.go) Create a component version stored in memory using a non-persistent composition version. ## Running the example diff --git a/examples/lib/tour/docsrc/03-working-with-credentials/README.md b/examples/lib/tour/docsrc/03-working-with-credentials/README.md index 37a4775192..a23716ce1a 100644 --- a/examples/lib/tour/docsrc/03-working-with-credentials/README.md +++ b/examples/lib/tour/docsrc/03-working-with-credentials/README.md @@ -9,10 +9,10 @@ and credential consunmers in a technology-agnostic way. It covers four basic scenarios: -- [`basic`](01-using-credentials.go) Writing to a repository with directly specified credentials. -- [`context`](02-basic-credential-management.go) Using credentials via the credential management to publish a component version. -- [`read`](02-basic-credential-management.go) Read the previously created component version using the credential management. -- [`credrepo`](03-credential-repositories.go) Providing credentials via credential repositories. +- [`basic`](/examples/lib/tour/03-working-with-credentials/01-using-credentials.go) Writing to a repository with directly specified credentials. +- [`context`](/examples/lib/tour/03-working-with-credentials/02-basic-credential-management.go) Using credentials via the credential management to publish a component version. +- [`read`](/examples/lib/tour/03-working-with-credentials/02-basic-credential-management.go) Read the previously created component version using the credential management. +- [`credrepo`](/examples/lib/tour/03-working-with-credentials/03-credential-repositories.go) Providing credentials via credential repositories. ## Running the example @@ -29,7 +29,7 @@ Set your favorite OCI registry and don't forget to add the repository prefix for ## Walkthrough -### Writing to a repository with directly specified credentials. +### Writing to a repository with directly specified credentials As usual, we start with getting access to an OCM context object. @@ -50,7 +50,6 @@ there is an interface `credentials.Credentials` provided, whose implementations provide access to those properties. A simple property based implementation is `credentials.DirectCredentials. - The most simple use case is to provide the credentials directly for the repository access creation. The example config file provides such credentials diff --git a/examples/lib/tour/docsrc/04-working-with-config/README.md b/examples/lib/tour/docsrc/04-working-with-config/README.md index 7df66e7820..aa1e0f302b 100644 --- a/examples/lib/tour/docsrc/04-working-with-config/README.md +++ b/examples/lib/tour/docsrc/04-working-with-config/README.md @@ -9,11 +9,11 @@ and configurable objects. It covers five basic scenarios: -- [`basic`](01-basic-config-management.go) Basic configuration management illustrating the configuration of credentials. -- [`generic`](02-handle-arbitrary-config.go) Handling of arbitrary configuration. -- [`ocm`](03-using-ocm-config.go) Central configuration -- [`provide`](04-write-config-type.go) Providing new config object types -- [`consume`](05-write-config-consumer.go) Preparing objects to be configured by the config management +- [`basic`](/examples/lib/tour/04-working-with-config/01-basic-config-management.go) Basic configuration management illustrating the configuration of credentials. +- [`generic`](/examples/lib/tour/04-working-with-config/02-handle-arbitrary-config.go) Handling of arbitrary configuration. +- [`ocm`](/examples/lib/tour/04-working-with-config/03-using-ocm-config.go) Central configuration +- [`provide`](/examples/lib/tour/04-working-with-config/04-write-config-type.go) Providing new config object types +- [`consume`](/examples/lib/tour/04-working-with-config/05-write-config-consumer.go) Preparing objects to be configured by the config management ## Running the example diff --git a/examples/lib/tour/docsrc/06-signing-component-versions/README.md b/examples/lib/tour/docsrc/06-signing-component-versions/README.md index 0c0e0d5d4c..923703787d 100644 --- a/examples/lib/tour/docsrc/06-signing-component-versions/README.md +++ b/examples/lib/tour/docsrc/06-signing-component-versions/README.md @@ -7,8 +7,8 @@ sign and verify signatures. It covers two basic scenarios: -- [`sign`](01-basic-signing.go) Create, Sign, Transport and Verify a component version. -- [`context`](02-using-context-settings.go) Using context settings to configure signing and verification in target repo. +- [`sign`](/examples/lib/tour/06-signing-component-versions/01-basic-signing.go) Create, Sign, Transport and Verify a component version. +- [`context`](/examples/lib/tour/06-signing-component-versions/02-using-context-settings.go) Using context settings to configure signing and verification in target repo. ## Running the examples diff --git a/examples/lib/transfer.md b/examples/lib/transfer.md index 14fba72dd5..dfbca5a95e 100644 --- a/examples/lib/transfer.md +++ b/examples/lib/transfer.md @@ -2,7 +2,7 @@ OCM content can be directly crated in public OCM repositories as shown in other examples. But it is also possible to compose component versions in local or temporary filesystem -structured according the [Common Transport Format](../../docs/formats/repositories/README.md). +structured according the [Common Transport Format](https://github.com/open-component-model/ocm-spec/blob/main/doc/01-model/01-model.md#component-repositories). Afterward, they can be transferred/published to public OCM repositories. This example shows some cases how this can be achieved directly using the OCM library. @@ -174,12 +174,12 @@ target repository (`transferHandler, err := standard.New(standard.Overwrite())`. return errors.Wrapf(err, "cannot get version %s for component %s", vname, cname) } loop.Close(cv) - + err = transfer.TransferVersion(printer, closure, cv, target, transferHandler) if err != nil { return errors.Wrapf(err, "cannot transfer version %s for component %s", vname, cname) } - + if err := loop.Finalize(); err != nil { return err } From 558fd5182eee0546501322b23dd12bf9abff0401 Mon Sep 17 00:00:00 2001 From: Hilmar Falkenberg Date: Wed, 14 Aug 2024 16:16:22 +0200 Subject: [PATCH 11/45] podinfo --- .wordlist.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.wordlist.txt b/.wordlist.txt index fdf55ad270..05f26957d1 100644 --- a/.wordlist.txt +++ b/.wordlist.txt @@ -100,7 +100,7 @@ OCM OCMBot OS parameterization -Podinfo +podinfo Podman predefine programmatically From a4d37bc9bf37da9804319608243d8aed61c5437f Mon Sep 17 00:00:00 2001 From: Hilmar Falkenberg Date: Wed, 14 Aug 2024 17:13:35 +0200 Subject: [PATCH 12/45] fix links --- cmds/ocm/commands/toicmds/cmd.go | 4 ++-- cmds/ocm/commands/toicmds/package/describe/cmd.go | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/cmds/ocm/commands/toicmds/cmd.go b/cmds/ocm/commands/toicmds/cmd.go index 9b3ec0e88d..20773ce2fd 100644 --- a/cmds/ocm/commands/toicmds/cmd.go +++ b/cmds/ocm/commands/toicmds/cmd.go @@ -21,13 +21,13 @@ func NewCommand(ctx clictx.Context) *cobra.Command { TOI is an abbreviation for (T)iny (O)CM (I)nstallation. It is a simple application framework on top of the Open Component Model, that can be used to describe image based installation executors and installation -packages (see topic ocm toi bootstrapping in form of resources +packages (see topic ocm toi-bootstrapping in form of resources with a dedicated type. All involved resources are hereby taken from a component version of the Open Component Model, which supports all the OCM features, like transportation. The framework consists of a generic bootstrap command -(ocm toi bootstrap componentversions) and an arbitrary set of image +(ocm toi bootstrap package) and an arbitrary set of image based executors, that are executed in containers and fed with the required installation data by th generic command. `, diff --git a/cmds/ocm/commands/toicmds/package/describe/cmd.go b/cmds/ocm/commands/toicmds/package/describe/cmd.go index 057d48752f..215f382b77 100644 --- a/cmds/ocm/commands/toicmds/package/describe/cmd.go +++ b/cmds/ocm/commands/toicmds/package/describe/cmd.go @@ -61,7 +61,7 @@ Describe a TOI package provided by a resource of an OCM component version. The package resource must have the type ` + toi.TypeTOIPackage + `. This is a simple YAML file resource describing the bootstrapping of a dedicated kind -of software. See also the topic ocm toi toi-bootstrapping. +of software. See also the topic ocm toi / ocm toi-bootstrapping. The first matching resource of this type is selected. Optionally a set of identity attribute can be specified used to refine the match. This can be the From ae28f0c2268f87f34e34393cf5f19b34e7220897 Mon Sep 17 00:00:00 2001 From: Hilmar Falkenberg Date: Wed, 14 Aug 2024 17:14:44 +0200 Subject: [PATCH 13/45] trying to fix some linter issues --- hack/generate-docs/cobradoc/md_docs.go | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/hack/generate-docs/cobradoc/md_docs.go b/hack/generate-docs/cobradoc/md_docs.go index d84cd31e55..2ce1530094 100644 --- a/hack/generate-docs/cobradoc/md_docs.go +++ b/hack/generate-docs/cobradoc/md_docs.go @@ -68,11 +68,11 @@ func GenMarkdownCustom(cmd *cobra.Command, w io.Writer, linkHandler func(string) if cmd.Runnable() || cmd.HasAvailableSubCommands() { buf.WriteString("### Synopsis\n\n") - buf.WriteString(fmt.Sprintf("```\n%s\n```\n\n", UseLine(cmd))) + buf.WriteString(fmt.Sprintf("```sh\n%s\n```\n\n", UseLine(cmd))) if len(cmd.Aliases) > 0 { - buf.WriteString("##### Aliases\n\n") + buf.WriteString("#### Aliases\n\n") cmd.NameAndAliases() - buf.WriteString(fmt.Sprintf("```\n%s\n```\n\n", cmd.NameAndAliases())) + buf.WriteString(fmt.Sprintf("```text\n%s\n```\n\n", cmd.NameAndAliases())) } } @@ -88,8 +88,8 @@ func GenMarkdownCustom(cmd *cobra.Command, w io.Writer, linkHandler func(string) desc = strings.ReplaceAll(desc, "\\\n", "\n") links, desc = cobrautils.SubstituteCommandLinks(cmd.Long, cobrautils.FormatLinkWithHandler(linkHandler)) - buf.WriteString("### Description\n\n") - buf.WriteString(desc + "\n\n") + buf.WriteString("### Description\n") + buf.WriteString(desc + "\n") } if len(cmd.Example) > 0 { @@ -118,7 +118,7 @@ func GenMarkdownCustom(cmd *cobra.Command, w io.Writer, linkHandler func(string) buf.WriteString("### SEE ALSO\n\n") if cmd.HasParent() { header = true - buf.WriteString("##### Parents\n\n") + buf.WriteString("#### Parents\n\n") parent := cmd for parent.HasParent() { parent = parent.Parent() From 985cd6f53e5479012db3105287052b5edb26cc45 Mon Sep 17 00:00:00 2001 From: Hilmar Falkenberg Date: Wed, 14 Aug 2024 17:17:05 +0200 Subject: [PATCH 14/45] generate lib/tour --- .../lib/tour/01-getting-started/README.md | 12 +++-- .../README.md | 27 +++++++---- .../03-working-with-credentials/README.md | 32 +++++++------ .../lib/tour/04-working-with-config/README.md | 46 +++++++++++-------- .../README.md | 13 +++--- .../06-signing-component-versions/README.md | 22 +++++---- examples/lib/tour/README.md | 12 ++--- 7 files changed, 97 insertions(+), 67 deletions(-) diff --git a/examples/lib/tour/01-getting-started/README.md b/examples/lib/tour/01-getting-started/README.md index 72ca76f19f..d376ae3c45 100644 --- a/examples/lib/tour/01-getting-started/README.md +++ b/examples/lib/tour/01-getting-started/README.md @@ -3,7 +3,9 @@ # Basic Usage of OCM Repositories -This [tour](example.go) illustrates the basic usage of the API to + + +This [tour](/examples/lib/tour/01-getting-started/example.go) illustrates the basic usage of the API to access component versions in an OCM repository. ## Running the example @@ -17,10 +19,12 @@ repository: ghcr.io/mandelsoft/ocm version: 0.1.0 ``` + + ## Walkthrough The basic entry point for using the OCM library is always -an [OCM Context object](../../contexts.md). It bundles all +an [OCM Context object](/examples/lib/contexts.md). It bundles all configuration settings and type registrations, like access methods, repository types, etc, and configuration settings, like credentials, @@ -162,7 +166,7 @@ and the resources described by the component version. This results in the following output (the shown version might differ, because the code always describes the latest version): -``` +```go resources of the latest version: version: 0.13.0 provider: ocm.software @@ -272,7 +276,7 @@ closing the reader, again defer reader.Close() ``` -Now, we just read the content and copy it to the intended +Now, we just read the content and copy it to the intended output file (`/tmp/ocmcli`). ```go diff --git a/examples/lib/tour/02-composing-a-component-version/README.md b/examples/lib/tour/02-composing-a-component-version/README.md index 573f1db9df..8f0a022811 100644 --- a/examples/lib/tour/02-composing-a-component-version/README.md +++ b/examples/lib/tour/02-composing-a-component-version/README.md @@ -3,12 +3,15 @@ # Composing a Component Version + + This tour illustrates the basic usage of the API to create/compose component versions. It covers two basic scenarios: -- [`basic`](01-basic-componentversion-creation.go) Create a component version stored in the file system -- [`compose`](02-composition-version.go) Create a component version stored in memory using a non-persistent composition version. + +- [`basic`](/examples/lib/tour/02-composing-a-component-version/01-basic-componentversion-creation.go) Create a component version stored in the file system +- [`compose`](/examples/lib/tour/02-composing-a-component-version/02-composition-version.go) Create a component version stored in memory using a non-persistent composition version. ## Running the example @@ -19,7 +22,7 @@ You can call the main program with the scenario as argument. Configuration is no ### Basic Component Version Creation The first variant just creates a new component version -in an OCM repository. To avoid the requirement for +in an OCM repository. To avoid the requirement for credentials a file system based repository is created, using the *Common Transport Format* (CTF). @@ -65,7 +68,7 @@ The result is a memory based representation, which is not yet persisted. Now, we can configure the component version. It only exists in memory so far, but is already connected to the repository. -The setup of the component version is put into a +The setup of the component version is put into a separate method (`setupVersion`), so it can be reused for the second variant. First, we configure the component version provider. @@ -122,7 +125,7 @@ Supported access types can be found under ``` Once we have both, the metadata and the content specification, -we can now add the resource to our component version. +we can now add the resource to our component version. The `SetResource` methods will replace an existing resource with the same identity, or add the resource, if no such resource exists in the component version. @@ -179,6 +182,7 @@ the resource as byte sequence. When storing the blob, it is possible to provide some optional additional information: + - a name of the resource described by the blob, which could be used to do a later upload into an external repository (for example the image repository of an OCI image stored @@ -199,7 +203,7 @@ version metadata in the same repository, no external repository is required. The above blob example describes the basic operations, -which can be used to compose any kind of resource +which can be used to compose any kind of resource from any kind of source. For selected use cases there are convenience helpers available, which can be used to compose a resource access object. @@ -225,6 +229,7 @@ contain all the required resource metadata. All kinds of `SetXXX` methods optionally accept options used to influence the target in the element list. It is possible to + - enforce an append (`ocm.AppendElement`) - enforce a dedicated index (`ocm.TargetIndex(n)`) - enforce the replacement of a dedicated element identity (`ocm.TargetIdentity(...)`) @@ -240,7 +245,7 @@ generated by docker builds. Here, we just compose a multi-platform image built with `buildx` from these sources (components/ocmcli) featuring two flavors. (you have to execute `make image.multi` in components/ocmcli -before executing this example. +before executing this example.) ```go meta, err = elements.ResourceMeta("ocmcli", resourcetypes.OCI_IMAGE) @@ -262,10 +267,12 @@ before executing this example. } ``` + + ### Composition Environment The second variant just creates a new component version -in a memory based composition environment, no persistence is +in a memory based composition environment, no persistence is required. Like all component versions, such component versions can be added to any repository later. @@ -300,7 +307,7 @@ Here, we use another feature of the composition environment. It also provides complete memory based OCM repositories. It has no storage backend and can be used to internally compose a set of component versions, which can then be transferred -to any other repository (see [tour 05](../05-transporting-component-versions/README.md)) +to any other repository (see [tour 05](../05-transporting-component-versions/README.md#transport)) ```go repo := composition.NewRepository(ctx) @@ -314,4 +321,4 @@ add the new component version. if err != nil { return errors.Wrapf(err, "cannot add version") } -``` \ No newline at end of file +``` diff --git a/examples/lib/tour/03-working-with-credentials/README.md b/examples/lib/tour/03-working-with-credentials/README.md index cfeb572121..8fe46fe9d7 100644 --- a/examples/lib/tour/03-working-with-credentials/README.md +++ b/examples/lib/tour/03-working-with-credentials/README.md @@ -3,16 +3,19 @@ # Working with Credentials + + This tour illustrates the basic handling of credentials using the OCM library. The library provides an extensible framework to bring together credential providers and credential consunmers in a technology-agnostic way. It covers four basic scenarios: -- [`basic`](01-using-credentials.go) Writing to a repository with directly specified credentials. -- [`context`](02-basic-credential-management.go) Using credentials via the credential management to publish a component version. -- [`read`](02-basic-credential-management.go) Read the previously created component version using the credential management. -- [`credrepo`](03-credential-repositories.go) Providing credentials via credential repositories. + +- [`basic`](/examples/lib/tour/03-working-with-credentials/01-using-credentials.go) Writing to a repository with directly specified credentials. +- [`context`](/examples/lib/tour/03-working-with-credentials/02-basic-credential-management.go) Using credentials via the credential management to publish a component version. +- [`read`](/examples/lib/tour/03-working-with-credentials/02-basic-credential-management.go) Read the previously created component version using the credential management. +- [`credrepo`](/examples/lib/tour/03-working-with-credentials/03-credential-repositories.go) Providing credentials via credential repositories. ## Running the example @@ -29,7 +32,7 @@ Set your favorite OCI registry and don't forget to add the repository prefix for ## Walkthrough -### Writing to a repository with directly specified credentials. +### Writing to a repository with directly specified credentials As usual, we start with getting access to an OCM context object. @@ -50,7 +53,6 @@ there is an interface `credentials.Credentials` provided, whose implementations provide access to those properties. A simple property based implementation is `credentials.DirectCredentials. - The most simple use case is to provide the credentials directly for the repository access creation. The example config file provides such credentials @@ -101,7 +103,7 @@ in `common.go` (It is shared by the other examples, also). } ``` -In contrast to our [first tour](../01-getting-started/README.md#walkthrough) +In contrast to our [first tour](../01-getting-started/README.md#getting-started-walkthrough) we cannot list components, here. OCI registries do not support component listers, therefore we just look up the actually added version to verify the result. @@ -117,6 +119,8 @@ just look up the actually added version to verify the result. The coding for `describeVersion` is similar to the one shown in the [first tour](../01-getting-started/README.md#describe-version). + + ### Using the Credential Management Passing credentials directly at the repository @@ -143,7 +147,6 @@ As usual, we start with the default OCM context. It is now used to gain access to the appropriate credential context. - ```go credctx := ctx.CredentialsContext() ``` @@ -212,7 +215,7 @@ The used functions above are just convenience wrappers around the core type ConsumerId, which might be provided for dedicated repository/consumer technologies. Everything can be done directly with the core interface -and property name constants provided by the dedicted technologies. +and property name constants provided by the dedicted technologies. Once we have the id we can finally set the credentials for this id. @@ -221,9 +224,9 @@ id. credctx.SetCredentialsForConsumer(id, creds) ``` -Now, the context is prepared to provide credentials +Now, the context is prepared to provide credentials for any usage of our OCI registry -Let's test, whether it could provide credentials +Let's test, whether it could provide credentials for storing our component version. First, we get the repository object for our OCM repository. @@ -370,9 +373,9 @@ the access method as credential consumer can access the blob. ### Providing credentials via credential repositories -The OCM toolset embraces multiple storage +The OCM tool set embraces multiple storage backend technologies, for OCM metadata as well -as for artifacts described by a component version. +as for artifacts described by a component version. All those technologies typically have their own way to configure credentials for command line tools or servers. @@ -392,7 +395,6 @@ credentials for dedicated OCI registries. We start again by providing access to the OCM context and the connected credential context. - ```go ctx := ocm.DefaultContext() credctx := ctx.CredentialsContext() @@ -445,7 +447,7 @@ specification. We are not interested in the repository object, so we just ignore the result. -So, if you have done the appropriate docker login for your +So, if you have done the appropriate docker login for your OCI registry, it should be possible now to get the credentials for the configured repository. diff --git a/examples/lib/tour/04-working-with-config/README.md b/examples/lib/tour/04-working-with-config/README.md index bc1ac0d845..590a0cdc0d 100644 --- a/examples/lib/tour/04-working-with-config/README.md +++ b/examples/lib/tour/04-working-with-config/README.md @@ -3,17 +3,20 @@ # Working with Configurations + + This tour illustrates the basic configuration management included in the OCM library. The library provides an extensible framework to bring together configuration settings and configurable objects. It covers five basic scenarios: -- [`basic`](01-basic-config-management.go) Basic configuration management illustrating the configuration of credentials. -- [`generic`](02-handle-arbitrary-config.go) Handling of arbitrary configuration. -- [`ocm`](03-using-ocm-config.go) Central configuration -- [`provide`](04-write-config-type.go) Providing new config object types -- [`consume`](05-write-config-consumer.go) Preparing objects to be configured by the config management + +- [`basic`](/examples/lib/tour/04-working-with-config/01-basic-config-management.go) Basic configuration management illustrating the configuration of credentials. +- [`generic`](/examples/lib/tour/04-working-with-config/02-handle-arbitrary-config.go) Handling of arbitrary configuration. +- [`ocm`](/examples/lib/tour/04-working-with-config/03-using-ocm-config.go) Central configuration +- [`provide`](/examples/lib/tour/04-working-with-config/04-write-config-type.go) Providing new config object types +- [`consume`](/examples/lib/tour/04-working-with-config/05-write-config-consumer.go) Preparing objects to be configured by the config management ## Running the example @@ -260,7 +263,7 @@ configuration file for the OCM ecosystem, as will be shown in the next example. Although the configuration of an OCM context can be done by a sequence of explicit calls according to the mechanisms -shown in the examples before, a simple convenience +shown in the examples before, a simple convenience library function is provided, which can be used to configure an OCM context and all related other contexts with a single call based on a central configuration file (`~/.ocmconfig`) @@ -279,6 +282,8 @@ enriched with specialized config specifications for credentials, default repositories, signing keys and any other configuration specification. + + #### Standard Configuration File Most important are here the credentials. @@ -298,7 +303,7 @@ the central configuration. One such repository type is the Docker config type. It reads a `dockerconfig.json` file and feeds in the credentials. -Because it is used for a dedicated purpose (credentials for +Because it is used for a dedicated purpose (credentials for OCI registries), it not only can feed the credentials, but also their mapping to consumer ids. @@ -342,6 +347,7 @@ default initial OCM configuration file. ``` The result should look similar to (but with reordered fields): + ```yaml type: generic.config.ocm.software configurations: @@ -395,7 +401,7 @@ If you have provided your OCI credentials with #### Templating The configuration library function does not only read the -ocm config file, it also applies [*spiff*](https://github.com/mandelsoft/spiff) +ocm config file, it also applies [*spiff*](github.com/mandelsoft/spiff) processing to the provided YAML/JSON content. *Spiff* is an in-domain yaml-based templating engine. Therefore, you can use any spiff dynaml expression to define values or even complete @@ -432,6 +438,8 @@ If this is used with the above library functions, the finally generated config object will contain the read file content, which is hopefully a valid certificate. + + ### Providing new config object types So far, we just used existing config types to configure existing objects. @@ -439,7 +447,7 @@ But the configuration management is highly extensible, and it is quite simple to provide new config types, which can be used to configure any new or existing object, which is prepared to consume configuration. -The next [chapter](#preparing-objects-to-be-configured-by-the-config-management) will show how to prepare an +The next [chapter](#consume-config) will show how to prepare an object to be automatically configurable by the configuration management. Here, we focus on the implementation of new config object types. Therefore, we want to configure the @@ -531,7 +539,7 @@ func (c *ExampleConfigSpec) SetTargetRepositoryData(data []byte) error { ``` -The utility function `runtime.CheckSpecification` can be used to +The utility function `runtime.CheckSpecification` can be used to check a byte sequence to be a valid specification. It just checks for a valid YAML document featuring a non-empty `type` field: @@ -601,9 +609,9 @@ may apply is settings or even parts of its setting to any kind of target object. Our configuration object supports two kinds of target objects: if the target is a credentials context it configures the credentials to be used for the -described OCI repository similar to our [credential management example](../03-working-with-credentials/README.md#using-the-credential-management). +described OCI repository similar to our [credential management example](../03-working-with-credentials/README.md#using-cred-management). -But we want to accept more types of target objects. Therefore, we +But we want to accept more types of target objects. Therefore, we introduce an own interface declaring the methods required for applying some configuration settings. @@ -616,7 +624,7 @@ type RepositoryTarget interface { ``` -By checking the target object against this interface, we are able +By checking the target object against this interface, we are able to configure any kind of object, as long as it provides the necessary configuration methods. @@ -627,7 +635,7 @@ about the new type. This is done by an `init()` function in our config package. Here, we call a registration function, which gets called with a dedicated type object for the new config type. -A *type object* describes the config type, its type name, how +A *type object* describes the config type, its type name, how it is serialized and deserialized and some description. We use a standard type object, here, instead of implementing an own one. It is parameterized by the Go pointer type (`*ExampleConfigSpec`) for @@ -660,7 +668,7 @@ A usual, we gain access to our required contexts. ctx := credctx.ConfigContext() ``` -To setup our environment we create our new config based on the actual settings +To setup our environment we create our new config based on the actual settings and apply it to the config context. ```go @@ -767,6 +775,8 @@ used. Our simple repository target is just an example for some kind of ad-hoc configuration. A complete scenario is shown in the next example. + + ### Preparing Objects to be Configured by the Config Management We already have our new acme.org config object type, @@ -789,7 +799,7 @@ the config context it should use to configure itself. Therefore, our type contains an additional field `updater`. Its type `cpi.Updater` is a utility provided by the configuration -management, which holds a reference to a configuration context +management, which holds a reference to a configuration context and is able to configure an object based on a managed configuration watermark. It remembers which config objects from the @@ -880,7 +890,7 @@ to the config context. prov := NewRepositoryProvider(credctx) ``` -If we ask now for a repository we will get the empty +If we ask now for a repository we will get the empty answer, because nothing is configured, yet. ```go @@ -937,4 +947,4 @@ the credential context. return errors.Wrapf(err, "credentials") } fmt.Printf("credentials: %s\n", obfuscate(creds)) -``` \ No newline at end of file +``` diff --git a/examples/lib/tour/05-transporting-component-versions/README.md b/examples/lib/tour/05-transporting-component-versions/README.md index 89da4f5c59..53d94055e9 100644 --- a/examples/lib/tour/05-transporting-component-versions/README.md +++ b/examples/lib/tour/05-transporting-component-versions/README.md @@ -3,6 +3,8 @@ # Transporting Component Versions + + This [tour](example.go) illustrates the basic support for transporting content from one environment into another. @@ -35,9 +37,9 @@ targetRepository: ocmConfig: ``` -The actual version of the example just works with the file system +The actual version of the example just works with the file system target, because it is not possible to specify credentials for the -target repository in this simple config file. But, if you specify an [OCM config file](../04-working-with-config/README.md#standard-configuration-file) you can +target repository in this simple config file. But, if you specify an [OCM config file](../04-working-with-config/README.md#ocm-config-file) you can add more predefined credential settings to make it possible to use target repositories requiring credentials. The credentials are automatically taken from the credentials context and don't need to be @@ -52,7 +54,7 @@ As usual, we start with getting access to an OCM context ``` Then we configure this context with optional ocm config defined in our config file. -See [OCM config scenario in tour 04](../04-working-with-config/README.md#standard-configuration-file). +See [OCM config scenario in tour 04](../04-working-with-config/README.md#ocm-config-file). ```go err := ReadConfiguration(ctx, cfg) @@ -81,7 +83,7 @@ func ReadConfiguration(ctx ocm.Context, cfg *helper.Config) error { The context acts as factory for various model types based on specification descriptor serialization formats in YAML or JSON. -Access method specifications and repository specification are +Access method specifications and repository specification are examples for this feature. Now, we use the repository specification serialization format to @@ -100,7 +102,7 @@ configuration file. For our source we just use the component version provided by the last examples in a remote repository. Therefore, we set up the credentials context, as -shown in [tour 03](../03-working-with-credentials/README.md#using-the-credential-management). +shown in [tour 03](../03-working-with-credentials/README.md#using-cred-management). ```go id, err := oci.GetConsumerIdForRef(cfg.Repository) @@ -155,7 +157,6 @@ be migrated to local blobs. Now, we check the result of our transport action in the target repository. - ```go tcv, err := target.LookupComponentVersion("acme.org/example03", "v0.1.0") if err != nil { diff --git a/examples/lib/tour/06-signing-component-versions/README.md b/examples/lib/tour/06-signing-component-versions/README.md index 4c86e61f62..35a05acd97 100644 --- a/examples/lib/tour/06-signing-component-versions/README.md +++ b/examples/lib/tour/06-signing-component-versions/README.md @@ -3,12 +3,15 @@ # Signing Component Versions + + This tour illustrates the basic functionality to sign and verify signatures. It covers two basic scenarios: -- [`sign`](01-basic-signing.go) Create, Sign, Transport and Verify a component version. -- [`context`](02-using-context-settings.go) Using context settings to configure signing and verification in target repo. + +- [`sign`](/examples/lib/tour/06-signing-component-versions/01-basic-signing.go) Create, Sign, Transport and Verify a component version. +- [`context`](/examples/lib/tour/06-signing-component-versions/02-using-context-settings.go) Using context settings to configure signing and verification in target repo. ## Running the examples @@ -39,8 +42,9 @@ As usual, we start with getting access to an OCM context ```go ctx := ocm.DefaultContext() ``` + Then, we configure this context with optional ocm config defined in our config file. -See [OCM config scenario in tour 04](../04-working-with-config/README.md#standard-configuration-file). +See [OCM config scenario in tour 04](../04-working-with-config/README.md#ocm-config-file). ```go err := ReadConfiguration(ctx, cfg) @@ -84,7 +88,7 @@ There might be multiple signatures, therefore every signature has a name (here `acme.org`). Keys are always specified for a dedicated signature name. The signing process can be influenced by several options. Here, we just provide the private key to be used in an ad-hoc manner. -[Later](#using-context-settings-to-configure-signing), we will see how everything can be preconfigured in a *signing context*. +[Later](#signing-context), we will see how everything can be preconfigured in a *signing context*. ```go _, err = signing.SignComponentVersion(cv, "acme.org", signing.PrivateKey("acme.org", privkey)) @@ -143,6 +147,8 @@ target version. } ``` + + ### Using Context Settings to Configure Signing Instead of providing all signing relevant information directly with @@ -156,7 +162,7 @@ As usual, we start with getting access to an OCM context ``` Then, we configure this context with optional ocm config defined in our config file. -See [OCM config scenario in tour 04](../04-working-with-config/README.md#standard-configuration-file). +See [OCM config scenario in tour 04](../04-working-with-config/README.md#ocm-config-file). ```go err := ReadConfiguration(ctx, cfg) @@ -216,7 +222,7 @@ Now, we manually add the keys to our context. ``` We are prepared now and can sign any component version without specifying further options -in any repository for the signature name `acme.org`. +in any repository for the signature name `acme.org`. Therefore, we just get the component version from the prepared repository @@ -263,7 +269,7 @@ Manually adding keys to the signing attribute might simplify the call to possibly multiple signing/verification calls, but it does not help to provide keys via an external configuration (for example for using the OCM CLI). -In [tour04](../04-working-with-config/README.md#providing-new-config-object-types) +In [tour04](../04-working-with-config/README.md#tour04-arbitrary) we have seen how arbitrary configuration possibilities can be added. The signing attribute uses this mechanism to configure itself by providing an own @@ -344,4 +350,4 @@ configurations: -----END RSA PUBLIC KEY----- type: keys.config.ocm.software type: generic.config.ocm.software -``` \ No newline at end of file +``` diff --git a/examples/lib/tour/README.md b/examples/lib/tour/README.md index 3046d42686..bd9a10a9e8 100644 --- a/examples/lib/tour/README.md +++ b/examples/lib/tour/README.md @@ -10,9 +10,9 @@ handling credentials and configurations. So far, it does not cover the implementation of extension points of the library. -- [Basic Usage of OCM Repositories](01-getting-started/README.md) -- [Composing Component Versions](02-composing-a-component-version/README.md) -- [Working with Credentials](03-working-with-credentials/README.md) -- [Working with Configuration](04-working-with-config/README.md) -- [Transporting Component Versions](05-transporting-component-versions/README.md) -- [Signing Component Versions](06-signing-component-versions/README.md) \ No newline at end of file +- [Basic Usage of OCM Repositories](01-getting-started/README.md#getting-started) +- [Composing Component Versions](02-composing-a-component-version/README.md#compose-compvers) +- [Working with Credentials](03-working-with-credentials/README.md#credentials) +- [Working with Configuration](04-working-with-config/README.md#config) +- [Transporting Component Versions](05-transporting-component-versions/README.md#transport) +- [Signing Component Versions](06-signing-component-versions/README.md#signing) \ No newline at end of file From f9caf2d5c349671368a3f6675f762c7cd86fe303 Mon Sep 17 00:00:00 2001 From: Hilmar Falkenberg Date: Wed, 14 Aug 2024 17:17:15 +0200 Subject: [PATCH 15/45] generate docs --- docs/pluginreference/plugin.md | 4 +--- docs/pluginreference/plugin_accessmethod.md | 6 ++---- .../plugin_accessmethod_compose.md | 6 ++---- docs/pluginreference/plugin_accessmethod_get.md | 6 ++---- .../plugin_accessmethod_validate.md | 6 ++---- docs/pluginreference/plugin_action.md | 6 ++---- docs/pluginreference/plugin_action_execute.md | 6 ++---- docs/pluginreference/plugin_command.md | 4 +--- docs/pluginreference/plugin_describe.md | 6 ++---- docs/pluginreference/plugin_descriptor.md | 4 +--- docs/pluginreference/plugin_download.md | 6 ++---- docs/pluginreference/plugin_info.md | 4 ++-- docs/pluginreference/plugin_upload.md | 6 ++---- docs/pluginreference/plugin_upload_put.md | 6 ++---- docs/pluginreference/plugin_upload_validate.md | 6 ++---- docs/pluginreference/plugin_valuemergehandler.md | 6 ++---- .../plugin_valuemergehandler_execute.md | 6 ++---- docs/pluginreference/plugin_valueset.md | 6 ++---- docs/pluginreference/plugin_valueset_compose.md | 6 ++---- docs/pluginreference/plugin_valueset_validate.md | 6 ++---- docs/reference/ocm.md | 4 +--- docs/reference/ocm_add.md | 4 ++-- docs/reference/ocm_add_componentversions.md | 10 ++++------ .../ocm_add_componentversions_ocm-labels.md | 4 +--- docs/reference/ocm_add_references.md | 10 ++++------ docs/reference/ocm_add_resource-configuration.md | 10 ++++------ docs/reference/ocm_add_resources.md | 10 ++++------ docs/reference/ocm_add_routingslips.md | 10 ++++------ docs/reference/ocm_add_source-configuration.md | 10 ++++------ docs/reference/ocm_add_sources.md | 10 ++++------ docs/reference/ocm_attributes.md | 4 +--- docs/reference/ocm_bootstrap.md | 4 ++-- docs/reference/ocm_bootstrap_configuration.md | 10 ++++------ ...m_bootstrap_configuration_toi-bootstrapping.md | 4 +--- docs/reference/ocm_bootstrap_package.md | 10 ++++------ .../ocm_bootstrap_package_toi-bootstrapping.md | 4 +--- docs/reference/ocm_cache.md | 4 ++-- docs/reference/ocm_check.md | 4 ++-- docs/reference/ocm_check_componentversions.md | 10 ++++------ docs/reference/ocm_clean.md | 4 ++-- docs/reference/ocm_clean_cache.md | 6 ++---- docs/reference/ocm_configfile.md | 4 +--- docs/reference/ocm_controller.md | 4 ++-- docs/reference/ocm_controller_install.md | 4 ++-- docs/reference/ocm_controller_uninstall.md | 4 ++-- docs/reference/ocm_create.md | 4 ++-- docs/reference/ocm_create_componentarchive.md | 10 ++++------ docs/reference/ocm_create_rsakeypair.md | 10 ++++------ docs/reference/ocm_create_transportarchive.md | 10 ++++------ docs/reference/ocm_credential-handling.md | 4 +--- docs/reference/ocm_credentials.md | 8 ++++---- docs/reference/ocm_describe.md | 4 ++-- docs/reference/ocm_describe_artifacts.md | 10 ++++------ docs/reference/ocm_describe_cache.md | 6 ++---- docs/reference/ocm_describe_package.md | 15 +++++++-------- .../ocm_describe_package_toi-bootstrapping.md | 4 +--- docs/reference/ocm_describe_plugins.md | 10 ++++------ docs/reference/ocm_download.md | 4 ++-- docs/reference/ocm_download_artifacts.md | 10 ++++------ docs/reference/ocm_download_cli.md | 10 ++++------ docs/reference/ocm_download_componentversions.md | 10 ++++------ docs/reference/ocm_download_resources.md | 10 ++++------ docs/reference/ocm_execute.md | 4 ++-- docs/reference/ocm_execute_action.md | 6 ++---- docs/reference/ocm_get.md | 4 ++-- docs/reference/ocm_get_artifacts.md | 10 ++++------ docs/reference/ocm_get_componentversions.md | 10 ++++------ docs/reference/ocm_get_config.md | 10 ++++------ docs/reference/ocm_get_credentials.md | 10 ++++------ docs/reference/ocm_get_plugins.md | 10 ++++------ docs/reference/ocm_get_pubsub.md | 10 ++++------ docs/reference/ocm_get_references.md | 10 ++++------ docs/reference/ocm_get_resources.md | 10 ++++------ docs/reference/ocm_get_routingslips.md | 10 ++++------ docs/reference/ocm_get_sources.md | 10 ++++------ docs/reference/ocm_hash.md | 4 ++-- docs/reference/ocm_hash_componentversions.md | 10 ++++------ docs/reference/ocm_install.md | 4 ++-- docs/reference/ocm_install_plugins.md | 10 ++++------ docs/reference/ocm_list.md | 4 ++-- docs/reference/ocm_list_componentversions.md | 10 ++++------ docs/reference/ocm_logging.md | 4 +--- docs/reference/ocm_oci-references.md | 4 +--- docs/reference/ocm_oci.md | 4 ++-- docs/reference/ocm_ocm-accessmethods.md | 4 +--- docs/reference/ocm_ocm-downloadhandlers.md | 4 +--- docs/reference/ocm_ocm-labels.md | 4 +--- docs/reference/ocm_ocm-pubsub.md | 4 +--- docs/reference/ocm_ocm-references.md | 4 +--- docs/reference/ocm_ocm-uploadhandlers.md | 4 +--- docs/reference/ocm_ocm.md | 4 ++-- docs/reference/ocm_set.md | 4 ++-- docs/reference/ocm_set_pubsub.md | 10 ++++------ docs/reference/ocm_show.md | 4 ++-- docs/reference/ocm_show_tags.md | 6 ++---- docs/reference/ocm_show_versions.md | 10 ++++------ docs/reference/ocm_sign.md | 4 ++-- docs/reference/ocm_sign_componentversions.md | 10 ++++------ docs/reference/ocm_sign_hash.md | 6 ++---- docs/reference/ocm_toi-bootstrapping.md | 4 +--- docs/reference/ocm_toi.md | 13 ++++++------- docs/reference/ocm_transfer.md | 4 ++-- docs/reference/ocm_transfer_artifacts.md | 10 ++++------ .../ocm_transfer_commontransportarchive.md | 10 ++++------ docs/reference/ocm_transfer_componentarchive.md | 10 ++++------ docs/reference/ocm_transfer_componentversions.md | 10 ++++------ docs/reference/ocm_verify.md | 4 ++-- docs/reference/ocm_verify_componentversions.md | 10 ++++------ docs/reference/ocm_version.md | 8 ++++---- 109 files changed, 291 insertions(+), 455 deletions(-) diff --git a/docs/pluginreference/plugin.md b/docs/pluginreference/plugin.md index dfccfdc733..a1c4dabfdc 100644 --- a/docs/pluginreference/plugin.md +++ b/docs/pluginreference/plugin.md @@ -2,7 +2,7 @@ ### Synopsis -``` +```sh plugin ``` @@ -16,7 +16,6 @@ plugin ### Description - The OCM library has several extension points, which can be used by a registration mechanism to add further variants, like repository types, backend technologies, access methods, blob downloaders and uploaders. @@ -52,7 +51,6 @@ Any plugin, regardless of its functionality has to provide an [plugin info](plug which prints JSON document containing a plugin descriptor that describes the apabilities of the plugin. - ### SEE ALSO diff --git a/docs/pluginreference/plugin_accessmethod.md b/docs/pluginreference/plugin_accessmethod.md index 9449f0ba8e..ceebe2eddd 100644 --- a/docs/pluginreference/plugin_accessmethod.md +++ b/docs/pluginreference/plugin_accessmethod.md @@ -2,7 +2,7 @@ ### Synopsis -``` +```sh plugin accessmethod [] ... ``` @@ -13,13 +13,11 @@ plugin accessmethod [] ... ``` ### Description - This command group provides all commands used to implement an access method described by an access method descriptor ([plugin descriptor](plugin_descriptor.md). - ### SEE ALSO -##### Parents +#### Parents * [plugin](plugin.md) — OCM Plugin diff --git a/docs/pluginreference/plugin_accessmethod_compose.md b/docs/pluginreference/plugin_accessmethod_compose.md index e451f8f7c7..b4c908b9a6 100644 --- a/docs/pluginreference/plugin_accessmethod_compose.md +++ b/docs/pluginreference/plugin_accessmethod_compose.md @@ -2,7 +2,7 @@ ### Synopsis -``` +```sh plugin accessmethod compose [] ``` @@ -14,7 +14,6 @@ plugin accessmethod compose [] ### Description - The task of this command is to compose an access specification based on some explicitly given input options and preconfigured specifications. @@ -74,10 +73,9 @@ The following predefined value types are supported: - string=YAML: string map with arbitrary values defined by dedicated assignments - string=string: string map defined by dedicated assignments - string=string,string: string map defined by dedicated assignment of comma separated strings - ### SEE ALSO -##### Parents +#### Parents * [plugin accessmethod](plugin_accessmethod.md) — access method operations * [plugin](plugin.md) — OCM Plugin diff --git a/docs/pluginreference/plugin_accessmethod_get.md b/docs/pluginreference/plugin_accessmethod_get.md index 6c2018cc70..046ac342a0 100644 --- a/docs/pluginreference/plugin_accessmethod_get.md +++ b/docs/pluginreference/plugin_accessmethod_get.md @@ -2,7 +2,7 @@ ### Synopsis -``` +```sh plugin accessmethod get [] [] ``` @@ -16,13 +16,11 @@ plugin accessmethod get [] [] ### Description - Evaluate the given access specification and return the described blob on *stdout*. - ### SEE ALSO -##### Parents +#### Parents * [plugin accessmethod](plugin_accessmethod.md) — access method operations * [plugin](plugin.md) — OCM Plugin diff --git a/docs/pluginreference/plugin_accessmethod_validate.md b/docs/pluginreference/plugin_accessmethod_validate.md index 1bb553c1c2..b3ce5ec93a 100644 --- a/docs/pluginreference/plugin_accessmethod_validate.md +++ b/docs/pluginreference/plugin_accessmethod_validate.md @@ -2,7 +2,7 @@ ### Synopsis -``` +```sh plugin accessmethod validate [] ``` @@ -14,7 +14,6 @@ plugin accessmethod validate [] ### Description - This command accepts an access specification as argument. It is used to validate the specification and to provide some metadata for the given specification. @@ -41,10 +40,9 @@ following fields: The consumer id used to determine optional credentials for the underlying repository. If specified, at least the type field must be set. - ### SEE ALSO -##### Parents +#### Parents * [plugin accessmethod](plugin_accessmethod.md) — access method operations * [plugin](plugin.md) — OCM Plugin diff --git a/docs/pluginreference/plugin_action.md b/docs/pluginreference/plugin_action.md index 234ab75da5..eee30fe18d 100644 --- a/docs/pluginreference/plugin_action.md +++ b/docs/pluginreference/plugin_action.md @@ -2,7 +2,7 @@ ### Synopsis -``` +```sh plugin action [] ... ``` @@ -13,12 +13,10 @@ plugin action [] ... ``` ### Description - This command group provides all commands used to implement an action. - ### SEE ALSO -##### Parents +#### Parents * [plugin](plugin.md) — OCM Plugin diff --git a/docs/pluginreference/plugin_action_execute.md b/docs/pluginreference/plugin_action_execute.md index 534255a9f1..513ee489d3 100644 --- a/docs/pluginreference/plugin_action_execute.md +++ b/docs/pluginreference/plugin_action_execute.md @@ -2,7 +2,7 @@ ### Synopsis -``` +```sh plugin action execute [] ``` @@ -16,7 +16,6 @@ plugin action execute [] ### Description - This command executes an action. This action has to provide an execution result as JSON string on *stdout*. It has the @@ -33,10 +32,9 @@ following fields: Additional fields depend on the kind of action. - ### SEE ALSO -##### Parents +#### Parents * [plugin action](plugin_action.md) — action operations * [plugin](plugin.md) — OCM Plugin diff --git a/docs/pluginreference/plugin_command.md b/docs/pluginreference/plugin_command.md index 57d91820db..72c06b96f4 100644 --- a/docs/pluginreference/plugin_command.md +++ b/docs/pluginreference/plugin_command.md @@ -1,13 +1,11 @@ ## plugin command — CLI Command Extensions ### Description - This command group provides all CLI command extensions described by an access method descriptor ([plugin descriptor](plugin_descriptor.md). - ### SEE ALSO -##### Parents +#### Parents * [plugin](plugin.md) — OCM Plugin diff --git a/docs/pluginreference/plugin_describe.md b/docs/pluginreference/plugin_describe.md index 82e65ddb47..ed5ef99a43 100644 --- a/docs/pluginreference/plugin_describe.md +++ b/docs/pluginreference/plugin_describe.md @@ -2,7 +2,7 @@ ### Synopsis -``` +```sh plugin describe [] ``` @@ -13,12 +13,10 @@ plugin describe [] ``` ### Description - Display a detailed description of the capabilities of this OCM plugin. - ### SEE ALSO -##### Parents +#### Parents * [plugin](plugin.md) — OCM Plugin diff --git a/docs/pluginreference/plugin_descriptor.md b/docs/pluginreference/plugin_descriptor.md index e2c05f2bae..ca18616cf1 100644 --- a/docs/pluginreference/plugin_descriptor.md +++ b/docs/pluginreference/plugin_descriptor.md @@ -2,7 +2,6 @@ ### Description - The plugin descriptor describes the capabilities of a plugin. It uses the following fields: @@ -294,7 +293,6 @@ The descriptor for a label merge specification has the following fields: The configuration settings used for the algorithm. It may contain nested merge specifications. - ### Examples ``` @@ -332,7 +330,7 @@ The descriptor for a label merge specification has the following fields: ### SEE ALSO -##### Parents +#### Parents * [plugin](plugin.md) — OCM Plugin diff --git a/docs/pluginreference/plugin_download.md b/docs/pluginreference/plugin_download.md index 35f54e0e9e..e30d975836 100644 --- a/docs/pluginreference/plugin_download.md +++ b/docs/pluginreference/plugin_download.md @@ -2,7 +2,7 @@ ### Synopsis -``` +```sh plugin download [] [] ``` @@ -17,7 +17,6 @@ plugin download [] [] ### Description - This command accepts a target filepath as argument. It is used as base name to store the downloaded content. The blob content is provided on the *stdin*. The first argument specified the downloader to use for the operation. @@ -26,10 +25,9 @@ The task of this command is to transform the content of the provided blob into a filesystem structure applicable to the type specific tools working with content of the given artifact type. - ### SEE ALSO -##### Parents +#### Parents * [plugin](plugin.md) — OCM Plugin diff --git a/docs/pluginreference/plugin_info.md b/docs/pluginreference/plugin_info.md index 988f3a6aea..f2750d7a38 100644 --- a/docs/pluginreference/plugin_info.md +++ b/docs/pluginreference/plugin_info.md @@ -2,7 +2,7 @@ ### Synopsis -``` +```sh plugin info [] ``` @@ -14,7 +14,7 @@ plugin info [] ### SEE ALSO -##### Parents +#### Parents * [plugin](plugin.md) — OCM Plugin diff --git a/docs/pluginreference/plugin_upload.md b/docs/pluginreference/plugin_upload.md index 8234e41c1d..0ee23a42b2 100644 --- a/docs/pluginreference/plugin_upload.md +++ b/docs/pluginreference/plugin_upload.md @@ -2,7 +2,7 @@ ### Synopsis -``` +```sh plugin upload [] ... ``` @@ -14,13 +14,11 @@ plugin upload [] ... ### Description - This command group provides all commands used to implement an uploader described by an uploader descriptor. - ### SEE ALSO -##### Parents +#### Parents * [plugin](plugin.md) — OCM Plugin diff --git a/docs/pluginreference/plugin_upload_put.md b/docs/pluginreference/plugin_upload_put.md index ba61b055f8..2b8dc30023 100644 --- a/docs/pluginreference/plugin_upload_put.md +++ b/docs/pluginreference/plugin_upload_put.md @@ -2,7 +2,7 @@ ### Synopsis -``` +```sh plugin upload put [] [] ``` @@ -19,17 +19,15 @@ plugin upload put [] [] ### Description - Read the blob content from *stdin*, store the blob in the repository specified by the given repository specification and return the access specification (as JSON document string) usable to retrieve the blob, again, on * stdout*. The uploader to use is specified by the first argument. This might only be relevant, if the plugin supports multiple uploaders. - ### SEE ALSO -##### Parents +#### Parents * [plugin upload](plugin_upload.md) — upload specific operations * [plugin](plugin.md) — OCM Plugin diff --git a/docs/pluginreference/plugin_upload_validate.md b/docs/pluginreference/plugin_upload_validate.md index 8a2f1f875b..ec6405dc49 100644 --- a/docs/pluginreference/plugin_upload_validate.md +++ b/docs/pluginreference/plugin_upload_validate.md @@ -2,7 +2,7 @@ ### Synopsis -``` +```sh plugin upload validate [] [] ``` @@ -16,7 +16,6 @@ plugin upload validate [] [] ### Description - This command accepts a target specification as argument. It is used to validate the specification for the specified upoader and to provide some metadata for the given specification. @@ -30,10 +29,9 @@ following fields: underlying repository. If specified, at least the type field must be set. - ### SEE ALSO -##### Parents +#### Parents * [plugin upload](plugin_upload.md) — upload specific operations * [plugin](plugin.md) — OCM Plugin diff --git a/docs/pluginreference/plugin_valuemergehandler.md b/docs/pluginreference/plugin_valuemergehandler.md index 89d3970016..a096832d2e 100644 --- a/docs/pluginreference/plugin_valuemergehandler.md +++ b/docs/pluginreference/plugin_valuemergehandler.md @@ -2,7 +2,7 @@ ### Synopsis -``` +```sh plugin valuemergehandler [] ... ``` @@ -13,12 +13,10 @@ plugin valuemergehandler [] ... ``` ### Description - This command group provides all commands used to implement an value merge handlers. - ### SEE ALSO -##### Parents +#### Parents * [plugin](plugin.md) — OCM Plugin diff --git a/docs/pluginreference/plugin_valuemergehandler_execute.md b/docs/pluginreference/plugin_valuemergehandler_execute.md index a2f95a7ac3..19a33e4054 100644 --- a/docs/pluginreference/plugin_valuemergehandler_execute.md +++ b/docs/pluginreference/plugin_valuemergehandler_execute.md @@ -2,7 +2,7 @@ ### Synopsis -``` +```sh plugin valuemergehandler execute [] ``` @@ -14,7 +14,6 @@ plugin valuemergehandler execute [] ### Description - This command executes a value merge. The values are taken from *stdin* as JSON string. It has the following fields: @@ -41,10 +40,9 @@ following fields: An error message. - ### SEE ALSO -##### Parents +#### Parents * [plugin valuemergehandler](plugin_valuemergehandler.md) — value merge handler operations * [plugin](plugin.md) — OCM Plugin diff --git a/docs/pluginreference/plugin_valueset.md b/docs/pluginreference/plugin_valueset.md index 81c8c1dad7..3d124b9828 100644 --- a/docs/pluginreference/plugin_valueset.md +++ b/docs/pluginreference/plugin_valueset.md @@ -2,7 +2,7 @@ ### Synopsis -``` +```sh plugin valueset [] ... ``` @@ -13,13 +13,11 @@ plugin valueset [] ... ``` ### Description - This command group provides all commands used to implement a value set described by a value set descriptor ([plugin descriptor](plugin_descriptor.md). - ### SEE ALSO -##### Parents +#### Parents * [plugin](plugin.md) — OCM Plugin diff --git a/docs/pluginreference/plugin_valueset_compose.md b/docs/pluginreference/plugin_valueset_compose.md index f7513c805b..886093270d 100644 --- a/docs/pluginreference/plugin_valueset_compose.md +++ b/docs/pluginreference/plugin_valueset_compose.md @@ -2,7 +2,7 @@ ### Synopsis -``` +```sh plugin valueset compose [] ``` @@ -14,7 +14,6 @@ plugin valueset compose [string=YAML: string map with arbitrary values defined by dedicated assignments - string=string: string map defined by dedicated assignments - string=string,string: string map defined by dedicated assignment of comma separated strings - ### SEE ALSO -##### Parents +#### Parents * [plugin valueset](plugin_valueset.md) — valueset operations * [plugin](plugin.md) — OCM Plugin diff --git a/docs/pluginreference/plugin_valueset_validate.md b/docs/pluginreference/plugin_valueset_validate.md index cdba2f357c..0c882b1286 100644 --- a/docs/pluginreference/plugin_valueset_validate.md +++ b/docs/pluginreference/plugin_valueset_validate.md @@ -2,7 +2,7 @@ ### Synopsis -``` +```sh plugin valueset validate [] ``` @@ -14,7 +14,6 @@ plugin valueset validate [] ### Description - This command accepts a value set as argument. It is used to validate the specification and to provide some metadata for the given specification. @@ -26,10 +25,9 @@ following fields: A short textual description of the described value set. - ### SEE ALSO -##### Parents +#### Parents * [plugin valueset](plugin_valueset.md) — valueset operations * [plugin](plugin.md) — OCM Plugin diff --git a/docs/reference/ocm.md b/docs/reference/ocm.md index bf1e08c570..b47624f49d 100644 --- a/docs/reference/ocm.md +++ b/docs/reference/ocm.md @@ -2,7 +2,7 @@ ### Synopsis -``` +```sh ocm [] ... ``` @@ -29,7 +29,6 @@ ocm [] ... ### 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. @@ -353,7 +352,6 @@ 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 diff --git a/docs/reference/ocm_add.md b/docs/reference/ocm_add.md index c479623e85..8087f15b7b 100644 --- a/docs/reference/ocm_add.md +++ b/docs/reference/ocm_add.md @@ -2,7 +2,7 @@ ### Synopsis -``` +```sh ocm add [] ... ``` @@ -14,7 +14,7 @@ ocm add [] ... ### SEE ALSO -##### Parents +#### Parents * [ocm](ocm.md) — Open Component Model command line client diff --git a/docs/reference/ocm_add_componentversions.md b/docs/reference/ocm_add_componentversions.md index 18174e6ae2..b0aa969c0e 100644 --- a/docs/reference/ocm_add_componentversions.md +++ b/docs/reference/ocm_add_componentversions.md @@ -2,13 +2,13 @@ ### Synopsis -``` +```sh ocm add componentversions [] [--version ] [] {} ``` -##### Aliases +#### Aliases -``` +```text componentversions, componentversion, cv, components, component, comps, comp, c ``` @@ -37,7 +37,6 @@ componentversions, componentversion, cv, components, component, comps, comp, c ### Description - Add component versions specified by a constructor file to a Common Transport Archive. The archive might be either a directory prepared to host component version content or a tar/tgz file (see option --type). @@ -212,7 +211,6 @@ The uploader name may be a path expression with the following possibilities: See [ocm ocm-uploadhandlers](ocm_ocm-uploadhandlers.md) for further details on using upload handlers. - ### Examples @@ -259,7 +257,7 @@ next to the description file. ### SEE ALSO -##### Parents +#### Parents * [ocm add](ocm_add.md) — Add elements to a component repository or component version * [ocm](ocm.md) — Open Component Model command line client diff --git a/docs/reference/ocm_add_componentversions_ocm-labels.md b/docs/reference/ocm_add_componentversions_ocm-labels.md index 4652a06ec6..0e613ca79d 100644 --- a/docs/reference/ocm_add_componentversions_ocm-labels.md +++ b/docs/reference/ocm_add_componentversions_ocm-labels.md @@ -2,7 +2,6 @@ ### Description - Labels are a set of arbitrary properties, which can be attached to elements of a component version: - a component version itself @@ -171,10 +170,9 @@ The following algorithms are possible: The following label assignments are configured: - label:routing-slips: simpleMapMerge - ### SEE ALSO -##### Parents +#### Parents * [ocm add componentversions](ocm_add_componentversions.md) — add component version(s) to a (new) transport archive * [ocm add](ocm_add.md) — Add elements to a component repository or component version diff --git a/docs/reference/ocm_add_references.md b/docs/reference/ocm_add_references.md index ddae161009..41d76d17e0 100644 --- a/docs/reference/ocm_add_references.md +++ b/docs/reference/ocm_add_references.md @@ -2,13 +2,13 @@ ### Synopsis -``` +```sh ocm add references [] [] { | =} ``` -##### Aliases +#### Aliases -``` +```text references, reference, refs ``` @@ -39,7 +39,6 @@ references, reference, refs ### Description - Add aggregation information specified in a reference file to a component version. So far only component archives are supported as target. @@ -156,7 +155,6 @@ There are several templaters that can be selected by the --templater - ### Examples @@ -188,7 +186,7 @@ $ ocm add references path/to/ca references.yaml VERSION=1.0.0 ### SEE ALSO -##### Parents +#### Parents * [ocm add](ocm_add.md) — Add elements to a component repository or component version * [ocm](ocm.md) — Open Component Model command line client diff --git a/docs/reference/ocm_add_resource-configuration.md b/docs/reference/ocm_add_resource-configuration.md index 19b89ca832..f86c4e3f2a 100644 --- a/docs/reference/ocm_add_resource-configuration.md +++ b/docs/reference/ocm_add_resource-configuration.md @@ -2,13 +2,13 @@ ### Synopsis -``` +```sh ocm add resource-configuration [] { | =} ``` -##### Aliases +#### Aliases -``` +```text resource-configuration, resourceconfig, rsccfg, rcfg ``` @@ -101,7 +101,6 @@ resource-configuration, resourceconfig, rsccfg, rcfg ### Description - Add a resource specification to a resource config file used by [ocm add resources](ocm_add_resources.md). It is possible to describe a single resource via command line options. @@ -972,7 +971,6 @@ There are several templaters that can be selected by the --templater - ### Examples ``` @@ -981,7 +979,7 @@ $ ocm add resource-configuration resources.yaml --name myresource --type PlainTe ### SEE ALSO -##### Parents +#### Parents * [ocm add](ocm_add.md) — Add elements to a component repository or component version * [ocm](ocm.md) — Open Component Model command line client diff --git a/docs/reference/ocm_add_resources.md b/docs/reference/ocm_add_resources.md index 6265a41af7..a1b624b102 100644 --- a/docs/reference/ocm_add_resources.md +++ b/docs/reference/ocm_add_resources.md @@ -2,13 +2,13 @@ ### Synopsis -``` +```sh ocm add resources [] [] { | =} ``` -##### Aliases +#### Aliases -``` +```text resources, resource, res, r ``` @@ -108,7 +108,6 @@ resources, resource, res, r ### Description - Adds resources specified in a resource file to a component version. So far, only component archives are supported as target. @@ -989,7 +988,6 @@ There are several templaters that can be selected by the --templater - ### Examples @@ -1025,7 +1023,7 @@ $ ocm add resources ‐‐file path/to/ca resources.yaml VERSION=1.0.0 ### SEE ALSO -##### Parents +#### Parents * [ocm add](ocm_add.md) — Add elements to a component repository or component version * [ocm](ocm.md) — Open Component Model command line client diff --git a/docs/reference/ocm_add_routingslips.md b/docs/reference/ocm_add_routingslips.md index ce8478ffa4..8636dd0427 100644 --- a/docs/reference/ocm_add_routingslips.md +++ b/docs/reference/ocm_add_routingslips.md @@ -2,13 +2,13 @@ ### Synopsis -``` +```sh ocm add routingslips [] ``` -##### Aliases +#### Aliases -``` +```text routingslips, routingslip, rs ``` @@ -33,7 +33,6 @@ routingslips, routingslip, rs ### Description - Add a routing slip entry for the specified routing slip name to the given component version. The name is typically a DNS domain name followed by some qualifiers separated by a slash (/). It is possible to use arbitrary types, @@ -114,7 +113,6 @@ it only contains a single component version. Therefore, in this scenario this option must always be specified to be able to follow component references. - ### Examples ``` @@ -123,7 +121,7 @@ $ ocm add routingslip ghcr.io/mandelsoft/ocm//ocmdemoinstaller:0.0.1-dev mandels ### SEE ALSO -##### Parents +#### Parents * [ocm add](ocm_add.md) — Add elements to a component repository or component version * [ocm](ocm.md) — Open Component Model command line client diff --git a/docs/reference/ocm_add_source-configuration.md b/docs/reference/ocm_add_source-configuration.md index 9626b9a720..aaafe7acb7 100644 --- a/docs/reference/ocm_add_source-configuration.md +++ b/docs/reference/ocm_add_source-configuration.md @@ -2,13 +2,13 @@ ### Synopsis -``` +```sh ocm add source-configuration [] { | =} ``` -##### Aliases +#### Aliases -``` +```text source-configuration, sourceconfig, srccfg, scfg ``` @@ -100,7 +100,6 @@ source-configuration, sourceconfig, srccfg, scfg ### Description - Add a source specification to a source config file used by [ocm add sources](ocm_add_sources.md). It is possible to describe a single source via command line options. @@ -972,7 +971,6 @@ There are several templaters that can be selected by the --templater - ### Examples ``` @@ -981,7 +979,7 @@ $ ocm add source-config sources.yaml --name sources --type filesystem --access ' ### SEE ALSO -##### Parents +#### Parents * [ocm add](ocm_add.md) — Add elements to a component repository or component version * [ocm](ocm.md) — Open Component Model command line client diff --git a/docs/reference/ocm_add_sources.md b/docs/reference/ocm_add_sources.md index 34903cf46a..df2e70be1f 100644 --- a/docs/reference/ocm_add_sources.md +++ b/docs/reference/ocm_add_sources.md @@ -2,13 +2,13 @@ ### Synopsis -``` +```sh ocm add sources [] [] { | =} ``` -##### Aliases +#### Aliases -``` +```text sources, source, src, s ``` @@ -106,7 +106,6 @@ sources, source, src, s ### 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. @@ -987,7 +986,6 @@ There are several templaters that can be selected by the --templater - ### Examples ``` @@ -996,7 +994,7 @@ $ ocm add sources --file path/to/cafile sources.yaml ### SEE ALSO -##### Parents +#### Parents * [ocm add](ocm_add.md) — Add elements to a component repository or component version * [ocm](ocm.md) — Open Component Model command line client diff --git a/docs/reference/ocm_attributes.md b/docs/reference/ocm_attributes.md index 48124fd901..fbebdab82d 100644 --- a/docs/reference/ocm_attributes.md +++ b/docs/reference/ocm_attributes.md @@ -2,7 +2,6 @@ ### Description - The OCM library supports a set of attributes, which can be used to influence the behaviour of various functions. The CLI also supports setting of those attributes using the config file (see [ocm configfile](ocm_configfile.md)) or by @@ -206,10 +205,9 @@ OCM library: - *rekorURL* *string* default is https://rekor.sigstore.dev - *OIDCIssuer* *string* default is https://oauth2.sigstore.dev/auth - *OIDCClientID* *string* default is sigstore - ### SEE ALSO -##### Parents +#### Parents * [ocm](ocm.md) — Open Component Model command line client diff --git a/docs/reference/ocm_bootstrap.md b/docs/reference/ocm_bootstrap.md index 14ed4fb875..76770d70d8 100644 --- a/docs/reference/ocm_bootstrap.md +++ b/docs/reference/ocm_bootstrap.md @@ -2,7 +2,7 @@ ### Synopsis -``` +```sh ocm bootstrap [] ... ``` @@ -14,7 +14,7 @@ ocm bootstrap [] ... ### SEE ALSO -##### Parents +#### Parents * [ocm](ocm.md) — Open Component Model command line client diff --git a/docs/reference/ocm_bootstrap_configuration.md b/docs/reference/ocm_bootstrap_configuration.md index e7609ec4cb..40b29c9e71 100644 --- a/docs/reference/ocm_bootstrap_configuration.md +++ b/docs/reference/ocm_bootstrap_configuration.md @@ -2,13 +2,13 @@ ### Synopsis -``` +```sh ocm bootstrap configuration [] {} {} ``` -##### Aliases +#### Aliases -``` +```text configuration, config, cfg ``` @@ -24,7 +24,6 @@ configuration, config, cfg ### Description - If a TOI package provides information for configuration file templates/prototypes this command extracts this data and provides appropriate files in the filesystem. @@ -95,7 +94,6 @@ it only contains a single component version. Therefore, in this scenario this option must always be specified to be able to follow component references. - ### Examples ``` @@ -104,7 +102,7 @@ $ ocm toi bootstrap config ghcr.io/mandelsoft/ocm//ocmdemoinstaller:0.0.1-dev ### SEE ALSO -##### Parents +#### Parents * [ocm bootstrap](ocm_bootstrap.md) — bootstrap components * [ocm](ocm.md) — Open Component Model command line client diff --git a/docs/reference/ocm_bootstrap_configuration_toi-bootstrapping.md b/docs/reference/ocm_bootstrap_configuration_toi-bootstrapping.md index f40b3daee0..8795110f04 100644 --- a/docs/reference/ocm_bootstrap_configuration_toi-bootstrapping.md +++ b/docs/reference/ocm_bootstrap_configuration_toi-bootstrapping.md @@ -2,7 +2,6 @@ ### Description - TOI is a small toolset on top of the Open Component Model. It provides a possibility to run images taken from a component version with user configuration and feed them with the content of this component version. @@ -400,7 +399,6 @@ Basically the output may contain any data, but is strongly recommended to use yaml or json files, only. This enables further formal processing by the TOI toolset. - ### Examples ``` @@ -452,7 +450,7 @@ additionalResources: ### SEE ALSO -##### Parents +#### Parents * [ocm bootstrap configuration](ocm_bootstrap_configuration.md) — bootstrap TOI configuration files * [ocm bootstrap](ocm_bootstrap.md) — bootstrap components diff --git a/docs/reference/ocm_bootstrap_package.md b/docs/reference/ocm_bootstrap_package.md index acfaf415af..60c2515653 100644 --- a/docs/reference/ocm_bootstrap_package.md +++ b/docs/reference/ocm_bootstrap_package.md @@ -2,13 +2,13 @@ ### Synopsis -``` +```sh ocm bootstrap package [] {} {} ``` -##### Aliases +#### Aliases -``` +```text package, pkg, componentversion, cv, component, comp, c ``` @@ -27,7 +27,6 @@ package, pkg, componentversion, cv, component, comp, c ### Description - Use the simple TOI bootstrap mechanism to execute actions for a TOI package resource based on the content of an OCM component version and some command input describing the dedicated installation target. @@ -176,7 +175,6 @@ it only contains a single component version. Therefore, in this scenario this option must always be specified to be able to follow component references. - ### Examples ``` @@ -185,7 +183,7 @@ $ ocm toi bootstrap package ghcr.io/mandelsoft/ocm//ocmdemoinstaller:0.0.1-dev ### SEE ALSO -##### Parents +#### Parents * [ocm bootstrap](ocm_bootstrap.md) — bootstrap components * [ocm](ocm.md) — Open Component Model command line client diff --git a/docs/reference/ocm_bootstrap_package_toi-bootstrapping.md b/docs/reference/ocm_bootstrap_package_toi-bootstrapping.md index 2fb9215c24..b777d84361 100644 --- a/docs/reference/ocm_bootstrap_package_toi-bootstrapping.md +++ b/docs/reference/ocm_bootstrap_package_toi-bootstrapping.md @@ -2,7 +2,6 @@ ### Description - TOI is a small toolset on top of the Open Component Model. It provides a possibility to run images taken from a component version with user configuration and feed them with the content of this component version. @@ -400,7 +399,6 @@ Basically the output may contain any data, but is strongly recommended to use yaml or json files, only. This enables further formal processing by the TOI toolset. - ### Examples ``` @@ -452,7 +450,7 @@ additionalResources: ### SEE ALSO -##### Parents +#### Parents * [ocm bootstrap package](ocm_bootstrap_package.md) — bootstrap component version * [ocm bootstrap](ocm_bootstrap.md) — bootstrap components diff --git a/docs/reference/ocm_cache.md b/docs/reference/ocm_cache.md index 9ec1ae5c2b..b664b59986 100644 --- a/docs/reference/ocm_cache.md +++ b/docs/reference/ocm_cache.md @@ -2,7 +2,7 @@ ### Synopsis -``` +```sh ocm cache [] ... ``` @@ -14,7 +14,7 @@ ocm cache [] ... ### SEE ALSO -##### Parents +#### Parents * [ocm](ocm.md) — Open Component Model command line client diff --git a/docs/reference/ocm_check.md b/docs/reference/ocm_check.md index 0d3a7b9f2a..c2f99a3d98 100644 --- a/docs/reference/ocm_check.md +++ b/docs/reference/ocm_check.md @@ -2,7 +2,7 @@ ### Synopsis -``` +```sh ocm check [] ... ``` @@ -14,7 +14,7 @@ ocm check [] ... ### SEE ALSO -##### Parents +#### Parents * [ocm](ocm.md) — Open Component Model command line client diff --git a/docs/reference/ocm_check_componentversions.md b/docs/reference/ocm_check_componentversions.md index 03860c1dab..699c0b98e2 100644 --- a/docs/reference/ocm_check_componentversions.md +++ b/docs/reference/ocm_check_componentversions.md @@ -2,13 +2,13 @@ ### Synopsis -``` +```sh ocm check componentversions [] {} ``` -##### Aliases +#### Aliases -``` +```text componentversions, componentversion, cv, components, component, comps, comp, c ``` @@ -26,7 +26,6 @@ componentversions, componentversion, cv, components, component, comps, comp, c ### Description - This command checks, whether component versions are completely contained in an OCM repository with all its dependent component references. @@ -87,7 +86,6 @@ The following modes are supported: - wide - yaml - ### Examples ``` @@ -97,7 +95,7 @@ $ ocm get componentversion --repo OCIRegistry::ghcr.io mandelsoft/kubelink ### SEE ALSO -##### Parents +#### Parents * [ocm check](ocm_check.md) — check components in OCM repository * [ocm](ocm.md) — Open Component Model command line client diff --git a/docs/reference/ocm_clean.md b/docs/reference/ocm_clean.md index 164d8875b4..eb142aca23 100644 --- a/docs/reference/ocm_clean.md +++ b/docs/reference/ocm_clean.md @@ -2,7 +2,7 @@ ### Synopsis -``` +```sh ocm clean [] ... ``` @@ -14,7 +14,7 @@ ocm clean [] ... ### SEE ALSO -##### Parents +#### Parents * [ocm](ocm.md) — Open Component Model command line client diff --git a/docs/reference/ocm_clean_cache.md b/docs/reference/ocm_clean_cache.md index 133dd3105a..c43d1b3fab 100644 --- a/docs/reference/ocm_clean_cache.md +++ b/docs/reference/ocm_clean_cache.md @@ -2,7 +2,7 @@ ### Synopsis -``` +```sh ocm clean cache [] ``` @@ -16,10 +16,8 @@ ocm clean cache [] ### Description - Cleanup all blobs stored in oci blob cache (if given). - ### Examples ``` @@ -28,7 +26,7 @@ $ ocm clean cache ### SEE ALSO -##### Parents +#### Parents * [ocm clean](ocm_clean.md) — Cleanup/re-organize elements * [ocm](ocm.md) — Open Component Model command line client diff --git a/docs/reference/ocm_configfile.md b/docs/reference/ocm_configfile.md index 2e28cd951f..1949d1e712 100644 --- a/docs/reference/ocm_configfile.md +++ b/docs/reference/ocm_configfile.md @@ -2,7 +2,6 @@ ### Description - The command line client supports configuring by a given configuration file. If existent, by default, the file $HOME/.ocmconfig will be read. Using the option --config an alternative file can be specified. @@ -326,7 +325,6 @@ The following configuration types are supported: ... - ### Examples ``` @@ -350,7 +348,7 @@ configurations: ### SEE ALSO -##### Parents +#### Parents * [ocm](ocm.md) — Open Component Model command line client diff --git a/docs/reference/ocm_controller.md b/docs/reference/ocm_controller.md index e74255bbaa..1f61cdb543 100644 --- a/docs/reference/ocm_controller.md +++ b/docs/reference/ocm_controller.md @@ -2,7 +2,7 @@ ### Synopsis -``` +```sh ocm controller [] ... ``` @@ -14,7 +14,7 @@ ocm controller [] ... ### SEE ALSO -##### Parents +#### Parents * [ocm](ocm.md) — Open Component Model command line client diff --git a/docs/reference/ocm_controller_install.md b/docs/reference/ocm_controller_install.md index 3c597bb1d4..a56fe2de7e 100644 --- a/docs/reference/ocm_controller_install.md +++ b/docs/reference/ocm_controller_install.md @@ -2,7 +2,7 @@ ### Synopsis -``` +```sh ocm controller install controller {--version v0.0.1} ``` @@ -27,7 +27,7 @@ ocm controller install controller {--version v0.0.1} ### SEE ALSO -##### Parents +#### Parents * [ocm controller](ocm_controller.md) — Commands acting on the ocm-controller * [ocm](ocm.md) — Open Component Model command line client diff --git a/docs/reference/ocm_controller_uninstall.md b/docs/reference/ocm_controller_uninstall.md index 21f3ce288c..ed39f08925 100644 --- a/docs/reference/ocm_controller_uninstall.md +++ b/docs/reference/ocm_controller_uninstall.md @@ -2,7 +2,7 @@ ### Synopsis -``` +```sh ocm controller uninstall controller ``` @@ -26,7 +26,7 @@ ocm controller uninstall controller ### SEE ALSO -##### Parents +#### Parents * [ocm controller](ocm_controller.md) — Commands acting on the ocm-controller * [ocm](ocm.md) — Open Component Model command line client diff --git a/docs/reference/ocm_create.md b/docs/reference/ocm_create.md index f3f37341e6..776bc2980f 100644 --- a/docs/reference/ocm_create.md +++ b/docs/reference/ocm_create.md @@ -2,7 +2,7 @@ ### Synopsis -``` +```sh ocm create [] ... ``` @@ -14,7 +14,7 @@ ocm create [] ... ### SEE ALSO -##### Parents +#### Parents * [ocm](ocm.md) — Open Component Model command line client diff --git a/docs/reference/ocm_create_componentarchive.md b/docs/reference/ocm_create_componentarchive.md index e56306ad7f..096893e603 100644 --- a/docs/reference/ocm_create_componentarchive.md +++ b/docs/reference/ocm_create_componentarchive.md @@ -2,13 +2,13 @@ ### Synopsis -``` +```sh ocm create componentarchive [] --provider {--provider