Skip to main content
Version: 3.0.0

Opscotch Packager Tool

Opscotch is secure by design: configurations are deployed to the agent encrypted.

The opscotch packager is used to perform the following functions:

  • encrypt bootstrap host credentials
  • encrypt a bootstrap file
  • package and encrypt a workflow file
  • compare two workflow files

All packaging operations accept data through stdin and emit packaged data on stdout.

Packaging configuration​

All encryption operations require the packaging configuration.

The packaging configurations defines resources for compiling and signing workflow configurations, encrypting and license information.

The packaging configuration has the following items:

  • resources: Workflow configurations can refer to external resource files which are included when packaging. They are referred to as "resources". Resources can be supplied from multiple resource directories. This field is only required when packaging workflows.
  • agent public key: The files supplied to the agent are encrypted using public key encryption. Use the public key that matches the private key the agent is configured with.
  • opscotch license: all packaging activities require a valid opscotch license. See here for details on licensing

The above information is written into a json file such as package.json:

{
    "license" : "license.txt",
    "agentPublicKey" : "configs/agent.public.key", // or the base64 contents of the key file
    "resourceDirs" : ["."] // a list of resource directories, only required for workflow packaging
}

Bootstrap encryption​

Bootstrap files can be encrypted. see Securing

To encrypt a bootstrap, pipe the raw bootstrap into the the opscotch packager, using the bootstrap mode and provide the packaging configuration. The encrypted file will be emitted to stdout where you can redirected it to a file.

cat bootstrap.json | opscotch-packager bootstrap package.json > bootstrap.packaged

Loading an encrypted bootstrap file in the agent requires that you provide the decryption key as the second argument when starting the agent:

opscotch-agent bootstrap.packaged <path to decryption key or base64 endcoded key>

Authentication property encryption​

Authentication host properties can be encrypted, see Securing.

Encrypted authentication host properties are useful when the bootstrap source is stored in plain text, you can still have the credentials encrypted. Additionally, if you use environment variables to load credentials into authentication hosts, the environment variable values can be encrypted.

To encrypt a value, pipe the raw value into the the opscotch packager, using the encrypt mode and provide the packaging configuration. The encrypted value will be emitted to stdout where it can be copied and pasted into the bootstrap file authentication host properties.

echo "encrypt me" | opscotch-packager encrypt package.json

Workflow packaging and encryption​

Workflow configurations are compiled, signed and encrypted, see Securing.

Workflow packaging requires the resources property set in the packaging configuration.

To package a workflow file, pipe the raw workflow into the the opscotch packager, using the workflow mode and provide the packaging configuration. The encrypted file will be emitted to stdout where you can redirected it to a file.

cat workflow.json | opscotch-packager workflow package.json > workflow.packaged

Workflow comparison​

Workflow comparison is the operation of comparing two workflow files to determine the differences.

One workflow is considered the "source" and the other is considered the "target" - the packager will describe the changes that need to be made to the source for it to be equivalent to the target, which is useful when verifying changes.

Differences are described in terms of:

  • addition: something needs to be added to the source to make it equivalent to the target
  • removal: something needs to be removed to the source to make it equivalent to the target
  • replace: something needs to be replaced in the source to make it equivalent to the target

When comparing workflows, it is important to understand how the compare works: when the compare is executed, the packager reconstructs the packaging process from source. Therefore to compare two workflows, you need access to the source and resources at the time/version when they were packaged, not the packaged file. Consider that some time ago you packaged and deployed a workflow file, and now you've made some changes to the underlying resources and you want to verify the differences. You will need to provide the source workflow and resources at the time that it was packaged, and the target workflow and resource at the time that it was packaged. Because of this, it is critical to manage your source code well - you need to preserve a record of what version of the resources were at when you package.

To run the comparison you need to pass the configuration json file via stdin. For example:

  • assume the version of the workflow file that you are comparing from (source) is abcd and you have that checked out the workflow file and resources to /configs/abcd
  • assume the version that you are wanting to know the differences in is at version efgh and you have that checked out the workflow file and resources to /configs/efgh
  • your compare configuration would look like this:
{
    "sourceWorkflowFile" : "/configs/abcd/workflow.json",
    "targetWorkflowFile" : "/configs/efgh/workflow.json",
    "sourceResources" : [ "/configs/abcd/resources" ],
    "targetResources" : [ "/configs/efgh/resources"]
}

When run the output will be an array of difference objects like this:

[
...
  {
    "op": "value",
    "sourcePath": ".workflows[3].steps[0].trigger.timer.period",
    "targetPath": ".workflows[12].steps[0].trigger.timer.period",
    "sourceValue": 60000,
    "targetValue": 900000
  }
...
]

The difference object describes the following:

  • op: The op describes the change operation. The types are
    • value: the value has changed in the target
    • delete: the property has been deleted in the target
    • add: the value has been added in the target
    • type: the property type has changed in the target
  • sourcePath and targetPath: these are the jsonPath to the element in the source or target file. Notice in the example that they are different: the compare algorithm compares workflows and steps by id rather than array index. This means that workflows and steps can be in any order and the algorithm will identify the correct object to compare
  • sourceValue and targetValue: shows the value in both the source and target