From 9c461bdff94116afe165e4f36881867d0b3b364d Mon Sep 17 00:00:00 2001 From: Gerald Morrison <67469729+morri-son@users.noreply.github.com> Date: Tue, 12 Mar 2024 11:47:32 +0100 Subject: [PATCH] Correct link (#195) ## Description correct links --- .../docs/guides/getting-started-with-ocm.md | 81 ++++++++++++++++--- 1 file changed, 70 insertions(+), 11 deletions(-) diff --git a/content/en/docs/guides/getting-started-with-ocm.md b/content/en/docs/guides/getting-started-with-ocm.md index 50508b87..408d1b23 100644 --- a/content/en/docs/guides/getting-started-with-ocm.md +++ b/content/en/docs/guides/getting-started-with-ocm.md @@ -46,6 +46,7 @@ This chapter walks you through some basic steps to get started with OCM concepts To follow the steps described in this section, you will need: - The OCM Command Line Interface (CLI) to interact with component versions and registries. Download it from the [releases](https://github.com/open-component-model/ocm/releases) or with the following command: + ```shell #generic: use a bash installer curl -s https://ocm.software/install.sh | sudo bash @@ -53,10 +54,11 @@ To follow the steps described in this section, you will need: #macos: use homebrew brew install open-component-model/tap/ocm ``` + - Access to an OCM repository. This can be any OCI registry for which you have write permission (e.g. GitHub Packages). An OCM repository based on an OCI registry is identified by a leading OCI repository prefix. For example: `ghcr.io//ocm`. - Credentials for the CLI to access the OCM repository. The easiest way to do this is to reuse the Docker configuration. - To do this, create a file named `.ocmconfig` in your home directory with the following: + To do this, create a file named `.ocmconfig` in your home directory with the following content: ```yaml type: generic.config.ocm.software/v1 @@ -77,6 +79,7 @@ To follow the steps described in this section, you will need: The first step when creating a new component version is to create a component archive. A component archive contains references, resources and sources. The `ocm` CLI tool can help with this. For convenience, we define the following environment variables: + ```bash PROVIDER="acme.org" ORG="acme" @@ -96,7 +99,7 @@ Let's asssume that we create a component based on a GitHub source repository. ### Create a component archive -First we create an empty component archive using the command `ocm create componentarchive`: +First we create an empty component archive using the command [`ocm create componentarchive`](https://github.com/open-component-model/ocm/blob/main/docs/reference/ocm_create_componentarchive.md) ```shell ocm create componentarchive ${COMPONENT} ${VERSION} --provider ${PROVIDER} --file $CA_ARCHIVE @@ -105,6 +108,7 @@ ocm create componentarchive ${COMPONENT} ${VERSION} --provider ${PROVIDER} --fi
What happened? This command creates the following file structure: + ```bash $ tree ca-hello-world ca-hello-world @@ -141,6 +145,7 @@ The next step is `ocm transfer componentarchive`: ```shell OCMREPO=ghcr.io/acme ocm transfer componentarchive ./ca-hello-world ${OCMREPO} ``` + ```shell transferring version "github.com/acme/helloworld:1.0.0"... ...resource 0(github.com/acme/helloworld/echoserver:0.1.0)... ...adding component version... ``` - ### Bundle composed components If you have created multiple components according to the instructions above, you can bundle @@ -402,12 +417,14 @@ for transport operations. CTF_ARCHIVE=ctf-hello-world ocm transfer componentversion ${CA_ARCHIVE} ${CTF_ARCHIVE} ``` + ```shell transferring version "github.com/acme/helloworld:1.0.0"... ...resource 0(github.com/acme/helloworld/echoserver:0.1.0)... ...adding component version... 1 versions transferred ``` +
What happened? The resulting transport archive has the following file structure: @@ -415,6 +432,7 @@ The resulting transport archive has the following file structure: ```shell tree ${CTF_ARCHIVE} ``` + ```shell ctf-hello-world ├── artifact-index.json @@ -431,6 +449,7 @@ contains the list of component version artifacts to be transported. ```shell jq . ${CTF_ARCHIVE}/artifact-index.json ``` + ```shell { "schemaVersion": 1, @@ -451,6 +470,7 @@ The component version is described as an OCI manifest: ```shell jq . ${CTF_ARCHIVE}/blobs/sha256.63dc40246a604ef503f0361e14216ab7e002912697d09da49f50bba7091549f7 ``` + ```shell { "schemaVersion": 2, @@ -480,6 +500,7 @@ Notice that the output of the component version above contains the component des ```shell tar xvf ctf-hello-world/blobs/sha256.4f2080d8d41d2b52182f325f4f42d91e2581e3f2299f4f8631196801773ba869 -O - component-descriptor.yaml ``` + ```shell component: componentReferences: [] @@ -514,10 +535,12 @@ The other elements listed as `layers` describe the blobs for the local resources
### All in One + The previous steps can be combined into a single operation working on a single description file: -* Creating a Common Transport Archive -* Adding one or more components -* With resources, sources and references + +- Creating a Common Transport Archive +- Adding one or more components +- With resources, sources and references The command [ocm add componentversions](https://github.com/open-component-model/ocm/blob/main/docs/reference/ocm_add_componentversions.md) directly creates or extends a common transport archive without the need for creating dedicated component archives @@ -576,6 +599,7 @@ ctf-hello-world ├── sha256.d275a99002962136691f3982b7e176a2812a22193809aa2c879e29cac6851919 └── sha256.ee6d6431f54c511015a59203213c998ba0654730a3f3279b56d1b29e9b51b068 ``` +
## Display and Examine component versions @@ -587,6 +611,7 @@ To show the component stored in a component archive (without looking at the file ```shell ocm get componentversion ${CA_ARCHIVE} ``` + ```shell COMPONENT VERSION PROVIDER github.com/acme/helloworld 1.0.0 acme.org @@ -597,6 +622,7 @@ To see the component descriptor of the displayed component version, use the outp ```shell ocm get componentversion ${CA_ARCHIVE} -o yaml ``` + ```shell --- context: [] @@ -619,6 +645,7 @@ Display the component versions of any OCM repository with this command: ```shell ocm get cv ghcr.io/mandelsoft/cnudie//github.com/mandelsoft/ocmhelmdemo ``` + ```shell COMPONENT VERSION PROVIDER github.com/mandelsoft/ocmhelmdemo 0.1.0-dev mandelsoft @@ -635,6 +662,7 @@ With the option `--recursive`, it is possible to show the complete component ver ```shell ocm get cv ghcr.io/mandelsoft/cnudie//github.com/mandelsoft/ocmhelmdemo --recursive ``` + ```shell REFERENCEPATH COMPONENT VERSION PROVIDER IDENTITY github.com/mandelsoft/ocmhelmdemo 0.1.0-dev mandelsoft @@ -646,6 +674,7 @@ To get a tree view, add the option `-o tree`: ```shell ocm get componentversion ghcr.io/mandelsoft/cnudie//github.com/mandelsoft/ocmhelmdemo --recursive -o tree ``` + ```shell NESTING COMPONENT VERSION PROVIDER IDENTITY └─ ⊗ github.com/mandelsoft/ocmhelmdemo 0.1.0-dev mandelsoft @@ -659,6 +688,7 @@ To list the resources found in a component version tree, the command + #### Download with download handlers @@ -736,6 +769,7 @@ into a more suitable format: ```shell ocm download resource -d ghcr.io/jensh007//github.com/acme/helloworld:1.0.0 chart -O helmchart.tgz ``` + ```shell helmchart.tgz: 4747 byte(s) written ``` @@ -746,6 +780,7 @@ The downloaded archive is now a regular Helm Chart archive: ```shell tar tvf echoserver-0.1.0.tgz ``` + ```shell -rw-r--r-- 0 0 0 136 Nov 30 13:19 echoserver/Chart.yaml -rw-r--r-- 0 0 0 1842 Nov 30 13:19 echoserver/values.yaml @@ -759,8 +794,8 @@ tar tvf echoserver-0.1.0.tgz -rw-r--r-- 0 0 0 385 Nov 30 13:19 echoserver/templates/tests/test-connection.yaml -rw-r--r-- 0 0 0 349 Nov 30 13:19 echoserver/.helmignore ``` - + #### Download an image @@ -769,6 +804,7 @@ For example, for OCI images, the OCI format is more suitable: ```shell ocm download resource ghcr.io/jensh007//github.com/acme/helloworld:1.0.0 image -O echoserver.tgz ``` + ```shell echoserver.tgz: 46148828 byte(s) written ``` @@ -779,6 +815,7 @@ The file `echoserver.tgz` was downloaded. ```shell tar xvf echoserver.tgz ``` + ```shell x index.json x oci-layout @@ -796,6 +833,7 @@ x blobs/sha256.cb5c1bddd1b5665e1867a7fa1b5fa843a47ee433bbb75d4293888b71def53229 x blobs/sha256.d5157969118932d522396fe278eb722551751c7aa7473e6d3f03e821a74ee8ec x blobs/sha256.e0962580d8254d0b1ef35006d7e2319eb4870e63dc1f9573d2406c7c47d442d2 ``` + ```shell jq . index.json @@ -820,17 +858,21 @@ jq . index.json } } ``` + #### Download an executable + The Open Component Model allows to publish platform-specific executables. In this case, the platform specification is used by convention as extra identity for the artifacts that are contained in the component version. Example: + ```shell ocm get componentversion ghcr.io/open-component-model/ocm//ocm.software/ocmcli:0.1.0-dev -o yaml ``` + ```shell ... resources: @@ -858,6 +900,7 @@ ocm get componentversion ghcr.io/open-component-model/ocm//ocm.software/ocmcli:0 type: localBlob ... ``` + Note, the resources shown above have the same name and type `executable` but a different extra-identity. If a component version complies to this convention, executables can directly be downloaded for the specified platform with the use of the `-x` option. If only one executable is contained in the component version, the @@ -866,6 +909,7 @@ resource name can be omitted. Example: ```shell ocm download resource -x --latest ghcr.io/open-component-model/ocm//ocm.software/ocmcli ``` + ```shell ocm: 52613730 byte(s) written ``` @@ -875,13 +919,16 @@ ocm: 52613730 byte(s) written ```shell ls -l ``` + ```shell total 51M -rwxr-xr-x 1 me staff 51M Nov 30 13:49 ocm ``` + ```shell file ocm ``` + ```shell ocm: Mach-O 64-bit executable arm64 ``` @@ -903,6 +950,7 @@ Download entire component versions using the ### Signing with certificates @@ -1137,9 +1196,8 @@ ocm sign componentversion --signature acme-sig --private-key=acme.priv --issuer Now the issuer will be stored along the signature and will be checked when verifying with the certificate instead of the public key. - - ### Signature Verification + You can verify a signed component version. Therefore a public or a certificate provided by the signer is required. If a certificate is provided it is validated according its certificate chain. If not an official CA is used you need the certificate of the used root CA. @@ -1149,6 +1207,7 @@ To verify the signature of a component version use ```shell ocm verify componentversions --signature acme-sig --public-key=acme.pub ctf-hello-world ``` + ```shell applying to version "github.com/acme/helloworld:1.0.0"... successfully verified github.com/acme/helloworld:1.0.0 (digest sha256:46615253117b7217903302d172a45de7a92f2966f6a41efdcc948023ada318bc)