Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP

Loading…

Add guide for Google Cloud Engine. #6350

Closed
wants to merge 1 commit into from

3 participants

@franckcuny

This is a first attempt to document the GCE modules.

Please bear in mind that I'm not a native speaker, but I'm more than happy to improve and update this PR.

(cc @erjohnso).

Thanks.

@mpdehaan

Very nice! This comes at a very good time actually.

I hope to get this reviewed and up this week. Thanks very much!

@mpdehaan mpdehaan self-assigned this
docsite/rst/guide_gce.rst
@@ -0,0 +1,186 @@
+ Google Web Services Guide

Google marketing folks would prefer "Google Cloud Platform Guide" if you don't mind.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
docsite/rst/guide_gce.rst
((7 lines not shown))
+------------
+
+.. note:: This section of the documentation is under construction. We are in the process of adding more examples about all of the GCE modules and how they work together.
+
+The GCE modules require the apache-libcloud module, which you can install from pip:
+
+.. code-block:: bash
+
+ $ pip install apache-libcloud
+
+.. note:: If you're using Ansible on Mac OS X, libcloud needs to access a CA cert chain. You'll need to download one (you can get one for `here <http://curl.haxx.se/docs/caextract.html>`_.)
+
+Credentials
+-----------
+
+To work with the GCE modules, you'll first need some to get some credentials. You can create new one from the `console <https://console.developers.google.com/>`_ by going to the "APIs and Auth" section. Once you've created a new client ID and downloaded the generated private key (in the pkcs2 format), you'll need to convert the key by running the following command:

...you'll first need to get some credentials. Remove extra "some".

pkcs2 -> pkcs12

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
docsite/rst/guide_gce.rst
((51 lines not shown))
+ pem_file: /path/to/project.pem
+ project_id: project-id
+ machine_type: n1-standard-1
+ image: debian-7
+ tasks:
+ - name: Launch instances
+ local_action: gce instance_names=dev machine_type={{ machine_type }} image={{ image }} service_account_email={{ service_account_email }} pem_file={{ pem_file }} project_id={{ project_id }}
+
+secrets.py
+``````````
+
+Create a file ``secrets.py`` looking like following, and put it in some folder which is in your ``$PYTHONPATH``:
+
+.. code-block:: python
+
+ GCE_PARAMS = ('i...@project.googleusercontent.com', 'secret')

Suggest using a path notation, 'secret' -> '/path/to/project.pem'

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@erjohnso

Great work @franckcuny! I had a few small suggestions but otherwise, this is really great to see and thank you!

@franckcuny

I've fixed all the suggestions. This should be good to go.

@mpdehaan

Working on merging this in now!

@mpdehaan

All merged in, I also updated this a bit to show the usage of tags rather than hostnames to manage cloud "more like cloud", and also updated somethings stylistically to make them not have to rely on "local_action" which makes formatting a little better.

Some of these changes have not had the full benefit of testing and review, so if you would like to help look these over I can easily push updates.

That all being said, this is now integrated into the docs and I'll be kicking off a docs build/push ...
NOW.

Other upgrades are of course also welcome -- like maybe crosslinking to the GCE modules pages?

Thanks very much for this, great to see the guide sections being built out further.

Much appreciated!

@mpdehaan mpdehaan closed this
@franckcuny franckcuny deleted the franckcuny:gce-doc branch
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Commits on Mar 10, 2014
  1. @franckcuny
This page is out of date. Refresh to see the latest.
Showing with 186 additions and 0 deletions.
  1. +186 −0 docsite/rst/guide_gce.rst
View
186 docsite/rst/guide_gce.rst
@@ -0,0 +1,186 @@
+ Google Cloud Platform Guide
+============================
+
+.. _gce_intro:
+
+Introduction
+------------
+
+.. note:: This section of the documentation is under construction. We are in the process of adding more examples about all of the GCE modules and how they work together.
+
+The GCE modules require the apache-libcloud module, which you can install from pip:
+
+.. code-block:: bash
+
+ $ pip install apache-libcloud
+
+.. note:: If you're using Ansible on Mac OS X, libcloud needs to access a CA cert chain. You'll need to download one (you can get one for `here <http://curl.haxx.se/docs/caextract.html>`_.)
+
+Credentials
+-----------
+
+To work with the GCE modules, you'll first need to get some credentials. You can create new one from the `console <https://console.developers.google.com/>`_ by going to the "APIs and Auth" section. Once you've created a new client ID and downloaded the generated private key (in the `pkcs12 format <http://en.wikipedia.org/wiki/PKCS_12>`_), you'll need to convert the key by running the following command:
+
+.. code-block:: bash
+
+ $ openssl pkcs12 -in pkey.pkcs12 -passin pass:notasecret -nodes -nocerts | openssl rsa -out pkey.pem
+
+There's three different ways to provide credentials to Ansible when you want to talk to Google Cloud:
+
+* by providing to the modules directly
+* by populating a ``secrets.py`` file
+* by populating the ``gce.ini`` file (for the inventory script only)
+
+Module
+``````
+
+For the GCE modules you can specify the credentials as argument:
+
+* ``service_account_email``: email associated with the project
+* ``pem_file``: path to the pem file
+* ``project_id``: id of the project
+
+For example, to create a new instance using the cloud module, you can use the following configuration:
+
+.. code-block:: yaml
+ - name: Create instance(s)
+ hosts: localhost
+ gather_facts: no
+ vars:
+ service_account_email: unique-id@developer.gserviceaccount.com
+ pem_file: /path/to/project.pem
+ project_id: project-id
+ machine_type: n1-standard-1
+ image: debian-7
+ tasks:
+ - name: Launch instances
+ local_action: gce instance_names=dev machine_type={{ machine_type }} image={{ image }} service_account_email={{ service_account_email }} pem_file={{ pem_file }} project_id={{ project_id }}
+
+secrets.py
+``````````
+
+Create a file ``secrets.py`` looking like following, and put it in some folder which is in your ``$PYTHONPATH``:
+
+.. code-block:: python
+
+ GCE_PARAMS = ('i...@project.googleusercontent.com', '/path/to/project.pem')
+ GCE_KEYWORD_PARAMS = {'project': 'project-name'}
+
+gce.ini
+```````
+
+When using the inventory script ``gce.py``, you need to populate the ``gce.ini`` file that you can find in the inventory directory.
+
+Host Inventory
+--------------
+
+The best way to interact with your hosts is to use the gce inventory plugin, which dynamically queries GCE and tells Ansible what nodes can be managed.
+
+gce.py
+++++++
+
+To use the GCE dynamic inventory script, copy ``gce.py`` from ``plugings/inventory`` into your inventory directory and make it executable. You can specify credentials for ``gce.py`` using the ``GCE_INI_PATH`` environment variable.
+
+Let's test our inventory script to see if it can talk to Google Cloud.
+
+.. code-block:: bash
+
+ $ GCE_INI_PATH=~/.gce.ini ansible all -i gce.py -m setup
+ hostname | success >> {
+ "ansible_facts": {
+ "ansible_all_ipv4_addresses": [
+ "x.x.x.x"
+ ],
+
+The recommended way to use the inventory is to create an ``inventory`` directory, and place both the ``gce.py`` script and a file containing ``localhost`` in it.
+
+Executing ``ansible`` or ``ansible-playbook`` and specifying the ``inventory`` directory instead of an individual file will cause ansible to evaluate each file in that directory for inventory.
+
+Let's test our inventory script to see if it can talk to Google Cloud:
+
+.. code-block:: bash
+
+ $ ansible all -i inventory/ -m setup
+ hostname | success >> {
+ "ansible_facts": {
+ "ansible_all_ipv4_addresses": [
+ "x.x.x.x"
+ ],
+
+The output should be similar to the previous command.
+
+Use Cases
+---------
+
+For the following use case, I'm using a small shell script as a wrapper.
+
+.. code-block:: bash
+
+ #!/bin/bash
+ PLAYBOOK="$1"
+
+ if [ -z $PLAYBOOK ]; then
+ echo "You need to pass a playback as argument to this script."
+ exit 1
+ fi
+
+ export SSL_CERT_FILE=$(pwd)/cacert.cer
+ export ANSIBLE_HOST_KEY_CHECKING=False
+
+ if [ ! -f "$SSL_CERT_FILE" ]; then
+ curl -O http://curl.haxx.se/ca/cacert.pem
+ fi
+
+ ansible-playbook -v -i inventory/ "$PLAYBOOK"
+
+
+Create an instance
+``````````````````
+
+The GCE module provides the ability to provision instances within Google Compute Engine. The provisioning task is typically performed from your Ansible control server against Google Cloud's API.
+
+A playbook would looks like this:
+
+.. code-block:: yaml
+
+ - name: Create instance(s)
+ hosts: localhost
+ gather_facts: no
+ vars:
+ machine_type: n1-standard-1 # default
+ image: debian-7
+ service_account_email: unique-id@developer.gserviceaccount.com
+ pem_file: /path/to/project.pem
+ project_id: project-id
+ tasks:
+ - name: Launch instances
+ local_action: gce instance_names=dev machine_type={{ machine_type }} image={{ image }} service_account_email={{ service_account_email }} pem_file={{ pem_file }} project_id={{ project_id }}
+ register: gce
+ - name: Wait for SSH to come up
+ local_action: wait_for host={{ item.public_ip }} port=22 delay=10 timeout=60 state=started
+ with_items: gce.instance_data
+
+Create a web server
+```````````````````
+
+With this example we will install a web server (lighttpd) on our new instance and ensure that the port 80 is open for incoming connections.
+
+.. code-block:: yaml
+
+ - name: Create a firewall rule to allow HTTP
+ hosts: dev
+ gather_facts: no
+ vars:
+ machine_type: n1-standard-1 # default
+ image: debian-7
+ service_account_email: unique-id@developer.gserviceaccount.com
+ pem_file: /path/to/project.pem
+ project_id: project-id
+ tasks:
+ - name: Install lighttpd
+ apt: pkg=lighttpd state=installed
+ sudo: True
+ - name: Allow HTTP
+ local_action: gce_net fwname=all-http name=default allowed=tcp:80 state=present service_account_email={{ service_account_email }} pem_file={{ pem_file }} project_id={{ project_id }}
+
+By pointing your browser to the IP of the server, you should see a page welcoming you.
Something went wrong with that request. Please try again.