exec mixin
Run a command or script.
✅ Learn how to use the exec mixin with our Exec Mixin Best Practice Guide
Source: https://porter.sh/src/pkg/exec
Install or Upgrade
porter mixin install exec
Mixin Syntax
exec:
description: "Description of the command"
command: cmd # The command to run, must be on the PATH
arguments: # arguments to pass to the command
- arg1
- arg2
flags: # flags to pass to the command, porter determines if it is a long (--flag) or short flag (-f)
a: flag-value
long-flag: true
repeated-flag: # Use an array if a flag must be specified multiple times with different values
- flag-value1
- flag-value2
suffix-arguments: # These arguments are specified after any flags are passed
- suffix-arg1
suppress-output: false # Do not print the command output to the console
ignoreError: # Conditions when execution should continue even if the command fails
all: true # Ignore all errors
exitCodes: # Ignore failed commands that return the following exit codes
- 1
- 2
output: # Ignore failed commands based on the contents of stderr
contains: # Ignore when stderr contains a substring
- "SUBSTRING IN STDERR"
regex: # Ignore when stderr matches a regular expression
- "GOLANG_REGULAR_EXPRESSION"
outputs: # Collect values from the command and make it available as an output
- name: NAME
jsonPath: JSONPATH # Scrape stdout with a json path expression
- name: NAME
regex: GOLANG_REGULAR_EXPRESSION # Scrape stdout with a regular expression
- name: NAME
path: FILEPATH # Save the contents of a file
This is executed as:
$ cmd arg1 arg2 -a flag-value --long-flag true --repeated-flag flag-value1 --repeated-flag flag-value2 suffix-arg1
Suppress Output
The suppress-output
field controls whether output from the mixin should be
prevented from printing to the console. By default, this value is false, using
Porter’s default behavior of hiding known sensitive values. When
suppress-output: true
all output from the mixin (stderr and stdout) are hidden.
Step outputs (below) are still collected when output is suppressed. This allows you to prevent sensitive data from being exposed while still collecting it from a command and using it in your bundle.
Ignore Error
In some cases, you may need to have the bundle continue executing when a mixin command fails. For example when the command fails because the resource already exists.
You can ignore errors based on:
- All - Ignore all errors from the command.
- ExitCodes - Ignore errors when one of the specified exit codes are returned.
- Output Contains - Ignore errors when the command’s stderr contains the specified string.
- Output Regex - Ignore errors when the command’s stderr matches the specified regular expression (in Go syntax).
Porter only prints out that an error was ignored in debug mode.
Outputs
The mixin supports outputs of various types:
JSON Path
The jsonPath
output treats stdout like a json document and applies the expression, saving the result to the output.
outputs:
- name: NAME
jsonPath: JSONPATH
For example, if the jsonPath
expression was $[*].id
and the command sent the following to stdout:
[
{
"id": "1085517466897181794",
"name": "my-vm"
}
]
Then the output would have the following contents:
["1085517466897181794"]
When you are developing your jsonPath expression, you can specify the –debug flag, and the full json document with your query are printed to stderr so that you can troubleshoot and improve your query based on the real result of the mixin’s execution.
Note: Porter attempts to preserve the original format of numeric values, so if the value is in scientific notation, the captured output should also be in scientific notation. Conversely, if the original number was not in scientific notation, then the captured value should also not be in scientific notation. Please open a bug if you find that the format doesn’t match what you expected.
Regular Expressions
The regex
output applies a Go-syntax regular expression to stdout and saves every capture group, one per line, to the output.
outputs:
- name: NAME
regex: GOLANG_REGULAR_EXPRESSION
For example, if the regex
expression was --- FAIL: (.*) \(.*\)
and the command send the following to stdout:
--- FAIL: TestMixin_Install (0.00s)
stuff
things
--- FAIL: TestMixin_Upgrade (0.00s)
more
logs
Then the output would have the following contents:
TestMixin_Install
TestMixin_Upgrade
File Paths
The path
output saves the content of the specified file path to an output.
outputs:
- name: kubeconfig
path: /root/.kube/config
Examples
See exec outputs for a full working example.
Run a command
install:
- exec:
description: "Install Hello World"
command: make
arguments:
- install
Run a script
install:
- exec:
description: "Install Hello World"
command: ./install-world.sh
FAQ
How do I use pipes?
If you have a command that pipes, place the command in a script file and then use the exec mixin to invoke that script passing in any parameters that the script requires as arguments.