# Deployment Considerations for FastProxy: Embedded, Sidecar, and Gateway Patterns

> Explore FastProxy deployment options: embedded Go SDK, sidecar, or gateway. Learn how to optimize lifecycle management and dynamic configuration for your application.

- Repository: [Kingson4Wu/fast_proxy](https://github.com/kingson4wu/fast_proxy)
- Tags: architecture
- Published: 2026-03-05

---

**FastProxy supports three distinct deployment models—embedded Go SDK, containerized sidecar, and standalone central gateway—all utilizing the identical `common/server` core for graceful lifecycle management, FastHTTP optimization, and dynamic configuration via YAML or Apollo.**

FastProxy is a high-performance Go service proxy designed for flexible deployment across microservice architectures. Understanding the deployment considerations for FastProxy ensures you can choose between tight application integration, service-mesh isolation, or centralized traffic management while maintaining consistent configuration and security guarantees.

## Deployment Modes Overview

FastProxy offers three operational patterns that share the same core engine located in [`common/server/server.go`](https://github.com/kingson4wu/fast_proxy/blob/main/common/server/server.go)【/cache/repos/github.com/kingson4wu/fast_proxy/main/common/server/server.go#L1-L84】:

- **Embedded SDK** – Import FastProxy as a Go library and start the server from your application code. Ideal for zero-process overhead and tight integration.
- **Sidecar** – Deploy as a separate binary alongside a service in Docker or Kubernetes. Provides service-mesh style isolation with independent lifecycle management.
- **Central Ingress/Egress Gateway** – Run as a standalone gateway fronting many services. Enables central policy enforcement and observability aggregation.

## Building and Running the Binaries

FastProxy ships with pre-defined build targets for five binaries: `center`, `server`, `in-proxy`, `out-proxy`, and `client`. Compile them using the repository `Makefile`:

```bash
make

```

This places all executables in the repository root. To start a complete pipeline on a single host:

```bash
./center &
./server &
./in-proxy &
./out-proxy &
./client

```

Each binary reads configuration via the `Read` functions in their respective `*config` packages. For example, [`inproxy/inconfig/config.go`](https://github.com/kingson4wu/fast_proxy/blob/main/inproxy/inconfig/config.go) and [`outproxy/outconfig/config.go`](https://github.com/kingson4wu/fast_proxy/blob/main/outproxy/outconfig/config.go) handle YAML parsing and default injection【/cache/repos/github.com/kingson4wu/fast_proxy/main/inproxy/inconfig/config.go#L1-L30】【/cache/repos/github.com/kingson4wu/fast_proxy/main/outproxy/outconfig/config.go#L1-L30】.

## Embedded SDK Deployment

Add FastProxy as a module dependency to integrate the proxy directly into your Go application:

```bash
go get github.com/kingson4wu/fast_proxy

```

Initialize and start the server programmatically:

```go
import (
    "github.com/Kingson4Wu/fast_proxy/common/logger/zap"
    "github.com/Kingson4Wu/fast_proxy/outproxy"
    "github.com/Kingson4Wu/fast_proxy/outproxy/outconfig"
)

func main() {
    cfg := outconfig.Config{
        ServerPort:     8080,
        FastHttpEnable: false,
    }
    outconfig.Read(cfg)     // load yaml or apollo config
    outproxy.NewServer(cfg) // boots server, registers shutdown hooks
    zap.DefaultLogger().Info("proxy embedded and ready")
}

```

The `outproxy.NewServer` function in [`outproxy/outproxy.go`](https://github.com/kingson4wu/fast_proxy/blob/main/outproxy/outproxy.go) wires the proxy handler (`proxy.GetProxy`) and ensures resource cleanup on termination【/cache/repos/github.com/kingson4wu/fast_proxy/main/outproxy/outproxy.go#L29-L43】.

## Sidecar Deployment with Docker and Kubernetes

For containerized environments, package the binary with a minimal Dockerfile:

```dockerfile
FROM golang:1.22-alpine AS builder
WORKDIR /app
COPY . .
RUN go build -o /outproxy ./outproxy

FROM alpine:latest
COPY --from=builder /outproxy /usr/local/bin/outproxy
COPY outproxy/config.yaml /etc/fast_proxy/config.yaml
ENTRYPOINT ["/usr/local/bin/outproxy"]

```

Deploy to Kubernetes using a ConfigMap for configuration separation:

```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: fast-proxy-sidecar
spec:
  replicas: 1
  selector:
    matchLabels:
      app: fast-proxy
  template:
    metadata:
      labels:
        app: fast-proxy
    spec:
      containers:
        - name: fast-proxy
          image: yourrepo/fast-proxy:latest
          args: ["-c", "/etc/fast_proxy/config.yaml"]
          ports:
            - containerPort: 8080
          volumeMounts:
            - name: config
              mountPath: /etc/fast_proxy
      volumes:
        - name: config
          configMap:
            name: fast-proxy-config

```

The sidecar reads configuration through [`outproxy/outconfig/yaml_config.go`](https://github.com/kingson4wu/fast_proxy/blob/main/outproxy/outconfig/yaml_config.go) and registers with the built-in service discovery when enabled【/cache/repos/github.com/kingson4wu/fast_proxy/main/common/server/server.go#L84-L90】.

## Central Gateway Deployment

When deploying as a dedicated gateway, enable **FastHTTP** for maximum throughput. Set `FastHttpEnable: true` in your YAML configuration; the server switches to `fasthttp.ListenAndServe` and automatically exposes pprof endpoints at `/debug/pprof` for profiling【/cache/repos/github.com/kingson4wu/fast_proxy/main/common/server/server.go#L92-L104】.

Cluster multiple gateway instances behind a load balancer. Each instance registers itself with the `ServiceCenter` via `server.Start`, allowing the **Center** component to maintain an up-to-date service registry【/cache/repos/github.com/kingson4wu/fast_proxy/main/common/server/server.go#L84-L89】.

## Configuration Sources

FastProxy abstracts configuration through two backends defined in the `*config` packages:

| Source | Implementation | Loading Method |
|--------|---------------|----------------|
| **YAML files** | `*config/yaml_config.go` | `Read(c)` parses the struct and injects defaults |
| **Apollo (Ctrip)** | [`common/config/apollo_config.go`](https://github.com/kingson4wu/fast_proxy/blob/main/common/config/apollo_config.go) | `LoadApolloConfig(appId, ns, cluster, addr, logger)` creates a watching client【/cache/repos/github.com/kingson4wu/fast_proxy/main/common/config/apollo_config.go#L13-L41】 |

Combine both sources—use YAML for static values and Apollo for dynamic policy updates without restarting.

## Runtime and Resource Management

FastProxy handles production concerns through the `common/server` package:

- **Graceful shutdown** – `Proxy.Start` registers OS signal handlers and calls `http.Server.Shutdown` with a configurable `WithShutdownTimeout`. The routine deregisters the instance from the service center before exit.
- **Metrics and profiling** – Built-in pprof is available when FastHTTP mode is active. Logging uses the Zap-based logger (`common/logger/zap`).
- **Concurrency control** – The server uses a `sync.WaitGroup` to await goroutine workers. Swap handlers via `WithCustomHandler` for custom logic.
- **Encryption** – TLS and payload encryption utilize primitives in `common/encrypt` (AES and custom algorithms), invoked by `inproxy/internal/encrypt` and `outproxy/internal/encrypt`.
- **Service discovery** – Pass a `ServiceCenter` implementation (Consul, etcd) via `WithServiceCenter` to enable dynamic registration.

## Quick Start: Out-Proxy Implementation

Deploy an outbound proxy using the public API:

```go
package main

import (
    "github.com/Kingson4Wu/fast_proxy/outproxy"
    "github.com/Kingson4Wu/fast_proxy/outproxy/outconfig"
    "github.com/Kingson4Wu/fast_proxy/common/logger/zap"
)

func main() {
    cfg := outconfig.Config{
        ServerPort:      9090,
        FastHttpEnable:  true,
    }
    outconfig.Read(cfg)       // parses yaml/apollo
    outproxy.BuildClient(cfg) // prepares connection pool
    outproxy.NewServer(cfg)   // starts server with shutdown hooks
    zap.DefaultLogger().Info("out-proxy ready")
}

```

This implementation leverages [`outproxy/outproxy.go`](https://github.com/kingson4wu/fast_proxy/blob/main/outproxy/outproxy.go) for server boot and `outproxy/outconfig` for configuration handling【/cache/repos/github.com/kingson4wu/fast_proxy/main/outproxy/outproxy.go#L29-L43】.

## Summary

- FastProxy offers **three deployment models** (Embedded, Sidecar, Gateway) using the identical core engine in [`common/server/server.go`](https://github.com/kingson4wu/fast_proxy/blob/main/common/server/server.go).
- **Five binaries** (`center`, `server`, `in-proxy`, `out-proxy`, `client`) are available via the `Makefile` for standalone operation.
- **Configuration flexibility** supports both static YAML files and dynamic Apollo configuration without code changes.
- **Production readiness** includes graceful shutdown via signal handlers, FastHTTP for high throughput, and optional service discovery integration.
- **Security** is handled through the `common/encrypt` package, with transparent encryption in the proxy pipelines.

## Frequently Asked Questions

### How do I enable high-performance mode in FastProxy?

Set `FastHttpEnable: true` in your configuration struct before calling `outconfig.Read()`. This switches the server from standard `net/http` to `fasthttp.ListenAndServe`, significantly increasing throughput for gateway deployments. The mode also automatically exposes pprof endpoints for performance analysis【/cache/repos/github.com/kingson4wu/fast_proxy/main/common/server/server.go#L92-L104】.

### Can FastProxy handle configuration updates without restarting?

Yes. When using the Apollo configuration backend via `LoadApolloConfig` in [`common/config/apollo_config.go`](https://github.com/kingson4wu/fast_proxy/blob/main/common/config/apollo_config.go), FastProxy watches for namespace changes and updates runtime behavior dynamically. For YAML-based deployments, you must restart the process to reload configuration files【/cache/repos/github.com/kingson4wu/fast_proxy/main/common/config/apollo_config.go#L13-L41】.

### What is the recommended way to deploy FastProxy in a service mesh?

Use the **Sidecar** pattern. Build a container image using the provided Dockerfile template, then deploy it alongside your application container in the same Kubernetes pod. Mount configuration via ConfigMap and use the `outproxy` or `inproxy` binary with the `-c` flag pointing to the mounted config path. This provides process isolation while maintaining low latency.

### How does FastProxy manage graceful shutdown?

The `common/server` package registers OS signal handlers that trigger `http.Server.Shutdown` with a configurable timeout. During shutdown, the server waits for active connections to drain using a `sync.WaitGroup`, then deregisters the instance from the configured `ServiceCenter` to prevent new traffic from routing to the terminating pod【/cache/repos/github.com/kingson4wu/fast_proxy/main/common/server/server.go#L1-L84】.