Load/Extract
The main purpose of Design Extract/Load feature is two-fold:
- to provide an ability to save and source control assembly design in some external tool (i.e. github).
- to enable easy and seemless way to share designs with other assemblies/organization/users.
Other benefits include: making it easy to apply a large number of changes without having to “click-thru” UI pages and automation enablement (i.e. external tool integration via API).
Extract can be used to save a design created in OneOps into a YAML or JSON file. The generated file (YAML or JSON) is not meant to store a full snapshot of current design but rather contain a “delta” style description capturing the list of assembly platforms and only the difference between their configuration and the default configuration defined in the platform packs. When any attributes is changed in design a user should “lock” those changed attributes in order to explicitly have them included in design yaml/json file as well as to preserve their changed values from overwriting (to pack defaults) during Pack Pull operation. A lock button is available next to every component attribute and variables. Enable locking to extract any specific attributes into the yaml file.
Therefore the design yaml/json file generated by Extract will explicitly include:
- all the design variables;
- all platforms;
- all platform variables;
- platform dependencies (links);
- optional components (explicitly) added by user to platforms;
- additional component dependencies (explicitly) added by user;
- attachments;
- “locked” (only) component and attachment attributes regardless of whether they different from default values (from pack or metadata).
Unlocked attributes/variable has icon as below:
The lock icon changes to locked.
NOTE: User MUST mark attributes as “locked” to indicate that such attribute is to be included in the extract design file. Changed attribute values are NOT included in the design file (by default) unless they are locked.
Load feature can be used to bulk-update an assembly design using a YAML/JSON file typically generated by Extract. Load will generate design changes to bring it in alignment with design configuration specified in the design YAML/JSON file by adding them to the current open design release (when possible – if there are no changes for the same platforms in current release) or by opening a new design release. The resulting release is not automatically committed and stays open for user to review the changes before committing or discarding it.
Design YAML/JSON file can be composed of smaller files (i.e. one design file per platform) by referencing them via special import directive. The same file can also include explicit content further in the file. For example:
import:
- https://raw.githubusercontent.com/oneops/setup/master/design/adapter-design.yaml
- https://raw.githubusercontent.com/oneops/setup/master/design/admin-design.yaml
- https://raw.githubusercontent.com/oneops/setup/master/design/wire-design.yaml
- https://raw.githubusercontent.com/oneops/setup/master/design/antenna-design.yaml
...
variables:
VAR1: "foor"
VAR2: "bar"
...
platforms:
db:
pack: oneops/postgresql:1
variables:
db-user: $OO_GLOBAL{VAR1}
db-pass: $OO_GLOBAL{VAR2}
components:
compute/oneops.1.Compute:
compute:
size: L
database/oneops.1.Database:
database:
dbname: cool_app
username: $OO_LOCAL{db-user}
password: $OO_LOCAL{db-pass}
...
The file can be loaded using any of the following:
- UI page for design load by uploading the yaml file or posting the yaml content directly in the text area. To get
to the design load page in the UI go to the assembly design and click on the
Loadbutton in the header. - CLI command
oneops design load. The defaults path for the Design file is./oneops-design.yaml. For additional information see CLI section. - API request for design load. Some examples using cURL:
GET request to extract design in YAML format:
curl -u API_TOKEN: .../assemblies/:assembly/design/extract.yaml
GET request to extract design in JSON format:
curl -u API_TOKEN: .../assemblies/:assembly/design/extract.json
PUT request to load design from YAML file:
curl -u API_TOKEN: .../assemblies/:assembly/design/load.json -X PUT -F "data_file=@design.yaml"
PUT requst to validate design load (no design release will be created) from JSON string:
curl -u API_TOKEN: .../assemblies/:assembly/design/load.json -X PUT -d "preview=true&data=..."
Global Variables
Variables that can be used anywhere in the design and are referenced via $OO_GLOBAL{...} syntax. For additional information on global variables see variables reference page.
variables:
MYGLOBALVAR1: "foo"
MYGLOBALVAR2: "bar"
MYENCRYPTEDVAR1: "::ENCRYPTED::<foobar>"
Encrypted variables can either be provided into yaml in plain text using above format(e.g. MYENCRYPTEDVAR1) OR load of yaml with encrypted variable/attribute would require a manual override on load.
Platforms
Definition of platforms to be loaded inside the assembly design.
Multiple design files can be loaded with separate platform definitions in each.
Loadoperation performs an upsert for each platform found in the file, but does not do any platform deletions. Deletes must be done directly via the UI/CLI/API per platform, not via load.
This section contains a list of all configuration options supported by a platform definition.
pack
A string in the form of <source>/<name>:<version> declaring the pack to be used for this platform. For additional information on packs see packs.
pack: oneops/tomcat:1
major_version
Major version of the platform. For new design this will usually be set to 1 and increased when a platform version upgrade is needed.
major_version: '1'
links
Links are used to describe dependencies between platforms. For additional information on links between platforms see platform links.
links:
- db
- mq
platform variables
Platform variables that can be used inside the specified platform in design and are referenced via $OO_LOCAL{...} syntax. For additional information on platform variables see variables reference page.
variables:
MYLOCALVAR1: "foo"
MYLOCALVAR2: "bar"
Components
Definition of components inside the platform.
Only optional components or components with custom attribute values need to be specified in this section. All other components declared in the packs are inherited using the default pack values.
components is a three-level structure with the 1st key a string in the format <resource template>/<class name> matching the corresponding entities in the pack. The 2nd key is the unique name of the component and the 3rd key is any of the attributes supported in the metadata for that component class. See the corresponding pack and component documentation for possible values.
artifact/Artifact:
artifact:
install_dir: /app/artifact
version: '1.0'
Attachments
‘attachments’ can be used in the same level as the component attributes to declare component attachments.
attachments:
myscript:
path: /tmp/myscript.sh
exec_cmd: /tmp/myscript.sh
priority: '1'
content: |-
#!/bin/sh
echo "hello"
run_on: before-add,before-replace,before-update
Example yaml file
variables:
MYGLOBALVAR1: "foo"
MYGLOBALVAR2: "bar"
platforms:
app:
pack: oneops/tomcat:1
major_version: '1'
variables:
MYLOCALVAR1: "foo"
MYLOCALVAR2: "bar"
links:
- db
- mq
components:
artifact/Artifact:
artifact:
install_dir: /app/artifact
version: '1.0'
tomcat/Tomcat:
tomcat:
tomcat_install_dir: '/opt'
attachments:
myscript:
path: /tmp/myscript.sh
exec_cmd: /tmp/myscript.sh
priority: '1'
content: |-
#!/bin/sh
echo "hello"
run_on: before-add,before-replace,before-update
