✈
Command Line Usage
We use the jetp CLI to apply configurations or send orders to remote machines, often like this:
$ ssh-agent
$ ssh-add ~/.ssh/id_rsa
$ jetp ssh --playbook ~/playbooks/setup.yml --inventory ~/inventory --user opsteam
Local configuration looks like this:
$ jetp local --playbook ~/local_playbooks/local.yml
Built-in help is available and will give you a better idea of what jet can do:
$ jetp --help
Details on available subcommands and options continue below.
Jetp has various modes grouped into subcommands.
The main command for configuring local machines is "jetp local", and if you want to push orders out to multiple remote machines there is "jetp ssh'.
Upcoming Connectivity Modes
Jet is already fairly effectient and can easily use very high thread counts (such as 100-150 simultaneous threads) for parallel SSH. To push this over the edge, future "planetary scale" and SSH fanout deployment modes will be available using additional subcommands in the future.
subcommand | purpose | makes changes |
|---|---|---|
check-ssh | connects to remote machines over SSH and sees if any changes would be made if running in 'ssh' mode. | no |
ssh | connects to remote machines and runs playbooks in a 'live' configuring mode | yes |
check-local | evaluates a playbook locally and reports if any changes would be made if running in 'local' mode | no |
local | runs a playbook locally in 'live' configuring mode | yes |
show-inventory | display information about SSH inventory groups and hosts | no |
About Check Modes
'check-ssh' and 'check-local' modes compare hosts to a define policy rather than configure them.
These are sometimes imperfect in that they do not evaluate any shell tasks that might be relied upon for conditional execution later on in a playbook, if using conditonal expressions in the playbook. They do remotely evaluate facts and other passive tasks.
It is possible that a check-local or check-ssh command would fail when a 'local' or 'ssh' run would succeed. If this happens, do not be dissuaded, Jet is designed for declarative application of configurations, and this is mostly provided for when someone would want to use automation as a policy monitoring tool.
There is no need to run check-mode before applying configurations.
The following parameters are used in nearly all jetp runs:
-p path/to/playbook.yml
--playbook path/to/playbook.yml
--playbook pb1.yml
The playbook tells Jet what actions to perform (or what policy to apply) on what machines. This is needed for both local and SSH configuration.
-i path/to/inventory
--inventory path/to/inventory/
--inventory dynamic_inventory_script.py
--inventory path/one/:path/two/
--inventory path/one --inventory path/two
For file-based static inventory, we specifiy the directory name for the inventory. For a dynamic inventory, we give the inventory script filename.
Starting With Static Inventory
We recommend using a file based inventory using some known hostnames or IP addresses when learning Jet, and once you have done something sufficiently "hello-world" like, then exploring the world of dynamic inventory sources. Starting with dynamic inventory is ok, but it's probably more productive to explore the language first and get to that a bit later.
Using multiple simultaneous inventory sources is possible, enabling, for example, communication with multiple clouds at the same time, or mixing clouds with physical datacenters.
The Inventory Flag Is Not Always Required
The pending messaging-enabled modes will not use an --inventory parameter, nor does local mode use it.
-r path/to/roles/directory
--roles path/to/roles/directory
--roles path/to/roles/directory:path/to/more/roles
Jet will by default look for roles in a subdirectory called "roles/" alongside the playbook, and this parameter adds additional directories to the roles search path. Roles alongside the playbook would only be used in a single project, whereas a roles path might indicate roles tracked in another git repository. Having an git repo full of common roles that service-specific playbooks can use may be a useful pattern to emulate.
Jet will always also look in the 'roles/' directory alongside the playbook after these locations are searched.
Specifying Roles From Environment Variables
The environment variable JET_ROLES_PATH can also set additional roles path search locations. It works just like the Unix parameter PATH and can contain multiple directory values seperated by colons.
The following parameters are good to know, and are situationally relevant. You may not use all of these parameters, and it's fine to not try them until they are needed. If you're just getting a feel of learning Jet, you're welcome to skip ahead in the documentation and skim these later.
This is NOT recommended and is provided for limited bootstrapping capabilities only - namely adding your SSH key into authorized_keys in a home lab setup.
We strongly recommend using ssh-agent with jet because passing login passwords to compromised systems can share your login password with an untrustworthy host. This option is only here use with bootstrapping existing non-cloud lab systems. Be careful with what machines you talk to this way. For cloud based systems, you can almost always provision the system with your SSH key preinstalled.
--ask-login-password
Also note, the --ask-login-password parameter will not work with modules that support the --forward-agent parameter (namely the git module when doing private repo operations)
-u stuart
--user bob
In SSH mode, jetp's default behavior is to attempt to connect to the remote machine at the given hostnames as specified in inventory, on port 22, and use the username of the currently logged in account ($USER) on the control machine.
Most commonly, only the remote username needs to be changed, and this can be adjusted on the command line:
jetp --playbook pb1.yml --inventory ~/inventory --user opsteam
In other words, if you were configuring from a Mac and your Mac account is logged in as "fezzik" and your SSH keys are for accounts on your production machines named "prod", you would want to pass "--user prod" on the command line.
The remote user (as well as the port and the actual dns name or IP used for the host) can also be set using inventory variables, as described here, or set in the Play.
Often most of a playbook will be checked into git and inventory will be prepared, but some variables need to be injected from outside. A most common example of this would be if making a "release" playbook where perhaps some version information came from a build system or another file.
To enable this use case, --extra-vars supplies additional variables to Jet either on the command line or from arbitrary YAML files.
Inline JSON is assumed unless the argument starts with "@", in which case any file path can be used for YAML input.
Extra variables have the same level of precedence as the "vars" or "vars_files" keyword in a playbook, which means the values will definitely override any defaults or values set in inventory.
jetp --playbook release.yaml --inventory ~/inventory
--extra-vars '{"version": "1.23"}'
jetp --playbook release.yml --inventory ~/inventory --extra-vars @version.yml
--limit-hosts www.example.com:www2.example.com
--limit-groups group1:group2
Normally the playbook says what groups to configure or execute tasks against. If a limit (either --limit-hosts or --limit-groups) is specified, it is possible to further restrict the execution to a specified subset of hosts or groups, narrowing the playbook down further.
If more than one item is specified by separating the terms with a ":", the two are treated as an OR condition, where the hosts can be in either of the two groups.
This can be useful in debugging a playbook, or re-running a playbook on just a particular host that has failed. It can also be used to make fairly generic playbooks (such as, for, maybe restarting a specific service or doing a migration) that can be sent to a specific node or cluster without editing the playbook files in version control.
SSH agent forwarding currently only has to be used when using the git module when using key-based authentication against private repositories.
The security implications of SSH forwarding for this module are discussed in the git module documentation.
Agent forwarding is only used during operation of module operations that request it (such as the git module when using non-https:// checkouts), so all modules will otherwise work fine with SSH Agent Forwarding disabled. For instance, SSH agent forwarding is not (yet) made available as an option to the shell module.
--forward-agent
Administrators should already be familiar with sudo.
The need to sudo after login can be specified in a playbook or on the command line. If sudo details are set at playbook level, the command line setting will override the playbook.
Per task sudo settings then override all of these settings, as even when sudoed to, for example, the root account, some automation steps may need to be run from other user accounts, such as a database account.
--sudo root
Alternative sudo replacements
The sudo command does not mean the literal 'sudo' command needs to be used, and other sudo replacement tools are supported. See the Play documentation on the sudo_template keyword for how to configure sudo alternatives.
Sudo With Password
Passwords (and configurable password prompts) are not yet supported in Tech Preview 1. Sudo passwords are going to be added as a feature in the Tech Preview 2 release.
Sometimes users may want to execute only a portion of a playbook. This may be to save time in re-running a configuration after some error has been corrected, or when authoring playbook content for the first time.
Multiple tags can be specified using the ":" seperator, in which case the task only needs to have one of the given tags to run.
--tags foo_app
--tags security:common
-t 100
--threads 100
In SSH modes, this setting sets how many parallel threads are used to talk to remote systems. These are OS threads, not forks, so the value can easily go quite high depending on the capabilities of the control machine.
Setting Thread Defaults
This value can also be set by the environment variable JET_THREADS.
Verbosity levels can help debug a playbook, but having too much output can sometimes be a bit much to handle.
Verbosity levels can be adjusted by adding -v parameters, as many as you would like!
jetp ssh --playbook pb1.yml --inventory ~/private_inventory -v
jetp ssh --playbook pb1.yml --inventory ~/private_inventory -vv
jetp ssh --playbook pb1.yml --inventory ~/private_inventory -vvv
OR
jetp ssh --playbook pb1.yml --inventory ~/private_inventory -v -v -v
The levels are roughly as follows:
- 1.show all commands executed by the shell and when file transfers happen. This may give you some idea about what modules are doing internally and could be interesting to many users, even if it does not represent actionable information.
- 2.reserved
- 3.show the output of all commands run. This could be a lot of output and is often best used with --limit-hosts singlehost.example.com for debugging purposes.
When debugging playbook problems, verbosity settings work well with --limit-groups or --limit-hosts to retry a playbook with more output on a subsset of the total number of systems.
Verbosity flags are not required to show any detail about failures that result in the failure of a module call, these are shown automatically.
--help prints a friendly cheat sheet showing modes, long, and short options:
jetp --help
Last modified 3d ago