stackit-dev-tools/terraform-provider-stackitprivatepreview
3
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

fix(docs): Update CDN usage example (#1005)

Browse source 
relates to STACKITCDN-1003
This commit is contained in:
Christian Hamm 2025-10-16 13:49:17 +02:00 • committed by GitHub
parent 2a077d17d8
commit c733535d9b
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
2 changed files with 490 additions and 102 deletions
Download patch file Download diff file Expand all files Collapse all files

248
docs/guides/stackit_cdn_with_custom_domain.md
View file

@ -1,33 +1,66 @@
--- ---
page_title: "Using STACKIT CDN with your own domain" page_title: "Using STACKIT CDN to service static files from an HTTP Origin with STACKIT CDN"
--- ---
# Using STACKIT CDN with your own domain
## Overview # Using STACKIT CDN to service static files from an HTTP Origin with STACKIT CDN
This guide outlines the process of creating a STACKIT CDN distribution and configuring it to make use of an existing domain using STACKIT DNS. This guide will walk you through the process of setting up a STACKIT CDN distribution to serve static files from a
generic HTTP origin using Terraform. This is a common use case for developers who want to deliver content with low
latency and high data transfer speeds.
## Steps ---
1. **Create a STACKIT CDN and DNS Zone** ## Prerequisites
Create the CDN distribution and the DNS zone. Before you begin, make sure you have the following:
* A **STACKIT project** and a user account with the necessary permissions for the CDN.
* A **Service Account Key**: you can read about creating one here: [Create a Service Account Key
](https://docs.stackit.cloud/stackit/en/create-a-service-account-key-175112456.html)
---
## Step 1: Configure the Terraform Provider
First, you need to configure the STACKIT provider in your Terraform configuration. Create a file named `main.tf` and add
the following code. This block tells Terraform to download and use the STACKIT provider.
```terraform ```terraform
resource "stackit_cdn_distribution" "example_distribution" { terraform {
project_id = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" required_providers {
config = { stackit = {
backend = { source = "stackitcloud/stackit"
type = "http"
origin_url = "mybackend.onstackit.cloud"
} }
regions = ["EU", "US", "ASIA", "AF", "SA"]
blocked_countries = ["DE", "AT", "CH"]
} }
} }
variable "service_account_key" {
type = string
description = "Your STACKIT service account key."
sensitive = true
default = "path/to/sa-key.json"
}
variable "project_id" {
type = string
default = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" # Your project ID
}
provider "stackit" {
# The STACKIT provider is configured using the defined variables.
default_region = "eu01"
service_account_key_path = var.service_account_key
}
```
## Step 2: Create the DNS Zone
The first resource you'll create is the DNS zone, which will manage the records for your domain.
```terraform
resource "stackit_dns_zone" "example_zone" { resource "stackit_dns_zone" "example_zone" {
project_id = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" project_id = var.project_id
name = "My DNS zone" name = "My DNS zone"
dns_name = "myapp.runs.onstackit.cloud" dns_name = "myapp.runs.onstackit.cloud"
contact_email = "aa@bb.ccc" contact_email = "aa@bb.ccc"
@ -35,27 +68,188 @@ This guide outlines the process of creating a STACKIT CDN distribution and confi
} }
``` ```
2. **Add CNAME record to your DNS zone** ## Step 3: Create the CDN Distribution
Next, define the CDN distribution. This is the core service that will cache and serve your content from its origin.
If you want to redirect your entire domain to the CDN, you can instead use an A record.
```terraform ```terraform
resource "stackit_dns_record_set" "example" { resource "stackit_cdn_distribution" "example_distribution" {
project_id = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" project_id = var.project_id
config = {
# Define the backend configuration
backend = {
type = "http"
# Replace with the URL of your HTTP origin
origin_url = "https://your-origin-server.com"
}
# The regions where content will be hosted
regions = ["EU", "US", "ASIA", "AF", "SA"]
blocked_countries = []
}
}
```
## Step 4: Create the DNS CNAME Record
Finally, create the **CNAME record** to point your custom domain to the CDN. This step must come after the CDN is
created because it needs the CDN's unique domain name as its target.
```terraform
resource "stackit_dns_record_set" "cname_record" {
project_id = stackit_dns_zone.example_zone.project_id
zone_id = stackit_dns_zone.example_zone.zone_id zone_id = stackit_dns_zone.example_zone.zone_id
# This is the custom domain name which will be added to your zone
name = "cdn" name = "cdn"
type = "CNAME" type = "CNAME"
records = ["${stackit_cdn_distribution.domains[0].name}."] ttl = 3600
# Points to the CDN distribution's unique domain.
# Notice the added dot at the end of the domain name to point to a FQDN.
records = ["${stackit_cdn_distribution.example_distribution.domains[0].name}."]
} }
``` ```
3. **Create a STACKIT CDN Custom Domain** This record directs traffic from your custom domain to the STACKIT CDN infrastructure.
## Step 5: Add a Custom Domain to the CDN
To provide a user-friendly URL, associate a custom domain (like `cdn.myapp.runs.onstackit.cloud`) with your
distribution.
```terraform ```terraform
# Create a CDN custom domain resource "stackit_cdn_custom_domain" "example_custom_domain" {
resource "stackit_cdn_custom_domain" "example" { project_id = stackit_cdn_distribution.example_distribution.project_id
project_id = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
distribution_id = stackit_cdn_distribution.example_distribution.distribution_id distribution_id = stackit_cdn_distribution.example_distribution.distribution_id
name = "${stackit_dns_record_set.example.name}.${stackit_dns_zone.example_zone.dns_name}"
# Creates "cdn.myapp.runs.onstackit.cloud" dynamically
name = "${stackit_dns_record_set.cname_record.name}.${stackit_dns_zone.example_zone.dns_name}"
} }
``` ```
Now, you can access your content on the url `cdn.myapp.runs.onstackit.cloud`. This resource links the subdomain you created in the previous step to the CDN distribution.
## Complete Terraform Configuration
Here is the complete `main.tf` file, which follows the logical order of operations.
```terraform
# This configuration file sets up a complete STACKIT CDN distribution
# with a custom domain managed by STACKIT DNS.
# -----------------------------------------------------------------------------
# PROVIDER CONFIGURATION
# -----------------------------------------------------------------------------
terraform {
required_providers {
stackit = {
source = "stackitcloud/stackit"
}
}
}
variable "service_account_key" {
type = string
description = "Your STACKIT service account key."
sensitive = true
default = "path/to/sa-key.json"
}
variable "project_id" {
type = string
description = "Your STACKIT project ID."
default = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
provider "stackit" {
# The STACKIT provider is configured using the defined variables.
default_region = "eu01"
service_account_key_path = var.service_account_key
}
# -----------------------------------------------------------------------------
# DNS ZONE RESOURCE
# -----------------------------------------------------------------------------
# The DNS zone manages all records for your domain.
# It's the first resource to be created.
# -----------------------------------------------------------------------------
resource "stackit_dns_zone" "example_zone" {
project_id = var.project_id
name = "My DNS zone"
dns_name = "myapp.runs.onstackit.cloud"
contact_email = "aa@bb.ccc"
type = "primary"
}
# -----------------------------------------------------------------------------
# CDN DISTRIBUTION RESOURCE
# -----------------------------------------------------------------------------
# This resource defines the CDN, its origin, and caching regions.
# -----------------------------------------------------------------------------
resource "stackit_cdn_distribution" "example_distribution" {
project_id = var.project_id
config = {
# Define the backend configuration
backend = {
type = "http"
# Replace with the URL of your HTTP origin
origin_url = "https://your-origin-server.com"
}
# The regions where content will be hosted
regions = ["EU", "US", "ASIA", "AF", "SA"]
blocked_countries = []
}
}
# -----------------------------------------------------------------------------
# CUSTOM DOMAIN AND DNS RECORD
# -----------------------------------------------------------------------------
# These resources link your CDN to a user-friendly custom domain and create
# the necessary DNS record to route traffic.
# -----------------------------------------------------------------------------
resource "stackit_dns_record_set" "cname_record" {
project_id = stackit_dns_zone.example_zone.project_id
zone_id = stackit_dns_zone.example_zone.zone_id
# This is the custom domain name which will be added to your zone
name = "cdn"
type = "CNAME"
ttl = 3600
# Points to the CDN distribution's unique domain.
# The dot at the end makes it a fully qualified domain name (FQDN).
records = ["${stackit_cdn_distribution.example_distribution.domains[0].name}."]
}
resource "stackit_cdn_custom_domain" "example_custom_domain" {
project_id = stackit_cdn_distribution.example_distribution.project_id
distribution_id = stackit_cdn_distribution.example_distribution.distribution_id
# Creates "cdn.myapp.runs.onstackit.cloud" dynamically
name = "${stackit_dns_record_set.cname_record.name}.${stackit_dns_zone.example_zone.dns_name}"
}
# -----------------------------------------------------------------------------
# OUTPUTS
# -----------------------------------------------------------------------------
# This output will display the final custom URL after `terraform apply` is run.
# -----------------------------------------------------------------------------
output "custom_cdn_url" {
description = "The final custom domain URL for the CDN distribution."
value = "https://${stackit_cdn_custom_domain.example_custom_domain.name}"
}
```

248
templates/guides/stackit_cdn_with_custom_domain.md.tmpl
View file

@ -1,33 +1,66 @@
--- ---
page_title: "Using STACKIT CDN with your own domain" page_title: "Using STACKIT CDN to service static files from an HTTP Origin with STACKIT CDN"
--- ---
# Using STACKIT CDN with your own domain
## Overview # Using STACKIT CDN to service static files from an HTTP Origin with STACKIT CDN
This guide outlines the process of creating a STACKIT CDN distribution and configuring it to make use of an existing domain using STACKIT DNS. This guide will walk you through the process of setting up a STACKIT CDN distribution to serve static files from a
generic HTTP origin using Terraform. This is a common use case for developers who want to deliver content with low
latency and high data transfer speeds.
## Steps ---
1. **Create a STACKIT CDN and DNS Zone** ## Prerequisites
Create the CDN distribution and the DNS zone. Before you begin, make sure you have the following:
* A **STACKIT project** and a user account with the necessary permissions for the CDN.
* A **Service Account Key**: you can read about creating one here: [Create a Service Account Key
](https://docs.stackit.cloud/stackit/en/create-a-service-account-key-175112456.html)
---
## Step 1: Configure the Terraform Provider
First, you need to configure the STACKIT provider in your Terraform configuration. Create a file named `main.tf` and add
the following code. This block tells Terraform to download and use the STACKIT provider.
```terraform ```terraform
resource "stackit_cdn_distribution" "example_distribution" { terraform {
project_id = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" required_providers {
config = { stackit = {
backend = { source = "stackitcloud/stackit"
type = "http"
origin_url = "mybackend.onstackit.cloud"
} }
regions = ["EU", "US", "ASIA", "AF", "SA"]
blocked_countries = ["DE", "AT", "CH"]
} }
} }
variable "service_account_key" {
type = string
description = "Your STACKIT service account key."
sensitive = true
default = "path/to/sa-key.json"
}
variable "project_id" {
type = string
default = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" # Your project ID
}
provider "stackit" {
# The STACKIT provider is configured using the defined variables.
default_region = "eu01"
service_account_key_path = var.service_account_key
}
```
## Step 2: Create the DNS Zone
The first resource you'll create is the DNS zone, which will manage the records for your domain.
```terraform
resource "stackit_dns_zone" "example_zone" { resource "stackit_dns_zone" "example_zone" {
project_id = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" project_id = var.project_id
name = "My DNS zone" name = "My DNS zone"
dns_name = "myapp.runs.onstackit.cloud" dns_name = "myapp.runs.onstackit.cloud"
contact_email = "aa@bb.ccc" contact_email = "aa@bb.ccc"
@ -35,27 +68,188 @@ This guide outlines the process of creating a STACKIT CDN distribution and confi
} }
``` ```
2. **Add CNAME record to your DNS zone** ## Step 3: Create the CDN Distribution
Next, define the CDN distribution. This is the core service that will cache and serve your content from its origin.
If you want to redirect your entire domain to the CDN, you can instead use an A record.
```terraform ```terraform
resource "stackit_dns_record_set" "example" { resource "stackit_cdn_distribution" "example_distribution" {
project_id = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" project_id = var.project_id
config = {
# Define the backend configuration
backend = {
type = "http"
# Replace with the URL of your HTTP origin
origin_url = "https://your-origin-server.com"
}
# The regions where content will be hosted
regions = ["EU", "US", "ASIA", "AF", "SA"]
blocked_countries = []
}
}
```
## Step 4: Create the DNS CNAME Record
Finally, create the **CNAME record** to point your custom domain to the CDN. This step must come after the CDN is
created because it needs the CDN's unique domain name as its target.
```terraform
resource "stackit_dns_record_set" "cname_record" {
project_id = stackit_dns_zone.example_zone.project_id
zone_id = stackit_dns_zone.example_zone.zone_id zone_id = stackit_dns_zone.example_zone.zone_id
# This is the custom domain name which will be added to your zone
name = "cdn" name = "cdn"
type = "CNAME" type = "CNAME"
records = ["${stackit_cdn_distribution.domains[0].name}."] ttl = 3600
# Points to the CDN distribution's unique domain.
# Notice the added dot at the end of the domain name to point to a FQDN.
records = ["${stackit_cdn_distribution.example_distribution.domains[0].name}."]
} }
``` ```
3. **Create a STACKIT CDN Custom Domain** This record directs traffic from your custom domain to the STACKIT CDN infrastructure.
## Step 5: Add a Custom Domain to the CDN
To provide a user-friendly URL, associate a custom domain (like `cdn.myapp.runs.onstackit.cloud`) with your
distribution.
```terraform ```terraform
# Create a CDN custom domain resource "stackit_cdn_custom_domain" "example_custom_domain" {
resource "stackit_cdn_custom_domain" "example" { project_id = stackit_cdn_distribution.example_distribution.project_id
project_id = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
distribution_id = stackit_cdn_distribution.example_distribution.distribution_id distribution_id = stackit_cdn_distribution.example_distribution.distribution_id
name = "${stackit_dns_record_set.example.name}.${stackit_dns_zone.example_zone.dns_name}"
# Creates "cdn.myapp.runs.onstackit.cloud" dynamically
name = "${stackit_dns_record_set.cname_record.name}.${stackit_dns_zone.example_zone.dns_name}"
} }
``` ```
Now, you can access your content on the url `cdn.myapp.runs.onstackit.cloud`. This resource links the subdomain you created in the previous step to the CDN distribution.
## Complete Terraform Configuration
Here is the complete `main.tf` file, which follows the logical order of operations.
```terraform
# This configuration file sets up a complete STACKIT CDN distribution
# with a custom domain managed by STACKIT DNS.
# -----------------------------------------------------------------------------
# PROVIDER CONFIGURATION
# -----------------------------------------------------------------------------
terraform {
required_providers {
stackit = {
source = "stackitcloud/stackit"
}
}
}
variable "service_account_key" {
type = string
description = "Your STACKIT service account key."
sensitive = true
default = "path/to/sa-key.json"
}
variable "project_id" {
type = string
description = "Your STACKIT project ID."
default = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
provider "stackit" {
# The STACKIT provider is configured using the defined variables.
default_region = "eu01"
service_account_key_path = var.service_account_key
}
# -----------------------------------------------------------------------------
# DNS ZONE RESOURCE
# -----------------------------------------------------------------------------
# The DNS zone manages all records for your domain.
# It's the first resource to be created.
# -----------------------------------------------------------------------------
resource "stackit_dns_zone" "example_zone" {
project_id = var.project_id
name = "My DNS zone"
dns_name = "myapp.runs.onstackit.cloud"
contact_email = "aa@bb.ccc"
type = "primary"
}
# -----------------------------------------------------------------------------
# CDN DISTRIBUTION RESOURCE
# -----------------------------------------------------------------------------
# This resource defines the CDN, its origin, and caching regions.
# -----------------------------------------------------------------------------
resource "stackit_cdn_distribution" "example_distribution" {
project_id = var.project_id
config = {
# Define the backend configuration
backend = {
type = "http"
# Replace with the URL of your HTTP origin
origin_url = "https://your-origin-server.com"
}
# The regions where content will be hosted
regions = ["EU", "US", "ASIA", "AF", "SA"]
blocked_countries = []
}
}
# -----------------------------------------------------------------------------
# CUSTOM DOMAIN AND DNS RECORD
# -----------------------------------------------------------------------------
# These resources link your CDN to a user-friendly custom domain and create
# the necessary DNS record to route traffic.
# -----------------------------------------------------------------------------
resource "stackit_dns_record_set" "cname_record" {
project_id = stackit_dns_zone.example_zone.project_id
zone_id = stackit_dns_zone.example_zone.zone_id
# This is the custom domain name which will be added to your zone
name = "cdn"
type = "CNAME"
ttl = 3600
# Points to the CDN distribution's unique domain.
# The dot at the end makes it a fully qualified domain name (FQDN).
records = ["${stackit_cdn_distribution.example_distribution.domains[0].name}."]
}
resource "stackit_cdn_custom_domain" "example_custom_domain" {
project_id = stackit_cdn_distribution.example_distribution.project_id
distribution_id = stackit_cdn_distribution.example_distribution.distribution_id
# Creates "cdn.myapp.runs.onstackit.cloud" dynamically
name = "${stackit_dns_record_set.cname_record.name}.${stackit_dns_zone.example_zone.dns_name}"
}
# -----------------------------------------------------------------------------
# OUTPUTS
# -----------------------------------------------------------------------------
# This output will display the final custom URL after `terraform apply` is run.
# -----------------------------------------------------------------------------
output "custom_cdn_url" {
description = "The final custom domain URL for the CDN distribution."
value = "https://${stackit_cdn_custom_domain.example_custom_domain.name}"
}
```