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 "inference_ami_version" {
31
  description = "SageMaker-managed host AMI (NVIDIA driver + container runtime) for the production variant. Defaults to the latest available version. Set to \"\" to use the SageMaker default for your instance type."
32
  type        = string
33
  default     = "al2023-ami-sagemaker-inference-gpu-4-1"
34
35
  validation {
36
    condition = contains([
37
      "",
38
      "al2-ami-sagemaker-inference-gpu-2",
39
      "al2-ami-sagemaker-inference-gpu-2-1",
40
      "al2-ami-sagemaker-inference-gpu-3-1",
41
      "al2023-ami-sagemaker-inference-gpu-4-1",
42
    ], var.inference_ami_version)
43
    error_message = "inference_ami_version must be a supported GPU AMI version, or \"\" to use the SageMaker default."
44
  }
45
}
46
47
variable "initial_instance_count" {
48
  description = "Number of instances to launch at endpoint creation."
49
  type        = number
50
  default     = 1
51
}
52
53
variable "variant_name" {
54
  description = "Name of the production variant."
55
  type        = string
56
  default     = "AllTraffic"
57
}
58
59
variable "deepgram_engine_env" {
60
  description = "Map of DEEPGRAM_ENGINE_* environment variables for TOML overrides."
61
  type        = map(string)
62
  default     = {}
63
}
64
65
variable "deepgram_api_env" {
66
  description = "Map of DEEPGRAM_API_* environment variables for TOML overrides."
67
  type        = map(string)
68
  default     = {}
69
}
70
71
variable "enable_autoscaling" {
72
  description = "Enable auto-scaling for the endpoint."
73
  type        = bool
74
  default     = false
75
}
76
77
variable "autoscaling_min_capacity" {
78
  description = "Minimum instance count for auto-scaling."
79
  type        = number
80
  default     = 1
81
}
82
83
variable "autoscaling_max_capacity" {
84
  description = "Maximum instance count for auto-scaling."
85
  type        = number
86
  default     = 4
87
}
88
89
variable "autoscaling_target_value" {
90
  description = "Target concurrent requests per instance for the scaling policy."
91
  type        = number
92
  default     = 5.0
93
}
94
95
variable "enable_async_inference" {
96
  description = "Deploy an asynchronous endpoint (queued, S3 in/out) instead of a real-time endpoint. Async endpoints accept only asynchronous invocations."
97
  type        = bool
98
  default     = false
99
}
100
101
variable "async_s3_output_path" {
102
  description = "S3 URI for async transcription output, e.g. s3://my-bucket/output/. Required when enable_async_inference = true."
103
  type        = string
104
  default     = ""
105
106
  validation {
107
    condition     = var.async_s3_output_path == "" || can(regex("^s3://", var.async_s3_output_path))
108
    error_message = "async_s3_output_path must be an s3:// URI."
109
  }
110
}
111
112
variable "async_s3_failure_path" {
113
  description = "Optional S3 URI for async failure output, e.g. s3://my-bucket/failures/."
114
  type        = string
115
  default     = ""
116
}

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.56" # inference_ami_version requires provider >= 5.56.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
    inference_ami_version  = var.inference_ami_version != "" ? var.inference_ami_version : null
118
  }
119
120
  dynamic "async_inference_config" {
121
    for_each = var.enable_async_inference ? [1] : []
122
    content {
123
      output_config {
124
        s3_output_path  = var.async_s3_output_path
125
        s3_failure_path = var.async_s3_failure_path != "" ? var.async_s3_failure_path : null
126
      }
127
    }
128
  }
129
130
  lifecycle {
131
    precondition {
132
      condition     = !var.enable_async_inference || var.async_s3_output_path != ""
133
      error_message = "async_s3_output_path is required when enable_async_inference = true."
134
    }
135
  }
136
}
137
138
###############################################################################
139
# SageMaker Endpoint
140
###############################################################################
141
142
resource "aws_sagemaker_endpoint" "deepgram" {
143
  name                 = var.endpoint_name
144
  endpoint_config_name = aws_sagemaker_endpoint_configuration.deepgram.name
145
}
146
147
###############################################################################
148
# Auto-Scaling (optional)
149
###############################################################################
150
151
resource "aws_appautoscaling_target" "sagemaker" {
152
  count = var.enable_autoscaling ? 1 : 0
153
154
  max_capacity       = var.autoscaling_max_capacity
155
  min_capacity       = var.autoscaling_min_capacity
156
  resource_id        = "endpoint/${aws_sagemaker_endpoint.deepgram.name}/variant/${var.variant_name}"
157
  scalable_dimension = "sagemaker:variant:DesiredInstanceCount"
158
  service_namespace  = "sagemaker"
159
}
160
161
resource "aws_appautoscaling_policy" "sagemaker" {
162
  count = var.enable_autoscaling ? 1 : 0
163
164
  name               = "${var.endpoint_name}-concurrency-policy"
165
  policy_type        = "TargetTrackingScaling"
166
  resource_id        = aws_appautoscaling_target.sagemaker[0].resource_id
167
  scalable_dimension = aws_appautoscaling_target.sagemaker[0].scalable_dimension
168
  service_namespace  = aws_appautoscaling_target.sagemaker[0].service_namespace
169
170
  target_tracking_scaling_policy_configuration {
171
    target_value = var.autoscaling_target_value
172
173
    # Real-time: scale on concurrent requests per model.
174
    dynamic "predefined_metric_specification" {
175
      for_each = var.enable_async_inference ? [] : [1]
176
      content {
177
        predefined_metric_type = "SageMakerVariantConcurrentRequestsPerModelHighResolution"
178
      }
179
    }
180
181
    # Async: scale on queue depth per instance.
182
    dynamic "customized_metric_specification" {
183
      for_each = var.enable_async_inference ? [1] : []
184
      content {
185
        metric_name = "ApproximateBacklogSizePerInstance"
186
        namespace   = "AWS/SageMaker"
187
        statistic   = "Average"
188
        dimensions {
189
          name  = "EndpointName"
190
          value = aws_sagemaker_endpoint.deepgram.name
191
        }
192
      }
193
    }
194
195
    scale_in_cooldown  = 300
196
    scale_out_cooldown = 60
197
  }
198
}
199
200
###############################################################################
201
# Async scale-from-zero (only when async + autoscaling are enabled)
202
###############################################################################
203
204
resource "aws_appautoscaling_policy" "async_scale_from_zero" {
205
  count = var.enable_async_inference && var.enable_autoscaling ? 1 : 0
206
207
  name               = "${var.endpoint_name}-scale-from-zero"
208
  policy_type        = "StepScaling"
209
  resource_id        = aws_appautoscaling_target.sagemaker[0].resource_id
210
  scalable_dimension = aws_appautoscaling_target.sagemaker[0].scalable_dimension
211
  service_namespace  = aws_appautoscaling_target.sagemaker[0].service_namespace
212
213
  step_scaling_policy_configuration {
214
    adjustment_type         = "ChangeInCapacity"
215
    metric_aggregation_type = "Average"
216
    cooldown                = 300
217
218
    step_adjustment {
219
      metric_interval_lower_bound = 0
220
      scaling_adjustment          = 1
221
    }
222
  }
223
}
224
225
resource "aws_cloudwatch_metric_alarm" "async_has_backlog" {
226
  count = var.enable_async_inference && var.enable_autoscaling ? 1 : 0
227
228
  alarm_name          = "${var.endpoint_name}-has-backlog-without-capacity"
229
  namespace           = "AWS/SageMaker"
230
  metric_name         = "HasBacklogWithoutCapacity"
231
  statistic           = "Average"
232
  period              = 60
233
  evaluation_periods  = 2
234
  datapoints_to_alarm = 2
235
  threshold           = 1
236
  comparison_operator = "GreaterThanOrEqualToThreshold"
237
  treat_missing_data  = "missing"
238
239
  dimensions = {
240
    EndpointName = aws_sagemaker_endpoint.deepgram.name
241
  }
242
243
  alarm_actions = [aws_appautoscaling_policy.async_scale_from_zero[0].arn]
244
}

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
inference_ami_version = "al2023-ami-sagemaker-inference-gpu-4-1"
7
8
# Optional: Deepgram configuration overrides
9
deepgram_engine_env = {
10
  "01" = "max_active_requests=120"
11
}
12
deepgram_api_env = {
13
  "01" = "features.listen_v2=true"
14
}
15
16
# Optional: Enable auto-scaling
17
enable_autoscaling       = true
18
autoscaling_min_capacity = 1
19
autoscaling_max_capacity = 4
20
autoscaling_target_value = 5.0
21
22
# Optional: deploy an asynchronous endpoint instead of real-time
23
# enable_async_inference   = true
24
# async_s3_output_path     = "s3://my-deepgram-async/output/"
25
# async_s3_failure_path    = "s3://my-deepgram-async/failures/"
26
# enable_autoscaling       = true
27
# autoscaling_min_capacity = 0    # async supports scale-to-zero
28
# 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
}