-
Notifications
You must be signed in to change notification settings - Fork 21
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
Conversation
@@ -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 |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
You can just call the main program with some config file argument | |
You can call the main program with a config file argument, |
There was a problem hiding this comment.
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: |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
with the following content: | |
where the config file has the following content: |
There was a problem hiding this comment.
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 |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Therefore, the first step is always to get access to such | |
The first step is always to get access to such |
There was a problem hiding this comment.
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. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
It can be accessed by a function of the ocm package. | |
It can be accessed by a function of the `ocm` package. |
There was a problem hiding this comment.
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 |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
repository providing the standard OCM | |
repository hosted on `ghcr.io` and which is providing |
There was a problem hiding this comment.
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`. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
components hosted on `ghcr.io`. | |
the standard OCM components. |
There was a problem hiding this comment.
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 |
There was a problem hiding this comment.
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 | |
To release potentially allocated temporary resources, |
There was a problem hiding this comment.
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. |
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
OCM version names must follow the semver rules. | |
OCM version names must follow the SemVer rules. |
There was a problem hiding this comment.
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 |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Now, we have a look at the latest version, it is | |
Now, we have a look at the latest version. It is |
There was a problem hiding this comment.
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. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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. |
There was a problem hiding this comment.
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 |
There was a problem hiding this comment.
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?
There was a problem hiding this comment.
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 |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
consists of a set of properties. The property name must | |
consists of a set of properties. The property `name` is mandatory. |
There was a problem hiding this comment.
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. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
always be given. |
There was a problem hiding this comment.
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 |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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 |
There was a problem hiding this comment.
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. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
generated accessing the underlying access technology. | |
generated to access the underlying access technology. |
There was a problem hiding this comment.
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. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
sets the X flag. | |
sets the `X` flag. |
There was a problem hiding this comment.
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 |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
- [`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. |
There was a problem hiding this comment.
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 |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
object | |
object: |
There was a problem hiding this comment.
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 |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
we finally need some OCM repository to | |
we need some OCM repository to |
There was a problem hiding this comment.
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 |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
For example credentials for ghcr.io/acme can be used | |
For example, credentials for ghcr.io/acme can be used |
There was a problem hiding this comment.
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 |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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 |
There was a problem hiding this comment.
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 |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Lets test, whether it could provide credentials | |
Let's test whether it could provide credentials |
There was a problem hiding this comment.
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 |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
A credential consumer may provide might provide consumer id information | |
A credential consumer may provide consumer id information |
There was a problem hiding this comment.
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 |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
function directly providing a credentials interface for the | |
function, which directly provides a credentials interface for the |
There was a problem hiding this comment.
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. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
the returned interface then offers access to the credential properties. | |
The returned interface then offers access to the credential properties |
There was a problem hiding this comment.
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 |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The following code snipped show the code for the `context` variant | |
The following code snipped shows the code for the `context` variant |
There was a problem hiding this comment.
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. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The rest of the example is then the same. | |
The rest of the example is the same. |
There was a problem hiding this comment.
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, |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This resource access points effectively to the same OCI registry, | |
This resource access effectively points to the same OCI registry, |
There was a problem hiding this comment.
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 |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
OCM credential management judt by providing | |
OCM credential management just by providing |
There was a problem hiding this comment.
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 |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
One such case is the docker config json, a config | |
One such case is the Docker config json, a config |
There was a problem hiding this comment.
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 |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
or type-specific ones, like the docker config json | |
or type-specific ones, like the Docker config json |
There was a problem hiding this comment.
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. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
used to configure credentials for the docker client. | |
used to configure credentials for the Docker client. |
There was a problem hiding this comment.
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 |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Therefore, such repository implementations are able to provide credential | |
Therefore, such repository implementations are also able to provide credential |
There was a problem hiding this comment.
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 |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
mappings for consumer ids, also. This is supported by the credential repository | |
mappings for consumer ids. This is supported by the credential repository |
There was a problem hiding this comment.
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 |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
now we can just add the repository for this specification to | |
Now we can just add the repository for this specification to |
There was a problem hiding this comment.
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 |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The actual version of the example just works with the filesystem | |
The actual version of the example just works with the file system |
There was a problem hiding this comment.
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 |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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 |
There was a problem hiding this comment.
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 |
There was a problem hiding this comment.
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" ?
There was a problem hiding this comment.
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 |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
where possible. For a CTF Archive as target, there are no | |
where possible. For a CTF archive as target, there are no |
There was a problem hiding this comment.
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 |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
configured handlers, by default. Therefore, all resources will | |
configured handlers by default. Therefore, all resources will |
There was a problem hiding this comment.
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 |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The actual version of the example just works with the filesystem | |
The actual version of the example just works with the file system |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
done
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, |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The simplest form....
Description
The tour examples in
examples/lib/tour
to illustrate the library usage scenarios have been extended andthe 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)
Related Tickets & Documents
Screenshots
Added tests?
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?
Checklist: