Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Extended Tour Documentation #614

Merged
merged 10 commits into from
Jan 4, 2024
Merged

Conversation

mandelsoft
Copy link
Contributor

@mandelsoft mandelsoft commented Jan 2, 2024

Description

The tour examples in examples/lib/tour to illustrate the library usage scenarios have been extended and
the README files now contain a complete walkthrough explaining the various code fragments.

These markdown files are now generated based on mdref to keep
the code fragments in the documentation up to date with the actual example coding.

Just call go generate examples/lib/... to generate the markdown files.
The Makefile and the installation targets have been updated accordingly.

What type of PR is this? (check all applicable)

  • 🍕 Feature
  • 🐛 Bug Fix
  • 📝 Documentation Update
  • 🎨 Style
  • 🧑‍💻 Code Refactor
  • 🔥 Performance Improvements
  • ✅ Test
  • 🤖 Build
  • 🔁 CI
  • 📦 Chore (Release)
  • ⏩ Revert

Related Tickets & Documents

  • Related Issue # (issue)
  • Closes # (issue)
  • Fixes # (issue)

Remove if not applicable

Screenshots

Added tests?

  • 👍 yes
  • 🙅 no, because they aren't needed
  • 🙋 no, because I need help
  • Separate ticket for tests # (issue/pr)

Please describe the tests that you ran to verify your changes. Provide instructions so we can reproduce. Please also list any relevant details for your test configuration

Added to documentation?

  • 📜 README.md
  • 🙅 no documentation needed

Checklist:

  • My code follows the style guidelines of this project
  • I have performed a self-review of my code
  • I have commented my code, particularly in hard-to-understand areas
  • I have made corresponding changes to the documentation
  • My changes generate no new warnings
  • I have added tests that prove my fix is effective or that my feature works
  • New and existing unit tests pass locally with my changes
  • Any dependent changes have been merged and published in downstream modules

@@ -3,11 +3,265 @@
This [tour](example.go) illustrates the basic usage of the API to
access component versions in an OCM repository.

## Running the example

You can just call the main program with some config file argument
Copy link
Contributor

@morri-son morri-son Jan 3, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
You can just call the main program with some config file argument
You can call the main program with a config file argument,

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

done

@@ -3,11 +3,265 @@
This [tour](example.go) illustrates the basic usage of the API to
access component versions in an OCM repository.

## Running the example

You can just call the main program with some config file argument
with the following content:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
with the following content:
where the config file has the following content:

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

done

ecosystem.

Therefore, the first step is always to get access to such
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Therefore, the first step is always to get access to such
The first step is always to get access to such

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Therefore relates to the paragraph before, therefore I think it should be ok.

type registration contained in the executable.

It can be accessed by a function of the ocm package.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
It can be accessed by a function of the ocm package.
It can be accessed by a function of the `ocm` package.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

done

First, we get a repository, to look for
component versions. We use the OCM
repository providing the standard OCM
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
repository providing the standard OCM
repository hosted on `ghcr.io` and which is providing

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

done

component versions. We use the OCM
repository providing the standard OCM
components hosted on `ghcr.io`.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
components hosted on `ghcr.io`.
the standard OCM components.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

done

```

Many objects must be closed, if they should not be used
Copy link
Contributor

@morri-son morri-son Jan 3, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Many objects must be closed, if they should not be used
To release potentially allocated temporary resources,

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

done


Many objects must be closed, if they should not be used
anymore, to release potentially allocated temporary resources.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

many objects must be closed, if they should not be used anymore.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

done

```

OCM version names must follow the semver rules.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
OCM version names must follow the semver rules.
OCM version names must follow the SemVer rules.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

done

```

Now, we have a look at the latest version, it is
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Now, we have a look at the latest version, it is
Now, we have a look at the latest version. It is

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

done


Resources have some metadata, like the resource identity and a resource type.
And they describe how the content of the resource (as blob) can be accessed.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
And they describe how the content of the resource (as blob) can be accessed.
They describe how the content of the resource (as blob) can be accessed.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

And relates to the sentence before

like the respository specification.

The component version contains the executables for the OCM CLI
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

sollte man hier nicht eventuell das "component version" als resource in Hochticks stellen oder noch so etwas wie "die Resource" oder "der Typ" oder was component version hier auch immer ist?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There are more errors, here, fo example, the identity is not stored as label. I've reformulated the paragraph.

get the executable for the actual environment.
The identity of a resource described by a component version
consists of a set of properties. The property name must
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
consists of a set of properties. The property name must
consists of a set of properties. The property `name` is mandatory.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

done

The identity of a resource described by a component version
consists of a set of properties. The property name must
always be given.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
always be given.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

done

```

Now we want to retrieve the executable. There are two basic ways
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Now we want to retrieve the executable. There are two basic ways
Now we want to retrieve the executable and there are two basic ways

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

reformulated

The method needs to be closed, because the method
object may cache the technical blob representation
generated accessing the underlying access technology.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
generated accessing the underlying access technology.
generated to access the underlying access technology.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

by accessing

selected resource and mime type combinations.
The executable downloader is registered by default and automatically
sets the X flag.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
sets the X flag.
sets the `X` flag.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

done

# Composing a Component Version

This tor illustrates the basic usage of the API to
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 filesystem
Copy link
Contributor

@morri-son morri-son Jan 3, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
- [`basic`](01-basic-componentversion-creation.go) Create a component version stored in the filesystem
- [`basic`](01-basic-componentversion-creation.go) Create a component version stored in the file system.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

done

the *Common Transport Format* (CTF).

As usual, we start with getting access to an OCM context
object
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
object
object:

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

done

```

To compose and store a new component version
we finally need some OCM repository to
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
we finally need some OCM repository to
we need some OCM repository to

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

done

different repository path (the GitHub org/user).
Therefore, different credentials needs to be provided
for different repository paths.
For example credentials for ghcr.io/acme can be used
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
For example credentials for ghcr.io/acme can be used
For example, credentials for ghcr.io/acme can be used

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

done

Everything can be done directly with the core interface
and property name constants provided by the dedicted technologies.

Once we have the id we can finnaly set the credentials for this
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Once we have the id we can finnaly set the credentials for this
Once we have the id we can finaly set the credentials for this

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

done


Now, the context is prepared to provide credentials
for any usage of our OCI registry
Lets test, whether it could provide credentials
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Lets test, whether it could provide credentials
Let's test whether it could provide credentials

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

done

```

Second, we determine the consumer id for our intended repository acccess.
A credential consumer may provide might provide consumer id information
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
A credential consumer may provide might provide consumer id information
A credential consumer may provide consumer id information

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

done

The basic context method `credctx.GetCredentialsForConsumer` returns
a credentials source interface able to provide credentials
for a changing credentials source. Here, we use a convenience
function directly providing a credentials interface for the
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
function directly providing a credentials interface for the
function, which directly provides a credentials interface for the

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

done

actually valid credentials.
An error is only provided if something went wrong while determining
the credentials. Delivering NO credentials is a valid result.
the returned interface then offers access to the credential properties.
Copy link
Contributor

@morri-son morri-son Jan 3, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
the returned interface then offers access to the credential properties.
The returned interface then offers access to the credential properties

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

done

Now, we can continue with our basic component version composition
from the last example, or we just display the content.

The following code snipped show the code for the `context` variant
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
The following code snipped show the code for the `context` variant
The following code snipped shows the code for the `context` variant

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

done


The following code snipped show the code for the `context` variant
creating a new version, the `read` variant just omits the version creation.
The rest of the example is then the same.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
The rest of the example is then the same.
The rest of the example is the same.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

done

{{include}{../../03-working-with-credentials/02-basic-credential-management.go}{examine cli}}
```

This resource access points effectively to the same OCI registry,
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
This resource access points effectively to the same OCI registry,
This resource access effectively points to the same OCI registry,

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

done

is able to provide any number of named
credential sets. This way any special
credential store can be connected to the
OCM credential management judt by providing
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
OCM credential management judt by providing
OCM credential management just by providing

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

done

OCM credential management judt by providing
an own implementation for the repository interface.

One such case is the docker config json, a config
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
One such case is the docker config json, a config
One such case is the Docker config json, a config

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

done

```

There are general credential stores, like a HashiCorp Vault
or type-specific ones, like the docker config json
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
or type-specific ones, like the docker config json
or type-specific ones, like the Docker config json

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

done


There are general credential stores, like a HashiCorp Vault
or type-specific ones, like the docker config json
used to configure credentials for the docker client.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
used to configure credentials for the docker client.
used to configure credentials for the Docker client.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

done

Those specialized repository implementations are not only able to
provide credential sets, they also know about the usage context
of the provided credentials.
Therefore, such repository implementations are able to provide credential
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Therefore, such repository implementations are able to provide credential
Therefore, such repository implementations are also able to provide credential

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

done

provide credential sets, they also know about the usage context
of the provided credentials.
Therefore, such repository implementations are able to provide credential
mappings for consumer ids, also. This is supported by the credential repository
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
mappings for consumer ids, also. This is supported by the credential repository
mappings for consumer ids. This is supported by the credential repository

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

done

example used by the `vault` implementation. It uses dedicated attributes
to allow the user to configure intended consumer id properties.

now we can just add the repository for this specification to
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
now we can just add the repository for this specification to
Now we can just add the repository for this specification to

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

done

ocmConfig: <config file>
```

The actual version of the example just works with the filesystem
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
The actual version of the example just works with the filesystem
The actual version of the example just works with the file system

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

done


The actual version of the example just works with the filesystem
target, because it is not possible to specify credentials for the
target repository in this simple config file. But, if you specific an [OCM config file](../04-working-with-config/README.md) you can
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
target repository in this simple config file. But, if you specific an [OCM config file](../04-working-with-config/README.md) you can
target repository in this simple config file. But, if you specify
an [OCM config file](../04-working-with-config/README.md) you can

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

done

The actual version of the example just works with the filesystem
target, because it is not possible to specify credentials for the
target repository in this simple config file. But, if you specific an [OCM config file](../04-working-with-config/README.md) you can
add more credential settings to make target repositories possible
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

was meinst du damit? "to make target repositories possible requiring credentials" ?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

explained

Here, all resources are transported per value, all external
references will be inlined as `localBlob`s and imported into
the target environment, applying blob upload handlers
where possible. For a CTF Archive as target, there are no
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
where possible. For a CTF Archive as target, there are no
where possible. For a CTF archive as target, there are no

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

done

references will be inlined as `localBlob`s and imported into
the target environment, applying blob upload handlers
where possible. For a CTF Archive as target, there are no
configured handlers, by default. Therefore, all resources will
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
configured handlers, by default. Therefore, all resources will
configured handlers by default. Therefore, all resources will

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

done

ocmConfig: <your ocm config file>
```

The actual version of the example just works with the filesystem
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
The actual version of the example just works with the filesystem
The actual version of the example just works with the file system

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

done

morri-son
morri-son previously approved these changes Jan 4, 2024
@mandelsoft mandelsoft merged commit 0c66570 into open-component-model:main Jan 4, 2024
11 of 12 checks passed
@mandelsoft mandelsoft deleted the doc branch January 4, 2024 12:54
Hereby, blobs are stored along with the component descriptor
instead of storing a reference to content in an external repository.

The most simple form is to directly provide a byte sequence,
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The simplest form....

@mandelsoft mandelsoft restored the doc branch August 16, 2024 08:56
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants