Hostname buckets are BETA
This feature is still in BETA. If you're interested and would like to use hostname buckets now, contact your Akamai account team.
Some products such as Adaptive Media Delivery, IoT Edge Connect Message Store, IoT Edge Connect Message Store, and Akamai Cloud Embed are not supported with hostname buckets yet.
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.
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 and custom), and for HTTP-only delivery.
The hostnames you manage may vary in terms of security requirements. The best practice is to 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 custom 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
- 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 certificates, create a "dummy" Enhanced TLS certificate to obtain a placeholder value for the required
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:
Mac OS, Linux, or Unix:
a1234.dscx.akamaiedge.net. a1234.dscx.akamaiedge.net. 20 IN A 18.104.22.168
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. So, what you'll get in the response varies based 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
hostnameparameter, define a pattern that you'll use for naming your origin hostnames. For example, prepend
origin-and append the
.saas.comdomain to the property hostname, for which you'll use the built-in variable. Example:
If you set
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 to the property configuration.
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
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 certificates only
This step applies only if you're provisioning hostnames using default certificates. In the case of custom 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
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
6 - Test the activated hostname
Make an HTTPS request and verify the response:
$ curl -v https://www.example.com/ --resolve "www.example.com:443:22.214.171.124"
7 - Go live
Instruct your customer to redirect traffic to Akamai by deleting the existing CNAME record and adding 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.