Playable

Note: This project needs help in development. If you are interested please join our slack group at: https://join.slack.com/t/kodekloud/shared_invite/enQtNDY2NzI2OTY1NTIxLTQ5NjM1NTg2MDlmMDBhYWY3MWI2NmMwYzA4YTkyY2JiZmRjMTE4ZmU5NzA5ODIzMDc2YzcyZGZlYTgwYTY4ODg

Note: Only compatible with Ansible version - <2.4.

Playable is an Ansible Playbook generator UI developed in MEAN stack using Yeoman angular-fullstack-generator and built using Docker. The tool may be used by an individual or a team to

Generate Ansible Playbooks
Easily Search and import roles from Galaxy or Github
Execute and Test Playbooks (Not available in the publicly hosted version)
Develop custom modules and test them
All the above while enforcing Ansible Best Practices

This is a fun project I started working on from my experience working with Ansible and developing custom modules, hoping that it will help the Ansible community.

Note: This project is in its initial Alpha release. Hence this is only to be used for test purpose and at your own risk.

Demo

Try a publicly hosted live demo at ansible-playable.com

Note: You may create projects and playbooks. But cannot execute or test them. For this you must host a private version of the tool yourself, following instructions below

Getting Started

The easiest way to get started is to use Docker. The latest version of the software is built using docker and is available at Docker hub

Run the image to get started

  docker run -p 80:8080 mmumshad/ansible-playable

Remember to use port mapping to map http port to external host.

Once the docker container is running visit http://<docker host> to access the web portal.

The above command should only be used for testing purpose as the changes you make are not saved. The projects you create are not retained after restarting docker container.

To persist data across docker container restarts use the below command to map volumes from docker container on the docker host.

  docker run -p 80:8080 -v /data/db:/data/db -v /opt/ansible-projects:/opt/ansible-projects mmumshad/ansible-playable

This command creates two volume maps - /data and /opt/ansible-projects. These directories must pre-exist on the docker host. All changes made by the docker container will now be stored in these folders.

Checkout Advanced Topics below for more details

Features

The tool currently supports the following features and functionality:

Ansible Engine
- Add one Ansible Engine/s (Ansible Controller) per project
- Test connectivity to Ansible Engine
- Identify Ansible version
Ansible Projects
- Create/Edit/Delete Ansible Projects
- Define Ansible Inventory files and variables
- View and edit project files
- Create Playbooks
- Create Plays and Tasks
- List all available modules
- Show module descriptions and parameters. Automatically identify parameters from documentation. (Provided the module was documented correctly in the standard format)
- List defined variables and values from inventory files as module parameters
- Search Roles from Github/Ansible Galaxy
- Show ReadMe file of roles in HTML format
- Import Roles from Github/Ansible Galaxy
Playbook Execution
- Execute playbooks - individual or full
  - Select custom verbose level
  - Select custom hosts
- View Ansible output in the UI
- Test imported Roles
- View previous execution results
Custom Modules
- Auto generate custom module template as per best practice
- Auto update documentation and parameter section based on user input
- Provides default properties and available types in UI
- Test developed custom module
Admin
- View list of users
- Delete Users
- View System and Server logs from the Admin tab

Advanced options

Some advanced options on customizing execution are given below

External database

By default the web application uses a local mongodb instance. To use an external instance of MongoDB provide a different environmental variable using the -e parameter in docker command

  docker run -p 80:8080 -e MONGODB_URI=mongodb://dbuser:password@test.mlab.com/ansible-playable mmumshad/ansible-playable

S3 storage for projects data

By default all ansible projects and files are stored at location /opt/ansible-projects. You may map volume using docker run parameter -v to map a local volume on host to this directory. In case you need this to be on an external S3 store, set the below environment variables:

- AWS_ACCESS_KEY_ID=KEY
- AWS_SECRET_ACCESS_KEY=SECRET_KEY
- MOUNT_S3=True
- S3_PATH=ansible-playable-storage/data

Example Command:

   docker run -p 80:8080 -e AWS_ACCESS_KEY_ID=KEY -e - AWS_SECRET_ACCESS_KEY=SECRET_KEY -e MOUNT_S3=True -e S3_PATH=ansible-playable-storage/data mmumshad/ansible-playable

Authentication

To configure Google Authentication provide the below keys:

- DOMAIN=http://ansible-playable.com
- GOOGLE_ID=ID
- GOOGLE_SECRET=SECRET

Note: you must first configure google authentication and gather the GOOGLE_ID and GOOGLE_SECRET for this.

Admin user account

By default the local admin account is created and the email used is "admin@example.com" and the password is "admin". Provide the below environment variables to use a different password or to recreate admin and test account

- SEED_DB=true
- EMAIL_USER_ADMIN=admin@playable.com
- PASSWORD_ADMIN=ADMIN_PASSWORD
- EMAIL_USER_TEST=test@playable.com
- PASSWORD_TEST=TEST_ACCOUNT_PASSWORD

Prerequisites

With Docker

A host with docker installed. For instructions on installing Docker on host please check here

Without Docker

Without Docker you will have to setup the system manually:

Install the following dependencies

Git
Node.js and npm Node >= 4.x.x, npm >= 2.x.x
Gulp (npm install --global gulp)
MongoDB - Keep a running daemon with mongod
Ansible

The Dockerfile in this code repository will give you the exact instructions to install dependencies and setup environment

Developing

Run npm install to install server dependencies.
Run mongod in a separate shell to keep an instance of the MongoDB Daemon running
Run gulp serve to start the development server. It should automatically open the client in your browser when ready.

Build & development

Run gulp build for building and gulp serve for preview.

Testing

Running gulp test will run the unit tests with karma.

Limitations

Only compatible with Ansible version - <2.4.

Improvements

Improve Logging
Improve Testing - add additional test cases
Improve Security
Sharing projects with multiple users
Implement Vault Support
Integration with Active Directory/LDAP
Improve Collaboration
- Sharing projects between multiple users
- GIT integration

License

MIT License

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

thenam153/ansible-playable