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.
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.
Before you start provisioning thousands of your hostnames, you need to set up a common configuration they'll all share.
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.
These identifiers specify what modules and features you'll be able to use in your property.
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. 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 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 188.8.131.52
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.
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.
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.
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.
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.
Push your updated JSON file back to the property.
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.
Make sure the activation was successful. The response should contain
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.
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
Confirm the customer has correctly validated the certificate by verifying the DNS record exists and has the right value.
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.
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.
Verify if the hostnames are ready for testing and the request completed by checking whether the status for your hostnames is
Make an HTTPS request and verify the response:
$ curl -v https://www.example.com/ --resolve "www.example.com:443:184.108.40.206"
For more details on testing and activation, see Activate a property.
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.