Skip to content

Latest commit

 

History

History
128 lines (89 loc) · 3.73 KB

README.md

File metadata and controls

128 lines (89 loc) · 3.73 KB
Raw

knife-bastion

Code Climate Gem Version

This plugin allows Knife to access Chef server over a secure SSH connection, without exposing Chef server port to your VPN network.

Installation

If you're using ChefDK, install knife-bastion into the Chef omnibus:

chef gem install knife-bastion

If you're using rubygems to manage your Chef repository dependencies, add this line to your Chef repository's Gemfile:

gem 'knife-bastion'

And then execute:

$ bundle

Or install it yourself as:

$ gem install knife-bastion

Usage

Configure your bastion server in .chef/knife.rb (at the bottom):

# ...
# your knife configurations goes here
# ...

# Bastion host SSH settings
knife[:bastion_host] = "bastion.mycorp.net"
knife[:bastion_user] = ENV["MYCORP_USER"] || ENV["CHEF_USER"] || ENV["USER"]

# If you have multiple networks, that require different MFA tokens, specify
# each network name here. (This configuration is referenced to clarify the
# token a user should employ.)
# knife[:bastion_network] = "mynet"

# By default, the proxy server is created on port 4443. You may configure the
# local bastion port here:
# knife[:bastion_local_port] = 4443

require "knife-bastion/activate"

Now, your workflow will look like this:

  1. Run knife bastion start - this command will establish SSH connection to bastion box for 10 minutes, and create a SOCKS proxy on port 4443, that will forward all Chef requests to Chef server via bastion box.
  2. Use Chef to do your work.
  3. At any time you can use knife bastion status - which will verify the proxy and make sure everything works as expected.
  4. After you finished, run knife bastion stop to shutdown the connection and turn off the proxy. If you forget to do this, it will die automatically after 10 minutes.

Sometimes when you work on a big change, default timeout of 10 minutes is too short. You can increase timeout with --timeout flag:

knife bastion start --timeout 1800

Maximum timeout is 3600 (1 hour) for security reasons. You can re-establish bastion connection by executing knife bastion start (if the connection is currently active, it will be forcibly closed.)

Bastion troubleshooting

If something is not right, you need to ensure you have access to bastion box. Try connecting to bastion.mycorp.net via SSH:

ssh ${MYCORP_USER-$USER}@bastion.mycorp.net

Check current bastion connection status (it will tell you if there is anything wrong with your box):

knife bastion status

Using knife-bastion Outside of Chef

This gem can be used to connect to any server utilizing generic proxy client. The bastion should be started the same way as it is described above.

Example:

require 'knife-bastion/client_proxy'
require 'rest_client'

# initialize RestClient::Resource object and wrap it into a bastion proxy
api = KnifeBastion::ClientProxy.new(
  RestClient::Resource.new('https://domain.com/api/v1')
)

# use api the same way as it would be used as a RestClient::Resource
api['posts/1/comments'].post 'Good article.', content_type: 'text/plain'

Contributing

  1. Fork it
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Add some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create new Pull Request

Bug reports and pull requests are welcome on GitHub at https://github.com/eligible/knife-bastion.

License

The gem is available as open source under the terms of the MIT License.