mirror of https://github.com/istio/istio.io.git
[release-1.22] Ambient policy enforcement (#15202)
* real basic layout Signed-off-by: Ian Rudie <ian.rudie@solo.io> * figuring out a table for different enforcements Signed-off-by: Ian Rudie <ian.rudie@solo.io> * updated table contents Signed-off-by: Ian Rudie <ian.rudie@solo.io> * cleanup and refine tables Signed-off-by: Ian Rudie <ian.rudie@solo.io> * adding mermaid diagram Signed-off-by: Ian Rudie <ian.rudie@solo.io> * Apply suggestions from code review Fixes from review! Co-authored-by: Daniel Hawton <daniel.hawton@solo.io> * TargetRef changed to targetRefs Signed-off-by: Ian Rudie <ian.rudie@solo.io> * adding targetRefs to dictionary Signed-off-by: Ian Rudie <ian.rudie@solo.io> * remove targetRefs from dict, back tick targetRefs in tables Signed-off-by: Ian Rudie <ian.rudie@solo.io> * move attachement into better locations Signed-off-by: Ian Rudie <ian.rudie@solo.io> * lints Signed-off-by: Ian Rudie <ian.rudie@solo.io> * update formatting of footnotes Signed-off-by: Ian Rudie <ian.rudie@solo.io> * update wording of namespace scope footnote Signed-off-by: Ian Rudie <ian.rudie@solo.io> * lints Signed-off-by: Ian Rudie <ian.rudie@solo.io> * Apply suggestions from code review Improvements from review Co-authored-by: Craig Box <craig.box@gmail.com> * lints Signed-off-by: ilrudie <ian.rudie@solo.io> * fixing up some missing bits after accepting latest suggestions Signed-off-by: ilrudie <ian.rudie@solo.io> * lints Signed-off-by: ilrudie <ian.rudie@solo.io> * revise wording, prep for new doc around creating auth pol Signed-off-by: ilrudie <ian.rudie@solo.io> * Rewrite L4 and L7 guides; park "how to pick policy" guide work for now * lint * Update content/en/docs/ambient/usage/l4-policy/index.md Co-authored-by: Ian Rudie <ilrudie@gmail.com> * refactor and improve L4 and L7 guides * Rename waypoints in example * missed a bit * fix link. those don't lint locally * I'll get that URL right yet * missed a link * Always a blank space baby, I'll write your name * Fixes from code review * lints Signed-off-by: ilrudie <ian.rudie@solo.io> --------- Signed-off-by: Ian Rudie <ian.rudie@solo.io> Signed-off-by: ilrudie <ian.rudie@solo.io> Co-authored-by: Ian Rudie <ian.rudie@solo.io> Co-authored-by: Ian Rudie <ilrudie@gmail.com> Co-authored-by: Daniel Hawton <daniel.hawton@solo.io> Co-authored-by: Craig Box <craig.box@gmail.com>
This commit is contained in:
Istio Automation
GitHub
parent
2007865007
commit
799e36d3d7
|
|
@ -767,6 +767,7 @@ metadata
|
|||
MetalLB
|
||||
MetaProtocol
|
||||
metaprotocol
|
||||
metaresources
|
||||
MiB
|
||||
MicroK8s
|
||||
microservice
|
||||
|
|
|
|||
|
|
@ -6,17 +6,13 @@ owner: istio/wg-networking-maintainers
|
|||
test: no
|
||||
---
|
||||
|
||||
The layering of {{< gloss >}}ztunnel{{< /gloss >}} and {{< gloss >}}waypoint{{< /gloss >}} proxies in Istio's ambient mode gives you a choice on whether or not you want to enable Layer 7 (L7) processing for a given workload.
|
||||
The Layer 4 (L4) features of Istio's [security policies](/docs/concepts/security) are supported by {{< gloss >}}ztunnel{{< /gloss >}}, and are available in {{< gloss "ambient" >}}ambient mode{{< /gloss >}}. [Kubernetes Network Policies](https://kubernetes.io/docs/concepts/services-networking/network-policies/) also continue to work if your cluster has a {{< gloss >}}CNI{{< /gloss >}} plugin that supports them, and can be used to provide defense-in-depth.
|
||||
|
||||
The Layer 4 (L4) features of Istio's [security policies](/docs/concepts/security) are supported by ztunnel, and are available in ambient mode. [Kubernetes Network Policies](https://kubernetes.io/docs/concepts/services-networking/network-policies/) also continue to work if your cluster has a {{< gloss >}}CNI{{< /gloss >}} plugin that supports them, and can be used to provide defense-in-depth.
|
||||
The layering of ztunnel and {{< gloss "waypoint" >}}waypoint proxies{{< /gloss >}} gives you a choice as to whether or not you want to enable Layer 7 (L7) processing for a given workload. To use L7 policies, and Istio's traffic routing features, you can [deploy a waypoint](/docs/ambient/usage/waypoint) for your workloads. Because policy can now be enforced in two places, there are [considerations](#considerations) that need to be understood.
|
||||
|
||||
To use L7 policies, and Istio's traffic routing features, you can [deploy a waypoint](/docs/ambient/usage/waypoint) for your workloads.
|
||||
## Policy enforcement using ztunnel
|
||||
|
||||
## Layer 4 authorization policies
|
||||
|
||||
The ztunnel proxy performs authorization policy enforcement when a workload is enrolled in secure overlay mode.
|
||||
|
||||
The actual enforcement point is at the receiving (server-side) ztunnel proxy in the path of a connection.
|
||||
The ztunnel proxy can perform authorization policy enforcement when a workload is enrolled in {{< gloss "Secure L4 Overlay" >}}secure overlay mode{{< /gloss >}}. The enforcement point is the receiving (server-side) ztunnel proxy in the path of a connection.
|
||||
|
||||
A basic L4 authorization policy looks like this:
|
||||
|
||||
|
|
@ -35,21 +31,44 @@ spec:
|
|||
- source:
|
||||
principals:
|
||||
- cluster.local/ns/ambient-demo/sa/sleep
|
||||
EOF
|
||||
{{< /text >}}
|
||||
|
||||
The behavior of the L4 `AuthorizationPolicy` API has the same functional behavior in Istio ambient mode as in sidecar mode. When there is no `AuthorizationPolicy` provisioned, then the default action is `ALLOW`. Once a policy is provisioned, pods matching the selector in the policy only allow traffic which is explicitly allowed. In this example, pods with the label `app: httpbin` only allow traffic from sources with an identity principal of `cluster.local/ns/ambient-demo/sa/sleep`. Traffic from all other sources will be denied.
|
||||
This policy can be used in both {{< gloss "sidecar" >}}sidecar mode{{< /gloss >}} and ambient mode.
|
||||
|
||||
### Layer 7 authorization policies without waypoints installed
|
||||
The L4 (TCP) features of the Istio `AuthorizationPolicy` API have the same functional behavior in ambient mode as in sidecar mode. When there is no authorization policy provisioned, the default action is `ALLOW`. Once a policy is provisioned, pods targeted by the policy only permit traffic which is explicitly allowed. In the above example, pods with the label `app: httpbin` only permit traffic from sources with an identity principal of `cluster.local/ns/ambient-demo/sa/sleep`. Traffic from all other sources will be denied.
|
||||
|
||||
{{< warning >}}
|
||||
If an `AuthorizationPolicy` has been configured that requires any traffic processing beyond L4, and if no waypoint proxies are configured for the destination of the traffic, then ztunnel proxy will simply drop all traffic as a defensive move. Hence, check to ensure that either all rules involve L4 processing only or else if non-L4 rules are unavoidable, that waypoint proxies are configured.
|
||||
{{< /warning >}}
|
||||
## Targeting policies
|
||||
|
||||
Sidecar mode and L4 policies in ambient are *targeted* in the same fashion: they are scoped by the namespace in which the policy object resides, and an optional `selector` in the `spec`. If the policy is in the Istio root namespace (traditionally `istio-system`), then it will target all namespaces. If it is in any other namespace, it will target only that namespace.
|
||||
|
||||
L7 policies in ambient mode are enforced by waypoints, which are configured with the {{< gloss "gateway api" >}}Kubernetes Gateway API{{< /gloss >}}. They are *attached* using the `targetRef` field.
|
||||
|
||||
## Allowed policy attributes
|
||||
|
||||
Authorization policy rules can contain [source](/docs/reference/config/security/authorization-policy/#Source) (`from`), [operation](/docs/reference/config/security/authorization-policy/#Operation) (`to`), and [condition](/docs/reference/config/security/authorization-policy/#Condition) (`when`) clauses.
|
||||
|
||||
This list of attributes determines whether a policy is considered L4-only:
|
||||
|
||||
| Type | Attribute | Positive match | Negative match |
|
||||
| --- | --- | --- | --- |
|
||||
| Source | Peer identity | `principals` | `notPrincipals` |
|
||||
| Source | Namespace | `namespaces` | `notNamespaces` |
|
||||
| Source | IP block | `ipBlocks` | `notIpBlocks` |
|
||||
| Operation | Destination port | `ports` | `notPorts` |
|
||||
| Condition | Source IP | `source.ip` | n/a |
|
||||
| Condition | Source namespace | `source.namespace` | n/a |
|
||||
| Condition | Source identity | `source.principal` | n/a |
|
||||
| Condition | Remote IP | `destination.ip` | n/a |
|
||||
| Condition | Remote port | `destination.port` | n/a |
|
||||
|
||||
### Policies with Layer 7 conditions
|
||||
|
||||
The ztunnel cannot enforce L7 policies. If a policy with rules matching L7 attributes (i.e. those not listed in the table above) is targeted such that it will be enforced by a receiving ztunnel, it will fail safe by becoming a `DENY` policy.
|
||||
|
||||
This example adds a check for the HTTP GET method:
|
||||
|
||||
{{< text yaml >}}
|
||||
apiVersion: security.istio.io/v1beta1
|
||||
apiVersion: security.istio.io/v1
|
||||
kind: AuthorizationPolicy
|
||||
metadata:
|
||||
name: allow-sleep-to-httpbin
|
||||
|
|
@ -69,12 +88,22 @@ spec:
|
|||
EOF
|
||||
{{< /text >}}
|
||||
|
||||
Even though the identity of the pod is otherwise correct, the presence of a L7 policy, and the traffic not originating from a waypoint proxy, causes the ztunnel to deny the connection:
|
||||
Even if the identity of the client pod is correct, the presence of a L7 attribute causes the ztunnel to deny the connection:
|
||||
|
||||
{{< text plain >}}
|
||||
command terminated with exit code 56
|
||||
{{< /text >}}
|
||||
|
||||
## Choosing enforcement points when waypoints are introduced {#considerations}
|
||||
|
||||
When a waypoint proxy is added to a workload, you now have two possible places where you can enforce L4 policy. (L7 policy can only be enforced at the waypoint proxy.)
|
||||
|
||||
With only the secure overlay, traffic appears at the destination ztunnel with the identity of the *source* workload.
|
||||
|
||||
Waypoint proxies do not impersonate the identity of the source workload. Once you have introduced a waypoint to the traffic path, the destination ztunnel will see traffic with the *waypoint's* identity, not the source identity.
|
||||
|
||||
This means that when you have a waypoint installed, **the ideal place to enforce policy shifts**. Even if you only wish to enforce policy against L4 attributes, if you are dependent on the source identity, you should attach your policy to your waypoint proxy. A second policy may be targeted at your workload to make its ztunnel enforce policies like "in-mesh traffic must come from my waypoint in order to reach my application".
|
||||
|
||||
## Peer authentication
|
||||
|
||||
Istio's [peer authentication policies](/docs/concepts/security/#peer-authentication), which configure mutual TLS (mTLS) modes, are supported by ztunnel.
|
||||
|
|
|
|||
|
|
@ -6,36 +6,51 @@ owner: istio/wg-networking-maintainers
|
|||
test: no
|
||||
---
|
||||
|
||||
By adding a waypoint proxy to your traffic flow you can enable more of [Istio's features](/docs/concepts).
|
||||
|
||||
Ambient mode supports configuring waypoints using the Kubernetes Gateway API. Configurations that apply to a Gateway API are called _policies_.
|
||||
By adding a waypoint proxy to your traffic flow you can enable more of [Istio's features](/docs/concepts). Waypoints are configured using the {{< gloss "gateway api" >}}Kubernetes Gateway API{{< /gloss >}}.
|
||||
|
||||
{{< warning >}}
|
||||
The Istio classic traffic management APIs (virtual service, destination rules etc) remain at Alpha in the ambient data plane mode.
|
||||
The Istio classic traffic management APIs (virtual service, destination rules etc) remain at Alpha when used with the ambient data plane mode.
|
||||
|
||||
Mixing Istio classic API and Gateway API configuration is not supported, and will lead to undefined behavior.
|
||||
{{< /warning >}}
|
||||
|
||||
## Route and policy attachment
|
||||
|
||||
The Gateway API defines the relationship between objects (such as routes and gateways) in terms of *attachment*.
|
||||
|
||||
* Route objects (such as [HTTPRoute](https://gateway-api.sigs.k8s.io/api-types/httproute/)) include a way to reference the **parent** resources it wants to attach to.
|
||||
* Policy objects are considered [*metaresources*](https://gateway-api.sigs.k8s.io/geps/gep-713/): objects that augments the behavior of a **target** object in a standard way.
|
||||
|
||||
The tables below show the type of attachment that is configured for each object.
|
||||
|
||||
## Traffic routing
|
||||
|
||||
With a waypoint proxy deployed, you can use the following API types:
|
||||
With a waypoint proxy deployed, you can use the following traffic route types:
|
||||
|
||||
| Name | Feature Status | Attachment |
|
||||
| --- | --- | --- |
|
||||
| `HTTPRoute` | Beta | `parentRefs` |
|
||||
| `TCPRoute` | Alpha | `parentRefs` |
|
||||
| `TLSRoute` | Alpha | `parentRefs` |
|
||||
| [`HTTPRoute`](https://gateway-api.sigs.k8s.io/guides/http-routing/) | Beta | `parentRefs` |
|
||||
| [`TLSRoute`](https://gateway-api.sigs.k8s.io/guides/tls) | Alpha | `parentRefs` |
|
||||
| [`TCPRoute`](https://gateway-api.sigs.k8s.io/guides/tcp/) | Alpha | `parentRefs` |
|
||||
|
||||
Refer to the [traffic management](/docs/tasks/traffic-management/) documentation to see the range of features that can be implemented using these routes.
|
||||
|
||||
## Security
|
||||
|
||||
Without a waypoint installed, you can only use [Layer 4 security policies](/docs/ambient/usage/l4-policy/). By adding a waypoint, you gain access to the following policies:
|
||||
Without a waypoint installed, you can only use [Layer 4 security policies](/docs/ambient/usage/l4-policy/). By adding a waypoint, you gain access to the following policies:
|
||||
|
||||
| Name | Feature Status | Attachment |
|
||||
| --- | --- | --- |
|
||||
| `AuthorizationPolicy` (including L7 features) | Beta | `targetRefs` |
|
||||
| `RequestAuthentication` | Beta | `targetRefs` |
|
||||
| [`AuthorizationPolicy`](/docs/reference/config/security/authorization-policy/) (including L7 features) | Beta | `targetRefs` |
|
||||
| [`RequestAuthentication`](/docs/reference/config/security/request_authentication/) | Beta | `targetRefs` |
|
||||
|
||||
### Considerations for authorization policies {#considerations}
|
||||
|
||||
In ambient mode, authorization policies can either be *targeted* (for ztunnel enforcement) or *attached* (for waypoint enforcement). For an authorization policy to be attached to a waypoint it must have a `targetRef` which refers to the waypoint, or a Service which uses that waypoint.
|
||||
|
||||
The ztunnel cannot enforce L7 policies. If a policy with rules matching L7 attributes is targeted with a workload selector (rather than attached with a `targetRef`), such that it is enforced by a ztunnel, it will fail safe by becoming a `DENY` policy.
|
||||
|
||||
See [the L4 policy guide](/docs/ambient/usage/l4-policy/) for more information, including when to attach policies to waypoints for TCP-only use cases.
|
||||
|
||||
## Observability
|
||||
|
||||
|
|
@ -43,35 +58,38 @@ The [full set of Istio traffic metrics](/docs/reference/config/metrics/) are exp
|
|||
|
||||
## Extension
|
||||
|
||||
As the waypoint proxy is a deployment of {{< gloss >}}Envoy{{< /gloss >}}, the extension mechanisms that are available for Envoy in {{< gloss >}}sidecar{{< /gloss >}} mode are also available to waypoint proxies.
|
||||
As the waypoint proxy is a deployment of {{< gloss >}}Envoy{{< /gloss >}}, the extension mechanisms that are available for Envoy in {{< gloss "sidecar">}}sidecar mode{{< /gloss >}} are also available to waypoint proxies.
|
||||
|
||||
| Name | Feature Status | Attachment |
|
||||
| --- | --- | --- |
|
||||
| `WasmPlugin` | Alpha | `targetRefs` |
|
||||
| `WasmPlugin` † | Alpha | `targetRefs` |
|
||||
| `EnvoyFilter` | Alpha | `targetRefs` |
|
||||
|
||||
Read more on how to extend waypoints with Wasm plugins [here](/docs/ambient/usage/extend-waypoint-wasm/).
|
||||
† [Read more on how to extend waypoints with WebAssembly plugins](/docs/ambient/usage/extend-waypoint-wasm/).
|
||||
|
||||
## Targeting policies or routing rules
|
||||
Extension configurations are considered policy by the Gateway API definition.
|
||||
|
||||
## Scoping routes or policies
|
||||
|
||||
A route or policy can be scoped to apply to all traffic traversing a waypoint proxy, or only specific services.
|
||||
|
||||
### Attach to the entire waypoint proxy
|
||||
|
||||
To attach a policy or routing rule to the entire waypoint — so that it applies to all traffic enrolled to use it — set `Gateway` as the `parentRefs` or `targetRefs` value, depending on the type.
|
||||
To attach a route or a policy to the entire waypoint — so that it applies to all traffic enrolled to use it — set `Gateway` as the `parentRefs` or `targetRefs` value, depending on the type.
|
||||
|
||||
For example, to apply an `AuthorizationPolicy` policy to the waypoint named `waypoint` for the `default` namespace:
|
||||
To scope an `AuthorizationPolicy` policy to apply to the waypoint named `default` for the `default` namespace:
|
||||
|
||||
{{< text bash >}}
|
||||
$ kubectl apply -f - <<EOF
|
||||
apiVersion: security.istio.io/v1beta1
|
||||
{{< text yaml >}}
|
||||
apiVersion: security.istio.io/v1
|
||||
kind: AuthorizationPolicy
|
||||
metadata:
|
||||
name: viewer
|
||||
name: view-only
|
||||
namespace: default
|
||||
spec:
|
||||
targetRefs:
|
||||
- kind: Gateway
|
||||
group: gateway.networking.k8s.io
|
||||
name: waypoint
|
||||
name: default
|
||||
action: ALLOW
|
||||
rules:
|
||||
- from:
|
||||
|
|
@ -80,21 +98,20 @@ spec:
|
|||
to:
|
||||
- operation:
|
||||
methods: ["GET"]
|
||||
EOF
|
||||
{{< /text >}}
|
||||
|
||||
### Attach to a specific service
|
||||
|
||||
You can also attach a policy or routing rule to a specific service within the waypoint. Set `Service` as the `parentRefs` or `targetRefs` value, as appropriate.
|
||||
You can also attach a route to one or more specific services within the waypoint. Set `Service` as the `parentRefs` or `targetRefs` value, as appropriate.
|
||||
|
||||
The example below shows how to apply the `reviews` HTTPRoute to the `reviews` service in the `default` namespace:
|
||||
To apply the `reviews` HTTPRoute to the `reviews` service in the `default` namespace:
|
||||
|
||||
{{< text bash >}}
|
||||
$ kubectl apply -f - <<EOF
|
||||
apiVersion: gateway.networking.k8s.io/v1beta1
|
||||
{{< text yaml >}}
|
||||
apiVersion: gateway.networking.k8s.io/v1
|
||||
kind: HTTPRoute
|
||||
metadata:
|
||||
name: reviews
|
||||
namespace: default
|
||||
spec:
|
||||
parentRefs:
|
||||
- group: ""
|
||||
|
|
@ -109,5 +126,4 @@ spec:
|
|||
- name: reviews-v2
|
||||
port: 9080
|
||||
weight: 10
|
||||
EOF
|
||||
{{< /text >}}
|
||||
|
|
|
|||
|
|
@ -0,0 +1,6 @@
|
|||
---
|
||||
title: Gateway API
|
||||
test: n/a
|
||||
---
|
||||
|
||||
The [Kubernetes Gateway API](https://gateway-api.sigs.k8s.io/) is a configuration API for traffic routing in Kubernetes. It represents the next generation of Kubernetes ingress, load balancing, and service mesh APIs, and is designed with learnings from Istio's traditional APIs.
|
||||
|
|
@ -4,4 +4,4 @@ test: n/a
|
|||
---
|
||||
|
||||
HBONE (or HTTP-Based Overlay Network Environment) is a secure tunneling protocol used between Istio components.
|
||||
[Learn more about HBONE](/docs/ambient/architecture/hbone/)
|
||||
[Learn more about HBONE](/docs/ambient/architecture/hbone/).
|
||||
|
|
|
|||
|
|
@ -0,0 +1,6 @@
|
|||
---
|
||||
title: Secure L4 Overlay
|
||||
test: n/a
|
||||
---
|
||||
|
||||
The term "secure overlay" or "secure L4 overlay" is used to collectively describe the set of L4 networking functions implemented in an ambient mesh via the ztunnel proxy. At the transport layer, this is implemented via an HTTP CONNECT-based traffic tunneling protocol called [HBONE](/docs/reference/glossary/#hbone).
|
||||
Loading…
Reference in New Issue