Nomad
Deploy a Consul API Gateway on Nomad
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
Register a listener for the API Gateway.
$ consul config write example/gateway-listeners.hcl
Register http routes for the API Gateway so that Envoy knows how and where to write the traffic.
$ 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.