summaryrefslogtreecommitdiff
path: root/pkg/api/server/register_containers.go
diff options
context:
space:
mode:
Diffstat (limited to 'pkg/api/server/register_containers.go')
-rw-r--r--pkg/api/server/register_containers.go251
1 files changed, 120 insertions, 131 deletions
diff --git a/pkg/api/server/register_containers.go b/pkg/api/server/register_containers.go
index af1881624..711aecc84 100644
--- a/pkg/api/server/register_containers.go
+++ b/pkg/api/server/register_containers.go
@@ -11,10 +11,8 @@ import (
func (s *APIServer) RegisterContainersHandlers(r *mux.Router) error {
// swagger:operation POST /containers/create containers createContainer
- //
- // Create a container
- //
// ---
+ // summary: Create a container
// produces:
// - application/json
// parameters:
@@ -24,44 +22,62 @@ func (s *APIServer) RegisterContainersHandlers(r *mux.Router) error {
// description: container name
// responses:
// '201':
- // description: tbd
+ // $ref: "#/responses/ContainerCreateResponse"
// '400':
// "$ref": "#/responses/BadParamError"
// '404':
// "$ref": "#/responses/NoSuchContainer"
// '409':
- // "$ref": "#/types/ConflictError"
+ // "$ref": "#/responses/ConflictError"
// '500':
- // "$ref": "#/types/InternalError"
+ // "$ref": "#/responses/InternalError"
r.HandleFunc(VersionedPath("/containers/create"), APIHandler(s.Context, generic.CreateContainer)).Methods(http.MethodPost)
// swagger:operation GET /containers/json containers listContainers
- //
- // List containers
- //
// ---
+ // summary: List containers
+ // description: Returns a list of containers
+ // parameters:
+ // - in: query
+ // name: filters
+ // type: string
+ // description: |
+ // Returns a list of containers.
+ // - ancestor=(<image-name>[:<tag>], <image id>, or <image@digest>)
+ // - before=(<container id> or <container name>)
+ // - expose=(<port>[/<proto>]|<startport-endport>/[<proto>])
+ // - exited=<int> containers with exit code of <int>
+ // - health=(starting|healthy|unhealthy|none)
+ // - id=<ID> a container's ID
+ // - is-task=(true|false)
+ // - label=key or label="key=value" of a container label
+ // - name=<name> a container's name
+ // - network=(<network id> or <network name>)
+ // - publish=(<port>[/<proto>]|<startport-endport>/[<proto>])
+ // - since=(<container id> or <container name>)
+ // - status=(created|restarting|running|removing|paused|exited|dead)
+ // - volume=(<volume name> or <mount point destination>)
// produces:
// - application/json
// responses:
// '200':
- // schema:
- // type: array
- // items:
- // "$ref": "#/responses/Container"
+ // "$ref": "#/responses/DocsListContainer"
// '400':
// "$ref": "#/responses/BadParamError"
// '500':
// "$ref": "#/responses/InternalError"
r.HandleFunc(VersionedPath("/containers/json"), APIHandler(s.Context, generic.ListContainers)).Methods(http.MethodGet)
// swagger:operation POST /containers/prune containers pruneContainers
- //
- // Prune unused containers
- //
// ---
+ // summary: Delete stopped containers
+ // description: Remove containers not in use
// parameters:
// - in: query
// name: filters
- // type: map[string][]string
- // description: something
+ // type: string
+ // description: |
+ // Filters to process on the prune list, encoded as JSON (a `map[string][]string`). Available filters:
+ // - `until=<timestamp>` Prune containers created before this timestamp. The `<timestamp>` can be Unix timestamps, date formatted timestamps, or Go duration strings (e.g. `10m`, `1h30m`) computed relative to the daemon machine’s time.
+ // - `label` (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) Prune containers with (or without, in case `label!=...` is used) the specified labels.
// produces:
// - application/json
// responses:
@@ -71,10 +87,8 @@ func (s *APIServer) RegisterContainersHandlers(r *mux.Router) error {
// "$ref": "#/responses/InternalError"
r.HandleFunc(VersionedPath("/containers/prune"), APIHandler(s.Context, generic.PruneContainers)).Methods(http.MethodPost)
// swagger:operation DELETE /containers/{nameOrID} containers removeContainer
- //
- // Delete container
- //
// ---
+ // summary: Remove a container
// parameters:
// - in: path
// name: nameOrID
@@ -83,11 +97,13 @@ func (s *APIServer) RegisterContainersHandlers(r *mux.Router) error {
// - in: query
// name: force
// type: bool
- // description: need something
+ // default: false
+ // description: If the container is running, kill it before removing it.
// - in: query
// name: v
// type: bool
- // description: need something
+ // default: false
+ // description: Remove the volumes associated with the container.
// - in: query
// name: link
// type: bool
@@ -107,15 +123,19 @@ func (s *APIServer) RegisterContainersHandlers(r *mux.Router) error {
// "$ref": "#/responses/InternalError"
r.HandleFunc(VersionedPath("/containers/{name:..*}"), APIHandler(s.Context, generic.RemoveContainer)).Methods(http.MethodDelete)
// swagger:operation GET /containers/{nameOrID}/json containers getContainer
- //
- // Inspect Container
- //
// ---
+ // summary: Inspect container
+ // description: Return low-level information about a container.
// parameters:
// - in: path
// name: nameOrID
// required: true
- // description: the name or ID of the container
+ // description: the name or id of the container
+ // - in: query
+ // name: size
+ // type: bool
+ // default: false
+ // description: include the size of the container
// produces:
// - application/json
// responses:
@@ -126,11 +146,10 @@ func (s *APIServer) RegisterContainersHandlers(r *mux.Router) error {
// '500':
// "$ref": "#/responses/InternalError"
r.HandleFunc(VersionedPath("/containers/{name:..*}/json"), APIHandler(s.Context, generic.GetContainer)).Methods(http.MethodGet)
- // swagger:operation POST /containers/{nameOrID}/kill containers killContainer
- //
- // Kill Container
- //
+ // swagger:operation post /containers/{nameOrID}/kill containers killcontainer
// ---
+ // summary: Kill container
+ // description: Signal to send to the container as an integer or string (e.g. SIGINT)
// parameters:
// - in: path
// name: nameOrID
@@ -153,10 +172,9 @@ func (s *APIServer) RegisterContainersHandlers(r *mux.Router) error {
// "$ref": "#/responses/InternalError"
r.HandleFunc(VersionedPath("/containers/{name:..*}/kill"), APIHandler(s.Context, generic.KillContainer)).Methods(http.MethodPost)
// swagger:operation GET /containers/{nameOrID}/logs containers LogsFromContainer
- //
- // Get logs from container
- //
// ---
+ // summary: Get container logs
+ // description: Get stdout and stderr logs from a container.
// parameters:
// - in: path
// name: nameOrID
@@ -165,46 +183,47 @@ func (s *APIServer) RegisterContainersHandlers(r *mux.Router) error {
// - in: query
// name: follow
// type: bool
- // description: needs description
+ // description: Keep connection after returning logs.
// - in: query
// name: stdout
// type: bool
- // description: needs description
+ // description: not supported
// - in: query
// name: stderr
// type: bool
- // description: needs description
+ // description: not supported?
// - in: query
// name: since
// type: string
- // description: needs description
+ // description: Only return logs since this time, as a UNIX timestamp
// - in: query
// name: until
// type: string
- // description: needs description
+ // description: Only return logs before this time, as a UNIX timestamp
// - in: query
// name: timestamps
// type: bool
- // description: needs description
+ // default: false
+ // description: Add timestamps to every log line
// - in: query
// name: tail
// type: string
- // description: needs description
+ // description: Only return this number of log lines from the end of the logs
+ // default: all
// produces:
// - application/json
// responses:
// '200':
- // description: tbd
+ // description: logs returned as a stream in response body.
// '404':
// "$ref": "#/responses/NoSuchContainer"
// '500':
// "$ref": "#/responses/InternalError"
r.HandleFunc(VersionedPath("/containers/{name:..*}/logs"), APIHandler(s.Context, generic.LogsFromContainer)).Methods(http.MethodGet)
// swagger:operation POST /containers/{nameOrID}/pause containers pauseContainer
- //
- // Pause Container
- //
// ---
+ // summary: Pause container
+ // description: Use the cgroups freezer to suspend all processes in a container.
// parameters:
// - in: path
// name: nameOrID
@@ -222,10 +241,8 @@ func (s *APIServer) RegisterContainersHandlers(r *mux.Router) error {
r.HandleFunc(VersionedPath("/containers/{name:..*}/pause"), APIHandler(s.Context, handlers.PauseContainer)).Methods(http.MethodPost)
r.HandleFunc(VersionedPath("/containers/{name:..*}/rename"), APIHandler(s.Context, handlers.UnsupportedHandler)).Methods(http.MethodPost)
// swagger:operation POST /containers/{nameOrID}/restart containers restartContainer
- //
- // Restart Container
- //
// ---
+ // summary: Restart container
// parameters:
// - in: path
// name: nameOrID
@@ -246,10 +263,8 @@ func (s *APIServer) RegisterContainersHandlers(r *mux.Router) error {
// "$ref": "#/responses/InternalError"
r.HandleFunc(VersionedPath("/containers/{name:..*}/restart"), APIHandler(s.Context, handlers.RestartContainer)).Methods(http.MethodPost)
// swagger:operation POST /containers/{nameOrID}/start containers startContainer
- //
- // Start a container
- //
// ---
+ // summary: Start a container
// parameters:
// - in: path
// name: nameOrID
@@ -272,10 +287,9 @@ func (s *APIServer) RegisterContainersHandlers(r *mux.Router) error {
// "$ref": "#/responses/InternalError"
r.HandleFunc(VersionedPath("/containers/{name:..*}/start"), APIHandler(s.Context, handlers.StartContainer)).Methods(http.MethodPost)
// swagger:operation GET /containers/{nameOrID}/stats containers statsContainer
- //
- // Get stats for a container
- //
// ---
+ // summary: Get stats for a container
+ // description: This returns a live stream of a container’s resource usage statistics.
// parameters:
// - in: path
// name: nameOrID
@@ -284,24 +298,21 @@ func (s *APIServer) RegisterContainersHandlers(r *mux.Router) error {
// - in: query
// name: stream
// type: bool
- // description: needs description
+ // default: true
+ // description: Stream the output
// produces:
// - application/json
// responses:
- // '204':
- // description: tbd
- // '304':
- // "$ref": "#/responses/ContainerAlreadyStartedError"
+ // '200':
+ // description: no error
// '404':
// "$ref": "#/responses/NoSuchContainer"
// '500':
// "$ref": "#/responses/InternalError"
r.HandleFunc(VersionedPath("/containers/{name:..*}/stats"), APIHandler(s.Context, generic.StatsContainer)).Methods(http.MethodGet)
// swagger:operation POST /containers/{nameOrID}/stop containers stopContainer
- //
- // Stop a container
- //
// ---
+ // summary: Stop a container
// parameters:
// - in: path
// name: nameOrID
@@ -324,10 +335,8 @@ func (s *APIServer) RegisterContainersHandlers(r *mux.Router) error {
// "$ref": "#/responses/InternalError"
r.HandleFunc(VersionedPath("/containers/{name:..*}/stop"), APIHandler(s.Context, handlers.StopContainer)).Methods(http.MethodPost)
// swagger:operation GET /containers/{nameOrID}/top containers topContainer
- //
- // List processes running inside a container
- //
// ---
+ // summary: List processes running inside a container
// parameters:
// - in: path
// name: nameOrID
@@ -348,10 +357,9 @@ func (s *APIServer) RegisterContainersHandlers(r *mux.Router) error {
// "$ref": "#/responses/InternalError"
r.HandleFunc(VersionedPath("/containers/{name:..*}/top"), APIHandler(s.Context, handlers.TopContainer)).Methods(http.MethodGet)
// swagger:operation POST /containers/{nameOrID}/unpause containers unpauseContainer
- //
- // Unpause Container
- //
// ---
+ // summary: Unpause container
+ // description: Resume a paused container
// parameters:
// - in: path
// name: nameOrID
@@ -362,17 +370,15 @@ func (s *APIServer) RegisterContainersHandlers(r *mux.Router) error {
// responses:
// '204':
// description: no error
- // schema:
// '404':
// "$ref": "#/responses/NoSuchContainer"
// '500':
// "$ref": "#/responses/InternalError"
r.HandleFunc(VersionedPath("/containers/{name:..*}/unpause"), APIHandler(s.Context, handlers.UnpauseContainer)).Methods(http.MethodPost)
// swagger:operation POST /containers/{nameOrID}/wait containers waitContainer
- //
- // Wait on a container to exit
- //
// ---
+ // summary: Wait on a container to exit
+ // description: Block until a container stops, then returns the exit code.
// parameters:
// - in: path
// name: nameOrID
@@ -385,8 +391,8 @@ func (s *APIServer) RegisterContainersHandlers(r *mux.Router) error {
// produces:
// - application/json
// responses:
- // '204':
- // description: no error
+ // '200':
+ // $ref: "#/responses/ContainerWaitResponse"
// '404':
// "$ref": "#/responses/NoSuchContainer"
// '500':
@@ -398,11 +404,10 @@ func (s *APIServer) RegisterContainersHandlers(r *mux.Router) error {
*/
r.HandleFunc(VersionedPath("/libpod/containers/create"), APIHandler(s.Context, libpod.CreateContainer)).Methods(http.MethodPost)
- // swagger:operation GET /libpod/containers/json containers listContainers
- //
- // List containers
- //
+ // swagger:operation GET /libpod/containers/json containers libpodListContainers
// ---
+ // summary: List containers
+ // description: Returns a list of containers
// produces:
// - application/json
// responses:
@@ -416,11 +421,10 @@ func (s *APIServer) RegisterContainersHandlers(r *mux.Router) error {
// '500':
// "$ref": "#/responses/InternalError"
r.HandleFunc(VersionedPath("/libpod/containers/json"), APIHandler(s.Context, libpod.ListContainers)).Methods(http.MethodGet)
- // swagger:operation POST /libpod/containers/prune containers pruneContainers
- //
- // Prune unused containers
- //
+ // swagger:operation POST /libpod/containers/prune containers libpodPruneContainers
// ---
+ // summary: Prune unused containers
+ // description: Remove stopped and exited containers
// parameters:
// - in: query
// name: force
@@ -428,21 +432,23 @@ func (s *APIServer) RegisterContainersHandlers(r *mux.Router) error {
// description: something
// - in: query
// name: filters
- // type: map[string][]string
- // description: something
+ // type: string
+ // description: |
+ // Filters to process on the prune list, encoded as JSON (a `map[string][]string`). Available filters:
+ // - `until=<timestamp>` Prune containers created before this timestamp. The `<timestamp>` can be Unix timestamps, date formatted timestamps, or Go duration strings (e.g. `10m`, `1h30m`) computed relative to the daemon machine’s time.
+ // - `label` (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) Prune containers with (or without, in case `label!=...` is used) the specified labels.
// produces:
// - application/json
// responses:
// '200':
- // description: TBD
+ // description: to be determined
// '500':
// "$ref": "#/responses/InternalError"
r.HandleFunc(VersionedPath("/libpod/containers/prune"), APIHandler(s.Context, libpod.PruneContainers)).Methods(http.MethodPost)
// swagger:operation GET /libpod/containers/showmounted containers showMounterContainers
- //
- // Show mounted containers
- //
// ---
+ // summary: Show mounted containers
+ // description: Lists all mounted containers mount points
// produces:
// - application/json
// responses:
@@ -455,11 +461,9 @@ func (s *APIServer) RegisterContainersHandlers(r *mux.Router) error {
// '500':
// "$ref": "#/responses/InternalError"
r.HandleFunc(VersionedPath("/libpod/containers/showmounted"), APIHandler(s.Context, libpod.ShowMountedContainers)).Methods(http.MethodGet)
- // swagger:operation DELETE /libpod/containers/json containers removeContainer
- //
- // Delete container
- //
+ // swagger:operation DELETE /libpod/containers/json containers libpodRemoveContainer
// ---
+ // summary: Delete container
// parameters:
// - in: path
// name: nameOrID
@@ -472,7 +476,7 @@ func (s *APIServer) RegisterContainersHandlers(r *mux.Router) error {
// - in: query
// name: v
// type: bool
- // description: need something
+ // description: delete volumes
// produces:
// - application/json
// responses:
@@ -487,11 +491,10 @@ func (s *APIServer) RegisterContainersHandlers(r *mux.Router) error {
// '500':
// "$ref": "#/responses/InternalError"
r.HandleFunc(VersionedPath("/libpod/containers/{name:..*}"), APIHandler(s.Context, libpod.RemoveContainer)).Methods(http.MethodDelete)
- // swagger:operation GET /libpod/containers/{nameOrID}/json containers getContainer
- //
- // Inspect Container
- //
+ // swagger:operation GET /libpod/containers/{nameOrID}/json containers libpodGetContainer
// ---
+ // summary: Inspect container
+ // description: Return low-level information about a container.
// parameters:
// - in: path
// name: nameOrID
@@ -511,11 +514,10 @@ func (s *APIServer) RegisterContainersHandlers(r *mux.Router) error {
// '500':
// "$ref": "#/responses/InternalError"
r.HandleFunc(VersionedPath("/libpod/containers/{name:..*}/json"), APIHandler(s.Context, libpod.GetContainer)).Methods(http.MethodGet)
- // swagger:operation POST /libpod/containers/{nameOrID}/kill containers killContainer
- //
- // Kill Container
- //
+ // swagger:operation POST /libpod/containers/{nameOrID}/kill containers libpodKillContainer
// ---
+ // summary: Kill container
+ // description: send a signal to a container, defaults to killing the container
// parameters:
// - in: path
// name: nameOrID
@@ -539,10 +541,9 @@ func (s *APIServer) RegisterContainersHandlers(r *mux.Router) error {
// "$ref": "#/responses/InternalError"
r.HandleFunc(VersionedPath("/libpod/containers/{name:..*}/kill"), APIHandler(s.Context, libpod.KillContainer)).Methods(http.MethodGet)
// swagger:operation GET /libpod/containers/{nameOrID}/mount containers mountContainer
- //
- // Mount a container
- //
// ---
+ // summary: Mount a container
+ // description: Mount a container to the filesystem
// parameters:
// - in: path
// name: nameOrID
@@ -563,11 +564,10 @@ func (s *APIServer) RegisterContainersHandlers(r *mux.Router) error {
// "$ref": "#/responses/InternalError"
r.HandleFunc(VersionedPath("/libpod/containers/{name:..*}/mount"), APIHandler(s.Context, libpod.MountContainer)).Methods(http.MethodPost)
r.HandleFunc(VersionedPath("/libpod/containers/{name:..*}/logs"), APIHandler(s.Context, libpod.LogsFromContainer)).Methods(http.MethodGet)
- // swagger:operation POST /libpod/containers/{nameOrID}/pause containers pauseContainer
- //
- // Pause Container
- //
+ // swagger:operation POST /libpod/containers/{nameOrID}/pause containers libpodPauseContainer
// ---
+ // summary: Pause a container
+ // description: Use the cgroups freezer to suspend all processes in a container.
// parameters:
// - in: path
// name: nameOrID
@@ -583,11 +583,9 @@ func (s *APIServer) RegisterContainersHandlers(r *mux.Router) error {
// '500':
// "$ref": "#/responses/InternalError"
r.HandleFunc(VersionedPath("/libpod/containers/{name:..*}/pause"), APIHandler(s.Context, handlers.PauseContainer)).Methods(http.MethodPost)
- // swagger:operation POST /libpod/containers/{nameOrID}/restart containers restartContainer
- //
- // Restart Container
- //
+ // swagger:operation POST /libpod/containers/{nameOrID}/restart containers libpodRestartContainer
// ---
+ // summary: Restart a container
// parameters:
// - in: path
// name: nameOrID
@@ -607,11 +605,9 @@ func (s *APIServer) RegisterContainersHandlers(r *mux.Router) error {
// '500':
// "$ref": "#/responses/InternalError"
r.HandleFunc(VersionedPath("/libpod/containers/{name:..*}/restart"), APIHandler(s.Context, handlers.RestartContainer)).Methods(http.MethodPost)
- // swagger:operation POST /libpod/containers/{nameOrID}/start containers startContainer
- //
- // Start a container
- //
+ // swagger:operation POST /libpod/containers/{nameOrID}/start containers libpodStartContainer
// ---
+ // summary: Start a container
// parameters:
// - in: path
// name: nameOrID
@@ -635,11 +631,9 @@ func (s *APIServer) RegisterContainersHandlers(r *mux.Router) error {
r.HandleFunc(VersionedPath("/libpod/containers/{name:..*}/start"), APIHandler(s.Context, handlers.StartContainer)).Methods(http.MethodPost)
r.HandleFunc(VersionedPath("/libpod/containers/{name:..*}/stats"), APIHandler(s.Context, libpod.StatsContainer)).Methods(http.MethodGet)
r.HandleFunc(VersionedPath("/libpod/containers/{name:..*}/top"), APIHandler(s.Context, handlers.TopContainer)).Methods(http.MethodGet)
- // swagger:operation POST /libpod/containers/{nameOrID}/unpause containers unpauseContainer
- //
- // Unpause Container
- //
+ // swagger:operation POST /libpod/containers/{nameOrID}/unpause containers libpodUnpauseContainer
// ---
+ // summary: Unpause Container
// parameters:
// - in: path
// name: nameOrID
@@ -655,11 +649,9 @@ func (s *APIServer) RegisterContainersHandlers(r *mux.Router) error {
// '500':
// "$ref": "#/responses/InternalError"
r.HandleFunc(VersionedPath("/libpod/containers/{name:..*}/unpause"), APIHandler(s.Context, handlers.UnpauseContainer)).Methods(http.MethodPost)
- // swagger:operation POST /libpod/containers/{nameOrID}/wait containers waitContainer
- //
- // Wait on a container to exit
- //
+ // swagger:operation POST /libpod/containers/{nameOrID}/wait containers libpodWaitContainer
// ---
+ // summary: Wait on a container to exit
// parameters:
// - in: path
// name: nameOrID
@@ -680,10 +672,9 @@ func (s *APIServer) RegisterContainersHandlers(r *mux.Router) error {
// "$ref": "#/responses/InternalError"
r.HandleFunc(VersionedPath("/libpod/containers/{name:..*}/wait"), APIHandler(s.Context, libpod.WaitContainer)).Methods(http.MethodPost)
// swagger:operation POST /libpod/containers/{nameOrID}/exists containers containerExists
- //
- // Check if container exists
- //
// ---
+ // summary: Check if container exists
+ // description: Quick way to determine if a container exists by name or ID
// parameters:
// - in: path
// name: nameOrID
@@ -699,11 +690,9 @@ func (s *APIServer) RegisterContainersHandlers(r *mux.Router) error {
// '500':
// "$ref": "#/responses/InternalError"
r.HandleFunc(VersionedPath("/libpod/containers/{name:..*}/exists"), APIHandler(s.Context, libpod.ContainerExists)).Methods(http.MethodGet)
- // swagger:operation POST /libpod/containers/{nameOrID}/stop containers stopContainer
- //
- // Stop a container
- //
+ // swagger:operation POST /libpod/containers/{nameOrID}/stop containers libpodStopContainer
// ---
+ // summary: Stop a container
// parameters:
// - in: path
// name: nameOrID
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2025-01-11 12:38:55 +0000