Port Assignments

This section documents every port assignment in the MATIH Enterprise Platform. The canonical source of truth for port assignments is scripts/config/components.yaml in the platform repository. If any discrepancy exists between this documentation and that file, the YAML file takes precedence.

To validate that deployed services match the defined port assignments, run:

./scripts/tools/validate-ports.sh

To programmatically access a service port in shell scripts, source the port library:

source scripts/lib/core/ports.sh
PORT=$(port_get_service_port "ai-service")

Port Allocation Strategy

Ports are allocated by category to prevent conflicts and make the system predictable:

Control Plane Services

All Control Plane services are Java Spring Boot 3.2 applications deployed in the matih-control-plane Kubernetes namespace.

Resource Allocations (Control Plane)

All Control Plane services share the same base resource profile:

Replica Counts (Control Plane)

Data Plane Services

Data Plane services use a mix of Java Spring Boot, Python FastAPI, and Node.js. They are deployed in the matih-data-plane Kubernetes namespace.

Resource Allocations (Data Plane)

Replica Counts (Data Plane)

Frontend Workbenches

All frontend workbenches are React/Next.js applications deployed in the matih-system Kubernetes namespace. In development, they serve on their assigned ports via Next.js dev server. In production, they run behind NGINX with the API Gateway handling API proxying.

Resource Allocations (Frontend)

All frontend workbenches share the same resource profile:

Internal Service Ports

These ports are used by supporting infrastructure and proxy services.

Platform Infrastructure Ports

These ports are used by platform infrastructure components. They are not exposed externally and are only accessible within the Kubernetes cluster.

Observability Stack Ports

Port Conflict Notes

The following ports are shared across services that run in different namespaces and never conflict at the network level:

When accessing services from within the cluster, always use the fully qualified domain name (FQDN) to avoid ambiguity:

http://{service-name}.{namespace}.svc.cluster.local:{port}

For example:

http://ai-service.matih-data-plane.svc.cluster.local:8000
http://iam-service.matih-control-plane.svc.cluster.local:8081
http://prometheus.matih-monitoring.svc.cluster.local:9090

Deployment Phase Order

Services are deployed in a strict dependency order across 14 phases. Each phase must complete before the next begins. This order is defined in scripts/config/components.yaml under deployment_phases.

Namespace Summary

Port Validation

To detect port drift between this documentation, the components.yaml configuration file, and actual running services, use the validation script:

./scripts/tools/validate-ports.sh

This script performs the following checks:

Programmatic Port Access

For shell scripts that need to reference service ports, use the port library:

source scripts/lib/core/ports.sh
 
# Get a service port by name
AI_PORT=$(port_get_service_port "ai-service")
echo "AI Service port: ${AI_PORT}"  # Output: 8000
 
# Get health endpoint for a service
HEALTH_PATH=$(port_get_health_path "ai-service")
echo "Health path: ${HEALTH_PATH}"  # Output: /health
 
# Construct full health URL
HEALTH_URL="http://ai-service.matih-data-plane.svc.cluster.local:${AI_PORT}${HEALTH_PATH}"

This approach ensures that port numbers are never hardcoded in scripts and always reference the single source of truth.