Add specs definition

traffic-policy.md → traffic-access-control.md

@@ -1,62 +1,10 @@
-## Traffic Policy
+## Traffic Access Control
 
-This resource allows users to define the authorization policy between
-applications and clients.
+This resource allows users to define policies that control access to resources
+for clients.
 
 ## Specification
 
-### HTTPService
-
-```yaml
-kind: HTTPService
-apiVersion: v1beta1
-metadata:
-  name: foo
-  namespace: default
-resources:
-# v1.ObjectReference
-- kind: Service
-  name: foo
-routes:
-- name: admin
-  methods:
-  - GET
-  pathRegex: "/admin/.*"
-- name: default
-  methods: ["*"]
-  pathRegex: ".*"
-```
-
-### gRPCService
-
-```yaml
-kind: gRPCService
-apiVersion: v1beta1
-metadata:
-  name: foo
-  namespace: default
-resources:
-- kind: Service
-  name: foo
-package: foo.v1
-service: SearchService
-rpc:
-- name: Search
-```
-
-### TCPService
-
-```yaml
-kind: TCPService
-apiVersion: v1beta1
-metadata:
-  name: foo
-  namespace: default
-resources:
-- kind: Service
-  name: foo
-```
-
 ### TrafficRole
 
 ```yaml
@@ -68,11 +16,20 @@ metadata:
 resource:
   name: foo
   kind: Deployment
-subjects:
-- kind: HTTPService
-  name: admin
+port: 8080
+rules:
+- kind: HTTPRoutes
+  name: the-routes
+  specs:
+  - metrics
 ```
 
+This example associates a set of routes with a set of pods. It will match the
+routes arriving at these pods on the specified port (8080). While `the-routes`
+definition contains multiple elements, only a single element is referenced in
+this role. This example could be used in conjunction with a TrafficRoleBinding
+to provide Prometheus the access to scrape metrics on the `foo` deployment.
+
 ### TrafficRoleBinding
 
 ```yaml
@@ -90,10 +47,36 @@ roleRef:
   name: path-specific
 ```
 
-Note: this specification defines that policy is *always* enforced on the
+This example grants the ability to access the routes in `path-specific` to any
+client providing the identity `bar` based on a ServiceAccount.
+
+As access control is additive, it is important to provide definitions that allow
+non-authenticated traffic access. Imagine rolling a service mesh out
+incrementally. It is important to not immediately block any traffic that is not
+from an authenticated client. In this world, groups are important as a source of
+identity.
+
+```yaml
+kind: TrafficRoleBinding
+apiVersion: v1beta1
+metadata:
+  name: account-specific
+  namespace: default
+subjects:
+- kind: Group
+  name: system:unauthenticated
+roleRef:
+  kind: TrafficRole
+  name: path-specific
+```
+
+This example allows any unauthenticated client access to the rules defined in
+`path-specific`.
+
+Note: this specification defines that access control is *always* enforced on the
 *server* side of a connection. It is up to implementations to decide whether
-they would also like to enforce this policy on the *client* side of the
-connection as well.
+they would also like to enforce access control on the *client* side
+of the connection as well.
 
 ## Use Cases
 
@@ -107,7 +90,7 @@ TODO ...
 
 ## Example Implementation
 
-## Tradeoffs {#policy-tradeoffs}
+## Tradeoffs
 
 * Additive policy - policy that denies instead of only allows is valuable
   sometimes. Unfortunately, it makes it extremely difficult to reason about what

traffic-specs.md

@@ -0,0 +1,89 @@
+## Traffic Spec
+
+This resource allows users to specify how their traffic looks. It is used in
+concert with authorization and other policies to concretely define what should
+happen to specific types of traffic as it flows through the mesh.
+
+There are many different protocols that users would like to have be part of a
+mesh. Right now, this is primarily HTTP, but it is possible to imagine a world
+where service meshes are aware of other protocols. Each resource in this
+specification is meant to match 1:1 with a specific protocol. This allows users
+to define the traffic in a protocol specific fashion.
+
+## Specification
+
+### HTTPRoutes
+
+This resource is used to describe HTTP/1 and HTTP/2 traffic. It enumerates the
+routes that can be served by an application.
+
+```yaml
+apiVersion: v1beta1
+kind: HTTPRoutes
+metadata:
+  name: the-routes
+  labels:
+    app: foobar
+    class: admin
+routes:
+- name: metrics
+  pathRegex: "/metrics"
+  methods:
+  - GET
+- name: health
+  pathRegex: "/ping"
+  methods: ["*"]
+```
+
+This example defines two routes, `metrics` and `health`. The name is the primary
+key and all fields are required. A regex is used to match against the URI and is
+anchored (`^`) to the beginning of the URI. Methods can either be specific
+(`GET`) or `*` to match all methods.
+
+These routes have not yet been associated with any resources. See
+[access control](traffic-access-control.md) for an example of how routes become
+associated with applications serving traffic.
+
+In this example, there are labels. These are used to allow flexible binding. As
+routes can be thought of as a bucket that defines traffic, it is valuable to
+have different classifications and applications. Imagine an access control
+binding across `class: admin` for specific clients such as Prometheus or
+liveness and readiness probes.
+
+Another example defines an unauthenticated catch-all and a set of specific
+routes that are sensitive and should have access controlled.
+
+```yaml
+apiVersion: v1beta1
+kind: HTTPRoutes
+metadata:
+  name: external-routes
+  labels:
+    app: foobar
+routes:
+- name: admin
+  pathRegex: "/admin/.*"
+  methods: ["*"]
+- name: unauthenticated
+  pathRegex: "/.*"
+  methods: ["*"]
+```
+
+## Automatic Generation
+
+While it is possible for users to create these by hand, the recommended pattern
+is for tools to do it for the users. OpenAPI specifications can be consumed to
+generate the list of routes. gRPC protobufs can similarly be used to
+automatically generate the list of routes from code.
+
+## Tradeoffs
+
+* These specifications are *not* directly associated with applications and other
+  resources. They're used to describe the type of traffic flowing through a mesh
+  and used by higher level policies such as access control or rate limiting. The
+  policies themselves bind these routes to the applications serving traffic.
+
+## Out of scope
+
+* gRPC - there should be a gRPC specific traffic spec. As part of the first
+  version, this has been left out as HTTPRoutes can be used in the interim.