Skip to content

Getting Started with the Service Proxy

This guide will walk you through the process of exposing your application to the internet using the Service Proxy. You will learn how to create HTTPProxy resources to control how traffic is routed to your services.

Prerequisites

Before you begin, you must have an application running and exposed via a Kubernetes Service object within your namespace.

The HTTPProxy Resource

Instead of using the standard Kubernetes Ingress resource, our Service Proxy is configured using a Custom Resource Definition (CRD) called HTTPProxy. This resource provides a more flexible and secure way to manage ingress routing, especially in multi-team environments.

Basic Example: Exposing a Service

The most common use case is to route all traffic for a specific hostname to a single backend service.

Let's say you have a Service named my-app-service running on port 8080 in your namespace, and you want to expose it at app.example.com.

You would create the following HTTPProxy resource:

apiVersion: projectcontour.io/v1
kind: HTTPProxy
metadata:
  name: my-app-proxy
  namespace: your-namespace
spec:
  virtualhost:
    fqdn: app.example.com
    tls:
      secretName: app-example-com-tls # Assumes a TLS secret exists
  routes:
    - services:
        - name: my-app-service
          port: 8080

Key Fields Explained

  • spec.virtualhost.fqdn: The fully qualified domain name (FQDN) that this proxy will handle traffic for.
  • spec.virtualhost.tls.secretName: Specifies the name of the Kubernetes Secret containing the TLS certificate and key for this host. Our Certificates Service can automate the creation and management of these secrets for you.
  • spec.routes: A list of routing rules.
  • spec.routes.services: Defines the backend Kubernetes Service(s) to which traffic should be sent.

Advanced Example: Route Delegation

HTTPProxy allows a powerful feature called delegation, where a central "root" proxy can delegate control over specific URL paths to other HTTPProxy resources, often in different namespaces. This is ideal for microservices, where different teams manage different parts of an application.

Imagine a scenario where a central team manages example.com, but the API team needs to control all traffic to example.com/api.

1. The Root HTTPProxy

In the namespace that owns the domain, you would create a root HTTPProxy that delegates the /api path.

# In the 'root-namespace'
apiVersion: projectcontour.io/v1
kind: HTTPProxy
metadata:
  name: example-root-proxy
  namespace: root-namespace
spec:
  virtualhost:
    fqdn: example.com
    tls:
      secretName: example-com-tls
  includes:
    - name: api-routes
      namespace: api-team-namespace
      conditions:
      - prefix: /api
  • spec.includes: This block defines the delegation rules.
  • name and namespace: Point to the child HTTPProxy that will handle this traffic.
  • conditions.prefix: Specifies that any request whose path starts with /api will be handled by the delegated proxy.

2. The Delegated (Child) HTTPProxy

Now, the API team can create an HTTPProxy in their own namespace (api-team-namespace) without needing access to the root domain's TLS secrets.

# In the 'api-team-namespace'
apiVersion: projectcontour.io/v1
kind: HTTPProxy
metadata:
  name: api-routes
  namespace: api-team-namespace
spec:
  routes:
    - conditions:
      - prefix: /v1/users
      services:
        - name: user-service
          port: 80
    - conditions:
      - prefix: /v1/orders
      services:
        - name: order-service
          port: 80

Notice that this HTTPProxy does not have a virtualhost section. It only defines the routes for the paths it is responsible for. The Service Proxy will automatically combine the rules from the root and child proxies.

Next Steps

You have now learned the basics of creating HTTPProxy resources to expose your services.

  • Explore more advanced routing capabilities like header-based routing, traffic weighting for canary releases, and request rewriting in the official Contour documentation.
  • Learn how to automate TLS certificate management by reading the Certificates Service introduction.