|
| 1 | +# Traffic Access Control |
| 2 | + |
| 3 | +**API Group:** access.smi-spec.io |
| 4 | + |
| 5 | +**API Version:** v1alpha2 |
| 6 | + |
| 7 | +**Compatible With:** specs.smi-spec.io/v1alpha3 |
| 8 | + |
| 9 | +This set of resources allows users to define access control policy for their |
| 10 | +applications. It is the authorization side of the picture. Authentication should |
| 11 | +already be handled by the underlying implementation and surfaced through a subject. |
| 12 | + |
| 13 | +Access control in this specification is additive, all traffic is denied by default. |
| 14 | +See [tradeoffs](#tradeoffs) for a longer discussion about why. |
| 15 | + |
| 16 | +## Specification |
| 17 | + |
| 18 | +### TrafficTarget |
| 19 | + |
| 20 | +A `TrafficTarget` associates a set of traffic definitions (rules) with a |
| 21 | +service identity which is allocated to a group of pods. Access is controlled |
| 22 | +via referenced [TrafficSpecs](/apis/traffic-specs/v1alpha3/traffic-specs.md) |
| 23 | +and by a list of source service identities. If a pod which holds the reference |
| 24 | +service identity makes a call to the destination on one of the defined routes |
| 25 | +then access will be allowed. Any pod which attempts to connect and is not in |
| 26 | +the defined list of sources will be denied. Any pod which is in the defined |
| 27 | +list but attempts to connect on a route which is not in the list of |
| 28 | +`TrafficSpecs` will be denied. |
| 29 | + |
| 30 | +Access is controlled based on service identity, at present the method of |
| 31 | +assigning service identity is using Kubernetes service accounts, provision for |
| 32 | +other identity mechanisms will be handled by the spec at a later date. |
| 33 | + |
| 34 | +Rules are [traffic specs](/apis/traffic-specs/v1alpha3/traffic-specs.md) that |
| 35 | +define what traffic for specific protocols would look like. The kind can be |
| 36 | +different depending on what traffic a target is serving. In the following |
| 37 | +examples, `HTTPRouteGroup` is used for applications serving HTTP based traffic. |
| 38 | + |
| 39 | +To understand how this all fits together, first define the routes for some |
| 40 | +traffic. |
| 41 | + |
| 42 | +```yaml |
| 43 | +kind: HTTPRouteGroup |
| 44 | +metadata: |
| 45 | + name: the-routes |
| 46 | +spec: |
| 47 | + matches: |
| 48 | + - name: metrics |
| 49 | + pathRegex: "/metrics" |
| 50 | + methods: |
| 51 | + - GET |
| 52 | + - name: everything |
| 53 | + pathRegex: ".*" |
| 54 | + methods: ["*"] |
| 55 | +``` |
| 56 | +
|
| 57 | +For this definition, there are two routes: metrics and everything. It is a |
| 58 | +common use case to restrict access to `/metrics` to only be scraped by |
| 59 | +Prometheus. To define the target for this traffic, it takes a `TrafficTarget`. |
| 60 | + |
| 61 | +```yaml |
| 62 | +--- |
| 63 | +kind: TrafficTarget |
| 64 | +metadata: |
| 65 | + name: path-specific |
| 66 | + namespace: default |
| 67 | +spec: |
| 68 | + destination: |
| 69 | + kind: ServiceAccount |
| 70 | + name: service-a |
| 71 | + namespace: default |
| 72 | + port: 8080 |
| 73 | + rules: |
| 74 | + - kind: HTTPRouteGroup |
| 75 | + name: the-routes |
| 76 | + matches: |
| 77 | + - metrics |
| 78 | + sources: |
| 79 | + - kind: ServiceAccount |
| 80 | + name: prometheus |
| 81 | + namespace: default |
| 82 | +``` |
| 83 | + |
| 84 | +This example selects all the pods which have the `service-a` `ServiceAccount`. |
| 85 | +Traffic destined on a path `/metrics` is allowed. The `matches` field is |
| 86 | +optional and if omitted, a rule is valid for all the matches in a traffic spec |
| 87 | +(a OR relationship). It is possible for a service to expose multiple ports, |
| 88 | +the `port` field allows the user to specify specifically which port traffic |
| 89 | +should be allowed on. `port` is an optional element, if not specified, traffic |
| 90 | +will be allowed to all ports on the destination service. |
| 91 | + |
| 92 | +Allowing destination traffic should only be possible with permission of the |
| 93 | +service owner. Therefore, RBAC rules should be configured to control the pods |
| 94 | +which are allowed to assign the `ServiceAccount` defined in the TrafficTarget |
| 95 | +destination. |
| 96 | + |
| 97 | +**Note:** access control is *always* enforced on the *server* side of a |
| 98 | +connection (or the target). It is up to implementations to decide whether they |
| 99 | +would also like to enforce access control on the *client* (or source) side of |
| 100 | +the connection as well. |
| 101 | + |
| 102 | +Source identities which are allowed to connect to the destination is defined in |
| 103 | +the sources list. Only pods which have a `ServiceAccount` which is named in |
| 104 | +the sources list are allowed to connect to the destination. |
| 105 | + |
| 106 | +## Example Implementation |
| 107 | + |
| 108 | +The following implementation shows four services api, website, payment and |
| 109 | +prometheus. It shows how it is possible to write fine grained TrafficTargets |
| 110 | +which allow access to be controlled by route and source. |
| 111 | + |
| 112 | +```yaml |
| 113 | +kind: HTTPRouteGroup |
| 114 | +metadata: |
| 115 | + name: api-service-routes |
| 116 | +spec: |
| 117 | + matches: |
| 118 | + - name: api |
| 119 | + pathRegex: /api |
| 120 | + methods: ["*"] |
| 121 | + - name: metrics |
| 122 | + pathRegex: /metrics |
| 123 | + methods: ["GET"] |
| 124 | +--- |
| 125 | +kind: TrafficTarget |
| 126 | +metadata: |
| 127 | + name: api-service-metrics |
| 128 | + namespace: default |
| 129 | +spec: |
| 130 | + destination: |
| 131 | + kind: ServiceAccount |
| 132 | + name: api-service |
| 133 | + namespace: default |
| 134 | + rules: |
| 135 | + - kind: HTTPRouteGroup |
| 136 | + name: api-service-routes |
| 137 | + matches: |
| 138 | + - metrics |
| 139 | + sources: |
| 140 | + - kind: ServiceAccount |
| 141 | + name: prometheus |
| 142 | + namespace: default |
| 143 | +--- |
| 144 | +kind: TrafficTarget |
| 145 | +metadata: |
| 146 | + name: api-service-api |
| 147 | + namespace: default |
| 148 | +spec: |
| 149 | + destination: |
| 150 | + kind: ServiceAccount |
| 151 | + name: api-service |
| 152 | + namespace: default |
| 153 | + port: 8080 |
| 154 | + rules: |
| 155 | + - kind: HTTPRouteGroup |
| 156 | + name: api-service-routes |
| 157 | + matches: |
| 158 | + - api |
| 159 | + sources: |
| 160 | + - kind: ServiceAccount |
| 161 | + name: website-service |
| 162 | + namespace: default |
| 163 | + - kind: ServiceAccount |
| 164 | + name: payments-service |
| 165 | + namespace: default |
| 166 | +``` |
| 167 | + |
| 168 | +The previous example would allow the following HTTP traffic: |
| 169 | + |
| 170 | +| source | destination | path | method | |
| 171 | +| ----------------- | ------------- | -------- | ------ | |
| 172 | +| website-service | api-service | /api | * | |
| 173 | +| payments-service | api-service | /api | * | |
| 174 | +| prometheus | api-service | /metrics | GET | |
| 175 | + |
| 176 | +## Tradeoffs |
| 177 | + |
| 178 | +* Additive policy - policy that denies instead of only allows is valuable |
| 179 | + sometimes. Unfortunately, it makes it extremely difficult to reason about what |
| 180 | + is allowed or denied in a configuration. |
| 181 | + |
| 182 | +* Resources vs selectors - it would be possible to reference concrete resources |
| 183 | + such as a deployment instead of selecting across pods. |
| 184 | + |
| 185 | +* As this access control is on the destination (server) side, implicitly |
| 186 | + |
| 187 | +* Currently the specification does not have provision for the definition of |
| 188 | + higher level elements such as a service. It is probable that this specification |
| 189 | + will change once these elements are defined. |
| 190 | + |
| 191 | +## Out of scope |
| 192 | + |
| 193 | +* Egress policy - TrafficTarget does *not* allow for the possibility of egress |
| 194 | + access control as it selects specific pods and not hostnames. Another object |
| 195 | + will need to be created to manage this use case. |
| 196 | + |
| 197 | +* Ingress policy - assuming clients present the correct identity, this *should* |
| 198 | + work for some kind of ingress. Unfortunately, it does not cover many of the |
| 199 | + common use cases (filtering by hostname) and will need to be expanded to cover |
| 200 | + this use case. |
| 201 | + |
| 202 | +* Other types of policy - having policy around retries, timeouts and rate limits |
| 203 | + would be great. This specific object only manages access control. As policy |
| 204 | + for these examples would be HTTP specific, there needs to be a HTTP specific |
| 205 | + policy object created. |
| 206 | + |
| 207 | +* Other types of identity - there is room to expand the `kind` accepted for |
| 208 | + subjects in IdentityBinding to other types of identity. This needs further |
| 209 | + definition to explain use cases and implementation. |
0 commit comments