Add guide for CDN management

docs/guides/cdn.md

@@ -0,0 +1,204 @@
+---
+layout: "vkcs"
+page_title: "Building VPN Tunnel between VK Cloud private subnets"
+description: |-
+  CDN within VKCS.
+---
+
+# Manage CDN with the VKCS Terraform Provider
+
+This guide provides a detailed, step-by-step approach to configuring and managing VKCS Content Delivery Network (CDN) resources using the provider. It covers essential tasks such as setting up CDN resources, origin groups, and SSL certificates.
+
+## Prerequisites
+
+Before diving into the guide, ensure you meet the following prerequisites:
+
+- **Configure Terraform and VKCS Provider** Make sure that you installed Terraform CLI and configured VKCS Provider. Follow [instructions](/docs/guides/getting_started.md) if needed.
+- **Understand Terraform Basics:** Familiarize yourself with Terraform concepts like resource lifecycles, dependencies, and state management. [Terraform documentation](https://developer.hashicorp.com/terraform/docs) will help you understand the basic principles and key points.
+- **Understand VKCS CDN Basics:** Check the CDN service [documentation](https://cloud.vk.com/docs/en/networks/cdn) to understand main concepts.
+
+## Configuring Origin Groups
+
+Origin groups manage the backend servers responsible for hosting and delivering content. A well-configured origin group ensures reliability and efficiency, and you should always configure an one for a CDN resource with an use of `vkcs_cdn_origin_group` resource.
+
+Consider adding multiple origins for redundancy and failover. When `use_next` argument is set to "true", a CDN server will request content by moving down the origin list on either on 4xx or 5xx errors, otherwise content will be requested from one of the active origins, and then from one of the backups if the first request failed with a 5xx error. To get more details, refer to the VK Cloud [documentation](https://cloud.vk.com/docs/en/networks/cdn/concepts/origin-groups).
+
+### Example Configuration:
+
+```hcl
+resource "vkcs_cdn_origin_group" "origin_group" {
+  name = "tfguide-origin-group"
+  origins = [
+    {
+      source = "origin1.vk.com"
+    },
+    {
+      source = "origin2.vk.com"
+      backup = true
+    }
+  ]
+  use_next = false
+}
+```
+
+## Adding a SSL certificate
+
+Proceed to the next step if you plan to use Let's Encrypt certificate, or not use one at all.
+
+SSL certificates should be used for content delivery over HTTPS protocol. To manage your own certificates and to apply them to CDN resources, you can use `vkcs_cdn_ssl_certificate` resource.
+
+```hcl
+resource "vkcs_cdn_ssl_certificate" "certificate" {
+  name        = "tfguide-ssl-certificate"
+  certificate = file("path/to/certificate.pem")
+  private_key = file("path/to/private.key")
+}
+```
+
+!> **Security Note:** `certificate` and `private_key` are marked as sensitive, and, therefore, will not be shown in outputs, but you should consider protecting them as input variables and state values. To get more information on the topic, you can refer to the [official tutorial](https://developer.hashicorp.com/terraform/tutorials/configuration-language/sensitive-variables#sensitive-values-in-state).
+
+## Creating a CDN Resource
+
+CDN resources serve as the cornerstone for accelerating content delivery, optimizing reliability, and reducing the load of origin services. To create an one, you should use `vkcs_cdn_resource` resource.
+
+### Example Configuration:
+
+```hcl
+resource "vkcs_cdn_resource" "resource" {
+  cname        = "tfguide-resource.vk.com"
+  origin_group = vkcs_cdn_origin_group.origin_group.id
+  options = {
+    edge_cache_settings = {
+      value = "10m"
+    }
+    forward_host_header = true
+  }
+  shielding = {
+    enabled = true
+    pop_id  = data.vkcs_cdn_shielding_pop.id
+  }
+  ssl_certificate = {
+    type = "own"
+    id   = vkcs_cdn_ssl_certificate.certificate.id
+  }
+}
+```
+
+### Using a Let's Encrypt certificate
+
+To issue a free [Let's Encrypt](https://letsencrypt.org/) certificate, specify "lets_encrypt" as the value for `ssl_certificate.type` argument. The certificate will be issued after the CDN resource is established, once the origin servers are available and DNS changes involving the CNAME records for personal domains have propagated.
+
+~> **Note:** The option is only available for an active CDN resource, to achieve this, set the value of `active` argument to "true".
+
+###  Utilizing Shielding PoPs
+
+Proceed to the next step if you do not plan to enable CDN resource shielding.
+
+Shielding PoPs act as intermediaries to enhance performance by caching content closer to end users, you should choose one strategically based on traffic origins.
+
+#### List all Points of Presence
+
+To list all points of presence, you can use "vkcs_cdn_shielding_pops" data source.
+
+```hcl
+data "vkcs_cdn_shielding_pops" "pops" {}
+```
+
+#### Retrieve the identifier of PoP
+
+To enable shielding on a CDN resource, you should provide the identifier of a specific PoP, which can be retrieved with an use of `vkcs_cdn_shielding_pop` data source:
+
+```hcl
+data "vkcs_cdn_shielding_pop" "pop" {
+  city = "Moscow-Megafon"
+}
+```
+
+### Configuring ACLs
+
+To enhance security, you can specify Access Control Lists (ACLs) options. All of the follow the same principles: when `policy_type` is "allow", it means that CDN server will allow access for all possible values of ACL subject except for those specified in `excepted_values` argument, and when `policy_type` is
+"deny", CDN will deny access with the same logic for excepted values.
+
+#### Example Configuration
+
+For example, to protect content from unauthorized access from certain countries, you could use `country_acl` option:
+
+```hcl
+resource "vkcs_cdn_resource" "resource" {
+  ...
+  options = {
+    country_acl = {
+      policy_type     = "allow"
+      excepted_values = ["GB", "DE"]
+    }
+  }
+  ...
+}
+```
+
+## Complete Example Configuration
+
+Below is an integrated example showcasing all components:
+
+```hcl
+data "vkcs_cdn_shielding_pop" "pop" {
+  city = "Moscow-Megafon"
+}
+
+resource "vkcs_cdn_origin_group" "origin_group" {
+  name = "tfguide-origin-group"
+  origins = [
+    {
+      source = "origin1.vk.com"
+    },
+    {
+      source = "origin2.vk.com"
+      backup = true
+    }
+  ]
+  use_next = true
+}
+
+resource "vkcs_cdn_ssl_certificate" "certificate" {
+  name        = "tfguide-ssl-certificate"
+  certificate = file("path/to/certificate.pem")
+  private_key = file("path/to/private.key")
+}
+
+resource "vkcs_cdn_resource" "resource" {
+  cname        = "tfguide-resource.vk.com"
+  origin_group = vkcs_cdn_origin_group.origin_group.id
+  options = {
+    edge_cache_settings = {
+      value = "10m"
+    }
+    forward_host_header = true
+  }
+  shielding = {
+    enabled = true
+    pop_id  = data.vkcs_cdn_shielding_pop.id
+  }
+  ssl_certificate = {
+    type = "own"
+    id   = vkcs_cdn_ssl_certificate.certificate.id
+  }
+}
+
+resource "vkcs_cdn_origin_group" "origin_group" {
+  name = "tfguide-origin-group"
+  origins = [
+    {
+      source = "origin1.vk.com"
+    },
+    {
+      source = "origin2.vk.com"
+      backup = true
+    }
+  ]
+  use_next = true
+}
+```
+
+## Next Steps
+
+Review the full documentation on CDN management with the VKCS Terraform Provider in the corresponding category of the provider [documentation](https://registry.terraform.io/providers/vk-cs/vkcs/latest/docs), pay special attention on the available CDN resource options. Test various configurations to optimize content freshness and perfomance, and to customize access.