First pass at Authentication summary in docs.

docs/gcloud-auth.rst

@@ -0,0 +1,208 @@
+.. toctree::
+  :maxdepth: 1
+  :hidden:
+
+Authentication
+--------------
+
+=======
+Summary
+=======
+
+For the majority of cases,
+authentication should "just work"
+as credentials can be loaded implicitly
+based on the environment you're application is running in
+and therefore there is no extra code required to authenticate.
+
+When running your app in production,
+you should rely on a service account.
+If you're running your application inside Google Compute Engine or
+Google App Engine,
+the service account can be automatically discovered.
+If you're running your application elsewhere,
+you should download the service account JSON keyfile
+and point to it using an environment variable.
+
+-------------------
+Order of evaluation
+-------------------
+
+``gcloud`` will look in a bunch of different places
+for authentication credentials, in the following order:
+
+#. Credentials you explicitly set in code
+#. Credentials from an environment variable (``GOOGLE_APPLICATION_CREDENTIALS``)
+#. Credentials provided when running in Google App Engine
+#. Credentials provided when running in Google Compute Engine
+#. Credentials provided by the Cloud SDK (``gcloud auth login``)
+
+This means that you can set your credentials a bunch of different ways.
+We recommend using some form of implicitly discovered credentials
+so that your code can be written the same and
+simply run in the environment of your choice.
+
+=========================================
+Authenticating locally with the Cloud SDK
+=========================================
+
+This is the easiest way to authenticate while you're developing locally.
+
+#. Download and install the Cloud SDK (You can get the Cloud SDK at https://cloud.google.com/sdk)
+#. Authenticate using OAuth2 (``gcloud auth login``)
+#. Run your code (ie, ``python myscript.py``)
+
+
+After you do this,
+your script will look for the authentication token
+that you got when authenticating,
+and you won't need to think about authentication in your code at all.
+
+======================================
+Authenticating with a specific keyfile
+======================================
+
+----------------------------------------------
+Setting the keyfile in an environment variable
+----------------------------------------------
+
+If you have a specific JSON keyfile downloaded that you'd like to use,
+you can simply set the path to this in
+the ``GOOGLE_APPLICATION_CREDENTIALS`` environment variable.
+
+This means your code doesn't have to change at all,
+and can run with different credentials depending on the environment.
+
+Here's what this looks like:
+
+.. code-block:: bash
+
+   $ export GOOGLE_APPLICATION_CREDENTIALS="/path/to/key.json"
+   $ python
+   >>> from gcloud import pubsub
+   >>> pubsub.Topic('topic_name').create()
+
+--------------------------------------
+Setting the keyfile explicitly in code
+--------------------------------------
+
+If you really want to set a specific keyfile in code
+(maybe for a code snippet to send to a friend?)
+you can do this, but it's really not recommended.
+
+~~~~~~~~~~~~~~~~~~~~~~~~
+... using a JSON keyfile
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: python
+
+   from gcloud.credentials import get_for_service_account_json
+   from gcloud import pubsub
+
+   # Create the credentials from the keyfile and set the default connection.
+   credentials = get_for_service_account_json('/path/to/key.json')
+   connection = pubsub.Connection(credentials=credentials)
+   pubsub.set_default_connection(connection)
+
+   # Now you can interact with the service as usual.
+   pubsub.Topic('topic_name').create()
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+... using a .p12 key and client email
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: python
+
+   from gcloud.credentials import get_for_service_account_p12
+   from gcloud import pubsub
+
+   # Create the credentials from the .p12 file and set the default connection.
+   credentials = get_for_service_account_p12(
+       'special-email-for-p12@developer.gserviceaccount.com',
+       '/path/to/key.p12')
+   connection = pubsub.Connection(credentials=credentials)
+   pubsub.set_default_connection(connection)
+
+   # Now you can interact with the service as usual.
+   pubsub.Topic('topic_name').create()
+
+=====================================
+Authenticating from inside GCE or GAE
+=====================================
+
+If you're application is inside
+Google Compute Engine or Google App Engine,
+no extra work is needed.
+You should simply write your code as though you've already authenticated
+as we can discover your credentials and Project ID automatically.
+
+The following code should "just work" inside GAE or GCE:
+
+.. code-block:: python
+
+   from gcloud import pubsub
+   pubsub.Topic('topic_name').create()
+
+---------------------------------------
+Using a different key inside GCE or GAE
+---------------------------------------
+
+You might be running inside GCE or GAE but want to
+use a different Service Account.
+In that case, jump up to the section about
+using a specific keyfile.
+Thanks to the order of evaluation,
+the keyfile you specify explicitly or via the environment variable
+will take precedence over the automatically discovered key in the
+App Engine or Compute Engine environment.
+
+=============================================
+Using multiple credentials in the same script
+=============================================
+
+There may be times where you want to use
+multiple different sets of credentials inside the same script.
+To do this, you should create miltiple connections
+and specify which to use on the various API calls you make.
+
+For example, here is how you would create two Pub/Sub topics
+in two different projects
+with two different sets of credentials.
+
+.. code-block:: python
+
+   from gcloud import pubsub
+   from gcloud.credentials import get_for_service_account_json
+
+   # Create two different credentials.
+   credentials1 = get_for_service_account_json('key1.json')
+   credentials2 = get_for_service_account_json('key2.json')
+
+   # Create two different connections.
+   connection1 = pubsub.Connection(credentials=credentials1)
+   connection2 = pubsub.Connection(credentials=credentials2)
+
+   # Create two different topics.
+   pubsub.Topic('topic1', connection=connection1).create()
+   pubsub.Topic('topic2', connection=connection2).create()
+
+If you have one "main" set of credentials
+and others are "one-offs" for special cases,
+you can avoid all this typing
+by using the default connection for the main set,
+and separate connections for the others.
+
+Using the same example as before,
+and assuming ``'key1.json'`` is the "main" set of credentials,
+here's what that same code might look like.
+
+.. code-block:: python
+
+   from gcloud import pubsub
+   from gcloud.credentials import get_for_service_account_json
+
+   credentials2 = get_for_service_account_json('key2.json')
+   connection2 = pubsub.Connection(credentials=credentials2)
+
+   pubsub.Topic('topic1').create()
+   pubsub.Topic('topic2', connection=connection2).create()

docs/index.rst

@@ -3,6 +3,7 @@
   :hidden:
 
   gcloud-api
+  gcloud-auth
   datastore-api
   datastore-entities
   datastore-keys