Merge pull request #5061 from baude/apiv2swaggerexec

[CI:DOCS]add apiv2 endpoints for exec

pkg/api/handlers/exec.go

@@ -0,0 +1,25 @@
+package handlers
+
+import (
+	"net/http"
+
+	"github.com/containers/libpod/libpod/define"
+	"github.com/containers/libpod/pkg/api/handlers/utils"
+)
+
+func CreateExec(w http.ResponseWriter, r *http.Request) {
+	utils.Error(w, "function not implemented", http.StatusInternalServerError, define.ErrNotImplemented)
+}
+
+func StartExec(w http.ResponseWriter, r *http.Request) {
+	utils.Error(w, "function not implemented", http.StatusInternalServerError, define.ErrNotImplemented)
+}
+
+func ResizeExec(w http.ResponseWriter, r *http.Request) {
+	utils.Error(w, "function not implemented", http.StatusInternalServerError, define.ErrNotImplemented)
+
+}
+
+func InspectExec(w http.ResponseWriter, r *http.Request) {
+	utils.Error(w, "function not implemented", http.StatusInternalServerError, define.ErrNotImplemented)
+}

pkg/api/server/register_exec.go

@@ -0,0 +1,329 @@
+package server
+
+import (
+	"net/http"
+
+	"github.com/containers/libpod/pkg/api/handlers"
+	"github.com/gorilla/mux"
+)
+
+func (s *APIServer) registerExecHandlers(r *mux.Router) error {
+	// swagger:operation POST /containers/{name}/create compat createExec
+	// ---
+	// tags:
+	//   - exec (compat)
+	// summary: Create an exec instance
+	// description: Run a command inside a running container.
+	// parameters:
+	//  - in: path
+	//    name: name
+	//    type: string
+	//    required: true
+	//    description: name of container
+	//  - in: body
+	//    name: control
+	//    description: Attributes for create
+	//    schema:
+	//      type: object
+	//      properties:
+	//        AttachStdin:
+	//          type: boolean
+	//          description: Attach to stdin of the exec command
+	//        AttachStdout:
+	//          type: boolean
+	//          description: Attach to stdout of the exec command
+	//        AttachStderr:
+	//          type: boolean
+	//          description: Attach to stderr of the exec command
+	//        DetachKeys:
+	//          type: string
+	//          description: |
+	//           "Override the key sequence for detaching a container. Format is a single character [a-Z] or ctrl-<value> where <value> is one of: a-z, @, ^, [, , or _."
+	//        Tty:
+	//          type: boolean
+	//          description: Allocate a pseudo-TTY
+	//        Env:
+	//          type: array
+	//          description: A list of environment variables in the form ["VAR=value", ...]
+	//          items:
+	//            type: string
+	//        Cmd:
+	//          type: array
+	//          description: Command to run, as a string or array of strings.
+	//          items:
+	//            type: string
+	//        Privileged:
+	//          type: boolean
+	//          default: false
+	//          description: Runs the exec process with extended privileges
+	//        User:
+	//          type: string
+	//          description: |
+	//           "The user, and optionally, group to run the exec process inside the container. Format is one of: user, user:group, uid, or uid:gid."
+	//        WorkingDir:
+	//          type: string
+	//          description: The working directory for the exec process inside the container.
+	// produces:
+	// - application/json
+	// responses:
+	//   201:
+	//     description: no error
+	//   404:
+	//     $ref: "#/responses/NoSuchContainer"
+	//   409:
+	//	   description: container is paused
+	//   500:
+	//     $ref: "#/responses/InternalError"
+	r.Handle(VersionedPath("/containers/{name}/create"), APIHandler(s.Context, handlers.CreateExec)).Methods(http.MethodPost)
+	// swagger:operation POST /exec/{id}/start compat startExec
+	// ---
+	// tags:
+	//   - exec (compat)
+	// summary: Start an exec instance
+	// description: Starts a previously set up exec instance. If detach is true, this endpoint returns immediately after starting the command. Otherwise, it sets up an interactive session with the command.
+	// parameters:
+	//  - in: path
+	//    name: id
+	//    type: string
+	//    required: true
+	//    description: Exec instance ID
+	//  - in: body
+	//    name: control
+	//    description: Attributes for start
+	//    schema:
+	//      type: object
+	//      properties:
+	//        Detach:
+	//          type: boolean
+	//          description: Detach from the command
+	//        Tty:
+	//          type: boolean
+	//          description: Allocate a pseudo-TTY
+	// produces:
+	// - application/json
+	// responses:
+	//   200:
+	//     description: no error
+	//   404:
+	//     $ref: "#/responses/NoSuchExecInstance"
+	//   409:
+	//	   description: container is stopped or paused
+	//   500:
+	//     $ref: "#/responses/InternalError"
+	r.Handle(VersionedPath("/exec/{id}/start"), APIHandler(s.Context, handlers.StartExec)).Methods(http.MethodPost)
+	// swagger:operation POST /exec/{id}/resize compat resizeExec
+	// ---
+	// tags:
+	//   - exec (compat)
+	// summary: Resize an exec instance
+	// description: |
+	//  Resize the TTY session used by an exec instance. This endpoint only works if tty was specified as part of creating and starting the exec instance.
+	// parameters:
+	//  - in: path
+	//    name: id
+	//    type: string
+	//    required: true
+	//    description: Exec instance ID
+	//  - in: query
+	//    name: h
+	//    type: integer
+	//    description: Height of the TTY session in characters
+	//  - in: query
+	//    name: w
+	//    type: integer
+	//    description: Width of the TTY session in characters
+	// produces:
+	// - application/json
+	// responses:
+	//   201:
+	//     description: no error
+	//   404:
+	//     $ref: "#/responses/NoSuchExecInstance"
+	//   500:
+	//     $ref: "#/responses/InternalError"
+	r.Handle(VersionedPath("/exec/{id}/resize"), APIHandler(s.Context, handlers.ResizeExec)).Methods(http.MethodPost)
+	// swagger:operation GET /exec/{id}/inspect compat inspectExec
+	// ---
+	// tags:
+	//   - exec (compat)
+	// summary: Inspect an exec instance
+	// description: Return low-level information about an exec instance.
+	// parameters:
+	//  - in: path
+	//    name: id
+	//    type: string
+	//    required: true
+	//    description: Exec instance ID
+	// produces:
+	// - application/json
+	// responses:
+	//   200:
+	//     description: no error
+	//   404:
+	//     $ref: "#/responses/NoSuchExecInstance"
+	//   500:
+	//     $ref: "#/responses/InternalError"
+	r.Handle(VersionedPath("/exec/{id}/json"), APIHandler(s.Context, handlers.InspectExec)).Methods(http.MethodGet)
+
+	/*
+		libpod api follows
+	*/
+
+	// swagger:operation POST /libpod/containers/{name}/create libpod libpodCreateExec
+	// ---
+	// tags:
+	//   - exec
+	// summary: Create an exec instance
+	// description: Run a command inside a running container.
+	// parameters:
+	//  - in: path
+	//    name: name
+	//    type: string
+	//    required: true
+	//    description: name of container
+	//  - in: body
+	//    name: control
+	//    description: Attributes for create
+	//    schema:
+	//      type: object
+	//      properties:
+	//        AttachStdin:
+	//          type: boolean
+	//          description: Attach to stdin of the exec command
+	//        AttachStdout:
+	//          type: boolean
+	//          description: Attach to stdout of the exec command
+	//        AttachStderr:
+	//          type: boolean
+	//          description: Attach to stderr of the exec command
+	//        DetachKeys:
+	//          type: string
+	//          description: |
+	//           "Override the key sequence for detaching a container. Format is a single character [a-Z] or ctrl-<value> where <value> is one of: a-z, @, ^, [, , or _."
+	//        Tty:
+	//          type: boolean
+	//          description: Allocate a pseudo-TTY
+	//        Env:
+	//          type: array
+	//          description: A list of environment variables in the form ["VAR=value", ...]
+	//          items:
+	//            type: string
+	//        Cmd:
+	//          type: array
+	//          description: Command to run, as a string or array of strings.
+	//          items:
+	//            type: string
+	//        Privileged:
+	//          type: boolean
+	//          default: false
+	//          description: Runs the exec process with extended privileges
+	//        User:
+	//          type: string
+	//          description: |
+	//           "The user, and optionally, group to run the exec process inside the container. Format is one of: user, user:group, uid, or uid:gid."
+	//        WorkingDir:
+	//          type: string
+	//          description: The working directory for the exec process inside the container.
+	// produces:
+	// - application/json
+	// responses:
+	//   201:
+	//     description: no error
+	//   404:
+	//     $ref: "#/responses/NoSuchContainer"
+	//   409:
+	//	   description: container is paused
+	//   500:
+	//     $ref: "#/responses/InternalError"
+	r.Handle(VersionedPath("/libpod/containers/{name}/create"), APIHandler(s.Context, handlers.CreateExec)).Methods(http.MethodPost)
+	// swagger:operation POST /libpod/exec/{id}/start libpod libpodStartExec
+	// ---
+	// tags:
+	//   - exec
+	// summary: Start an exec instance
+	// description: Starts a previously set up exec instance. If detach is true, this endpoint returns immediately after starting the command. Otherwise, it sets up an interactive session with the command.
+	// parameters:
+	//  - in: path
+	//    name: id
+	//    type: string
+	//    required: true
+	//    description: Exec instance ID
+	//  - in: body
+	//    name: control
+	//    description: Attributes for start
+	//    schema:
+	//      type: object
+	//      properties:
+	//        Detach:
+	//          type: boolean
+	//          description: Detach from the command
+	//        Tty:
+	//          type: boolean
+	//          description: Allocate a pseudo-TTY
+	// produces:
+	// - application/json
+	// responses:
+	//   200:
+	//     description: no error
+	//   404:
+	//     $ref: "#/responses/NoSuchExecInstance"
+	//   409:
+	//	   description: container is stopped or paused
+	//   500:
+	//     $ref: "#/responses/InternalError"
+	r.Handle(VersionedPath("/libpod/exec/{id}/start"), APIHandler(s.Context, handlers.StartExec)).Methods(http.MethodPost)
+	// swagger:operation POST /libpod/exec/{id}/resize libpod libpodResizeExec
+	// ---
+	// tags:
+	//   - exec
+	// summary: Resize an exec instance
+	// description: |
+	//  Resize the TTY session used by an exec instance. This endpoint only works if tty was specified as part of creating and starting the exec instance.
+	// parameters:
+	//  - in: path
+	//    name: id
+	//    type: string
+	//    required: true
+	//    description: Exec instance ID
+	//  - in: query
+	//    name: h
+	//    type: integer
+	//    description: Height of the TTY session in characters
+	//  - in: query
+	//    name: w
+	//    type: integer
+	//    description: Width of the TTY session in characters
+	// produces:
+	// - application/json
+	// responses:
+	//   201:
+	//     description: no error
+	//   404:
+	//     $ref: "#/responses/NoSuchExecInstance"
+	//   500:
+	//     $ref: "#/responses/InternalError"
+	r.Handle(VersionedPath("/libpod/exec/{id}/resize"), APIHandler(s.Context, handlers.ResizeExec)).Methods(http.MethodPost)
+	// swagger:operation GET /libpod/exec/{id}/inspect libpod libpodInspectExec
+	// ---
+	// tags:
+	//   - exec
+	// summary: Inspect an exec instance
+	// description: Return low-level information about an exec instance.
+	// parameters:
+	//  - in: path
+	//    name: id
+	//    type: string
+	//    required: true
+	//    description: Exec instance ID
+	// produces:
+	// - application/json
+	// responses:
+	//   200:
+	//     description: no error
+	//   404:
+	//     $ref: "#/responses/NoSuchExecInstance"
+	//   500:
+	//     $ref: "#/responses/InternalError"
+	r.Handle(VersionedPath("/libpod/exec/{id}/json"), APIHandler(s.Context, handlers.InspectExec)).Methods(http.MethodGet)
+	return nil
+}

pkg/api/server/server.go

@@ -105,6 +105,7 @@ func newServer(runtime *libpod.Runtime, duration time.Duration, listener *net.Li
 		server.RegisterAuthHandlers,
 		server.RegisterContainersHandlers,
 		server.RegisterDistributionHandlers,
+		server.registerExecHandlers,
 		server.registerHealthCheckHandlers,
 		server.registerImagesHandlers,
 		server.registerInfoHandlers,

pkg/api/server/swagger.go

@@ -23,6 +23,15 @@ type swagErrNoSuchContainer struct {
 	}
 }
 
+// No such exec instance
+// swagger:response NoSuchExecInstance
+type swagErrNoSuchExecInstance struct {
+	// in:body
+	Body struct {
+		utils.ErrorModel
+	}
+}
+
 // No such volume
 // swagger:response NoSuchVolume
 type swagErrNoSuchVolume struct {

pkg/api/tags.yaml

@@ -1,6 +1,8 @@
 tags:
     - name: containers
       description: Actions related to containers
+    - name: exec
+      description: Actions related to exec
     - name: images
       description: Actions related to images
     - name: pods
@@ -11,6 +13,8 @@ tags:
       description: Actions related to Podman engine
     - name: containers (compat)
       description: Actions related to containers for the compatibility endpoints
+    - name: exec (compat)
+      description: Actions related to exec for the compatibility endpoints
     - name: images (compat)
       description: Actions related to images for the compatibility endpoints
     - name: system (compat)