Skip to content
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.

Sign up for GitHub

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

docs(*) ingress annotation #384

Merged
merged 1 commit into from
Mar 8, 2021
Merged

docs(*) ingress annotation #384

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 1 addition & 7 deletions docs/docs/1.0.8/documentation/dps-and-data-model.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -294,11 +294,7 @@ spec:
...
```

The optimal gateway in Kubernetes mode would be Kong. You can use [Kong for Kubernetes](https://github.com/Kong/kubernetes-ingress-controller) to implement authentication, transformations, and other functionalities across Kubernetes clusters with zero downtime. When integrating [Kong for Kubernetes](https://github.com/Kong/kubernetes-ingress-controller) with Kuma you have to annotate every `Service` that you want to pass traffic to with [`ingress.kubernetes.io/service-upstream=true`](https://github.com/Kong/kubernetes-ingress-controller/blob/master/docs/references/annotations.md#ingresskubernetesioservice-upstream) annotation.

:::warning
Failure to apply the `ingress.kubernetes.io/service-upstream=true` annotation will prevent Kuma from taking over the load balancing of the requests and applying policies, therefore it is a required annotation when exposing a Kuma service via a `gateway` data plane proxy.
:::
The optimal gateway in Kubernetes mode would be Kong. You can use [Kong for Kubernetes](https://github.com/Kong/kubernetes-ingress-controller) to implement authentication, transformations, and other functionalities across Kubernetes clusters with zero downtime. Using [Kong for Kubernetes](https://github.com/Kong/kubernetes-ingress-controller) with Kuma requires an annotation on every `Service` that you want to pass traffic to [`ingress.kubernetes.io/service-upstream=true`](https://github.com/Kong/kubernetes-ingress-controller/blob/master/docs/references/annotations.md#ingresskubernetesioservice-upstream). This is automatically injected by Kuma for every Kubernetes service that is in a namespace part of the mesh i.e. has `kuma.io/sidecar-injection: enabled`
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This explanation took me a while to parse -- initially it seems to read as though you add the annotation manually, which makes removing the annotation field from the example yaml seem not right. I had to read carefully several times before I understood what the last sentence was saying (about automatically injecting the annotation). Let's go ahead and merge this, and I'll work on simplifying the explanation in a separate PR (need to go away and think about it some).

I also wonder whether we should be less pushy about Kong gateway, since Kuma is not only OSS but CNCF. Yes we want to explain it, but wdyt softening this tone also? I can include a revision in the PR to clarify the annotation explanation.


Services can be exposed to an API Gateway in one specific zone, or in multi-zone. For the latter, we need to expose a dedicated Kubernetes `Service` object with type `ExternalName`, which sets the `externalName` to the `.mesh` DNS record for the particular service that we want to expose, that will be resolved by Kuma's internal [service discovery](/docs/1.0.8/networking/dns).

Expand All @@ -312,8 +308,6 @@ kind: Service
metadata:
name: frontend
namespace: kuma-demo
annotations:
ingress.kubernetes.io/service-upstream: "true"
spec:
type: ExternalName
externalName: frontend-api.kuma-demo.svc.8080.mesh
Expand Down