5
import "github.com/containers/common/libnetwork/types"
7
// State is a storage backend for libpod's current state.
8
// A State is only initialized once per instance of libpod.
9
// As such, initialization methods for State implementations may safely assume
10
// they will be run as a singleton.
11
// For all container and pod retrieval methods, a State must retrieve the
12
// Configuration struct of the container or pod and include it in the returned
13
// struct. The State of the container or pod may optionally be included as well,
14
// but this is not a requirement.
15
// As such, all containers and pods must be synced with the database via the
16
// UpdateContainer and UpdatePod calls before any state-specific information is
17
// retrieved after they are pulled from the database.
18
// Generally speaking, the syncContainer() call should be run at the beginning
19
// of all API operations, which will silently handle this.
20
type State interface { //nolint:interfacebloat21
// Close performs any pre-exit cleanup (e.g. closing database
22
// connections) that may be required
25
// Refresh clears container and pod states after a reboot
28
// GetDBConfig retrieves several paths configured within the database
29
// when it was created - namely, Libpod root and tmp dirs, c/storage
30
// root and tmp dirs, and c/storage graph driver.
31
// This is not implemented by the in-memory state, as it has no need to
32
// validate runtime configuration.
33
GetDBConfig() (*DBConfig, error)
35
// ValidateDBConfig validates the config in the given Runtime struct
36
// against paths stored in the configured database.
37
// Libpod root and tmp dirs and c/storage root and tmp dirs and graph
38
// driver are validated.
39
// This is not implemented by the in-memory state, as it has no need to
40
// validate runtime configuration that may change over multiple runs of
42
ValidateDBConfig(runtime *Runtime) error
44
// Resolve an ID to a Container Name.
45
GetContainerName(id string) (string, error)
46
// Resolve an ID to a Pod Name.
47
GetPodName(id string) (string, error)
49
// Return a container from the database from its full ID.
50
// If the container is not in the set namespace, an error will be
52
Container(id string) (*Container, error)
53
// Return a container ID from the database by full or partial ID or full
55
LookupContainerID(idOrName string) (string, error)
56
// Return a container from the database by full or partial ID or full
58
// Containers not in the set namespace will be ignored.
59
LookupContainer(idOrName string) (*Container, error)
60
// Check if a container with the given full ID exists in the database.
61
// If the container exists but is not in the set namespace, false will
63
HasContainer(id string) (bool, error)
64
// Adds container to state.
65
// The container cannot be part of a pod.
66
// The container must have globally unique name and ID - pod names and
67
// IDs also conflict with container names and IDs.
68
// The container must be in the set namespace if a namespace has been
70
// All containers this container depends on must be part of the same
71
// namespace and must not be joined to a pod.
72
AddContainer(ctr *Container) error
73
// Removes container from state.
74
// Containers that are part of pods must use RemoveContainerFromPod.
75
// The container must be part of the set namespace.
76
// All dependencies must be removed first.
77
// All exec sessions referencing the container must be removed first.
78
RemoveContainer(ctr *Container) error
79
// UpdateContainer updates a container's state from the backing store.
80
// The container must be part of the set namespace.
81
UpdateContainer(ctr *Container) error
82
// SaveContainer saves a container's current state to the backing store.
83
// The container must be part of the set namespace.
84
SaveContainer(ctr *Container) error
85
// ContainerInUse checks if other containers depend upon a given
87
// It returns a slice of the IDs of containers which depend on the given
88
// container. If the slice is empty, no container depend on the given
90
// A container cannot be removed if other containers depend on it.
91
// The container being checked must be part of the set namespace.
92
ContainerInUse(ctr *Container) ([]string, error)
93
// Retrieves all containers presently in state.
94
// If `loadState` is set, the containers' state will be loaded as well.
95
// If a namespace is set, only containers within the namespace will be
97
AllContainers(loadState bool) ([]*Container, error)
99
// Get networks the container is currently connected to.
100
GetNetworks(ctr *Container) (map[string]types.PerNetworkOptions, error)
101
// Add the container to the given network with the given options
102
NetworkConnect(ctr *Container, network string, opts types.PerNetworkOptions) error
103
// Modify the container network with the given options.
104
NetworkModify(ctr *Container, network string, opts types.PerNetworkOptions) error
105
// Remove the container from the given network, removing all aliases for
106
// the container in that network in the process.
107
NetworkDisconnect(ctr *Container, network string) error
109
// Return a container config from the database by full ID
110
GetContainerConfig(id string) (*ContainerConfig, error)
112
// Add the exit code for the specified container to the database.
113
AddContainerExitCode(id string, exitCode int32) error
114
// Return the exit code for the specified container.
115
GetContainerExitCode(id string) (int32, error)
116
// Remove exit codes older than 5 minutes.
117
PruneContainerExitCodes() error
119
// Add creates a reference to an exec session in the database.
120
// The container the exec session is attached to will be recorded.
121
// The container state will not be modified.
122
// The actual exec session itself is part of the container's state.
123
// We assume higher-level callers will add the session by saving the
124
// container's state before calling this. This only ensures that the ID
125
// of the exec session is associated with the ID of the container.
126
// Implementations may, but are not required to, verify that the state
127
// of the given container has an exec session with the ID given.
128
AddExecSession(ctr *Container, session *ExecSession) error
129
// Get retrieves the container a given exec session is attached to.
130
GetExecSession(id string) (string, error)
131
// Remove a reference to an exec session from the database.
132
// This will not modify container state to remove the exec session there
133
// and instead only removes the session ID -> container ID reference
134
// added by AddExecSession.
135
RemoveExecSession(session *ExecSession) error
136
// Get the IDs of all exec sessions attached to a given container.
137
GetContainerExecSessions(ctr *Container) ([]string, error)
138
// Remove all exec sessions for a single container.
139
// Usually used as part of removing the container.
140
// As with RemoveExecSession, container state will not be modified.
141
RemoveContainerExecSessions(ctr *Container) error
143
// ContainerIDIsVolume checks if the given container ID is in use by a
145
// Some volumes are backed by a c/storage container. These do not have a
146
// corresponding Container struct in Libpod, but rather a Volume.
147
// This determines if a given ID from c/storage is used as a backend by
149
ContainerIDIsVolume(id string) (bool, error)
151
// PLEASE READ FULL DESCRIPTION BEFORE USING.
152
// Rewrite a container's configuration.
153
// This function breaks libpod's normal prohibition on a read-only
154
// configuration, and as such should be used EXTREMELY SPARINGLY and
155
// only in very specific circumstances.
156
// Specifically, it is ONLY safe to use thing function to make changes
157
// that result in a functionally identical configuration (migrating to
158
// newer, but identical, configuration fields), or during libpod init
159
// WHILE HOLDING THE ALIVE LOCK (to prevent other libpod instances from
160
// being initialized).
161
// Most things in config can be changed by this, but container ID and
162
// name ABSOLUTELY CANNOT BE ALTERED. If you do so, there is a high
163
// potential for database corruption.
164
// There are a lot of capital letters and conditions here, but the short
165
// answer is this: use this only very sparingly, and only if you really
166
// know what you're doing.
167
// TODO: Once BoltDB is removed, RewriteContainerConfig and
168
// SafeRewriteContainerConfig can be merged.
169
RewriteContainerConfig(ctr *Container, newCfg *ContainerConfig) error
170
// This is a more limited version of RewriteContainerConfig, though it
171
// comes with the added ability to alter a container's name. In exchange
172
// it loses the ability to manipulate the container's locks.
173
// It is not intended to be as restrictive as RewriteContainerConfig, in
174
// that we allow it to be run while other Podman processes are running,
175
// and without holding the alive lock.
176
// Container ID and pod membership still *ABSOLUTELY CANNOT* be altered.
177
// Also, you cannot change a container's dependencies - shared namespace
178
// containers or generic dependencies - at present. This is
179
// theoretically possible but not yet implemented.
180
// If newName is not "" the container will be renamed to the new name.
181
// The oldName parameter is only required if newName is given.
182
SafeRewriteContainerConfig(ctr *Container, oldName, newName string, newCfg *ContainerConfig) error
183
// PLEASE READ THE DESCRIPTION FOR RewriteContainerConfig BEFORE USING.
184
// This function is identical to RewriteContainerConfig, save for the
185
// fact that it is used with pods instead.
186
// It is subject to the same conditions as RewriteContainerConfig.
187
// Please do not use this unless you know what you're doing.
188
RewritePodConfig(pod *Pod, newCfg *PodConfig) error
189
// PLEASE READ THE DESCRIPTION FOR RewriteContainerConfig BEFORE USING.
190
// This function is identical to RewriteContainerConfig, save for the
191
// fact that it is used with volumes instead.
192
// It is subject to the same conditions as RewriteContainerConfig.
193
// The exception is that volumes do not have IDs, so only volume name
194
// cannot be altered.
195
// Please do not use this unless you know what you're doing.
196
RewriteVolumeConfig(volume *Volume, newCfg *VolumeConfig) error
198
// Accepts full ID of pod.
199
// If the pod given is not in the set namespace, an error will be
201
Pod(id string) (*Pod, error)
202
// Accepts full or partial IDs (as long as they are unique) and names.
203
// Pods not in the set namespace are ignored.
204
LookupPod(idOrName string) (*Pod, error)
205
// Checks if a pod with the given ID is present in the state.
206
// If the given pod is not in the set namespace, false is returned.
207
HasPod(id string) (bool, error)
208
// Check if a pod has a container with the given ID.
209
// The pod must be part of the set namespace.
210
PodHasContainer(pod *Pod, ctrID string) (bool, error)
211
// Get the IDs of all containers in a pod.
212
// The pod must be part of the set namespace.
213
PodContainersByID(pod *Pod) ([]string, error)
214
// Get all the containers in a pod.
215
// The pod must be part of the set namespace.
216
PodContainers(pod *Pod) ([]*Container, error)
217
// Adds pod to state.
218
// The pod must be part of the set namespace.
219
// The pod's name and ID must be globally unique.
220
AddPod(pod *Pod) error
221
// Removes pod from state.
222
// Only empty pods can be removed from the state.
223
// The pod must be part of the set namespace.
224
RemovePod(pod *Pod) error
225
// Remove all containers from a pod.
226
// Used to simultaneously remove containers that might otherwise have
227
// dependency issues.
228
// Will fail if a dependency outside the pod is encountered.
229
// The pod must be part of the set namespace.
230
RemovePodContainers(pod *Pod) error
231
// AddContainerToPod adds a container to an existing pod.
232
// The container given will be added to the state and the pod.
233
// The container and its dependencies must be part of the given pod,
234
// and the given pod's namespace.
235
// The pod must be part of the set namespace.
236
// The pod must already exist in the state.
237
// The container's name and ID must be globally unique.
238
AddContainerToPod(pod *Pod, ctr *Container) error
239
// RemoveContainerFromPod removes a container from an existing pod.
240
// The container will also be removed from the state.
241
// The container must be in the given pod, and the pod must be in the
243
RemoveContainerFromPod(pod *Pod, ctr *Container) error
244
// UpdatePod updates a pod's state from the database.
245
// The pod must be in the set namespace.
246
UpdatePod(pod *Pod) error
247
// SavePod saves a pod's state to the database.
248
// The pod must be in the set namespace.
249
SavePod(pod *Pod) error
250
// Retrieves all pods presently in state.
251
// If a namespace has been set, only pods in that namespace will be
253
AllPods() ([]*Pod, error)
255
// Volume accepts full name of volume
256
// If the volume doesn't exist, an error will be returned
257
Volume(volName string) (*Volume, error)
258
// LookupVolume accepts an unambiguous partial name or full name of a
259
// volume. Ambiguous names will result in an error.
260
LookupVolume(name string) (*Volume, error)
261
// HasVolume returns true if volName exists in the state,
262
// otherwise it returns false
263
HasVolume(volName string) (bool, error)
264
// VolumeInUse goes through the container dependencies of a volume
265
// and checks if the volume is being used by any container. If it is
266
// a slice of container IDs using the volume is returned
267
VolumeInUse(volume *Volume) ([]string, error)
268
// AddVolume adds the specified volume to state. The volume's name
269
// must be unique within the list of existing volumes
270
AddVolume(volume *Volume) error
271
// RemoveVolume removes the specified volume.
272
// Only volumes that have no container dependencies can be removed
273
RemoveVolume(volume *Volume) error
274
// UpdateVolume updates the volume's state from the database.
275
UpdateVolume(volume *Volume) error
276
// SaveVolume saves a volume's state to the database.
277
SaveVolume(volume *Volume) error
278
// AllVolumes returns all the volumes available in the state
279
AllVolumes() ([]*Volume, error)