The built-in gateway is configured using a combination of MeshGateway
, MeshHTTPRoute
and MeshTCPRoute
,
and served by Envoy instances represented by Dataplanes
configured as built-in
gateways. Kuma policies are then used to configure
built-in gateways.
New to Kuma?
Checkout our guide to get quickly started with builtin gateways!
Deploying gateways
The process for deploying built-in gateways is different depending on whether
you’re running in Kubernetes or Universal mode.
For managing gateway instances on Kubernetes, Kuma provides a
MeshGatewayInstance
CRD.
This resource launches kuma-dp
in your cluster.
If you are running a multi-zone Kuma, MeshGatewayInstance
needs to be created in a specific zone, not the global cluster.
See the dedicated section for using built-in gateways on
multi-zone.
This resource manages a Kubernetes Deployment
and Service
suitable for providing service capacity for the MeshGateway
.
Heads up!
In previous versions of Kuma, setting the kuma.io/service
tag directly within a MeshGatewayInstance
resource was used to identify the service. However, this practice is deprecated and no longer recommended for security reasons since Kuma version 2.7.0.
We’ve automatically switched to generating the service name for you based on your MeshGatewayInstance
resource name and namespace (format: {name}_{namespace}_svc
).
apiVersion: kuma.io/v1alpha1
kind: MeshGatewayInstance
metadata:
name: edge-gateway
namespace: default
spec:
replicas: 1
serviceType: LoadBalancer
See the MeshGatewayInstance
docs for more options.
You’ll need to create a Dataplane
object for your gateway:
type: Dataplane
mesh: default
name: gateway-instance-1
networking:
address: 127.0.0.1
gateway:
type: BUILTIN
tags:
kuma.io/service: edge-gateway
Note that this gateway has an identifying kuma.io/service
tag.
Now you need to explicitly run kuma-dp
:
kuma-dp run \
--cp-address=https://localhost:5678/ \
--dns-enabled=false \
--dataplane-token-file=kuma-token-gateway \ # this needs to be generated like for regular Dataplane
--dataplane-file=my-gateway.yaml # the Dataplane resource described above
Using MeshGatewayInstance
is highly recommended. If for any reason you are
unable to use MeshGatewayInstance
to deploy builtin gateways, you can manually create a Deployment
and Service
to manage kuma-dp
instances and forward traffic to them.
Keep in mind however, that you’ll need to keep the listeners of your
MeshGateway
in sync with your Service
.
These instructions will use the resources created by MeshGatewayInstance
with
version 2.6.2 as a
guide but remember to create a MeshGatewayInstance
for your version to configure as
much as you can and use it as a basis for these self-managed resources.
Given a MeshGateway
spec:
spec:
conf:
listeners:
- port: 80
protocol: HTTP
selectors:
- match:
kuma.io/service: demo-app_gateway
Service
The Service
will forward traffic to the kuma-dp
we’ll configure in the next
section. Its ports
need to be in sync with the MeshGateway
listeners
.
metadata:
annotations:
kuma.io/gateway: builtin
name: demo-app-gateway
namespace: kuma-demo
spec:
ports:
- name: "80"
port: 80
protocol: TCP
targetPort: 80
selector:
app: demo-app-gateway
The selector
should match the Pod
template created in the next section.
Deployment
The Deployment
we’ll create will manage running some number of kuma-dp
instances that are configured to serve traffic for your MeshGateway
.
We’ll cover just spec.selector
and spec.template
here because
other parts of the Deployment
can be configured arbitrarily.
Most importantly you’ll need to change:
kuma.io/tags
annotation - must match the MeshGateway
selectors
KUMA_CONTROL_PLANE_CA_CERT
environment variable - can be retrieved with kubectl get secret kuma-tls-cert -n kuma-system -o=jsonpath='{.data.ca\.crt}' | base64 -d
containers[0].image
field - should be the version of Kuma you’re using
Make sure containers[0].resources
is appropriate for your use case.
selector:
matchLabels:
app: demo-app-gateway
template:
metadata:
annotations:
kuma.io/gateway: builtin
kuma.io/mesh: default
kuma.io/tags: '{"kuma.io/service":"demo-app_gateway"}'
creationTimestamp: null
labels:
app: demo-app-gateway
kuma.io/sidecar-injection: disabled
spec:
containers:
- args:
- run
- --log-level=info
- --concurrency=2
env:
- name: INSTANCE_IP
valueFrom:
fieldRef:
apiVersion: v1
fieldPath: status.podIP
- name: KUMA_CONTROL_PLANE_CA_CERT
value: |
-----BEGIN CERTIFICATE-----
MIIDDzCCAfegAwIBAgIQJlMQnmK1ZfnjhDt1KvTvQTANBgkqhkiG9w0BAQsFADAS
MRAwDgYDVQQDEwdrdW1hLWNhMB4XDTI0MDQxNTEyMzkxNFoXDTM0MDQxMzEyMzkx
NFowEjEQMA4GA1UEAxMHa3VtYS1jYTCCASIwDQYJKoZIhvcNAQEBBQADggEPADCC
AQoCggEBALp6skN+nPPRQQ7Z2ZH4eDjcTtKnO/9n/ExM99tRuMgZCdaZe7zp5g6L
1wvdgi3mtOlplplFaYvLlC9QPn6A7TQSCOPd28vhTIqoUhZ4V7yjr54h0bn6wmH+
BdVXgnalXDb+mQtyDF4dvAY3f0QyOQAK3TjRp32OX+dYKsGGWtch1yiIPf7VnWPx
4/K2v4DTjRuDcXg6S0x4GskGZ9zAhR1WJYEa/2uM+XBmy0GmF9INn0WOeje7Jf3c
G5tCd+fPP6qEk5Q+tBVHd7Pz3xfD9TZjIfY1+h00UkpC50n/yE5FDK8aUpR17SUc
QKJUskOivKAqRD1pI9zfhnHBJ2URfbcCAwEAAaNhMF8wDgYDVR0PAQH/BAQDAgKk
MB0GA1UdJQQWMBQGCCsGAQUFBwMBBggrBgEFBQcDAjAPBgNVHRMBAf8EBTADAQH/
MB0GA1UdDgQWBBQRT2hdjPpIt/FzcLJo/EWPFafCQzANBgkqhkiG9w0BAQsFAAOC
AQEAO0Gfe750KCk+gMtBQHfHzEyQocO2qg2JXfZrBP/+rqeozbjXQj0BLYR9NXnp
tLrxJHoBHdeE+TOnTFsxB7IRIkF1njEElKX4DVx7MjZCL1qLeWDuaXQmEgtFoWDM
o4NqPZ4BIyuZZ9IVtYdeod5g5ucRopOP66zWr/RuwKFzdzni79BGaWuA3dNmLWcn
MdsbZ165hdXstF6b48yPFKFrOdGgLpJheSCLlR/6vp5a+pA03fQZ6qV2j2uSqvAm
XYl8Q3CdoI/yAX9p4mxkcYK7xaz0fQTrD/UyGD6l2cXgY90NP6LDAW1oYKHSD7Qc
Y8vutIcexOtJfAdTZ3/GxBxH1Q==
-----END CERTIFICATE-----
- name: KUMA_CONTROL_PLANE_URL
value: https://kuma-control-plane.kuma-system:5678
- name: KUMA_DATAPLANE_DRAIN_TIME
value: 30s
- name: KUMA_DATAPLANE_MESH
value: default
- name: KUMA_DATAPLANE_RUNTIME_TOKEN_PATH
value: /var/run/secrets/kubernetes.io/serviceaccount/token
- name: KUMA_DNS_CORE_DNS_BINARY_PATH
value: coredns
- name: KUMA_DNS_CORE_DNS_EMPTY_PORT
value: "15054"
- name: KUMA_DNS_CORE_DNS_PORT
value: "15053"
- name: KUMA_DNS_ENABLED
value: "true"
- name: KUMA_DNS_ENABLE_LOGGING
value: "false"
- name: KUMA_DNS_ENVOY_DNS_PORT
value: "15055"
- name: POD_NAME
valueFrom:
fieldRef:
apiVersion: v1
fieldPath: metadata.name
- name: POD_NAMESPACE
valueFrom:
fieldRef:
apiVersion: v1
fieldPath: metadata.namespace
- name: KUMA_DATAPLANE_RESOURCES_MAX_MEMORY_BYTES
valueFrom:
resourceFieldRef:
containerName: kuma-gateway
divisor: "0"
resource: limits.memory
image: docker.io/kumahq/kuma-dp:2.6.2
livenessProbe:
failureThreshold: 12
httpGet:
path: /ready
port: 9901
scheme: HTTP
initialDelaySeconds: 60
periodSeconds: 5
successThreshold: 1
timeoutSeconds: 3
name: kuma-gateway
readinessProbe:
failureThreshold: 12
httpGet:
path: /ready
port: 9901
scheme: HTTP
initialDelaySeconds: 1
periodSeconds: 5
successThreshold: 1
timeoutSeconds: 3
resources:
limits:
cpu: "1"
ephemeral-storage: 1G
memory: 512Mi
requests:
cpu: 50m
ephemeral-storage: 50M
memory: 64Mi
securityContext:
allowPrivilegeEscalation: false
runAsGroup: 5678
runAsUser: 5678
volumeMounts:
- mountPath: /tmp
name: tmp
securityContext:
sysctls:
- name: net.ipv4.ip_unprivileged_port_start
value: "0"
volumes:
- emptyDir: {}
name: tmp
Multi-zone
The Kuma Gateway resource types, MeshGateway
, MeshHTTPRoute
and MeshTCPRoute
, are synced across zones by the Kuma control plane.
If you have a multi-zone deployment, follow existing Kuma practice and create any Kuma Gateway resources in the global control plane.
Once these resources exist, you can provision serving capacity in the zones where it is needed by deploying built-in gateway Dataplanes
(in Universal zones) or MeshGatewayInstances
(Kubernetes zones).
See the
multi-zone docs
for a
refresher.