sketch of an extension manifest

extension/v1alpha1/manifest.proto

@@ -0,0 +1,213 @@
+// Copyright 2019 Istio Authors
+//
+//   Licensed under the Apache License, Version 2.0 (the "License");
+//   you may not use this file except in compliance with the License.
+//   You may obtain a copy of the License at
+//
+//       http://www.apache.org/licenses/LICENSE-2.0
+//
+//   Unless required by applicable law or agreed to in writing, software
+//   distributed under the License is distributed on an "AS IS" BASIS,
+//   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+//   See the License for the specific language governing permissions and
+//   limitations under the License.
+
+syntax = "proto3";
+
+// $schema: istio.extension.v1alpha1.ExtensionManifest
+// $title: Extension Manifest
+
+// `ExtensionManifest` specifies additional extensions to be
+// applied in a service mesh. Extensions are injected into the
+// data plane processing based on a set of criteria, such as
+// the workload labels, service ports, protocols, etc.
+//
+// ```yaml
+// apiVersion: extension.istio.io/v1alpha1
+// kind: ExtensionManifest
+// metadata:
+//   name: zip
+//   namespace: istio-config
+// spec:
+//   filters:
+//   - match:
+//       proxyVersion: '1\.4.*'
+//       context: SIDECAR_OUTBOUND
+//       portNumber: 8080
+//     type: HTTP_FILTER
+//     name: compress-outbound
+//     config:
+//       typeUrl: config.filter.http.gzip.v2.Gzip
+//       value:
+//         compression_level: BEST
+//     function: POST_PROCESSING
+//```
+//
+package istio.extension.v1alpha1;
+
+option go_package = "istio.io/api/extension/v1alpha1";
+
+import "google/protobuf/struct.proto";
+
+// Opaque configuration for an extension (wire and JSON compatible with UDPA).
+// The extension resource allows white-listing pre-defined configuration for
+// extensions.
+message Extension {
+  // A URL that uniquely identifies the type of the serialize protocol buffer
+  // message. This has same semantics and format described in
+  // google.protobuf.Any:
+  // https://github.com/protocolbuffers/protobuf/blob/master/src/google/protobuf/any.proto
+  string type_url = 1;
+
+  // A JSON representation of the above specified type.
+  google.protobuf.Struct value = 2;
+}
+
+// Reference to extension resource.
+message ExtensionRef {
+  string name = 1;
+  string namespace = 2;
+}
+
+// A condition limiting the extent of the extension application.
+message MatchContext {
+  // A regular expression in golang regex format (RE2) that can be
+  // used to select proxies using a specific version of istio
+  // proxy. The Istio version for a given proxy is obtained from the
+  // node metadata field ISTIO_VERSION supplied by the proxy when
+  // connecting to Pilot. This value is embedded as an environment
+  // variable (ISTIO_META_ISTIO_VERSION) in the Istio proxy docker
+  // image. Custom proxy implementations should provide this metadata
+  // variable to take advantage of the Istio version check option.
+  string proxy_version = 1;
+
+  // Match on the node metadata supplied by a proxy when connecting
+  // to Istio Pilot. Note that while Envoy's node metadata is of
+  // type Struct, only string key-value pairs are processed by
+  // Pilot. All keys specified in the metadata must match with exact
+  // values. The match will fail if any of the specified keys are
+  // absent or the values fail to match.
+  map<string, string> metadata = 2;
+
+  // Configuration type.
+  enum ProxyContext {
+    UNSPECIFIED = 0;
+    SIDECAR_INBOUND = 1;
+    SIDECAR_OUTBOUND = 2;
+    GATEWAY = 3;
+  };
+
+  // Match on the proxy type (applicable for network and HTTP filters).
+  ProxyContext context = 3;
+
+  // The service port of the upstream or downstream configuration resource. If
+  // omitted, applies to clusters and listeners for any port.
+  uint32 port_number = 4;
+
+  // The Istio gateway config's namespace/name for which this route
+  // configuration was generated. Applies only if the context is GATEWAY. Should
+  // be in the namespace/name format. Use this field in conjunction with the
+  // portNumber to accurately select the Envoy route configuration for a
+  // specific HTTPS server within a gateway config object.
+  string gateway = 5;
+
+  // The fully qualified service name for this cluster or listener. For
+  // services defined through service entries, the service name is same as the
+  // hosts defined in the service entry.
+  string service = 6;
+
+  // The subset associated with the service. If omitted, applies to
+  // clusters for any subset of a service.
+  string subset = 7;
+
+  // Criteria used to select the specific set of pods/VMs on which
+  // this patch configuration should be applied. If omitted, the set
+  // of patches in this configuration will be applied to all workload
+  // instances in the same namespace.  If omitted, the EnvoyFilter
+  // patches will be applied to all workloads in the same
+  // namespace. If the EnvoyFilter is present in the config root
+  // namespace, it will be applied to all applicable workloads in any
+  // namespace.
+  map<string, string> workload_labels = 8;
+
+  // Namespace of the proxy.
+  string namespace = 9;
+}
+
+// ExtensionManifest specifies a set of custom extensions.
+// Manifests can be applied in any namespace. Per-namespace manifests
+// may override the root manifests for the overlapping filter names if
+// both match conditions are satisfied.
+// Beyond that, the order of application of the manifests is unspecified.
+// Additional control over the delegation of the extension injection should
+// be enforced with either resource-level RBAC or an admission controller.
+message ExtensionManifest {
+  // Extension filter type.
+  enum FilterType {
+    UNSPECIFIED_FILTER_TYPE = 0;
+    HTTP_FILTER = 1;
+    NETWORK_FILTER = 2;
+    UPSTREAM_NETWORK_FILTER = 3;
+    LISTENER_FILTER = 4;
+  };
+
+  // Operation performed with the supplied config when the match condition is
+  // satisfied. By default, the operation is to displace the filter with the
+  // same name. If no filter with the same name is present, then the filter is
+  // added to chain using the provided function hint to locate the position of
+  // insertion. If the operation is to remove, then the filter with the same
+  // name is removed (config is optional). If no filter with the same name is
+  // found then, then it is a no-op.
+  enum Operation {
+    ADD = 0;
+    REMOVE = 2;
+  };
+
+  // Extension purpose serving as a hint to determine the order of the
+  // application of an extension in a chain of extensions. Istio recognizes the
+  // following categories of extensions and applies them in the order specified
+  // here.
+  enum Function {
+    UNSPECIFIED_FUNCTION = 0;
+    TELEMETRY = 1;
+    PRE_PROCESSING = 2;
+    AUTHORIZATION = 3;
+    POST_PROCESSING = 4;
+  };
+
+  // Extension description for a data plane filter.
+  message FilterExtension {
+    // Optional conditions to limit the scope of the extension.
+    // At least one of the conditions must be satisfied for the filter to be
+    // applied.
+    repeated MatchContext match = 1;
+
+    // Specifies the type of the filter.
+    FilterType type = 2;
+
+    // The required name of the filter instance. The name should generally be
+    // unique in a filter chain.
+    string name = 3;
+
+    // Opaque configuration for the filter.
+    oneof configuration {
+      // Inlined extension configuration.
+      Extension config = 4;
+      // Configuration reference.
+      ExtensionRef config_ref = 5;
+    }
+
+    // Modification operation (function is optional in case of replacement or
+    // removal).
+    Operation operation = 6;
+
+    // Purpose of the extension used to place the filter in a chain.
+    Function function = 7;
+  };
+
+  // A list of extensions to be applied. The filter extensions are processed in
+  // the order specified here. If multiple extension conditions are satisfied
+  // for the same filter name within a manifest, then the last filter config
+  // applies.
+  repeated FilterExtension filters = 1;
+}