api/services: define the introspection API

After several requests for information about platform support,
configuration introspection and feature switches, we now have a solution
that should work in all these use cases. The Introspection API hooks
into the plugin subsystem registration process. During registration,
plugins declare several pieces of information, allowing clients to
discover the cababilities and support that a containerd instance
provides, including whether or not it loaded with an error.

To allow symmetrical error reporting, the `google/rpc.Status` protobuf
definitions have been brought in from the googleapis project.
Unfortunately, we had to generate these in place to match our protobuf
system.

Once we like this design, we can add an implementation to integrate it
directly with the plugin system.

Enjoy!

Signed-off-by: Stephen J Day <stephen.day@docker.com>

Author: stevvooe

Makefile

@@ -87,7 +87,7 @@ check-protos: protos ## check if protobufs needs to be generated again
 	@echo "$(WHALE) $@"
 	@test -z "$$(git status --short | grep ".pb.go" | tee /dev/stderr)" || \
 		((git diff | cat) && \
-		(echo "$(ONI) please run 'make generate' when making changes to proto files" && false))
+		(echo "$(ONI) please run 'make protos' when making changes to proto files" && false))
 
 check-api-descriptors: protos ## check that protobuf changes aren't present.
 	@echo "$(WHALE) $@"
@@ -105,7 +105,7 @@ fmt: ## run go fmt
 	@echo "$(WHALE) $@"
 	@test -z "$$(gofmt -s -l . | grep -Fv $(call FIX_PATH,'vendor/') | grep -v ".pb.go$$" | tee /dev/stderr)" || \
 		(echo "$(ONI) please format Go code with 'gofmt -s -w'" && false)
-	@test -z "$$(find . -path ./vendor -prune -o ! -name timestamp.proto ! -name duration.proto -name '*.proto' -type f -exec grep -Hn -e "^ " {} \; | tee /dev/stderr)" || \
+	@test -z "$$(find . -path ./vendor -prune -o -path ./protobuf/google/rpc -prune -o -name '*.proto' -type f -exec grep -Hn -e "^ " {} \; | tee /dev/stderr)" || \
 		(echo "$(ONI) please indent proto files with tabs only" && false)
 	@test -z "$$(find . -path ./vendor -prune -o -name '*.proto' -type f -exec grep -Hn "Meta meta = " {} \; | grep -v '(gogoproto.nullable) = false' | tee /dev/stderr)" || \
 		(echo "$(ONI) meta fields in proto files must have option (gogoproto.nullable) = false" && false)

Protobuild.toml

@@ -7,12 +7,12 @@ plugins = ["grpc", "fieldpath"]
 [includes]
   # Include paths that will be added before all others. Typically, you want to
   # treat the root of the project as an include, but this may not be necessary.
-  # before = ["."]
+  before = ["./protobuf"]
 
   # Paths that should be treated as include roots in relation to the vendor
   # directory. These will be calculated with the vendor directory nearest the
   # target package.
-  vendored = ["github.com/gogo/protobuf"]
+  packages = ["github.com/gogo/protobuf"]
 
   # Paths that will be added untouched to the end of the includes. We use
   # `/usr/local/include` to pickup the common install location of protobuf.
@@ -27,6 +27,8 @@ plugins = ["grpc", "fieldpath"]
   "google/protobuf/descriptor.proto" = "github.com/gogo/protobuf/protoc-gen-gogo/descriptor"
   "google/protobuf/field_mask.proto" = "github.com/gogo/protobuf/types"
   "google/protobuf/timestamp.proto" = "github.com/gogo/protobuf/types"
+  "google/protobuf/duration.proto" = "github.com/gogo/protobuf/types"
+  "google/rpc/status.proto" = "github.com/containerd/containerd/protobuf/google/rpc"
 
 # Aggregrate the API descriptors to lock down API changes.
 [[descriptors]]

api/next.pb.txt

@@ -2182,6 +2182,201 @@ file {
   }
   syntax: "proto3"
 }
+file {
+  name: "github.com/containerd/containerd/api/types/platform.proto"
+  package: "containerd.types"
+  dependency: "gogoproto/gogo.proto"
+  message_type {
+    name: "Platform"
+    field {
+      name: "os"
+      number: 1
+      label: LABEL_OPTIONAL
+      type: TYPE_STRING
+      options {
+        65004: "OS"
+      }
+      json_name: "os"
+    }
+    field {
+      name: "architecture"
+      number: 2
+      label: LABEL_OPTIONAL
+      type: TYPE_STRING
+      json_name: "architecture"
+    }
+    field {
+      name: "variant"
+      number: 3
+      label: LABEL_OPTIONAL
+      type: TYPE_STRING
+      json_name: "variant"
+    }
+  }
+  options {
+    go_package: "github.com/containerd/containerd/api/types;types"
+  }
+  syntax: "proto3"
+}
+file {
+  name: "google/rpc/status.proto"
+  package: "google.rpc"
+  dependency: "google/protobuf/any.proto"
+  message_type {
+    name: "Status"
+    field {
+      name: "code"
+      number: 1
+      label: LABEL_OPTIONAL
+      type: TYPE_INT32
+      json_name: "code"
+    }
+    field {
+      name: "message"
+      number: 2
+      label: LABEL_OPTIONAL
+      type: TYPE_STRING
+      json_name: "message"
+    }
+    field {
+      name: "details"
+      number: 3
+      label: LABEL_REPEATED
+      type: TYPE_MESSAGE
+      type_name: ".google.protobuf.Any"
+      json_name: "details"
+    }
+  }
+  options {
+    java_package: "com.google.rpc"
+    java_outer_classname: "StatusProto"
+    java_multiple_files: true
+    go_package: "github.com/containerd/containerd/protobuf/google/rpc;rpc"
+    objc_class_prefix: "RPC"
+  }
+  syntax: "proto3"
+}
+file {
+  name: "github.com/containerd/containerd/api/services/introspection/v1/introspection.proto"
+  package: "containerd.services.introspection.v1"
+  dependency: "github.com/containerd/containerd/api/types/platform.proto"
+  dependency: "google/rpc/status.proto"
+  dependency: "gogoproto/gogo.proto"
+  message_type {
+    name: "Plugin"
+    field {
+      name: "type"
+      number: 1
+      label: LABEL_OPTIONAL
+      type: TYPE_STRING
+      json_name: "type"
+    }
+    field {
+      name: "id"
+      number: 2
+      label: LABEL_OPTIONAL
+      type: TYPE_STRING
+      json_name: "id"
+    }
+    field {
+      name: "requires"
+      number: 3
+      label: LABEL_REPEATED
+      type: TYPE_STRING
+      json_name: "requires"
+    }
+    field {
+      name: "platforms"
+      number: 4
+      label: LABEL_REPEATED
+      type: TYPE_MESSAGE
+      type_name: ".containerd.types.Platform"
+      options {
+        65001: 0
+      }
+      json_name: "platforms"
+    }
+    field {
+      name: "exports"
+      number: 5
+      label: LABEL_REPEATED
+      type: TYPE_MESSAGE
+      type_name: ".containerd.services.introspection.v1.Plugin.ExportsEntry"
+      json_name: "exports"
+    }
+    field {
+      name: "capabilities"
+      number: 6
+      label: LABEL_REPEATED
+      type: TYPE_STRING
+      json_name: "capabilities"
+    }
+    field {
+      name: "init_err"
+      number: 7
+      label: LABEL_OPTIONAL
+      type: TYPE_MESSAGE
+      type_name: ".google.rpc.Status"
+      json_name: "initErr"
+    }
+    nested_type {
+      name: "ExportsEntry"
+      field {
+        name: "key"
+        number: 1
+        label: LABEL_OPTIONAL
+        type: TYPE_STRING
+        json_name: "key"
+      }
+      field {
+        name: "value"
+        number: 2
+        label: LABEL_OPTIONAL
+        type: TYPE_STRING
+        json_name: "value"
+      }
+      options {
+        map_entry: true
+      }
+    }
+  }
+  message_type {
+    name: "PluginsRequest"
+    field {
+      name: "filters"
+      number: 1
+      label: LABEL_REPEATED
+      type: TYPE_STRING
+      json_name: "filters"
+    }
+  }
+  message_type {
+    name: "PluginsResponse"
+    field {
+      name: "plugins"
+      number: 1
+      label: LABEL_REPEATED
+      type: TYPE_MESSAGE
+      type_name: ".containerd.services.introspection.v1.Plugin"
+      options {
+        65001: 0
+      }
+      json_name: "plugins"
+    }
+  }
+  service {
+    name: "Introspection"
+    method {
+      name: "Plugins"
+      input_type: ".containerd.services.introspection.v1.PluginsRequest"
+      output_type: ".containerd.services.introspection.v1.PluginsResponse"
+    }
+  }
+  options {
+    go_package: "github.com/containerd/containerd/api/services/introspection/v1;introspection"
+  }
+  syntax: "proto3"
+}
 file {
   name: "github.com/containerd/containerd/api/services/namespaces/v1/namespace.proto"
   package: "containerd.services.namespaces.v1"

api/services/introspection/v1/doc.go

@@ -0,0 +1 @@
+package introspection