Installing Consul API Gateway

This topic describes how to use the Consul API Gateway add-on module. It includes instructions for installation and configuration.

Requirements

Ensure that the environment you are deploying Consul API Gateway in meets the requirements listed in the Technical Specifications. This includes validating that the requirements for minimum versions of software are met. See the Release Notes for the version of API Gateway you are deploying.

Installation

Version reference convention: Replace VERSION in command and configuration examples with the Consul API Gateway version you are installing, such as 0.3.0. In some instances, VERSION is prepended with a lowercase v. This indicates that you must include the v as is part of the version, for example v0.3.0.

1. Issue the following command to install the CRDs:

   $ kubectl apply --kustomize="github.com/hashicorp/consul-api-gateway/config/crd?ref=vVERSION"

   $ kubectl apply --kustomize="github.com/hashicorp/consul-api-gateway/config/crd?ref=vVERSION"

2. Create a values.yaml file for your Consul API Gateway deployment. Copy the content below into the values.yaml file. The values.yaml will be used by the Consul Helm chart. Available versions of the Consul and Consul API Gateway Docker images can be found on DockerHub, with additional context on version compatibility published in GitHub releases. See Helm Chart Configuration - apiGateway for more available options on how to configure your Consul API Gateway deployment via the Helm chart.

   global:
     name: consul
   connectInject:
     enabled: true
   controller:
     enabled: true
   apiGateway:
     enabled: true
     image: hashicorp/consul-api-gateway:VERSION

   

   values.yaml

   global:
     name: consul
   connectInject:
     enabled: true
   controller:
     enabled: true
   apiGateway:
     enabled: true
     image: hashicorp/consul-api-gateway:VERSION

3. Install Consul API Gateway using the standard Consul Helm chart and specify the custom values file. Available versions of the Consul Helm chart can be found in GitHub releases.

   $ helm install consul hashicorp/consul --version 0.45.0 --values values.yaml --create-namespace --namespace consul

   $ helm install consul hashicorp/consul --version 0.45.0 --values values.yaml --create-namespace --namespace consul

Usage

1. Verify that the requirements have been met.

2. Verify that the Consul API Gateway CRDs and controller have been installed and applied (see Installation).

3. Configure the artifacts described below in Configuration.

   apiGateway:
     managedGatewayClass:
       enabled: true

   

   values.yaml

   apiGateway:
     managedGatewayClass:
       enabled: true

4. Issue the kubectl apply command to implement the configurations, e.g.:

   $ kubectl apply -f gateway.yaml routes.yaml

   $ kubectl apply -f gateway.yaml routes.yaml

Configuration

Configure the following artifacts to facilitate ingress into your Consul service mesh:

• GatewayClassConfig: Describes additional Consul API Gateway-related configuration parameters for the GatewayClass resource.
• GatewayClass: Defines a class of gateway resources that you can use as a template for creating gateways.
• Gateway: Defines the main infrastructure resource that links API gateway components. It specifies the name of the GatewayClass and one or more listeners (see Listeners), which specify the logical endpoints bound to the gateway’s addresses.
• Routes: Specifies the path from the client to the listener.

Note: Add the following managedGatewayClass configuration to the values.yaml Helm configuration to enable the GatewayClassConfig and GatewayClass to be created automatically. The gateway, listeners, and routes will need to be configured manually. When managedGatewayClass is enabled, the serviceType for a managed GatewayClass will also default to LoadBalancer, which is appropriate for most deployments to managed Kubernetes cloud offerings (i.e., EKS, GKE, AKS). Other deployments, such as to a kind cluster, may require specifying NodePort or ClusterIP, instead.

GatewayClassConfig

The GatewayClassConfig object describes Consul API Gateway-related configuration parameters for the GatewayClass.

Add the kind: GatewayClassConfig option to the gateway values file to declare a gateway class. The following example creates a gateway class configuration called test-gateway-class-config:

apiVersion: api-gateway.consul.hashicorp.com/v1alpha1
kind: GatewayClassConfig
metadata:
  name: test-gateway-class-config
spec:
  useHostPorts: true
  logLevel: 'trace'
  consul:
    scheme: 'https'
    ports:
      http: 8501
      grpc: 8502

gateway.yaml

apiVersion: api-gateway.consul.hashicorp.com/v1alpha1
kind: GatewayClassConfig
metadata:
  name: test-gateway-class-config
spec:
  useHostPorts: true
  logLevel: 'trace'
  consul:
    scheme: 'https'
    ports:
      http: 8501
      grpc: 8502

The following table describes the allowed parameters for the spec array:

Refer to the Consul API Gateway repository for the complete specification.

GatewayClass

The GatewayClass resource is used as a template for creating Gateway resources. The specification includes the name of the controller (controllerName) and an API object containing controller-specific configuration resources within the cluster (parametersRef). The value of the controllerName field must be set to hashicorp.com/consul-api-gateway-controller.

When gateways are created from a GatewayClass, they use the parameters specified in the GatewayClass at the time of instantiation.

Add the kind: GatewayClass option to the the gateway values file to declare a gateway class. The following example creates a gateway class called test-gateway-class:

apiVersion: gateway.networking.k8s.io/v1alpha2
kind: GatewayClass
metadata:
  name: test-gateway-class
spec:
  controllerName: 'hashicorp.com/consul-api-gateway-controller'
  parametersRef:
    group: api-gateway.consul.hashicorp.com
    kind: GatewayClassConfig
    name: test-gateway-class-config

gateway.yaml

apiVersion: gateway.networking.k8s.io/v1alpha2
kind: GatewayClass
metadata:
  name: test-gateway-class
spec:
  controllerName: 'hashicorp.com/consul-api-gateway-controller'
  parametersRef:
    group: api-gateway.consul.hashicorp.com
    kind: GatewayClassConfig
    name: test-gateway-class-config

Refer to the Kubernetes Gateway API documentation for details about configuring gateway classes.

Gateway

The gateway configuration is the main infrastructure resource that links API gateway components. It specifies the name of the GatewayClass and one or more listeners.

Add the kind: Gateway option to the configuration file to declare a gateway. The following example creates a gateway called example-gateway. The gateway is based on the test-gateway-class and includes a listener called https (see Listeners for details about the listener configuration).

apiVersion: gateway.networking.k8s.io/v1alpha2
kind: Gateway
metadata:
  name: example-gateway
  annotations:
    'external-dns.alpha.kubernetes.io/hostname': DNS_HOSTNAME
spec:
  gatewayClassName: test-gateway-class
  listeners:
    - protocol: HTTPS
      hostname: DNS_HOSTNAME
      port: 443
      name: https
      allowedRoutes:
        namespaces:
          from: Same
      tls:
        certificateRefs:
          - name: gateway-production-certificate

gateway.yaml

apiVersion: gateway.networking.k8s.io/v1alpha2
kind: Gateway
metadata:
  name: example-gateway
  annotations:
    'external-dns.alpha.kubernetes.io/hostname': DNS_HOSTNAME
spec:
  gatewayClassName: test-gateway-class
  listeners:
    - protocol: HTTPS
      hostname: DNS_HOSTNAME
      port: 443
      name: https
      allowedRoutes:
        namespaces:
          from: Same
      tls:
        certificateRefs:
          - name: gateway-production-certificate

If you configure a listener’s certificateRefs to reference a secret in a different namespace, you must also create a ReferencePolicy in the same namespace as the secret. The ReferencePolicy grants the listener the permission to read the secret.

The following example creates a Gateway named example-gateway in gateway-namespace. This Gateway has a certificateRef in secret-namespace. The listener can use the certificate because reference-policy in secret-namespace is configured to allow Gateways in gateway-namespace to reference Secrets in secret-namespace.

apiVersion: gateway.networking.k8s.io/v1alpha2
kind: Gateway
metadata:
  name: example-gateway
  namespace: gateway-namespace
  annotations:
    'external-dns.alpha.kubernetes.io/hostname': DNS_HOSTNAME
spec:
  gatewayClassName: test-gateway-class
  listeners:
    - protocol: HTTPS
      hostname: DNS_HOSTNAME
      port: 443
      name: https
      allowedRoutes:
        namespaces:
          from: Same
      tls:
        certificateRefs:
          - name: gateway-production-certificate
            namespace: secret-namespace
---
apiVersion: gateway.networking.k8s.io/v1alpha2
kind: ReferencePolicy
metadata:
  name: reference-policy
  namespace: secret-namespace
spec:
  from:
    - group: gateway.networking.k8s.io
      kind: Gateway
      namespace: gateway-namespace
  to:
    - group: ""
      kind: Secret
      name: gateway-production-certificate

gateway_with_referencepolicy.yaml

apiVersion: gateway.networking.k8s.io/v1alpha2
kind: Gateway
metadata:
  name: example-gateway
  namespace: gateway-namespace
  annotations:
    'external-dns.alpha.kubernetes.io/hostname': DNS_HOSTNAME
spec:
  gatewayClassName: test-gateway-class
  listeners:
    - protocol: HTTPS
      hostname: DNS_HOSTNAME
      port: 443
      name: https
      allowedRoutes:
        namespaces:
          from: Same
      tls:
        certificateRefs:
          - name: gateway-production-certificate
            namespace: secret-namespace
---
apiVersion: gateway.networking.k8s.io/v1alpha2
kind: ReferencePolicy
metadata:
  name: reference-policy
  namespace: secret-namespace
spec:
  from:
    - group: gateway.networking.k8s.io
      kind: Gateway
      namespace: gateway-namespace
  to:
    - group: ""
      kind: Secret
      name: gateway-production-certificate

Refer to the Kubernetes Gateway API documentation for further details about configuring gateways.

Listeners

Listeners are the logical endpoints bound to the gateway’s addresses. Add the listener object to the gateway configuration and specify the following properties to define a listener:

Refer to the Kubernetes Gateway API documentation for details about configuring listeners.

Scaling

You can scale a logical gateway object to multiple instances with the kubectl scale command. The object scales according to the bounds set in GatewayClassConfig.

$ kubectl get deployment --selector api-gateway.consul.hashicorp.com/name=example-gateway
NAME              READY   UP-TO-DATE   AVAILABLE
example-gateway   1/1     1            1

$ kubectl get deployment --selector api-gateway.consul.hashicorp.com/name=example-gateway
NAME              READY   UP-TO-DATE   AVAILABLE
example-gateway   1/1     1            1

$ kubectl scale deployment/example-gateway --replicas=3
deployment.apps/example-gateway scaled

$ kubectl scale deployment/example-gateway --replicas=3
deployment.apps/example-gateway scaled

$ kubectl get deployment --selector api-gateway.consul.hashicorp.com/name=example-gateway
NAME              READY   UP-TO-DATE   AVAILABLE
example-gateway   3/3     3            3

$ kubectl get deployment --selector api-gateway.consul.hashicorp.com/name=example-gateway
NAME              READY   UP-TO-DATE   AVAILABLE
example-gateway   3/3     3            3

Route

Routes are independent configuration objects that are associated with specific listeners.

Declare a route with either kind: HTTPRoute or kind: TCPRoute and configure the route parameters in the spec block. Refer to the Kubernetes Gateway API documentation for each object type for details:

• HTTPRoute
• TCPRoute

The following example creates a route named example-route associated with a listener defined in example-gateway.

apiVersion: gateway.networking.k8s.io/v1alpha2
kind: HTTPRoute
metadata:
  name: example-route
spec:
  parentRefs:
    - name: example-gateway
  rules:
    - backendRefs:
        - kind: Service
          name: echo
          port: 8080

routes.yaml

apiVersion: gateway.networking.k8s.io/v1alpha2
kind: HTTPRoute
metadata:
  name: example-route
spec:
  parentRefs:
    - name: example-gateway
  rules:
    - backendRefs:
        - kind: Service
          name: echo
          port: 8080

To create a route for a backendRef in a different namespace, you must also create a ReferencePolicy.

The following example creates a route named example-route in namespace gateway-namespace. This route has a backendRef in namespace service-namespace. Traffic is allowed because the ReferencePolicy, named reference-policy in namespace service-namespace, allows traffic from HTTPRoutes in gateway-namespace to Services in service-namespace.

apiVersion: gateway.networking.k8s.io/v1alpha2
kind: HTTPRoute
metadata:
  name: example-route
  namespace: gateway-namespace
spec:
  parentRefs:
    - name: example-gateway
  rules:
    - backendRefs:
        - kind: Service
          name: echo
          namespace: service-namespace
          port: 8080
---
apiVersion: gateway.networking.k8s.io/v1alpha2
kind: ReferencePolicy
metadata:
  name: reference-policy
  namespace: service-namespace
spec:
  from:
    - group: gateway.networking.k8s.io
      kind: HTTPRoute
      namespace: gateway-namespace
  to:
    - group: ""
      kind: Service
      name: echo

route_with_referencepolicy.yaml

apiVersion: gateway.networking.k8s.io/v1alpha2
kind: HTTPRoute
metadata:
  name: example-route
  namespace: gateway-namespace
spec:
  parentRefs:
    - name: example-gateway
  rules:
    - backendRefs:
        - kind: Service
          name: echo
          namespace: service-namespace
          port: 8080
---
apiVersion: gateway.networking.k8s.io/v1alpha2
kind: ReferencePolicy
metadata:
  name: reference-policy
  namespace: service-namespace
spec:
  from:
    - group: gateway.networking.k8s.io
      kind: HTTPRoute
      namespace: gateway-namespace
  to:
    - group: ""
      kind: Service
      name: echo

MeshService

The MeshService configuration holds a reference to an externally-managed Consul service mesh service and can be used as a backendRef for a Route.

Refer to the Consul API Gateway repository for the complete specification.