Train - Transport Interface
- Project State: Active
- Issues Response SLA: 3 business days
- Pull Request Response SLA: 3 business days
For more information on project states and SLAs, see this documentation.
Umbrella Project: Chef Foundation
Project State: Active
Issues Response Time Maximum: 14 days
Pull Request Response Time Maximum: 14 days
Train lets you talk to your local or remote operating systems and APIs with a unified interface.
It allows you to:
- execute commands via
run_command
- interact with files via
file
- identify the target operating system via
os
- authenticate to API-based services and treat them like a platform
Train supports:
- Local execution
- SSH
- WinRM
- Docker and Podman
- Mock (for testing and debugging)
- AWS as an API
- Azure as an API
- VMware via PowerCLI
- Habitat
Examples
Setup
Local
require 'train'
train = Train.create('local')
SSH
require 'train'
train = Train.create('ssh',
host: '1.2.3.4', port: 22, user: 'root', key_files: '/vagrant')
If you don't specify the key_files
and password
options, SSH agent authentication will be attempted. For example:
require 'train'
train = Train.create('ssh', host: '1.2.3.4', port: 22, user: 'root')
SSH transport has an ssh_config_file
option to set the SSH config file path. This is set by default to true
to read the values from the default SSH config file path. For example, ~/.ssh/config
, /etc/ssh_config
, /etc/ssh/ssh_config
. Precedence is given to the options set through the arguments.
WinRM
require 'train'
train = Train.create('winrm',
host: '1.2.3.4', user: 'Administrator', password: '...', ssl: true, self_signed: true)
Docker
require 'train'
train = Train.create('docker', host: 'container_id...')
You can use user
option to connect with privileged user on non root user images.
require 'train'
train = Train.create('docker', host: 'container_id...', user: 'root')
For Docker Desktop for Windows, you must enable the "Expose daemon on tcp://localhost:2375 without TLS" setting. To change the URL that train uses to connect to Docker, use the docker_url
option:
require 'train'
train = Train.create('docker', host: 'container_id...', docker_url: 'tcp://localhost:1234')
Windows Docker containers require PowerShell, which is assumed to be installed as powershell.exe
. If it is installed as pwsh
, use the --shell-command
option to specify pwsh
as the shell.
Podman
require 'train'
train = Train.create('podman', host: 'container_id...')
require 'train'
train = Train.create('podman', host: 'container_id...', podman_url: 'tcp://localhost:1234')
To connect to a Podman container, the Podman API endpoint URL needs to set. It can be set through the podman_url
option or else Train will check for the CONTAINER_HOST environment variable. If neither is defined then Train will try to connect to the default URL, that is unix:///run/user/UID/podman/podman.sock
for non-root users and unix:///run/podman/podman.sock
for the root user. Precedence is given to options set through the arguments.
AWS
To use AWS API authentication, setup an AWS client profile to store the Access Key ID and Secret Access Key.
require 'train'
train = Train.create('aws', region: 'us-east-2', profile: 'my-profile')
You may also use the standard AWS CLI environment variables, AWS_ACCESS_KEY_ID
, AWS_SECRET_ACCESS_KEY
and AWS_REGION
.
require 'train'
train = Train.create('aws')
VMware
require 'train'
Train.create('vmware', viserver: '10.0.0.10', user: 'demouser', password: 'securepassword')
You may also use environment variables by setting VISERVER
, VISERVER__USERNAME
, and VISERVER_PASSWORD
require 'train'
Train.create('vmware')
Configuration
To get a list of available options for a plugin:
puts Train.options('ssh')
This will provide all configuration options:
{
:host => { :required => true},
:port => { :default => 22, :required => true},
:user => { :default => "root", :required => true},
:keys => { :default => nil},
:password => { :default => nil},
...
Usage
# start or reuse a connection
conn = train.connection
# run a command on Linux/Unix/Mac
puts conn.run_command('whoami').stdout
# get OS info
puts conn.os[:family]
puts conn.os[:release]
# access files
puts conn.file('/proc/version').content
# access specific API client functionality
ec2_client = train.connection.aws_client(Aws::EC2::Client)
puts ec2_client.describe_instances
# close the connection
conn.close
Testing
We perform unit
, integration
and windows
tests.
unit
tests ensure the intended behaviour of the implementationintegration
tests run against VMs and docker containerswindows
tests that run on appveyor for windows integration tests
Mac/Linux
bundle exec ruby -W -Ilib:test/unit test/unit/extras/stat_test.rb
Windows
# run windows tests
bundle exec rake test:windows
# run single tests
bundle exec ruby -I .\test\windows\ .\test\windows\local_test.rb
Kudos and Contributors
Train is heavily based on the work of:
-
by Adam Jacob, Chef Software Inc. and a great community of contributors
We also want to thank halo who did a great contribution by handing over the train
gem name.
Contributing
- Fork it
- Create your feature branch (git checkout -b my-new-feature)
- Commit your changes (git commit -am 'Add some feature')
- Push to the branch (git push origin my-new-feature)
- Create new Pull Request
License
| Author: | Dominik Richter ([email protected])
| Author: | Christoph Hartmann ([email protected])
| Copyright: | Copyright (c) 2015-2019 Chef Software Inc.
| Copyright: | Copyright (c) 2015 Vulcano Security GmbH.
| License: | Apache License, Version 2.0
Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.