API docs by Redocly

phenix (0.0.0)

Download OpenAPI specification:

URL: https://github.com/sandialabs/sceptre-phenix License: GNU General Public License v3.0 Terms of Service

phenix API

Find out more about Swagger

Configs

Config details and controls

Get all phenix configs

query Parameters
kind
string
Default: "all"
Enum: "all" "topology" "scenario" "experiment" "image" "user" "role"

limit configs to specified kind (defaults to all)

Responses

Response samples

Content type
application/json
{
  • "configs": [
    ]
}

Create new phenix config

Request Body schema:
required

phenix config creation parameters

apiVersion
required
string
kind
required
string
required
object
required
object

Responses

Request samples

Content type
{
  • "apiVersion": "string",
  • "kind": "string",
  • "metadata": {
    },
  • "spec": { }
}

Response samples

Content type
application/json
{
  • "message": "string",
  • "cause": "string",
  • "metadata": {
    }
}

Get existing phenix config

path Parameters
kind
required
string

kind of phenix config to get

name
required
string

name of phenix config to get

header Parameters
Accept
string
Default: application/json
Enum: "application/json" "application/x-yaml"

content format for response

Responses

Response samples

Content type
{
  • "apiVersion": "string",
  • "kind": "string",
  • "metadata": {
    },
  • "spec": { }
}

Update existing phenix config

Can also be used to rename a config by changing the name in the metadata portion of the config header and using the old name in the request path.

path Parameters
kind
required
string

kind of phenix config to get

name
required
string

name of phenix config to get

Request Body schema:
required

phenix config update parameters

apiVersion
required
string
kind
required
string
required
object
required
object

Responses

Request samples

Content type
{
  • "apiVersion": "string",
  • "kind": "string",
  • "metadata": {
    },
  • "spec": { }
}

Response samples

Content type
application/json
{
  • "message": "string",
  • "cause": "string",
  • "metadata": {
    }
}

Delete existing phenix config

path Parameters
kind
required
string

kind of phenix config to delete

name
required
string

name of phenix config to delete

Responses

Schemas

Config spec schemas

Get full schema (all config specs) for specific version

path Parameters
version
required
string
Enum: "v0" "v1" "v2"

version of phenix config schema to get

header Parameters
Accept
string
Default: application/json
Enum: "application/json" "application/x-yaml"

content format for response

Responses

Response samples

Content type
{ }

Get schema for specific config spec kind/version

the Workflow schema exists only in version v0

path Parameters
kind
required
string
Enum: "topology" "scenario" "experiment" "image" "user" "role" "workflow"

kind of phenix config schema to get

version
required
string
Enum: "v0" "v1" "v2"

version of phenix config schema to get

header Parameters
Accept
string
Default: application/json
Enum: "application/json" "application/x-yaml"

content format for response

Responses

Response samples

Content type
{ }

Experiments

Experiments details and controls

Get all phenix experiments

query Parameters
screenshot
string

whether or not to include VM screenshots (value is size to grab)

Responses

Response samples

Content type
application/json
{
  • "experiments": [
    ]
}

Create new phenix experiment

Request Body schema: application/json
required

phenix experiment creation parameters

name
string
topology
string
apps
Array of strings
vlan_min
integer
vlan_max
integer

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "topology": "string",
  • "apps": [
    ],
  • "vlan_min": 0,
  • "vlan_max": 0
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "string",
  • "topology": "string",
  • "apps": [
    ],
  • "start_time": "2019-08-24T14:15:22Z",
  • "running": true,
  • "vm_count": 0,
  • "vlan_min": 0,
  • "vlan_max": 0,
  • "vlan_count": 0,
  • "vlans": [
    ],
  • "vms": {
    }
}

Get existing phenix experiment

path Parameters
name
required
string

name of phenix experiment to get

query Parameters
screenshot
string

whether or not to include VM screenshots (value is size to grab)

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "string",
  • "topology": "string",
  • "apps": [
    ],
  • "start_time": "2019-08-24T14:15:22Z",
  • "running": true,
  • "vm_count": 0,
  • "vlan_min": 0,
  • "vlan_max": 0,
  • "vlan_count": 0,
  • "vlans": [
    ],
  • "vms": {
    }
}

Delete existing phenix experiment

path Parameters
name
required
string

name of phenix experiment to delete

Responses

Start existing phenix experiment

path Parameters
name
required
string

name of phenix experiment to start

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "string",
  • "topology": "string",
  • "apps": [
    ],
  • "start_time": "2019-08-24T14:15:22Z",
  • "running": true,
  • "vm_count": 0,
  • "vlan_min": 0,
  • "vlan_max": 0,
  • "vlan_count": 0,
  • "vlans": [
    ],
  • "vms": {
    }
}

Stop existing phenix experiment

path Parameters
name
required
string

name of phenix experiment to stop

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "string",
  • "topology": "string",
  • "apps": [
    ],
  • "start_time": "2019-08-24T14:15:22Z",
  • "running": true,
  • "vm_count": 0,
  • "vlan_min": 0,
  • "vlan_max": 0,
  • "vlan_count": 0,
  • "vlans": [
    ],
  • "vms": {
    }
}

Get current schedule for existing experiment

path Parameters
name
required
string

name of phenix experiment to get schedule for

Responses

Response samples

Content type
application/json
{
  • "schedule": [
    ]
}

Update current schedule for existing experiment

path Parameters
name
required
name

name of phenix experiment to update schedule for

Request Body schema: application/json
required

scheduling algorithm to use

algorithm
string

Responses

Request samples

Content type
application/json
{
  • "algorithm": "string"
}

Response samples

Content type
application/json
{
  • "schedule": [
    ]
}

Get captures for existing experiment

path Parameters
name
required
string

name of phenix experiment to get captures for

Responses

Response samples

Content type
application/json
{
  • "captures": [
    ]
}

Get list of files for experiment

path Parameters
name
required
string

name of phenix experiment to get files for

Responses

Response samples

Content type
application/json
{
  • "files": [
    ]
}

Download experiment file

path Parameters
name
required
string

name of phenix experiment to get file from

filename
required
string

name of file download

Responses

Virtual Machines

Experiment VM details and controls

get all VMs in existing experiment

path Parameters
exp_name
required
string

name of phenix experiment to get VMs for

query Parameters
screenshot
string

whether or not to include VM screenshots (value is size to grab)

Responses

Response samples

Content type
application/json
{
  • "vms": [
    ]
}

get given VM in existing experiment

path Parameters
exp_name
required
string

name of phenix experiment to get VM from

vm_name
required
string

name of phenix experiment VM to get

query Parameters
screenshot
string

whether or not to include VM screenshots (value is size to grab)

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "string",
  • "experiment": "string",
  • "host": "string",
  • "ipv4": [
    ],
  • "cpus": 0,
  • "ram": 0,
  • "disk": "string",
  • "dnb": true,
  • "networks": [
    ],
  • "taps": [
    ],
  • "captures": [
    ],
  • "running": null,
  • "uptime": 0.1,
  • "screenshot": "string"
}

Update existing VM settings in existing experiment

path Parameters
exp_name
required
string

name of phenix experiment to modify

vm_name
required
string

name of phenix virtual machine to modify

Request Body schema: application/json
required

phenix virtual machine patch parameters

host
string
cpus
integer
ram
integer
disk
string
dnb
boolean
object

Responses

Request samples

Content type
application/json
{
  • "host": "string",
  • "cpus": 0,
  • "ram": 0,
  • "disk": "string",
  • "dnb": true,
  • "interface": {
    }
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "string",
  • "experiment": "string",
  • "host": "string",
  • "ipv4": [
    ],
  • "cpus": 0,
  • "ram": 0,
  • "disk": "string",
  • "dnb": true,
  • "networks": [
    ],
  • "taps": [
    ],
  • "captures": [
    ],
  • "running": null,
  • "uptime": 0.1,
  • "screenshot": "string"
}

Delete phenix experiment VM

path Parameters
name
required
string

name of phenix experiment

vm_name
required
string

name of phenix virtual machine to delete

Responses

start VM in experiment

path Parameters
exp_name
required
string

name of phenix experiment

vm_name
required
string

name of phenix VM to start

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "string",
  • "experiment": "string",
  • "host": "string",
  • "ipv4": [
    ],
  • "cpus": 0,
  • "ram": 0,
  • "disk": "string",
  • "dnb": true,
  • "networks": [
    ],
  • "taps": [
    ],
  • "captures": [
    ],
  • "running": null,
  • "uptime": 0.1,
  • "screenshot": "string"
}

stop VM in experiment

path Parameters
exp_name
required
string

name of phenix experiment

vm_name
required
string

name of phenix VM to stop

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "string",
  • "experiment": "string",
  • "host": "string",
  • "ipv4": [
    ],
  • "cpus": 0,
  • "ram": 0,
  • "disk": "string",
  • "dnb": true,
  • "networks": [
    ],
  • "taps": [
    ],
  • "captures": [
    ],
  • "running": null,
  • "uptime": 0.1,
  • "screenshot": "string"
}

redeploy VM in experiment

path Parameters
exp_name
required
string

name of phenix experiment

vm_name
required
string

name of phenix VM to redeploy

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "string",
  • "experiment": "string",
  • "host": "string",
  • "ipv4": [
    ],
  • "cpus": 0,
  • "ram": 0,
  • "disk": "string",
  • "dnb": true,
  • "networks": [
    ],
  • "taps": [
    ],
  • "captures": [
    ],
  • "running": null,
  • "uptime": 0.1,
  • "screenshot": "string"
}

Get screenshot of running VM in experiment

path Parameters
exp_name
required
string

name of phenix experiment

vm_name
required
string

name of phenix virtual machine to get screenshot from

query Parameters
size
string

size of screenshot to grab

base64
boolean

whether or not to base64 encode the screenshot image

Responses

Tunnel to VNC of running VM using a WebSocket

path Parameters
exp_name
required
string

name of phenix experiment

vm_name
required
string

name of phenix virtual machine to connect to

Responses

get phenix experiment VM packet captures

path Parameters
exp_name
required
string

name of phenix experiment

vm_name
required
string

name of phenix VM to get captures for

Responses

Response samples

Content type
application/json
{
  • "captures": [
    ]
}

start phenix experiment VM packet capture

path Parameters
exp_name
required
string

name of phenix experiment

vm_name
required
string

name of phenix VM to start capture on

Request Body schema: application/json
required

phenix VM packet capture parameters

interface
integer
filename
string

Responses

Request samples

Content type
application/json
{
  • "interface": 0,
  • "filename": "string"
}

stop phenix experiment VM packet captures

path Parameters
exp_name
required
string

name of phenix experiment

vm_name
required
string

name of phenix VM to stop captures on

Responses

get phenix experiment VM snapshots

path Parameters
exp_name
required
string

name of phenix experiment

vm_name
required
string

name of phenix VM to get snapshots for

Responses

Response samples

Content type
application/json
{
  • "snapshots": [
    ]
}

create phenix experiment VM snapshot

path Parameters
exp_name
required
string

name of phenix experiment

vm_name
required
string

name of phenix VM to snapshot

Request Body schema: application/json
required

phenix VM snapshot parameters

filename
string

Responses

Request samples

Content type
application/json
{
  • "filename": "string"
}

restore phenix experiment VM to snapshot

path Parameters
exp_name
required
string

name of phenix experiment

vm_name
required
string

name of phenix VM to restore

snapshot
required
string

name of snapshot to restore VM to

Responses

Get all running VMs

query Parameters
screenshot
string

whether or not to include VM screenshots (value is size to grab)

Responses

Response samples

Content type
application/json
{
  • "vms": [
    ]
}

Hosts

Cluster host details

Get all cluster hosts

Responses

Response samples

Content type
application/json
{
  • "hosts": [
    ]
}

Applications

Available phenix user applications

Get all available user applications

Responses

Response samples

Content type
application/json
{
  • "applications": [
    ]
}

Topologies

Available phenix topologies

Get all available topologies

Responses

Response samples

Content type
application/json
{
  • "topologies": [
    ]
}

Builder

Graphical topology Builder diagrams and the topologies built from them

Get topologies that carry a Builder diagram

Responses

Response samples

Content type
application/json
{
  • "topologies": [
    ]
}

Create a topology and its Builder diagram

Creates the topology config and stores the diagram on it. Does not create an experiment. Refused while an experiment built from a topology of the same name is running.

Request Body schema: application/json
required

Builder topology and diagram

name
string

topology name; ignored by PUT /builder/topologies/{name}

required
object

generated topology spec

builderXML
required
string

mxGraph document for the diagram

object

VLAN alias to ID, used by the experiment endpoints only

scenario
string

scenario name, used by the experiment endpoints only

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "topology": {
    },
  • "builderXML": "string",
  • "vlans": {
    },
  • "scenario": "string"
}

Get one Builder diagram

path Parameters
name
required
string

topology name

Responses

Update a topology and its Builder diagram

Writes only the spec and the diagram, leaving the rest of the stored config's metadata intact. Does not create or update an experiment.

path Parameters
name
required
string

topology name, which takes precedence over the payload

Request Body schema: application/json
required

Builder topology and diagram

name
string

topology name; ignored by PUT /builder/topologies/{name}

required
object

generated topology spec

builderXML
required
string

mxGraph document for the diagram

object

VLAN alias to ID, used by the experiment endpoints only

scenario
string

scenario name, used by the experiment endpoints only

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "topology": {
    },
  • "builderXML": "string",
  • "vlans": {
    },
  • "scenario": "string"
}

Create a topology and a same-named experiment from Builder

Request Body schema: application/json
required

Builder topology, diagram, VLAN aliases, and scenario

name
string

topology name; ignored by PUT /builder/topologies/{name}

required
object

generated topology spec

builderXML
required
string

mxGraph document for the diagram

object

VLAN alias to ID, used by the experiment endpoints only

scenario
string

scenario name, used by the experiment endpoints only

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "topology": {
    },
  • "builderXML": "string",
  • "vlans": {
    },
  • "scenario": "string"
}

Update a Builder topology and its same-named experiment

Request Body schema: application/json
required

Builder topology, diagram, VLAN aliases, and scenario

name
string

topology name; ignored by PUT /builder/topologies/{name}

required
object

generated topology spec

builderXML
required
string

mxGraph document for the diagram

object

VLAN alias to ID, used by the experiment endpoints only

scenario
string

scenario name, used by the experiment endpoints only

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "topology": {
    },
  • "builderXML": "string",
  • "vlans": {
    },
  • "scenario": "string"
}

Disks

Available phenix disk images

Get all available disk images

Responses

Response samples

Content type
application/json
{
  • "disks": [
    ]
}

Users

User details and controls

Get all users

Responses

Response samples

Content type
application/json
{
  • "users": [
    ]
}

Create a new user

Request Body schema: application/json
required

user details

username
string
password
string
first_name
string
last_name
string
role_name
string
resource_names
Array of strings

Responses

Request samples

Content type
application/json
{
  • "username": "string",
  • "password": "string",
  • "first_name": "string",
  • "last_name": "string",
  • "role_name": "string",
  • "resource_names": [
    ]
}

Response samples

Content type
application/json
{
  • "username": "string",
  • "first_name": "string",
  • "last_name": "string",
  • "role": {
    }
}

Get a specific user

path Parameters
username
required
string

username of user to get

Responses

Response samples

Content type
application/json
{
  • "username": "string",
  • "first_name": "string",
  • "last_name": "string",
  • "role": {
    }
}

Update existing user

path Parameters
username
required
string

username of user to modify

Request Body schema: application/json
required

user paramaters

first_name
string
last_name
string
role_name
string
resource_names
Array of strings

Responses

Request samples

Content type
application/json
{
  • "first_name": "string",
  • "last_name": "string",
  • "role_name": "string",
  • "resource_names": [
    ]
}

Response samples

Content type
application/json
{
  • "username": "string",
  • "first_name": "string",
  • "last_name": "string",
  • "role": {
    }
}

Delete existing user

path Parameters
username
required
string

username of user to delete

Responses

Signup as a new user

Request Body schema: application/json
required

user details

username
string
password
string
first_name
string
last_name
string

Responses

Request samples

Content type
application/json
{
  • "username": "string",
  • "password": "string",
  • "first_name": "string",
  • "last_name": "string"
}

Response samples

Content type
application/json
{
  • "username": "string",
  • "first_name": "string",
  • "last_name": "string",
  • "role": "string",
  • "token": "string"
}

Login a user

query Parameters
user
string

login username

pass
string

login password

Responses

Response samples

Content type
application/json
{
  • "username": "string",
  • "first_name": "string",
  • "last_name": "string",
  • "role": "string",
  • "token": "string"
}

Login a user

Request Body schema: application/json
required

login credentials

user
string
pass
string

Responses

Request samples

Content type
application/json
{
  • "user": "string",
  • "pass": "string"
}

Response samples

Content type
application/json
{
  • "username": "string",
  • "first_name": "string",
  • "last_name": "string",
  • "role": "string",
  • "token": "string"
}

Logout a user

Responses

Workflow

Workflow config upserts and applies, and the server options clients read

Create or update a phenix config for a workflow branch

Creates the config if it does not exist and updates it otherwise. The server sets BRANCH_NAME to the branch before parsing the body, so ${BRANCH_NAME} placeholders expand to the branch name. The Content-Type header must be exactly application/json or application/x-yaml. A Topology is also checked for a node an experiment could not use, such as a hostname used twice or a reserved hostname, before it is stored. With dryRun=true it runs the same checks, returns what it would do, and stores nothing.

path Parameters
branch
required
string

workflow branch name

query Parameters
dryRun
boolean
Default: false

Checks the config as a real request would (placeholder expansion, the create or update decision, permissions, schema validation and, for a Topology, the node checks an experiment would fail on) and returns the result without storing the config or running config hooks. For an Experiment config only the schema is checked; the experiment checks run when the config is stored. The parameter's name is matched exactly, so a request that spells it differently is carried out for real.

Request Body schema:
required

phenix config of a storable kind (e.g. Topology or Scenario)

apiVersion
required
string
kind
required
string
required
object
required
object

Responses

Request samples

Content type
{
  • "apiVersion": "string",
  • "kind": "string",
  • "metadata": {
    },
  • "spec": { }
}

Response samples

Content type
application/json
{
  • "action": "create",
  • "kind": "string",
  • "name": "string",
  • "dryRun": true,
  • "pending": "string"
}

Apply a phenix workflow config to a workflow branch

Validates the workflow config against the Workflow schema, finds the experiment mapped to the branch (phenix.workflow/branch annotation), plans an action, and checks the default bridge and the topology and scenario the action would use, including a stored topology's nodes, as creating an experiment would. Only then does it create, update, start, or restart the experiment. A failed check leaves a running experiment running. With dryRun=true the plan is returned after the same checks, and nothing is changed; a dry run before a first deploy names the configs the caller will store with pending. The server sets BRANCH_NAME to the branch before parsing the body. The Content-Type header must be exactly application/json or application/x-yaml.

path Parameters
branch
required
string

workflow branch name

query Parameters
tag
Array of strings

key=value tag stored on the experiment, joined with commas into the phenix.workflow/tags annotation; repeat the parameter for more tags

dryRun
boolean
Default: false

Runs every check, a stored topology's node checks included, and returns the plan without creating, updating, starting, or stopping anything. The parameter's name is matched exactly, so a request that spells it differently is treated as a real apply, and refused with 400 when it also carries pending.

pending
Array of strings

A config the caller will create or update before the real apply, usually the pending value a dry run of POST /workflow/configs/{branch} returned: /, such as Topology/helloworld, optionally followed by "?" and the config's references, such as Scenario/helloworld?from=helloworld-base&topology=helloworld (url-encode the value). The kind may be in any case. Repeat the parameter for more configs. A pending topology or scenario is not looked up, decoded or merged, so a first deploy can be checked before its configs are stored; the references listed after "?" are checked instead, with the errors the real apply gives (on a create, a scenario's topology annotation; each fromScenario, which must be pending or stored and annotated for the topology; each included topology, which must be pending, stored or a file on the server). An include that is neither pending nor stored is looked up as a file on the server, as the real apply does, so the answer shows whether that path exists on the server; grant workflow:create only to roles trusted with that (the default policies give it to Global Admin only). Only allowed with dryRun=true; otherwise, or for a value that is not a config name, the request is a 400.

expect
string
Enum: "none" "create" "createAndStart" "update" "updateAndStart" "restart"

The action the caller expects, usually the action a previous dry run returned. If the server plans a different action, it returns 409 and changes nothing. It is checked on dry runs as well as real applies. A value that is not an action is a 400 with the message invalid expect value "" and the cause unknown workflow action "".

Request Body schema:
required

phenix workflow config

apiVersion
required
string (API Version)
Value: "phenix.sandia.gov/v0"

The config API version; a workflow config is phenix.sandia.gov/v0.

kind
required
string (Kind)
Value: "Workflow"

The config kind, which is always Workflow.

metadata
object or null (Metadata)

Not read by the server; it is accepted so a workflow config has the same four top-level keys as every other phenix config, and so a later version can carry a name or annotations without a breaking change.

required
object (Workflow Spec)

What an apply may do and the experiment settings it sets; an empty spec applies every default.

Responses

Request samples

Content type
{
  • "apiVersion": "phenix.sandia.gov/v0",
  • "kind": "Workflow",
  • "metadata": { },
  • "spec": {
    }
}

Response samples

Content type
application/json
{
  • "action": "none",
  • "experiment": "string",
  • "reason": "string",
  • "dryRun": true
}

Get server-side options

Server-side settings that clients read: every phenix CLI command fetches them over the unix socket when it starts, to inherit the server's bridge-mode, deploy-mode and use-gre-mesh, and the web UI's Experiments page reads them too. workflow-dry-run is true when POST /workflow/configs/{branch} and POST /workflow/apply/{branch} both support dryRun, and apply supports pending and expect. An older server ignores dryRun on /workflow/configs/{branch} and stores the config, so phenix workflow apply refuses servers without it.

Responses

Response samples

Content type
application/json
{
  • "bridge-mode": "string",
  • "deploy-mode": "string",
  • "use-gre-mesh": true,
  • "base-dir.injects": "string",
  • "workflow-dry-run": true
}