ihop

Documentation

Index

• type Builder
  • func NewBuilder(client ImageClient, scanner ImageScanner, workerCount int) Builder
  • func (b Builder) Execute(def DefinitionImage, platform string) ImageBuildPromise
• type BuilderPromise
  • func (bp BuilderPromise) Resolve() (Image, SBOM, error)
• type Cataloger
  • func (c Cataloger) Scan(path string) (SBOM, error)
• type Client
  • func NewClient(dir string) (Client, error)
  • func (c Client) Build(def DefinitionImage, platform string) (Image, error)
  • func (c Client) Export(path string, images ...Image) error
  • func (c Client) Update(image Image) (Image, error)
• type Creator
  • func NewCreator(docker ImageClient, builder ImageBuilder, ...) Creator
  • func (c Creator) Execute(def Definition) (Stack, error)
• type Definition
  • func NewDefinitionFromFile(path string, secrets ...string) (Definition, error)
• type DefinitionDeprecated
• type DefinitionImage
  • func (i DefinitionImage) Arguments() ([]string, error)
• type DefinitionRequiredFieldError
  • func NewDefinitionRequiredFieldError(field string) DefinitionRequiredFieldError
  • func (e DefinitionRequiredFieldError) Error() string
• type Image
  • func FromImage(path string, image v1.Image) (Image, error)
• type ImageBuildPromise
• type ImageBuilder
• type ImageClient
• type ImageScanner
• type Layer
• type LayerCreator
• type LegacySBOMPackage
• type LegacySBOMPackageSource
• type OsReleaseLayerCreator
  • func (o OsReleaseLayerCreator) Create(image Image, _ DefinitionImage, _ SBOM) (Layer, error)
• type Packages
  • func NewPackages(build, run []string) Packages
• type SBOM
  • func NewSBOM(sbom sbom.SBOM) SBOM
  • func (s SBOM) CycloneDXFormat() (string, error)
  • func (s SBOM) LegacyFormat() (string, error)
  • func (s SBOM) Packages() []string
  • func (s SBOM) SyftFormat() (string, error)
• type SBOMDistro
• type SBOMLayerCreator
  • func (c SBOMLayerCreator) Create(image Image, def DefinitionImage, sbom SBOM) (Layer, error)
• type Stack
• type UserLayerCreator
  • func (c UserLayerCreator) Create(image Image, def DefinitionImage, _ SBOM) (Layer, error)

Types

type Builder

type Builder struct {
	// contains filtered or unexported fields
}

A Builder is used to asynchronously build and scan a stack image.

func NewBuilder

func NewBuilder(client ImageClient, scanner ImageScanner, workerCount int) Builder

NewBuilder returns a Builder that can build and scan stack images. The Builder will spin up a number of workers to process the build and scan of the stack image. These workers will use the promise returned by the Execute method to pass their results back to the caller.

func (Builder) Execute

func (b Builder) Execute(def DefinitionImage, platform string) ImageBuildPromise

Execute returns an ImageBuildPromise that can be waited upon to receive a built image and its SBOM scan results.

type BuilderPromise

type BuilderPromise struct {
	// contains filtered or unexported fields
}

BuilderPromise implements the ImageBuildPromise interface.

func (BuilderPromise) Resolve

func (bp BuilderPromise) Resolve() (Image, SBOM, error)

Resolve blocks until the image is built and scanned before returning these results.

type Cataloger

type Cataloger struct{}

A Cataloger can be used to generate a software bill-of-materials result using Syft.

func (Cataloger) Scan

func (c Cataloger) Scan(path string) (SBOM, error)

Scan generates an SBOM for an image tagged in the Docker daemon.

type Client

type Client struct {
	// contains filtered or unexported fields
}

A Client can be used to build, update, and export container images.

func NewClient

func NewClient(dir string) (Client, error)

NewClient returns a Client that has been configured to interact with the local Docker daemon using the environment configuration options.

func (Client) Build

func (c Client) Build(def DefinitionImage, platform string) (Image, error)

Build uses BuildKit to build a container image from its reference Dockerfile as specified in the given DefinitionImage. Specifying a platform other than the native platform for the Docker daemon will require that the daemon is configured following the guidelines in https://docs.docker.com/buildx/working-with-buildx/#build-multi-platform-images.

func (Client) Export

func (c Client) Export(path string, images ...Image) error

Export creates an OCI-archive tarball at the path location that includes the given Images.

func (Client) Update

func (c Client) Update(image Image) (Image, error)

Update will apply any modifications made to the Image reference onto the actual container image in the Docker daemon.

type Creator

type Creator struct {
	// contains filtered or unexported fields
}

A Creator can be used to generate a Stack.

func NewCreator

func NewCreator(docker ImageClient, builder ImageBuilder, userLayerCreator, sbomLayerCreator LayerCreator, osReleaseLayerCreator LayerCreator, now func() time.Time, logger scribe.Logger) Creator

NewCreator returns a Creator configured with the given arguments.

func (Creator) Execute

func (c Creator) Execute(def Definition) (Stack, error)

Execute builds a Stack using the given Definition.

type Definition

type Definition struct {
	// ID is the stack id applied to the built images.
	ID string `toml:"id"`

	// Name is a human readable name of the stack.
	Name string `toml:"name"`

	// Homepage is the homepage for the stack.
	Homepage string `toml:"homepage"`

	// SupportURL is the support homepage for the stack.
	SupportURL string `toml:"support-url"`

	// BugReportURL is the bug report homepage for the stack.
	BugReportURL string `toml:"bug-report-url"`

	// Maintainer is the named individual or group responsible for maintaining
	// the stack.
	Maintainer string `toml:"maintainer"`

	// Platforms is a list of platforms the built stack should support. These
	// values must conform to values accepted by the --platform flag on the
	// docker CLI.
	Platforms []string `toml:"platforms"`

	// Build is the DefinitionImage for the stack build image.
	Build DefinitionImage `toml:"build"`

	// Run is the DefinitionImage for the stack run image.
	Run DefinitionImage `toml:"run"`

	// Deprecated contains fields enabling deprecated features of the stack
	// images.
	Deprecated DefinitionDeprecated `toml:"deprecated"`

	// IncludeExperimentalSBOM can be used to attach an experimental SBOM layer
	// to the run image.
	IncludeExperimentalSBOM bool `toml:"-"`
}

A Definition represents the content of the stack descriptor file.

func NewDefinitionFromFile

func NewDefinitionFromFile(path string, secrets ...string) (Definition, error)

NewDefinitionFromFile parses the stack descriptor from a file location.

type DefinitionDeprecated

type DefinitionDeprecated struct {
	// LegacySBOM can be set to true to include the io.paketo.stack.packages
	// image label.
	LegacySBOM bool `toml:"legacy-sbom"`

	// Mixins can be set to true to include the io.buildpacks.stack.mixins image
	// label.
	Mixins bool `toml:"mixins"`
}

DefinitionDeprecated defines the deprecated features of the stack.

type DefinitionImage

type DefinitionImage struct {
	// Args can be used to pass arguments to the Dockerfile as might be done with
	// the --build-arg docker CLI flag.
	Args map[string]any `toml:"args"`

	// Description will be used to fill the io.buildpacks.stack.description image
	// label.
	Description string `toml:"description"`

	// Dockerfile is the path to the Dockerfile used to build the image. The
	// surrounding directory is used as the build context.
	Dockerfile string `toml:"dockerfile"`

	// GID is the cnb group id to be specified in the image.
	GID int `toml:"gid"`

	// Secrets can be used to pass secret arguments to the Dockerfile build.
	Secrets map[string]string `toml:"-"`

	// Shell is the default shell to be configured for the cnb user.
	Shell string `toml:"shell"`

	// UID is the cnb user id to be specified in the image.
	UID int `toml:"uid"`
}

DefinitionImage defines the definition of a build or run stack image.

func (DefinitionImage) Arguments

func (i DefinitionImage) Arguments() ([]string, error)

Arguments converts the Args map into a slice of strings of the form key=value.

type DefinitionRequiredFieldError

type DefinitionRequiredFieldError string

DefinitionRequiredFieldError defines the error message when a required field is missing from the stack descriptor.

func NewDefinitionRequiredFieldError

func NewDefinitionRequiredFieldError(field string) DefinitionRequiredFieldError

NewDefinitionRequiredFieldError returns a DefinitionRequiredFieldError to report the absence of the given field.

func (DefinitionRequiredFieldError) Error

func (e DefinitionRequiredFieldError) Error() string

Error returns an error message indicating that a required field is missing from the stack descriptor.

type Image

type Image struct {
	Digest       string
	OS           string
	Architecture string
	User         string

	Env    []string
	Labels map[string]string

	Layers []Layer

	Actual v1.Image
	Path   string
}

An Image is a representation of a container image that can be built, updated, or exported to an OCI-archive format.

func FromImage

func FromImage(path string, image v1.Image) (Image, error)

type ImageBuildPromise

type ImageBuildPromise interface {
	Resolve() (Image, SBOM, error)
}

type ImageBuilder

type ImageBuilder interface {
	Execute(definitionImage DefinitionImage, platform string) ImageBuildPromise
}

type ImageClient

type ImageClient interface {
	Build(definitionImage DefinitionImage, platform string) (Image, error)
	Update(Image) (Image, error)
}

type ImageScanner

type ImageScanner interface {
	Scan(path string) (SBOM, error)
}

type Layer

type Layer struct {
	DiffID string

	v1.Layer
}

A Layer is a representation of a container image layer.

type LayerCreator

type LayerCreator interface {
	Create(Image, DefinitionImage, SBOM) (Layer, error)
}

type LegacySBOMPackage

type LegacySBOMPackage struct {
	Name    string                   `json:"name"`
	Version string                   `json:"version"`
	Arch    string                   `json:"arch"`
	Source  *LegacySBOMPackageSource `json:"source,omitempty"`
	Summary string                   `json:"summary,omitempty"`
}

LegacySBOMPackage represents a package as defined in the legacy SBOM format.

type LegacySBOMPackageSource

type LegacySBOMPackageSource struct {
	Name            string `json:"name"`
	Version         string `json:"version,omitempty"`
	UpstreamVersion string `json:"upstreamVersion,omitempty"`
}

LegacySBOMPackageSource represents a package source as defined in the legacy SBOM format.

type OsReleaseLayerCreator

type OsReleaseLayerCreator struct {
	Def Definition
}

A OsReleaseLayerCreator can be used to construct a layer that includes /etc/os-release.

func (OsReleaseLayerCreator) Create

func (o OsReleaseLayerCreator) Create(image Image, _ DefinitionImage, _ SBOM) (Layer, error)

type Packages

type Packages struct {
	// Intersection is the set of packages that appear in both the build and run
	// image.
	Intersection []string

	// BuildComplement is the set of package that appear only in the build image.
	BuildComplement []string

	// RunComplement is the set of package that appear only in the run image.
	RunComplement []string
}

Packages represents the set of packages contained in the build and run images.

func NewPackages

func NewPackages(build, run []string) Packages

NewPackages returns a Packages that includes the intersection and complements for each of the build and run image packages lists.

type SBOM

type SBOM struct {
	Distro SBOMDistro
	// contains filtered or unexported fields
}

SBOM represents the software bill-of-materials results from an image scan.

func NewSBOM

func NewSBOM(sbom sbom.SBOM) SBOM

NewSBOM returns an SBOM given the results from a Syft image scan.

func (SBOM) CycloneDXFormat

func (s SBOM) CycloneDXFormat() (string, error)

CycloneDXFormat returns a CycloneDX JSON-encoded string representation of the SBOM contents using schema version 1.3.

func (SBOM) LegacyFormat

func (s SBOM) LegacyFormat() (string, error)

LegacyFormat returns a JSON-encoded string representation of the legacy SBOM format.

func (SBOM) Packages

func (s SBOM) Packages() []string

Packages returns the list of packages included in the SBOM.

func (SBOM) SyftFormat

func (s SBOM) SyftFormat() (string, error)

SyftFormat returns a Syft JSON-encoded string representation of the SBOM contents using schema version 2.0.2.

type SBOMDistro

type SBOMDistro struct {
	Name    string
	Version string
}

SBOMDistroy contains the name and version of the underlying image distribution.

type SBOMLayerCreator

type SBOMLayerCreator struct{}

A SBOMLayerCreator can be used to construct a layer that includes the contents of an SBOM in Syft and CycloneDX formats.

func (SBOMLayerCreator) Create

func (c SBOMLayerCreator) Create(image Image, def DefinitionImage, sbom SBOM) (Layer, error)

Create returns a Layer that can be attached to an existing image.

type Stack

type Stack struct {
	Build []Image
	Run   []Image
}

A Stack holds all of the Build and Run images for a built stack.

type UserLayerCreator

type UserLayerCreator struct{}

A UserLayerCreator can be used to construct a layer that includes user and group metadata defining the cnb user for the container.

func (UserLayerCreator) Create

func (c UserLayerCreator) Create(image Image, def DefinitionImage, _ SBOM) (Layer, error)

Create returns a Layer that can be attached to an existing image.