appforce-ssh-manager

Ansible tool to manage the deployment of ssh keys and user profiles to client servers

gem appforce-spawn

Installation

The gem is published on RubyGems.org.

$ gem install appforce-spawn

This will install the gem and script.

Usage

It requires a .appforce configuration file in your home directory to operate. Once the gem is installed you can run appforce-spawn -D to dump an example config to your home directory (~/.appforce.example). This will have all you need, except for your API token. This token can be found by logging into the API Admin. If you do not have an account on the Admin, please contact Derek Smith.

The tool has help information and a list of available action commands. 

$ appforce-spawn -h
USAGE: appforce-spawn [options]
    -a, --action [ACTION]            Action to perform. Use '-l' to view all available actions
    -l, --list_actions               List available Actions
    -C, --client [CLIENT API NAME]   API Client Name to use for calls
    -c, --config [PATH]              Optional custom config file
    -D, --dump-config                Generate a example config template (to ~/.appforce.example)
    -v, --verbose                    If set, print verbose output
    -h, --help                       Show help documentation

$ appforce-spawn -l
 == Available Actions ==
 clients          # Retrieve a complete list of Clients
 generate         # Build out the Ansible template for a Client (client API name is required)
 client:hosts     # Retrieve a Hosts file for a Client (client API name is required)
 client:users     # Retrieve a Users file for a Client (client API name is required)
 client:vars      # Retrieve a Vars file for a Client (client API name is required)
 ping             # Test connection to host and API access
 ping:host        # Test if API is available
 ping:api         # Test if you have access to the API
 spawn            # Run Ansible Playbook to spawn users to Client hosts
 spawn:command    # Display Ansible command to run Playbook for a Client
 spawn:ping       # Ansible ping Client hosts in the 'hosts' file
 spawn:ping:command # Display ansible ping command
 =========================

Typical Workflow

  • appforce-spawn -a clients will return the list of available clients and API names for those clients.
  • appforce-spawn -a generate -C [Client API Name] will generate the Ansible template for that client, making directories and downloading files.
  • cd [Client API Name] change into the template directory that was just created.
  • appforce-spawn -a spawn:ping will test the configuration that was just downloaded as well as connectivity to the Client hosts.
  • appforce-spawn -a spawn will run the Ansible Playbook to generate the User Groups, Users and set permissions.

Testing Locally

Notes

Helpful Ansible introduction

For Mac use Homebrew (brew):

$ brew update
$ brew install ansible

You will need the vagrant-triggers gem in order to properly teardown the test cluster. Just run the following command to install: vagrant plugin install vagrant-triggers

Test structure will be a Single Test VM connecting to a Cluster of Test VMs.

You should add vagrant/config/users/local.key to assume-unchanged in order to let users add their own ssh keys for inspecting test env. Use the following command:

$ git update-index --assume-unchanged vagrant/config/users/local.key

How to Run Tests

You will need to have vagrant, a VM provider (VirtualBox will do) and ansible installed.

  1. Ensure you have the required vagrant triggers module installed
    • vagrant plugin install vagrant-triggers
  2. Build Vagrant test cluster. This will take some time.
    • cd vagrant/ && vagrant up
  3. Change dirs to Ansible root and install Ansible RVM role.
    • cd ../ansible && ansible-galaxy install rvm_io.rvm1-ruby
  4. Run the playbook.
    • ansible-playbook -i test site.yml --extra-vars="users_file=../vagrant/etc/users.yml"
  5. Now, go to the vagrant root and ssh to the nexus VM
    • cd ../vagrant && vagrant ssh nexus
  6. From here you can sudo su - [USER] to the users that were just created (derek, brown, melissa, cage)
  7. Once a new user, ssh to any of the 4 nodes in the cluster. You will need to accept the SSH fingerprint and that's it.
  8. Check the group settings by typing groups. synctree-admin has sudo permissions while synctree-user does not.

One command to rule them all after you have installed the plugin, to be run form the project root:

cd vagrant/ && vagrant up && cd ../ansible && ansible-galaxy install rvm_io.rvm1-ruby && ansible-playbook -i test site.yml --extra-vars="ansible_user=ansible users_file=../vagrant/etc/users.yml"

Developing appforce-spawn gem

$ gem build appforce-spawn.gemspec
$ gem install appforce-spawn-[version numnber].gem

The version number for the gem is controlled by lib/appforce/spawn/version.rb

The list of included files in the gem build is controlled by what files are included in the git index. Look at the gemspec file to see the exact command.

The appforce-spawn script resides in the bin/ directory. There is a config file located in home directory of the user (~/.appforce) that configures the appforce-spawn script.

To test connectivity with the API run:

$ appforce-spawn -a ping

Dependencies

Test:

Production:

  • Ansible
    • :godmode:
  • httparty