Hostname buckets are primarily intended for SaaS/PaaS providers who frequently add and remove thousands of custom domain hostnames. With buckets enabled, hostnames are tied directly to the property, so you can add and automatically activate up to a thousand property hostnames with a single PAPI operation without incrementing the property version. You can safely make changes to the configuration logic and roll them back without the risk of accidentally removing hostnames and disturbing the traffic to your sites.

You may want to create multiple hostname bucket properties if you have various types of application instances with different delivery needs.

🚧

Hostname Buckets and Adaptive Media Delivery

Currently, Hostname Buckets are not supported with Adaptive Media Delivery (AMD) properties.

Before you begin

Make sure you get these things done before you start with this workflow.

• Set up authentication. To make calls through the various ​Akamai​ APIs available for this workflow, you need to authenticate using tokens you generate and apply in requests from your API client tool. Ensure that your authentication is set up for READ/WRITE access to PAPI. For Enhanced TLS certificates, you'll also need an access to the Certificate Provisioning System (CPS) API.

• Make sure you have write access to your DNS server. You'll need to modify DNS zones, origin servers and records during the process.

Prepare the hostname bucket

Before you start provisioning thousands of your hostnames, you need to set up a common configuration they'll all share.

1 - Set up a DNS zone for your origin hostnames

On your DNS server, set up a DNS zone to manage the origin hostnames. Typically, you'll need a separate origin hostname for each property hostname you add to the bucket.

You can also use Akamai Edge DNS API for that purpose.

2 - Get contracts, groups, and products

These identifiers specify what modules and features you'll be able to use in your property.

3 - Create an edge hostname

An edge hostname is used to process the request between a client and the ​​Akamai​ edge network. This step is required for both certificate types (Default Domain Validation (DV) and CPS-managed), and for HTTP-only delivery.

The hostnames you manage may vary in terms of security requirements. As best practice, set up a single edge hostname, CP code, and property for all the hostnames in the bucket that share the same security level, either Standard or Enhanced TLS.

To be able to create an Enhanced TLS edge hostname, first obtain a certificate enrollment ID.

• If you have an existing CPS-managed Enhanced TLS edge certificate, run the Certificate Provisioning System API's list enrollments operation. Choose the appropriate Enhanced TLS enrollment, strip the leading path expression from its location member, and use that value for the certEnrollmentId parameter.
• If you don't have an Enhanced TLS edge certificate, create one with the CPS API. Even if you want to proceed using the Default DV certificates, create a "dummy" Enhanced TLS certificate to obtain a placeholder value for the required certEnrollmentId parameter.

If you'd like to test whether the edge hostname exists, look it up in the DNS. For example, let's assume you set up a Standard TLS edge hostname:

Windows:

nslookup standardtls.saas.com.edgekey.net

Mac OS, Linux, or Unix:

dig standardtls.saas.com.edgekey.net

Sample response:

a1234.dscx.akamaiedge.net.
a1234.dscx.akamaiedge.net. 20	IN	A	1.2.3.4

4 - Create a CP code

You just need a single CP code for all the hostnames you add to the bucket. CP codes track any web traffic handled by edge servers. Each property’s default rule needs a valid CP code to bill and report for the service.

If you already have one, you can reuse an existing CP code.

5 - Create a hostname bucket property

Think of a property as a container for your product configuration. Create one to control how your content is delivered. Set "useHostnameBucket": true to easily manage over thousands of hostnames in your property without incrementing property versions.

6 - Get the rule tree

Get the baseline of your property's rule tree. It includes all of the default rules and behaviors that ​Akamai​ adds. What you'll get in the response varies depending on your ​Akamai​ product.

7 - Edit the rule tree

Provide necessary details for the top-level default rule. At a minimum, configure these mandatory behaviors in a rule:

• origin. In the hostname parameter, define a pattern that you'll use for naming your origin hostnames. For example, prepend origin- and append the .saas.com domain to the property hostname, for which you'll use the built-in variable. Example: origin-{{builtin.AK_HOST}}.saas.com.
  If you set SAAS_​DYNAMIC_​ORIGIN as your originType, you can use other parts of the request to identify the origin in your pattern, such as cookie, path or query string.
• cpCode. CP codes track any web traffic handled by edge servers. Set the behavior using the CP code you created in step 4.

You can optionally include any number of your own rules to customize content delivery. Rule trees are maintained in a special form of JSON that you can best edit and validate in the dedicated VS code or Eclipse IDE plugins.

8 - Validate the rule tree changes

Make sure your JSON file is correct and complete before deploying it on edge servers. You need to resolve returned errors, as they block an activation, but you can activate a property version that yields less severe warnings. For more information, see Rule tree errors and warnings. Both VS code and Eclipse plugins support full rule tree validation.

9 - Update the property's rule tree

Push your updated JSON file back to the property.

10 - Activate the property on staging and production

With brand new setups, you only need to test your configuration on production. But, you can activate your property on both networks at the same time.

11 - Confirm activation

Make sure the activation was successful. The response should contain "status": ACTIVE.

Provision the hostnames

Whenever you want to onboard a new site for your customer, you add a hostname to the bucket you've just created, test it, and tell your customers to point the traffic to the edge server.

1 - Calculate the domain validation challenges

📘

Default DV certificates only

This step applies only if you're provisioning hostnames using Default DV certificates. In the case of CPS-managed certificates, domain validation is performed earlier, as a part of the CPS flow. See developer documentation for CPS for details.

Run the POST operation to generate the certificate domain validation challenge ahead of time.

The response includes the validationCname object. Hand it out to the customer whose site you're onboarding with the instructions to create a new CNAME record in their DNS configuration and map the hostname to the target.

2 - Verify the hostname certificate deployment

Confirm the customer has correctly validated the certificate by verifying the DNS record exists and has the right value.

3 - Create an origin hostname

On your end, in the DNS zone you set up in step 1, create the origin hostname for the site you're onboarding using the pattern you defined in step 7. Map that origin hostname to the IP address of the application instance you created for your customer's site.

4 - Add hostnames to the hostname bucket

Run the PATCH operation, including all the hostname details in the add array. You can add up to 1000 custom domain hostnames with a single request, total of 100,000 within a single property. Reuse the edge hostname you created in step 4 for all the hostnames that share the same security level, either Standard TLS or Enhanced TLS.

Once you add (or remove) hostnames, they are activated automatically. There is no separate activation step for certificate domain validation.

5 - Confirm the hostnames activation

Verify if the hostnames are ready for testing and the request completed by checking whether the status for your hostnames is ACTIVE.

6 - Test the activated hostname

Make an HTTPS request and verify the response:

$ curl -v https://www.example.com/ --resolve "www.example.com:443:1.2.3.4"

For more details on testing and activation, see Activate a property.

7 - Go live

Instruct your customer to redirect traffic to ​Akamai​ by replacing the existing CNAME record with a new one, setting its value to the ​Akamai​​ edge hostname.

You can pass the ​Akamai​ edge hostnames directly to your customers, or alternatively create intermediary CNAMEs on your own domain and pass those to your customers.