Create a Datum HTTP Proxy (Reverse Proxy)

Before you begin

This tutorial assumes you have already:

• Registered a Datum account
• Installed and configured the necessary tools
• Created a Datum project
• Configured a kubeconfig context for your project

Understanding HTTP Proxies

An HTTPProxy is a simplified way to configure HTTP reverse proxy functionality in Datum. It automatically creates and manages Gateway, HTTPRoute, and EndpointSlice resources for you, reducing the complexity of manual configuration.

HTTPProxy provides:

• Simple single-manifest configuration for reverse proxy setups
• Automatic backend endpoint resolution from URLs
• Built-in support for path-based routing and header manipulation
• Seamless integration with Datum’s global proxy infrastructure

This tutorial will create an HTTPProxy that proxies traffic to example.com as the backend service.

Creating a Basic HTTPProxy

Let’s create a simple HTTPProxy that will route traffic to example.com. Here’s the basic configuration:

Apply from stdin

cat <<EOF | kubectl apply -f -
apiVersion: networking.datumapis.com/v1alpha
kind: HTTPProxy
metadata:
  name: httpproxy-sample-example-com
spec:
  rules:
      - backends:
        - endpoint: https://example.com
EOF

Apply from file

Save and apply the following resource to your project:

apiVersion: networking.datumapis.com/v1alpha
kind: HTTPProxy
metadata:
  name: httpproxy-sample-example-com
spec:
  rules:
      - backends:
        - endpoint: https://example.com

Summary of this HTTPProxy’s configuration:

• Rule Matching: A default path prefix match is inserted which matches all incoming requests and forwards them to the backend.

• Backend URL Components: The endpoint: https://example.com URL is parsed to extract:

  • Scheme: https (determines the protocol for backend connections)
  • Host: example.com (the target hostname for proxy requests)
  • Port: 443 (inferred from HTTPS scheme)

• Single Backend Limitation: Currently, HTTPProxy supports only one backend endpoint per rule.

Verifying the HTTPProxy

Check that your HTTPProxy was created and programmed successfully:

kubectl get httpproxy httpproxy-sample-example-com

You should see output similar to:

NAME                           HOSTNAME                                                       PROGRAMMED   AGE
httpproxy-sample-example-com   c4b9c93d-97c2-46d1-972e-48197cc9a9da.prism.e2e.env.datum.net   True         11s

The key fields in this output are:

• NAME: Your HTTPProxy resource name
• HOSTNAME: The auto-generated hostname where your proxy is accessible
• PROGRAMMED: True indicates the HTTPProxy has been successfully configured
• AGE: How long the resource has existed

Testing the HTTPProxy

Once your HTTPProxy shows PROGRAMMED: True, you can test it using the generated hostname:

# Use the hostname from kubectl get httpproxy output
curl -v http://c4b9c93d-97c2-46d1-972e-48197cc9a9da.prism.e2e.env.datum.net

Alternatively, copy the hostname into a browser to view example.com content served through your Datum HTTPProxy.

Understanding Generated Resources

HTTPProxy automatically creates several Kubernetes resources behind the scenes:

1. Gateway Resource

Check the generated Gateway:

kubectl get gateway

The HTTPProxy creates a Gateway that handles incoming traffic and provides the external hostname.

2. HTTPRoute Resource

View the generated HTTPRoute:

kubectl get httproute

The HTTPRoute defines the routing rules and connects the Gateway to the backend endpoints.

3. EndpointSlice Resource

Examine the generated EndpointSlice:

kubectl get endpointslices

The EndpointSlice contains the resolved IP addresses and port information for the backend service extracted from your endpoint URL.

Advanced Configuration

HTTPProxy leverages many existing Gateway API features, including matches and filters. Datum supports all Core Gateway API capabilities, providing you with a rich set of traffic management features through the simplified HTTPProxy interface.

Multiple Path Rules

You can define multiple routing rules within a single HTTPProxy:

Apply from stdin

cat <<EOF | kubectl apply -f -
apiVersion: networking.datumapis.com/v1alpha
kind: HTTPProxy
metadata:
  name: httpproxy-multi-path
spec:
  rules:
    - name: root-route
      matches:
        - path:
            type: PathPrefix
            value: /
      backends:
        - endpoint: https://example.com
    - name: headers-route
      matches:
        - path:
            type: PathPrefix
            value: /headers
      backends:
        - endpoint: https://httpbingo.org
EOF

Apply from file

Save and apply the following resource to your project:

apiVersion: networking.datumapis.com/v1alpha
kind: HTTPProxy
metadata:
  name: httpproxy-multi-path
spec:
  rules:
    - name: root-route
      matches:
        - path:
            type: PathPrefix
            value: /
      backends:
        - endpoint: https://example.com
    - name: headers-route
      matches:
        - path:
            type: PathPrefix
            value: /headers
      backends:
        - endpoint: https://httpbingo.org

Header-based Routing and rewrite filters

HTTPProxy supports header-based matching and request rewrites:

Apply from stdin

cat <<EOF | kubectl apply -f -
apiVersion: networking.datumapis.com/v1alpha
kind: HTTPProxy
metadata:
  name: httpproxy-header-based
spec:
  rules:
    - name: headers
      matches:
        - headers:
            - name: x-rule
              value: headers
      filters:
        - type: URLRewrite
          urlRewrite:
            path:
              type: ReplaceFullPath
              replaceFullPath: /headers
      backends:
        - endpoint: https://httpbingo.org
    - name: ip
      matches:
        - headers:
            - name: x-rule
              value: ip
      filters:
        - type: URLRewrite
          urlRewrite:
            path:
              type: ReplaceFullPath
              replaceFullPath: /ip
      backends:
        - endpoint: https://httpbingo.org
EOF

Apply from file

Save and apply the following resource to your project:

apiVersion: networking.datumapis.com/v1alpha
kind: HTTPProxy
metadata:
  name: httpproxy-header-based
spec:
  rules:
    - name: headers
      matches:
        - headers:
            - name: x-rule
              value: headers
      filters:
        - type: URLRewrite
          urlRewrite:
            path:
              type: ReplaceFullPath
              replaceFullPath: /headers
      backends:
        - endpoint: https://httpbingo.org
    - name: ip
      matches:
        - headers:
            - name: x-rule
              value: ip
      filters:
        - type: URLRewrite
          urlRewrite:
            path:
              type: ReplaceFullPath
              replaceFullPath: /ip
      backends:
        - endpoint: https://httpbingo.org

Once your HTTPProxy shows PROGRAMMED: True, you can test it using the generated hostname:

Headers Rule:

# Use the hostname from kubectl get httpproxy output
curl -H "x-rule: headers" -v http://c4b9c93d-97c2-46d1-972e-48197cc9a9da.prism.e2e.env.datum.net

You should see output similar to:

{
  "headers": {
    "Accept": [
      "*/*"
    ],
    // ...
  }
}

IP Rule:

# Use the hostname from kubectl get httpproxy output
curl -H "x-rule: ip" -v http://c4b9c93d-97c2-46d1-972e-48197cc9a9da.prism.e2e.env.datum.net

You should see output similar to:

{
  "origin": "127.0.0.1"
}

Custom Hostnames

An HTTPProxy may optionally be configured with one or more custom hostnames via the spec.hostnames field.

Apply from stdin

cat <<EOF | kubectl apply -f -
apiVersion: networking.datumapis.com/v1alpha
kind: HTTPProxy
metadata:
  name: httpproxy-sample-example-com
spec:
  hostnames: # Custom hostnames
    - test.example.com
  rules:
      - backends:
        - endpoint: https://example.com
EOF

Apply from file

Save and apply the following resource to your project:

apiVersion: networking.datumapis.com/v1alpha
kind: HTTPProxy
metadata:
  name: httpproxy-sample-example-com
spec:
  hostnames: # Custom hostnames
    - test.example.com
  rules:
      - backends:
        - endpoint: https://example.com

Hostnames which have been programmed will be listed in the status.hostnames field.

  status:
    hostnames:
      - test.example.com

Domain Ownership

The system must verify domain ownership before programming a hostname on an HTTPProxy. A hostname is considered verified if any matching Domain resource exists in the same namespace and is verified.

A hostname matches a Domain if:

• The spec.domainName value exactly matches the hostname.
• The spec.domainName value is a suffix match of the hostname.

A Domain with a spec.domainName value of example.com will match a hostname of test.example.com, foo.test.example.com, and exactly example.com, but not a hostname of test-example.com.

If a Domain resource does not exist that matches a hostname, one will automatically be created for the root domain of the hostname. If an HTTPProxy is configured with the hostnames test.example.com and api.example.com, and there is no matching Domain, one will be created for example.com.

Any hostname which has not been verified will be listed in the message field of the HostnamesVerified condition.

status:
  conditions:
  - lastTransitionTime: "2025-08-11T16:09:09Z"
    message: 'unverified hostnames present, check status of Domains in the same namespace:
      test.example.com'
    observedGeneration: 2
    reason: UnverifiedHostnamesPresent
    status: "False"
    type: HostnamesVerified

For more information on Domains and Domain Ownership, see Managing Domains.

Platform Uniqueness

In addition to verifying ownership, hostnames must be unique across the platform.

If a hostname is already programmed on another resource, a conflict will be encountered and communicated in the HostnamesInUse condition.

status:
  conditions:
  - lastTransitionTime: "2025-08-11T16:09:09Z"
    message: 'Hostnames are already attached to another resource: test.example.com'
    observedGeneration: 2
    reason: HostnameInUse
    status: "True"
    type: HostnamesInUse

Note

Wildcard hostnames are not supported at this time.

Next Steps

• Export telemetry to Grafana Cloud

Troubleshooting

Common issues and their solutions:

1. HTTPProxy not showing PROGRAMMED: True:

   • Check the HTTPProxy status: kubectl describe httpproxy <name>

2. Generated hostname not responding:

   • Verify the HTTPProxy status shows PROGRAMMED: True
   • Verify the hostname is present in the status.hostnames field. If it is not, check for the HostnamesVerified or HostnamesInUse conditions

3. Backend URL parsing issues:

   • Ensure the endpoint URL includes the scheme (http:// or https://)
   • Check for any typos in the endpoint URL

4. Checking generated resources:

   • List all related resources: kubectl get gateway,httproute,endpointslices
   • Use kubectl describe on any resource showing issues