diff --git a/content/docs/concepts/_index.md b/content/docs/concepts/_index.md index 2473a270b..99114261b 100644 --- a/content/docs/concepts/_index.md +++ b/content/docs/concepts/_index.md @@ -1,6 +1,6 @@ --- title: "Concepts" -description: "Explore basic concepts and principles of the Open Component Model" +description: "Explore basic concepts and principles of the Open Component Model." icon: "📚" weight: 30 url: /docs/concepts/ diff --git a/content/docs/getting-started/create-component-version.md b/content/docs/getting-started/create-component-version.md index 519109010..85e06fcb5 100644 --- a/content/docs/getting-started/create-component-version.md +++ b/content/docs/getting-started/create-component-version.md @@ -7,20 +7,25 @@ weight: 23 toc: true --- -## Creating and Storing Component Versions +## How It Works -Component Versions are created using a `component-constructor.yaml` file, which is a description file that contains one or multiple components. The file describes the components and their artifacts - resources and sources, metadata in form of labels and references to other components. +Component versions are created using a `component-constructor.yaml` file, which is a description file that contains one or multiple components. The file describes the components and their artifacts - resources and sources, metadata in form of labels and references to other components. -Component Versions are locally stored in archives using the [Common Transfer Format (CTF)](https://github.com/open-component-model/ocm-spec/blob/main/doc/04-extensions/03-storage-backends/ctf.md). A CTF archive may contain any number of component versions and is used to transfer components to and between component repositories. +Component versions are locally stored in archives using the [Common Transfer Format (CTF)](https://github.com/open-component-model/ocm-spec/blob/main/doc/04-extensions/03-storage-backends/ctf.md). A CTF archive may contain any number of component versions and is used to transfer components to and between component repositories. Note that a CTF archive itself is also an OCM repository, so it can be used as source or target for component transfer operations using the OCM CLI. The command [`ocm add componentversions`](https://github.com/open-component-model/ocm/blob/main/docs/reference/ocm_add_componentversions.md) directly creates a component version from a `component-constructor.yaml` file and stores it in a local CTF archive. -### Create a Component Version +## Prerequisites -In this example we will use the The `ocm` CLI tool to create a very basic component version that contains a local resource and a resource that is accessed from a remote location. The local resource is the `podinfo` Helm Chart and the referenced resource is a Docker image stored in an OCI registry. +- [Install and configure the OCM CLI]({{< relref "ocm-cli-installation.md" >}}). +- Install [jq](https://jqlang.org/). + +## Create a Component Version + +In this example, we will use the the `ocm` CLI tool to create a very basic component version that contains two resources: a local resource and a resource that is accessed from a remote location. The local resource is the `podinfo` Helm Chart and the referenced resource is a Docker image stored in an OCI registry. We start by creating a test folder where we execute all required steps for this example and navigating into it: @@ -76,14 +81,14 @@ The type field is used to specify the kind of access. If the resource content is taken from local resources, the field `input` is used to specify the access to the local resources. Similarly to the `access` attribute, the kind of the input source is described by the field `type`. -Available access and input types are described [here]({{< relref "docs/tutorials/input-and-access-types" >}}). +For the available access and input types, refer to [Input and Access Types]({{< relref "docs/tutorials/input-and-access-types" >}}). -For more complex scenarios, the description files might use variable substitution (templating), see [Best Practices]({{< relref "docs/tutorials/best-practices#templating-the-resources" >}}). +For more complex scenarios, the description files might use variable substitution (templating), refer to [Best Practices]({{< relref "docs/tutorials/best-practices#templating-the-resources" >}}). -### Add Component Version to CTF archive +## Store Component Versions -To store our component version locally and to make it transportable, we now add it to a CTF archive -using the following command. The option `--create` is used to create a new CTF archive if it does not exist: +To store the component version locally and to make it transportable, we add it to a CTF archive +using the command [`ocm add componentversions`](https://github.com/open-component-model/ocm/blob/main/docs/reference/ocm_add_componentversions.md). The option `--create` is used to create a new CTF archive if it does not exist: ```shell ocm add componentversions --create --file ctf-hello-world component-constructor.yaml @@ -134,7 +139,7 @@ jq . ${CTF_ARCHIVE}/artifact-index.json } ``` -The content of the transport archive is stored as OCI artifacts. Notice that the repository names of Component Version artifacts (found at `artifacts.respository`) are prefixed by `component-descriptors/`. +The content of the transport archive is stored as OCI artifacts. Notice that the repository names of component version artifacts (found at `artifacts.respository`) are prefixed by `component-descriptors/`. The component version is described as an OCI manifest: @@ -208,3 +213,103 @@ component: The other elements listed as `layers` describe the blobs for the local resources stored along with the component version. The digests can be seen in the `localReference` attributes of the component descriptor. + +## View Component Versions + +To show a component stored in an OCM repository or CTF archive (which itself is an OCM repository), use the [`ocm get componentversion`](https://github.com/open-component-model/ocm/blob/main/docs/reference/ocm_get_componentversions.md) command: + +```shell +ocm get componentversion ghcr.io/open-component-model/ocm//ocm.software/toi/demo/helmdemo:0.12.0 +``` + +```shell + COMPONENT VERSION PROVIDER + ocm.software/toi/demo/helmdemo 0.12.0 ocm.software +``` + +To see the component descriptor of the displayed component version, use the output format option `-o yaml`: + +```shell +ocm get cv ghcr.io/open-component-model/ocm//ocm.software/toi/demo/helmdemo:0.12.0 -o yaml +``` + +```yaml +component: + componentReferences: + - componentName: ocm.software/toi/installers/helminstaller + name: installer + version: 0.12.0 + creationTime: "2024-07-19T14:32:13Z" + name: ocm.software/toi/demo/helmdemo + provider: ocm.software + repositoryContexts: + - baseUrl: ghcr.io + componentNameMapping: urlPath + subPath: open-component-model/ocm + type: OCIRegistry + resources: + - access: + localReference: sha256:8a2fe6af4ce56249094622c9d618e24b4cfb461a7dfa6a42cce31749189bc499 + mediaType: application/vnd.toi.ocm.software.package.v1+yaml + type: localBlob + digest: + ... + labels: + - name: commit + value: e5ca3001323b75ee5793a786089f1f410e9e8db3 + name: package + relation: local + type: toiPackage + version: 0.12.0 + - access: + imageReference: ghcr.io/open-component-model/ocm/ocm.software/toi/demo/helmdemo/echoserver:0.1.0 + type: ociArtifact + digest: + ... + name: chart + relation: local + type: helmChart + version: 0.12.0 +... +``` + +To refer to the content of a component repository, the component name can be appended to the repository specification separated by `//` (you can also use the `--repo` option to specify the repository). + +In the example above, `ghcr.io/open-component-model/ocm` is the OCM repository, whereas `ocm.software/toi/demo/helmdemo` is the component stored in this component repository. + +Optionally, a specific version can be appended, separated by a colon (`:`). If no version is specified, all component versions will be displayed. + +With the option `--recursive`, it is possible to show the complete component version, including the component versions it references. + +```shell +ocm get cv ghcr.io/open-component-model/ocm//ocm.software/toi/demo/helmdemo:0.12.0 --recursive +``` + +```shell + REFERENCEPATH COMPONENT VERSION PROVIDER IDENTITY + ocm.software/toi/demo/helmdemo 0.12.0 ocm.software + ocm.software/toi/demo/helmdemo:0.12.0 ocm.software/toi/installers/helminstaller 0.12.0 ocm.software "name"="installer" +``` + +To get a tree view, add the option `-o tree`: + +```shell +ocm get cv ghcr.io/open-component-model/ocm//ocm.software/toi/demo/helmdemo:0.12.0 --recursive -o tree +``` + +```shell + NESTING COMPONENT VERSION PROVIDER IDENTITY + └─ ⊗ ocm.software/toi/demo/helmdemo 0.12.0 ocm.software + └─ ocm.software/toi/installers/helminstaller 0.12.0 ocm.software "name"="installer" +``` + +As mentioned before a CTF archive itself is an OCM repository, so we can execute the same commands on a CTF archive. So, let's get the information about the component `github.com/acme.org/helloworld` we created in the previous step and that we stored in the CTF archive `/tmp/helloworld/ctf-hello-world`: + +```shell +ocm get cv /tmp/helloworld/ctf-hello-world//github.com/acme.org/helloworld:1.0.0 +``` + +```shell + COMPONENT VERSION PROVIDER + github.com/acme.org/helloworld 0.1.0 ocm.software +``` diff --git a/content/docs/getting-started/deploy-helm-chart.md b/content/docs/getting-started/deploy-helm-chart.md index b4b9710db..bd0a7c604 100644 --- a/content/docs/getting-started/deploy-helm-chart.md +++ b/content/docs/getting-started/deploy-helm-chart.md @@ -1,6 +1,6 @@ --- title: Deploy a Helm Chart -description: "Deploy a Helm Chart from an OCM component version using ocm-controller.md" +description: "Deploy a Helm chart from an OCM component version using the OCM controllers." icon: "🚀" weight: 28 toc: true @@ -11,7 +11,7 @@ The [OCM controllers](https://github.com/open-component-model/open-component-mod in early development and not yet ready for production use. {{}} -This guide demonstrates how to deploy a Helm Chart from an OCM component version using OCM controllers, kro, and FluxCD. +This guide demonstrates how to deploy a Helm chart from an OCM component version using OCM controllers, kro, and FluxCD. It is a rather basic example, in which it is assumed that a developer created an application, packaged it as a Helm chart, and publishes it as OCM component version in an OCI registry. Then, an operator who wants to deploy the application via Helm chart in a Kubernetes cluster, creates a `ResourceGraphDefinition` with resources that point to @@ -19,9 +19,10 @@ this OCM component version. Using CEL expressions inside the `ResourceGraphDefin resource location will be passed to FluxCD, which will then configure the Helm chart and deploy it into the Kubernetes cluster. -{{}} -Before starting, make sure you have set up your environment as described in the [setup guide]({{< relref "setup-controller.md" >}}). -{{}} +## Prerequisites + +- [Install the OCM CLI]({{< relref "docs/getting-started/ocm-cli-installation.md" >}}). +- [Set up an OCM controller environment]({{< relref "docs/getting-started/setup-controller.md" >}}). ## Create the OCM Component Version @@ -171,7 +172,7 @@ spec: tag: ${resourceChart.status.reference.tag} # secretRef is required, if the OCI repository requires credentials to access it. # secretRef: - # HelmRelease refers to the OCIRepository, lets you configure the helm chart and deploys the Helm Chart into the + # HelmRelease refers to the OCIRepository, lets you configure the Helm chart and deploys the Helm chart into the # Kubernetes cluster. - id: helmrelease template: @@ -228,7 +229,7 @@ simple v1alpha1 Simple Active 19s This creates a Kubernetes Custom Resource Definition (CRD) `Simple` that can be used to create instances. An applied instance of the CRD will create all resources defined in the `ResourceGraphDefinition`. -### Create an Instance of "Simple" +### Create an Instance of Simple To create an instance of the `Simple` CRD, create a file named `instance.yaml` and add the following content: diff --git a/content/docs/getting-started/display-examine-component-versions.md b/content/docs/getting-started/download-resources-from-component-versions.md similarity index 73% rename from content/docs/getting-started/display-examine-component-versions.md rename to content/docs/getting-started/download-resources-from-component-versions.md index b9544c2dc..3b6f9ce01 100644 --- a/content/docs/getting-started/display-examine-component-versions.md +++ b/content/docs/getting-started/download-resources-from-component-versions.md @@ -1,114 +1,21 @@ --- -title: "Display and Examine Component Versions" -description: "Learn how to display and examine component versions in OCM." -icon: "👁️" +title: "Download Resources from Component Versions" +description: "Learn how to download resources from component versions in OCM." +icon: "📥 " weight: 24 toc: true --- -## List Component Versions +This guide shows how to view and download the resources of a component version. You will also learn how to download a complete component version as well as OCI artifacts. -To show a component stored in an OCM repository or CTF archive (which itself is an OCM repository), the [`ocm get componentversion`](https://github.com/open-component-model/ocm/blob/main/docs/reference/ocm_get_componentversions.md) command can be used: +## Prerequisites -```shell -ocm get componentversion ghcr.io/open-component-model/ocm//ocm.software/toi/demo/helmdemo:0.12.0 -``` - -```shell - COMPONENT VERSION PROVIDER - ocm.software/toi/demo/helmdemo 0.12.0 ocm.software -``` - -To see the component descriptor of the displayed component version, use the output format option `-o yaml`: - -```shell -ocm get cv ghcr.io/open-component-model/ocm//ocm.software/toi/demo/helmdemo:0.12.0 -o yaml -``` - -```yaml -component: - componentReferences: - - componentName: ocm.software/toi/installers/helminstaller - name: installer - version: 0.12.0 - creationTime: "2024-07-19T14:32:13Z" - name: ocm.software/toi/demo/helmdemo - provider: ocm.software - repositoryContexts: - - baseUrl: ghcr.io - componentNameMapping: urlPath - subPath: open-component-model/ocm - type: OCIRegistry - resources: - - access: - localReference: sha256:8a2fe6af4ce56249094622c9d618e24b4cfb461a7dfa6a42cce31749189bc499 - mediaType: application/vnd.toi.ocm.software.package.v1+yaml - type: localBlob - digest: - ... - labels: - - name: commit - value: e5ca3001323b75ee5793a786089f1f410e9e8db3 - name: package - relation: local - type: toiPackage - version: 0.12.0 - - access: - imageReference: ghcr.io/open-component-model/ocm/ocm.software/toi/demo/helmdemo/echoserver:0.1.0 - type: ociArtifact - digest: - ... - name: chart - relation: local - type: helmChart - version: 0.12.0 -... -``` - -To refer to the content of a component repository, the component name can be appended to the repository specification separated by `//` (you can also use the `--repo` option to specify the repository). - -In the example above, `ghcr.io/open-component-model/ocm` is the OCM repository, whereas `ocm.software/toi/demo/helmdemo` is the component stored in this component repository. - -Optionally, a specific version can be appended, separated by a colon (`:`). If no version is specified, all component versions will be displayed. - -With the option `--recursive`, it is possible to show the complete component version, including the component versions it references. - -```shell -ocm get cv ghcr.io/open-component-model/ocm//ocm.software/toi/demo/helmdemo:0.12.0 --recursive -``` - -```shell - REFERENCEPATH COMPONENT VERSION PROVIDER IDENTITY - ocm.software/toi/demo/helmdemo 0.12.0 ocm.software - ocm.software/toi/demo/helmdemo:0.12.0 ocm.software/toi/installers/helminstaller 0.12.0 ocm.software "name"="installer" -``` - -To get a tree view, add the option `-o tree`: - -```shell -ocm get cv ghcr.io/open-component-model/ocm//ocm.software/toi/demo/helmdemo:0.12.0 --recursive -o tree -``` - -```shell - NESTING COMPONENT VERSION PROVIDER IDENTITY - └─ ⊗ ocm.software/toi/demo/helmdemo 0.12.0 ocm.software - └─ ocm.software/toi/installers/helminstaller 0.12.0 ocm.software "name"="installer" -``` - -As mentioned before a CTF archive itself is an OCM repository, so we can execute the same commands on a CTF archive. So, let's get the information about the component `github.com/acme.org/helloworld` we created in the previous step and that we stored in the CTF archive `/tmp/helloworld/ctf-hello-world`: - -```shell -ocm get cv /tmp/helloworld/ctf-hello-world//github.com/acme.org/helloworld:1.0.0 -``` - -```shell - COMPONENT VERSION PROVIDER - github.com/acme.org/helloworld 0.1.0 ocm.software -``` +- [Install and configure the OCM CLI]({{< relref "ocm-cli-installation.md" >}}). +- Install [jq](https://jqlang.org/). ## List the Resources of a Component Version -To list the resources found in a component version tree, the command [`ocm get resources`](https://github.com/open-component-model/ocm/blob/main/docs/reference/ocm_get_resources.md) can be used: +To list the resources found in a component version tree, use the command [`ocm get resources`](https://github.com/open-component-model/ocm/blob/main/docs/reference/ocm_get_resources.md): ```shell ocm get resources ghcr.io/open-component-model/ocm//ocm.software/toi/demo/helmdemo:0.12.0 --recursive -o tree @@ -363,7 +270,7 @@ files. Additionally, it filters all matching resources for executables and the c -### Download a Full Component Version +## Download a Full Component Version Download entire component versions using the [`ocm download componentversion`](https://github.com/open-component-model/ocm/blob/main/docs/reference/ocm_download_componentversions.md) command: diff --git a/content/docs/getting-started/ocm-cli-installation.md b/content/docs/getting-started/ocm-cli-installation.md index 02a9ea114..956a91bc8 100644 --- a/content/docs/getting-started/ocm-cli-installation.md +++ b/content/docs/getting-started/ocm-cli-installation.md @@ -7,18 +7,13 @@ weight: 22 toc: true --- -## Overview +This guide walks you through installing the OCM CLI and configuring the necessary credentials. -You can install the latest release of the OCM CLI from any of the following sources (more details below): +## Install the OCM CLI -- [Homebrew](https://brew.sh) -- [Nix](https://nixos.org) -- [AUR](https://aur.archlinux.org/packages/ocm-cli) -- [Docker](https://www.docker.com/) -- [Podman](https://podman.io/) -- [GitHub Releases](https://github.com/open-component-model/ocm/releases) +You can install the latest release of the OCM CLI from any of the following sources. -## Bash +### Bash To install with `bash` for macOS or Linux, execute the following command: @@ -26,55 +21,56 @@ To install with `bash` for macOS or Linux, execute the following command: curl -s https://ocm.software/install.sh | sudo bash ``` -## Install using Homebrew +### Using Homebrew ```sh # Homebrew (macOS and Linux) brew install open-component-model/tap/ocm ``` -## Install using Nix (with Flakes) +For more information, refer to the [OCM CLI package on Homebrew](https://formulae.brew.sh/formula/ocm#default) and the [Homebrew documentation](https://brew.sh). + +### Using Nix (with Flakes) ```sh # Nix (macOS, Linux, and Windows) -# ad hoc cmd execution +# Ad hoc cmd execution nix run github:open-component-model/ocm -- --help nix run github:open-component-model/ocm#helminstaller -- --help -# install development version +# Install development version nix profile install github:open-component-model/ocm -# or release +# Or release nix profile install github:open-component-model/ocm/ -#check installation +# Check installation nix profile list | grep ocm -# optionally, open a new shell and verify that cmd completion works +# Optionally, open a new shell and verify that cmd completion works ocm --help ``` -see: [Flakes](https://nixos.wiki/wiki/Flakes) - -## Install from AUR (Arch Linux User Repository) +For more information, refer to the Nix documentation: [Nix flakes](https://nixos.wiki/wiki/Flakes). -[package-url](https://aur.archlinux.org/packages/ocm-cli) +### From AUR (Arch Linux User Repository) ```shell -# if not using a helper util +# If not using a helper util git clone https://aur.archlinux.org/ocm-cli.git cd ocm-cli makepkg -i ``` +For more information, refer to the [OCM CLI package on AUR](https://aur.archlinux.org/packages/ocm-cli) and the [AUR Documentation](https://wiki.archlinux.org/title/Arch_User_Repository). -[AUR Documentation](https://wiki.archlinux.org/title/Arch_User_Repository) - -## Install using Docker / Podman +### Using Docker / Podman ```sh podman run -t ghcr.io/open-component-model/ocm:latest --help ``` -### Build and Run It Yourself +For more information, refer to the [Podman documentation](https://podman.io/). + +#### Build and Run It Yourself ```sh podman build -t ocm . @@ -99,30 +95,32 @@ Please check [hub.docker.com](https://hub.docker.com/_/golang/tags?page=1&name=a podman build -t ocm --build-arg GO_VERSION=1.22 --build-arg ALPINE_VERSION=3.19 --build-arg GO_PROXY=https://proxy.golang.org . ``` -## on MS Windows +### On MS Windows -### using Chocolatey +#### Using Chocolatey ```powershell choco install ocm-cli ``` -see: [chocolatey community package: ocm-cli](https://community.chocolatey.org/packages/ocm-cli) +For more information, refer to the [OCM CLI package on Chocolatey](https://community.chocolatey.org/packages/ocm-cli) and the [Chocolatey documentation](https://chocolatey.org/). -### using winget +#### Using winget _Deprecated_: Please note, winget packages are no longer provided. Any existing packages are still working, but no new packages are built and published to winget repository. -## Building from Source +### Build It From Source -### Prerequisites +#### Prerequisites -- [git](https://www.git-scm.com/) -- [golang](https://go.dev/) +You need the following tools installed: + +- [Git](https://www.git-scm.com/) +- [Golang](https://go.dev/) - make -### Installation Process +#### Installation Process Clone the `open-component-model/ocm` repo: @@ -143,3 +141,54 @@ Verify the installation: ```bash ocm version ``` + +## Configure the OCM Command Line Client + +Credentials to be used by the OCM CLI can be configured by supplying it with a [configuration file]({{< relref "docs/tutorials/creds-in-ocmconfig" >}}). By default, the CLI looks for the file in `$HOME/.ocmconfig`. + +### Prerequisites + +- Obtain 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`. + +### Using the Docker Configuration File + +The easiest way to do this is to reuse your Docker configuration `json` file. + +Create a file named `.ocmconfig` in your home directory with the following content: + +```yaml +type: generic.config.ocm.software/v1 +configurations: +- type: credentials.config.ocm.software + repositories: + - repository: + type: DockerConfig/v1 + # The path to the Docker configuration file + dockerConfigFile: "~/.docker/config.json" + propagateConsumerIdentity: true +- type: attributes.config.ocm.software + attributes: + cache: ~/.ocm/cache +``` + +### Using Basic Authentication + +Alternatively, you can use basic authentication. Create a file named `.ocmconfig` in your home directory with the following content: + +```yaml +type: generic.config.ocm.software/v1 +configurations: + - type: credentials.config.ocm.software + consumers: + - identity: + type: ociRegistry + hostname: / # e.g. ghcr.io/acme/acme + credentials: + - type: Credentials + properties: + username: + password: +``` + +More information on the credentials topic can be found by running the OCM CLI help topic command `ocm credential-handling` +and in the guide [Credentials in an .ocmconfig File]({{< relref "docs/tutorials/creds-in-ocmconfig" >}}), which contains many examples for different repository types. diff --git a/content/docs/getting-started/prerequisites.md b/content/docs/getting-started/prerequisites.md deleted file mode 100644 index 3febda841..000000000 --- a/content/docs/getting-started/prerequisites.md +++ /dev/null @@ -1,66 +0,0 @@ ---- -title: "Prerequisites" -url: /docs/getting-started/prerequisites/ -description: "What you need to get started with OCM" -icon: "⚠️" -weight: 21 -toc: true ---- - -This and the following chapters walk you through some basic steps to get started with OCM concepts and the OCM CLI. -You will learn how to create a component version, display and examine the component, and how to transport and sign it. - -To follow the steps described in this section, you will need to: - -## Install the OCM Command Line Interface (CLI) - -The CLI is used to interact with component versions and registries. Install it like described in [Installing the OCM CLI]({{< relref "docs/getting-started/ocm-cli-installation" >}}). - -## Obtain 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`. - -## Obtain Credentials for the CLI to Access the OCM Repository - -### Using the Docker Configuration File - -The easiest way to do this is to reuse your Docker configuration `json` file. - -To do this, create a file named `.ocmconfig` in your home directory with the following content: - -```yaml -type: generic.config.ocm.software/v1 -configurations: -- type: credentials.config.ocm.software - repositories: - - repository: - type: DockerConfig/v1 - # The path to the Docker configuration file - dockerConfigFile: "~/.docker/config.json" - propagateConsumerIdentity: true -- type: attributes.config.ocm.software - attributes: - cache: ~/.ocm/cache -``` - -### Using Basic Authentication - -Alternatively, you can use basic authentication. Create a file named `.ocmconfig` in your home directory with the following content: - -```yaml -type: generic.config.ocm.software/v1 -configurations: - - type: credentials.config.ocm.software - consumers: - - identity: - type: ociRegistry - hostname: / # e.g. ghcr.io/acme/acme - credentials: - - type: Credentials - properties: - username: - password: -``` - -More information on the credentials topic can be seen by running the OCM CLI help topic command `ocm credential-handling` -and [in this guide]({{< relref "docs/tutorials/creds-in-ocmconfig" >}}) with many examples for different repository types. diff --git a/content/docs/getting-started/setup-controller.md b/content/docs/getting-started/setup-controller.md index 5a477639d..a1e0d2b89 100644 --- a/content/docs/getting-started/setup-controller.md +++ b/content/docs/getting-started/setup-controller.md @@ -1,5 +1,5 @@ --- -title: Set Up OCM Controller Environment +title: Set Up an OCM Controller Environment description: "Set up a local environment for running examples from the getting-started guides" icon: "🛠️" weight: 27 @@ -12,11 +12,14 @@ The [OCM controllers](https://github.com/open-component-model/open-component-mod in early development and not yet ready for production use. {{}} -This document describes how to set up a local environment to [Deploy a Helm Chart]({{< relref "deploy-helm-chart.md" >}}) using the OCM controllers. +This document describes how to set up a local environment for running the examples from the [Deploy a Helm Chart]({{< relref "deploy-helm-chart.md" >}}) guide. You will create a local Kubernetes cluster with kind and then install kro, Flux, and the OCM controllers. ## Prerequisites -- [kubectl](https://kubernetes.io/docs/tasks/tools/#kubectl) +- Install [kubectl](https://kubernetes.io/docs/tasks/tools/#kubectl). +- Install [kind](https://kind.sigs.k8s.io/). +- Install [Git](https://git-scm.com/). +- Install [Task](https://taskfile.dev/). ## Start a Local Kubernetes Cluster with kind @@ -24,9 +27,6 @@ This document describes how to set up a local environment to [Deploy a Helm Char You don't need to run kind if you are using a remote Kubernetes cluster you have access to. If so, you can skip this. {{}} -For download and installation instructions, see the -[kind documentation](https://kind.sigs.k8s.io/docs/user/quick-start). - To create a local kind cluster run the following command: ```bash @@ -35,7 +35,7 @@ kind create cluster ## Install kro -Please follow the official installation guides for [kro](https://kro.run/docs/getting-started/Installation). You might +Please follow the [official installation guides for kro](https://kro.run/docs/getting-started/Installation). You might need [helm](https://helm.sh/docs/intro/install/) to install kro. If kro is installed correctly, you should see some similar output when running the following command: @@ -112,7 +112,7 @@ ocm-k8s-toolkit-system ocm-k8s-toolkit-controller-manager-788f58d4bd-ntbx8 1 ... ``` -## Access to a Registry +## Get Access to a Registry As all examples and guides will create an OCM component version that will be consumed by the OCM controllers, you will need access to a registry. You can either choose a public registry like [ghcr.io][ghcr.io] or deploy a registry (like diff --git a/content/docs/getting-started/sign-component-versions.md b/content/docs/getting-started/sign-component-versions.md index 94a087c9a..606a4a49d 100644 --- a/content/docs/getting-started/sign-component-versions.md +++ b/content/docs/getting-started/sign-component-versions.md @@ -16,7 +16,13 @@ component version is used for signing. See [Signing Process and Normalization](h Currently, only signing according to the [RSA PKCS #1 v1.5 signature algorithm](https://datatracker.ietf.org/doc/html/rfc3447) is supported. -To follow the examples, one must follow the instructions from the section [Create a Component Version]({{< relref "docs/getting-started/create-component-version" >}}). +## Prerequisites + +- [Install and configure the OCM CLI]({{< relref "ocm-cli-installation.md" >}}). +- Install [jq](https://jqlang.org/). +- To follow the examples, you need to create the component version from our guide [Create Component Versions]({{< relref "docs/getting-started/create-component-version" >}}). + +## Sign with a Key Pair Create a key pair using the OCM CLI: @@ -158,7 +164,7 @@ signatures: -## Signing with Certificates +## Sign with Certificates The public key from the last example cannot be validated. This can be changed by using a certificate instead of a pure public key. The certificate is signed by a CA. This ensures the authenticity of the @@ -216,7 +222,7 @@ ocm sign componentversion ${CTF_ARCHIVE} --private-key key.priv --public-key key 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 +## Verify a Signature You can verify a signed component version. Therefore, a public key or a certificate provided by the signer is required. If a certificate is provided, it is validated according to its certificate chain. diff --git a/content/docs/getting-started/transport-component-versions.md b/content/docs/getting-started/transport-component-versions.md index ba3475045..4cdf7490f 100644 --- a/content/docs/getting-started/transport-component-versions.md +++ b/content/docs/getting-started/transport-component-versions.md @@ -6,11 +6,17 @@ weight: 26 toc: true --- -The section [Add Component Version to CTF archive]({{< relref "docs/getting-started/create-component-version#add-component-version-to-ctf-archive/" >}}) explained how to store component versions in a CTF archive. +## Prerequisites -During the transfer, it is possible to include component references as local blobs. It is also possible to include references in a recursive way. +- [Install and configure the OCM CLI]({{< relref "ocm-cli-installation.md" >}}). -Here is an example of a recursive transfer from one OCI registry to another, which includes resources and references: +## Transfer a Component Version + +The section [Store Component Versions]({{< relref "docs/getting-started/create-component-version#store-component-versions" >}}) explained how to add a component version to a CTF archive. There, you used the [`ocm add componentversions`](https://github.com/open-component-model/ocm/blob/main/docs/reference/ocm_add_componentversions.md) command. + +To transfer component versions between two OCM repositories, you can use the [`ocm transfer componentversions`](https://github.com/open-component-model/ocm/blob/main/docs/reference/ocm_transfer_componentversions.md) command. + +Here is an example of a recursive transfer from one OCI registry to another. The transfer includes both resources and references: ```shell ocm transfer componentversion --recursive --copy-resources ghcr.io/open-component-model/ocm//ocm.software/toi/demo/helmdemo:0.12.0 another-registry/ diff --git a/content/docs/overview/_index.md b/content/docs/overview/_index.md index 99dc0b5c8..582036dad 100644 --- a/content/docs/overview/_index.md +++ b/content/docs/overview/_index.md @@ -1,6 +1,6 @@ --- title : "Overview" -description: "Get an overview of the Open Component Model (OCM)" +description: "Get an overview of the Open Component Model (OCM)." icon: "🌐" weight: 10 toc: true