docs(policies): rework intro page and add concepts #1956
Conversation
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
Have a central concepts page to link from there to different other pages. Change pages to make policies intro docs simpler Signed-off-by: Charly Molter <charly.molter@konghq.com>
lahabana
requested review from
Automaat and
bartsmykla
and removed request for
a team
✅ Deploy Preview for kuma ready!
To edit notification comments on pull requests, go to your Netlify site configuration. |
Signed-off-by: Charly Molter <charly.molter@konghq.com>
|
|
||
| In this page we will introduce concepts that are core to understanding Kuma. | ||
|
|
||
| ## Control-Plane |
There was a problem hiding this comment.
There's no reason to use a hyphen here
|
|
||
| The data-plane handles traffic between services. | ||
| It connects to the control-plane which computes a configuration specific to it. | ||
| The Data-Plane proxy or Sidecar is the instance of Envoy running alongside the data-plane which will send and receive traffic from the rest of the service mesh. |
There was a problem hiding this comment.
or capitalize these words
|
|
||
| Like all [resources](/docs/{{ page.version }}/introduction/concepts#resource) in {{ site.mesh_product_name }}, there are two parts to a policy: | ||
|
|
||
| 1. The metadata |
There was a problem hiding this comment.
imo this list while reading is very bold and grabs your eye for relatively little information content. I think it can be an inline sentence and then we have the sections.
| ``` | ||
|
|
||
| {% warning %} | ||
| Policies are namespaced scope and currently the namespace must be the one the control-plane is running in `{{site.mesh_namespace}}` by default. |
There was a problem hiding this comment.
Suggested change
| Policies are namespaced scope and currently the namespace must be the one the control-plane is running in `{{site.mesh_namespace}}` by default. | |
| Policies are namespace-scoped and currently the namespace must be the one the control-plane is running in. This is `{{site.mesh_namespace}}` by default. |
| Some policies apply to only a subset of the configuration of the proxy. | ||
|
|
||
| - **Inbound policies** apply only to incoming traffic. The `spec.from[].targetRef` field defines the subset of clients that are going to be impacted by this policy. | ||
| - **Outbound policies** apply only to outgoing traffic. The `spec.to[].targetRef` field defines the outbounds that are going to be impacted by this policy |
There was a problem hiding this comment.
"outbounds" as a concept IMO isn't widely defined, we should use "destinations" or similar, like "clients" in the line above.
| - **Inbound policies** apply only to incoming traffic. The `spec.from[].targetRef` field defines the subset of clients that are going to be impacted by this policy. | ||
| - **Outbound policies** apply only to outgoing traffic. The `spec.to[].targetRef` field defines the outbounds that are going to be impacted by this policy | ||
|
|
||
| The actual configuration is defined in a `default` map. |
There was a problem hiding this comment.
Suggested change
| The actual configuration is defined in a `default` map. | |
| The actual configuration is defined under the `default` field. |
|
|
||
| ## Writing a `targetRef` | ||
|
|
||
| `targetRef` is a concept borrowed from [Kubernetes Gateway API](https://gateway-api.sigs.k8s.io/) its usage is fully defined in [MADR 005](https://github.com/kumahq/kuma/blob/master/docs/madr/decisions/005-policy-matching.md). |
There was a problem hiding this comment.
Is this MADR useful/even up to date to link here?
| name: "my-name" # For kinds MeshService, and MeshGateway a name has to be defined | ||
| tags: | ||
| key: value # For kinds MeshSubset and MeshGateway a list of matching tags can be used | ||
| proxyTypes: ["Sidecar", "Gateway"] # For kinds Mesh and MeshSubset a list of matching Dataplanes types can be used |
| The `spec.from[].targetRef` section enables logging for any traffic coming from _anywhere_ in the `Mesh`. | ||
|
|
||
| ### Omitting `targetRef` | ||
| When a `targetRef` is not present. It is semantically equivalent to: `targetRef.kind: Mesh` meaning everything inside the mesh. |
There was a problem hiding this comment.
Suggested change
| When a `targetRef` is not present. It is semantically equivalent to: `targetRef.kind: Mesh` meaning everything inside the mesh. | |
| When a `targetRef` is not present. It is semantically equivalent to `targetRef.kind: Mesh`, meaning everything inside the `Mesh`. |
| ``` | ||
|
|
||
| There is however, one exception to this when using `MeshService` with **outbound** policies (policies with `spec.to[].targetRef`). | ||
| In this case, if you define a policy in the same namespace as the `MeshService` it is defined in a policy will be considered to be a **producer** policy. |
There was a problem hiding this comment.
Suggested change
| In this case, if you define a policy in the same namespace as the `MeshService` it is defined in a policy will be considered to be a **producer** policy. | |
| In this case, if you define a policy in the same namespace as the `MeshService` it is defined in, that policy will be considered a **producer** policy. |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
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.
Have a central concepts page to link from there to different other pages.
Change pages to make policies intro docs simpler