Skip to main content

Deliver and secure ingress for APIs in Kubernetes

You currently have a K8s cluster with an API (micro)service and want to deliver it to production with additional features and protection, like rate limiting, authentication, and DDoS protection.

In this guide, you'll learn how to implement ngrok as an API gateway, using the ngrok Kubernetes Operator, in these steps:

  1. Apply the ngrok Kubernetes Operator to your cluster
  2. Configure your cluster to use ngrok as an API gateway
  3. Set up Traffic Policy to shape traffic into/out of your API service

What you'll need​

ngrok account

Any tier will do— register now.

A reserved domain

Grab yours in the ngrok dashboard.

A Kubernetes cluster

... and optionally, a functioning API service. If you don't yet have one, you can install our demo service.

kubectl and Helm

Both installed locally on your workstation.

Why use the K8s Gateway API for your API gateway?​

Kubernetes has two APIs for handling ingress from external traffic into your cluster's internal network: the original Ingress Controller or the Gateway API.

The ngrok Kubernetes Operator supports both mechanisms. While we encourage you to explore both, we recommend the Gateway API based on the following:

  • The Ingress API, which Ingress Controllers utilize, is frozen in new versions of K8s and no longer receives updates.
  • While the Ingress Controller is designed purely for ingress, the Gateway API is also designed for dynamic infrastructure provisioning and advanced traffic routing.
  • The Gateway API is role-oriented, allowing DevOps/platform/infrastructure engineering teams to control clusters, policies, and permissions centrally, while still allowing API developers to self-service endpoints to their services with route objects.
  • The Gateway API provides a common interface to K8s networking, removing reliance on vendor-specific configurations.
  • Many developers can integrate their APIs or apps onto a single GatewayClass or Gateway, using HTTPRoutes, without affecting others.

For the scope of this guide, and based on this recommendation, we'll focus on Gateway API.

Step 0. Deploy the example ngrok API service​

If you're building a proof of concept with ngrok as the API gateway for your APIs in Kubernetes, you can use our example ngrok API service. This service responds to all routes with information about the connection—think of it as the pong to your curl.

note

If you already have an API service, you can skip this step—just be aware that you'll need to edit the example configurations below to properly configure the ngrok Kubernetes Operator.

To deploy the ngrok API service to your cluster, apply the deployment.yaml file to your cluster, which first creates a new prod namespace if one doesn't already exist.

Loading…

Step 1. Apply the ngrok Kubernetes Operator​

Add the ngrok Kubernetes Operator repo to Helm.

Loading…

Apply the latest Gateway API CRDs to your cluster.

Loading…

Set up a few environment variables to help apply the ngrok Kubernetes Operator.

Loading…

Install the ngrok Kubernetes Operator into a new ngrok-operator namespace with Gateway API functionality enabled.

Loading…

Step 2. Configure your cluster to use ngrok as an API gateway​

For ngrok to operate as your API gateway, using the native Gateway API, you need to configure the following:

  • A GatewayClass that uses the controller from the ngrok Kubernetes Operator project.
  • A Gateway with at least one listener attached to the ngrok domain you already reserved.
  • At least one HTTPRoute in the same namespace as your API service (prod in our example) that matches specific paths to its name and port.

Create the API gateway configuration​

Create a new YAML file named ngrok-api-gateway.yaml and paste in the following content.

First, replace {YOUR_NGROK_DOMAIN} with the domain you reserved.

If you're using the example API service from Step 0, substitute {YOUR_SERVICE_NAME} with ngrok-api-service and {SERVICE-PORT} with 80.

If you're deploying your own API service, change those variables accordingly, and edit the prod namespace to match the namespace where your service is already running. If you have multiple API services in different containers, you'll need to create multiple rules to match paths to services.

Loading…

Write the manifest to disk and apply to your cluster.

Loading…

With the ngrok Kubernetes Operator deployed and configured as an API gateway, your API service is now publicly available at {YOUR_NGROK_DOMAIN}. You can now test your API gateway and service.

Loading…

You'll see a response like the following:

Loading…

Step 3. Set up Traffic Policy to shape traffic into/out of your API service​

ngrok's Traffic Policy module allows you to conditionally act upon traffic as it arrives and departs your API gateway. In a Kubernetes context, Traffic Policy builds on top of the existing YAML manifests you already use to declare your deployments and services.

When the ngrok Kubernetes Operator initiates in your cluster, and your HTTPRoute configuration contains one or more filter dictionaries that reference the NgrokTrafficPolicy CRD, the Operator pipes the raw YAML to ngrok's network to provision the action and enforce it upon incoming and outgoing traffic.

Rate limiting—one of the most in-demand API gateway features— is both quick to implement and highly flexible based on your use case.

Define a rate limiting rule​

Create a new YAML file named ngrok-rate-limit.yaml with the following content:

Loading…

This CRD instantiates a rate limiting rule with the following properties:

  • Via the expression, it only applies to requests with the POST or PUT HTTP method—all others, like GET, are unaffected.
  • Allows for a maximum of 10 requests within the last 60s—both values are configurable to your needs.
  • Uses the client's IP address (via the conn.client_ip variable) to track usage against your capacity limit.

Check out the Traffic Policy (for HTTP tunnels) documentation for a complete view of how to combine variables, expressions, and actions to create rules that beneficially shape the traffic on your API gateway and lessen the operational burden on your API service.

Apply the Traffic Policy rule to your cluster​

You must instantiate the NgrokTrafficPolicy CRD in your cluster before you can reference it in your API gateway configuration.

Loading…

Update your API gateway configuration to include the Traffic Policy rule​

With the CRD applied, you need to update your existing configuration ngrok-api-gateway.yaml with a filter, which is a process that must be completed during the request or response lifecycle.

Edit your existing ngrok-api-gateway.yaml file—specifically the HTTPRoute section—to add a reference to the rate limiting policy.

Loading…

Re-apply your manifest to update your API gateway with the new Traffic Policy rule.

Loading…

Test the rate limiting rule​

Finally, you can validate that your new rate limiting rule was deployed successfully at the ngrok network by creating a large number of requests in quick succession. Run the following on your local workstation, replacing {YOUR_NGROK_DOMAIN}.

Loading…

Depending on the capacity value you configured in the NgrokTrafficPolicy CRD, you should start seeing 429 response codes shortly.

You can confirm your Traffic Policy rules in the Edges section of your ngrok dashboard. Click on the edge associated with this deployment, then one of the routes you attached your Traffic Policy rule to. Click Traffic Policy to view the rule as run on the ngrok network.

Viewing the ngrok dashboard to confirm deployment of a Traffic Policy rule

What's next?​

Congratulations—you've now made your API service available to the public internet, backed by the power of ngrok operating as an API gateway.

You also already have HTTP/2 enabled by default for all connections that support it. HTTP/2 gives you better performance with prioritization, multiplexing, and header compression.

Your next best step is to expand your usage of Traffic Policy actions to handle more advanced API gateway requirements:

Finally, you can extend how you use ngrok as an API gateway to better match your Git-based workflows and using version-controlled, declarative, and repeatable configurations with a continuous deployment mechanism like Argo CD.