mirror of https://github.com/hashicorp/consul
69 lines
3.2 KiB
Plaintext
69 lines
3.2 KiB
Plaintext
|
---
|
||
|
|
layout: docs
|
||
|
|
page_title: Define API gateway routes on Kubernetes
|
||
|
|
description: Learn how to define and attach HTTP and TCP routes to Consul API gateway listeners in Kubernetes-orchestrated networks.
|
||
|
|
---
|
||
|
|
|
||
|
|
# Define API gateway routes on Kubernetes
|
||
|
|
|
||
|
|
This topic describes how to configure HTTP and TCP routes and attach them to Consul API gateway listeners in Kubernetes-orchestrated networks. Routes are rule-based configurations that allow external clients to send requests to services in the mesh. For information
|
||
|
|
|
||
|
|
## Overview
|
||
|
|
|
||
|
|
The following steps describe the general workflow for defining and deploying routes:
|
||
|
|
|
||
|
|
1. Define a route configuration that specifies the protocol type, name of the gateway to attach to, and rules for routing requests.
|
||
|
|
1. Deploy the configuration to create the routes and attach them to the gateway.
|
||
|
|
|
||
|
|
Routes and the gateways they are attached to are eventually-consistent objects. They provide feedback about their current state through a series of status conditions. As a result, you must manually check the route status to determine if the route successfully bound to the gateway.
|
||
|
|
|
||
|
|
## Requirements
|
||
|
|
|
||
|
|
Verify that your environment meets the requirements specified in [Technical specifications for Kubernetes](/consul/docs/connect/gateways/api-gateway/tech-specs).
|
||
|
|
|
||
|
|
### OpenShift
|
||
|
|
|
||
|
|
If your Kubernetes-orchestrated network runs on OpenShift, verify that OpenShift is enabled for your Consul installation. Refer to [OpenShift requirements](/consul/docs/connect/gateways/api-gateway/tech-specs#openshift-requirements) for additional information.
|
||
|
|
|
||
|
|
## Define routes
|
||
|
|
|
||
|
|
Define route configurations and bind them to listeners configured on the gateway so that Consul can route incoming requests to services in the mesh.
|
||
|
|
|
||
|
|
1. Create a configuration file and specify the following fields:
|
||
|
|
|
||
|
|
- `apiVersion`: Specifies the Kuberenetes API gateway version. This must be set to `gateway.networking.k8s.io/v1beta1`
|
||
|
|
- `kind`: Set to `HTTPRoute` or `TCPRoute`.
|
||
|
|
- `metadata.name`: Specify a name for the route. The name is metadata that you can use to reference the configuration when performing Consul operations.
|
||
|
|
- `spec.parentRefs.name`: Specifies a list of API gateways that the route binds to.
|
||
|
|
- `spec. rules`: Specifies a list of routing rules for constructing a routing table that maps listeners to services.
|
||
|
|
|
||
|
|
Refer to the [`Routes` configuration reference](/consul/docs/connect/gateways/api-gateway/configuration/routes) for details about configuring route rules.
|
||
|
|
|
||
|
|
1. Configure any additional fields necessary for your use case, such as the namespace or admin partition.
|
||
|
|
1. Save the configuration.
|
||
|
|
|
||
|
|
The following example creates a route named `example-route` associated with a listener defined in `example-gateway`.
|
||
|
|
|
||
|
|
```yaml
|
||
|
|
apiVersion: gateway.networking.k8s.io/v1beta1
|
||
|
|
kind: HTTPRoute
|
||
|
|
metadata:
|
||
|
|
name: example-route
|
||
|
|
spec:
|
||
|
|
parentRefs:
|
||
|
|
- name: example-gateway
|
||
|
|
rules:
|
||
|
|
- backendRefs:
|
||
|
|
- kind: Service
|
||
|
|
name: echo
|
||
|
|
port: 8080
|
||
|
|
```
|
||
|
|
|
||
|
|
## Deploy the route configuration
|
||
|
|
|
||
|
|
Apply the configuration to your cluster using the `kubectl` command. The following command applies the configuration to the `consul` namespace:
|
||
|
|
|
||
|
|
```shell-session
|
||
|
|
$ kubectl apply -f my-route.yaml -n consul
|
||
|
|
```
|