podman

1
package define
2

3
import (
4
	"io"
5
	"time"
6

7
	nettypes "github.com/containers/common/libnetwork/types"
8
	"github.com/containers/image/v5/docker/reference"
9
	"github.com/containers/image/v5/types"
10
	encconfig "github.com/containers/ocicrypt/config"
11
	"github.com/containers/storage/pkg/archive"
12
	"golang.org/x/sync/semaphore"
13
)
14

15
// AdditionalBuildContext contains verbose details about a parsed build context from --build-context
16
type AdditionalBuildContext struct {
17
	// Value is the URL of an external tar archive.
18
	IsURL bool
19
	// Value is the name of an image which may or may not have already been pulled.
20
	IsImage bool
21
	// Value holds a URL, an image name, or an absolute filesystem path.
22
	Value string
23
	// Absolute filesystem path to downloaded and exported build context
24
	// from external tar archive. This will be populated only if following
25
	// buildcontext is created from IsURL and was downloaded before in any
26
	// of the RUN step.
27
	DownloadedCache string
28
}
29

30
// CommonBuildOptions are resources that can be defined by flags for both buildah from and build
31
type CommonBuildOptions struct {
32
	// AddHost is the list of hostnames to add to the build container's /etc/hosts.
33
	AddHost []string
34
	// OmitHistory tells the builder to ignore the history of build layers and
35
	// base while preparing image-spec, setting this to true will ensure no history
36
	// is added to the image-spec. (default false)
37
	OmitHistory bool
38
	// CgroupParent is the path to cgroups under which the cgroup for the container will be created.
39
	CgroupParent string
40
	// CPUPeriod limits the CPU CFS (Completely Fair Scheduler) period
41
	CPUPeriod uint64
42
	// CPUQuota limits the CPU CFS (Completely Fair Scheduler) quota
43
	CPUQuota int64
44
	// CPUShares (relative weight
45
	CPUShares uint64
46
	// CPUSetCPUs in which to allow execution (0-3, 0,1)
47
	CPUSetCPUs string
48
	// CPUSetMems memory nodes (MEMs) in which to allow execution (0-3, 0,1). Only effective on NUMA systems.
49
	CPUSetMems string
50
	// HTTPProxy determines whether *_proxy env vars from the build host are passed into the container.
51
	HTTPProxy bool
52
	// IdentityLabel if set ensures that default `io.buildah.version` label is not applied to build image.
53
	IdentityLabel types.OptionalBool
54
	// Memory is the upper limit (in bytes) on how much memory running containers can use.
55
	Memory int64
56
	// DNSSearch is the list of DNS search domains to add to the build container's /etc/resolv.conf
57
	DNSSearch []string
58
	// DNSServers is the list of DNS servers to add to the build container's /etc/resolv.conf
59
	DNSServers []string
60
	// DNSOptions is the list of DNS
61
	DNSOptions []string
62
	// LabelOpts is a slice of the fields of an SELinux context, given in "field:pair" format, or "disable".
63
	// Recognized field names are "role", "type", and "level".
64
	LabelOpts []string
65
	// MemorySwap limits the amount of memory and swap together.
66
	MemorySwap int64
67
	// NoHostname tells the builder not to create /etc/hostname content when running
68
	// containers.
69
	NoHostname bool
70
	// NoHosts tells the builder not to create /etc/hosts content when running
71
	// containers.
72
	NoHosts bool
73
	// NoNewPrivileges removes the ability for the container to gain privileges
74
	NoNewPrivileges bool
75
	// OmitTimestamp forces epoch 0 as created timestamp to allow for
76
	// deterministic, content-addressable builds.
77
	OmitTimestamp bool
78
	// SeccompProfilePath is the pathname of a seccomp profile.
79
	SeccompProfilePath string
80
	// ApparmorProfile is the name of an apparmor profile.
81
	ApparmorProfile string
82
	// ShmSize is the "size" value to use when mounting an shmfs on the container's /dev/shm directory.
83
	ShmSize string
84
	// Ulimit specifies resource limit options, in the form type:softlimit[:hardlimit].
85
	// These types are recognized:
86
	// "core": maximum core dump size (ulimit -c)
87
	// "cpu": maximum CPU time (ulimit -t)
88
	// "data": maximum size of a process's data segment (ulimit -d)
89
	// "fsize": maximum size of new files (ulimit -f)
90
	// "locks": maximum number of file locks (ulimit -x)
91
	// "memlock": maximum amount of locked memory (ulimit -l)
92
	// "msgqueue": maximum amount of data in message queues (ulimit -q)
93
	// "nice": niceness adjustment (nice -n, ulimit -e)
94
	// "nofile": maximum number of open files (ulimit -n)
95
	// "nproc": maximum number of processes (ulimit -u)
96
	// "rss": maximum size of a process's (ulimit -m)
97
	// "rtprio": maximum real-time scheduling priority (ulimit -r)
98
	// "rttime": maximum amount of real-time execution between blocking syscalls
99
	// "sigpending": maximum number of pending signals (ulimit -i)
100
	// "stack": maximum stack size (ulimit -s)
101
	Ulimit []string
102
	// Volumes to bind mount into the container
103
	Volumes []string
104
	// Secrets are the available secrets to use in a build.  Each item in the
105
	// slice takes the form "id=foo,src=bar", where both "id" and "src" are
106
	// required, in that order, and "bar" is the name of a file.
107
	Secrets []string
108
	// SSHSources is the available ssh agent connections to forward in the build
109
	SSHSources []string
110
	// OCIHooksDir is the location of OCI hooks for the build containers
111
	OCIHooksDir []string
112
}
113

114
// BuildOptions can be used to alter how an image is built.
115
type BuildOptions struct {
116
	// ContainerSuffix it the name to suffix containers with
117
	ContainerSuffix string
118
	// ContextDirectory is the default source location for COPY and ADD
119
	// commands.
120
	ContextDirectory string
121
	// PullPolicy controls whether or not we pull images.  It should be one
122
	// of PullIfMissing, PullAlways, PullIfNewer, or PullNever.
123
	PullPolicy PullPolicy
124
	// Registry is a value which is prepended to the image's name, if it
125
	// needs to be pulled and the image name alone can not be resolved to a
126
	// reference to a source image.  No separator is implicitly added.
127
	Registry string
128
	// IgnoreUnrecognizedInstructions tells us to just log instructions we
129
	// don't recognize, and try to keep going.
130
	IgnoreUnrecognizedInstructions bool
131
	// Manifest Name to which the image will be added.
132
	Manifest string
133
	// Quiet tells us whether or not to announce steps as we go through them.
134
	Quiet bool
135
	// Isolation controls how Run() runs things.
136
	Isolation Isolation
137
	// Runtime is the name of the command to run for RUN instructions when
138
	// Isolation is either IsolationDefault or IsolationOCI.  It should
139
	// accept the same arguments and flags that runc does.
140
	Runtime string
141
	// RuntimeArgs adds global arguments for the runtime.
142
	RuntimeArgs []string
143
	// TransientMounts is a list of unparsed mounts that will be provided to
144
	// RUN instructions.
145
	TransientMounts []string
146
	// CacheFrom specifies any remote repository which can be treated as
147
	// potential cache source.
148
	CacheFrom []reference.Named
149
	// CacheTo specifies any remote repository which can be treated as
150
	// potential cache destination.
151
	CacheTo []reference.Named
152
	// CacheTTL specifies duration, if specified using `--cache-ttl` then
153
	// cache intermediate images under this duration will be considered as
154
	// valid cache sources and images outside this duration will be ignored.
155
	CacheTTL time.Duration
156
	// Compression specifies the type of compression which is applied to
157
	// layer blobs.  The default is to not use compression, but
158
	// archive.Gzip is recommended.
159
	Compression archive.Compression
160
	// Arguments which can be interpolated into Dockerfiles
161
	Args map[string]string
162
	// Map of external additional build contexts
163
	AdditionalBuildContexts map[string]*AdditionalBuildContext
164
	// Name of the image to write to.
165
	Output string
166
	// BuildOutput specifies if any custom build output is selected for following build.
167
	// It allows end user to export recently built rootfs into a directory or tar.
168
	// See the documentation of 'buildah build --output' for the details of the format.
169
	BuildOutput string
170
	// ConfidentialWorkload controls whether or not, and if so, how, we produce an
171
	// image that's meant to be run using krun as a VM instead of a conventional
172
	// process-type container.
173
	ConfidentialWorkload ConfidentialWorkloadOptions
174
	// Additional tags to add to the image that we write, if we know of a
175
	// way to add them.
176
	AdditionalTags []string
177
	// Logfile specifies if log output is redirected to an external file
178
	// instead of stdout, stderr.
179
	LogFile string
180
	// LogByPlatform tells imagebuildah to split log to different log files
181
	// for each platform if logging to external file was selected.
182
	LogSplitByPlatform bool
183
	// Log is a callback that will print a progress message.  If no value
184
	// is supplied, the message will be sent to Err (or os.Stderr, if Err
185
	// is nil) by default.
186
	Log func(format string, args ...interface{})
187
	// In is connected to stdin for RUN instructions.
188
	In io.Reader
189
	// Out is a place where non-error log messages are sent.
190
	Out io.Writer
191
	// Err is a place where error log messages should be sent.
192
	Err io.Writer
193
	// SignaturePolicyPath specifies an override location for the signature
194
	// policy which should be used for verifying the new image as it is
195
	// being written.  Except in specific circumstances, no value should be
196
	// specified, indicating that the shared, system-wide default policy
197
	// should be used.
198
	SignaturePolicyPath string
199
	// SkipUnusedStages allows users to skip stages in a multi-stage builds
200
	// which do not contribute anything to the target stage. Expected default
201
	// value is true.
202
	SkipUnusedStages types.OptionalBool
203
	// ReportWriter is an io.Writer which will be used to report the
204
	// progress of the (possible) pulling of the source image and the
205
	// writing of the new image.
206
	ReportWriter io.Writer
207
	// OutputFormat is the format of the output image's manifest and
208
	// configuration data.
209
	// Accepted values are buildah.OCIv1ImageManifest and buildah.Dockerv2ImageManifest.
210
	OutputFormat string
211
	// SystemContext holds parameters used for authentication.
212
	SystemContext *types.SystemContext
213
	// NamespaceOptions controls how we set up namespaces processes that we
214
	// might need when handling RUN instructions.
215
	NamespaceOptions []NamespaceOption
216
	// ConfigureNetwork controls whether or not network interfaces and
217
	// routing are configured for a new network namespace (i.e., when not
218
	// joining another's namespace and not just using the host's
219
	// namespace), effectively deciding whether or not the process has a
220
	// usable network.
221
	ConfigureNetwork NetworkConfigurationPolicy
222
	// CNIPluginPath is the location of CNI plugin helpers, if they should be
223
	// run from a location other than the default location.
224
	CNIPluginPath string
225
	// CNIConfigDir is the location of CNI configuration files, if the files in
226
	// the default configuration directory shouldn't be used.
227
	CNIConfigDir string
228

229
	// NetworkInterface is the libnetwork network interface used to setup CNI or netavark networks.
230
	NetworkInterface nettypes.ContainerNetwork `json:"-"`
231

232
	// ID mapping options to use if we're setting up our own user namespace
233
	// when handling RUN instructions.
234
	IDMappingOptions *IDMappingOptions
235
	// AddCapabilities is a list of capabilities to add to the default set when
236
	// handling RUN instructions.
237
	AddCapabilities []string
238
	// DropCapabilities is a list of capabilities to remove from the default set
239
	// when handling RUN instructions. If a capability appears in both lists, it
240
	// will be dropped.
241
	DropCapabilities []string
242
	// CommonBuildOpts is *required*.
243
	CommonBuildOpts *CommonBuildOptions
244
	// CPPFlags are additional arguments to pass to the C Preprocessor (cpp).
245
	CPPFlags []string
246
	// DefaultMountsFilePath is the file path holding the mounts to be mounted for RUN
247
	// instructions in "host-path:container-path" format
248
	DefaultMountsFilePath string
249
	// IIDFile tells the builder to write the image ID to the specified file
250
	IIDFile string
251
	// Squash tells the builder to produce an image with a single layer instead of with
252
	// possibly more than one layer, by only committing a new layer after processing the
253
	// final instruction.
254
	Squash bool
255
	// Labels to set in a committed image.
256
	Labels []string
257
	// LayerLabels metadata for an intermediate image
258
	LayerLabels []string
259
	// Annotations to set in a committed image, in OCI format.
260
	Annotations []string
261
	// OnBuild commands to be run by builds that use the image we'll commit as a base image.
262
	OnBuild []string
263
	// Layers tells the builder to commit an image for each step in the Dockerfile.
264
	Layers bool
265
	// NoCache tells the builder to build the image from scratch without checking for a cache.
266
	// It creates a new set of cached images for the build.
267
	NoCache bool
268
	// RemoveIntermediateCtrs tells the builder whether to remove intermediate containers used
269
	// during the build process. Default is true.
270
	RemoveIntermediateCtrs bool
271
	// ForceRmIntermediateCtrs tells the builder to remove all intermediate containers even if
272
	// the build was unsuccessful.
273
	ForceRmIntermediateCtrs bool
274
	// BlobDirectory is a directory which we'll use for caching layer blobs.
275
	BlobDirectory string
276
	// Target the targeted FROM in the Dockerfile to build.
277
	Target string
278
	// Devices are unparsed devices to provide to RUN instructions.
279
	Devices []string
280
	// SignBy is the fingerprint of a GPG key to use for signing images.
281
	SignBy string
282
	// Architecture specifies the target architecture of the image to be built.
283
	Architecture string
284
	// Timestamp sets the created timestamp to the specified time, allowing
285
	// for deterministic, content-addressable builds.
286
	Timestamp *time.Time
287
	// OS is the specifies the operating system of the image to be built.
288
	OS string
289
	// MaxPullPushRetries is the maximum number of attempts we'll make to pull or push any one
290
	// image from or to an external registry if the first attempt fails.
291
	MaxPullPushRetries int
292
	// PullPushRetryDelay is how long to wait before retrying a pull or push attempt.
293
	PullPushRetryDelay time.Duration
294
	// OciDecryptConfig contains the config that can be used to decrypt an image if it is
295
	// encrypted if non-nil. If nil, it does not attempt to decrypt an image.
296
	OciDecryptConfig *encconfig.DecryptConfig
297
	// Jobs is the number of stages to run in parallel.  If not specified it defaults to 1.
298
	// Ignored if a JobSemaphore is provided.
299
	Jobs *int
300
	// JobSemaphore, for when you want Jobs to be shared with more than just this build.
301
	JobSemaphore *semaphore.Weighted
302
	// LogRusage logs resource usage for each step.
303
	LogRusage bool
304
	// File to which the Rusage logs will be saved to instead of stdout.
305
	RusageLogFile string
306
	// Excludes is a list of excludes to be used instead of the .dockerignore file.
307
	Excludes []string
308
	// IgnoreFile is a name of the .containerignore file
309
	IgnoreFile string
310
	// From is the image name to use to replace the value specified in the first
311
	// FROM instruction in the Containerfile.
312
	From string
313
	// GroupAdd is a list of groups to add to the primary process when handling RUN
314
	// instructions. The magic 'keep-groups' value indicates that the process should
315
	// be allowed to inherit the current set of supplementary groups.
316
	GroupAdd []string
317
	// Platforms is the list of parsed OS/Arch/Variant triples that we want
318
	// to build the image for.  If this slice has items in it, the OS and
319
	// Architecture fields above are ignored.
320
	Platforms []struct{ OS, Arch, Variant string }
321
	// AllPlatforms tells the builder to set the list of target platforms
322
	// to match the set of platforms for which all of the build's base
323
	// images are available.  If this field is set, Platforms is ignored.
324
	AllPlatforms bool
325
	// UnsetEnvs is a list of environments to not add to final image.
326
	UnsetEnvs []string
327
	// UnsetLabels is a list of labels to not add to final image from base image.
328
	UnsetLabels []string
329
	// Envs is a list of environment variables to set in the final image.
330
	Envs []string
331
	// OSFeatures specifies operating system features the image requires.
332
	// It is typically only set when the OS is "windows".
333
	OSFeatures []string
334
	// OSVersion specifies the exact operating system version the image
335
	// requires.  It is typically only set when the OS is "windows".  Any
336
	// value set in a base image will be preserved, so this does not
337
	// frequently need to be set.
338
	OSVersion string
339
	// SBOMScanOptions encapsulates options which control whether or not we
340
	// run scanners on the rootfs that we're about to commit, and how.
341
	SBOMScanOptions []SBOMScanOptions
342
	// CDIConfigDir is the location of CDI configuration files, if the files in
343
	// the default configuration locations shouldn't be used.
344
	CDIConfigDir string
345
}
346