Deploy a Consul API Gateway on Nomad

3min
|
Nomad
Consul

An API Gateway is used for controlling access at entry and traffic management. In this tutorial, you will:

Deploy Consul ACL roles, policies, and intentions for the API Gateway.
Deploy an API Gateway job to Nomad.
Deploy an example upstream job, and configure the gateway.

This tutorial uses Nomad's Workload Identity to authorize a Consul task to bootstrap the API Gateway task and correctly register the API Gateway with Consul. The API Gateway is deployed in its own Nomad namespace. You will add a Consul ACL role that grants the appropriate permissions to the API Gateway and matches the Consul binding rule for that Nomad namespace.

Prerequisites

Clone the API Gateway on Nomad repository. This repository contains all of the necessary Consul and Nomad configuration files.

$ git clone https://github.com/hashicorp-guides/consul-api-gateway-on-nomad

Navigate to the cloned repository directory.

$ cd consul-gateway-on-nomad

Follow the instructions in the README file to create a Nomad and Consul cluster with the correct configuration.

Create required policies

Create a Nomad namespace.

$ nomad namespace apply \
    -description "namespace for Consul API Gateways" \
    ingress

Create a Consul ACL binding rule for the API Gateway that assigns the builtin/api-gateway templated policy to Nomad workloads deployed into the Nomad namespace ingress that you just created.

consul acl binding-rule create \
    -method 'nomad-workloads' \
    -description 'Nomad API gateway' \
    -bind-type 'templated-policy' \
    -bind-name 'builtin/api-gateway' \
    -bind-vars 'Name=${value.nomad_job_id}' \
    -selector '"nomad_service" not in value and value.nomad_namespace==ingress'

Upload certificates for API Gateway

The API Gateway job needs Consul mTLS certificates to communicate with Consul. This tutorial uses Nomad Variables to store the certificates securely, but you can also use Vault secrets. Add the certificates to the ingress namespace.

$ nomad var put -namespace ingress \
    nomad/jobs/my-api-gateway/gateway/setup \
    consul_cacert=@$CONSUL_CACERT \
    consul_client_cert=@$CONSUL_CLIENT_CERT \
    consul_client_key=@$CONSUL_CLIENT_KEY

Deploy API Gateway

Run the Nomad job. You can pass additional values to the command with the -var option.

$ nomad job run ./api-gateway.nomad.hcl

Once the deployment is complete, check the Consul UI to see that the API Gateway service has been registered.

Run an example upstream

Add intentions to allow traffic from the API Gateway to the hello application.

$ consul config write example/hello-app-intentions.hcl

$ consul config write example/gateway-listeners.hcl

$ consul config write example/my-http-route.hcl

Start the hello app.

$ nomad run example/hello-app.nomad.hcl

Once the deployment is complete, you can test the API Gateway.

Find the allocation for the API gateway.

$ nomad job status -namespace ingress my-api-gateway

Find the address for the API Gateway allocation and provide the allocation ID from the status command above by replacing the placeholder <allocID> in this command.

$ nomad alloc -namespace ingress status <allocID>

Submit a request to the hello app and observe the response. Replace the placeholder values <api-gateway-address> and <api-gateway-port> with the address and port respectively from the status command.

$ curl -v http://<api-gateway-address>:<api-gateway-port>/hello

Next steps

In this tutorial you deployed Consul ACL roles, policies, and intentions for an API Gateway, deployed an API Gateway job to Nomad, deployed an example upstream job, and configured an API gateway.

Learn more by checking out these resources.

Consul in production

Next Collection

Load Balancing