Application Endpoints¶

Create a new application.

Example request:

$ curl -XPUT '/app?app_name=widgetmaker'

Create a new build object.

Example request:

$ curl -XPUT '/app/widgetmakers/builds?build_name=1-master' -d '{ "attributes": { "branch_name": "master" } }'

Create a new package map.

A package map is a mapping of package names to one or more filename patterns. Patterns are interpreted as glob expressions including ‘**’ syntax for recursive matching (similar to globstar option of the bash shell). Each package must have a “patterns” key consisting of a list of one or more pattern strings.

There can be any number of packages within the package map, and there must be at least one pattern associated with each package.

Package Map Format

A package map is a mapping of package name (which can be an arbitrary string) to a JSON object consisting of the following fields:

• patterns (required, list of strings): a list of glob-style patterns which will be matched against filenames (including paths) in the master package. Matching files will be included in the package. “**” (double star) may be used for recursive matching.
• prefix (optional, string): this string will be prepended to the archive name of each file in the package. Path separators can be used to create a directory hierarchy. This is performed after remove_prefix is processed (if present).
• remove_prefix (optional, string): if this string is present in the filename (including path), it will be removed exactly once beginning from the left. Prefix removal always occurs prior to prefix prepending via the “prefix” field.

Example JSON body

{
  "packages": {

     "binaries": {
         "patterns": [ "bin/**/*" ]
     },
     "configs": {
         "patterns": [ "conf/**/*.xml" ],
         "prefix": "app-config/"
     }

  }
}

The above package map creates two packages: “binaries” and “configs”. The first (“binaries”) contains all files in the top-level “bin/” directory within the master package. The files are added recursively preserving directory structure.

The second package (“configs”) includes all XML files under the top-level “conf/” directory within the master package. Note that it also preserves the directory structure (but directories that do not contain matching files will not be included).

Note also that the “configs” package contains a prefix field. The prefix will be prepended to the archive name of every file in the package. For example, if a file “conf/a/b/main.xml” is added to the package, the archive name (the name that the file will have when the package is unpacked) will be “app-config/conf/a/b/main.xml”. There is another optional field called “remove_prefix” which does the opposite: if that string is present in the filename, it will be removed a maximum of one time starting from the left.

Example request:

$ echo '{ "packages": { "binaries": { "patterns": [ "bin/**/*" ] } } }' |http PUT '/app/widgetmakers/packagemaps?name=example_map'

Create a new gitrepo. If the parameter “existing” is false, Elita will create the repository using the gitprovider API.

Example request:

$ curl -XPUT '/app/widgetmakers/gitrepos?name=MyRepo1&existing=false&gitprovider=gp1&keypair=kp1'

Create a new gitdeploy. You must provide a valid JSON-encoded gitdeploy object in the body of the request.

The required top-level keys are:

“package” - the build package to deploy. Must be a string and must be a valid package name. Note that this is not checked for validity at the time of gitdeploy creation, allowing you to create gitdeploys prior to implementing packaging.

“location” - an object describing where to deploy on end servers (see below)

Additional optional top-level keys are:

“attributes” - user-defined attributes

“options” - git options (see below)

“action” - pre/post salt states to run in addition to the deployment (see below)

Location object:

The location object is a JSON object that has the following required keys:

“path” - absolute deployment path on end servers. This is where the gitrepo will be cloned.

“gitrepo” - name of gitrepo to deploy at path.

“default_branch” - name of git branch to deploy (use ‘master’ unless you know you need something else)

Options object:

The options object allow you to specify the following git options which are used during deployments:

“favor” - can be “ours” (local) or “theirs” (remote). Defaults to “ours”. This reduces the chances of merge failures if local changes exist, preferring the local changes to the incoming remote changes.

“ignore-whitespace” - “true”/”false”. Also reduces likelihood of merge conflicts. Defaults to true.

“gitignore” - a list of strings representing the .gitignore file on end servers. Use this to ignore local changes on end servers so they don’t cause failed deployments.

Actions object:

The actions object allows you to inject salt states into the gitdeploy. It consists of two keys: “prepull” and “postpull”. As the names suggest, “prepull” is executed immediately prior to deployment and “postpull” is executed immediately afterward.

Salt states by convention are usually expressed as YAML. This is easily translated into JSON. Keep in mind, however, that every state must have a unique ID. It’s therefore preferable to express them with an arbitrary (but unique) ID and an explicit “name” parameter, rather than the more terse form of using the ID as the implicit name.

Example:

This is an idiomatic Salt state to ensure httpd is running (in YAML):

httpd:
     service
     - running

Prior to injection it should be converted to the following form (in YAML):

start_apache:
     service:
     - name: httpd
     - running

Translated into JSON:

{
 "start_apache": {
     "service": [
         {
             "name": "httpd"
         },
         "running"
     ]
 }
}

Example gitdeploy object (simple):

{
  "package": "webapplication_pkg",
  "location": {
    "path": "/opt/widgetmaker",
    "default_branch": "master",
    "gitrepo": "wm_webapp_gitrepo"
  }
}

Example gitdeploy object (complex):

{
  "attributes": {
    "description": "Example gitdeploy for Elita documentation"
  },
  "package": "webapplication_pkg",
  "location": {
    "path": "/opt/widgetmaker",
    "default_branch": "master",
    "gitrepo": "wm_webapp_gitrepo"
  },
  "options": {
    "favor": "ours",
    "ignore-whitespace": "true",
    "gitignore": [
      "foo.txt"
    ]
  },
  "actions": {
    "prepull": {
      "stop_apache": {
        "service": [
          {
            "name": "httpd"
          },
          "dead"
        ]
      }
    },
    "postpull": {
      "start_apache": {
        "service": [
          {
            "name": "httpd"
          },
          "running"
        ]
      }
    }
  }
}

Example request:

$ curl -XPUT '/app/widgetmakers/gitdeploys?name=WebApp' -d $(cat WebApp.json)

Create a group. You must supply a JSON-encoded list of gitdeploys in the body of the request. The “gitdeploys” key can either be a flat list of strings (unordered) or a list-of-lists (ordered). See Group Explanation for details.

Example JSON:

{
  "gitdeploys": [ "Configuration", "WebApplication", "StaticAssets" ]
}

Example request:

$ curl -XPUT '/app/widgetmakers/groups?name=WebFrontEnd' -d '{ "gitdeploys": [ "Configuration", "WebApplication", "StaticAssets" ] }'