diff --git a/apis/traffic-specs/v1alpha4/traffic-specs.md b/apis/traffic-specs/traffic-specs.md similarity index 89% rename from apis/traffic-specs/v1alpha4/traffic-specs.md rename to apis/traffic-specs/traffic-specs.md index 881546d..9dffc1c 100644 --- a/apis/traffic-specs/v1alpha4/traffic-specs.md +++ b/apis/traffic-specs/traffic-specs.md @@ -2,7 +2,7 @@ **API Group:** specs.smi-spec.io -**API Version:** v1alpha4 +**API Version:** v1alpha5-draft ## Specification @@ -28,7 +28,7 @@ kind: HTTPRouteGroup metadata: name: the-routes spec: - matches: + routes: - name: metrics pathRegex: "/metrics" methods: @@ -38,7 +38,7 @@ spec: methods: ["*"] ``` -This example defines two matches, `metrics` and `health`. The name is the +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. @@ -47,7 +47,7 @@ These routes have not yet been associated with any resources. See [Traffic Target](/apis/traffic-access/v1alpha3/traffic-access.md) for an example of how routes become associated with applications serving traffic. -The `matches` field only applies to URIs and HTTP headers. +The `routes` field only applies to URIs and HTTP headers. ```yaml kind: HTTPRouteGroup @@ -55,7 +55,7 @@ metadata: name: the-routes namespace: default spec: - matches: + routes: - name: everything pathRegex: ".*" methods: ["*"] @@ -83,7 +83,7 @@ metadata: name: the-routes namespace: default spec: - matches: + routes: - name: android-insiders headers: - user-agent: ".*Android.*" @@ -99,7 +99,7 @@ metadata: name: the-routes namespace: default spec: - matches: + routes: - name: android-insiders headers: - user-agent: ".*Android.*" @@ -119,7 +119,7 @@ kind: HTTPRouteGroup metadata: name: the-routes spec: - matches: + routes: - name: iphone-users pathRegex: "/api/.*" methods: @@ -144,22 +144,20 @@ kind: TCPRoute metadata: name: the-routes spec: - matches: - ports: - - 3306 - - 6446 + ports: + - 3306 + - 6446 ``` -When matching ports are not specified, -the TCP route will match all the ports of a Kubernetes service: +When matching ports are not specified, the TCP route will match all the ports of +a Kubernetes service: ```yaml kind: TCPRoute metadata: name: the-routes spec: - matches: - ports: [] + ports: [] ``` ### UDPRoute @@ -171,22 +169,20 @@ kind: UDPRoute metadata: name: the-routes spec: - matches: - ports: - - 989 - - 990 + ports: + - 989 + - 990 ``` -When matching ports are not specified, -the UDP route will match all the ports of a Kubernetes service: +When matching ports are not specified, the UDP route will match all the ports of +a Kubernetes service: ```yaml kind: UDPRoute metadata: name: the-routes spec: - matches: - ports: [] + ports: [] ``` ## Automatic Generation diff --git a/apis/traffic-specs/v1alpha1/traffic-specs.md b/apis/traffic-specs/v1alpha1/traffic-specs.md deleted file mode 100644 index fc9ddb7..0000000 --- a/apis/traffic-specs/v1alpha1/traffic-specs.md +++ /dev/null @@ -1,97 +0,0 @@ -# Traffic Specs `v1alpha1` - -This set of resources allows users to specify how their traffic looks. It is -used in concert with [access control](traffic-access-control.md) 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 - -### HTTPRouteGroup - -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: specs.smi-spec.io/v1alpha1 -kind: HTTPRouteGroup -metadata: - name: the-routes -matches: -- name: metrics - pathRegex: "/metrics" - methods: - - GET -- name: health - pathRegex: "/ping" - methods: ["*"] -``` - -This example defines two matches, `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. - -The `matches` field only applies to URIs. It is common to look at other parts of -an HTTP request. This behaviour is not yet defined; however, the spec will be -extended at a later date to accommodate capabilities such as HTTP header, -Host, etc. - -```yaml -apiVersion: v1alpha1 -kind: HTTPRouteGroup -metadata: - name: the-routes - namespace: default -matches: -- name: everything - pathRegex: ".*" - methods: ["*"] -``` - -This example defines a single route that matches anything. - -### TCPRoute - -This resource is used to describe L4 TCP traffic. It is a simple route which configures -an application to receive raw non protocol specific traffic. - -```yaml -apiVersion: specs.smi-spec.io/v1alpha1 -kind: TCPRoute -metadata: - name: tcp-route -``` - -## 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 HTTPRouteGroup can be used in the interim. - -* Arbitrary header filtering - there should be a way to filter based on headers. - This has been left out for now, but the specification should be expanded to - address this use case. diff --git a/apis/traffic-specs/v1alpha2/traffic-specs.md b/apis/traffic-specs/v1alpha2/traffic-specs.md deleted file mode 100644 index 7cc6618..0000000 --- a/apis/traffic-specs/v1alpha2/traffic-specs.md +++ /dev/null @@ -1,161 +0,0 @@ -# Traffic Specs - -**API Group:** specs.smi-spec.io - -**Version:** v1alpha2 - -## Specification - -This specification describes a set of resources that allows users to specify -how their traffic looks. It is used in concert with -[access control](/apis/traffic-access/v1alpha1/traffic-access.md) 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. - -### HTTPRouteGroup - -This resource is used to describe HTTP/1 and HTTP/2 traffic. It enumerates the -routes that can be served by an application. - -```yaml -kind: HTTPRouteGroup -metadata: - name: the-routes -matches: -- name: metrics - pathRegex: "/metrics" - methods: - - GET -- name: health - pathRegex: "/ping" - methods: ["*"] -``` - -This example defines two matches, `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 -[Traffic Target](/apis/traffic-access/v1alpha1/traffic-access.md) for an example -of how routes become associated with applications serving traffic. - -The `matches` field only applies to URIs and HTTP headers. - -```yaml -kind: HTTPRouteGroup -metadata: - name: the-routes - namespace: default -matches: -- name: everything - pathRegex: ".*" - methods: ["*"] -``` - -This example defines a single route that matches anything. - -### HTTP header filters - -A route definition can specify a list of HTTP header filters. -A filter defines a match condition that's applied to incoming HTTP requests. -The filters defined in a route group can be associated with a -[traffic split](/apis/traffic-split/v1alpha3/traffic-split.md) thus enabling traffic -shifting for A/B testing scenarios. - -A HTTP filter is a key-value pair, the key is the name of the HTTP header and -the value is a regex expression that defines the match condition for that header. - -A route with multiple header filters represents an `AND` condition while multiple -routes each with its own header filter represents an `OR` condition. - -```yaml -kind: HTTPRouteGroup -metadata: - name: the-routes - namespace: default -matches: -- name: android-insiders - headers: - - user-agent: ".*Android.*" - - cookie: "^(.*?;)?(type=insider)(;.*)?$" -``` - -The above example defines a filter that targets Android users with a -`type=insider` cookie. - -```yaml -kind: HTTPRouteGroup -metadata: - name: the-routes - namespace: default -matches: -- name: android-insiders - headers: - - user-agent: ".*Android.*" - - cookie: "^(.*?;)?(type=insider)(;.*)?$" -- name: firefox-users - headers: - - user-agent: ".*Firefox.*" -``` - -The above example defines two routes that target Android users with a `type=insider` -cookie or Firefox users. - -A route that targets a specific path and/or HTTP methods can contain header filters: - -```yaml -kind: HTTPRouteGroup -metadata: - name: the-routes -matches: -- name: iphone-users - pathRegex: "/api/.*" - methods: - - GET - - HEAD - headers: - - user-agent: ".*iPhone.*" -``` - -The above example defines a route that targets iPhone users that are issuing -`GET` or `HEAD` requests to `/api`. - -When `pathRegex` and `methods` are not defined, the header filters are applied -to any path and all HTTP methods. - -### TCPRoute - -This resource is used to describe L4 TCP traffic. It is a simple route which configures -an application to receive raw non protocol specific traffic. - -```yaml -kind: TCPRoute -metadata: - name: tcp-route -``` - -## 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 HTTPRouteGroup can be used in the interim. diff --git a/apis/traffic-specs/v1alpha3/traffic-specs.md b/apis/traffic-specs/v1alpha3/traffic-specs.md deleted file mode 100644 index 04ffbce..0000000 --- a/apis/traffic-specs/v1alpha3/traffic-specs.md +++ /dev/null @@ -1,167 +0,0 @@ -# Traffic Specs - -**API Group:** specs.smi-spec.io - -**Version:** v1alpha3 - -## Specification - -This specification describes a set of resources that allows users to specify -how their traffic looks. It is used in concert with -[access control](/apis/traffic-access/v1alpha2/traffic-access.md) 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. - -### HTTPRouteGroup - -This resource is used to describe HTTP/1 and HTTP/2 traffic. It enumerates the -routes that can be served by an application. - -```yaml -kind: HTTPRouteGroup -metadata: - name: the-routes -spec: - matches: - - name: metrics - pathRegex: "/metrics" - methods: - - GET - - name: health - pathRegex: "/ping" - methods: ["*"] -``` - -This example defines two matches, `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 -[Traffic Target](/apis/traffic-access/v1alpha2/traffic-access.md) for an example -of how routes become associated with applications serving traffic. - -The `matches` field only applies to URIs and HTTP headers. - -```yaml -kind: HTTPRouteGroup -metadata: - name: the-routes - namespace: default -spec: - matches: - - name: everything - pathRegex: ".*" - methods: ["*"] -``` - -This example defines a single route that matches anything. - -### HTTP header filters - -A route definition can specify a list of HTTP header filters. -A filter defines a match condition that's applied to incoming HTTP requests. -The filters defined in a route group can be associated with a -[traffic split](/apis/traffic-split/v1alpha3/traffic-split.md) thus enabling traffic -shifting for A/B testing scenarios. - -A HTTP filter is a key-value pair, the key is the name of the HTTP header and -the value is a regex expression that defines the match condition for that header. - -A route with multiple header filters represents an `AND` condition while multiple -routes each with its own header filter represents an `OR` condition. - -```yaml -kind: HTTPRouteGroup -metadata: - name: the-routes - namespace: default -spec: - matches: - - name: android-insiders - headers: - - user-agent: ".*Android.*" - - cookie: "^(.*?;)?(type=insider)(;.*)?$" -``` - -The above example defines a filter that targets Android users with a -`type=insider` cookie. - -```yaml -kind: HTTPRouteGroup -metadata: - name: the-routes - namespace: default -spec: - matches: - - name: android-insiders - headers: - - user-agent: ".*Android.*" - - cookie: "^(.*?;)?(type=insider)(;.*)?$" - - name: firefox-users - headers: - - user-agent: ".*Firefox.*" -``` - -The above example defines two routes that target Android users with a `type=insider` -cookie or Firefox users. - -A route that targets a specific path and/or HTTP methods can contain header filters: - -```yaml -kind: HTTPRouteGroup -metadata: - name: the-routes -spec: - matches: - - name: iphone-users - pathRegex: "/api/.*" - methods: - - GET - - HEAD - headers: - - user-agent: ".*iPhone.*" -``` - -The above example defines a route that targets iPhone users that are issuing -`GET` or `HEAD` requests to `/api`. - -When `pathRegex` and `methods` are not defined, the header filters are applied -to any path and all HTTP methods. - -### TCPRoute - -This resource is used to describe L4 TCP traffic. It is a simple route which configures -an application to receive raw non protocol specific traffic. - -```yaml -kind: TCPRoute -metadata: - name: tcp-route -spec: {} -``` - -## 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 HTTPRouteGroup can be used in the interim.