Deploy with Terraform

1
variable "aws_region" {
2
  description = "AWS region where the SageMaker Endpoint will be deployed."
3
  type        = string
4
  default     = "us-east-1"
5
}
6
7
variable "model_package_arn" {
8
  description = "ARN of the Deepgram Model Package from AWS Marketplace."
9
  type        = string
10
}
11
12
variable "model_name" {
13
  description = "Name for the SageMaker Model resource."
14
  type        = string
15
  default     = "deepgram-stt"
16
}
17
18
variable "endpoint_name" {
19
  description = "Name for the SageMaker Endpoint."
20
  type        = string
21
  default     = "deepgram-stt-endpoint"
22
}
23
24
variable "instance_type" {
25
  description = "SageMaker instance type for the endpoint."
26
  type        = string
27
  default     = "ml.g5.2xlarge"
28
}
29
30
variable "initial_instance_count" {
31
  description = "Number of instances to launch at endpoint creation."
32
  type        = number
33
  default     = 1
34
}
35
36
variable "variant_name" {
37
  description = "Name of the production variant."
38
  type        = string
39
  default     = "AllTraffic"
40
}
41
42
variable "deepgram_engine_env" {
43
  description = "Map of DEEPGRAM_ENGINE_* environment variables for TOML overrides."
44
  type        = map(string)
45
  default     = {}
46
}
47
48
variable "deepgram_api_env" {
49
  description = "Map of DEEPGRAM_API_* environment variables for TOML overrides."
50
  type        = map(string)
51
  default     = {}
52
}
53
54
variable "enable_autoscaling" {
55
  description = "Enable auto-scaling for the endpoint."
56
  type        = bool
57
  default     = false
58
}
59
60
variable "autoscaling_min_capacity" {
61
  description = "Minimum instance count for auto-scaling."
62
  type        = number
63
  default     = 1
64
}
65
66
variable "autoscaling_max_capacity" {
67
  description = "Maximum instance count for auto-scaling."
68
  type        = number
69
  default     = 4
70
}
71
72
variable "autoscaling_target_value" {
73
  description = "Target concurrent requests per instance for the scaling policy."
74
  type        = number
75
  default     = 5.0
76
}
77
78
variable "enable_async_inference" {
79
  description = "Deploy an asynchronous endpoint (queued, S3 in/out) instead of a real-time endpoint. Async endpoints accept only asynchronous invocations."
80
  type        = bool
81
  default     = false
82
}
83
84
variable "async_s3_output_path" {
85
  description = "S3 URI for async transcription output, e.g. s3://my-bucket/output/. Required when enable_async_inference = true."
86
  type        = string
87
  default     = ""
88
89
  validation {
90
    condition     = var.async_s3_output_path == "" || can(regex("^s3://", var.async_s3_output_path))
91
    error_message = "async_s3_output_path must be an s3:// URI."
92
  }
93
}
94
95
variable "async_s3_failure_path" {
96
  description = "Optional S3 URI for async failure output, e.g. s3://my-bucket/failures/."
97
  type        = string
98
  default     = ""
99
}

1
###############################################################################
2
# Provider
3
###############################################################################
4
5
terraform {
6
  required_version = ">= 1.5"
7
8
  required_providers {
9
    aws = {
10
      source  = "hashicorp/aws"
11
      version = ">= 5.0"
12
    }
13
  }
14
}
15
16
provider "aws" {
17
  region = var.aws_region
18
}
19
20
###############################################################################
21
# IAM Role — SageMaker Execution
22
###############################################################################
23
24
data "aws_iam_policy_document" "sagemaker_assume_role" {
25
  statement {
26
    actions = ["sts:AssumeRole"]
27
28
    principals {
29
      type        = "Service"
30
      identifiers = ["sagemaker.amazonaws.com"]
31
    }
32
  }
33
}
34
35
resource "aws_iam_role" "sagemaker_execution" {
36
  name               = "${var.model_name}-execution-role"
37
  assume_role_policy = data.aws_iam_policy_document.sagemaker_assume_role.json
38
}
39
40
resource "aws_iam_role_policy_attachment" "sagemaker_full_access" {
41
  role       = aws_iam_role.sagemaker_execution.name
42
  policy_arn = "arn:aws:iam::aws:policy/AmazonSageMakerFullAccess"
43
}
44
45
###############################################################################
46
# Async S3 access (only when enable_async_inference = true)
47
###############################################################################
48
49
locals {
50
  async_buckets = var.enable_async_inference ? toset(compact([
51
    try(split("/", replace(var.async_s3_output_path, "s3://", ""))[0], ""),
52
    try(split("/", replace(var.async_s3_failure_path, "s3://", ""))[0], ""),
53
  ])) : toset([])
54
}
55
56
resource "aws_iam_role_policy" "async_s3" {
57
  count = var.enable_async_inference ? 1 : 0
58
59
  name = "${var.model_name}-async-s3"
60
  role = aws_iam_role.sagemaker_execution.id
61
62
  policy = jsonencode({
63
    Version = "2012-10-17"
64
    Statement = [
65
      {
66
        Effect   = "Allow"
67
        Action   = ["s3:GetObject", "s3:PutObject"]
68
        Resource = [for b in local.async_buckets : "arn:aws:s3:::${b}/*"]
69
      },
70
      {
71
        Effect   = "Allow"
72
        Action   = ["s3:ListBucket"]
73
        Resource = [for b in local.async_buckets : "arn:aws:s3:::${b}"]
74
      },
75
    ]
76
  })
77
}
78
79
###############################################################################
80
# Merge Deepgram environment variables
81
###############################################################################
82
83
locals {
84
  deepgram_env = merge(
85
    { for k, v in var.deepgram_engine_env : "DEEPGRAM_ENGINE_${k}" => v },
86
    { for k, v in var.deepgram_api_env : "DEEPGRAM_API_${k}" => v },
87
  )
88
}
89
90
###############################################################################
91
# SageMaker Model — from AWS Marketplace Model Package
92
###############################################################################
93
94
resource "aws_sagemaker_model" "deepgram" {
95
  name                     = var.model_name
96
  execution_role_arn       = aws_iam_role.sagemaker_execution.arn
97
  enable_network_isolation = true
98
99
  primary_container {
100
    model_package_name = var.model_package_arn
101
    environment        = local.deepgram_env
102
  }
103
}
104
105
###############################################################################
106
# SageMaker Endpoint Configuration
107
###############################################################################
108
109
resource "aws_sagemaker_endpoint_configuration" "deepgram" {
110
  name = "${var.endpoint_name}-config"
111
112
  production_variants {
113
    variant_name           = var.variant_name
114
    model_name             = aws_sagemaker_model.deepgram.name
115
    initial_instance_count = var.initial_instance_count
116
    instance_type          = var.instance_type
117
  }
118
119
  dynamic "async_inference_config" {
120
    for_each = var.enable_async_inference ? [1] : []
121
    content {
122
      output_config {
123
        s3_output_path  = var.async_s3_output_path
124
        s3_failure_path = var.async_s3_failure_path != "" ? var.async_s3_failure_path : null
125
      }
126
    }
127
  }
128
129
  lifecycle {
130
    precondition {
131
      condition     = !var.enable_async_inference || var.async_s3_output_path != ""
132
      error_message = "async_s3_output_path is required when enable_async_inference = true."
133
    }
134
  }
135
}
136
137
###############################################################################
138
# SageMaker Endpoint
139
###############################################################################
140
141
resource "aws_sagemaker_endpoint" "deepgram" {
142
  name                 = var.endpoint_name
143
  endpoint_config_name = aws_sagemaker_endpoint_configuration.deepgram.name
144
}
145
146
###############################################################################
147
# Auto-Scaling (optional)
148
###############################################################################
149
150
resource "aws_appautoscaling_target" "sagemaker" {
151
  count = var.enable_autoscaling ? 1 : 0
152
153
  max_capacity       = var.autoscaling_max_capacity
154
  min_capacity       = var.autoscaling_min_capacity
155
  resource_id        = "endpoint/${aws_sagemaker_endpoint.deepgram.name}/variant/${var.variant_name}"
156
  scalable_dimension = "sagemaker:variant:DesiredInstanceCount"
157
  service_namespace  = "sagemaker"
158
}
159
160
resource "aws_appautoscaling_policy" "sagemaker" {
161
  count = var.enable_autoscaling ? 1 : 0
162
163
  name               = "${var.endpoint_name}-concurrency-policy"
164
  policy_type        = "TargetTrackingScaling"
165
  resource_id        = aws_appautoscaling_target.sagemaker[0].resource_id
166
  scalable_dimension = aws_appautoscaling_target.sagemaker[0].scalable_dimension
167
  service_namespace  = aws_appautoscaling_target.sagemaker[0].service_namespace
168
169
  target_tracking_scaling_policy_configuration {
170
    target_value = var.autoscaling_target_value
171
172
    # Real-time: scale on concurrent requests per model.
173
    dynamic "predefined_metric_specification" {
174
      for_each = var.enable_async_inference ? [] : [1]
175
      content {
176
        predefined_metric_type = "SageMakerVariantConcurrentRequestsPerModelHighResolution"
177
      }
178
    }
179
180
    # Async: scale on queue depth per instance.
181
    dynamic "customized_metric_specification" {
182
      for_each = var.enable_async_inference ? [1] : []
183
      content {
184
        metric_name = "ApproximateBacklogSizePerInstance"
185
        namespace   = "AWS/SageMaker"
186
        statistic   = "Average"
187
        dimensions {
188
          name  = "EndpointName"
189
          value = aws_sagemaker_endpoint.deepgram.name
190
        }
191
      }
192
    }
193
194
    scale_in_cooldown  = 300
195
    scale_out_cooldown = 60
196
  }
197
}
198
199
###############################################################################
200
# Async scale-from-zero (only when async + autoscaling are enabled)
201
###############################################################################
202
203
resource "aws_appautoscaling_policy" "async_scale_from_zero" {
204
  count = var.enable_async_inference && var.enable_autoscaling ? 1 : 0
205
206
  name               = "${var.endpoint_name}-scale-from-zero"
207
  policy_type        = "StepScaling"
208
  resource_id        = aws_appautoscaling_target.sagemaker[0].resource_id
209
  scalable_dimension = aws_appautoscaling_target.sagemaker[0].scalable_dimension
210
  service_namespace  = aws_appautoscaling_target.sagemaker[0].service_namespace
211
212
  step_scaling_policy_configuration {
213
    adjustment_type         = "ChangeInCapacity"
214
    metric_aggregation_type = "Average"
215
    cooldown                = 300
216
217
    step_adjustment {
218
      metric_interval_lower_bound = 0
219
      scaling_adjustment          = 1
220
    }
221
  }
222
}
223
224
resource "aws_cloudwatch_metric_alarm" "async_has_backlog" {
225
  count = var.enable_async_inference && var.enable_autoscaling ? 1 : 0
226
227
  alarm_name          = "${var.endpoint_name}-has-backlog-without-capacity"
228
  namespace           = "AWS/SageMaker"
229
  metric_name         = "HasBacklogWithoutCapacity"
230
  statistic           = "Average"
231
  period              = 60
232
  evaluation_periods  = 2
233
  datapoints_to_alarm = 2
234
  threshold           = 1
235
  comparison_operator = "GreaterThanOrEqualToThreshold"
236
  treat_missing_data  = "missing"
237
238
  dimensions = {
239
    EndpointName = aws_sagemaker_endpoint.deepgram.name
240
  }
241
242
  alarm_actions = [aws_appautoscaling_policy.async_scale_from_zero[0].arn]
243
}

1
output "endpoint_name" {
2
  description = "Name of the deployed SageMaker Endpoint."
3
  value       = aws_sagemaker_endpoint.deepgram.name
4
}
5
6
output "endpoint_arn" {
7
  description = "ARN of the deployed SageMaker Endpoint."
8
  value       = aws_sagemaker_endpoint.deepgram.arn
9
}
10
11
output "model_name" {
12
  description = "Name of the SageMaker Model."
13
  value       = aws_sagemaker_model.deepgram.name
14
}
15
16
output "execution_role_arn" {
17
  description = "ARN of the IAM execution role."
18
  value       = aws_iam_role.sagemaker_execution.arn
19
}
20
21
output "async_s3_output_path" {
22
  description = "S3 location where async transcription results are written (async mode only)."
23
  value       = var.enable_async_inference ? var.async_s3_output_path : null
24
}

1
aws_region        = "us-east-1"
2
model_package_arn = "arn:aws:sagemaker:us-east-1:123456789012:model-package/deepgram-stt-nova-3/1"
3
model_name        = "deepgram-streaming-stt"
4
endpoint_name     = "my-deepgram-stt"
5
instance_type     = "ml.g5.2xlarge"
6
7
# Optional: Deepgram configuration overrides
8
deepgram_engine_env = {
9
  "01" = "max_active_requests=120"
10
}
11
deepgram_api_env = {
12
  "01" = "features.listen_v2=true"
13
}
14
15
# Optional: Enable auto-scaling
16
enable_autoscaling       = true
17
autoscaling_min_capacity = 1
18
autoscaling_max_capacity = 4
19
autoscaling_target_value = 5.0
20
21
# Optional: deploy an asynchronous endpoint instead of real-time
22
# enable_async_inference   = true
23
# async_s3_output_path     = "s3://my-deepgram-async/output/"
24
# async_s3_failure_path    = "s3://my-deepgram-async/failures/"
25
# enable_autoscaling       = true
26
# autoscaling_min_capacity = 0    # async supports scale-to-zero
27
# autoscaling_target_value = 5.0  # target ApproximateBacklogSizePerInstance

1
resource "aws_sagemaker_model" "deepgram" {
2
  name                     = var.model_name
3
  execution_role_arn       = aws_iam_role.sagemaker_execution.arn
4
  enable_network_isolation = true
5
6
  primary_container {
7
    model_package_name = var.model_package_arn
8
    environment        = local.deepgram_env
9
  }
10
11
  vpc_config {
12
    subnets            = ["subnet-0123456789abcdef0", "subnet-0123456789abcdef1"]
13
    security_group_ids = ["sg-0123456789abcdef0"]
14
  }
15
}