api

Documentation

Overview

Provides types used for processing s2i builds.

Index

• Constants
• func IsInvalidFilename(name string) bool
• type CGroupLimits
• type CloneConfig
• type Config
• type DockerConfig
• type DockerNetworkMode
  • func NewDockerNetworkModeContainer(id string) DockerNetworkMode
• type EnvironmentList
  • func (e *EnvironmentList) Set(value string) error
  • func (e *EnvironmentList) String() string
  • func (e *EnvironmentList) Type() string
• type EnvironmentSpec
• type InstallResult
• type ProxyConfig
• type PullPolicy
  • func (p *PullPolicy) Set(v string) error
  • func (p *PullPolicy) String() string
  • func (p *PullPolicy) Type() string
• type Result
• type SourceInfo
• type VolumeList
  • func (l *VolumeList) AsBinds() []string
  • func (l *VolumeList) Set(value string) error
  • func (l *VolumeList) String() string
  • func (l *VolumeList) Type() string
• type VolumeSpec

Constants

const (
	// Assemble is the name of the script responsible for the build process of the resulting image.
	Assemble = "assemble"
	// AssembleRuntime is the name of the script responsible for the preparation process of the resulting image.
	AssembleRuntime = "assemble-runtime"
	// Run is the name of the script responsible for running the final application.
	Run = "run"
	// SaveArtifacts is the name of the script responsible for storing dependencies etc. between builds.
	SaveArtifacts = "save-artifacts"
	// Usage is the name of the script responsible for printing the builder image's short info.
	Usage = "usage"

	// Environment contains list of key value pairs that will be set during the
	// STI build. Users can use this file to provide extra configuration
	// depending on the builder image used.
	Environment = "environment"
)

const (
	// UserScripts is the location of scripts downloaded from user provided URL (-s flag).
	UserScripts = "downloads" + string(os.PathSeparator) + "scripts"
	// DefaultScripts is the location of scripts downloaded from default location (io.openshift.s2i.scripts-url label).
	DefaultScripts = "downloads" + string(os.PathSeparator) + "defaultScripts"
	// SourceScripts is the location of scripts downloaded with application sources.
	SourceScripts = "upload" + string(os.PathSeparator) + "src" + string(os.PathSeparator) + ".s2i" + string(os.PathSeparator) + "bin"
	// UploadScripts is the location of scripts that will be uploaded to the image during STI build.
	UploadScripts = "upload" + string(os.PathSeparator) + "scripts"
	// Source is the location of application sources.
	Source = "upload" + string(os.PathSeparator) + "src"

	// ContextTmp is the location of applications sources off of a supplied context dir
	ContextTmp = "upload" + string(os.PathSeparator) + "tmp"

	// RuntimeArtifactsDir is the location of application artifacts and scripts that will be copied into a runtime image.
	RuntimeArtifactsDir = "upload" + string(os.PathSeparator) + "runtimeArtifacts"

	// Ignorefile is the s2i version for ignore files like we see with .gitignore or .dockerignore .. initial impl mirrors documented .dockerignore capabilities
	IgnoreFile = ".s2iignore"
)

const (
	DefaultNamespace    = "io.openshift.s2i."
	KubernetesNamespace = "io.k8s."
)

Image label namespace constants

const (
	// PullAlways means that we always attempt to pull the latest image.
	PullAlways PullPolicy = "always"

	// PullNever means that we never pull an image, but only use a local image.
	PullNever PullPolicy = "never"

	// PullIfNotPresent means that we pull if the image isn't present on disk.
	PullIfNotPresent PullPolicy = "if-not-present"

	// DefaultBuilderPullPolicy specifies the default pull policy to use
	DefaultBuilderPullPolicy = PullIfNotPresent

	// DefaultRuntimeImagePullPolicy specifies the default pull policy to use.
	DefaultRuntimeImagePullPolicy = PullIfNotPresent

	// DefaultPreviousImagePullPolicy specifies policy for pulling the previously
	// build Docker image when doing incremental build
	DefaultPreviousImagePullPolicy = PullIfNotPresent
)

const (
	// DockerNetworkModeHost places the container in the default (host) network namespace.
	DockerNetworkModeHost DockerNetworkMode = "host"
	// DockerNetworkModeBridge instructs docker to create a network namespace for this container connected to the docker0 bridge via a veth-pair.
	DockerNetworkModeBridge DockerNetworkMode = "bridge"
	// DockerNetworkModeContainerPrefix is the string prefix used by NewDockerNetworkModeContainer.
	DockerNetworkModeContainerPrefix string = "container:"
)

Functions

func IsInvalidFilename

func IsInvalidFilename(name string) bool

IsInvalidFilename verifies if the provided filename contains malicious characters.

Types

type CGroupLimits

type CGroupLimits struct {
	MemoryLimitBytes int64
	CPUShares        int64
	CPUPeriod        int64
	CPUQuota         int64
	MemorySwap       int64
}

CGroupLimits holds limits used to constrain container resources.

type CloneConfig

type CloneConfig struct {
	Recursive bool
	Quiet     bool
}

CloneConfig specifies the options used when cloning the application source code.

type Config

type Config struct {
	// DisplayName is a result image display-name label. This defaults to the
	// output image name.
	DisplayName string

	// Description is a result image description label. The default is no
	// description.
	Description string

	// BuilderImage describes which image is used for building the result images.
	BuilderImage string

	// BuilderImageVersion provides optional version information about the builder image.
	BuilderImageVersion string

	// BuilderBaseImageVersion provides optional version information about the builder base image.
	BuilderBaseImageVersion string

	// RuntimeImage specifies the image that will be a base for resulting image
	// and will be used for running an application. By default, BuilderImage is
	// used for building and running, but the latter may be overridden.
	RuntimeImage string

	// RuntimeImagePullPolicy specifies when to pull a runtime image.
	RuntimeImagePullPolicy PullPolicy

	// RuntimeAuthentication holds the authentication information for pulling the
	// runtime Docker images from private repositories.
	RuntimeAuthentication docker.AuthConfiguration

	// RuntimeArtifacts specifies a list of source/destination pairs that will
	// be copied from builder to a runtime image. Source can be a file or
	// directory. Destination must be a directory. Regardless whether it
	// is an absolute or relative path, it will be placed into image's WORKDIR.
	// Destination also can be empty or equals to ".", in this case it just
	// refers to a root of WORKDIR.
	// In case it's empty, S2I will try to get this list from
	// io.openshift.s2i.assemble-input-files label on a RuntimeImage.
	RuntimeArtifacts VolumeList

	// DockerConfig describes how to access host docker daemon.
	DockerConfig *DockerConfig

	// DockerCfgPath provides the path to the .dockercfg file
	DockerCfgPath string

	// PullAuthentication holds the authentication information for pulling the
	// Docker images from private repositories
	PullAuthentication docker.AuthConfiguration

	// IncrementalAuthentication holds the authentication information for pulling the
	// previous image from private repositories
	IncrementalAuthentication docker.AuthConfiguration

	// DockerNetworkMode is used to set the docker network setting to --net=container:<id>
	// when the builder is invoked from a container.
	DockerNetworkMode DockerNetworkMode

	// PreserveWorkingDir describes if working directory should be left after processing.
	PreserveWorkingDir bool

	// IgnoreSubmodules determines whether we will attempt to pull in submodules
	// (via --recursive or submodule init)
	IgnoreSubmodules bool

	// Source URL describing the location of sources used to build the result image.
	Source string

	// Ref is a tag/branch to be used for build.
	Ref string

	// Tag is a result image tag name.
	Tag string

	// BuilderPullPolicy specifies when to pull the builder image
	BuilderPullPolicy PullPolicy

	// PreviousImagePullPolicy specifies when to pull the previously build image
	// when doing incremental build
	PreviousImagePullPolicy PullPolicy

	// ForcePull defines if the builder image should be always pulled or not.
	// This is now deprecated by BuilderPullPolicy and will be removed soon.
	// Setting this to 'true' equals setting BuilderPullPolicy to 'PullAlways'.
	// Setting this to 'false' equals setting BuilderPullPolicy to 'PullIfNotPresent'
	ForcePull bool

	// Incremental describes whether to try to perform incremental build.
	Incremental bool

	// IncrementalFromTag sets an alternative image tag to look for existing
	// artifacts. Tag is used by default if this is not set.
	IncrementalFromTag string

	// RemovePreviousImage describes if previous image should be removed after successful build.
	// This applies only to incremental builds.
	RemovePreviousImage bool

	// Environment is a map of environment variables to be passed to the image.
	Environment EnvironmentList

	// EnvironmentFile provides the path to a file with list of environment
	// variables.
	EnvironmentFile string

	// LabelNamespace provides the namespace under which the labels will be generated.
	LabelNamespace string

	// CallbackURL is a URL which is called upon successful build to inform about that fact.
	CallbackURL string

	// ScriptsURL is a URL describing the localization of S2I scripts used during build process.
	ScriptsURL string

	// Destination specifies a location where the untar operation will place its artifacts.
	Destination string

	// WorkingDir describes temporary directory used for downloading sources, scripts and tar operations.
	WorkingDir string

	// WorkingSourceDir describes the subdirectory off of WorkingDir set up during the repo download
	// that is later used as the root for ignore processing
	WorkingSourceDir string

	// LayeredBuild describes if this is build which layered scripts and sources on top of BuilderImage.
	LayeredBuild bool

	// Operate quietly. Progress and assemble script output are not reported, only fatal errors.
	// (default: false).
	Quiet bool

	// ForceCopy results in only the file SCM plugin being used (i.e. no `git clone`); allows for empty directories to be included
	// in resulting image (since git does not support that).
	// (default: false).
	ForceCopy bool

	// Specify a relative directory inside the application repository that should
	// be used as a root directory for the application.
	ContextDir string

	// AllowedUIDs is a list of user ranges of users allowed to run the builder image.
	// If a range is specified and the builder (or runtime) image uses a non-numeric
	// user or a user that is outside the specified range, then the build fails.
	AllowedUIDs user.RangeList

	// AssembleUser specifies the user to run the assemble script in container
	AssembleUser string

	// RunImage will trigger a "docker run ..." invocation of the produced image so the user
	// can see if it operates as he would expect
	RunImage bool

	// Usage allows for properly shortcircuiting s2i logic when `s2i usage` is invoked
	Usage bool

	// Injections specifies a list source/destination folders that are injected to
	// the container that runs assemble.
	// All files we inject will be truncated after the assemble script finishes.
	Injections VolumeList

	// CGroupLimits describes the cgroups limits that will be applied to any containers
	// run by s2i.
	CGroupLimits *CGroupLimits

	// DropCapabilities contains a list of capabilities to drop when executing containers
	DropCapabilities []string

	// ScriptDownloadProxyConfig optionally specifies the http and https proxy
	// to use when downloading scripts
	ScriptDownloadProxyConfig *ProxyConfig

	// ExcludeRegExp contains a string representation of the regular expression desired for
	// deciding which files to exclude from the tar stream
	ExcludeRegExp string

	// BlockOnBuild prevents s2i from performing a docker build operation
	// if one is necessary to execute ONBUILD commands, or to layer source code into
	// the container for images that don't have a tar binary available, if the
	// image contains ONBUILD commands that would be executed.
	BlockOnBuild bool

	// HasOnBuild will be set to true if the builder image contains ONBUILD instructions
	HasOnBuild bool

	// BuildVolumes specifies a list of volumes to mount to container running the
	// build.
	BuildVolumes VolumeList
}

Config contains essential fields for performing build.

type DockerConfig

type DockerConfig struct {
	// Endpoint is the docker network endpoint or socket
	Endpoint string

	// CertFile is the certificate file path for a TLS connection
	CertFile string

	// KeyFile is the key file path for a TLS connection
	KeyFile string

	// CAFile is the certificate authority file path for a TLS connection
	CAFile string
}

DockerConfig contains the configuration for a Docker connection.

type DockerNetworkMode

type DockerNetworkMode string

DockerNetworkMode specifies the network mode setting for the docker container

func NewDockerNetworkModeContainer

func NewDockerNetworkModeContainer(id string) DockerNetworkMode

NewDockerNetworkModeContainer creates a DockerNetworkMode value which instructs docker to place the container in the network namespace of an existing container. It can be used, for instance, to place the s2i container in the network namespace of the infrastructure container of a k8s pod.

type EnvironmentList

type EnvironmentList []EnvironmentSpec

EnvironmentList contains list of environment variables.

func (*EnvironmentList) Set

func (e *EnvironmentList) Set(value string) error

Set implements the Set() function of pflags.Value interface.

func (*EnvironmentList) String

func (e *EnvironmentList) String() string

String implements the String() function of pflags.Value interface.

func (*EnvironmentList) Type

func (e *EnvironmentList) Type() string

Type implements the Type() function of pflags.Value interface.

type EnvironmentSpec

type EnvironmentSpec struct {
	Name  string
	Value string
}

EnvironmentSpec specifies a single environment variable.

type InstallResult

type InstallResult struct {

	// Script describes which script this result refers to
	Script string

	// URL describes from where the script was taken
	URL string

	// Downloaded describes if download operation happened, this will be true for
	// external scripts, but false for scripts from inside the image
	Downloaded bool

	// Installed describes if script was installed to upload directory
	Installed bool

	// Error describes last error encountered during install operation
	Error error

	// FailedSources is a list of sources that were attempted but failed
	// when downloading this script
	FailedSources []string
}

InstallResult structure describes the result of install operation

type ProxyConfig

type ProxyConfig struct {
	HTTPProxy  *url.URL
	HTTPSProxy *url.URL
}

ProxyConfig holds proxy configuration.

type PullPolicy

type PullPolicy string

PullPolicy specifies a type for the method used to retrieve the Docker image

func (*PullPolicy) Set

func (p *PullPolicy) Set(v string) error

Set implements the Set() function of pflags.Value interface The valid options are "always", "never" or "if-not-present"

func (*PullPolicy) String

func (p *PullPolicy) String() string

String implements the String() function of pflags.Value so this can be used as command line parameter. This method is really used just to show the default value when printing help. It will not default the configuration.

func (*PullPolicy) Type

func (p *PullPolicy) Type() string

Type implements the Type() function of pflags.Value interface

type Result

type Result struct {

	// Success describes whether the build was successful.
	Success bool

	// Messages is a list of messages from build process.
	Messages []string

	// WorkingDir describes temporary directory used for downloading sources, scripts and tar operations.
	WorkingDir string

	// ImageID describes resulting image ID.
	ImageID string
}

Result structure contains information from build process.

type SourceInfo

type SourceInfo struct {
	// Ref represents a commit SHA-1, valid Git branch name or a Git tag
	// The output image will contain this information as 'io.openshift.build.commit.ref' label.
	Ref string

	// CommitID represents an arbitrary extended object reference in Git as SHA-1
	// The output image will contain this information as 'io.openshift.build.commit.id' label.
	CommitID string

	// Date contains a date when the committer created the commit.
	// The output image will contain this information as 'io.openshift.build.commit.date' label.
	Date string

	// AuthorName contains the name of the author
	// The output image will contain this information (along with AuthorEmail) as 'io.openshift.build.commit.author' label.
	AuthorName string

	// AuthorEmail contains the e-mail of the author
	// The output image will contain this information (along with AuthorName) as 'io.openshift.build.commit.author' lablel.
	AuthorEmail string

	// CommitterName contains the name of the committer
	CommitterName string

	// CommitterEmail contains the e-mail of the committer
	CommitterEmail string

	// Message represents the first 80 characters from the commit message.
	// The output image will contain this information as 'io.openshift.build.commit.message' label.
	Message string

	// Location contains a valid URL to the original repository.
	// The output image will contain this information as 'io.openshift.build.source-location' label.
	Location string

	// ContextDir contains path inside the Location directory that
	// contains the application source code.
	// The output image will contain this information as 'io.openshift.build.source-context-dir'
	// label.
	ContextDir string
}

SourceInfo stores information about the source code

type VolumeList

type VolumeList []VolumeSpec

VolumeList contains list of VolumeSpec.

func (*VolumeList) AsBinds

func (l *VolumeList) AsBinds() []string

AsBinds converts the list of volume definitions to go-dockerclient compatible list of bind mounts.

func (*VolumeList) Set

func (l *VolumeList) Set(value string) error

Set implements the Set() function of pflags.Value interface. This function parses the string that contains source:destination pair. When the destination is not specified, the source get copied into current working directory in container.

func (*VolumeList) String

func (l *VolumeList) String() string

String implements the String() function of pflags.Value interface.

func (*VolumeList) Type

func (l *VolumeList) Type() string

Type implements the Type() function of pflags.Value interface.

type VolumeSpec

type VolumeSpec struct {
	Source      string
	Destination string
}

VolumeSpec represents a single volume mount point.