Merge pull request #1296 from stevvooe/api-stability-tooling

api: generate merged descriptors when building protobufs

Protobuild.toml

@@ -27,3 +27,29 @@ 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"
+
+# Aggregrate the API descriptors to lock down API changes.
+[[descriptors]]
+prefix = "github.com/containerd/containerd/api"
+target = "api/next.pb.txt"
+ignore_files = [
+	"google/protobuf/descriptor.proto",
+	"gogoproto/gogo.proto"
+]
+
+# Lock down runc config
+[[descriptors]]
+prefix = "github.com/containerd/containerd/linux/runcopts"
+target = "linux/runcopts/next.pb.txt"
+ignore_files = [
+	"google/protobuf/descriptor.proto",
+	"gogoproto/gogo.proto"
+]
+
+[[descriptors]]
+prefix = "github.com/containerd/containerd/windows/hcsshimopts"
+target = "windows/hcsshimopts/next.pb.txt"
+ignore_files = [
+	"google/protobuf/descriptor.proto",
+	"gogoproto/gogo.proto"
+]

api/README.md

@@ -0,0 +1,18 @@
+This directory contains the GRPC API definitions for contaienrd.
+
+All defined services and messages have been aggregated into `*.pb.txt`
+descriptors files in this directory. Definitions present here are considered
+frozen after the release.
+
+At release time, the current `next.pb.txt` file will be moved into place to
+freeze the API changes for the minor version. For example, when 1.0.0 is
+released, `next.pb.txt` should be moved to `1.0.txt`. Notice that we leave off
+the patch number, since the API will be completely locked down for a given
+patch series.
+
+We may find that by default, protobuf descriptors are too noisy to lock down
+API changes. In that case, we may filter out certain fields in the descriptors,
+possibly regenerating for old versions.
+
+This process is similar to the [process used to ensure backwards compatibility
+in Go](https://github.com/golang/go/tree/master/api).

linux/runcopts/next.pb.txt

@@ -0,0 +1,144 @@
+file {
+  name: "github.com/containerd/containerd/linux/runcopts/runc.proto"
+  package: "containerd.linux.runc"
+  dependency: "gogoproto/gogo.proto"
+  message_type {
+    name: "RuncOptions"
+    field {
+      name: "criu_path"
+      number: 1
+      label: LABEL_OPTIONAL
+      type: TYPE_STRING
+      json_name: "criuPath"
+    }
+    field {
+      name: "systemd_cgroup"
+      number: 2
+      label: LABEL_OPTIONAL
+      type: TYPE_STRING
+      json_name: "systemdCgroup"
+    }
+  }
+  message_type {
+    name: "CreateOptions"
+    field {
+      name: "no_pivot_root"
+      number: 1
+      label: LABEL_OPTIONAL
+      type: TYPE_BOOL
+      json_name: "noPivotRoot"
+    }
+    field {
+      name: "open_tcp"
+      number: 2
+      label: LABEL_OPTIONAL
+      type: TYPE_BOOL
+      json_name: "openTcp"
+    }
+    field {
+      name: "external_unix_sockets"
+      number: 3
+      label: LABEL_OPTIONAL
+      type: TYPE_BOOL
+      json_name: "externalUnixSockets"
+    }
+    field {
+      name: "terminal"
+      number: 4
+      label: LABEL_OPTIONAL
+      type: TYPE_BOOL
+      json_name: "terminal"
+    }
+    field {
+      name: "file_locks"
+      number: 5
+      label: LABEL_OPTIONAL
+      type: TYPE_BOOL
+      json_name: "fileLocks"
+    }
+    field {
+      name: "empty_namespaces"
+      number: 6
+      label: LABEL_REPEATED
+      type: TYPE_STRING
+      json_name: "emptyNamespaces"
+    }
+    field {
+      name: "cgroups_mode"
+      number: 7
+      label: LABEL_OPTIONAL
+      type: TYPE_STRING
+      json_name: "cgroupsMode"
+    }
+    field {
+      name: "no_new_keyring"
+      number: 8
+      label: LABEL_OPTIONAL
+      type: TYPE_BOOL
+      json_name: "noNewKeyring"
+    }
+    field {
+      name: "shim_cgroup"
+      number: 9
+      label: LABEL_OPTIONAL
+      type: TYPE_STRING
+      json_name: "shimCgroup"
+    }
+  }
+  message_type {
+    name: "CheckpointOptions"
+    field {
+      name: "exit"
+      number: 1
+      label: LABEL_OPTIONAL
+      type: TYPE_BOOL
+      json_name: "exit"
+    }
+    field {
+      name: "open_tcp"
+      number: 2
+      label: LABEL_OPTIONAL
+      type: TYPE_BOOL
+      json_name: "openTcp"
+    }
+    field {
+      name: "external_unix_sockets"
+      number: 3
+      label: LABEL_OPTIONAL
+      type: TYPE_BOOL
+      json_name: "externalUnixSockets"
+    }
+    field {
+      name: "terminal"
+      number: 4
+      label: LABEL_OPTIONAL
+      type: TYPE_BOOL
+      json_name: "terminal"
+    }
+    field {
+      name: "file_locks"
+      number: 5
+      label: LABEL_OPTIONAL
+      type: TYPE_BOOL
+      json_name: "fileLocks"
+    }
+    field {
+      name: "empty_namespaces"
+      number: 6
+      label: LABEL_REPEATED
+      type: TYPE_STRING
+      json_name: "emptyNamespaces"
+    }
+    field {
+      name: "cgroups_mode"
+      number: 7
+      label: LABEL_OPTIONAL
+      type: TYPE_STRING
+      json_name: "cgroupsMode"
+    }
+  }
+  options {
+    go_package: "github.com/containerd/containerd/linux/runcopts;runcopts"
+  }
+  syntax: "proto3"
+}

windows/hcsshimopts/next.pb.txt

@@ -0,0 +1,56 @@
+file {
+  name: "google/protobuf/duration.proto"
+  package: "google.protobuf"
+  message_type {
+    name: "Duration"
+    field {
+      name: "seconds"
+      number: 1
+      label: LABEL_OPTIONAL
+      type: TYPE_INT64
+      json_name: "seconds"
+    }
+    field {
+      name: "nanos"
+      number: 2
+      label: LABEL_OPTIONAL
+      type: TYPE_INT32
+      json_name: "nanos"
+    }
+  }
+  options {
+    java_package: "com.google.protobuf"
+    java_outer_classname: "DurationProto"
+    java_multiple_files: true
+    go_package: "github.com/golang/protobuf/ptypes/duration"
+    cc_enable_arenas: true
+    objc_class_prefix: "GPB"
+    csharp_namespace: "Google.Protobuf.WellKnownTypes"
+  }
+  syntax: "proto3"
+}
+file {
+  name: "github.com/containerd/containerd/windows/hcsshimopts/hcsshim.proto"
+  package: "containerd.windows.hcsshim"
+  dependency: "gogoproto/gogo.proto"
+  dependency: "google/protobuf/duration.proto"
+  message_type {
+    name: "CreateOptions"
+    field {
+      name: "terminate_duration"
+      number: 1
+      label: LABEL_OPTIONAL
+      type: TYPE_MESSAGE
+      type_name: ".google.protobuf.Duration"
+      options {
+        65011: 1
+        65001: 0
+      }
+      json_name: "terminateDuration"
+    }
+  }
+  options {
+    go_package: "github.com/containerd/containerd/windows/hcsshimopts;hcsshimopts"
+  }
+  syntax: "proto3"
+}