diff --git a/api/swagger.yaml b/api/swagger.yaml index 940506be32..d79b2348af 100644 --- a/api/swagger.yaml +++ b/api/swagger.yaml @@ -1118,11 +1118,15 @@ definitions: PluginMount: type: "object" + x-nullable: false + required: [Name, Description, Settable, Source, Destination, Type, Options] properties: Name: type: "string" + x-nullable: false Description: type: "string" + x-nullable: false Settable: type: "array" items: @@ -1131,8 +1135,10 @@ definitions: type: "string" Destination: type: "string" + x-nullable: false Type: type: "string" + x-nullable: false Options: type: "array" items: @@ -1140,11 +1146,15 @@ definitions: PluginDevice: type: "object" + required: [Name, Description, Settable, Path] + x-nullable: false properties: Name: type: "string" + x-nullable: false Description: type: "string" + x-nullable: false Settable: type: "array" items: @@ -1152,22 +1162,61 @@ definitions: Path: type: "string" + PluginEnv: + type: "object" + x-nullable: false + required: [Name, Description, Settable, Value] + properties: + Name: + x-nullable: false + type: "string" + Description: + x-nullable: false + type: "string" + Settable: + type: "array" + items: + type: "string" + Value: + type: "string" + + PluginInterfaceType: + type: "object" + x-nullable: false + required: [Prefix, Capability, Version] + properties: + Prefix: + type: "string" + x-nullable: false + Capability: + type: "string" + x-nullable: false + Version: + type: "string" + x-nullable: false + Plugin: description: "A plugin for the Remote API" type: "object" + required: [Config, Enabled, Manifest, Name, Tag] properties: Id: type: "string" Name: type: "string" + x-nullable: false Tag: type: "string" + x-nullable: false Enabled: description: "True when the plugin is running. False when the plugin is not running, only installed." type: "boolean" + x-nullable: false Config: description: "Settings that can be modified by users." type: "object" + x-nullable: false + required: [Args, Devices, Env, Mounts] properties: Mounts: type: "array" @@ -1188,40 +1237,67 @@ definitions: Manifest: description: "The manifest of a plugin." type: "object" + x-nullable: false + required: + - ManifestVersion + - Description + - Documentation + - Interface + - Entrypoint + - Workdir + - Network + - Capabilities + - Mounts + - Devices + - Env + - Args properties: ManifestVersion: type: "string" + x-nullable: false Description: type: "string" + x-nullable: false Documentation: type: "string" + x-nullable: false Interface: description: "The interface between Docker and the plugin" + x-nullable: false type: "object" + required: [Types, Socket] properties: Types: type: "array" items: - type: "string" + $ref: "#/definitions/PluginInterfaceType" Socket: type: "string" + x-nullable: false Entrypoint: type: "array" items: type: "string" Workdir: type: "string" + x-nullable: false User: type: "object" + x-nullable: false properties: UID: type: "integer" + format: "uint32" GID: type: "integer" + format: "uint32" Network: type: "object" + x-nullable: false + required: [Type] properties: Type: + x-nullable: false type: "string" Capabilities: type: "array" @@ -1236,24 +1312,19 @@ definitions: items: $ref: "#/definitions/PluginDevice" Env: - type: "object" - properties: - Name: - type: "string" - Description: - type: "string" - Settable: - type: "array" - items: - type: "string" - Value: - type: "string" + type: "array" + items: + $ref: "#/definitions/PluginEnv" Args: type: "object" + x-nullable: false + required: [Name, Description, Settable, Value] properties: Name: + x-nullable: false type: "string" Description: + x-nullable: false type: "string" Settable: type: "array" diff --git a/api/types/client.go b/api/types/client.go index 8bd1cd47fa..13ba5f4d1e 100644 --- a/api/types/client.go +++ b/api/types/client.go @@ -314,3 +314,12 @@ type TaskListOptions struct { type PluginRemoveOptions struct { Force bool } + +// PluginInstallOptions holds parameters to install a plugin. +type PluginInstallOptions struct { + Disabled bool + AcceptAllPermissions bool + RegistryAuth string // RegistryAuth is the base64 encoded credentials for the registry + PrivilegeFunc RequestPrivilegeFunc + AcceptPermissionsFunc func(PluginPrivileges) (bool, error) +} diff --git a/api/types/plugin.go b/api/types/plugin.go index 11091ef274..66a7877768 100644 --- a/api/types/plugin.go +++ b/api/types/plugin.go @@ -1,168 +1,163 @@ package types -import ( - "encoding/json" - "fmt" -) +// This file was generated by the swagger tool. +// Editing this file might prove futile when you re-run the swagger generate command -// PluginInstallOptions holds parameters to install a plugin. -type PluginInstallOptions struct { - Disabled bool - AcceptAllPermissions bool - RegistryAuth string // RegistryAuth is the base64 encoded credentials for the registry - PrivilegeFunc RequestPrivilegeFunc - AcceptPermissionsFunc func(PluginPrivileges) (bool, error) -} - -// PluginConfig represents the values of settings potentially modifiable by a user -type PluginConfig struct { - Mounts []PluginMount - Env []string - Args []string - Devices []PluginDevice -} - -// Plugin represents a Docker plugin for the remote API +// Plugin A plugin for the Remote API +// swagger:model Plugin type Plugin struct { - ID string `json:"Id,omitempty"` - Name string - Tag string - // Enabled is true when the plugin is running, is false when the plugin is not running, only installed. - Enabled bool - Config PluginConfig - Manifest PluginManifest + + // config + // Required: true + Config PluginConfig `json:"Config"` + + // True when the plugin is running. False when the plugin is not running, only installed. + // Required: true + Enabled bool `json:"Enabled"` + + // Id + ID string `json:"Id,omitempty"` + + // manifest + // Required: true + Manifest PluginManifest `json:"Manifest"` + + // name + // Required: true + Name string `json:"Name"` + + // tag + // Required: true + Tag string `json:"Tag"` } -// PluginsListResponse contains the response for the remote API -type PluginsListResponse []*Plugin +// PluginConfigSettings that can be modified by users. +// swagger:model PluginConfig +type PluginConfig struct { -const ( - authzDriver = "AuthzDriver" - graphDriver = "GraphDriver" - ipamDriver = "IpamDriver" - networkDriver = "NetworkDriver" - volumeDriver = "VolumeDriver" -) + // args + // Required: true + Args []string `json:"Args"` -// PluginInterfaceType represents a type that a plugin implements. -type PluginInterfaceType struct { - Prefix string // This is always "docker" - Capability string // Capability should be validated against the above list. - Version string // Plugin API version. Depends on the capability + // devices + // Required: true + Devices []PluginDevice `json:"Devices"` + + // env + // Required: true + Env []string `json:"Env"` + + // mounts + // Required: true + Mounts []PluginMount `json:"Mounts"` } -// UnmarshalJSON implements json.Unmarshaler for PluginInterfaceType -func (t *PluginInterfaceType) UnmarshalJSON(p []byte) error { - versionIndex := len(p) - prefixIndex := 0 - if len(p) < 2 || p[0] != '"' || p[len(p)-1] != '"' { - return fmt.Errorf("%q is not a plugin interface type", p) - } - p = p[1 : len(p)-1] -loop: - for i, b := range p { - switch b { - case '.': - prefixIndex = i - case '/': - versionIndex = i - break loop - } - } - t.Prefix = string(p[:prefixIndex]) - t.Capability = string(p[prefixIndex+1 : versionIndex]) - if versionIndex < len(p) { - t.Version = string(p[versionIndex+1:]) - } - return nil -} - -// MarshalJSON implements json.Marshaler for PluginInterfaceType -func (t *PluginInterfaceType) MarshalJSON() ([]byte, error) { - return json.Marshal(t.String()) -} - -// String implements fmt.Stringer for PluginInterfaceType -func (t PluginInterfaceType) String() string { - return fmt.Sprintf("%s.%s/%s", t.Prefix, t.Capability, t.Version) -} - -// PluginInterface describes the interface between Docker and plugin -type PluginInterface struct { - Types []PluginInterfaceType - Socket string -} - -// PluginSetting is to be embedded in other structs, if they are supposed to be -// modifiable by the user. -type PluginSetting struct { - Name string - Description string - Settable []string -} - -// PluginNetwork represents the network configuration for a plugin -type PluginNetwork struct { - Type string -} - -// PluginMount represents the mount configuration for a plugin -type PluginMount struct { - PluginSetting - Source *string - Destination string - Type string - Options []string -} - -// PluginEnv represents an environment variable for a plugin -type PluginEnv struct { - PluginSetting - Value *string -} - -// PluginArgs represents the command line arguments for a plugin -type PluginArgs struct { - PluginSetting - Value []string -} - -// PluginDevice represents a device for a plugin -type PluginDevice struct { - PluginSetting - Path *string -} - -// PluginUser represents the user for the plugin's process -type PluginUser struct { - UID uint32 `json:"Uid,omitempty"` - GID uint32 `json:"Gid,omitempty"` -} - -// PluginManifest represents the manifest of a plugin +// PluginManifestThe manifest of a plugin. +// swagger:model PluginManifest type PluginManifest struct { - ManifestVersion string - Description string - Documentation string - Interface PluginInterface - Entrypoint []string - Workdir string - User PluginUser `json:",omitempty"` - Network PluginNetwork - Capabilities []string - Mounts []PluginMount - Devices []PluginDevice - Env []PluginEnv - Args PluginArgs + + // args + // Required: true + Args PluginManifestArgs `json:"Args"` + + // capabilities + // Required: true + Capabilities []string `json:"Capabilities"` + + // description + // Required: true + Description string `json:"Description"` + + // devices + // Required: true + Devices []PluginDevice `json:"Devices"` + + // documentation + // Required: true + Documentation string `json:"Documentation"` + + // entrypoint + // Required: true + Entrypoint []string `json:"Entrypoint"` + + // env + // Required: true + Env []PluginEnv `json:"Env"` + + // interface + // Required: true + Interface PluginManifestInterface `json:"Interface"` + + // manifest version + // Required: true + ManifestVersion string `json:"ManifestVersion"` + + // mounts + // Required: true + Mounts []PluginMount `json:"Mounts"` + + // network + // Required: true + Network PluginManifestNetwork `json:"Network"` + + // user + User PluginManifestUser `json:"User,omitempty"` + + // workdir + // Required: true + Workdir string `json:"Workdir"` } -// PluginPrivilege describes a permission the user has to accept -// upon installing a plugin. -type PluginPrivilege struct { - Name string - Description string - Value []string +// PluginManifestArgsplugin manifest args +// swagger:model PluginManifestArgs +type PluginManifestArgs struct { + + // description + // Required: true + Description string `json:"Description"` + + // name + // Required: true + Name string `json:"Name"` + + // settable + // Required: true + Settable []string `json:"Settable"` + + // value + // Required: true + Value []string `json:"Value"` } -// PluginPrivileges is a list of PluginPrivilege -type PluginPrivileges []PluginPrivilege +// PluginManifestInterfaceThe interface between Docker and the plugin +// swagger:model PluginManifestInterface +type PluginManifestInterface struct { + + // socket + // Required: true + Socket string `json:"Socket"` + + // types + // Required: true + Types []PluginInterfaceType `json:"Types"` +} + +// PluginManifestNetworkplugin manifest network +// swagger:model PluginManifestNetwork +type PluginManifestNetwork struct { + + // type + // Required: true + Type string `json:"Type"` +} + +// PluginManifestUserplugin manifest user +// swagger:model PluginManifestUser +type PluginManifestUser struct { + + // g ID + GID uint32 `json:"GID,omitempty"` + + // UID + UID uint32 `json:"UID,omitempty"` +} diff --git a/api/types/plugin_device.go b/api/types/plugin_device.go new file mode 100644 index 0000000000..5699010675 --- /dev/null +++ b/api/types/plugin_device.go @@ -0,0 +1,25 @@ +package types + +// This file was generated by the swagger tool. +// Editing this file might prove futile when you re-run the swagger generate command + +// PluginDevice plugin device +// swagger:model PluginDevice +type PluginDevice struct { + + // description + // Required: true + Description string `json:"Description"` + + // name + // Required: true + Name string `json:"Name"` + + // path + // Required: true + Path *string `json:"Path"` + + // settable + // Required: true + Settable []string `json:"Settable"` +} diff --git a/api/types/plugin_env.go b/api/types/plugin_env.go new file mode 100644 index 0000000000..32962dc2eb --- /dev/null +++ b/api/types/plugin_env.go @@ -0,0 +1,25 @@ +package types + +// This file was generated by the swagger tool. +// Editing this file might prove futile when you re-run the swagger generate command + +// PluginEnv plugin env +// swagger:model PluginEnv +type PluginEnv struct { + + // description + // Required: true + Description string `json:"Description"` + + // name + // Required: true + Name string `json:"Name"` + + // settable + // Required: true + Settable []string `json:"Settable"` + + // value + // Required: true + Value *string `json:"Value"` +} diff --git a/api/types/plugin_interface_type.go b/api/types/plugin_interface_type.go new file mode 100644 index 0000000000..c82f204e87 --- /dev/null +++ b/api/types/plugin_interface_type.go @@ -0,0 +1,21 @@ +package types + +// This file was generated by the swagger tool. +// Editing this file might prove futile when you re-run the swagger generate command + +// PluginInterfaceType plugin interface type +// swagger:model PluginInterfaceType +type PluginInterfaceType struct { + + // capability + // Required: true + Capability string `json:"Capability"` + + // prefix + // Required: true + Prefix string `json:"Prefix"` + + // version + // Required: true + Version string `json:"Version"` +} diff --git a/api/types/plugin_mount.go b/api/types/plugin_mount.go new file mode 100644 index 0000000000..5c031cf8b5 --- /dev/null +++ b/api/types/plugin_mount.go @@ -0,0 +1,37 @@ +package types + +// This file was generated by the swagger tool. +// Editing this file might prove futile when you re-run the swagger generate command + +// PluginMount plugin mount +// swagger:model PluginMount +type PluginMount struct { + + // description + // Required: true + Description string `json:"Description"` + + // destination + // Required: true + Destination string `json:"Destination"` + + // name + // Required: true + Name string `json:"Name"` + + // options + // Required: true + Options []string `json:"Options"` + + // settable + // Required: true + Settable []string `json:"Settable"` + + // source + // Required: true + Source *string `json:"Source"` + + // type + // Required: true + Type string `json:"Type"` +} diff --git a/api/types/plugin_responses.go b/api/types/plugin_responses.go new file mode 100644 index 0000000000..8ef07d7fd0 --- /dev/null +++ b/api/types/plugin_responses.go @@ -0,0 +1,64 @@ +package types + +import ( + "encoding/json" + "fmt" +) + +// PluginsListResponse contains the response for the remote API +type PluginsListResponse []*Plugin + +const ( + authzDriver = "AuthzDriver" + graphDriver = "GraphDriver" + ipamDriver = "IpamDriver" + networkDriver = "NetworkDriver" + volumeDriver = "VolumeDriver" +) + +// UnmarshalJSON implements json.Unmarshaler for PluginInterfaceType +func (t *PluginInterfaceType) UnmarshalJSON(p []byte) error { + versionIndex := len(p) + prefixIndex := 0 + if len(p) < 2 || p[0] != '"' || p[len(p)-1] != '"' { + return fmt.Errorf("%q is not a plugin interface type", p) + } + p = p[1 : len(p)-1] +loop: + for i, b := range p { + switch b { + case '.': + prefixIndex = i + case '/': + versionIndex = i + break loop + } + } + t.Prefix = string(p[:prefixIndex]) + t.Capability = string(p[prefixIndex+1 : versionIndex]) + if versionIndex < len(p) { + t.Version = string(p[versionIndex+1:]) + } + return nil +} + +// MarshalJSON implements json.Marshaler for PluginInterfaceType +func (t *PluginInterfaceType) MarshalJSON() ([]byte, error) { + return json.Marshal(t.String()) +} + +// String implements fmt.Stringer for PluginInterfaceType +func (t PluginInterfaceType) String() string { + return fmt.Sprintf("%s.%s/%s", t.Prefix, t.Capability, t.Version) +} + +// PluginPrivilege describes a permission the user has to accept +// upon installing a plugin. +type PluginPrivilege struct { + Name string + Description string + Value []string +} + +// PluginPrivileges is a list of PluginPrivilege +type PluginPrivileges []PluginPrivilege diff --git a/hack/generate-swagger-api.sh b/hack/generate-swagger-api.sh index 4e1e32dac7..c33900eb04 100755 --- a/hack/generate-swagger-api.sh +++ b/hack/generate-swagger-api.sh @@ -5,4 +5,5 @@ swagger generate model -f api/swagger.yaml \ -t api -m types --skip-validator \ -n Volume \ -n Port \ - -n ImageSummary + -n ImageSummary \ + -n Plugin -n PluginDevice -n PluginMount -n PluginEnv -n PluginInterfaceType