Infrastructure as Code (IaC) is a way to manage and provision infrastructure for a service through code, rather than manually through a user interface. This can include resources such as servers, load balancers, databases, network configuration, and more.
By using code to manage infrastructure, teams can version control their infrastructure and make it easier to automate the provisioning and management of resources. This can be particularly helpful in large organizations with teams and complex infrastructure, as it allows for more consistent and predictable deployments. It can also make it easier to roll back changes if necessary.
Hashicorp Terraform is an open-source tool for building, changing, and versioning infrastructure safely and efficiently. Terraform can be used to manage many resource types including AWS resources through the AWS Provider. This guide will walk you through installing Terraform, creating an Amazon Interactive Video Service (Amazon IVS) Channel, enabling record to Amazon Simple Storage Service (Amazon S3), enabling Protected Channels, and creating an Amazon IVS Chat Room.
Installing Terraform
To begin, install Terraform following the guide from the Terraform tutorial. This will enable you to use the terraform command line interface to deploy infrastructure using code written in HashiCorp Configuration Language (HCL).
Creating an AWS Account
To use Amazon IVS, you must have an account. Amazon currently offers a free trial of Amazon IVS under the AWS Free Tier for Amazon IVS. Upon initial sign-up for an AWS account, each month for the first 12 months new AWS customers receive 5 hours of basic input and 100 hours of SD video output each month - plus more.
Wondering what it’ll cost to run Amazon IVS in your production application? Check out the Amazon IVS Cost Estimator!
Using the AWS Terraform Provider
Terraform uses providers to enable interactions with APIs. The Terraform AWS Provider documentation provides details on authentication with AWS and configuration of the provider, such as region selection. It also provides guidelines and best practices around credential usage.
Using Terraform with Amazon IVS
Terraform has full support for Amazon IVS beginning with version v4.40.0 of the AWS Terraform Provider using the following resources and data sources:
- Channels:
aws_ivs_channel - Playback Key Pairs:
aws_ivs_playback_key_pair - Recording Configurations:
aws_ivs_recording_configuration - Stream Key:
aws_ivs_stream_key
Creating an Amazon IVS Channel
The aws_ivs_channel resource supports many arguments to configure the channel properties, such as enabling recording to S3 or requiring playback authorization. This resource has output attributes of the ingestion endpoint (ingest_endpoint) and the playback URL (playback_url).
terraform {
required_version = ">= 0.12"
}
provider "aws" {
region = "us-west-2"
}
resource "aws_ivs_channel" "example" {
type = "BASIC"
}
data "aws_ivs_stream_key" "example" {
channel_arn = aws_ivs_channel.example.arn
}
output "ingest_endpoint" {
value = aws_ivs_channel.example.ingest_endpoint
}
output "stream_key" {
value = data.aws_ivs_stream_key.example.value
}
output "playback_url" {
value = aws_ivs_channel.example.playback_url
}
Note: Only Basic channel types are applicable in the AWS Free Tier.
When applying this configuration via terraform apply, Terraform shows the infrastructure plan and will require a "yes" user input to apply the configuration. The outputs (ingest endpoint, stream key, and playback url) are shown after applying the plan.
➜ terraform apply
Terraform used the selected providers to generate the following execution plan. Resource actions are indicated with the following symbols:
+ create
<= read (data resources)
Terraform will perform the following actions:
# data.aws_ivs_stream_key.example will be read during apply
# (config refers to values not yet known)
<= data "aws_ivs_stream_key" "example" {
+ arn = (known after apply)
+ channel_arn = (known after apply)
+ id = (known after apply)
+ tags = (known after apply)
+ value = (known after apply)
}
# aws_ivs_channel.example will be created
+ resource "aws_ivs_channel" "example" {
+ arn = (known after apply)
+ authorized = (known after apply)
+ id = (known after apply)
+ ingest_endpoint = (known after apply)
+ latency_mode = (known after apply)
+ name = (known after apply)
+ playback_url = (known after apply)
+ recording_configuration_arn = (known after apply)
+ tags_all = (known after apply)
+ type = (known after apply)
}
Plan: 1 to add, 0 to change, 0 to destroy.
Changes to Outputs:
+ ingest_endpoint = (known after apply)
+ playback_url = (known after apply)
+ stream_key = (known after apply)
Do you want to perform these actions?
Terraform will perform the actions described above.
Only 'yes' will be accepted to approve.
Enter a value: yes
aws_ivs_channel.example: Creating...
aws_ivs_channel.example: Creation complete after 3s [id=arn:aws:ivs:us-west-2:326937407773:channel/EmVV0KxDONIR]
data.aws_ivs_stream_key.example: Reading...
data.aws_ivs_stream_key.example: Read complete after 1s [id=arn:aws:ivs:us-west-2:326937407773:stream-key/0Dy6pn6CQhMx]
Apply complete! Resources: 1 added, 0 changed, 0 destroyed.
Outputs:
ingest_endpoint = "a447f74b0a52.global-contribute.live-video.net"
playback_url = "https://a447f74b0a52.us-west-2.playback.live-video.net/api/video/v1/us-west-2.326937407773.channel.EmVV0KxDONIR.m3u8"
stream_key = "sk_us-west-xxxxxxxxxxxxx"
With the ingest endpoint and stream key, head over to Amazon IVS - Web Broadcast Tool to begin streaming. Click the "Open settings" gear icon near the bottom of the page...
... and enter in the Ingest endpoint and Stream key:
Click "Save" and then the "Start Streaming" button:
... and your stream is live!
To view the stream, head over to Amazon IVS Player Tester. Click the gear icon in the upper right corner:
... and add an Amazon IVS Player:
Enter the playback URL and click the "Load" button, and your live stream will begin playback:
Modifying an Amazon IVS Channel to Add Record to S3
This example creates a new S3 Bucket for use with the recording configuration, a recording configuration to specify the destination bucket and thumbnail properties, and assigns the recording configuration to the channel previously created. Modify the previous example configuration:
provider "aws" {
region = "us-west-2"
}
+
+resource "aws_s3_bucket" "example" {
+ bucket_prefix = "tf-ivs-stream-archive-"
+ force_destroy = true
+}
+
+resource "aws_ivs_recording_configuration" "example" {
+ name = "tf-ivs-recording-configuration"
+ lifecycle {
+ create_before_destroy = true
+ }
+ thumbnail_configuration {
+ recording_mode = "INTERVAL"
+ target_interval_seconds = 30
+ }
+ destination_configuration {
+ s3 {
+ bucket_name = aws_s3_bucket.example.id
+ }
+ }
+}
+
resource "aws_ivs_channel" "example" {
type = "BASIC"
+ recording_configuration_arn = aws_ivs_recording_configuration.example.arn
}
data "aws_ivs_stream_key" "example" {
Note: The
create_before_destroylifecycle option is needed for future modifications of the configuration that would cause the Recording Configuration to be deleted, as they cannot be updated in-place and must be recreated on modification. Recording Configurations cannot be deleted while a Channel uses it, so this option (on subsequent modifications) will update the Channel with a new Recording Configuration prior to deleting the old one.
While streaming, Amazon IVS puts the contents of the stream inside an S3 bucket created. See Auto-Record to Amazon S3 - Amazon Interactive Video Service for more information.
Note: Channels cannot be modified while they are live. Terraform will report an applicable
Unable to perform: ivs:UpdateChannel while resource: <arn> is liveerror if attempting to modify a live channel.
Creating an Amazon IVS Channel with Playback Authorization
This examples creates a new asymmetric key pair using AWS Key Management Service (KMS), creates a new Playback Key Pair using the key's public key material, and creates a channel requiring authorization:
resource "aws_kms_key" "example" {
description = "KMS Key for Amazon IVS Playback"
key_usage = "SIGN_VERIFY"
customer_master_key_spec = "ECC_NIST_P384"
}
data "aws_kms_public_key" "example" {
key_id = aws_kms_key.example.key_id
}
resource "aws_ivs_playback_key_pair" "example" {
name = "tf-ivs-playback-key-pair"
public_key = data.aws_kms_public_key.example.public_key_pem
}
resource "aws_ivs_channel" "example" {
name = "tf-ivs-playback-key-pair-example"
type = "BASIC"
authorized = true
}
Authorized channels require a JWT token URL parameter attached to the playback URL. See Generate and Sign Playback Tokens
for more information.
Here is an example Node.js (v18) console script to create a signed URL. This script requires the following Node modules installed via npm or yarn:
The script takes as arguments the keyId, channelArn, and expiration time as expiresIn. Running the script with the infrastructure created from the Terraform configuration (found either by using terraform show or adding outputs to the configuration file) will return a playback URL with a valid token appended:
➜ node create-playback-url-with-token.mjs \
--keyId 3df50d5f-054a-4f20-88c6-bb7a73306dd0 \
--channelArn arn:aws:ivs:us-west-2:326937407773:channel/aVbMPCM9Il2x \
--expiresIn 30
https://a447f74b0a52.us-west-2.playback.live-video.net/api/video/v1/us-west-2.326937407773.channel.aVbMPCM9Il2x.m3u8?token=eyJhbGciOiJFUzM4NCIsInR5cCI6IkpXVCJ9.eyJhd3M6Y2hhbm5lbC1hcm4iOiJhcm46YXdzOml2czp1cy13ZXN0LTI6MzI2OTM3NDA3NzczOmNoYW5uZWwvYVZiTVBDTTlJbDJ4IiwiYXdzOmFjY2Vzcy1jb250cm9sLWFsbG93LW9yaWdpbiI6IiIsImV4cCI6MTY3MzI3MzY5NCwiaWF0IjoxNjczMjczNjY0fQ.YAvlvVdO3rAq-7K3KHRPBvN1sU-JXJZ2963_thbaHBlBaYfyGYGAiqdJEN8XraEm3uc-h8NZiea8o0_XlOCHWIh9F1TGI1hSPqD7YY757C0ZF5cNsyBU49-sPbPvqpqa
Using Terraform with Amazon IVS Chat
Terraform has full support for Amazon IVS Chat beginning with version v4.41.0 of the AWS Terraform Provider using the following resources and data sources:
- Logging Configuration:
aws_ivschat_logging_configuration - Room:
aws_ivschat_room
Creating an Amazon IVS Chat Room
An Amazon IVS Chat room can easily be created with the ivschat_room resource:
resource "aws_ivschat_room" "example" {
}
This room can be used with the Amazon IVS Chat product. See Getting Started with Amazon IVS Chat
for more information and the Amazon IVS Chat Web Demo where you can validate chat functionality using the resources created previously.
Creating an Amazon IVS Chat Room with Message Handler
An Amazon IVS Chat Message Review Handler is a Lambda Function that allows modification and/or rejection of chat messages prior to delivery. This example creates a Lambda function, an IAM Role to allow Amazon IVS Chat to execute the function, and an Amazon IVS Chat Room using the function as a message review handler.
// index.js
/** Amazon IVS Chat message review handler */
exports.handler = async function ({ Content }) {
return {
ReviewResult: "ALLOW",
Content: `${Content} - edited by Lambda`
};
}
# main.tf
data "aws_region" "current" {}
data "aws_caller_identity" "current" {}
resource "aws_iam_role" "example" {
name = "tf-ivschat-message-handler-role"
assume_role_policy = <<EOF
{
"Version": "2012-10-17",
"Statement": [{
"Effect": "Allow",
"Action": ["sts:AssumeRole"],
"Principal": {"Service": "lambda.amazonaws.com"}
}]
}
EOF
}
data "archive_file" "message_review_handler" {
type = "zip"
source_file = "${path.module}/index.js"
output_path = "${path.module}/lambda-handler.zip"
}
resource "aws_lambda_function" "example" {
filename = data.archive_file.message_review_handler.output_path
function_name = "tf-ivschat-message-handler"
role = aws_iam_role.example.arn
source_code_hash = data.archive_file.message_review_handler.output_base64sha256
runtime = "nodejs18.x"
handler = "index.handler"
}
resource "aws_lambda_permission" "example" {
action = "lambda:InvokeFunction"
function_name = aws_lambda_function.example.function_name
principal = "ivschat.amazonaws.com"
source_account = data.aws_caller_identity.current.account_id
source_arn = "arn:aws:ivschat:${data.aws_region.current.name}:${data.aws_caller_identity.current.account_id}:room/*"
}
resource "aws_ivschat_room" "example" {
name = "tf-ivschat-room"
depends_on = [aws_lambda_permission.example]
message_review_handler {
uri = aws_lambda_function.example.arn
fallback_result = "ALLOW"
}
}
Creating an Amazon IVS Chat Room with Logging
Amazon IVS Chat supports logging of chat messages to several types of destinations, such as S3 Buckets or CloudWatch. This example creates an S3 Bucket for use with the logging configuration,
and assigns the logging configuration to a created room:
resource "aws_s3_bucket" "example" {
bucket_prefix = "tf-ivschat-logging-"
force_destroy = true
}
resource "aws_ivschat_logging_configuration" "example" {
name = "tf-ivschat-logging-configuration"
destination_configuration {
s3 {
bucket_name = aws_s3_bucket.example.id
}
}
}
resource "aws_ivschat_room" "example" {
name = "tf-ivschat-room"
logging_configuration_identifiers = [aws_ivschat_logging_configuration.example.arn]
}
In Closing
With Terraform, developers can create configuration files to manage deployment of Amazon IVS and Amazon IVS Chat resources. Using IaC can provide teams several benefits, such as version control, collaboration, reusability, and disaster recovery. Browse through the Amazon IVS User Guide to explore all features related to Amazon IVS and Amazon IVS Chat.
Top comments (0)