### Complete Example: API Gateway Setup

Source: https://context7.com/apoxy-dev/apoxy/llms.txt

Demonstrates setting up a complete API gateway with backend routing, edge function processing, and rate limiting.

```APIDOC
## Complete Example: API Gateway Setup

### Description
This example demonstrates setting up a complete API gateway with backend routing, edge function processing, and rate limiting.

### Configuration Example
```yaml
# complete-setup.yaml
# 1. Proxy infrastructure
apiVersion: core.apoxy.dev/v1alpha2
kind: Proxy
metadata:
  name: production-proxy
spec:
  provider: cloud
  telemetry:
    tracing:
      enabled: true
    accessLogs:
      json:
        request_id: "%REQ(X-Request-ID)%"
---
# 2. Gateway class and gateway
apiVersion: gateway.apoxy.dev/v1
kind: GatewayClass
metadata:
  name: apoxy
spec:
  controllerName: gateway.apoxy.dev/gatewayclass-controller
---
apiVersion: gateway.apoxy.dev/v1
kind: Gateway
metadata:
  name: main-gateway
spec:
  gatewayClassName: apoxy
  infrastructure:
    parametersRef:
      kind: Proxy
      name: production-proxy
  listeners:
    - name: http
      protocol: HTTP
      port: 80
---
```
```

--------------------------------

### Complete API Gateway Setup - Apoxy YAML

Source: https://context7.com/apoxy-dev/apoxy/llms.txt

Demonstrates a comprehensive API gateway setup, including proxy infrastructure with telemetry, a GatewayClass, and a Gateway resource with HTTP listeners. This configuration enables routing, edge function processing, and rate limiting.

```yaml
# complete-setup.yaml
# 1. Proxy infrastructure
apiVersion: core.apoxy.dev/v1alpha2
kind: Proxy
metadata:
  name: production-proxy
spec:
  provider: cloud
  telemetry:
    tracing:
      enabled: true
    accessLogs:
      json:
        request_id: "%REQ(X-Request-ID)%"
---
# 2. Gateway class and gateway
apiVersion: gateway.apoxy.dev/v1
kind: GatewayClass
metadata:
  name: apoxy
spec:
  controllerName: gateway.apoxy.dev/gatewayclass-controller
---
apiVersion: gateway.apoxy.dev/v1
kind: Gateway
metadata:
  name: main-gateway
spec:
  gatewayClassName: apoxy
  infrastructure:
    parametersRef:
      kind: Proxy
      name: production-proxy
  listeners:
    - name: http
      protocol: HTTP
      port: 80
---
```

--------------------------------

### Start Local Development Environment - Apoxy CLI

Source: https://context7.com/apoxy-dev/apoxy/llms.txt

Starts a complete local development environment for Apoxy, including the API server, backplane, and tunnel proxy. It watches configuration files for automatic reloads.

```bash
# Start local development environment with config file
apoxy dev ./config/proxy.yaml
# Starting Apoxy server with Proxy name: my-laptop
# Starting apiserver using driver mode: docker
# Starting clickhouse using driver mode: docker
# Starting backplane using driver mode: docker
# Starting tunnelproxy using driver mode: docker
# Watching ./config/proxy.yaml for changes...
```

--------------------------------

### Run Local Development Environment

Source: https://github.com/apoxy-dev/apoxy/blob/main/CLAUDE.md

Starts the local development environment for the Apoxy project. This command is typically used to set up a local testing or development instance.

```bash
# Start local dev environment
apoxy dev
```

--------------------------------

### Deploy Apoxy Configuration using CLI

Source: https://context7.com/apoxy-dev/apoxy/llms.txt

Applies a complete Apoxy setup defined in 'complete-setup.yaml' using the Apoxy CLI. This command deploys various resources including proxy, gateway, backend, edge function, and HTTP route.

```bash
# Deploy complete setup
apoxy apply -f complete-setup.yaml
# proxy "production-proxy" applied
# gatewayclass "apoxy" applied
# gateway "main-gateway" applied
# backend "users-api" applied
# edgefunction "auth-filter" applied
# httproute "users-route" applied
#
# Applied 6 resources
```

--------------------------------

### Test API Endpoint with Authentication

Source: https://context7.com/apoxy-dev/apoxy/llms.txt

Tests the configured API endpoint 'https://api.example.com/users' by sending a GET request with a valid 'X-API-Key' header. This verifies that the route and authentication filter are functioning correctly.

```bash
# Test the endpoint
curl -H "X-API-Key: my-key" https://api.example.com/users
```

--------------------------------

### Run Go Tests

Source: https://github.com/apoxy-dev/apoxy/blob/main/CLAUDE.md

Executes Go tests for the Apoxy project. Supports running all tests, specific packages, verbose output, filtering by test name, and cross-platform testing.

```bash
# Run all tests
go test ./...

# Run specific package tests
go test ./pkg/tunnel/...
go test ./pkg/cmd/...

# Verbose output
go test -v ./...

# Run specific test
go test -run TestName ./...

# Linux-only tests (tunnel, netlink)
GOOS=linux go test ./pkg/net/lwtunnel/...
GOOS=linux go test ./pkg/tunnel/...
```

--------------------------------

### Build Apoxy Docker Images with Dagger

Source: https://github.com/apoxy-dev/apoxy/blob/main/CLAUDE.md

Builds Docker images for Apoxy components using Dagger. Allows building all images or specific ones like apiserver, backplane, or tunnelproxy.

```bash
# Build all images
dagger call build-all

# Build specific image
dagger call build-apiserver
dagger call build-backplane
dagger call build-tunnelproxy
```

--------------------------------

### Cross-Compile for Linux

Source: https://github.com/apoxy-dev/apoxy/blob/main/CLAUDE.md

Builds Go packages for the Linux operating system, specifically for packages that have Linux-only dependencies like netlink/syscall. This is necessary when building on non-Linux systems like macOS.

```bash
Build with GOOS=linux for these packages on macOS.
```

--------------------------------

### Configure Local Development with External ClickHouse - Apoxy CLI

Source: https://context7.com/apoxy-dev/apoxy/llms.txt

Starts the local Apoxy development environment, connecting to an external ClickHouse instance instead of running one in Docker. This allows using a pre-existing or separately managed ClickHouse database.

```bash
# Use external ClickHouse instance
apoxy dev ./config/proxy.yaml --clickhouse-addr 192.168.1.100
```

--------------------------------

### Build Apoxy CLI

Source: https://github.com/apoxy-dev/apoxy/blob/main/CLAUDE.md

Builds the Apoxy CLI executable. Supports both release and debug builds, extracting version from git tags and injecting build metadata using Go ldflags.

```bash
# Release build (installs to $GOPATH/bin/apoxy)
./build.sh

# Debug build
./build.sh -t debug
```

--------------------------------

### Configure Local Development with Subprocess Mode - Apoxy CLI

Source: https://context7.com/apoxy-dev/apoxy/llms.txt

Starts the local Apoxy development environment using subprocesses instead of Docker containers for core components. This can be useful for environments where Docker is not available or preferred.

```bash
# Use subprocess mode instead of Docker
apoxy dev ./config/proxy.yaml --use-subprocess
```

--------------------------------

### Define and Manage Apoxy Proxy Resources

Source: https://context7.com/apoxy-dev/apoxy/llms.txt

The Proxy resource defines deployment configurations for API proxies across different infrastructure providers (cloud, Kubernetes, unmanaged). It supports telemetry options like access logs, content logging, and distributed tracing. The CLI commands allow for creating, listing, getting, applying, and deleting proxy resources.

```yaml
# proxy.yaml - Create a cloud-deployed proxy with tracing enabled
apiv1alpha2
kind: Proxy
metadata:
  name: my-api-proxy
spec:
  provider: cloud  # Options: cloud, kubernetes, unmanaged
  telemetry:
    tracing:
      enabled: true
      tags:
        environment:
          value: "production"
    accessLogs:
      json:
        custom_field: "%REQ(X-Request-ID)%"
    contentLogs:
      requestBodyEnabled: true
      responseBodyEnabled: false
  shutdown:
    drainTimeout: 30s
    minimumDrainTime: 30s
```

```bash
# Create a proxy from file
apoxy proxy create -f proxy.yaml

# List all proxies
apoxy proxy list
# NAME          PROVIDER   STATUS      TELEMETRY   AGE
# my-api-proxy  cloud      Ready (1)   [Tracing]   5m

# Get a specific proxy
apoxy proxy get my-api-proxy

# Apply proxy configuration (server-side apply)
apoxy proxy apply -f proxy.yaml --field-manager apoxy-cli

# Delete a proxy
apoxy proxy delete my-api-proxy
```

--------------------------------

### Generate Go Code

Source: https://github.com/apoxy-dev/apoxy/blob/main/CLAUDE.md

Executes Go's built-in code generation tools for all packages within the project. This command should be run after making changes to code that relies on code generation.

```bash
# Other code generation
go generate ./...
```

--------------------------------

### Regenerate API Helpers

Source: https://github.com/apoxy-dev/apoxy/blob/main/CLAUDE.md

Regenerates API helper clients and types after modifying API definitions. This is crucial for maintaining consistency between API definitions and their usage in the codebase.

```bash
# Regenerate API helpers after modifying types in api/
./codegen/update.sh
```

--------------------------------

### Regenerate Apoxy API Code

Source: https://github.com/apoxy-dev/apoxy/blob/main/CLAUDE.md

Regenerates helper code for API types, including DeepCopy methods, type registration, client code, listers, informers, and OpenAPI schemas. Requires matching k8s.io/code-generator and k8s.io/apimachinery versions.

```bash
./codegen/update.sh
```

--------------------------------

### Multi-Resource Apply CLI

Source: https://context7.com/apoxy-dev/apoxy/llms.txt

Applies multiple API resources from files, directories, or stdin using server-side apply semantics for conflict-free updates.

```APIDOC
## Multi-Resource Apply CLI

### Description
The global apply command supports applying multiple resources from files, directories, or stdin with server-side apply semantics for conflict-free updates.

### Usage Examples
```bash
# Apply a single file with multiple resources
apoxy apply -f gateway-setup.yaml
# gatewayclass "apoxy" applied
# gateway "api-gateway" applied
# httproute "api-route" applied

# Apply all manifests in a directory
apoxy apply -f ./manifests/

# Apply recursively through subdirectories
apoxy apply -f ./config/ -R

# Apply from stdin
cat <<EOF | apoxy apply -f -
apiVersion: core.apoxy.dev/v1alpha2
kind: Proxy
metadata:
  name: stdin-proxy
spec:
  provider: unmanaged
EOF
# proxy "stdin-proxy" applied

# Force apply with conflict resolution
apoxy apply -f proxy.yaml --force-conflicts --field-manager my-controller
```
```

--------------------------------

### Apply Backend Configurations using Apoxy CLI

Source: https://context7.com/apoxy-dev/apoxy/llms.txt

Applies backend configurations defined in a YAML file using the Apoxy CLI. This command processes the specified file and applies the backend resources to the Apoxy system.

```bash
# Apply backend configurations
apoxy apply -f backends.yaml
# backend "static-backend" applied
# backend "dynamic-proxy-backend" applied
```

--------------------------------

### Configure Static and Dynamic Backends with YAML

Source: https://context7.com/apoxy-dev/apoxy/llms.txt

Defines static and dynamic backend configurations using YAML. Static backends specify explicit endpoints, while dynamic backends leverage DNS for endpoint discovery. Supports various protocol and DNS caching options.

```yaml
apiVersion: core.apoxy.dev/v1alpha2
kind: Backend
metadata:
  name: static-backend
spec:
  protocol: tls  # Options: "", tls, h2, h2c
  endpoints:
    - fqdn: api.upstream.com
    - fqdn: api-backup.upstream.com
    - ip: 10.0.1.100
---
apiVersion: core.apoxy.dev/v1alpha2
kind: Backend
metadata:
  name: dynamic-proxy-backend
spec:
  dynamicProxy:
    dnsCacheConfig:
      dnsLookupFamily: v4_only  # Options: auto, v4_only, v6_only, v4_preferred, all
      dnsRefreshRate: 60s
      dnsMinRefreshRate: 5s
      hostTTL: 5m
      maxHosts: 1024
      dnsQueryTimeout: 5s
```

--------------------------------

### Backend Configurations

Source: https://context7.com/apoxy-dev/apoxy/llms.txt

Defines static and dynamic backend configurations for routing traffic.

```APIDOC
## Backend Configurations

### Description
Defines static and dynamic backend configurations for routing traffic. Backends can be configured with specific protocols and endpoints, or as dynamic proxies with advanced DNS caching options.

### Resource Type
`core.apoxy.dev/v1alpha2/Backend`

### Static Backend Example
```yaml
apiVersion: core.apoxy.dev/v1alpha2
kind: Backend
metadata:
  name: static-backend
spec:
  protocol: tls  # Options: "", tls, h2, h2c
  endpoints:
    - fqdn: api.upstream.com
    - fqdn: api-backup.upstream.com
    - ip: 10.0.1.100
```

### Dynamic Proxy Backend Example
```yaml
apiVersion: core.apoxy.dev/v1alpha2
kind: Backend
metadata:
  name: dynamic-proxy-backend
spec:
  dynamicProxy:
    dnsCacheConfig:
      dnsLookupFamily: v4_only  # Options: auto, v4_only, v6_only, v4_preferred, all
      dnsRefreshRate: 60s
      dnsMinRefreshRate: 5s
      hostTTL: 5m
      maxHosts: 1024
      dnsQueryTimeout: 5s
```

### Apply Backend Configurations
```bash
apoxy apply -f backends.yaml
```
```

--------------------------------

### Configure HTTP Route with Auth Filter and Backend

Source: https://context7.com/apoxy-dev/apoxy/llms.txt

Sets up an HTTPRoute named 'users-route' that listens on 'api.example.com' for requests to the '/users' path. It applies the 'auth-filter' EdgeFunction before forwarding requests to the 'users-api' backend service.

```yaml
apiVersion: gateway.apoxy.dev/v1
kind: HTTPRoute
metadata:
  name: users-route
spec:
  parentRefs:
    - name: main-gateway
      port: 80
  hostnames:
    - "api.example.com"
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /users
      filters:
        - type: ExtensionRef
          extensionRef:
            kind: EdgeFunction
            group: extensions.apoxy.dev
            name: auth-filter
      backendRefs:
        - kind: Backend
          name: users-api
          port: 443
```

--------------------------------

### Apply Resources from Directory - Apoxy CLI

Source: https://context7.com/apoxy-dev/apoxy/llms.txt

Applies all Apoxy resource manifests located within a specified directory. The `-R` flag enables recursive application through subdirectories.

```bash
# Apply all manifests in a directory
apoxy apply -f ./manifests/

# Apply recursively through subdirectories
apoxy apply -f ./config/ -R
```

--------------------------------

### Apply Resources from Stdin - Apoxy CLI

Source: https://context7.com/apoxy-dev/apoxy/llms.txt

Applies Apoxy resources defined in standard input. This is useful for scripting and piping configurations directly to the apply command.

```bash
# Apply from stdin
cat <<EOF | apoxy apply -f -
apiVersion: core.apoxy.dev/v1alpha2
kind: Proxy
metadata:
  name: stdin-proxy
spec:
  provider: unmanaged
EOF
# proxy "stdin-proxy" applied
```

--------------------------------

### Gateway and HTTPRoute Configuration

Source: https://context7.com/apoxy-dev/apoxy/llms.txt

Configures Gateways and HTTPRoutes using the Kubernetes Gateway API. Gateways define listener configurations, while HTTPRoutes specify routing rules for directing traffic to various backends.

```APIDOC
## Gateway and HTTPRoute Configuration

### Description
Configures Gateways and HTTPRoutes using the Kubernetes Gateway API. Gateways define listener configurations for proxies, and HTTPRoutes specify routing rules based on hostnames, paths, and headers, directing traffic to Backends, EdgeFunctions, or other resources.

### Method
CLI Command

### Endpoint
N/A (CLI command)

### Parameters

#### Query Parameters
- **-f, --filename** (string) - Required - Path to the YAML file containing Gateway and HTTPRoute configurations.

### Request Example
```yaml
# gateway-setup.yaml
apiVersion: gateway.apoxy.dev/v1
kind: GatewayClass
metadata:
  name: apoxy
spec:
  controllerName: gateway.apoxy.dev/gatewayclass-controller
---
apiVersion: gateway.apoxy.dev/v1
kind: Gateway
metadata:
  name: api-gateway
spec:
  gatewayClassName: apoxy
  infrastructure:
    parametersRef:
      kind: Proxy
      name: my-api-proxy
  listeners:
    - name: http
      protocol: HTTP
      port: 80
    - name: https
      protocol: HTTPS
      port: 443
---
apiVersion: gateway.apoxy.dev/v1
kind: HTTPRoute
metadata:
  name: api-route
spec:
  parentRefs:
    - name: api-gateway
      port: 80
      kind: Gateway
  hostnames:
    - "api.example.com"
    - "*.api.example.com"
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /v1
      backendRefs:
        - kind: Backend
          name: api-backend
          port: 8080
      retry:
        codes:
          - 503
          - 504
```

```bash
apoxy apply -f gateway-setup.yaml
apoxy gateway list
apoxy gateway get api-gateway
apoxy gateway routes list
```

### Response
#### Success Response
- **Configuration applied confirmation**: Output indicating successful application of gateway and route configurations.
- **List of gateways**: Table format showing gateway name, class, listeners, status, and age.
- **Gateway details**: Information about a specific gateway, including attached routes.

#### Response Example
```
# apoxy gateway list output
NAME         CLASS   LISTENERS    STATUS    AGE
api-gateway  apoxy   HTTP/80,...  Accepted  2m
```
```

--------------------------------

### Local Development Mode CLI

Source: https://context7.com/apoxy-dev/apoxy/llms.txt

Runs a complete local development environment including API server, backplane, and tunnel proxy. Automatically reloads on configuration file changes.

```APIDOC
## Local Development Mode CLI

### Description
The `apoxy dev` command runs a complete local development environment with API server, backplane, and tunnel proxy. It watches configuration files for changes and automatically reloads.

### Usage Examples
```bash
# Start local development environment with config file
apoxy dev ./config/proxy.yaml
# Starting Apoxy server with Proxy name: my-laptop
# Starting apiserver using driver mode: docker
# Starting clickhouse using driver mode: docker
# Starting backplane using driver mode: docker
# Starting tunnelproxy using driver mode: docker
# Watching ./config/proxy.yaml for changes...

# Use subprocess mode instead of Docker
apoxy dev ./config/proxy.yaml --use-subprocess

# Use external ClickHouse instance
apoxy dev ./config/proxy.yaml --clickhouse-addr 192.168.1.100
```
```

--------------------------------

### Backend Configuration

Source: https://context7.com/apoxy-dev/apoxy/llms.txt

Defines Backend resources, which represent upstream endpoints for proxied traffic. Backends support static endpoints and dynamic forward proxy modes with various protocol options.

```APIDOC
## Backend Configuration

### Description
Defines Backend resources that specify upstream endpoints receiving proxied traffic. Supports static FQDN/IP endpoints and dynamic forward proxy mode with DNS resolution. Protocol options include plaintext, TLS, HTTP/2, and HTTP/2 cleartext (h2c).

### Method
CLI Command / YAML Configuration

### Endpoint
N/A (CLI command / Resource definition)

### Parameters

#### Request Body (YAML Example)
```yaml
apiVersion: core.apoxy.dev/v1alpha2
kind: Backend
metadata:
  name: api-backend
spec:
  address: "api.upstream.svc.cluster.local"
  port: 8080
  protocol: HTTP
  # Or for dynamic resolution:
  # forwardProxy:
  #   enabled: true
  #   resolver: "8.8.8.8:53"
```

### Request Example
```bash
# Assuming backend.yaml contains the above configuration
apoxy apply -f backend.yaml
```

### Response
#### Success Response
- **Backend creation/update confirmation**: Output indicating the successful application of the backend configuration.
```

--------------------------------

### Manage Edge Functions using Apoxy CLI

Source: https://context7.com/apoxy-dev/apoxy/llms.txt

Provides command-line interface commands for managing EdgeFunctions. Includes creating, listing, applying (server-side), and deleting EdgeFunction resources within the Apoxy system.

```bash
# Create edge function
apoxy edgefunction create -f edgefunction.yaml
# edge function "hello-api" created

# List edge functions
apoxy edgefunction list
# NAME       MODE     SOURCE TYPE  LIVE REVISION  AGE
# hello-api  backend  JavaScript   hello-api-v1   30s

# Get edge function details
apoxy edgefunction get hello-api

# Apply edge function (server-side apply)
apoxy edgefunction apply -f edgefunction.yaml

# Delete edge function
apoxy edgefunction delete hello-api
```

--------------------------------

### Define Backend Service for Users API

Source: https://context7.com/apoxy-dev/apoxy/llms.txt

Defines a backend service named 'users-api' that uses the 'h2' protocol and exposes an endpoint at 'users.internal.example.com'. This configuration is part of the core Apoxy API.

```yaml
apiVersion: core.apoxy.dev/v1alpha2
kind: Backend
metadata:
  name: users-api
spec:
  protocol: h2
  endpoints:
    - fqdn: users.internal.example.com
```

--------------------------------

### RateLimit Policy API

Source: https://context7.com/apoxy-dev/apoxy/llms.txt

Configures request throttling based on descriptors. Supports shadow mode for testing without enforcement.

```APIDOC
## RateLimit Policy API

### Description
Configures request throttling based on descriptors (key-value pairs extracted from requests). Shadow mode enables testing rate limits without enforcement.

### Resource Definition
```yaml
apiVersion: policy.apoxy.dev/v1alpha1
kind: RateLimit
metadata:
  name: api-ratelimit
spec:
  descriptors:
    - key: "remote_address"
      rateLimit:
        unit: Minute  # Options: Second, Minute, Hour, Day
        requestsPerUnit: 100
    - key: "header_match"
      value: "api-key-premium"
      rateLimit:
        unit: Minute
        requestsPerUnit: 1000
    - key: "path"
      value: "/api/heavy"
      rateLimit:
        unit: Second
        requestsPerUnit: 10
      shadowMode: true  # Log but don't enforce
```
```

--------------------------------

### Authenticate CLI with Apoxy Platform

Source: https://context7.com/apoxy-dev/apoxy/llms.txt

The `apoxy auth` command authenticates the CLI with the Apoxy platform by opening a browser for OAuth login. It stores credentials locally for subsequent API calls. The `--check` flag verifies authentication status without prompting.

```bash
# Authenticate with Apoxy (opens browser for login)
apoxy auth

# Check authentication status without prompting
apoxy auth --check

# Expected output when authenticated:
# Authenticated

# Expected output when not authenticated and --check is used:
# Invalid authentication
```

--------------------------------

### Configure Gateway and HTTPRoute for Traffic Routing

Source: https://context7.com/apoxy-dev/apoxy/llms.txt

Gateways define listener configurations for proxies using the Kubernetes Gateway API, while HTTPRoutes specify routing rules for directing traffic to backends based on hostnames, paths, and headers. These resources can be applied using the `apoxy apply` command and managed via `apoxy gateway` commands.

```yaml
# gateway-setup.yaml - Complete gateway with HTTP routing
apiv1
kind: GatewayClass
metadata:
  name: apoxy
spec:
  controllerName: gateway.apoxy.dev/gatewayclass-controller
---
apiv1
kind: Gateway
metadata:
  name: api-gateway
spec:
  gatewayClassName: apoxy
  infrastructure:
    parametersRef:
      kind: Proxy
      name: my-api-proxy
  listeners:
    - name: http
      protocol: HTTP
      port: 80
    - name: https
      protocol: HTTPS
      port: 443
---
apiv1
kind: HTTPRoute
metadata:
  name: api-route
spec:
  parentRefs:
    - name: api-gateway
      port: 80
      kind: Gateway
  hostnames:
    - "api.example.com"
    - "*.api.example.com"
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /v1
      backendRefs:
        - kind: Backend
          name: api-backend
          port: 8080
      retry:
        codes:
          - 503
          - 504
```

```bash
# Apply gateway configuration
apoxy apply -f gateway-setup.yaml

# List gateways
apoxy gateway list
# NAME         CLASS   LISTENERS    STATUS    AGE
# api-gateway  apoxy   HTTP/80,...  Accepted  2m

# Get gateway with attached routes
apoxy gateway get api-gateway
# NAME         CLASS   LISTENERS    STATUS    AGE
# api-gateway  apoxy   HTTP/80,...  Accepted  2m
#
# Attached Routes (1):
#   HTTPRoutes (1):
#     - api-route (hostnames: api.example.com, rules: 1)

# List all routes
apoxy gateway routes list
```

--------------------------------

### Proxy Resource Management

Source: https://context7.com/apoxy-dev/apoxy/llms.txt

Manages Proxy resources, which define the deployment and configuration of API proxies. Proxies can be deployed to cloud, Kubernetes, or unmanaged infrastructures and configured with various telemetry options.

```APIDOC
## Proxy Resource Management

### Description
Manages Proxy resources, defining where and how API proxies are deployed. Supports cloud, Kubernetes, and unmanaged providers, with configurable telemetry options like access logs, content logging, and distributed tracing.

### Method
CLI Command

### Endpoint
N/A (CLI command)

### Parameters

#### Query Parameters
- **-f, --filename** (string) - Required - Path to the YAML file defining the proxy configuration.
- **--field-manager** (string) - Optional - Specifies the field manager for server-side apply operations.

### Request Example
```yaml
# proxy.yaml
apiVersion: core.apoxy.dev/v1alpha2
kind: Proxy
metadata:
  name: my-api-proxy
spec:
  provider: cloud
  telemetry:
    tracing:
      enabled: true
      tags:
        environment:
          value: "production"
    accessLogs:
      json:
        custom_field: "%REQ(X-Request-ID)%"
    contentLogs:
      requestBodyEnabled: true
      responseBodyEnabled: false
  shutdown:
    drainTimeout: 30s
    minimumDrainTime: 30s
```

```bash
apoxy proxy create -f proxy.yaml
apoxy proxy list
apoxy proxy get my-api-proxy
apoxy proxy apply -f proxy.yaml --field-manager apoxy-cli
apoxy proxy delete my-api-proxy
```

### Response
#### Success Response
- **Proxy creation/update/deletion confirmation**: Output indicating the success of the operation.
- **List of proxies**: Table format displaying proxy name, provider, status, telemetry, and age.

#### Response Example
```
# apoxy proxy list output
NAME          PROVIDER   STATUS      TELEMETRY   AGE
my-api-proxy  cloud      Ready (1)   [Tracing]   5m
```
```

--------------------------------

### Apply Single Resource File - Apoxy CLI

Source: https://context7.com/apoxy-dev/apoxy/llms.txt

Applies a single YAML file containing multiple Apoxy resources using the `apoxy apply` command. This command utilizes server-side apply for conflict-free updates.

```bash
# Apply a single file with multiple resources
apoxy apply -f gateway-setup.yaml
# gatewayclass "apoxy" applied
# gateway "api-gateway" applied
# httproute "api-route" applied
```

--------------------------------

### CLI Authentication

Source: https://context7.com/apoxy-dev/apoxy/llms.txt

Authenticates the Apoxy CLI with the Apoxy platform. This command initiates an OAuth login flow via the Apoxy Dashboard and stores credentials locally for subsequent API interactions.

```APIDOC
## CLI Authentication

### Description
Authenticates the Apoxy CLI with the Apoxy platform. It opens a browser window for OAuth login via the Apoxy Dashboard and stores credentials locally for subsequent API calls.

### Method
CLI Command

### Endpoint
N/A (CLI command)

### Parameters

#### Query Parameters
- **--check** (boolean) - Optional - Checks authentication status without prompting for login.

### Request Example
```bash
apoxy auth
apoxy auth --check
```

### Response
#### Success Response
- **Authenticated**: Indicates successful authentication.

#### Error Response
- **Invalid authentication**: Indicates that the CLI is not authenticated.

#### Response Example
```
Authenticated
```
```

--------------------------------

### Apply Tunnel Configuration - Apoxy CLI

Source: https://context7.com/apoxy-dev/apoxy/llms.txt

Applies the tunnel configuration using the Apoxy CLI. This command creates or updates the tunnel resource on the server. It also shows how to run the tunnel agent to establish the connection.

```bash
# Create tunnel
apoxy apply -f tunnel.yaml
# tunnel "private-network" applied

# Run tunnel agent (connects to tunnel relay)
apoxy tunnel run --name private-network
```

--------------------------------

### Domain Management API

Source: https://context7.com/apoxy-dev/apoxy/llms.txt

Manages custom domain names for DNS and routing. Supports various DNS record types, automatic TLS certificates, and forwarding rules.

```APIDOC
## Domain Management API

### Description
Manages custom domain names for DNS and routing. Supports various DNS record types (A, AAAA, CNAME, TXT, MX, etc.), automatic TLS certificate provisioning via Let's Encrypt, and forwarding rules for non-HTTP protocols.

### Resource Definition
```yaml
apiVersion: core.apoxy.dev/v1alpha2
kind: Domain
metadata:
  name: api-domain
spec:
  zone: example-zone
  subdomains:
    - api
    - "*.api"  # Wildcard subdomain
  customDomains:
    - custom.mydomain.com
  target:
    ref:
      name: my-api-proxy
      kind: Proxy
  tls:
    certificateAuthority: letsencrypt
  filters:
    - name: rate-limiter
```

### DNS-Only Domain Definition
```yaml
apiVersion: core.apoxy.dev/v1alpha2
kind: Domain
metadata:
  name: dns-records
spec:
  zone: example-zone
  subdomains:
    - mail
  target:
    dns:
      dnsOnly: true
      mx:
        - "10 mail.example.com"
      txt:
        - "v=spf1 include:_spf.example.com ~all"
      ttl: 300
```
```

--------------------------------

### Configure Custom Domain with TLS - Apoxy YAML

Source: https://context7.com/apoxy-dev/apoxy/llms.txt

Defines a custom domain with automatic TLS provisioning using Let's Encrypt. It supports wildcard subdomains and specifies a target proxy for routing. This configuration is used for managing DNS and routing for custom domain names.

```yaml
apiVersion: core.apoxy.dev/v1alpha2
kind: Domain
metadata:
  name: api-domain
spec:
  zone: example-zone
  subdomains:
    - api
    - "*.api"  # Wildcard subdomain
  customDomains:
    - custom.mydomain.com
  target:
    ref:
      name: my-api-proxy
      kind: Proxy
  tls:
    certificateAuthority: letsencrypt
  filters:
    - name: rate-limiter
```

--------------------------------

### EdgeFunction Development

Source: https://context7.com/apoxy-dev/apoxy/llms.txt

Enables custom code execution at the edge for request/response transformations using JavaScript, WebAssembly, or Go plugins.

```APIDOC
## EdgeFunction Development

### Description
EdgeFunctions run custom code at the edge for request/response transformations. They support JavaScript (compiled to WebAssembly), WebAssembly binaries, and Go plugins. Functions can run in backend mode (serving requests directly) or filter mode (intercepting requests before backends).

### Resource Type
`extensions.apoxy.dev/v1alpha2/EdgeFunction`

### JavaScript Edge Function Example
```yaml
# edgefunction.yaml - JavaScript edge function as backend
apiVersion: extensions.apoxy.dev/v1alpha2
kind: EdgeFunction
metadata:
  name: hello-api
spec:
  revisionHistoryLimit: 10
  template:
    mode: backend  # Options: backend, filter
    runtime:
      port: 8080
      timeout: 30s
      capabilities:
        fetchAPI: true
        kv: true
    env:
      - name: API_KEY
        value: "secret-key"
    code:
      jsSource:
        entrypoint: "main.ts"
        assets:
          files:
            - path: "main.ts"
              content: |
                interface RequestPayload {
                  name: string;
                }

                Deno.serve(async (req: Request) => {
                  const url = new URL(req.url);

                  if (req.method === "POST") {
                    const { name }: RequestPayload = await req.json();
                    return new Response(
                      JSON.stringify({ message: `Hello ${name}!` }),
                      {
                        headers: {
                          "Content-Type": "application/json",
                          "X-Powered-By": "Apoxy EdgeFunction"
                        }
                      }
                    );
                  }

                  return new Response(
                    JSON.stringify({ status: "ok", path: url.pathname }),
                    { headers: { "Content-Type": "application/json" } }
                  );
                });
```

### WebAssembly Edge Function Example
```yaml
# edgefunction-wasm.yaml - WebAssembly edge function
apiVersion: extensions.apoxy.dev/v1alpha2
kind: EdgeFunction
metadata:
  name: wasm-filter
spec:
  template:
    mode: filter
    code:
      wasmSource:
        url: "https://example.com/filter.wasm"
```

### Go Plugin Edge Function Example (unmanaged/kubernetes only)
```yaml
# edgefunction-go.yaml - Go plugin edge function (unmanaged/kubernetes only)
apiVersion: extensions.apoxy.dev/v1alpha2
kind: EdgeFunction
metadata:
  name: go-filter
spec:
  template:
    mode: filter
    code:
      goPluginSource:
        oci:
          repo: registry.example.com/myorg/my-filter
          tag: "v1.0.0"
          credentials:
            username: "user"
            password: "pass"
        pluginConfig: '{"setting": "value"}'
```

### EdgeFunction Management Commands

#### Create Edge Function
```bash
apoxy edgefunction create -f edgefunction.yaml
```

#### List Edge Functions
```bash
apoxy edgefunction list
```

#### Get Edge Function Details
```bash
apoxy edgefunction get hello-api
```

#### Apply Edge Function (server-side apply)
```bash
apoxy edgefunction apply -f edgefunction.yaml
```

#### Delete Edge Function
```bash
apoxy edgefunction delete hello-api
```
```

--------------------------------

### Configure Go Plugin EdgeFunction as a Filter

Source: https://context7.com/apoxy-dev/apoxy/llms.txt

Defines a Go plugin EdgeFunction for use in filter mode, specifically for unmanaged or Kubernetes environments. It specifies the Go plugin source via an OCI registry and includes optional credentials and plugin configuration.

```yaml
# edgefunction-go.yaml - Go plugin edge function (unmanaged/kubernetes only)
apiVersion: extensions.apoxy.dev/v1alpha2
kind: EdgeFunction
metadata:
  name: go-filter
spec:
  template:
    mode: filter
    code:
      goPluginSource:
        oci:
          repo: registry.example.com/myorg/my-filter
          tag: "v1.0.0"
          credentials:
            username: "user"
            password: "pass"
        pluginConfig: '{"setting": "value"}'
```

--------------------------------

### Develop JavaScript EdgeFunction as a Backend

Source: https://context7.com/apoxy-dev/apoxy/llms.txt

Defines a JavaScript EdgeFunction that operates in backend mode. It includes environment variables, specifies runtime capabilities like fetchAPI and kv, and provides the JavaScript source code for handling requests.

```yaml
# edgefunction.yaml - JavaScript edge function as backend
apiVersion: extensions.apoxy.dev/v1alpha2
kind: EdgeFunction
metadata:
  name: hello-api
spec:
  revisionHistoryLimit: 10
  template:
    mode: backend  # Options: backend, filter
    runtime:
      port: 8080
      timeout: 30s
      capabilities:
        fetchAPI: true
        kv: true
    env:
      - name: API_KEY
        value: "secret-key"
    code:
      jsSource:
        entrypoint: "main.ts"
        assets:
          files:
            - path: "main.ts"
              content: |
                interface RequestPayload {
                  name: string;
                }

                Deno.serve(async (req: Request) => {
                  const url = new URL(req.url);

                  if (req.method === "POST") {
                    const { name }: RequestPayload = await req.json();
                    return new Response(
                      JSON.stringify({ message: `Hello ${name}!` }),
                      {
                        headers: {
                          "Content-Type": "application/json",
                          "X-Powered-By": "Apoxy EdgeFunction"
                        }
                      }
                    );
                  }

                  return new Response(
                    JSON.stringify({ status: "ok", path: url.pathname }),
                    { headers: { "Content-Type": "application/json" } }
                  );
                });
```

--------------------------------

### HTTPRoute with EdgeFunction Integration

Source: https://context7.com/apoxy-dev/apoxy/llms.txt

Integrates EdgeFunctions into HTTPRoutes, either as direct backends or as filters for request processing.

```APIDOC
## HTTPRoute with EdgeFunction Integration

### Description
EdgeFunctions can be used as route backends or as filters that process requests before forwarding to other backends. Filter mode is more performant for transformations as it reduces network hops.

### Resource Type
`gateway.apoxy.dev/v1/HTTPRoute`

### Example Configuration
```yaml
# route-with-edgefunction.yaml
apiVersion: gateway.apoxy.dev/v1
kind: HTTPRoute
metadata:
  name: filtered-route
spec:
  parentRefs:
    - name: api-gateway
      port: 80
      kind: Gateway
  hostnames:
    - "*"
  rules:
    # Route to EdgeFunction as backend
    - matches:
        - path:
            type: PathPrefix
            value: /api
      backendRefs:
        - kind: EdgeFunction
          group: extensions.apoxy.dev
          name: hello-api
    # Route through EdgeFunction filter to backend
    - matches:
        - path:
            type: PathPrefix
            value: /proxy
      filters:
        - type: ExtensionRef
          extensionRef:
            kind: EdgeFunction
            group: extensions.apoxy.dev
            name: wasm-filter
      backendRefs:
        - kind: Backend
          name: dynamic-proxy-backend
          port: 80
```
```

--------------------------------

### Configure Tunnel with Egress Gateway - Apoxy YAML

Source: https://context7.com/apoxy-dev/apoxy/llms.txt

Sets up a tunnel for secure connectivity to private networks, with an option to enable egress gateway mode. Egress gateway allows tunnel agents to route outbound traffic through Apoxy, enabling SNAT for outbound connections.

```yaml
# tunnel.yaml - Tunnel with egress gateway
apiVersion: core.apoxy.dev/v1alpha2
kind: Tunnel
metadata:
  name: private-network
spec:
  egressGateway:
    enabled: true  # Enable SNAT for outbound traffic from agents
```

--------------------------------

### Force Apply with Conflict Resolution - Apoxy CLI

Source: https://context7.com/apoxy-dev/apoxy/llms.txt

Forces the application of resources, resolving conflicts by overwriting changes. This is useful when a controller needs to take precedence during updates.

```bash
# Force apply with conflict resolution
apoxy apply -f proxy.yaml --force-conflicts --field-manager my-controller
```

--------------------------------

### Tunnel Configuration API

Source: https://context7.com/apoxy-dev/apoxy/llms.txt

Provides VPN-like connectivity between Apoxy's edge and private networks. Supports egress gateway mode for outbound traffic routing.

```APIDOC
## Tunnel Configuration API

### Description
Provides VPN-like connectivity between Apoxy's edge and private networks. Enables secure access to internal services without exposing them to the public internet. Egress gateway mode allows tunnel agents to route outbound traffic through Apoxy.

### Resource Definition
```yaml
apiVersion: core.apoxy.dev/v1alpha2
kind: Tunnel
metadata:
  name: private-network
spec:
  egressGateway:
    enabled: true  # Enable SNAT for outbound traffic from agents
```

### CLI Commands
```bash
# Create tunnel
apoxy apply -f tunnel.yaml
# tunnel "private-network" applied

# Run tunnel agent (connects to tunnel relay)
apoxy tunnel run --name private-network
```
```

--------------------------------

### Configure WebAssembly EdgeFunction as a Filter

Source: https://context7.com/apoxy-dev/apoxy/llms.txt

Defines a WebAssembly EdgeFunction configured to run in filter mode. It specifies the source of the WebAssembly binary via a URL, allowing it to intercept and process requests before they reach the backend.

```yaml
# edgefunction-wasm.yaml - WebAssembly edge function
apiVersion: extensions.apoxy.dev/v1alpha2
kind: EdgeFunction
metadata:
  name: wasm-filter
spec:
  template:
    mode: filter
    code:
      wasmSource:
        url: "https://example.com/filter.wasm"
```

--------------------------------

### Implement Auth Edge Function in JavaScript

Source: https://context7.com/apoxy-dev/apoxy/llms.txt

Creates an 'auth-filter' EdgeFunction using JavaScript. This function acts as a filter, validating API keys from incoming requests before allowing them to proceed to the backend. It returns a 401 Unauthorized response if the API key is missing.

```javascript
// Auth middleware - validates API keys
export default {
  async fetch(request: Request) {
    const apiKey = request.headers.get("X-API-Key");
    if (!apiKey) {
      return new Response("Missing API Key", { status: 401 });
    }
    // Continue to backend
    return fetch(request);
  }
};
```

--------------------------------

### Route Traffic Through EdgeFunction Filter to Backend

Source: https://context7.com/apoxy-dev/apoxy/llms.txt

Configures an HTTPRoute to use an EdgeFunction as a filter before forwarding traffic to a backend. This approach is efficient for request transformations, reducing network hops.

```yaml
# route-with-edgefunction.yaml
apiVersion: gateway.apoxy.dev/v1
kind: HTTPRoute
metadata:
  name: filtered-route
spec:
  parentRefs:
    - name: api-gateway
      port: 80
      kind: Gateway
  hostnames:
    - "*"
  rules:
    # Route to EdgeFunction as backend
    - matches:
        - path:
            type: PathPrefix
            value: /api
      backendRefs:
        - kind: EdgeFunction
          group: extensions.apoxy.dev
          name: hello-api
    # Route through EdgeFunction filter to backend
    - matches:
        - path:
            type: PathPrefix
            value: /proxy
      filters:
        - type: ExtensionRef
          extensionRef:
            kind: EdgeFunction
            group: extensions.apoxy.dev
            name: wasm-filter
      backendRefs:
        - kind: Backend
          name: dynamic-proxy-backend
          port: 80
```

--------------------------------

### Configure DNS-Only Domain - Apoxy YAML

Source: https://context7.com/apoxy-dev/apoxy/llms.txt

Configures a domain solely for DNS records without proxy routing. This is useful for services like mail servers where only DNS entries (MX, TXT) are needed. It allows specifying TTL for DNS records.

```yaml
# DNS-only domain (no proxy routing)
apiVersion: core.apoxy.dev/v1alpha2
kind: Domain
metadata:
  name: dns-records
spec:
  zone: example-zone
  subdomains:
    - mail
  target:
    dns:
      dnsOnly: true
      mx:
        - "10 mail.example.com"
      txt:
        - "v=spf1 include:_spf.example.com ~all"
      ttl: 300
```

--------------------------------

### Configure API Rate Limiting Policy - Apoxy YAML

Source: https://context7.com/apoxy-dev/apoxy/llms.txt

Defines a rate limiting policy for API requests based on various descriptors like remote address, headers, or specific paths. It supports a shadow mode to test limits without enforcement.

```yaml
# ratelimit.yaml - API rate limiting policy
apiVersion: policy.apoxy.dev/v1alpha1
kind: RateLimit
metadata:
  name: api-ratelimit
spec:
  descriptors:
    - key: "remote_address"
      rateLimit:
        unit: Minute  # Options: Second, Minute, Hour, Day
        requestsPerUnit: 100
    - key: "header_match"
      value: "api-key-premium"
      rateLimit:
        unit: Minute
        requestsPerUnit: 1000
    - key: "path"
      value: "/api/heavy"
      rateLimit:
        unit: Second
        requestsPerUnit: 10
      shadowMode: true  # Log but don't enforce
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.