Architecture
Library First
Regardless of which language you choose, all functionality should be implemented as a stand-alone library which can be used independently of the CLI.
Choosing a Language
We recommend using one of the following languages:
Language | Runtime | Binary Support |
---|---|---|
Golang | None | Yes, statically compiled for most platforms |
Python | Yes, available by default on most *Nix systems, issues with Python 2 vs 3 | No |
JavaScript | Node.js (optional) | Yes, for common platforms |
Note: All binaries must be code signed to work on restricted environments.
Dependency Management
Akamai CLI will automatically install dependencies when possible. It currently supports the following package managers:
Language | Package Manager | Expected Files | Notes |
---|---|---|---|
Golang | glide | glide.lock | |
Python | npm or yarn | package.json / yarn.lock | |
JavaScript | pip | requirements.txt | If a yarn.lock file exists, Yarn is used, otherwise npm is used |
PHP | composer | composer.json | Will use composer.lock if it exists |
Ruby | bundler | Gemfile |
If you are not using one of these package managers, then you must vendor all dependencies in your repository.
Credentials
See the Akamai Style Guide for details.
Caching
In order to make the CLI as responsive as possible, you should cache as much as possible — in particular, API requests. Akamai CLI exports the AKAMAI_CLI_CACHE_PATH
environment variable with the current location of the cache directory. Packages should use the following directory structure for caching:
- API responses should be stored using the endpoint path. Due to the way permissions can affect responses, they must be stored in a sub-directory for each credentials section:
$AKAMAI_CLI_CACHE_PATH/api/<Edgerc section>/<API URL path>
- Package specific caching should be placed under a package specific sub-directory:
$AKAMAI_CLI_CACHE_PATH/package/<package name>
Configuration
Akamai CLI maintains a configuration file in $AKAMAI_CLI_HOME/config
. The configuration file is in INI format.
Packages should add their own configuration under a section named after the package, e.g.:
[purge]
network = "staging"
Keys should be human-readable and use hyphens (-)
to separate words.
Note: the [cli]
section should be considered reserved for Akamai CLI, no other package may modify that section.
All configuration variables are made available via the environment as AKAMAI_CLI_{SECTION}_{KEY_NAME}
, with hyphens replaced with underscores (_)
.
Package Metadata
You must include a cli.json
file to inform Akamai CLI about the package and it’s included commands.
cli.json
allows you specify the command language runtime version, as well as define all commands included in package.
Format
requirements
— specify runtime requirements. You may specify a minimum version number or use * for any version. Possible requirements are:go
php
ruby
node
python
commands
— An array of commands included in the packagename
— The command name (used as the executable name)aliases
— An array of aliases that can be used to invoke the command (optional)version
— The command versiondescription
— A short description of the commandbin
— A url to fetch a binary package from if it cannot be installed from source (optional)
The bin
URL may contain the following placeholders:
{{.Version}}
— The command version{{.Name}}
— The command name{{.OS}}
— The current operating system- Possible values are:
windows
,mac
, orlinux
- Possible values are:
{{.Arch}}
— The current OS architecture- Possible values are:
386
,amd64
- Possible values are:
{{.BinSuffix}}
— The binary suffix for the current OS- Possible values are:
.exe
for windows
Example
{
"requirements": {
"go": "1.8.0"
},
"commands": [
{
"name": "purge",
"version": "0.1.0",
"description": "Purge content from the Edge",
"bin": "https://github.com/akamai/cli-purge/releases/download//akamai--"
}
]
}
Releases
Akamai CLI uses git
as it's primary mechanism for retrieving a package for installation.
Version Control
Due to the use of git, you must ensure that the primary
branch is usable at all times. This is the code that the package will run.
This means that all development should occur in feature or version branches:
Each release should be tagged with a version number, and release notes should be added using Github’s Releases feature:
Binaries
In addition to running from source code, Akamai CLI can fall back to using a pre-compiled binary instead. This ability means that for languages that support it, the language runtime is not a requirement.
If you plan to release binaries, they should be attached to the Github release. Akamai CLI will automatically find the latest release and download those binaries. Binaries will be downloaded using the URL indicated in the packages cli.json
by the bin
key (see: Package Metatadata).
Binary Signing & Signature Files
Every binary file must be accompanied by a file of the same name with a .sig
suffix that contains (only) the sha256 checksum for the file.
Akamai CLI will automatically verify that the signatures match when downloading.
Note: this is not a security feature, it only ensures that the binary file is not corrupt.
In addition, to ensure that the binaries can run on macOS and Windows platforms you should also use Code Signing to ensure that restricted environments will be able to execute the binary.
Updating
When akamai
update [package]
is called, the latest version of the primary
branch is checked out, and if necessary the latest binary will be downloaded. In the future, Akamai CLI may pro-actively check for updates automatically, similar to Akamai CLI itself.
Versioning
Akamai CLI packages must adhere to Semantic Versioning (AKA SemVer).
The first release for a package should be version 0.1.0
.