Akamai Property

This page provides reference information about how bossman commands relate to Akamai Property management.

Resource Configuration

resources:
  - module: bossman.plugins.akamai.property
    pattern: akamai/property/{name}
    options:
      edgerc: ~/.edgerc
      section: default
      #env_prefix: ""
      #account_key: xyz

The above are the default values, applied even if the .bossman configuration file is not present. You only need to configure if you need to depart from the defaults.

With these defaults, Bossman will look for folders under akamai/property and treat them as Akamai Property configurations. The {name} placeholder is required and defines the name of the property to be managed.

The next section details the structure of the resource, the files Bossman expects to find within the property configuration folder.

It is also possible to pass values from the environment. Supported variables include:

• EDGERC : path to the edgerc file

• EDGERC_SECTION : section within the edgerc file

• EDGERC_SWITCH_KEY : account switch key, if applicable

Values passed from the environment take precedence over the configuration file if specified.

If multiple resource groups are present and require different credentials, it is possible to specify env_prefix in the configuration file. For example, if you have this configuration:

resources:
  - module: bossman.plugins.akamai.property
    pattern: akamai/property/prod/{name}
    options:
      edgerc: ~/.edgerc
      env_prefix: PROD_
  - module: bossman.plugins.akamai.property
    pattern: akamai/property/preprod/{name}
    options:
      edgerc: ~/.edgerc
      env_prefix: PREPROD_

You can specify a different section (or even a different config file or switch key) like this:

PROD_EDGERC_SECTION=prod PREPROD_EDGERC_SECTION=preprod bossman status

The switch key can also be specified as part of an .edgerc section:

[example]
client_token = xxxx
client_secret = xxxx
auth_token = xxxxx
host = xxxx
account_key = B-C-1ED34DK:1-8BYUX

The order of precedence for the switch key is environment, .bossman config file, and finally .edgerc.

Resource Structure

An Akamai property is composed of two files:

• hostnames.json with the host -> edgehostname mapping information

• rules.json with the CDN delivery configuration rule tree to apply

Both files are completely standard as per the documented schemas and can be used independently of Bossman through regular API calls or other automation tools.

Bossman imposes the presence of top-level fields in rules.json which are not required by the schema:

• productId

• ruleFormat

• groupId

• contractId

productId and ruleFormat are required so that Bossman can accurately validate and version freeze property versions when they are deployed.

groupId and contractId are required so that Bossman has enough information to create new properties in the appropriate location.

bossman status [-e|--exact-match] [glob*]

The status command displays details about interesting property versions.

Interesting property versions are either:

• activating, or pending activation on any network

• the latest version

• a deployed version of the HEAD commit of the current branch (what you’re currently working on)

• deployed versions of any HEAD commit of any branch not merged into the current branch (other work in progress)

In the normal case, property versions are created by bossman and their status line shows:

• the property version

• STG, PRD or STG,PRD depending on the activation status (if they are pending activation to staging or production, the network trigram is followed by an hourglass)

• a 💥 icon if the version has validation errors

  • that this icon should normally never be visible alongside an activation indicator (STG,PRD)

  • this indicator relies on information stored in git at apply time (for performance). This means that a 🛑 dirty version will not show validation errors

• the first line of the property version notes, truncated to 40 characters

• a series of git refs to the corresponding commit, coloured green if the version corresponds to the latest commit on that branch, or brown if it is behind; the refs shown are:

  • the shortened git commit id

  • a relative ref to from the current branch (e.g. main~3) if the commit is reachable (merged)

  • a ref to every branch (merged or not) whose HEAD points at the commit

• a series of tags pointing at the corresponding commit, coloured blue

To illustrate:

See Making changes in the UI for more details about handling dirty versions.

bossman apply [--force] [--dry-run] [--since=commit] [-e|--exact-match] [glob*]

The apply command creates a new version for every commit on the current branch.

If the property does not exist, it is created.

The productId and ruleFormat fields specified in the rules.json file are used to freeze the property version to a specific schema version.

If the property version has validation errors, apply will succeed but a 💥 icon will be displayed, along with a list of errors as reported by the PAPI endpoint:

If bossman detects that the latest version of the property is 🛑 dirty, it will skip applying unless the --force flag is also provided.

Bossman structures property version notes, by encoding:

• the commit message

• metadata about the commit, including

  • the abbreviated commit hash

  • the branches containing the commit

  • the author

  • if applicable, the committer

The purpose is threefold.

• It improves the quality of property version notes; if a good git commit message convention is in place, it is automatically applied to the property version;

• The author(s) of the change are referenced clearly, which helps because API calls do not record this information in a legible way in the regular Author field;

• It provides a mechanism for bossman to correlate property versions with git revisions

bossman (pre)release [--rev HEAD] [-e|--exact-match] [glob*]

prerelease : activates the selected revision and resources to the staging network

release : the same, to the production network

If the property version has validation errors, activation is disallowed:

Acivation notes & notifications

When Bossman triggers an activation, it automatically adds the following emails to the email notification list:

• the author of the commit being released

• the committer of the commi being released, if different from the auhor

• the currently configured git user

It also formats the activation notes to look like this:

activation of 6d4fcb37 (R41) by jane.doe@acme.org using bossman 0.25.0

Where

• 6d4fcb37 is the abbreviated commit hash being released

• R41 is a list of tags pointing at the commit

• jane.doe@acme.org is the current git user email

Making changes in the UI

It is entirely acceptable to create new versions in the UI without breaking bossman. If an interesting version was created without using bossman, it will be called out as dirty, and will lack any git ref information to relate it to git history :

There are two caveats however:

• bossman will not be able to activate these versions - indeed, bossman concerns itself with the deployment and release cycle of git commits. By definition, a dirty version is not associated to a commit, and is therefore “out of band”; the recommended approach is then to re-integrate the change into the code

• bossman cannot help with reintegration of changes from dirty versions - this needs to be done manually and the method will depend largely on how the configurations are maintained as code.

These aspects are by design and unlikely to change. Bossman acknowledges the need to make occasional changes in the UI, but if it is the primary workflow, then maybe bossman is not the best choice.