diff --git a/traffic-policy.md b/traffic-access-control.md similarity index 61% rename from traffic-policy.md rename to traffic-access-control.md index 47cf683..d7bee86 100644 --- a/traffic-policy.md +++ b/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 diff --git a/traffic-specs.md b/traffic-specs.md new file mode 100644 index 0000000..6e5b2e5 --- /dev/null +++ b/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.