api

package
v1.1.6 Latest Latest
Warning

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

 Go to latest Published: May 12, 2017 License: Apache-2.0 Imports: 9 Imported by: 0

Documentation

Overview

Package api provides types used for processing s2i builds.

Index

Constants

View Source 
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"
)
View Source 
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"
)
View Source 
const (
	DefaultNamespace    = "io.openshift.s2i."
	KubernetesNamespace = "io.k8s."
)

Image label namespace constants

View Source 
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
)
View Source 
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:"
)

Variables

This section is empty.

Functions

func IsInvalidFilename added in v1.0.5 

func IsInvalidFilename(name string) bool

IsInvalidFilename verifies if the provided filename contains malicious characters.

Types

type AuthConfig added in v1.1.2 

type AuthConfig struct {
	Username      string
	Password      string
	Email         string
	ServerAddress string
}

AuthConfig is our abstraction of the Registry authorization information for whatever docker client we happen to be based on

type BuildInfo added in v1.1.3 

type BuildInfo struct {
	// Stages contains details about each build stage.
	Stages []StageInfo

	// FailureReason is a camel case reason that is used by the machine to reply
	// back to the OpenShift builder with information why any of the steps in the
	// build failed.
	FailureReason FailureReason
}

BuildInfo contains information about the build process.

type CGroupLimits added in v1.0.5 

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

CGroupLimits holds limits used to constrain container resources.

type CloneConfig added in v1.0.3 

type CloneConfig struct {
	Recursive bool
	Quiet     bool
}

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

type Config added in v1.0.1 

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 AuthConfig

	// 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 AuthConfig

	// IncrementalAuthentication holds the authentication information for pulling the
	// previous image from private repositories
	IncrementalAuthentication AuthConfig

	// 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

	// 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 []string

	// Labels specify labels and their values to be applied to the resulting image. Label keys
	// must have non-zero length. The labels defined here override generated labels in case
	// they have the same name.
	Labels map[string]string

	// SourceInfo provides the info about the source to be built rather than relying
	// on the Downloader to retrieve it.
	SourceInfo *SourceInfo
}

Config contains essential fields for performing build.

type ContainerConfig added in v1.1.2 

type ContainerConfig struct {
	Labels map[string]string
	Env    []string
}

ContainerConfig is the abstraction of the docker client provider (formerly go-dockerclient, now either engine-api or kube docker client) container.Config type that is leveraged by s2i or origin

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

	// UseTLS indicates if TLS must be used
	UseTLS bool

	// TLSVerify indicates if TLS peer must be verified
	TLSVerify bool
}

DockerConfig contains the configuration for a Docker connection.

type DockerNetworkMode added in v1.0.4 

type DockerNetworkMode string

DockerNetworkMode specifies the network mode setting for the docker container

func NewDockerNetworkModeContainer added in v1.0.4 

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 added in v1.0.8 

type EnvironmentList []EnvironmentSpec

EnvironmentList contains list of environment variables.

func (*EnvironmentList) Set added in v1.0.8 

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

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

func (*EnvironmentList) String added in v1.0.8 

func (e *EnvironmentList) String() string

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

func (*EnvironmentList) Type added in v1.0.8 

func (e *EnvironmentList) Type() string

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

type EnvironmentSpec added in v1.0.8 

type EnvironmentSpec struct {
	Name  string
	Value string
}

EnvironmentSpec specifies a single environment variable.

type FailureReason added in v1.1.3 

type FailureReason struct {
	Reason  StepFailureReason
	Message StepFailureMessage
}

FailureReason holds the type of failure that occurred during the build process.

type Image added in v1.1.2 

type Image struct {
	ID string
	*ContainerConfig
	Config *ContainerConfig
}

Image is the abstraction of the docker client provider (formerly go-dockerclient, now either engine-api or kube docker client) Image type that is leveraged by s2i or origin

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 added in v1.0.6 

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

ProxyConfig holds proxy configuration.

type PullPolicy added in v1.0.4 

type PullPolicy string

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

func (*PullPolicy) Set added in v1.0.4 

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 added in v1.0.4 

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 added in v1.0.4 

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

	// BuildInfo holds information about the result of a build.
	BuildInfo BuildInfo
}

Result structure contains information from build process.

type SourceInfo added in v1.0.1 

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 StageInfo added in v1.1.6 

type StageInfo struct {
	// Name is the identifier for each build stage.
	Name StageName

	// StartTime identifies when this stage started.
	StartTime time.Time

	// DurationMilliseconds identifies how long this stage ran.
	DurationMilliseconds int64

	// Steps contains details about each build step within a build stage.
	Steps []StepInfo
}

StageInfo contains details about a build stage.

func RecordStageAndStepInfo added in v1.1.6 

func RecordStageAndStepInfo(stages []StageInfo, stageName StageName, stepName StepName, startTime time.Time, endTime time.Time) []StageInfo

RecordStageAndStepInfo records details about each build stage and step

type StageName added in v1.1.6 

type StageName string

StageName is the identifier for each build stage. 

const (
	// StagePullImages pulls the docker images.
	StagePullImages StageName = "PullImages"

	//StageAssemble runs the assemble steps.
	StageAssemble StageName = "Assemble"

	// StageBuild builds the source.
	StageBuild StageName = "Build"

	// StageCommit commits the container.
	StageCommit StageName = "CommitContainer"

	// StageRetrieve retrieves artifacts.
	StageRetrieve StageName = "RetrieveArtifacts"
)

Valid StageNames

type StepFailureMessage added in v1.1.3 

type StepFailureMessage string

StepFailureMessage holds the detailed message of a failure.

type StepFailureReason added in v1.1.3 

type StepFailureReason string

StepFailureReason holds the type of failure that occurred during the build process.

type StepInfo added in v1.1.6 

type StepInfo struct {
	// Name is the identifier for each build step.
	Name StepName

	// StartTime identifies when this step started.
	StartTime time.Time

	// DurationMilliseconds identifies how long this step ran.
	DurationMilliseconds int64
}

StepInfo contains details about a build step.

type StepName added in v1.1.6 

type StepName string

StepName is the identifier for each build step. 

const (
	// StepPullBuilderImage pulls the builder image.
	StepPullBuilderImage StepName = "PullBuilderImage"

	// StepPullPreviousImage pulls the previous image for an incremental build.
	StepPullPreviousImage StepName = "PullPreviousImage"

	// StepPullRuntimeImage pull the runtime image.
	StepPullRuntimeImage StepName = "PullRuntimeImage"

	// StepAssembleBuildScripts runs the assemble scripts.
	StepAssembleBuildScripts StepName = "AssembleBuildScripts"

	// StepBuildDockerImage builds the Docker image for layered builds.
	StepBuildDockerImage StepName = "BuildDockerImage"

	// StepCommitContainer commits the container to the builder image.
	StepCommitContainer StepName = "CommitContainer"

	// StepRetrievePreviousArtifacts restores archived artifacts from the previous build.
	StepRetrievePreviousArtifacts StepName = "RetrievePreviousArtifacts"
)

Valid StepNames

type VolumeList added in v1.0.8 

type VolumeList []VolumeSpec

VolumeList contains list of VolumeSpec.

func (*VolumeList) AsBinds added in v1.0.8 

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

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

func (*VolumeList) Set added in v1.0.8 

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 added in v1.0.8 

func (l *VolumeList) String() string

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

func (*VolumeList) Type added in v1.0.8 

func (l *VolumeList) Type() string

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

type VolumeSpec added in v1.0.8 

type VolumeSpec struct {
	Source      string
	Destination string
}

VolumeSpec represents a single volume mount point.

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.