Installing Consul API Gateway

    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 for the version of API Gateway you are deploying.

    Version reference convention: Replace 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:

      1. $ 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 Docker images can be found on DockerHub, with additional context on version compatibility published in GitHub releases. See for more available options on how to configure your Consul API Gateway deployment via the Helm chart.

      1. global:
      2.   name: consul
      3. connectInject:
      4.   enabled: true
      5. controller:
      6.   enabled: true
      7. apiGateway:
      8.   enabled: true
      9.   image: hashicorp/consul-api-gateway:VERSION

      values.yaml

      1. global:
      2.   name: consul
      3. connectInject:
      4.   enabled: true
      5. controller:
      6.   enabled: true
      7. apiGateway:
      8.   enabled: true
      9.   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.

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

    1. Verify that the 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 .

      1. apiGateway:
      2.   managedGatewayClass:
      3.     enabled: true

      Installation - 图2

      values.yaml

      1. apiGateway:
      2.   managedGatewayClass:
      3.     enabled: true

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

      1. $ kubectl apply -f gateway.yaml routes.yaml

    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.
    • : 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 ), 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 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.

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

    1. apiVersion: api-gateway.consul.hashicorp.com/v1alpha1
    2. kind: GatewayClassConfig
    3. metadata:
    4.   name: test-gateway-class-config
    5. spec:
    6.   useHostPorts: true
    7.   logLevel: 'trace'
    8.   consul:
    9.     scheme: 'https'
    10.     ports:
    11.       http: 8501
    12.       grpc: 8502

    gateway.yaml

    1. apiVersion: api-gateway.consul.hashicorp.com/v1alpha1
    2. kind: GatewayClassConfig
    3. metadata:
    4.   name: test-gateway-class-config
    5. spec:
    6.   useHostPorts: true
    7.   logLevel: 'trace'
    8.   consul:
    9.     scheme: 'https'
    10.     ports:
    11.       http: 8501
    12.       grpc: 8502

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

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

    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:

    1. apiVersion: gateway.networking.k8s.io/v1alpha2
    2. kind: GatewayClass
    3. metadata:
    5. spec:
    6.   controllerName: 'hashicorp.com/consul-api-gateway-controller'
    7.   parametersRef:
    8.     group: api-gateway.consul.hashicorp.com
    9.     kind: GatewayClassConfig
    10.     name: test-gateway-class-config

    Installation - 图4

    gateway.yaml

    1. apiVersion: gateway.networking.k8s.io/v1alpha2
    2. kind: GatewayClass
    3. metadata:
    4.   name: test-gateway-class
    5. spec:
    6.   controllerName: 'hashicorp.com/consul-api-gateway-controller'
    7.     group: api-gateway.consul.hashicorp.com
    8.     kind: GatewayClassConfig
    9.     name: test-gateway-class-config

    Refer to the for details about configuring gateway classes.

    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).

    1. apiVersion: gateway.networking.k8s.io/v1alpha2
    2. kind: Gateway
    3. metadata:
    4.   name: example-gateway
    5.   annotations:
    6.     'external-dns.alpha.kubernetes.io/hostname': DNS_HOSTNAME
    7. spec:
    8.   gatewayClassName: test-gateway-class
    9.   listeners:
    10.     - protocol: HTTPS
    11.       hostname: DNS_HOSTNAME
    12.       port: 443
    13.       name: https
    14.       allowedRoutes:
    15.         namespaces:
    16.           from: Same
    17.       tls:
    18.         certificateRefs:
    19.           - name: gateway-production-certificate

    gateway.yaml

    1. apiVersion: gateway.networking.k8s.io/v1alpha2
    2. kind: Gateway
    3. metadata:
    4.   name: example-gateway
    5.   annotations:
    6.     'external-dns.alpha.kubernetes.io/hostname': DNS_HOSTNAME
    7. spec:
    8.   gatewayClassName: test-gateway-class
    9.   listeners:
    10.     - protocol: HTTPS
    11.       hostname: DNS_HOSTNAME
    12.       port: 443
    13.       name: https
    14.       allowedRoutes:
    15.         namespaces:
    16.           from: Same
    17.       tls:
    18.         certificateRefs:
    19.           - name: gateway-production-certificate

    If you configure a listener’s certificateRefs to reference a secret in a different namespace, you must also create a 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.

    1. apiVersion: gateway.networking.k8s.io/v1alpha2
    2. kind: Gateway
    3. metadata:
    4.   name: example-gateway
    5.   namespace: gateway-namespace
    6.   annotations:
    7.     'external-dns.alpha.kubernetes.io/hostname': DNS_HOSTNAME
    8. spec:
    9.   gatewayClassName: test-gateway-class
    10.   listeners:
    11.     - protocol: HTTPS
    12.       hostname: DNS_HOSTNAME
    13.       port: 443
    14.       name: https
    15.       allowedRoutes:
    16.         namespaces:
    17.           from: Same
    18.       tls:
    19.         certificateRefs:
    20.           - name: gateway-production-certificate
    21.             namespace: secret-namespace
    22. ---
    23. apiVersion: gateway.networking.k8s.io/v1alpha2
    24. kind: ReferencePolicy
    25. metadata:
    26.   name: reference-policy
    27.   namespace: secret-namespace
    28. spec:
    29.   from:
    30.     - group: gateway.networking.k8s.io
    31.       kind: Gateway
    32.       namespace: gateway-namespace
    33.   to:
    34.     - group: ""
    35.       kind: Secret
    36.       name: gateway-production-certificate

    gateway_with_referencepolicy.yaml

    1. apiVersion: gateway.networking.k8s.io/v1alpha2
    2. kind: Gateway
    3. metadata:
    4.   name: example-gateway
    5.   namespace: gateway-namespace
    6.   annotations:
    7.     'external-dns.alpha.kubernetes.io/hostname': DNS_HOSTNAME
    8. spec:
    9.   gatewayClassName: test-gateway-class
    10.   listeners:
    11.     - protocol: HTTPS
    12.       hostname: DNS_HOSTNAME
    13.       port: 443
    14.       allowedRoutes:
    15.         namespaces:
    16.           from: Same
    17.       tls:
    18.         certificateRefs:
    20.             namespace: secret-namespace
    21. ---
    22. apiVersion: gateway.networking.k8s.io/v1alpha2
    23. kind: ReferencePolicy
    24. metadata:
    25.   name: reference-policy
    26.   namespace: secret-namespace
    27. spec:
    28.   from:
    29.     - group: gateway.networking.k8s.io
    30.       kind: Gateway
    31.       namespace: gateway-namespace
    32.   to:
    33.     - group: ""
    34.       kind: Secret
    35.       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.

    1. $ kubectl get deployment --selector api-gateway.consul.hashicorp.com/name=example-gateway
    2. NAME              READY   UP-TO-DATE   AVAILABLE
    3. example-gateway   1/1     1            1
    1. $ kubectl scale deployment/example-gateway --replicas=3
    2. deployment.apps/example-gateway scaled
    1. $ kubectl scale deployment/example-gateway --replicas=3
    2. deployment.apps/example-gateway scaled
    1. $ kubectl get deployment --selector api-gateway.consul.hashicorp.com/name=example-gateway
    2. NAME              READY   UP-TO-DATE   AVAILABLE
    3. example-gateway   3/3     3            3
    1. $ kubectl get deployment --selector api-gateway.consul.hashicorp.com/name=example-gateway
    2. NAME              READY   UP-TO-DATE   AVAILABLE
    3. example-gateway   3/3     3            3

    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:

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

    1. apiVersion: gateway.networking.k8s.io/v1alpha2
    2. kind: HTTPRoute
    3. metadata:
    4.   name: example-route
    5. spec:
    6.   parentRefs:
    7.     - name: example-gateway
    8.   rules:
    9.     - backendRefs:
    10.         - kind: Service
    11.           name: echo
    12.           port: 8080

    Installation - 图7

    routes.yaml

    1. apiVersion: gateway.networking.k8s.io/v1alpha2
    2. kind: HTTPRoute
    3. metadata:
    4.   name: example-route
    5. spec:
    6.   parentRefs:
    7.     - name: example-gateway
    8.   rules:
    9.     - backendRefs:
    10.         - kind: Service
    11.           name: echo
    12.           port: 8080

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

    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.

    1. apiVersion: gateway.networking.k8s.io/v1alpha2
    2. kind: HTTPRoute
    3. metadata:
    4.   name: example-route
    5.   namespace: gateway-namespace
    6. spec:
    7.   parentRefs:
    8.     - name: example-gateway
    9.   rules:
    10.     - backendRefs:
    11.         - kind: Service
    12.           name: echo
    13.           namespace: service-namespace
    14.           port: 8080
    15. ---
    17. apiVersion: gateway.networking.k8s.io/v1alpha2
    18. kind: ReferencePolicy
    19. metadata:
    20.   name: reference-policy
    21.   namespace: service-namespace
    22. spec:
    23.   from:
    24.     - group: gateway.networking.k8s.io
    25.       kind: HTTPRoute
    26.       namespace: gateway-namespace
    27.   to:
    28.     - group: ""
    29.       kind: Service

    route_with_referencepolicy.yaml

    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 for the complete specification.