Skip to content

Migration Guide: Port Separation for HTTP and gRPC Services

Overview

Starting with version X.X.X, the WebSocket Manager now runs HTTP/REST APIs and gRPC services on separate ports. This is a breaking change from the previous single-port architecture.

What Changed

  • Before: Single --port argument for both HTTP and gRPC traffic
  • After: Separate --http-port and --grpc-port arguments
  • Default ports changed: HTTP default is 5001, gRPC default is 5002 (gRPC previously used the same port as HTTP)

Migration Steps

1. Command-Line Arguments

Before: 

dotnet run -- --port 5001

After: 

# Option A: Use default gRPC port (5002)
dotnet run -- --http-port 5001

# Option B: Specify both ports (recommended for clarity)
dotnet run -- --http-port 5001 --grpc-port 5002

# Option C: Use custom ports
dotnet run -- --http-port 8080 --grpc-port 8081

2. Environment Variables

Before: 

export PORT=5001
dotnet run

After: 

export HTTP_PORT=5001
export GRPC_PORT=5002
dotnet run

3. Docker Configuration

Before: 

EXPOSE 5001

# docker-compose.yml
ports:
  - "5001:5001"

After: 

EXPOSE 5001 5002

# docker-compose.yml
ports:
  - "5001:5001"  # HTTP port
  - "5002:5002"  # gRPC port

4. Kubernetes Configuration

Before: 

# service.yaml
ports:
  - name: http
    port: 5001
    targetPort: 5001

# deployment.yaml
ports:
  - containerPort: 5001
env:
  - name: PORT
    value: "5001"
args:
  - "--port"
  - "$(PORT)"

After: 

# service.yaml
ports:
  - name: http
    port: 5001
    targetPort: 5001
  - name: grpc
    port: 5002
    targetPort: 5002

# deployment.yaml
ports:
  - containerPort: 5001
    name: http
  - containerPort: 5002
    name: grpc
env:
  - name: HTTP_PORT
    value: "5001"
  - name: GRPC_PORT
    value: "5002"
args:
  - "--http-port"
  - "$(HTTP_PORT)"
  - "--grpc-port"
  - "$(GRPC_PORT)"

5. Client Applications

gRPC Clients

Before: 

var channel = GrpcChannel.ForAddress("http://localhost:5001");

After: 

// Connect to gRPC port (default: 5002)
var channel = GrpcChannel.ForAddress("http://localhost:5002");

Note: The gRPC port now supports plaintext HTTP/2, so TLS is not required.

REST API Clients

Before: 

curl http://localhost:5001/health

After: 

# Connect to HTTP port (default: 5001)
curl http://localhost:5001/health

6. Dapr Configuration

If using Dapr sidecar integration:

Before: 

annotations:
  dapr.io/app-port: "5001"

After: 

annotations:
  dapr.io/app-port: "5001"  # Dapr connects to HTTP port for REST APIs

Dapr continues to communicate with the HTTP port for REST APIs.

New Features

Plaintext HTTP/2 for gRPC

  • No TLS certificate required for gRPC connections
  • Simplifies development and testing
  • Works in both Development and Production environments

Protocol-Specific Configuration

  • HTTP Port: Supports HTTP/1.1 and HTTP/2
  • gRPC Port: Supports HTTP/2 only with plaintext

Enhanced Validation

  • Validates that HTTP and gRPC ports are different
  • Validates port ranges (1-65535)
  • Clear error messages for configuration issues

Troubleshooting

Port Conflicts

Error: Error: HTTP port and gRPC port must be different, got 5001 for both

Solution: Use different ports for HTTP and gRPC services.

Connection Issues

Issue: gRPC client cannot connect

Check: 1. Verify you're connecting to the gRPC port (default: 5002) 2. Ensure client is configured for HTTP/2 plaintext 3. Check firewall/network rules for both ports

Issue: REST API client cannot connect

Check: 1. Verify you're connecting to the HTTP port (default: 5001) 2. Check if the application is running with correct port configuration

Environment Variable Conflicts

If you have both old and new environment variables:

# Clear old environment variable
unset PORT

# Set new environment variables
export HTTP_PORT=5001
export GRPC_PORT=5002

Rollback Procedure

If you need to revert to the old single-port configuration:

  1. Check out the previous version of the code
  2. Use the --port argument instead of --http-port/--grpc-port
  3. Update deployment configurations accordingly

Additional Resources

  • README - Updated with new port configuration options
  • Getting Started Guide - Basic setup instructions
  • API Documentation - Updated endpoint URLs

Support

For assistance with migration: 1. Check the troubleshooting section above 2. Review the updated documentation 3. Contact the development team for specific issues