HYPERFLEET-439 - feat: add external API access documentation and example

README.md

@@ -88,6 +88,46 @@ helm install hyperfleet charts/hyperfleet-gcp -f my-values.yaml \
 
 ## Configuration
 
+### External API Access
+
+By default, the HyperFleet API is only accessible within the cluster (ClusterIP). For dev environments where external access is needed:
+
+**1. Enable firewall rules in terraform:**
+
+```bash
+cd hyperfleet-infra/terraform
+terraform apply -var="enable_external_api=true"
+```
+
+**2. Deploy with LoadBalancer service type:**
+
+```bash
+helm install hyperfleet charts/hyperfleet-gcp \
+  -f examples/gcp-pubsub-external/values.yaml \
+  -n hyperfleet-system --create-namespace
+```
+
+Or add to your values file:
+
+```yaml
+base:
+  hyperfleet-api:
+    service:
+      type: LoadBalancer
+      # Optional: Restrict to specific IPs
+      # loadBalancerSourceRanges:
+      #   - "YOUR_IP/32"
+```
+
+**3. Get the external IP:**
+
+```bash
+kubectl get svc -n hyperfleet-system hyperfleet-hyperfleet-api \
+  -o jsonpath='{.status.loadBalancer.ingress[0].ip}'
+```
+
+**Security Note:** External access is HTTP-only (no TLS). For production, consider using an Ingress controller with TLS termination. Use `loadBalancerSourceRanges` to restrict access to known IPs.
+
 ### Broker Options
 
 The broker is independent of cloud provider:
@@ -165,6 +205,7 @@ See [examples/](examples/) for ready-to-use values files:
 
 - [examples/gcp-rabbitmq/values.yaml](examples/gcp-rabbitmq/values.yaml) - GCP with RabbitMQ (development)
 - [examples/gcp-pubsub/values.yaml](examples/gcp-pubsub/values.yaml) - GCP with Pub/Sub (production)
+- [examples/gcp-pubsub-external/values.yaml](examples/gcp-pubsub-external/values.yaml) - GCP with Pub/Sub + external API access
 
 ## Troubleshooting
 

charts/hyperfleet-gcp/values.yaml

@@ -40,6 +40,14 @@ base:
   # API configuration
   hyperfleet-api:
     enabled: true
+    # Service type: ClusterIP (internal) or LoadBalancer (external)
+    # For external access, set type: LoadBalancer and ensure terraform
+    # was applied with enable_external_api=true for firewall rules
+    service:
+      type: ClusterIP
+      # Optionally restrict LoadBalancer access to specific IPs:
+      # loadBalancerSourceRanges:
+      #   - "YOUR_IP/32"
 
   # Sentinel configuration with GCP defaults
   sentinel:

examples/gcp-pubsub-external/values.yaml

@@ -0,0 +1,128 @@
+# HyperFleet GCP + Pub/Sub with External API Access
+#
+# This example extends gcp-pubsub with external API access via LoadBalancer.
+#
+# Prerequisites:
+# 1. GKE cluster with Workload Identity enabled
+# 2. Pub/Sub topics and subscriptions created (use hyperfleet-infra terraform)
+# 3. Terraform applied with enable_external_api=true for firewall rules
+#
+# Usage:
+#   cd charts/hyperfleet-gcp
+#   helm dependency update
+#   helm install hyperfleet . -f ../../examples/gcp-pubsub-external/values.yaml \
+#     -n hyperfleet-system --create-namespace
+#
+# Get external IP after deployment:
+#   kubectl get svc -n hyperfleet-system hyperfleet-hyperfleet-api \
+#     -o jsonpath='{.status.loadBalancer.ingress[0].ip}'
+#
+# Replace all <PLACEHOLDER> values with your actual configuration.
+
+base:
+  global:
+    image:
+      registry: "<YOUR_REGISTRY>"  # e.g., "quay.io/your-org"
+
+    hyperfleetApi:
+      baseUrl: "http://hyperfleet-hyperfleet-api:8000"
+      version: "v1"
+
+    broker:
+      type: googlepubsub
+      googlepubsub:
+        enabled: true
+        projectId: "<GCP_PROJECT_ID>"
+      rabbitmq:
+        enabled: false
+
+  hyperfleet-api:
+    enabled: true
+    image:
+      registry: "<YOUR_REGISTRY>"
+      repository: hyperfleet-api
+      tag: "<API_IMAGE_TAG>"
+    # External access via LoadBalancer
+    service:
+      type: LoadBalancer
+      # Optional: Restrict access to specific IPs for security
+      # loadBalancerSourceRanges:
+      #   - "<YOUR_IP>/32"
+      #   - "<OFFICE_IP_RANGE>/24"
+    database:
+      postgresql:
+        enabled: true
+        password: "<DB_PASSWORD>"
+
+  sentinel:
+    enabled: true
+    image:
+      registry: "<YOUR_REGISTRY>"
+      repository: sentinel
+      tag: "<SENTINEL_IMAGE_TAG>"
+    serviceAccount:
+      create: true
+      name: sentinel
+      annotations:
+        iam.gke.io/gcp-service-account: "<SENTINEL_GCP_SA>"
+    config:
+      resourceType: clusters
+      pollInterval: 5s
+    broker:
+      type: googlepubsub
+      topic: "<CLUSTERS_TOPIC>"
+      googlepubsub:
+        projectId: "<GCP_PROJECT_ID>"
+
+  adapter-landing-zone:
+    enabled: true
+    image:
+      registry: "<YOUR_REGISTRY>"
+      repository: hyperfleet-adapter
+      tag: "<ADAPTER_IMAGE_TAG>"
+    serviceAccount:
+      create: true
+      name: landing-zone-adapter
+      annotations:
+        iam.gke.io/gcp-service-account: "<LANDING_ZONE_GCP_SA>"
+    hyperfleetApi:
+      baseUrl: "http://hyperfleet-hyperfleet-api:8000"
+      version: "v1"
+    broker:
+      type: googlepubsub
+      googlepubsub:
+        projectId: "<GCP_PROJECT_ID>"
+        topic: "<CLUSTERS_TOPIC>"
+        subscription: "<LANDING_ZONE_SUBSCRIPTION>"
+        deadLetterTopic: "<CLUSTERS_DLQ_TOPIC>"
+      subscriber:
+        parallelism: 1
+
+  rabbitmq:
+    enabled: false
+
+validation-gcp:
+  enabled: true
+  replicaCount: 1
+  deploymentMode: "dummy"
+  image:
+    registry: "<YOUR_REGISTRY>"
+    repository: hyperfleet-adapter
+    tag: "<ADAPTER_IMAGE_TAG>"
+  serviceAccount:
+    create: true
+    name: validation-gcp-adapter
+    annotations:
+      iam.gke.io/gcp-service-account: "<VALIDATION_GCP_SA>"
+  hyperfleetApi:
+    baseUrl: "http://hyperfleet-hyperfleet-api:8000"
+    version: "v1"
+  broker:
+    type: googlepubsub
+    googlepubsub:
+      projectId: "<GCP_PROJECT_ID>"
+      topic: "<CLUSTERS_TOPIC>"
+      subscription: "<VALIDATION_GCP_SUBSCRIPTION>"
+      deadLetterTopic: "<CLUSTERS_DLQ_TOPIC>"
+    subscriber:
+      parallelism: 1