01-getting-started

README

Basic Usage of OCM Repositories

This tour illustrates the basic usage of the API to access component versions in an OCM repository.

Running the example

You can call the main program with a config file argument (--config <file>), where the config file has the following content:

component: github.com/mandelsoft/examples/cred1
repository: ghcr.io/mandelsoft/ocm
version: 0.1.0

Walkthrough

The basic entry point for using the OCM library is always an OCM Context object. It bundles all configuration settings and type registrations, like access methods, repository types, etc, and configuration settings, like credentials, which should be used when working with the OCM ecosystem.

Therefore, the first step is always to get access to such a context object. Our example uses the default context provided by the library, which covers the complete type registration contained in the executable.

It can be accessed by a function of the api/ocm package.

	ctx := ocm.DefaultContext()

The context acts as the central entry point to get access to OCM elements. First, we get a repository, to look for component versions. We use the OCM repository hosted on ghcr.io, which is providing the standard OCM components.

For every storage technology used to store OCM components, there is a serializable descriptor object, the repository specification. It describes the information required to access the repository and can be used to store the serialized form as part of other resources, for example Kubernetes resources or configuration settings. The available repository implementations can be found under .../api/ocm/extensions/repositories.

	spec := ocireg.NewRepositorySpec("ghcr.io/open-component-model/ocm")

The context can now be used to map the descriptor into a repository object, which then provides access to the OCM elements stored in this repository.

	repo, err := ctx.RepositoryForSpec(spec)
	if err != nil {
		return errors.Wrapf(err, "cannot setup repository")
	}

To release potentially allocated temporary resources, many objects must be closed, if they are not used anymore. This is typically done by a defer statement placed after a successful object retrieval.

	defer repo.Close()

All kinds of repositories, regardless of their type feature the same interface to work with OCM content. It can be used to access stored elements. First of all, a repository hosts component versions. They are stored for components. Components are not necessarily explicit objects stored in an OCM repository. But they have features like a name and versions. Therefore, the repository abstraction provided by the library offers a component object, which can be retrieved from a repository object. A component has a name and acts as namespace for versions.

	c, err := repo.LookupComponent("ocm.software/ocmcli")
	if err != nil {
		return errors.Wrapf(err, "cannot lookup component")
	}
	defer c.Close()

Now we look for the versions of the component available in this repository.

	versions, err := c.ListVersions()
	if err != nil {
		return errors.Wrapf(err, "cannot query version names")
	}

OCM version names must follow the SemVer rules. Therefore, we can simply order the versions and print them.

	err = semverutils.SortVersions(versions)
	if err != nil {
		return errors.Wrapf(err, "cannot sort versions")
	}
	fmt.Printf("versions for component ocm.software/ocmcli: %s\n", strings.Join(versions, ", "))

Now, we have a look at the latest version. It is the last one in the list.

	// to retrieve the latest version use
	// cv, err := c.LookupVersion(versions[len(versions)-1])
	cv, err := c.LookupVersion("0.17.0")
	if err != nil {
		return errors.Wrapf(err, "cannot get latest version")
	}
	defer cv.Close()

The component version object provides access to the component descriptor

	cd := cv.GetDescriptor()
	fmt.Printf("resources of the latest version:\n")
	fmt.Printf("  version:  %s\n", cv.GetVersion())
	fmt.Printf("  provider: %s\n", cd.Provider.Name)

and the resources described by the component version.

	for i, r := range cv.GetResources() {
		fmt.Printf("  %2d: name:           %s\n", i+1, r.Meta().GetName())
		fmt.Printf("      extra identity: %s\n", r.Meta().GetExtraIdentity())
		fmt.Printf("      resource type:  %s\n", r.Meta().GetType())
		acc, err := r.Access()
		if err != nil {
			fmt.Printf("      access:         error: %s\n", err)
		} else {
			fmt.Printf("      access:         %s\n", acc.Describe(ctx))
		}
	}

This results in the following output (the shown version might differ, because the code always describes the latest version):

resources of the latest version:
  version:  0.17.0
  provider: ocm.software
   1: name:           ocmcli
      extra identity: "architecture"="amd64","os"="linux"
      resource type:  executable
      access:         Local blob sha256:03a45dcde67ba565fe806cb5db67da3387f772f7c50af711a0edd6f802570c04[]
   2: name:           ocmcli
      extra identity: "architecture"="arm64","os"="linux"
      resource type:  executable
      access:         Local blob sha256:5a622634ae43cf03eac91079389d83266891d1f9b2d8a3884cef6fe639180324[]
   3: name:           ocmcli
      extra identity: "architecture"="arm64","os"="darwin"
      resource type:  executable
      access:         Local blob sha256:1482fe5b764e3a86cf96704d7a839ad7e53dcbfd4f5fce5405abffb1962153dd[]
   4: name:           ocmcli
      extra identity: "architecture"="amd64","os"="darwin"
      resource type:  executable
      access:         Local blob sha256:805f181aff48511eea12c699ed1bbcee8bdc4c5168924e81058aff8715946875[]
   5: name:           ocmcli
      extra identity: "architecture"="amd64","os"="windows"
      resource type:  executable
      access:         Local blob sha256:20839c68bf0c4cf99444d78ebb93f53358fa9e95fe806f186220bd21d520efa7[]
   6: name:           ocmcli-image
      extra identity: 
      resource type:  ociImage
      access:         OCI artifact ghcr.io/open-component-model/ocm/ocm.software/ocmcli/ocmcli-image:0.17.0@sha256:16fb52a1cb11c867bd058f4124dea53fbab94229842cc14b52653c2e80b1cede

Resources have some metadata, like their identity and a resource type. And, most importantly, they describe how the content of the resource (as blob) can be accessed. This is done by an access specification, again a serializable descriptor, like the repository specification.

The component version used here contains the executables for the OCM CLI for various platforms. The next step is to 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 is mandatory. But there may be more identity attributes finally stored as ``extraIdentity` in the component descriptor.

A convention is to use dedicated identity properties to indicate the operating system and the architecture for executables.

	id := metav1.NewIdentity("ocmcli",
		extraid.ExecutableOperatingSystem, runtime.GOOS,
		extraid.ExecutableArchitecture, runtime.GOARCH,
	)

	res, err := cv.GetResource(id)
	if err != nil {
		return errors.Wrapf(err, "resource %s", id)
	}

Now we want to retrieve the executable. The library provides two basic ways to do this.

First, there is the direct way to gain access to the blob by using the basic model operations to get a reader for the resource blob. Therefore, in a first step we get the access method for the resource

		var m ocm.AccessMethod
		m, err = res.AccessMethod()
		if err != nil {
			return errors.Wrapf(err, "cannot get access method")
		}
		defer m.Close()

The method needs to be closed, because the method object may cache the technical blob representation generated by accessing the underlying access technology. (for example, accessing an OCI image requires a sequence of backend requests for the manifest, the layers, etc, which will then be packaged into a tar archive returned as blob). This caching may not be required, if the backend directly returns a blob.

Now, we get access to the reader providing the blob content. The blob features a mime type, which can be used to understand the format of the blob. Here, we have a plain octet stream.

		fmt.Printf("  found blob with mime type %s\n", m.MimeType())
		reader, err = m.Reader()

Because this code sequence is a common operation, there is a utility function handling this sequence. A shorter way to get a resource reader is as follows:

		reader, err = utils.GetResourceReader(res)

Before we download the content we check the error and prepare closing the reader, again

	if err != nil {
		return errors.Wrapf(err, "cannot get resource reader")
	}
	defer reader.Close()

Now, we just read the content and copy it to the intended output file (/tmp/ocmcli).

	file, err := os.OpenFile("/tmp/ocmcli", os.O_CREATE|os.O_WRONLY|os.O_TRUNC, 0o766)
	if err != nil {
		return errors.Wrapf(err, "cannot open output file")
	}
	defer file.Close()

	n, err := io.Copy(file, reader)
	if err != nil {
		return errors.Wrapf(err, "write executable")
	}
	fmt.Printf("%d bytes written\n", n)

Another way to download a resource is to use registered downloaders. download.DownloadResource is used to download resources with specific handlers for selected resource and mime type combinations. The executable downloader is registered by default and automatically sets the X flag for the written file.

	_, err = download.DownloadResource(ctx, res, "/tmp/ocmcli", download.WithPrinter(common.NewPrinter(os.Stdout)))
	if err != nil {
		return errors.Wrapf(err, "download failed")
	}