ManageIQ · himdel · Dec 8, 2017 · Dec 11, 2017 · Dec 11, 2017 · Jan 21, 2019
diff --git a/README.md b/README.md
@@ -10,6 +10,7 @@
  - [Providers development guide](providers/dev-guide.md)
  - Provider setup instructions
  - [Amazon AWS](providers/amazon_aws_config.md)
+ - [Embedded Ansible](providers/embedded_ansible.md)
  - [Openshift](providers/openshift.md)
  - [Openstack Infra](providers/openstack_infra_provider.md)
  - [Interactive debugging with Pry-Remote](developer_setup/debugging.md)

diff --git a/providers/embedded_ansible.md b/providers/embedded_ansible.md
@@ -0,0 +1,227 @@
+## Embedded Ansbile - via AWX in a docker container
+
+ManageIQ supports more than one way (`manageiq/lib/embedded_ansible*`) of connecting to the Embedded Ansible provider.
+
+Here, we'll set up `DockerEmbeddedAnsible`, introduced in [ManageIQ/manageiq#16205](https://github.com/ManageIQ/manageiq/pull/16205) - this will download an awx docker container, and set local manageiq to connect to it.
+
+
+
+### Dependencies
+
+You need docker.
+
+On a mac, you also need `docker-machine`:
+
+```
+brew install docker docker-machine
+
+# read the output and start the service
+
+# run this in your .bashrc, or every shell where needed
+eval `docker-machine env default`
+```
+
+
+### DB config
+
+Your PostgreSQL must be configured to allow connections from the docker container, so that AWX can connect to manageiq's database.
+
+Your ManageIQ DB user (the one in `manageiq/config/database.yml`) must have the `SUPERUSER` privilege (or at least needs to be able to create roles and databases).
+
+
+Config file locations (where to expect it):
+
+ * Debian: `/etc/postgresql/9.6/main/`
+ * Fedora: `/var/lib/pgsql/data/`
+ * MacOSX: `/usr/local/var/postgres/`
+
+Note that these may depend on your version, or oven on how you installed PostgreSQL.
+If you still can't find the right location, you may have luck running `psql -d postgres -c 'show config_file'`.
+
+
+
+Make sure your `postgresql.conf` contains this line:
+
+```
+listen_addresses = '*'
+```
+
+
+Make sure your `pg_hba.conf` contains:
+
+```
+host all all 172.17.0.1/24 md5
+```
+
+Note: that `172.17.0.1/24` may depend on the address of your docker network interface - run `ip addr show dev docker0` and you should see an `inet` line with a similar address - use that.
+
+
+Mac users: you may also need to add this one, for `docker-machine`.
+
+```
+host all all 192.168.99.0/24 md5
+```
+
+
+Ensure your DB user (the one in `config/database.yml`) has `superuser` rights..
+
+ * Debian: `sudo su - postgres -c psql -c 'ALTER ROLE "root" SUPERUSER'`
+ * Fedora / MacOSX: `psql -c 'ALTER ROLE "root" SUPERUSER' postgres`
+
+
+### Clean up
+
+If you've already set up an AWX instance this way and want to clean it up:
+
+```
+psql -d postgres -c 'DROP DATABASE awx'
+psql -d postgres -c 'DROP ROLE awx'
+bin/rake evm:db:reset
+bin/rake db:seed
+```
+
+
+If you had previously added an embedded ansible using the [old way](http://talk.manageiq.org/t/howto-setup-embedded-ansible/2291/5?u=himdel), you'll need to clean up the provider (in Rails console):
+
+```
+ManageIQ::Providers::EmbeddedAnsible::Provider.first.destroy!
+```
+
+
+In both cases, you may also need to clean up the old authentications (in Rails console):
+
+```
+db = MiqDatabase.first
+db.authentication_type('ansible_secret_key').delete # db.ansible_secret_key.delete
+db.ansible_rabbitmq_authentication.delete
+db.ansible_admin_authentication.delete
+db.ansible_database_authentication.delete
+```
+
+
+### Procfiles
+
+Under your `manageiq/` directory, there should be a `Procfile.example` file.
+
+You need to uncomment these lines:
+
+```
+generic: ruby lib/workers/bin/run_single_worker.rb MiqGenericWorker
+ansible: ruby lib/workers/bin/run_single_worker.rb EmbeddedAnsibleWorker
+embedded_ansible_refresh: ruby lib/workers/bin/run_single_worker.rb --ems-id <id> ManageIQ::Providers::EmbeddedAnsible::AutomationManager::RefreshWorker
+embedded_ansible_event: ruby lib/workers/bin/run_single_worker.rb --ems-id <id> ManageIQ::Providers::EmbeddedAnsible::AutomationManager::EventCatcher
+```
+
+And you'll need to replace that `<id>` with the id of the newly created **manager** instance (`ManageIQ::Providers::EmbeddedAnsible::AutomationManager`, not `ManageIQ::Providers::EmbeddedAnsible::Provider`).
+
+
+### Setting it up
+
+ * configure your server to enable the ansible role (from Rails console):
+
+```
+server = MiqServer.my_server(true)
+server.role = "embedded_ansible,ems_inventory,ems_operations,event"
+server.activate_roles(%w(embedded_ansible ems_inventory ems_operations event))
+server.save!
+```
+
+ * run rails: `bin/rails s`
+
+ * run the worker that will download and set up the container: `foreman start -f Procfile.example` (only the `ansible` worker is needed at this point).
+
+ * grab a coffee or two - you can watch the progress by watching:
+ * authentication errors, docker problems: `tail -f managiq/log/evm.log`
+ * running containers: `docker ps`
+ * container logs: `docker logs -f awx_web`
+ * seeing awx initial upgrade progress `localhost:54321`
+
+ * once everything suceeded, you should see `Finished starting embedded ansible service.` in `evm.log`
+
+ * if you got that far, AWX is running and ManageIQ has an EmbeddedAnsible provider instance
+
+ * you need to edit `Procfile.example`, to replace that `<id>` with the actual id of the new manager (not provider) instance:
+
+```
+ManageIQ::Providers::EmbeddedAnsible::Provider.first.managers.first.id
+```
+
+ * run `foreman start -f Procfile.example`
+
+ * try adding a Repository in ManageIQ (Automate > Ansible > Repositories) :)
+
+
+If you're on MacOSX, you will also need to run these first:
+
+```
+# redirect local 54321 to docker-machine - otherwise, localhost:54321 doesn't work
+docker-machine ssh default -L 54321:127.0.0.1:54321
+
+# inside that docker-machine ssh shell - redirect postgres from the docker machine to the real one (otherwise, awx_web can't connect to manageiq DB)
+sudo sh -c 'echo 1 > /proc/sys/net/ipv4/ip_forward'
+sudo iptables -t nat -I PREROUTING --dst 172.17.0.1 -p tcp --dport 5432 -j DNAT --to-destination 192.168.99.1:5432
+
+# don't exit the shell
+```
+
+(`172.17.0.1` is the docker host IP address, `192.168.99.1` is the adress `docker-machine` gives to the host (the VM will have `192.168.99.100` most likely), and `default` is the default name for the docker machine)
+
+(Alternately, something like `VBoxManage modifyvm "default" --natpf1 "awx,tcp,127.0.0.1,54321,,54321"` might work too.)
+
+
+### Running it again
+
+Just run these 3, each in a different terminal:
+
+```
+bin/rails s
+foreman start -f Procfile.example
+```
+
+
+On a mac, you'll also need to do the `docker-machine ssh...` command running.
+And if you've restarted the machine (or `docker-machine`) since the last time, you'll also need the `iptables...` command.
+
+
+### Connecting to AWX directly
+
+Your docker awx instance is listening on `localhost:54321`.
+
+To log in, you can use the `admin` account - to determine the password, run Rails console and do:
+
+```
+MiqDatabase.first.ansible_admin_authentication.password
+```
+
+
+### Troubleshooting
+
+ * watch `manageiq/log/evm.log`
+
+```
+# should see this in evm.log
+[----] I, [2017-12-07T11:32:46.833998 #29139:2acb0db2ef8c] INFO -- : MIQ(EmbeddedAnsibleWorker::Runner#setup_ansible) Starting embedded ansible service ...
+[----] I, [2017-12-07T11:33:06.637266 #29139:2acb0db2ef8c] INFO -- : MIQ(DockerEmbeddedAnsible#start) Waiting for Ansible container to respond
+... a whole lot of this ....
+[----] I, [2017-12-07T11:33:08.732190 #29139:2acb0db2ef8c] INFO -- : MIQ(DockerEmbeddedAnsible#start) Waiting for Ansible container to respond
+[----] I, [2017-12-07T11:33:13.530599 #29139:2acb0db2ef8c] INFO -- : MIQ(EmbeddedAnsibleWorker::Runner#setup_ansible) Finished starting embedded ansible service.
+[----] I, [2017-12-07T11:33:15.605973 #29139:2acb0db2ef8c] INFO -- : MIQ(ManageIQ::Providers::EmbeddedAnsible::Provider#with_provider_connection) Connecting through ManageIQ::Providers::EmbeddedAnsible::Provider: [Embedded Ansible]
+[----] I, [2017-12-07T11:33:16.033227 #29139:2acb0db2ef8c] INFO -- : MIQ(AuthUseridPassword#validation_successful) [Provider] [1], previously valid/invalid on: []/[], previous status: []
+```
+
+ * watch docker container output - for problems like awx not being able to connect to ManageIQ database
+
+```
+docker logs -f awx_web
+```
+
+ * watch `docker ps` output
+
+```
+# should see this in `docker ps`
+CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
+d10993d1f25b ansible/awx_task:latest "/tini -- /bin/sh ..." 6 seconds ago Up 5 seconds 8052/tcp awx_task
+b63a677d32a7 ansible/awx_web:latest "/tini -- /bin/sh ..." 7 seconds ago Up 6 seconds 0.0.0.0:54321->8052/tcp awx_web
+59806de1bcd1 memcached:alpine "docker-entrypoint..." 27 seconds ago Up 26 seconds 11211/tcp memcached
+a89aa0e4a395 rabbitmq:3 "docker-entrypoint..." 27 seconds ago Up 26 seconds 4369/tcp, 5671-5672/tcp, 25672/tcp rabbitmq
+```