Skip to content

Getting started

This guide installs Coxswain into an existing cluster, creates a GatewayClass, deploys a test HTTPRoute, and verifies traffic flows end-to-end. It takes about 10 minutes.

Early development

Coxswain is under active development and not yet ready for production. Use this walkthrough on a sandbox cluster.

Prerequisites

  • Kubernetes 1.30 or later
  • Gateway API CRDs v1.5.1 or later (installed in Step 1)
  • kubectl configured against your target cluster
  • helm 3.x installed

Step 1 — Install the Gateway API CRDs

Coxswain supports both Gateway API and classic Ingress. The Gateway API CRDs are not bundled with Kubernetes and must be installed once per cluster:

kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/latest/download/standard-install.yaml

Step 2 — Install Coxswain

helm install coxswain oci://ghcr.io/coxswain-labs/charts/coxswain \
  --namespace coxswain-system --create-namespace

kubectl apply -f https://github.com/coxswain-labs/coxswain/releases/latest/download/install.yaml

Wait for the controller to become ready:

kubectl -n coxswain-system wait pod -l app.kubernetes.io/name=coxswain \
  --for=condition=Ready --timeout=90s

Verify the GatewayClass is accepted:

kubectl get gatewayclass coxswain
# NAME       CONTROLLER                              ACCEPTED   AGE
# coxswain   coxswain-labs.dev/gateway-controller    True       ...

Step 3 — Create a Gateway

# gateway.yaml
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: example-gateway
  namespace: default
spec:
  gatewayClassName: coxswain
  listeners:
    - name: http
      port: 80
      protocol: HTTP
      allowedRoutes:
        namespaces:
          from: Same

kubectl apply -f gateway.yaml
kubectl wait gateway/example-gateway --for=condition=Programmed --timeout=30s

Step 4 — Deploy a test backend

# echo-backend.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: echo
spec:
  replicas: 1
  selector:
    matchLabels:
      app: echo
  template:
    metadata:
      labels:
        app: echo
    spec:
      containers:
        - name: echo
          image: gcr.io/k8s-staging-gateway-api/echo-basic:latest
          ports:
            - containerPort: 3000
---
apiVersion: v1
kind: Service
metadata:
  name: echo
spec:
  selector:
    app: echo
  ports:
    - port: 80
      targetPort: 3000

kubectl apply -f echo-backend.yaml

Step 5 — Create an HTTPRoute

# route.yaml
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: echo-route
spec:
  parentRefs:
    - name: example-gateway
  hostnames:
    - echo.example.com
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /
      backendRefs:
        - name: echo
          port: 80

kubectl apply -f route.yaml
kubectl get httproute echo-route
# NAME         HOSTNAMES            AGE
# echo-route   ["echo.example.com"]   5s

Step 6 — Verify traffic

The proxy port depends on your cluster and install method. For a local cluster with a NodePort or port-forwarded service:

# Find the proxy service address
kubectl -n coxswain-system get svc coxswain-proxy

# Test via Host header
curl -H "Host: echo.example.com" http://<proxy-address>/
# {"host":"echo.example.com","method":"GET","path":"/", ...}

What's next?

  • Ingress — see the Ingress guide to use classic Ingress resources alongside Gateway API.
  • TLS — see the TLS guide to add HTTPS with cert-manager or a manual Secret.
  • Production — see Running in production before going live.