Ambient policy enforcement #15072

ilrudie · 2024-05-13T20:40:43Z

Description

Adding some information about different ways to apply/target policy and the resulting enforcement locations. This is presently in a deleted doc which I suspect we don't want to introduce this page again so @craigbox would appreciate suggestions as to where we may want to add these.

Alternatively these could be depicted as flow diagrams rather than tables if desired.

Reviewers

dhawton · 2024-05-14T19:09:53Z

/test lint

dhawton

May also want to wrap some of the really long lines

content/en/docs/ambient/usage/policy/index.md

ilrudie · 2024-05-16T19:03:35Z

@linsun, @craigbox I moved some of these sections around to location I think may be more appropriate. content/en/docs/ambient/usage/policy/index.md I think we will delete before merging, it was just a wip location to store some md I didn't yet have a location to land...

linsun · 2024-05-17T13:38:09Z

content/en/docs/ambient/usage/l7-features/index.md

+| no | Selector | Pod | n/a | DENY destination ztunnel |
+| yes | Selector | Pod | n/a | DENY destination ztunnel |
+| no | _empty**_ | Namespace | n/a | DENY destination ztunnel |
+| yes | _empty**_ | Namespace | n/a | DENY destination ztunnel |


Also, I don't understand why source identity is n/a. Wouldnt that be the client or waypoint if it exists?

linsun · 2024-05-17T13:39:22Z

content/en/docs/ambient/usage/l7-features/index.md

+
+* Whether or not there is already a waypoint is in the traffic path.
+
+** If no attachment is specified the policy will be treated as Namespace scoped.


Namespace scoped but only for L4? This is same as line 127 & 128, correct?

It was stated that having a blank cell in the table was confusing so I was trying to convey that if you don't have a selector or targetRef then you get namespace scope enforced at the ztunnel and this extra note was intended to clarify what empty in the cell means. Maybe it's a bad idea or just not worded correctly

I updated the wording of this line to hopefully clarify it a little. Ultimately maybe we should just change _empty**_ though so that a footnote isn't required

linsun · 2024-05-17T13:40:14Z

content/en/docs/ambient/usage/policy/index.md

@@ -0,0 +1,70 @@
+---
+title: Policy enforcement in ambient mode


Is this only Authz policy?

I would like to see this under a page for authz policy vs under usage/policy as if folks don't need authz policy, they don't need to care about this. Or if folks don't need L4 authz policy, they don't need to worry about most of this.

My suggestion is:

this becomes a "Designing authorization policy for ambient mode" guide (or whatever other types of policy are different between L4 and L7 and need consideration)

it is weighted to come after the initial L4/L7 feature introductions

most of the content is here, and the L4/L7 feature introductions link out to this doc.

ok, I thought we were attempting to get rid of a dedicated auth pol page for ambient. I'm ok with having it though.

We got rid of a dedicated page to move policy into the journey of an adopter:

here's how you install

here's how you can do L4 things

here's how you can add on L7 things

We didn't want to leave policy to after you've learned about L7.
However, a page on how you should think about and design policy is a good thing to have, and by the time you get to reading that, you should have understood L4/L7/etc architecturally.

linsun · 2024-05-17T13:41:25Z

content/en/docs/ambient/usage/policy/index.md

+test: no
+---
+
+Istio's ambient data plane splits the data plane into two different sets of components. This architecture allows users to only pay for application layer processing if they need it. The trade-off made is the extra complexity of understanding how traffic flows through this architecture and where policy will be enforced. This guide will introduce a number of broad scenarios and explore the permutations therein and the details to understand for each scenario.


extra complexity - we need to spin positively. flexibility, pay only what you need

I think we just delete this page. Right now it is basically just storing notes.

Ok, maybe good to have dedicated page for authz policy.

linux-foundation-easycla · 2024-05-17T14:56:40Z

The committers listed above are authorized under a signed CLA.

✅ login: craigbox / name: Craig Box (e7a0d68, db04afb, 6926d68, 58ed7b8, e0c92ef, 963f74e, faed98e, d3a8bc7, 9db8740, 52f3aeb, e236f55)
✅ login: ilrudie / name: Ian Rudie (805047e, 0eb6ff2, 6d29e9e, f1ea858, 208b7ca, b840fb4, f2bed33, 03ae934, 3812b0b, fd710e3, 3798972, b4bac3f, 3003c1d, 69d8071, 6fd11ee, 55abb8e, 282abe3, 57b4fa0, 53295d1, 245903d)

craigbox · 2024-05-19T23:46:29Z

Thanks for driving this, Ian!

I've had a look through today and here's what I would recommend:

a dedicated guide on how to design and use policy in an ambient world
a section in the L4 and L7 intro docs with a small amount of information - possibly just the table of situations under which the policy will apply,
each of those sections direct you off to the policy guide.

What you have here is basically that, with some rearrangement. The docs would probably also benefit from some "when and why to do X" docs, which I think @keithmattix was going to have a go at.

If you're interested, I can have a first pass at moving the things around?

content/en/docs/ambient/usage/l4-policy/index.md

content/en/docs/ambient/usage/l7-features/index.md

craigbox · 2024-05-19T23:51:12Z

content/en/docs/ambient/usage/policy/index.md

@@ -0,0 +1,70 @@
+---
+title: Policy enforcement in ambient mode


My suggestion is:

this becomes a "Designing authorization policy for ambient mode" guide (or whatever other types of policy are different between L4 and L7 and need consideration)

it is weighted to come after the initial L4/L7 feature introductions

most of the content is here, and the L4/L7 feature introductions link out to this doc.

content/en/docs/ambient/usage/policy/index.md

craigbox · 2024-05-19T23:54:45Z

content/en/docs/ambient/usage/l7-features/index.md

+| no | Selector | Pod | n/a | DENY destination ztunnel |
+| yes | Selector | Pod | n/a | DENY destination ztunnel |
+| no | _empty**_ | Namespace | n/a | DENY destination ztunnel |
+| yes | _empty**_ | Namespace | n/a | DENY destination ztunnel |


So why is row 2 a DENY?

also, suggest wording update to 'destination ztunnel (always DENY)' so it starts with the actual column heading, which is where it is enforced

craigbox · 2024-05-19T23:57:04Z

content/en/docs/ambient/usage/l4-policy/index.md

@@ -75,6 +75,31 @@ Even though the identity of the pod is otherwise correct, the presence of a L7 p
 command terminated with exit code 56
 {{< /text >}}

+### Authorization policy attachment
+
+In the simplest enforcement scenario, you want to enforce policy against TCP attributes and you have no waypoint proxies in your traffic's path. These policies can be enforced by ztunnel proxies.


I am still not comfortable with the hoops we have to jump through to describe "having a waypoint in your traffic's path"

https://istio.io/latest/docs/ambient/architecture/data-plane/ uses "in mesh" and "in mesh, waypoint enabled" which is close but probably still not how people are going to describe workload configuration.

Thoughts?

Not sure the ideal way to word this if we don't like "no waypoint proxies in your traffic path" which I think is at least fairly clear, if somewhat clunky. I don't really like "waypoint disabled" personally but if that is the project's preferred wording I can change it.

I've never heard "waypoint disabled" but I'd never use that; you don't define Stage 1 of something additive as "Without Stage 2" :)

"In the simplest enforcement scenario, you want to enforce policy against TCP attributes and you are only using the secure L4 overlay. These policies can be enforced by ztunnel proxies."

(Still too wordy.)
Diet Ambient™

craigbox · 2024-05-19T23:58:03Z

content/en/docs/ambient/usage/l4-policy/index.md

+
+In the simplest enforcement scenario, you want to enforce policy against TCP attributes and you have no waypoint proxies in your traffic's path. These policies can be enforced by ztunnel proxies.
+
+Once you introduce a waypoint proxy, the ideal place to enforce policy shifts. Traffic arriving at the destination ztunnel will be coming from the waypoint's identity because waypoint proxies do not impersonate `src` identity on behalf of the client. This means that even if you only wish to enforce policy against TCP attributes, you should bind that policy to your waypoint proxy. An additional TCP policy may be applied to your workload to request that ztunnel enforce rules like, "in-mesh traffic needs to come from my waypoint in order to reach my application". This type of policy allows you to choose if "bypassing" the waypoint proxy is permissible in your scenario.


replace 'be coming' with 'come' or 'appear' or 'is presented as' (to make active voice)

you should bind that policy to your waypoint proxy

Is there any performance penalty? I guess the implication is "it will go through the waypoint anyway, if the PEP is the destination ztunnel"

The point I was trying to make is that if you want to base any of your policy on client identity waypoint is your only real choice. Otherwise even a client called evil-do-not-ever-allow will just look like your waypoint proxy to the dest ztunnel so you can't make a very good decision based on identity anymore.

dhawton · 2024-05-20T17:10:01Z

/easycla

ilrudie · 2024-05-20T17:11:39Z

If you're interested, I can have a first pass at moving the things around?

@craigbox, I invited you as a collaborator on my istio.io fork if you wanna be able to contribute directly to this PR.

craigbox · 2024-05-21T10:26:58Z

If you're interested, I can have a first pass at moving the things around?

@craigbox, I invited you as a collaborator on my istio.io fork if you wanna be able to contribute directly to this PR.

Thanks, in general as a maintainer of Istio I can do that anyway 😊

ilrudie · 2024-05-21T15:03:16Z

Do we want to consider getting the L7 and L4 updates from this PR merged and break writing of the "design and use auth policy" out into it's own PR? I think the updates that exist now may provide value even though they are not the end state

craigbox · 2024-05-22T03:55:57Z

PTAL at these exact links

I am especially concerned as to if the behavior I have written up in the L7 table is true.

jarias-lfx · 2024-05-22T14:08:12Z

/easycla

ilrudie

nice work on rewording and organizing this. Couple of suggestions but overall I think it's an improvement

content/en/docs/ambient/usage/l7-features/index.md

content/en/docs/ambient/usage/l4-policy/index.md

Signed-off-by: ilrudie <[email protected]>

Co-authored-by: Ian Rudie <[email protected]>

craigbox · 2024-05-24T09:41:04Z

PTAL at the entirety of

ilrudie

Looks good overall and likely fine to merge as is if doc maintainers like it. I've added some notes/suggestions mostly for clarity.

ilrudie · 2024-05-28T14:35:03Z

content/en/docs/ambient/usage/l4-policy/index.md


-## Layer 4 authorization policies
+## Policy enforcement using the secure overlay


"secure overlay" hasn't really been introduced, folks may not know what it is?

Suggested change

## Policy enforcement using the secure overlay

## Policy enforcement using ztunnel

See https://istio.io/latest/docs/ambient/overview/#ztunnel and a few other places, as well as the bikeshed thread. We need a way to refer to what you get when ambient is installed with no waypoints, where you don't have to care about the implementation.

content/en/docs/ambient/usage/l4-policy/index.md

ilrudie · 2024-05-28T14:56:14Z

content/en/docs/ambient/usage/l4-policy/index.md

In peer authentication we should probably mention permissive and maybe remove the part about disabling ambient mode all together. "if you need to disable mTLS just don't use Istio" is effectively the last thing we say when practically speaking inbound passthrough via permissive is probably what they would actually want.

I'm not sure how to put that into words sorry, but could we do that in a different PR? It hasn't changed (except I merged in a fix to the formatting)

yeah, I can try to tackle that as a fast follower. I mostly just don't love the idea of an Istio doc ending with "don't use Istio" if we can avoid it.

.spelling

content/en/docs/ambient/usage/l7-features/index.md

mikemorris · 2024-05-30T17:23:50Z

content/en/docs/ambient/usage/l7-features/index.md


 ### 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.


I think it would be helpful to include when/why you would want to do this here - for policies with L7 attributes dependent on the identity of the calling service (as mentioned in the L4 docs under "Choosing enforcement points when waypoints are introduced " - any other specific use cases?) and mention implications for scope and which services are fronted by the waypoint (single service account vs all services in a namespace).

I believe we intend to write such s guide but this doc was scoped down to be useful until that happened.

I kind of stole it off Ian 😁

mikemorris · 2024-05-30T17:26:06Z

content/en/docs/ambient/usage/l7-features/index.md

 {{< /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 or policy to one or more specific services within the waypoint. Set `Service` as the `parentRefs` or `targetRefs` value, as appropriate.


Similar to waypoint attachment above, suggest which policies make sense to attach in this way (HTTPRoute commonly), and which may be impractical (would AuthorizationPolicy perhaps not work as may be expected by a user because the calling identity becomes the waypoint?)

craigbox

It pains me I can do this

ilrudie · 2024-05-30T20:05:56Z

It pains me I can do this

I am reminded of the StarCraft 2 Legacy of the Void intro where the Archon forms and says, "Power overwhelming". Craig the maintainer and Craig the author together has great powers!

Signed-off-by: ilrudie <[email protected]>

istio-testing · 2024-05-30T20:44:01Z

In response to a cherrypick label: new pull request created: #15202

* sync l7 update part * finish translate * fix lint * fix lint

ilrudie requested a review from a team as a code owner May 13, 2024 20:40

istio-policy-bot added area/ambient kind/docs labels May 13, 2024

istio-testing added the size/M Denotes a PR that changes 30-99 lines, ignoring generated files. label May 13, 2024

dhawton added the cherrypick/release-1.22 Set this label on a PR to auto-merge it to the release-1.22 branch label May 14, 2024

dhawton reviewed May 14, 2024

View reviewed changes

istio-testing added size/L Denotes a PR that changes 100-499 lines, ignoring generated files. and removed size/M Denotes a PR that changes 30-99 lines, ignoring generated files. labels May 16, 2024

linsun reviewed May 17, 2024

View reviewed changes

ilrudie force-pushed the ambient-policy-enforcement branch from 321ef22 to a5726f1 Compare May 17, 2024 15:07

craigbox reviewed May 19, 2024

View reviewed changes

ilrudie mentioned this pull request May 20, 2024

Co-authored-by checking fails unexpectedly communitybridge/easycla#4329

Open

17 tasks

ilrudie force-pushed the ambient-policy-enforcement branch 2 times, most recently from 2969715 to 206d2c3 Compare May 20, 2024 21:06

istio-testing added size/M Denotes a PR that changes 30-99 lines, ignoring generated files. and removed size/L Denotes a PR that changes 100-499 lines, ignoring generated files. labels May 22, 2024

ilrudie commented May 22, 2024

View reviewed changes

ilrudie and others added 9 commits May 24, 2024 21:19

lints

805047e

Signed-off-by: ilrudie <[email protected]>

fixing up some missing bits after accepting latest suggestions

3798972

Signed-off-by: ilrudie <[email protected]>

lints

282abe3

Signed-off-by: ilrudie <[email protected]>

revise wording, prep for new doc around creating auth pol

f1ea858

Signed-off-by: ilrudie <[email protected]>

Rewrite L4 and L7 guides; park "how to pick policy" guide work for now

e7a0d68

lint

9db8740

Update content/en/docs/ambient/usage/l4-policy/index.md

e0c92ef

Co-authored-by: Ian Rudie <[email protected]>

refactor and improve L4 and L7 guides

6926d68

Rename waypoints in example

58ed7b8

craigbox force-pushed the ambient-policy-enforcement branch from e7095cc to 58ed7b8 Compare May 24, 2024 09:24

istio-testing removed the needs-rebase Indicates a PR needs to be rebased before being merged label May 24, 2024

craigbox added 3 commits May 24, 2024 21:33

missed a bit

963f74e

fix link. those don't lint locally

d3a8bc7

I'll get that URL right yet

52f3aeb

craigbox added 2 commits May 24, 2024 21:46

missed a link

db04afb

Always a blank space baby, I'll write your name

faed98e

ilrudie commented May 28, 2024

View reviewed changes

craigbox mentioned this pull request May 30, 2024

docs: break apart the ambient getting start guide (WIP) #15168

Merged

14 tasks

mikemorris reviewed May 30, 2024

View reviewed changes

Fixes from code review

e236f55

craigbox approved these changes May 30, 2024

View reviewed changes

lints

245903d

Signed-off-by: ilrudie <[email protected]>

istio-testing merged commit 9191a27 into istio:master May 30, 2024
6 checks passed

istio-testing mentioned this pull request May 30, 2024

[release-1.22] Ambient policy enforcement #15202

Merged

craigbox mentioned this pull request May 30, 2024

update PeerAuthentication docs for ambient #15203

Closed

istio-testing pushed a commit that referenced this pull request May 31, 2024

[zh] Sync #15072 Ambient L7 usage update into Chinese (#15209)

c4e8f53

* sync l7 update part * finish translate * fix lint * fix lint


		* Whether or not there is already a waypoint is in the traffic path.

		** If no attachment is specified the policy will be treated as Namespace scoped.

		@@ -0,0 +1,70 @@
		---
		title: Policy enforcement in ambient mode


		In the simplest enforcement scenario, you want to enforce policy against TCP attributes and you have no waypoint proxies in your traffic's path. These policies can be enforced by ztunnel proxies.

		Once you introduce a waypoint proxy, the ideal place to enforce policy shifts. Traffic arriving at the destination ztunnel will be coming from the waypoint's identity because waypoint proxies do not impersonate `src` identity on behalf of the client. This means that even if you only wish to enforce policy against TCP attributes, you should bind that policy to your waypoint proxy. An additional TCP policy may be applied to your workload to request that ztunnel enforce rules like, "in-mesh traffic needs to come from my waypoint in order to reach my application". This type of policy allows you to choose if "bypassing" the waypoint proxy is permissible in your scenario.


		## Layer 4 authorization policies
		## Policy enforcement using the secure overlay

	## Policy enforcement using the secure overlay
	## Policy enforcement using ztunnel

Ambient policy enforcement #15072

Ambient policy enforcement #15072

Conversation

ilrudie commented May 13, 2024

Description

Reviewers

dhawton commented May 14, 2024

dhawton left a comment

Choose a reason for hiding this comment

ilrudie commented May 16, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

linsun May 17, 2024 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

linux-foundation-easycla bot commented May 17, 2024 • edited

craigbox commented May 19, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

craigbox May 21, 2024 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

dhawton commented May 20, 2024

ilrudie commented May 20, 2024 • edited

craigbox commented May 21, 2024

ilrudie commented May 21, 2024

craigbox commented May 22, 2024

jarias-lfx commented May 22, 2024

ilrudie left a comment

Choose a reason for hiding this comment

craigbox commented May 24, 2024

ilrudie left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

craigbox left a comment

Choose a reason for hiding this comment

ilrudie commented May 30, 2024 • edited

istio-testing commented May 30, 2024

linsun May 17, 2024 •

edited

linux-foundation-easycla bot commented May 17, 2024 •

edited

craigbox May 21, 2024 •

edited

ilrudie commented May 20, 2024 •

edited

ilrudie commented May 30, 2024 •

edited