Giters

joshjohnson / cli-property-manager

Geek Repo:Geek Repo

Github PK Tool:Github PK Tool

Akamai Property Manager CLI

Overview

The Property Manager CLI lets you make configuration changes locally and automate the deployment of Akamai property changes across one or many local environments. It comes with these commands:

  • akamai property-manager. Use to edit Property Manager configurations locally for an existing property.

  • akamai pipeline. Use to make changes within an automated pipeline of two or more environments.

See Workflows for more information.

With this client-side application, you can:

  • Better manage updates to your properties. You can create local client side templates, or snippets, for different parts of your property configuration, like rules or behaviors. Different teams within your organization can own specific snippets and make Property Manager changes both independently of and in parallel with other teams. Managing your properties this way can help minimize merge conflicts

  • Automate a pipeline. With Akamai Pipeline you can create a chain of environments that suit your organization's specific needs. A typical pipeline starts with one to many development and test environments and completes when the code reaches your production environment.

  • Validate. This CLI uses Property Manager validation before deploying changes.

  • Customize variable definitions between environments. If you want a use one variable value in a development environment and try out a different value in a test environment, you can add a custom variable to your Property Manager CLI template files.

Available commands

Want to see all available CLI commands? See this help for Property Manager CLI commands and this help for Akamai Pipeline commands.

Stay up to date

To make sure you always use the latest version of the CLI, run this command: akamai update property-manager

Concepts

To learn more about the concepts behind this CLI and the Property Manager API (PAPI), see the PAPI Overview section.

Workflows

With this CLI, you’ll likely use one of these common workflows:

  • Property management with snippets. Use this workflow to make local configuration changes for one property, enable different teams to own different parts of the configuration, and deploy without interdependencies.

  • Akamai Pipeline. Use this workflow to both set up configuration templates and create an automated pipeline for deploying Property Manager changes to your various environments.

Property management with snippets workflow

Here’s a typical workflow when you want to break your Property Manager configuration into separate rules-based snippets:

  1. Make some decisions:

    • Do you want to import an existing property in Property Manager locally, create a new property from scratch, or use an existing template?

    • How do you want to divide up the configuration? By default, a separate snippet is created for each top level rule in your configuration. You can add, remove, or modify snippets.

    • Do you need any new supporting processes?

  2. Typically, you’ll want to import an existing property, so run the akamai property-manager import command to create a local instance of your configuration.

  3. Verify that the /config-snippets folder contains a separate JSON-based configuration snippet for each rule in your property configuration.
    Within this folder, the main.json file ties all the snippets together: It lists the available snippets and contains the local permissions for each snippet.

  4. Edit the snippets as needed to reflect the rule changes you want to deploy.
    If another team owns a snippet, once they make their changes locally, they can copy it into the /config-snippets folder.

  5. Run the akamai property-manager activate command to activate the property. This command syncs the local changes in your /config-snippets directory to the Akamai network. Once activation is complete, you can verify changes in the Property Manager UI.

Akamai Pipeline workflow

Here’s a typical workflow for using Akamai Pipeline once you install and configure the CLI:

  1. Make some decisions:

    • Do you want to use an existing property or a specific product as a template for your pipeline?

    • Which environments to you want to include?

    • What do you want to call your pipeline?

  2. Create a new pipeline based on your decisions. If you’re using an existing property as a template, you’ll need the property ID or name. If you’re using a product as a template, you’ll need account information, like contract ID. The CLI includes commands for retrieving account-specific IDs.

    Note: The new pipeline adds one new Akamai property for each environment. The naming convention of the property is <environment_name>.<pipeline_name>.

  3. In the pipeline’s environments folder, edit the variableDefinitions.json file to define and reflect the attributes shared across the pipeline.

  4. In the folders created for each environment, edit the variables.json file to reflect the settings specific to that environment.

  5. In the templates folder, make your desired code change in the JSON-based configuration snippets.

  6. Promote the change to the first environment. Promoting saves and activates your change, and propagates it to the next environment in your pipeline.

  7. Verify that the change was successfully promoted to the first environment, and test the change.

  8. Complete steps 6 and 7 for each additional environment in the pipeline.

Get started

In order to start using Akamai Pipeline, you have to complete these tasks:

  • Verify you have a Unix-like shell environment, like those available with Mac OS X, Linux, and similar operating systems.

  • Set up your credential files as described in Get Started with APIs, and include authorization for the Property Manager API.

  • Install the Akamai CLI tool. Before starting this installation, verify that your .edgerc file contains a token in the [papi] section.

  • Install Node Version Manager (NVM), which lets you run applications with different node version requirements side by side.

  • Install Node.js version 8.0 Long Term Support (LTS).

Install the Akamai Property Manager CLI

You use the Akamai CLI tool to install the code. Here’s how:

  1. Create a project folder under your user home directory: mkdir <folder_name>. For example: mkdir akamai_pipeline.
    You’ll run Property Manager CLI commands from this folder, which also contains the default values for the CLI and a separate subdirectory for each pipeline you create.

  2. Run the installation command: akamai install property-manager

  3. Verify that the CLI is set up for your OPEN API permissions:

    1. Run this command to return the list of contracts you have access to: akamai property-manager list-contracts

    2. Verify that the list of contracts returned is accurate for your access level.

  4. Continue by either creating snippets for property management or setting up a new pipeline.

Set up property snippets

Create your local client side snippets to let different teams own different parts of your property configuration.

Create snippets of your Property Manager configuration

  1. Select which property configuration you want to create a local instance of.

  2. Determine how to handle any custom user variables.

  3. Run the akamai property-manager import command to create a local instance of your Property Manager configuration.

  4. In your project directory structure, navigate to the new config-snippets folder.
    This folder contains a separate JSON-based configuration snippet for each rule in your property configuration.

  5. Verify the folder structure, which will look something like this:

     project_name/
     /config-snippets
         main.json
         compression.json
         static.json
 		cloudlets.json
         ...

    Each snippet represents one of the property's child rules.

  6. If needed, add or edit snippets to support your organization's development structure.
    Say, for example, you have a cloudlets.json snippet that only includes Edge Redirector. Since Marketing maintains this Cloudlet, you'll change the filename to mkt-EdgeRedirect.json to note the owner and the application the rule is for.

  7. Open the main.json file, which corresponds to the property's default rule, edit the rule values as needed, and update the children array to reflect any snippet name changes, additions, or deletions.

  8. If required, set up local permissions for each JSON snippet.

  9. Run the akamai property-manager activate command to activate your changes.
    It's a good practice to test your changes before activating on production.

  10. If you'd like, verify your changes in the Property Manager UI.

Add a new snippet

If you want to add a new snippet to your property configuration:

  1. Create a JSON file for the new snippet that represents a Property Manager rule, including any child rules.
    For example:

    {
	"name": "Catalog",
	"children": [],
	"behaviors": [
		{
			"name": "timeout",
			"options": {
				"value": "5s"
			} } ],
	"criteria": [
		{
			"name": "path",
			"options": {
				"matchOperator": "MATCHES_ONE_OF",
				"values": [
					"/catalog/*"
				],
				"matchCaseSensitive": false
			} } ],
	"criteriaMustSatisfy": "all"
}

  2. Open the main.json file.

  3. Add the snippet to the children object:

    "rules": {
		"name": "default",
		"children": [
			"#include:Cache_extensions.json",
			"#include:Catalog.json",
			"#include:Furniture.json",
		    "#include:Clothing.json",
			],
		"Behaviors": [ 
		…
		… ],
		}

  4. Save your changes.

  5. Run the akamai property-manager activate command to activate your changes.

Create and set up a new pipeline

You can use the CLI to create a new pipeline. Before creating any type of pipeline, you’ll need the names of two or more environments that you want to include. If you're using a product as a template, you'll also need group, product, and contract IDs. If you're using a property as a template, you'll need either the property name or ID.

Note: You only have to create a pipeline once.

Create a new pipeline

To create a new pipeline:

  1. If you need to, retrieve and store the contract, group, and product IDs for your pipeline:

    1. Run this command to list contract IDs (contractId): akamai pipeline list-contracts

    2. Run this command to list group IDs (groupId): akamai pipeline list-groups

    3. Run this command to list product IDs (productId): akamai pipeline list-products -c

    Note: The IDs returned depend on the permissions associated with your username.

  2. Determine which environments you want to include in your pipeline, and what you want to name them. The environment names you choose are used in the pipeline’s directory structure.

  3. Choose a descriptive name for your pipeline.
    The pipeline name is added as a suffix to each property created for your new pipeline. Because of this, make sure the name you choose won’t result in any duplicate property names for the account. So, if your pipeline is example.com, and your environments are dev, qa, and www, the new properties will be dev.example.com, qa.example.com, and www.example.com.

  4. If creating a pipeline using a specific product as a template, run this command:
    akamai pipeline new-pipeline -c -g -d -p

    For example, if you want to base your pipeline on Ion, you'd enter a command like this: akamai pipeline new-pipeline -c 1-23ABC -g 12345 -d SPM -p MyPipeline123 qa prod

  5. If creating a pipeline using an existing property as a template:

    1. Determine how to handle any custom user variables.

    2. Run this command:
      akamai pipeline new-pipeline -p -e <environment1_name environment2_name...>

    For example: akamai pipeline new-pipeline -p MyPipeline123 -e 123 qa prod

  6. Verify the pipeline folder structure, which will look something like this:

        pipeline_name/
        projectInfo.json
        /cache
        /dist
        /environments
            variableDefinitions.json
            /environment1_name
                envInfo.json
                hostnames.json
                variables.json
                ...
           /environment2_name
                envInfo.json
                hostnames.json
                variables.json
                ...
               
        /templates
            main.json
            compression.json
            ...
            static.json

  7. Edit variableDefinitions.json to declare variables that you can use in any of the templates.
    See Update the variableDefinitions.json file for details.

  8. In each environment-specific subdirectory under the /environments folder, edit these JSON files:

File Description
hostnames.json Contains a list of hostname objects for this environment.
If the edgeHostnameId is null, the CLI creates edge hostnames for you. If you want to use an existing edge hostname, set both the cnameTo and edgeHostnameId values accordingly.
variables.json After editing your variableDefinitions.json file, update this file with the actual values for the environment, like content provider (CP) code, origin hostnames, and any additional variables you added.
Note: The CLI throws errors if there is a discrepancy between this file and the environment’s variableDefinitions.json file. For example, an error would occur if there’s a variable in the variables.json file that isn’t declared in the variableDefinitions.json file.

Update the variableDefinitions file

Update variableDefinitions.json to declare variables that you can use in any of the templates.

As a general rule:

If an attribute has... Then...
the same value across all environments and is already in the variableDefinitions.json file. Provide the default value in variableDefinitions.json.
Note: You can still override the default value in an environment’s variables.json file.
different values across environments and is already in the variableDefinitions.json file. Set the default to null in variableDefinitions.json and add the environment-specific value to each variables.json file.
different values across environments and does not exist in the variableDefinitions.json file.
  1. Parameterize it inside your template snippets using “${env.<variableName>}"
    For example: "ttl": “${env.ttl}"
  2. Add it to variableDefinitions.json and set it to null. You can set the type to anything you choose.
  3. Add it to your environment-specific variables.json files and set the individual values.

Common product IDs

If creating a new pipeline based on a product template, you’ll need to know your product ID. Here are some of the more commonly-used ones:

Product Code
Ion SPM
Dynamic Site Accelerator Site_Accel
Rich Media Accelerator Rich_Media_Accel
Web Application Accelerator Web_App_Accel

If you don’t see your product code, run this command to return the product IDs available for your account: akamai pipeline list-products -c <contractId>

Save and promote changes through the pipeline

Once you make changes to your pipeline, you can save and promote those changes to all environments in your pipeline.

To save and promote changes:

  1. Make your configuration change within the desired snippet inside your templates folder. This folder contains JSON snippets for the top-level rules in your property’s configuration.

  2. Optionally, update the property files to reflect your changes without saving to Property Manager: akamai pipeline merge -p <environment_name>

  3. Save your changes, validate your configuration, and create a new property version: akamai pipeline save -p <environment_name>

  4. Promote the change to the first environment in your pipeline: akamai pipeline promote -p -n <environment_name> <notification_emails>.

    The <network> value corresponds to Akamai’s staging and production networks. You can enter STAGING or PROD for this value. For example: akamai pipeline promote -p MyPipeline123 -n STAGING qa jsmith@example.com

    When run, promote merges the template and variables files, saves any changes to Property Manager, and activates the property version on the selected Akamai network.

  5. Once the activation is complete, run the following command to make sure the pipeline reflects the latest activation status: akamai pipeline check-promotion-status <environment_name>

    Note: You should receive an email once activation is complete. Activation times vary, so you may want to wait several minutes before attempting to run this command.

  6. Repeat steps 2 through 5 until you promote your changes to all environments in the pipeline.

  7. Verify that the updates made it to all environments in the pipeline: akamai pipeline lstat -p

How you can use this CLI

Here are some ways you can use the Property Manager CLI to meet your business needs.

Retrieving the latest version of the property from Property Manager

If people in your organization also use the Property Manager UI to update your Akamai properties, you may need to make sure your client side files are in sync with the latest version of the property.

To retrieve all updates from the latest property version:

  1. Activate any local changes you want to implement by running the akamai property-manager activate command.

  2. Run this command: akamai property-manager update-local -p <property_name>.
    The update-local command overrides any locally-saved configuration version with the latest active property version.

Retrieving a specific rule from Property Manager

You may want to manually retrieve the new rules from the Property Manager UI without updating all of your local snippets.

To get the JSON syntax for these rules, open the property version in the Property Manager application, select a rule, and click View Rule JSON to display the syntax. You can then copy the JSON and create a new snippet for the rule.

Using Property Manager user variables

Some Property Manager behaviors, like Origin Server origin, let you define custom user variables for certain settings.

Before using a property as a template for a pipeline or a local property configuration, see whether it contains custom variables. If it does, review these custom variables in the Property Manager application and adjust as needed. When you’re finally ready to run the command to create the pipeline or local configuration, use the --variable-mode user-var-value option with one of these values:

  • user-var-value. Creates local versions of the custom variables that the CLI can use.

  • no-var. Does not create local versions of the custom variables.

If you’re creating a new property from scratch, you can also use the default value, which replaces parts of the template configuration, like the origin behavior, with Property Manager’s default settings.

If you've already created a pipeline and want declare a new user variable, you can revise the ../environments/variableDefinitions.json and ../environments/{environment}/variables.json files using the syntax for Property Manager variables.

Using attributes that vary across environments with Akamai Pipeline

Property Manager CLI is a client-only library. With it you can tokenize any attribute in your configuration and have different values for that attribute in each environment.

Say you want a behavior enabled on one of your three environments for testing purposes. How can you set this up for your pipeline?

Many behaviors have a boolean enabled field, which is essentially an on/off switch. Here’s an example for the Forward Rewrite Cloudlet:

{
  "name": "forwardRewrite",
  "options": {
    "enabled": true,
    "cloudletPolicy": {
      "id": 12345,
      "name": "some policy name"
    }
  }
}

We need to change the value of enabled to a variable. We'll do this in a few steps:

  1. Pick a variable name, like forwardRewriteEnabled, and add it to the variableDefinitions.json file:

    {
    "definitions": {
        "forwardRewriteEnabled": {
            "type": "boolean",
            "default": true
        },
...
   }
}

  2. In the variables.json file for each environment, add a new JSON variable with a valid value. In this example, the variable needs a boolean value.

    {
"forwardRewriteEnabled": false,
...
}

  3. In the templates folder, update the JSON file containing the Forward Rewrite behavior by replacing the boolean value with the variable expression using the env prefix:

  4. In the templates folder, open the JSON file containing the Forward Rewrite behavior.

  5. Replace the boolean value with the variable expression using the env prefix, which represents the current environment:

    {
  "name": "forwardRewrite",
  "options": {
    "enabled": "${env.forwardRewriteEnabled}", //notice type string!
    "cloudletPolicy": {
      "id": 12345,
      "name": "some policy name"
    }
  }
}

  6. Merge, save, and promote your change as needed.

Working with edge hostnames

The Property Manager CLI lets you work with Standard Transport Layer Security (TLS), Enhanced TLS, and shared certificate edge hostnames.

Creating edge hostnames

With this CLI, you can create Standard Transport Layer Security (TLS), Enhanced TLS, and shared certificate edge hostnames.

When you first create a pipeline, it sets up a directory structure that includes JSON templates for each environment in the pipeline.

To create an edge hostname, follow these steps:

  1. In the hostname.json template file, make sure the edgeHostnameId is set to null. It's null by default.

  2. Check the entry in the cnameTo field. It needs to be brand new and have the correct domain suffix. If the cnameTo already exists, you'll be reusing an edge hostname, not creating one.

  3. If you want to create an edge hostname that is secure, you'll also have to add an enrollment ID to the hostname.json file:

    1. Retrieve the enrollment-id from the CPS CLI.

    2. Add a certEnrollmentId member to the hostname.json file and enter the enrollment-id as the value.

  4. Run the akamai pipeline save command.

When you run the command the CLI will save your pipeline, validate its configuration, and create edge hostnames for you.

Here's an example of what the entry in the hostname.json file might look like before you run the akamai pipeline save command:

   [
		{
			"cnameFrom": "www.example-1.com",
			"cnameTo": "www.example-1.edgekey.net",
			"certEnrollmentId": "12356666",
			"cnameType": "EDGE_HOSTNAME",
			"edgeHostnameId": null
		}
	]

Reusing edge hostnames

To reuse an edge hostname with your pipeline, simply add the existing edge hostname to your hostnames.json file. You can also create a new edge hostname in Property Manager and add it to your hostnames.json file.

You can view a list of your existing available edge hostnames by using this command: akamai property-manager list-edgehostnames -c <contractId> -g <groupId>

Using multiple edge hostnames

If you want to use multiple edge hostnames with any environment in your pipeline, you can modify the hostnames.json file like this:

[
	{
		"cnameFrom": "www.example.com",
		"cnameTo": "www.example.edgesuite.net",
		"cnameType": "EDGE_HOSTNAME",
		"edgeHostnameId": 343477
	},
	{
		"cnameFrom": "www.example-1.com",
		"cnameTo": "www.example-1.edgekey.net",
		"certEnrollmentId": "12356666",
		"cnameType": "EDGE_HOSTNAME",
		"edgeHostnameId": 224488
	}
]

When entering the cnameTo value, remember to use the correct domain suffix.

When you run the akamai pipeline save command, the CLI will create edge hostnames for each block, or find the right block if the edge hostname already exists for the environment.

Domain suffixes for edge hostnames

Each type of edge hostname has its own domain suffix. Knowing which one to use is important when setting the cnameTo value:

Edge hostname type Domain suffix Additional tasks
Enhanced TLS edgekey.net

Include the enrollment ID:

  1. Retrieve the enrollment-id from the CPS CLI
  2. Enter the ID as the certEnrollmentId value.
Standard TLS edgesuite.net Not applicable.
shared certificate akamaized.net Not applicable.

Working with advanced behaviors

Does the property you want to use as an Akamai Pipeline template include advanced behaviors? If so, you'll need to convert all advanced behaviors to custom behaviors before creating the pipeline. See Custom Behaviors for PAPI for more information.

With this CLI, you can use advanced and custom behaviors with local instances of properties you create as long as you don’t modify them.

Known issues

When creating a pipeline using an existing property as a template, verify that the new property includes a valid content provider (CP) code in the cpCode object.

If the template property doesn't have a CP code, the CLI automatically adds INPUT_CPCODE_ID as the id. If you do not replace this placeholder ID with a valid CP code, your pipeline will not work as expected.

Note: If needed, you can use PAPI to create a new CP code.

Notice

Your use of Akamai's products and services is subject to the terms and provisions outlined in Akamai's legal policies.

About

License:Apache License 2.0

Languages

Language:JavaScript 100.0%Language:Shell 0.0%