@spine-event-engine/deployment-gce 2.0.0-snapshot.2

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@spine-event-engine/deployment-gce",
+  "version": "2.0.0-snapshot.2",
+  "license": "Apache-2.0",
+  "type": "module",
+  "description": "Google Compute Engine deployment adapter for Spine TS application nodes.",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/SpineEventEngine/spine-ts",
+    "directory": "packages/deployment-gce"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public",
+    "tag": "snapshot"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "REFERENCE.md",
+    "examples",
+    "terraform"
+  ],
+  "dependencies": {
+    "loglayer": "9.4.0",
+    "@spine-event-engine/deployment": "2.0.0-snapshot.2"
+  },
+  "devDependencies": {
+    "@bufbuild/protobuf": "2.12.1",
+    "@spine-event-engine/auth": "2.0.0-snapshot.2",
+    "@spine-event-engine/server": "2.0.0-snapshot.2",
+    "@spine-event-engine/proto": "2.0.0-snapshot.2",
+    "@spine-event-engine/storage": "2.0.0-snapshot.2"
+  }
+}

package/terraform/.terraform.lock.hcl

@@ -0,0 +1,22 @@
+# This file is maintained automatically by "terraform init".
+# Manual edits may be lost in future updates.
+
+provider "registry.terraform.io/hashicorp/google" {
+  version     = "6.50.0"
+  constraints = "~> 6.0"
+  hashes = [
+    "h1:79CwMTsp3Ud1nOl5hFS5mxQHyT0fGVye7pqpU0PPlHI=",
+    "zh:1f3513fcfcbf7ca53d667a168c5067a4dd91a4d4cccd19743e248ff31065503c",
+    "zh:3da7db8fc2c51a77dd958ea8baaa05c29cd7f829bd8941c26e2ea9cb3aadc1e5",
+    "zh:3e09ac3f6ca8111cbb659d38c251771829f4347ab159a12db195e211c76068bb",
+    "zh:7bb9e41c568df15ccf1a8946037355eefb4dfb4e35e3b190808bb7c4abae547d",
+    "zh:81e5d78bdec7778e6d67b5c3544777505db40a826b6eb5abe9b86d4ba396866b",
+    "zh:8d309d020fb321525883f5c4ea864df3d5942b6087f6656d6d8b3a1377f340fc",
+    "zh:93e112559655ab95a523193158f4a4ac0f2bfed7eeaa712010b85ebb551d5071",
+    "zh:d3efe589ffd625b300cef5917c4629513f77e3a7b111c9df65075f76a46a63c7",
+    "zh:d4a4d672bbef756a870d8f32b35925f8ce2ef4f6bbd5b71a3cb764f1b6c85421",
+    "zh:e13a86bca299ba8a118e80d5f84fbdd708fe600ecdceea1a13d4919c068379fe",
+    "zh:f569b65999264a9416862bca5cd2a6177d94ccb0424f3a4ef424428912b9cb3c",
+    "zh:fec30c095647b583a246c39d557704947195a1b7d41f81e369ba377d997faef6",
+  ]
+}

package/terraform/main.tf

@@ -0,0 +1,402 @@
+locals {
+  application_image_host = split("/", var.application_image)[0]
+  delivery_image_host    = split("/", var.delivery_image)[0]
+  gateway_image_host     = split("/", var.gateway_image)[0]
+  runtime_ports          = [var.application_port, var.gateway_port, var.delivery_port]
+  runtime_tags           = ["spine-runtime"]
+}
+
+resource "google_compute_health_check" "application" {
+  name                = "spine-application"
+  check_interval_sec  = 10
+  timeout_sec         = 5
+  healthy_threshold   = 2
+  unhealthy_threshold = 3
+
+  tcp_health_check {
+    port = var.application_port
+  }
+}
+
+resource "google_compute_health_check" "gateway" {
+  name                = "spine-gateway"
+  check_interval_sec  = 10
+  timeout_sec         = 5
+  healthy_threshold   = 2
+  unhealthy_threshold = 3
+
+  tcp_health_check {
+    port = var.gateway_port
+  }
+}
+
+resource "google_compute_health_check" "delivery" {
+  name                = "spine-delivery"
+  check_interval_sec  = 10
+  timeout_sec         = 5
+  healthy_threshold   = 2
+  unhealthy_threshold = 3
+
+  tcp_health_check {
+    port = var.delivery_port
+  }
+}
+
+resource "google_compute_firewall" "private_runtime" {
+  name          = "spine-private-runtime"
+  network       = var.network
+  direction     = "INGRESS"
+  source_ranges = distinct(concat(var.private_source_ranges, var.health_check_source_ranges))
+  target_tags   = local.runtime_tags
+
+  allow {
+    protocol = "tcp"
+    ports    = [for port in local.runtime_ports : tostring(port)]
+  }
+}
+
+resource "google_compute_address" "gateway" {
+  name         = "spine-gateway"
+  region       = var.region
+  address_type = "INTERNAL"
+  purpose      = "GCE_ENDPOINT"
+  subnetwork   = var.subnetwork
+}
+
+resource "google_compute_address" "delivery" {
+  name         = "spine-delivery"
+  region       = var.region
+  address_type = "INTERNAL"
+  purpose      = "GCE_ENDPOINT"
+  subnetwork   = var.subnetwork
+}
+
+resource "google_compute_instance_template" "application" {
+  name_prefix  = "spine-application-"
+  machine_type = var.machine_type
+  tags         = local.runtime_tags
+
+  disk {
+    source_image = "projects/cos-cloud/global/images/family/cos-stable"
+    auto_delete  = true
+    boot         = true
+  }
+
+  network_interface {
+    network    = var.network
+    subnetwork = var.subnetwork
+  }
+
+  service_account {
+    email  = var.service_account_email
+    scopes = ["cloud-platform"]
+  }
+
+  metadata_startup_script = <<-EOT
+    #!/usr/bin/env bash
+    set -eu
+    export HOME=/var/lib/spine-docker
+    export DOCKER_CONFIG="$HOME/.docker"
+    mkdir -p "$DOCKER_CONFIG"
+    docker-credential-gcr configure-docker --registries=${local.application_image_host}
+    docker --config "$DOCKER_CONFIG" run --rm --network host \
+      -e HOST=0.0.0.0 \
+      -e PORT=${var.application_port} \
+      -e APPLICATION_PROCESS_COUNT=${var.application_process_count} \
+      -e DELIVERY_SERVER_URL=http://${google_compute_forwarding_rule.delivery.ip_address}:${var.delivery_port} \
+      -e DELIVERY_SHARD_COUNT=${var.delivery_shard_count} \
+      -e REGISTRY_NAMESPACE=${var.registry_namespace} \
+      -e REGISTRY_STORAGE_REFERENCE=${var.registry_storage_reference} \
+      -e APPLICATION_SECRET_REFERENCE=${var.application_secret_reference} \
+      ${var.application_image}
+  EOT
+
+  lifecycle {
+    create_before_destroy = true
+  }
+}
+
+resource "google_compute_instance_template" "gateway" {
+  name_prefix  = "spine-gateway-"
+  machine_type = var.machine_type
+  tags         = local.runtime_tags
+
+  disk {
+    source_image = "projects/cos-cloud/global/images/family/cos-stable"
+    auto_delete  = true
+    boot         = true
+  }
+
+  network_interface {
+    network    = var.network
+    subnetwork = var.subnetwork
+  }
+
+  service_account {
+    email  = var.service_account_email
+    scopes = ["cloud-platform"]
+  }
+
+  metadata_startup_script = <<-EOT
+    #!/usr/bin/env bash
+    set -eu
+    export HOME=/var/lib/spine-docker
+    export DOCKER_CONFIG="$HOME/.docker"
+    mkdir -p "$DOCKER_CONFIG"
+    docker-credential-gcr configure-docker --registries=${local.gateway_image_host}
+    docker --config "$DOCKER_CONFIG" run --rm --network host \
+      -e HOST=0.0.0.0 \
+      -e PORT=${var.gateway_port} \
+      -e REGISTRY_NAMESPACE=${var.registry_namespace} \
+      -e REGISTRY_STORAGE_REFERENCE=${var.registry_storage_reference} \
+      -e GATEWAY_SECRET_REFERENCE=${var.gateway_secret_reference} \
+      ${var.gateway_image}
+  EOT
+
+  lifecycle {
+    create_before_destroy = true
+  }
+}
+
+resource "google_compute_instance_template" "delivery" {
+  name_prefix  = "spine-delivery-"
+  machine_type = var.machine_type
+  tags         = local.runtime_tags
+
+  disk {
+    source_image = "projects/cos-cloud/global/images/family/cos-stable"
+    auto_delete  = true
+    boot         = true
+  }
+
+  network_interface {
+    network    = var.network
+    subnetwork = var.subnetwork
+  }
+
+  service_account {
+    email  = var.service_account_email
+    scopes = ["cloud-platform"]
+  }
+
+  metadata_startup_script = <<-EOT
+    #!/usr/bin/env bash
+    set -eu
+    export HOME=/var/lib/spine-docker
+    export DOCKER_CONFIG="$HOME/.docker"
+    mkdir -p "$DOCKER_CONFIG"
+    docker-credential-gcr configure-docker --registries=${local.delivery_image_host}
+    docker --config "$DOCKER_CONFIG" run --rm --network host \
+      -e HOST=0.0.0.0 \
+      -e PORT=${var.delivery_port} \
+      ${var.delivery_image}
+  EOT
+
+  lifecycle {
+    create_before_destroy = true
+  }
+}
+
+resource "google_compute_region_instance_group_manager" "application" {
+  name                      = "spine-application"
+  region                    = var.region
+  base_instance_name        = "spine-application"
+  distribution_policy_zones = var.application_zones
+  target_size               = var.autoscaling_enabled ? null : var.application_replicas
+
+  version {
+    instance_template = google_compute_instance_template.application.self_link_unique
+  }
+
+  named_port {
+    name = "grpc"
+    port = var.application_port
+  }
+
+  auto_healing_policies {
+    health_check      = google_compute_health_check.application.self_link
+    initial_delay_sec = var.application_startup_delay_sec
+  }
+
+  update_policy {
+    type                  = "PROACTIVE"
+    minimal_action        = "REPLACE"
+    replacement_method    = "SUBSTITUTE"
+    max_surge_fixed       = length(var.application_zones)
+    max_unavailable_fixed = 0
+  }
+
+  lifecycle {
+    precondition {
+      condition     = var.autoscaling_min_replicas <= var.autoscaling_max_replicas
+      error_message = "Autoscaling minimum replicas must not exceed the maximum."
+    }
+
+    precondition {
+      condition     = !var.autoscaling_enabled || var.autoscaling_signal == "cpu" || trimspace(var.autoscaling_metric) != ""
+      error_message = "Monitoring autoscaling requires a metric name."
+    }
+
+    precondition {
+      condition     = !var.autoscaling_enabled || var.autoscaling_signal != "monitoring" || var.autoscaling_min_replicas >= 1 || var.autoscaling_metric_scope == "whole_group"
+      error_message = "Monitoring minimum replicas of zero requires a whole_group Monitoring metric."
+    }
+
+    precondition {
+      condition     = !var.autoscaling_enabled || var.autoscaling_signal != "cpu" || var.autoscaling_min_replicas >= 1
+      error_message = "CPU autoscaling requires at least one application node."
+    }
+
+    precondition {
+      condition = !var.autoscaling_enabled || var.autoscaling_signal != "monitoring" || (
+        var.autoscaling_metric_scope == "per_instance" &&
+        can(regex("resource\\.type\\s*=\\s*\"gce_instance\"", var.autoscaling_metric_filter))
+        ) || (
+        var.autoscaling_metric_scope == "whole_group" &&
+        can(regex("resource\\.type\\s*=", var.autoscaling_metric_filter)) &&
+        !can(regex("resource\\.type\\s*=\\s*\"gce_instance\"", var.autoscaling_metric_filter))
+      )
+      error_message = "per_instance Monitoring metrics require resource.type = \"gce_instance\"; whole_group metrics require a resource.type other than \"gce_instance\"."
+    }
+  }
+}
+
+resource "google_compute_region_autoscaler" "application" {
+  count  = var.autoscaling_enabled ? 1 : 0
+  name   = "spine-application"
+  region = var.region
+  target = google_compute_region_instance_group_manager.application.id
+
+  autoscaling_policy {
+    min_replicas = var.autoscaling_min_replicas
+    max_replicas = var.autoscaling_max_replicas
+
+    dynamic "cpu_utilization" {
+      for_each = var.autoscaling_signal == "cpu" ? [true] : []
+      content {
+        target = var.autoscaling_target
+      }
+    }
+
+    dynamic "metric" {
+      for_each = var.autoscaling_signal == "cpu" ? [] : [true]
+      content {
+        name   = var.autoscaling_metric
+        filter = var.autoscaling_metric_filter
+        type   = var.autoscaling_metric_target_type
+        target = var.autoscaling_target
+      }
+    }
+  }
+}
+
+resource "google_compute_region_instance_group_manager" "gateway" {
+  name                      = "spine-gateway"
+  region                    = var.region
+  base_instance_name        = "spine-gateway"
+  distribution_policy_zones = [var.singleton_zone]
+  target_size               = 1
+
+  version {
+    instance_template = google_compute_instance_template.gateway.self_link_unique
+  }
+
+  named_port {
+    name = "gateway"
+    port = var.gateway_port
+  }
+
+  auto_healing_policies {
+    health_check      = google_compute_health_check.gateway.self_link
+    initial_delay_sec = var.application_startup_delay_sec
+  }
+
+  update_policy {
+    type                  = "PROACTIVE"
+    minimal_action        = "REPLACE"
+    replacement_method    = "SUBSTITUTE"
+    max_surge_fixed       = 0
+    max_unavailable_fixed = 1
+  }
+}
+
+resource "google_compute_region_instance_group_manager" "delivery" {
+  name                      = "spine-delivery"
+  region                    = var.region
+  base_instance_name        = "spine-delivery"
+  distribution_policy_zones = [var.singleton_zone]
+  target_size               = 1
+
+  version {
+    instance_template = google_compute_instance_template.delivery.self_link_unique
+  }
+
+  named_port {
+    name = "grpc"
+    port = var.delivery_port
+  }
+
+  auto_healing_policies {
+    health_check      = google_compute_health_check.delivery.self_link
+    initial_delay_sec = var.application_startup_delay_sec
+  }
+
+  update_policy {
+    type                  = "PROACTIVE"
+    minimal_action        = "REPLACE"
+    replacement_method    = "SUBSTITUTE"
+    max_surge_fixed       = 0
+    max_unavailable_fixed = 1
+  }
+}
+
+resource "google_compute_region_backend_service" "gateway" {
+  name                  = "spine-gateway"
+  region                = var.region
+  protocol              = "TCP"
+  load_balancing_scheme = "INTERNAL"
+  health_checks         = [google_compute_health_check.gateway.id]
+
+  backend {
+    group = google_compute_region_instance_group_manager.gateway.instance_group
+  }
+}
+
+resource "google_compute_region_backend_service" "delivery" {
+  name                  = "spine-delivery"
+  region                = var.region
+  protocol              = "TCP"
+  load_balancing_scheme = "INTERNAL"
+  health_checks         = [google_compute_health_check.delivery.id]
+
+  backend {
+    group = google_compute_region_instance_group_manager.delivery.instance_group
+  }
+}
+
+resource "google_compute_forwarding_rule" "gateway" {
+  name                  = "spine-gateway"
+  region                = var.region
+  load_balancing_scheme = "INTERNAL"
+  backend_service       = google_compute_region_backend_service.gateway.id
+  network               = var.network
+  subnetwork            = var.subnetwork
+  ip_address            = google_compute_address.gateway.id
+  ports                 = [tostring(var.gateway_port)]
+}
+
+resource "google_compute_forwarding_rule" "delivery" {
+  name                  = "spine-delivery"
+  region                = var.region
+  load_balancing_scheme = "INTERNAL"
+  backend_service       = google_compute_region_backend_service.delivery.id
+  network               = var.network
+  subnetwork            = var.subnetwork
+  ip_address            = google_compute_address.delivery.id
+  ports                 = [tostring(var.delivery_port)]
+}
+
+output "gateway_private_address" {
+  description = "Stable private address for an operator-managed TLS and authentication edge."
+  value       = google_compute_forwarding_rule.gateway.ip_address
+}

package/terraform/terraform.tfvars.example

@@ -0,0 +1,57 @@
+# This module never creates a public TLS/authentication edge. It creates only
+# private VM listeners, so select the existing VPC and subnetwork deliberately.
+project_id        = "my-project"
+region            = "us-central1"
+application_zones = ["us-central1-a", "us-central1-b"]
+singleton_zone    = "us-central1-a"
+network           = "projects/my-project/global/networks/private"
+subnetwork        = "projects/my-project/regions/us-central1/subnetworks/apps"
+
+# Use a least-privilege account that can access only the application-owned
+# configuration and external secret references required by these images.
+service_account_email = "spine-runtime@my-project.iam.gserviceaccount.com"
+
+# Replace each placeholder with a published immutable image digest.
+application_image = "us-docker.pkg.dev/my-project/spine/application@sha256:REPLACE"
+gateway_image     = "us-docker.pkg.dev/my-project/spine/gateway@sha256:REPLACE"
+delivery_image    = "us-docker.pkg.dev/my-project/spine/simple-delivery@sha256:REPLACE"
+
+# The images interpret these references. Terraform neither reads nor stores
+# secret values and does not select an application storage engine.
+registry_namespace         = "production-application-nodes"
+registry_storage_reference = "spine-production-storage"
+application_secret_reference = "projects/my-project/secrets/application-runtime"
+gateway_secret_reference     = "projects/my-project/secrets/gateway-runtime"
+
+# Manual capacity applies while autoscaling is disabled.
+application_replicas = 2
+
+# Set both values deliberately. They are independent: one VM starts this many
+# complete application children, while the application builds its contexts with
+# this many Delivery shards.
+application_process_count = 2
+delivery_shard_count      = 2
+
+# GCE owns capacity when this is true. CPU uses a utilization target. Monitoring
+# uses a separately chosen metric name, resource/series filter, target kind,
+# and scope. Per-instance filters must use `resource.type = "gce_instance"`.
+# Whole-group filters must use another resource type, such as `global`.
+autoscaling_enabled            = false
+autoscaling_signal             = "cpu"
+autoscaling_metric_scope       = "per_instance"
+autoscaling_metric             = ""
+autoscaling_metric_filter      = "resource.type = \"gce_instance\""
+autoscaling_metric_target_type = "GAUGE"
+autoscaling_target             = 0.7
+autoscaling_min_replicas       = 1
+autoscaling_max_replicas       = 8
+
+# A whole-group Monitoring metric can wake an empty group only when it exists
+# without an application VM. Use these explicit values for that case:
+# autoscaling_signal             = "monitoring"
+# autoscaling_metric_scope       = "whole_group"
+# autoscaling_metric             = "custom.googleapis.com/spine/pending_work"
+# autoscaling_metric_filter      = "resource.type = \"global\""
+# autoscaling_metric_target_type = "GAUGE"
+# autoscaling_target             = 1
+# autoscaling_min_replicas       = 0