Manage a CDN resource with Terraform

What is Terraform?

Terraform is a declarative command-line utility used to manage the infrastructure of Terraform partner providers. With this tool, you can manage our CDN service. 

To work with Terraform, you create a configuration file where you specify the changes you want to make to your CDN service — for example, to create a new CDN resource or to add an SSL certificate. Then you run the Terraform command to make changes. The utility reads the configuration file and sends necessary API requests. As a result, the required CDN settings are applied. 

Install Terraform and integrate it with our CDN

1. Download the appropriate Terraform package for your OS from the official Terraform website.  

2. Create a new folder and name it just as the downloaded package. 

3. Unzip the Terraform archive into the new folder. 

4. Add the directory of the unzipped Terraform archive to the PATH environment variable. 

5. Create a configuration file in the Terraform folder and name it main.tf.  

6. Copy the code below and paste it to the main.tf file.  

Where:

• 0.3.44 is the latest version of the Terraform provider indicated on the page;
• 251$d33611b35f26d8 is a permanent API token generated according to the guide.

7. Open the command-line interface, access the "Terraform" folder and run the command: 

      Copy
      
    terraform init

This command will install Terraform and download a set of modules to work with our CDN. The following response will appear:

This response means Terraform was successfully downloaded and installed, you can start working with it. 

Manage the CDN infrastructure via Terraform

If you have already worked with Terraform, you can use the abridged guide on how to manage the Gcore CDN infrastructure: 

1. Copy the required code from the Resources section in the Terraform documentation and paste it to the main.tf file. 

2. Add your values to the code. 

3. Run the terraform plan command — it will show what changes you are going to make to the CDN settings. 

4. Run the terraform apply command to make changes to the CDN. 

You can also use our step-by-step guides below.  

Create a new CDN resource

This guide will help you to create a CDN resource and integrate it with your websites (content sources). 

1. Open the main.tf file where you configured the Gcore provider for Terraform. 

2. At this step, you will write the code that creates an origin group — the CDN resource will pull content from those origins. An origin group has three features: 

• You choose which origin will be active and which origin will be backup. An active origin is accessed whenever the CDN requests content. A backup origin is accessed only when active origins return 4xx or 5xx error. A group must have at least one active origin.   
• You can enable or disable the "Use next upstream" option. It defines the order in which the CDN will access remaining origins if the first origin returns a 4xx or 5xx error. If this option is on, the CDN will access active origins one by one, and then request backup origins. If it is off, the CDN will ignore remaining active origins and will immediately request a backup origin. 
• You can create a group from a single origin. It must consist of an active origin. The "Use next upstream" option should be disabled.

Copy the code below to the file. Replace the hints in the brackets with your values and remove the brackets.   

If you want to enable the "Use next upstream" option, add the string below: 

      Copy
      
    use_next = true 

If you want to disable the "Use next upstream" option, add the string below: 

      Copy
      
    use_next = false 

To add an active origin, enter the code below. Specify your website domain and remove the brackets. 

To add a backup origin, enter the code below. Specify your website domain and remove the brackets. 

Add as many origins as you need. The maximum number is ten. 

Add another curly bracket to a new string below. 

      Copy
      
    } 

Here is an example. Let's say you want to create an origin group with the following parameters: 

• example_terraform — name of the origin group that will be displayed in Terraform, 
• example group — the name of the origin group that will be displayed in the Gcore Customer Portal, 
• the "Use next upstream" option is disabled, 
• one.com and two.com — the active origins, 
• three.com — the backup origin.

Then the code in the configuration file will look as follows: 

3. At this step, you will write the code that adds a CDN resource to your origin group. Continue to enter the code below in the same configuration file. 

Copy the code below, replace the hints in the brackets with your values, and remove the brackets.   

If you want to configure the CDN so that it will access an origin on a protocol of a user's request — HTTP or HTTPS — add the string below:   

      Copy
      
    origin_protocol     = "MATCH" 

If you want the CDN to be able to use only HTTP, add the string: 

      Copy
      
    origin_protocol     = "HTTP" 

If you want the CDN to be able to use only HTTPS, add the string: 

      Copy
      
    origin_protocol     = "HTTPS" 

If you want to deliver different types of content from two separate custom domains, add the string below: 

If you want to deliver different types of content from more than two separate custom domains, add the string below: 

In the end, add a curly bracket to a new string below.

      Copy
      
    } 

Here is an example. Let's say you want to create a CDN resource with the following parameters: 

• cdn_example_com — name of the resource that will be displayed in Terraform,  
• сdn.one.com — custom domain of the CDN resource that will be displayed in the file paths and in the Gcore Customer Portal,  
• example_terraform — name of the origin group that will be displayed in Terraform, 
• HTTPS — protocol that will be used by the CDN to access an origin,  
• cdn.two.com and cdn.three.com — additional custom domains.

Then the code in the configuration file will look as follows:  

4. At Step 2 and 3, you entered the code that has created an origin group and a CDN resource. Below is an example of how your code may look in your configuration file:

Make sure all data is correct and save the changes.  

5. Access the "Terraform" folder in command-line interface and run the terraform plan command — it will show what changes Terraform is going to make. If the code in the configuration file contains an error, the output will give a brief description of it. 

6. Run the terraform apply command — it will make changes to the CDN. Terraform will ask you to confirm the action — enter "yes". 

Congratulations! The origin group and CDN resource have been created! Then the CDN resource requires configuring a custom domain and changing the file paths so that they contain the custom domain instead of the origin domain. Use the guide below. 

1. Log in to your Gcore account, go to the "CDN" tab and click the custom domain of the resource created in Terraform.

2. On the page that opens, click "Setup guide". 

3. Copy the domain name such as *.gcdn.co. from the sliding panel.

4. Go to the settings of your DNS provider and create a CNAME record for the custom domain. For the value of the CNAME record, paste the value copied at the previous step.  

Here is an example. Let's say your custom domain is cdn.example.com and at Step 3 you copied the cl-sdf34f.gcdn.co domain. So, in the personal account of your DNS provider, you need to create a CNAME record for cdn.example.com with cl-sdf34f.gcdn.co. as its value. 

5. Change the file paths so that they contain the custom domain instead of origin domain. For example, if your origin is example.com, and the custom domain is cdn.example.com, replace in the file paths example.com with cdn.example.com. If the source website is built on a CMS, you can change the file paths using special plugins you can find on the Internet. If the site is not built on a CMS, we recommend writing a script to replace domain name in the paths. 

Congratulations! The setup is complete! You have created and integrated your CDN resource.  

Configure CDN resource options

When you create a CDN resource via Terraform, it automatically adds the following options with default values: 

• browse_cache_settings — Browser Caching, 
• cors — CORS header support, 
• edge_cache_settings — CDN Caching, 
• gzip_on — GZip Compression, 
• host_header — Change Host Header, 
• ignore_query_string — Ignore Query String (Ignore All), 
• query_params_blacklist — Ignore Query String (Ignore All Except), 
• query_params_whitelist — Ignore Query String (Ignore Only), 
• redirect_http_to_https — Enable HTTPS, 
• rewrite — Rewrite (request redirection), 
• sni — Change SNI hostname, 
• static_request_headers — Response headers, 
• tls_versions — Supported TLS versions, 
• webp — WebP Compression, 
• websockets  — WebSockets.

We constantly add new options. The up-to-date list is always available in the Terraform documentation for the Gcore provider. 

If a CDN resource was created via Terraform, you can change its options via Terraform. To do this, use the guide below. 

1. Open the main.tf file. 

2. The file is supposed to contain the code for the creation of your CDN resource. If it is missing, add the code according to the "Create a new CDN resource" section.  

Don't worry, Terraform won't duplicate a resource. Terraform requires the code used for the creation of the resource only to identify a resource that should be changed. 

3. Add the following string before the last curly bracket:  

      Copy
      
    options { 

4. Open the Terraform documentation for the Gcore provider and find the required option. Follow the guide from the Terraform documentation, to enter the required option values. 

5. Be aware to add a curly bracket to a new string below: 

      Copy
      
    } 

Here is an example. You want to set up CDN Caching and find this option in the Terraform documentation — edge_cache_settings. You need to set up CDN Caching with these settings:  

• 345600 seconds (4 days) is the caching time for responses with 200, 206, 301, and 302 codes, 
• 1000 seconds is the caching time for responses with a 403 code, 
• 50 seconds is the caching time for responses with a 404 code.

According to the guide, you need to add the necessary settings below the options { string. 

      Copy
      
    edge_cache_settings {    
  custom_values = {       
    "403" = "1000s"      
    "404" = "50s" 
  }    
  enabled = true   
  value = "345600s" 
  } 

6. The configuration file now contains the code that creates a CDN resource with your option values. An example of the file:

Save the changes in the configuration file.  

7. Access the "Terraform" folder in the command-line interface and run the terraform plan command — it will show what changes Terraform is going to make. If the code contains an error, the output will give a brief description of it. 

8. Run the terraform apply command — it will make changes to the CDN. Terraform will ask you to confirm the action — enter "yes". 

Add an SSL certificate

If a CDN resource was created via Terraform, you can add an SSL certificate via Terraform. To do this, use the guide below. 

1. Open the main.tf file. 

2_._ The file is supposed to contain the code for the creation of your CDN resource. If it is missing, add the code according to the Create a new CDN resource section.  

Don't worry, Terraform won't duplicate a resource. Terraform requires the code used for the creation of the resource only to identify a resource that should be changed. 

3. At this step, you will add the necessary strings for issuing an SSL certificate. 

Add the code below before the following string: resource "gcore_cdn_resource" "(name of your resource in Terraform)" {. Replace the hints in the brackets with your values and remove the brackets. 

4. Add the code below after the secondary_hostnames string, if any (if not, after origin_protocol). Replace the hints in the brackets with your values and remove the brackets. 

Here is an example of adding a certificate. Let's suppose your values are as follows: 

• example_cert — the name of the certificate that will be displayed in Terraform, 
• example_certificate — the name of the certificate that will be displayed in the Gcore Customer Portal, 
• -----BEGIN CERTIFICATE-----MIIDkjCCAnqgAwIBAgIgTfqoZeTGCEvm...T7XH8IlQY0SGq2FSZKJAlrfX+UOpIMWQcOwcuDB97DXl5Bjs+QEXO203GW0C-----END CERTIFICATE----- — the public key of the certificate,
• -----BEGIN RSA PRIVATE KEY-----MIIEpAIBAAKCAQEAzzj54zBOWxBIJRFMBtG...xyf2T9RZYRpIVbkatg977nXryEZC8Sp8U76c3Oww==-----END RSA PRIVATE KEY----- — the private key of the certificate.

To add such a certificate, you have inserted the necessary strings into the configuration file. The file is supposed to look as follows:

5. Save the changes in the configuration file. 

6. Access the "Terraform" folder in the command-line interface unless you are already in it, and run the terraform plan command — it will show what changes Terraform is going to make. If the code contains an error, the output will give a brief description of it.  

7. Run the terraform apply command — it will make changes to the CDN. Terraform will ask you to confirm the action — enter "yes". 

Create a rule

If a CDN resource was created via Terraform, you can add a rule to it via Terraform. To do this, use the guide below.  

1. Open the main.tf file. 

2. The file is supposed to contain the code for the creation of your CDN resource. If it is missing, add the code according to the Create a new CDN resource section.  

Don't worry, Terraform won't duplicate a resource. Terraform requires the code used to create a resource only to identify a resource that should be changed. 

3. At this step, you will add the necessary strings for creating a rule to the configuration file. 

Add the code below to a new string. Replace the hints in the brackets with your values and remove the brackets.  

4. If you want to add options to the rule, paste the code below. Replace the hints in the brackets with your values and remove the brackets. 

If you don't need options, do not add the options code segment. 

5. Be aware to add a curly bracket to a new string below. 

      Copy
      
    } 

Here is an example of a configuration file. Let's say you want to add a rule with the following characteristics: 

• example_rule — the name of the rule for Terraform, 
• cdn_example_com — the name of the CDN resource in Terraform,  
• PNG images — the name of the rule from the Gcore Customer Portal. 
• /folder/images/*.png — the path to the files. 
• The "WebP Compression" option with a final quality of 66 is required.

The final code in the configuration file will look as follows:

6. Save the changes in the configuration file. 

7. Access the "Terraform" folder in the command-line interface unless you are already in it, and run the terraform plan command — it will show what changes Terraform is going to make. If the code contains an error, the output will give a brief description of it.  

8. Run the terraform apply command — it will make changes to the CDN. Terraform will ask you to confirm the action — enter "yes".