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 <[email protected]>
zhuangqh · Oct 10, 2017 · 363d692 · 363d692
1 parent 12c79cc
commit 363d692
Show file tree

Hide file tree

Showing 18 changed files with 5,678 additions and 5 deletions.
diff --git a/Makefile b/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)

diff --git a/Protobuild.toml b/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]]

diff --git a/api/next.pb.txt b/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"

diff --git a/api/services/introspection/v1/doc.go b/api/services/introspection/v1/doc.go
@@ -0,0 +1 @@
+package introspection