-
Notifications
You must be signed in to change notification settings - Fork 212
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
add top-level HTTPRoute features doc #1657
Merged
Merged
Changes from 4 commits
Commits
Show all changes
9 commits
Select commit
Hold shift + click to select a range
274eb29
add top-level HTTPRoute features doc
hawkw 71281d7
links 'n' stuff
hawkw 16b7e37
markdownlint
hawkw 7485389
mardkownlint
hawkw 14ce2a0
trailing slash
hawkw 119c896
Update linkerd.io/content/2-edge/tasks/configuring-timeouts.md
hawkw a2b19e1
s/CRDs/CRs
hawkw 3f5b04e
reword warning
hawkw d129165
Apply suggestions from @kflynn
hawkw File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,62 @@ | ||
+++ | ||
title = "HTTPRoutes" | ||
description = "Linkerd can use the HTTPRoute resource to configure per-route policies." | ||
aliases = [ | ||
"../httproutes/" | ||
] | ||
+++ | ||
|
||
To configure routing behavior and policy for HTTP traffic, Linkerd supports the | ||
[HTTPRoute resource], defined by the Kubernetes [Gateway API]. | ||
|
||
An HTTPRoute is a Kubernetes resource which attaches to a parent resource, such | ||
as a [Service]. The HTTPRoute defines a set of rules which match HTTP requests | ||
to that resource, based on parameters such as the request's path, method, and | ||
headers, and can configure how requests matching that rule are routed by the | ||
Linkerd service mesh. | ||
|
||
Two types of HTTPRoute are used for configuring the behavior of Linkerd's | ||
proxies: | ||
|
||
- HTTPRoutes with a [Service] as their parent resource configure policies for | ||
_outbound_ proxies in pods which are clients of that [Service]. Outbound | ||
policy includes [dynamic request routing][dyn-routing], adding request | ||
headers, modifying a request's path, and reliability features such as | ||
[timeouts]. | ||
- HTTPRoutes with a [Server] as their parent resource configure policy for | ||
_inbound_ proxies in pods which recieve traffic to that [Server]. Inbound | ||
HTTPRoutes are used to configure fine-grained [per-route authorization and | ||
authentication policies][auth-policy]. | ||
|
||
{{< warning >}} | ||
Outbound HTTPRoutes are **incompatible with ServiceProfiles**. If a | ||
[ServiceProfile](../service-profiles/) is defined for the parent | ||
Service of an HTTPRoute, proxies will use the ServiceProfile configuration, | ||
rather than the HTTPRoute configuration, as long as the ServiceProfile | ||
exists. | ||
{{< /warning >}} | ||
|
||
To get started with HTTPRoutes, you can: | ||
|
||
<!-- TODO(eliza): add this link once the timeout doc discusses HTTPRoutes... | ||
- [Configure timeouts][timeouts] using an outbound HTTPRoute. | ||
--> | ||
<!-- TODO(eliza): add this link once the fault injection doc discusses | ||
HTTPRoutes... | ||
- [Configure fault injection](../../tasks/fault-injection/) using an outbound | ||
HTTPRoute. | ||
--> | ||
|
||
- [Configure dynamic request routing][dyn-routing] using an outbound HTTPRoute. | ||
- [Configure per-route authorization policy][auth-policy] using an inbound | ||
HTTPRoute. | ||
- See the [reference documentation](../../reference/httproute) for a complete | ||
description of the HTTPRoute resource. | ||
|
||
[HTTPRotue resource]: https://gateway-api.sigs.k8s.io/api-types/httproute/ | ||
hawkw marked this conversation as resolved.
Show resolved
Hide resolved
|
||
[Gateway API]: https://gateway-api.sigs.k8s.io/ | ||
[Service]: https://kubernetes.io/docs/concepts/services-networking/service/ | ||
[Server]: ../../reference/authorization-policy/#server | ||
[auth-policy]: ../../tasks/configuring-per-route-policy/ | ||
[dyn-routing]:../../tasks/configuring-dynamic-request-routing/ | ||
[timeouts]: ../../tasks/configuring-dynamic-request-routing/ |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -70,8 +70,8 @@ the fly. | |
Two policy CRDs represent "targets" for policy: subsets of traffic over which | ||
policy can be applied. | ||
|
||
- `Server`: all traffic to a port, for a set of pods in a namespace | ||
- `HTTPRoute`: a subset of HTTP requests for a `Server` | ||
- [`Server`]: all traffic to a port, for a set of pods in a namespace | ||
- [`HTTPRoute`]: a subset of HTTP requests for a [`Server`] | ||
|
||
Two policy CRDs represent authentication rules that must be satisfied as part of | ||
a policy rule: | ||
|
@@ -87,11 +87,11 @@ authentication rules to targets. | |
unless an authentication rule is met | ||
|
||
- `ServerAuthorization`: an earlier form of policy that restricts access to | ||
`Servers` only (i.e. not `HTTPRoutes`) | ||
[`Server`s] only (i.e. not [`HTTPRoute`]s) | ||
hawkw marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
||
The general pattern for Linkerd's dynamic, fine-grained policy is to define the | ||
traffic target that must be protected (via a combination of `Server` and | ||
`HTTPRoute` CRs); define the types of authentication that are required before | ||
[`HTTPRoute`] CRDs); define the types of authentication that are required before | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. was this change from CR to CRDs intentional? There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. i thought this was a typo, but I think it's not actually...i'll undo this change! |
||
access to that traffic is permitted (via `MeshTLSAuthentication` and | ||
`NetworkAuthentication`); and then define the policy that maps authentication to | ||
target (via an `AuthorizationPolicy`). | ||
|
@@ -102,7 +102,7 @@ details on how these resources work. | |
## ServerAuthorization vs AuthorizationPolicy | ||
|
||
Linkerd 2.12 introduced `AuthorizationPolicy` as a more flexible alternative to | ||
`ServerAuthorization` that can target `HTTPRoute`s as well as `Server`s. Use of | ||
`ServerAuthorization` that can target [`HTTPRoute`]s as well as `Server`s. Use of | ||
`AuthorizationPolicy` is preferred, and `ServerAuthorization` will be deprecated | ||
in future releases. | ||
|
||
|
@@ -113,9 +113,9 @@ from Kubernetes, meaning that the pod would not be able to start. Thus, any | |
default-deny setup must, in practice, still authorize these probes. | ||
|
||
In order to simplify default-deny setups, Linkerd automatically authorizes | ||
probes to pods. These default authorizations apply only when no `Server` is | ||
configured for a port, or when a `Server` is configured but no `HTTPRoutes` are | ||
configured for that `Server`. If any `HTTPRoute` matches the `Server`, these | ||
probes to pods. These default authorizations apply only when no [`Server`] is | ||
configured for a port, or when a [`Server`] is configured but no [`HTTPRoute`]s are | ||
configured for that [`Server`]. If any [`HTTPRoute`] matches the `Server`, these | ||
hawkw marked this conversation as resolved.
Show resolved
Hide resolved
|
||
automatic authorizations are not created and you must explicitly create them for | ||
health and readiness probes. | ||
|
||
|
@@ -132,3 +132,6 @@ result in an abrupt termination of those connections. | |
|
||
- [Policy reference](../../reference/authorization-policy/) | ||
- [Guide to configuring per-route policy](../../tasks/configuring-per-route-policy/) | ||
|
||
[`HTTPRoute`]: ../httproute/ | ||
[`Server`]: ../../reference/authorization-policy/#server |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
2 changes: 1 addition & 1 deletion
2
linkerd.io/content/2-edge/tasks/configuring-per-route-policy.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
If this is a temporary situation, I would call it out as such and say that this will be fixed in the future. If this is a permanent situation, I would say that ServiceProfiles override HTTPRoute behavior rather than saying they're incompatible, which to me suggests that something will break.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
i'm happy to reword this. i should mention, though, that the text of this warning is copied from other docs pages --- do you think it makes sense to also apply the same change to other instances of this warning box in the docs?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@wmorgan what do you think of the wording in 3f5b04e ? I'm happy to make the same change to other warnings if you like that language!
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I'm good with that wording, there and elsewhere. Not really sure whether this should be a warning vs an info block, but I'll leave that to you. Thank you