a9s Add-on Specification - Version 1

This document specifies version 1 of the a9s Add-on specification. It includes a detailed description of the add-on internal structure and how add-ons under this version are distributed.

Notational Conventions

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.

Terminology

• BOSH release: a gzipped tarball as specified by Cloud Foundry BOSH.
• gzipped tarball: multiple directories and files archived with Tar and compressed with Gzip, named with the .tgz extension.
• ops files: A YAML file that includes multiple operations to be applied to a different YAML file as defined in BOSH Operations file.
• anynines-deployment: The anynines-deployment directory after extracting the offline package.

Distribution

Any a9s Add-on MUST be packaged in a gzipped tarball (with the .tgz extension) and MUST be shipped under the corresponding anynines-deployment release version.

The name of the gzipped tarball SHALL have the following pattern:

<add-on_name>-<anynines-deployment_version>.tgz

The gzipped tarball MUST include only the directory named with the same name as the package, but without the extension. All the content of the add-on MUST be inside this directory. This means that after extracting the <dummy-add-on>-<anynines-deployment-version>.tgz package you will get a <dummy-add-on>-<anynines-deployment-version> directory, the content of this directory is specified in section Package Structure.

• <anynines-deployment_version> is the anynines-deployment version. It follows Semantic Versioning 2.0.0.
• <add-on_name> can only contain alphanumeric characters, - or _.

Package Structure

The add-on package MUST comply with the following structure:

Name	Type	Presence
releases	directory	optional
ops	directory	mandatory
licenses	directory	optional
SPEC_VERSION	file	mandatory
README.md	file	mandatory
metadata.json	file	mandatory

Example:

<add-on_name>-<anynines-deployment-version>/
  releases/
    boshrelease-a-X.tgz
    boshrelease-b-Y.tgz
    (...)
  ops/
    some-ops-file-1.yml
    some-ops-file-2.yml
    (...)
  licenses/
    file-with-one-license.txt
    file-with-multiple-licenses.txt
    (...)
  README.md
  SPEC_VERSION
  metadata.json

The specification of each directory and each file is defined below.

releases

This directory holds all the BOSH releases necessary to deploy the extension provided by the add-on.

Nested directories are not allowed, only gzipped tarball SHALL be found inside the releases directory.

All the licenses required by the software contained in the BOSH releases MUST be placed under the licenses directory and they SHALL follow the licenses specification.

All files in this directory MUST be declared under the releases section of the metadata.json file. Check the metadata.json section for more information.

This directory CAN only be omitted If no release is required as a dependency.

All releases in this directory SHALL be uploaded to the BOSH director as part of the installation of the add-on.

ops

This directory SHALL hold all the ops files necessary to apply the add-on, and only ops files SHALL be placed under this directory following the Kebab case naming convention. These ops files MUST be enough to deploy the add-on with the default configuration. In case that extra configuration is necessary any details or specific information MUST be detailed in the README.md file.

The intent of these ops files is to be interpolated with other manifests to extend the original anynines-deployment content.

Nested directories are not allowed, only YAML files with the .yml extension SHALL be found inside the ops directory.

All files in this directory MUST be declared under the ops section of the metadata.json file. Check the metadata.json section for more information.

The ops files in this directory are how the necessary changes are applied to install the add-on. They can be applied either with BOSH interpolate, followed by replacing the necessary files:

bosh interpolate manifest.yml --ops-file ops-file-1.yml --ops-file ops-file-2.yml (...) > manifest.yml

Or given as part of the argument while deploying the services with --ops-file argument:

bosh -d <deployment> deploy manifest.yml --ops-file ops-file-1.yml --ops-file ops-file-2.yml (...)

licenses

This directory SHALL hold all the necessary licenses to use the add-on. This includes all the licenses required by every BOSH release or any other required license.

Nested directories are not allowed.

Every file MAY contain more than one license.

While not all licenses might be released under the OSD, all license definitions MUST be in plain text with the .txt extension.

All files in this directory MUST be declared under the licenses section of the metadata.json file. Check the metadata.json section for more information.

This directory CAN only be omitted if no license is required.

SPEC_VERSION

This is the specification version file named SPEC_VERSION.

This document describes version 1 of the add-on specification, and every add-on following this version MUST have only the number 1 hardcoded as the content of this file.

To know more about the SPEC_VERSION, check the Add-on Versions section.

README.md

Markdown file with general information about the add-on where the target audience is the platform operator installing the add-on. By the end of this file, the reader MUST understand what the add-on does and how to enable it.

The file MUST contain at least the following sections described in the template below:

<Name of the Add-on>
===================

<brief description of the add-on as paragraph>

# Description

(...)

## ops

* <ops-file-name-1>: <very brief description of what the ops file does>
* <ops-file-name-2>: <very brief description of what the ops file does>
* (...)

# Prerequisites

(...)

Title

The name of the add-on must be in capitalized title format.

Description

A long and detailed description of the add-on, how it extends anynines-deployment, and any other information relevant for the platform operator installing this add-on.

If any extra configuration is necessary (e.g.: IaaS variable, manual CredHub credential creation, etc), it MUST be disclosed and detailed in this section.

A list of the ops files provided and a very brief description of what it does MUST be included to provide some information about which ops files the operator is interested in enabling at that moment.

Prerequisites

A complete list of prerequisites and requirements for the add-on.

metadata.json

A metadata file following the JSON specification using the .json extension in the root directory of the add-on. It is the source of truth for the releases, ops files, and licenses.

This file references all the files shipped in the add-on, and their attributes.

It MUST have at least the following properties:

Property	Type	Description
ops	array	An array of ops files definitions with the ops file and the target manifests
releases	array	An array of strings referencing the BOSH releases of the add-on
licenses	array	An array of string referencing the license files in the add-on

Example:

{
  "ops":[
    {
      "file" : "ops/some-ops-file-1.yml",
      "target_manifests" : [
        "<data-service-1>/<data-service-manifest-1>",
        "<data-service-2>/<data-service-manifest-2>",
        (...)
      ]
    },
    {
      "file" : "ops/some-ops-file-2.yml",
      "target_manifests" : [
        "<data-service-1>/<data-service-manifest-1>",
        "<data-service-2>/<data-service-manifest-2>",
        (...)
      ]
    }
  ],
  "releases" : [
    "releases/boshrelease-a-X.tgz",
    "releases/boshrelease-b-Y.tgz",
    (...)
  ],
  "licenses" : [
    "licences/file-with-one-license.txt",
    "licences/file-with-multiple-licenses.txt",
    (...)
  ]
}

Each property is described below.

ops

An array of ops files, where each ops file is declared with:

Property	Type	Description
file	string	Path to the ops file in the add-on
target_manifests	array	An array of strings referencing the anynines-deployment data services manifests that this ops file can be applied to.

Example:

{
  "file" : "ops/some-ops-file-1.yml",
  "target_manifests" : [
    "<data-service-1>/<data-service-manifest-1>",
    "<data-service-2>/<data-service-manifest-2>",
    (...)
  ]
},

file

A string with the path to the ops file. The path MUST be relative to the add-on directory, as described in the Package Structure section.

target_manifests

An array of strings, where each string is the path to the manifest inside anynines-deployment, that the ops file declared in file CAN be applied to. The paths are relative to the root of anynines-deployment and follow the format <service-name>-service/<service-name>-service.yml.

By checking the ops property of the metadata file, the operator can see all ops files available in the add-on, and which manifests under anynines-deployment they CAN be applied to.

releases

An array of strings, where each string is the path to a BOSH release inside the releases directory. The path is relative to the root of the add-on directory (e.g.: releases/<boshrelease-a-X.tgz>).

These releases SHALL be uploaded directly to the BOSH Director or merged with the releases of the anynines-deployment, but all of them must be uploaded to the BOSH Director during the installation.

All releases under the releases directory MUST be declared in this property.

licenses

An array of strings, where each string is the path to a license file inside the licenses directory. The path is relative to the root of the add-on directory (e.g.: licenses/<license>.txt).

All license files under the licenses directory MUST be declared in this property.

Additional Information

How add-ons are applied can vary from add-on to add-on, but in general, the platform operator can follow these steps to install the add-on:

• Extract the add-on gzipped tarball package.
• Read the SPEC_VERSION to be sure it is version 1.
• Iterate over all BOSH releases declared in the releases section of the metadata.json file and upload the release into the BOSH Director..
• For each data service, check which ops files can be applied (the ops section in the metadata.json file), and interpolate or apply all the necessary ops files during installation or update.