Skip to content

getting-started.md

Latest commit

 

History

History
204 lines (160 loc) · 3.85 KB

getting-started.md

File metadata and controls

204 lines (160 loc) · 3.85 KB

Getting Started

This guide walks through deploying Praxis on a Kubernetes cluster and routing HTTP traffic through it.

Prerequisites

  • Kubernetes 1.32+
  • kubectl configured for your cluster
  • Gateway API CRDs installed (v1.5.1)
  • A LoadBalancer provider (MetalLB for bare-metal/KIND, or a cloud provider)

Install the Gateway API CRDs if you haven't already:

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

Install the Operator

Apply the operator manifests:

kubectl apply -f https://raw.githubusercontent.com/praxis-proxy/praxis-operator/main/deploy/rbac.yaml
kubectl apply -f https://raw.githubusercontent.com/praxis-proxy/praxis-operator/main/deploy/deployment.yaml
kubectl apply -f https://raw.githubusercontent.com/praxis-proxy/praxis-operator/main/deploy/gatewayclass.yaml

This creates:

  • A praxis-system namespace with the operator Deployment and RBAC
  • A praxis GatewayClass registered with controller name praxis.sh/gateway-controller

Verify the operator is running:

kubectl -n praxis-system rollout status \
    deployment/praxis-operator

Verify the GatewayClass is accepted:

kubectl get gatewayclass praxis

The ACCEPTED column should show True.

Deploy a Backend

Create a namespace and a simple HTTP echo service:

apiVersion: v1
kind: Namespace
metadata:
  name: demo
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: echo
  namespace: demo
spec:
  replicas: 1
  selector:
    matchLabels:
      app: echo
  template:
    metadata:
      labels:
        app: echo
    spec:
      containers:
        - name: echo
          image: hashicorp/http-echo
          args: ["-text=hello from praxis"]
          ports:
            - containerPort: 5678
---
apiVersion: v1
kind: Service
metadata:
  name: echo
  namespace: demo
spec:
  selector:
    app: echo
  ports:
    - port: 5678
      targetPort: 5678
kubectl apply -f backend.yaml
kubectl -n demo rollout status deployment/echo

Create a Gateway

Create a Gateway with an HTTP listener on port 8080:

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: my-gateway
  namespace: demo
spec:
  gatewayClassName: praxis
  listeners:
    - name: http
      port: 8080
      protocol: HTTP
kubectl apply -f gateway.yaml

Wait for the Gateway to become programmed:

kubectl -n demo get gateway my-gateway

The PROGRAMMED column should show True. The operator creates a Deployment, ConfigMap, and LoadBalancer Service named praxis-my-gateway in the demo namespace.

Create an HTTPRoute

Route traffic from the Gateway to the echo backend:

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: echo-route
  namespace: demo
spec:
  parentRefs:
    - name: my-gateway
  rules:
    - backendRefs:
        - name: echo
          port: 5678
kubectl apply -f httproute.yaml

Verify the route is accepted:

kubectl -n demo get httproute echo-route

Send Traffic

Get the Gateway's assigned address:

GW_IP=$(kubectl -n demo get gateway my-gateway \
    -o jsonpath='{.status.addresses[0].value}')
echo "${GW_IP}"

Send a request:

curl http://${GW_IP}:8080/

Expected output:

hello from praxis

Clean Up

kubectl delete namespace demo

The Gateway's child resources (Deployment, ConfigMap, Service) are automatically deleted via owner references.

Next Steps