> ## Documentation Index
> Fetch the complete documentation index at: https://docs.golf.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Deploy in Distributed Mode

> Use local server definitions with centralized policy management from Control Plane.

Deploy in Distributed mode to maintain local control over MCP server definitions while receiving security policies and organization settings from the Control Plane.

## Prerequisites

* Golf Gateway account with gateway created
* Docker or Kubernetes environment (with Redis available)
* Local YAML configuration file

<Note>
  Golf Gateway **requires Redis** for session management, rate limiting, replay protection, and authentication caching. Ensure Redis is available before deploying.
</Note>

## When to use Distributed Mode

Distributed mode is ideal when you need:

* Local control over MCP server definitions
* Central management of security policies
* Gradual migration to full Centralized mode management

## Create the configuration file

Create `golf-gateway.yaml`. The `control_plane` section activates Distributed mode — the gateway reads servers from this YAML file while fetching organization policies from the Control Plane.

```yaml theme={null}
version: "1.0"

# Control Plane connection (activates distributed mode)
control_plane:
  api_key: ${GOLF_GATEWAY_API_KEY}
  gateway_id: ${GOLF_GATEWAY_ID}

servers:
  - name: github-mcp
    url: http://localhost:3001
    description: "GitHub MCP Server"
    server_type: third_party
    rbac_enabled: true
    allowed_groups:
      - developers
      - devops

  - name: slack-mcp
    url: http://localhost:3002
    description: "Slack MCP Server"
    server_type: inhouse
    allowed_groups:
      - all-users
```

<Warning>
  **Treat your configuration file as a secret.** The YAML file may contain sensitive information such as server URLs, group names, and policy configurations. Never commit it to version control unencrypted.

  For production deployments, store your configuration in:

  * **AWS Secrets Manager** with External Secrets Operator
  * **HashiCorp Vault** with External Secrets Operator
  * **Kubernetes Secrets** (not ConfigMaps)
</Warning>

## Deploy with YAML config

<Tabs>
  <Tab title="Docker Compose">
    ```yaml theme={null}
    version: "3.8"
    services:
      redis:
        image: redis:7-alpine
        ports:
          - "6379:6379"
        healthcheck:
          test: ["CMD", "redis-cli", "ping"]
          interval: 10s
          timeout: 5s
          retries: 3

      golf-gateway:
        image: ghcr.io/golf-mcp/golf-gateway-backend:latest
        ports:
          - "8080:8080"
        volumes:
          - ./golf-gateway.yaml:/app/golf-gateway.yaml:ro
        environment:
          # These env vars are referenced by ${} in the YAML file
          GOLF_GATEWAY_API_KEY: <your-api-key>
          GOLF_GATEWAY_ID: <your-gateway-id>
          GOLF_GATEWAY_EXTERNAL_URL: https://gateway.example.com
          GOLF_CACHE_REDIS_URL: redis://redis:6379/0
        depends_on:
          redis:
            condition: service_healthy
    ```
  </Tab>

  <Tab title="Kubernetes Secret">
    ```yaml theme={null}
    apiVersion: v1
    kind: Secret
    metadata:
      name: golf-gateway-config
    type: Opaque
    stringData:
      golf-gateway.yaml: |
        version: "1.0"
        control_plane:
          api_key: ${GOLF_GATEWAY_API_KEY}
          gateway_id: ${GOLF_GATEWAY_ID}
        servers:
          - name: github-mcp
            url: http://github-mcp-service:3001
            rbac_enabled: true
            allowed_groups:
              - developers
    ---
    apiVersion: apps/v1
    kind: Deployment
    metadata:
      name: golf-gateway
    spec:
      template:
        spec:
          containers:
          - name: golf-gateway
            env:
            - name: GOLF_GATEWAY_EXTERNAL_URL
              value: "https://gateway.example.com"
            - name: GOLF_CACHE_REDIS_URL
              value: "redis://redis:6379/0"
            volumeMounts:
            - name: config
              mountPath: /app/golf-gateway.yaml
              subPath: golf-gateway.yaml
              readOnly: true
          volumes:
          - name: config
            secret:
              secretName: golf-gateway-config
    ```

    <Tip>
      For production, use External Secrets Operator to sync from AWS Secrets Manager or HashiCorp Vault.
    </Tip>
  </Tab>
</Tabs>

<Info>
  Golf Gateway offers additional Helm charts for different deployment scenarios. Contact the Golf team for more details on available charts and enterprise deployment options.
</Info>

## What comes from where

| Configuration            | Centralized   | Distributed   |
| ------------------------ | ------------- | ------------- |
| MCP server definitions   | Control Plane | YAML file     |
| Server-level RBAC        | Control Plane | YAML file     |
| Gateway-level policy     | Control Plane | YAML file     |
| Security engine settings | Control Plane | YAML file     |
| Exporters                | Control Plane | YAML file     |
| Org-wide policies        | Control Plane | Control Plane |

## Verify Distributed mode

1. Check health endpoint:
   ```bash theme={null}
   curl http://localhost:8080/health
   ```

2. Verify servers synced to Control Plane:
   * In Admin Portal, go to **MCP Servers**
   * Your YAML-defined servers appear with a **YAML** badge

<Tip>
  Changes to the YAML file are detected automatically. The gateway reloads configuration without restart.
</Tip>

## Related guides

* [Deploy in Centralized Mode](/gateway/guides/getting-started/deploy-control-plane) - Full Centralized mode management
* [YAML Configuration Schema](/gateway/reference/yaml-schema) - Complete YAML reference