Configure network lists

With the Akamai Network Lists provider for Terraform you can automate the creation, deployment, and management of network lists (shared sets of IP addresses, CIDR blocks, or broad geographic areas) used in various Akamai security products such as Kona Site Defender, Web App Protector, and Bot Manager. Along with managing your own lists, you can also access read-only lists that Akamai dynamically updates for you.

For more information about network lists, see the API documentation.

Before you begin

Complete the tasks in Get started. You need to have an API client and a valid akamai.tf configuration file before adding this subprovider

Retrieve network list information

You can obtain information about all the network lists available to you by using the akamai_networklists_network_lists data source and its output_text attribute. To do that, use the following Terraform configuration:

terraform {
 required_providers {
  akamai  = {
   source = "akamai/akamai"
  }
 }
}

provider "akamai" {
 edgerc = "~/.edgerc"
}

data "akamai_networklist_network_lists" "network_lists" {
}

output "network_lists_text" {
 value = data.akamai_networklist_network_lists.network_lists.output_text
}

Create a network list

As noted in the introduction, network lists are collections of device addresses that can be either:

  • Individual IP addresses or CIDR (Class Inter-Domain Routing) addresses. CIDR provides a shortcut way to refer to a block of IP addresses. For example, the CIDR address 192.168.100.0/22 represent the 1,024 IPv4 addresses from 192.168.100.0 through 192.168.103.255.
  • Two-character ISO 3166 country codes (US for the United States, MX for Mexico, etc.). Using country codes provides a way to manage network addresses across a broad geographical area.

These network lists can be used with Akamai products such as Kona Site Defender or Bot Manager, as well as by Terraform resources such as akamai_appsec_ip_geo. That resource enables you to specify the network lists allowed to pass through your IP/Geo firewall and those that are not.

To create a new network list, use a Terraform configuration similar to the following:

terraform {
 required_providers {
  akamai  = {
   source = "akamai/akamai"
  }
 }
}

provider "akamai" {
 edgerc = "~/.edgerc"
}

resource "akamai_networklist_network_list" "network_list" {
 name        = "Documentation Network"
 type        = "IP"
 description = "This is a test network used by the documentation team."
 list        = ["198.51.100.253","198.51.100.254","198.51.100.255"]
 mode        = "APPEND"
}

resource "akamai_networklist_activations" "activation" {
 network_list_id     = akamai_networklist_network_list.network_list.uniqueid
 network             = "STAGING"
 notes               = "This is the staged network for the documentation test network."
 notification_emails = ["gstemp@akamai.com"]
}

Note. The final block in this configuration activates the new network list. We'll ignore that block for now, then return to it in the Activating a Network List section of this documentation.

The Terraform configuration starts by initializing our provider and by providing the authentication credentials. After that, the configuration uses the akamai_networklist_network_list resource and the following block to create the network list:

resource "akamai_networklist_network_list" "network_list" {
 name        = "Documentation Network"
 type        = "IP"
 description = "This is a test network used by the documentation team."
 list        = ["198.51.100.253","198.51.100.254","198.51.100.255"]
 mode        = "REPLACE"
}

The properties used in this block are described in the following table:

ArgumentDescription
nameName of the new network list. Names don't have to be unique: you can have multiple network lists that share the same name. When the list is created it’s issued a unique ID, a value comprised of a numeric prefix and the list name. In some cases, this might be a variation of that name. For example, a list named Documentation Network is given an ID similar to 108970_DOCUMENTATIONNETWORK, with the blank space in the name being removed.)
typeIndicates the type of addresses used on the list. Allowed values are:

IP. For IP/CIDR addresses.
GEO. For ISO 3166 geographic codes.

Note that you can’t mix IP/CIDR addresses and geographic codes on the same list.
descriptionBrief description of the network list.
listArray containing either the IP/CIDR addresses or the geographic codes to be added to the new network list. For example:

list = ["US", "CA", "MX"]

Note that the list value must be formatted as an array even if you are only adding a single item to that list:

list = ["US"]

Note, too that list is the one optional argument available to you: you don't have to include this argument in your configuration. However, leaving out the list argument means that you'll end up creating a network list that has no IP/CIDR addresses or geographic codes (and, as a result, has little practical use).
modeSpecifies whether the addresses/geographic codes on the list should:

Be added to the existing set of addresses (APPEND).
Be removed from the existing set of addresses (REMOVE).
_ Replace the existing set of addresses (REPLACE).

Because we're creating a new network list, there won't _be* an existing set of addresses. Consequently, you can set the mode either to APPEND or to REPLACE.

After you've created your configuration, run the terraform plan command to validate and verify that configuration. Assuming your command succeeds you can then run terraform apply to create the network list. If the apply command is successful, you'll see output that includes the ID (108972_DOCUMENTATIONNETWORK ) of the network list:

akamai_networklist_network_list.network_list: Creation complete after 4s [id=108972_DOCUMENTATIONNETWORK]

Apply complete! Resources: 1 added, 0 changed, 0 destroyed.

Activate a network list

After the network list is created, we use this Terraform block to activate the network:

resource "akamai_networklist_activations" "activation" {
 network_list_id     = akamai_networklist_network_list.network_list.uniqueid
 network             = "STAGING"
 notes               = "This is the staged network for the documentation test network."
 notification_emails = ["gstemp@akamai.com"]
}

This step is optional. You don't have to activate a network immediately after its creation. Instead, you can call the akamai_networklist_activations resource at any time to activate a network. Keep in mind, however, that a network can't be referenced by Akamai products or by other Terraform resources until it's been activated.

Our activation block uses the following arguments:

ArgumentDescription
network_list_idUnique identifier of the network being activated. In this example, akamai_networklist_network_list.network_list.uniqueid represents the ID of the network that we just created. To activate a previously existing network, specify the ID of that network.
networkIndicates which network the list will be activated on. Allowed values are:

STAGING
PRODUCTION

Note that this argument is optional. If not included in your configuration, the network is automatically activated on the staging network.
notesOptional description of the network and information about the activation.
notification_emailsJSON array containing the email addresses of users to be notified when the network activation finishes.

If you both create and activate a network list using a single Terraform configuration, you'll see output similar to the following:

akamai_networklist_network_list.network_list: Creating...
akamai_networklist_network_list.network_list: Creation complete after 4s [id=108970_DOCUMENTATIONNETWORK]
akamai_networklist_activations.activation: Creating...
akamai_networklist_activations.activation: Still creating... [10s elapsed]
akamai_networklist_activations.activation: Still creating... [20s elapsed]
akamai_networklist_activations.activation: Still creating... [30s elapsed]
akamai_networklist_activations.activation: Still creating... [40s elapsed]
akamai_networklist_activations.activation: Still creating... [50s elapsed]
akamai_networklist_activations.activation: Still creating... [1m0s elapsed]
akamai_networklist_activations.activation: Still creating... [1m10s elapsed]
akamai_networklist_activations.activation: Still creating... [1m20s elapsed]
akamai_networklist_activations.activation: Creation complete after 1m23s [id=6697234]

Apply complete! Resources: 2 added, 0 changed, 0 destroyed.

In addition, each user included in the notification_emails argument is emailed an activation notice.

Modify an existing network list

Modifying an existing network list can be tricky, if only because you need to know which Terraform resource modifies which property values. Use the following table to help you determine which resource is the appropriate one to use:

PropertyRecommended resource for modifying the property
nameakamai_networklist_network_list

By default, the network name is included in the network ID. For example, a network named USANetwork will have an ID similar to 110987_USANETWORK. However, if you change the name of the network the network ID will not change. You can change the name USANetwork to HomeNetwork, but the ID for that network ID will still be 110987_USANETWORK.
typeakamai_networklist_network_list

If you change the network type (for example, if you switch from an IP list to a GEO list) you also need to change the list value as well.
descriptionakamai_networklist_description

You can also use the akamai_networklist_network_list resource to change the description.
listakamai_networklist_network_list

Be sure to set the mode to the appropriate operation type (APPEND, REPLACE, REMOVE) when changing the list.
recipientsakamai_networklist_subscription

To have email notifications sent to multiple addresses, separate those addresses by using commas:

["gstemp@akamai.com", "karim.nafir@mail.com"]

For example, this configuration changes the description assigned to the network list named Documentation Network:

terraform {
 required_providers {
  akamai  = {
   source = "akamai/akamai"
  }
 }
}

provider "akamai" {
 edgerc = "~/.edgerc"
}

data "akamai_networklist_network_lists" "network_lists_filter" {
 name = "Documentation Network"
}

resource "akamai_networklist_description" "network_list_description" {
 network_list_id = data.akamai_networklist_network_lists.network_lists_filter.uniqueid
 name            = "Documentation Network"
 description     = "Updated description for the documentation network."
}

And this configuration changes the set of email addresses assigned to that same network list:

terraform {
 required_providers {
  akamai  = {
   source = "akamai/akamai"
  }
 }
}

provider "akamai" {
 edgerc = "~/.edgerc"
}

data "akamai_networklist_network_lists" "network_lists_filter" {
 name = "Documentation Network"
}

resource "akamai_networklist_subscription" "subscribe" {
 network_list = data.akamai_networklist_network_lists.network_lists_filter.list
 recipients   = ["gstemp@akamai.com", "gmstemp@hotmail.com"]
}

Deactivate a network list

To deactivate a network list, remove all the addresses or geographic codes that have been assigned to that list. For example, this Terraform configuration deactivates the network list Documentation Network:

terraform {
 required_providers {
  akamai  = {
   source = "akamai/akamai"
  }
 }
}

provider "akamai" {
 edgerc = "~/.edgerc"
}

data "akamai_networklist_network_lists" "network_lists_filter" {
 name = "Documentation Network"
}

resource "akamai_networklist_network_list" "network_list" {
 name        = "Documentation Network"
 type        = "IP"
 description = "Test network list updated description."
 list        = []
 mode        = "REPLACE"
}

These two lines remove the addresses ore the geographic codes from the list:

list = []
mode = "REPLACE"

The first line sets the list (that is, the collection of device addresses or geographic codes) to an empty array. The second line then specifies that the new, empty list should replace the existing set of addresses/geographic codes. In effect, that removes all the IP addresses/geographic codes from the network list, which, in turn, deactivates that list.

Import a network list

Terraform allows you to add a resource to its state even if this resource was created outside of Terraform,
for example by using the Control Center application. This allows you to keep Terraform's state in sync with
the state of your actual infrastructure. To do this, use the terraform import command with a configuration
file that includes a description of the existing resource. The import command requires that you specify
both the address and ID of the resource. The address indicates the destination to which the resource
should be imported. This is formed by combining the resource type and local name of the resource as described
in the local configuration file, joining them with a period ("."). For example, suppose a nework list has
been created outside of Terraform. You can use the information available in the Control Center to create a
matching description of this policy in your local configuration file. Here is an example, using sample values
for the resource's parameters:

resource "akamai_networklist_network_list" "network_list" {
  name        = "Test-white-list"
  type        = "IP"
  description = "network list description"
  list        = ["198.51.100.0/24","203.0.113.255","233.252.0.0"]
  mode        = "APPEND"
}

The address of this resource is found by combining the resource type and its local name within the
configuration file: "akamai_networklist_network_list.network_list"

The ID indicates the unique identifier for this resource within Terraform's state. The unique identifier
for a network list can be found in the Control Center, and typically is of the form "12345_QWERTY". For this
example, suppose that the network list has been created and given the unique ID "80255_TESTWHITELIST". To
import this resource into your local Terrform state, you would run this command:

$ terraform import akamai_networklist_network_list.network_list 80255_TESTWHITELISTNL