platforms

package module
v0.2.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jun 10, 2024 License: Apache-2.0 Imports: 14 Imported by: 352

README

platforms

A Go package for formatting, normalizing and matching container platforms.

This package is based on the Open Containers Image Spec definition of a platform.

Platform Specifier

While the OCI platform specifications provide a tool for components to specify structured information, user input typically doesn't need the full context and much can be inferred. To solve this problem, this package introduces "specifiers". A specifier has the format <os>|<arch>|<os>/<arch>[/<variant>]. The user can provide either the operating system or the architecture or both.

An example of a common specifier is linux/amd64. If the host has a default runtime that matches this, the user can simply provide the component that matters. For example, if an image provides amd64 and arm64 support, the operating system, linux can be inferred, so they only have to provide arm64 or amd64. Similar behavior is implemented for operating systems, where the architecture may be known but a runtime may support images from different operating systems.

Project details

platforms is a containerd sub-project, licensed under the Apache 2.0 license. As a containerd sub-project, you will find the:

information in our containerd/project repository.

Documentation

Overview

Package platforms provides a toolkit for normalizing, matching and specifying container platforms.

Centered around OCI platform specifications, we define a string-based specifier syntax that can be used for user input. With a specifier, users only need to specify the parts of the platform that are relevant to their context, providing an operating system or architecture or both.

How do I use this package?

The vast majority of use cases should simply use the match function with user input. The first step is to parse a specifier into a matcher:

m, err := Parse("linux")
if err != nil { ... }

Once you have a matcher, use it to match against the platform declared by a component, typically from an image or runtime. Since extracting an images platform is a little more involved, we'll use an example against the platform default:

if ok := m.Match(Default()); !ok { /* doesn't match */ }

This can be composed in loops for resolving runtimes or used as a filter for fetch and select images.

More details of the specifier syntax and platform spec follow.

Declaring Platform Support

Components that have strict platform requirements should use the OCI platform specification to declare their support. Typically, this will be images and runtimes that should make these declaring which platform they support specifically. This looks roughly as follows:

  type Platform struct {
	   Architecture string
	   OS           string
	   Variant      string
  }

Most images and runtimes should at least set Architecture and OS, according to their GOARCH and GOOS values, respectively (follow the OCI image specification when in doubt). ARM should set variant under certain discussions, which are outlined below.

Platform Specifiers

While the OCI platform specifications provide a tool for components to specify structured information, user input typically doesn't need the full context and much can be inferred. To solve this problem, we introduced "specifiers". A specifier has the format `<os>|<arch>|<os>/<arch>[/<variant>]`. The user can provide either the operating system or the architecture or both.

An example of a common specifier is `linux/amd64`. If the host has a default of runtime that matches this, the user can simply provide the component that matters. For example, if a image provides amd64 and arm64 support, the operating system, `linux` can be inferred, so they only have to provide `arm64` or `amd64`. Similar behavior is implemented for operating systems, where the architecture may be known but a runtime may support images from different operating systems.

Normalization

Because not all users are familiar with the way the Go runtime represents platforms, several normalizations have been provided to make this package easier to user.

The following are performed for architectures:

Value    Normalized
aarch64  arm64
armhf    arm
armel    arm/v6
i386     386
x86_64   amd64
x86-64   amd64

We also normalize the operating system `macos` to `darwin`.

ARM Support

To qualify ARM architecture, the Variant field is used to qualify the arm version. The most common arm version, v7, is represented without the variant unless it is explicitly provided. This is treated as equivalent to armhf. A previous architecture, armel, will be normalized to arm/v6.

Similarly, the most common arm64 version v8, and most common amd64 version v1 are represented without the variant.

While these normalizations are provided, their support on arm platforms has not yet been fully implemented and tested.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func DefaultSpec

func DefaultSpec() specs.Platform

DefaultSpec returns the current platform's default platform specification.

func DefaultString

func DefaultString() string

DefaultString returns the default string specifier for the platform, with [PR#6](https://github.com/containerd/platforms/pull/6) the result may now also include the OSVersion from the provided platform specification.

func Format

func Format(platform specs.Platform) string

Format returns a string specifier from the provided platform specification.

func FormatAll added in v0.2.0

func FormatAll(platform specs.Platform) string

FormatAll returns a string specifier that also includes the OSVersion from the provided platform specification.

func MustParse

func MustParse(specifier string) specs.Platform

MustParse is like Parses but panics if the specifier cannot be parsed. Simplifies initialization of global variables.

func Normalize

func Normalize(platform specs.Platform) specs.Platform

Normalize validates and translate the platform to the canonical value.

For example, if "Aarch64" is encountered, we change it to "arm64" or if "x86_64" is encountered, it becomes "amd64".

func Parse

func Parse(specifier string) (specs.Platform, error)

Parse parses the platform specifier syntax into a platform declaration.

Platform specifiers are in the format `<os>[(<OSVersion>)]|<arch>|<os>[(<OSVersion>)]/<arch>[/<variant>]`. The minimum required information for a platform specifier is the operating system or architecture. The OSVersion can be part of the OS like `windows(10.0.17763)` When an OSVersion is specified, then specs.Platform.OSVersion is populated with that value, and an empty string otherwise. If there is only a single string (no slashes), the value will be matched against the known set of operating systems, then fall back to the known set of architectures. The missing component will be inferred based on the local environment.

func ParseAll

func ParseAll(specifiers []string) ([]specs.Platform, error)

ParseAll parses a list of platform specifiers into a list of platform.

Types

type MatchComparer

type MatchComparer interface {
	Matcher

	Less(specs.Platform, specs.Platform) bool
}

MatchComparer is able to match and compare platforms to filter and sort platforms.

var All MatchComparer = allPlatformComparer{}

All is a platform MatchComparer which matches all platforms with preference for ordering.

func Any

func Any(platforms ...specs.Platform) MatchComparer

Any returns a platform MatchComparer which matches any of the platforms with no preference for ordering.

func Default

func Default() MatchComparer

Default returns the default matcher for the platform.

func DefaultStrict

func DefaultStrict() MatchComparer

DefaultStrict returns strict form of Default.

func Only

func Only(platform specs.Platform) MatchComparer

Only returns a match comparer for a single platform using default resolution logic for the platform.

For arm/v8, will also match arm/v7, arm/v6 and arm/v5 For arm/v7, will also match arm/v6 and arm/v5 For arm/v6, will also match arm/v5 For amd64, will also match 386

func OnlyStrict

func OnlyStrict(platform specs.Platform) MatchComparer

OnlyStrict returns a match comparer for a single platform.

Unlike Only, OnlyStrict does not match sub platforms. So, "arm/vN" will not match "arm/vM" where M < N, and "amd64" will not also match "386".

OnlyStrict matches non-canonical forms. So, "arm64" matches "arm/64/v8".

func Ordered

func Ordered(platforms ...specs.Platform) MatchComparer

Ordered returns a platform MatchComparer which matches any of the platforms but orders them in order they are provided.

type Matcher

type Matcher interface {
	Match(platform specs.Platform) bool
}

Matcher matches platforms specifications, provided by an image or runtime.

func NewMatcher

func NewMatcher(platform specs.Platform) Matcher

NewMatcher returns a simple matcher based on the provided platform specification. The returned matcher only looks for equality based on os, architecture and variant.

One may implement their own matcher if this doesn't provide the required functionality.

Applications should opt to use `Match` over directly parsing specifiers.

type Platform

type Platform = specs.Platform

Platform is a type alias for convenience, so there is no need to import image-spec package everywhere.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL