10000 First pass at Authentication summary in docs. · googleapis/google-cloud-python@0c9c31f · GitHub
[go: up one dir, main page]
Skip to content

Commit 0c9c31f

Browse files
jgeewaxjgeewax
committed
First pass at Authentication summary in docs.
1 parent 6283ab9 commit 0c9c31f

File tree

2 files changed

+265
-0
lines changed

2 files changed

+265
-0
lines changed

‎docs/gcloud-auth.rst

Lines changed: 264 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,264 @@
1+
.. toctree::
2+
:maxdepth: 1
3+
:hidden:
4+
5+
Authentication
6+
--------------
7+
8+
==============
9+
Quick overview
10+
==============
11+
12+
**If you're running in Compute Engine or App Engine**,
13+
authentication should "just work"
14+
as credentials can be loaded automatically
15+
and therefore there is no extra code required to authenticate.
16+
17+
**If you're developing locally**,
18+
the easiest way to authenticate is using the Cloud SDK.
19+
20+
**If you're running your application elsewhere**,
21+
you should download the service account JSON keyfile
22+
and point to it using an environment variable.
23+
24+
-----------------------------------------------
25+
In what order does gcloud discover credentials?
26+
-----------------------------------------------
27+
28+
``gcloud`` will look in a bunch of different places
29+
for authentication credentials, in the following order:
30+
31+
#. Credentials you explicitly set in code
32+
#. Credentials from an environment variable (``GOOGLE_APPLICATION_CREDENTIALS``)
33+
#. Credentials provided by the Cloud SDK (``gcloud auth login``)
34+
#. Credentials provided when running in Google App Engine
35+
#. Credentials provided when running in Google Compute Engine
36+
37+
This means that you can set your credentials a bunch of different ways.
38+
We recommend using some form of implicitly discovered credentials
39+
(ie, set in an environment variable or auto-discovered in GCE/GAE)
40+
so that your code can be written the same and
41+
simply run in the environment of your choice.
42+
43+
=========================================
44+
Authenticating locally with the Cloud SDK
45+
=========================================
46+
47+
This is the easiest way to authenticate while you're developing locally.
48+
49+
#. Download and install the Cloud SDK (You can get the Cloud SDK at https://cloud.google.com/sdk)
50+
#. Authenticate using OAuth2 (``gcloud auth login``)
51+
#. Run your code (ie, ``python myscript.py``)
52+
53+
54+
After you do this,
55+
your script will look for the authentication token
56+
that you got when authenticating,
57+
and you won't need to think about authentication in your code at all.
58+
59+
======================================
60+
Authenticating with a specific keyfile
61+
======================================
62+
63+
----------------------------------------------
64+
Setting the keyfile in an environment variable
65+
----------------------------------------------
66+
67+
If you have a specific JSON keyfile downloaded that you'd like to use,
68+
you can simply set the path to this in
69+
the ``GOOGLE_APPLICATION_CREDENTIALS`` environment variable.
70+
71+
This means your code doesn't have to change at all,
72+
and can run with different credentials depending on the environment.
73+
74+
Here's what this looks like:
75+
76+
.. code-block:: bash
77+
78+
$ export GOOGLE_APPLICATION_CREDENTIALS="/path/to/key.json"
79+
$ python
80+
>>> from gcloud import pubsub
81+
>>> pubsub.Topic('topic_name').create()
82+
83+
--------------------------------------
84+
Setting the keyfile explicitly in code
85+
--------------------------------------
86+
87+
If you really want to set a specific keyfile in code
88+
(maybe for a code snippet to send to a friend?)
89+
you can do this, but it's really not recommended.
90+
91+
~~~~~~~~~~~~~~~~~~~~~~~~
92+
... using a JSON keyfile
93+
~~~~~~~~~~~~~~~~~~~~~~~~
94+
95+
.. code-block:: python
96+
97+
from gcloud.credentials import get_for_service_account_json
98+
from gcloud import pubsub
99+
100+
# Create the credentials from the keyfile and set the default connection.
101+
credentials = get_for_service_account_json('/path/to/key.json')
102+
connection = pubsub.Connection(credentials=credentials)
103+
pubsub.set_default_connection(connection)
104+
105+
# Now you can interact with the service as usual.
106+
pubsub.Topic('topic_name').create()
107+
108+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
109+
... using a .p12 key and client email
110+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
111+
112+
.. code-block:: python
113+
114+
from gcloud.credentials import get_for_service_account_p12
115+
from gcloud import pubsub
116+
117+
# Create the credentials from the .p12 file and set the default connection.
118+
credentials = get_for_service_account_p12(
119+
'special-email-for-p12@developer.gserviceaccount.com',
120+
'/path/to/key.p12')
121+
connection = pubsub.Connection(credentials=credentials)
122+
pubsub.set_default_connection(connection)
123+
124+
# Now you can interact with the service as usual.
125+
pubsub.Topic('topic_name').create()
126+
127+
=====================================
128+
Authenticating from inside GCE or GAE
129+
=====================================
130+
131+
If you're application is inside
132+
Google Compute Engine or Google App Engine,
133+
no extra work is needed.
134+
You should simply write your code as though you've already authenticated
135+
as we can discover your credentials and Project ID automatically.
136+
137+
The following code should "just work" inside GAE or GCE:
138+
139+
.. code-block:: python
140+
141+
from gcloud import pubsub
142+
pubsub.Topic('topic_name').create()
143+
144+
---------------------------------------
145+
Using a different key inside GCE or GAE
146+
---------------------------------------
147+
148+
You might be running inside GCE or GAE but want to
149+
use a different Service Account.
150+
In that case, jump up to the section about
151+
using a specific keyfile.
152+
Thanks to the order of evaluation,
153+
the keyfile you specify explicitly or via the environment variable
154+
will take precedence over the automatically discovered key in the
155+
App Engine or Compute Engine environment.
156+
157+
=============================================
158+
Using multiple credentials in the same script
159+
=============================================
160+
161+
There may be times where you want to use
162+
multiple different sets of credentials inside the same script.
163+
To do this, you should create miltiple connections
164+
and specify which to use on the various API calls you make.
165+
166+
For example, here is how you would create two Pub/Sub topics
167+
in two different projects
168+
with two different sets of credentials.
169+
170+
.. code-block:: python
171+
172+
from gcloud import pubsub
173+
from gcloud.credentials import get_for_service_account_json
174+
175+
# Create two different credentials.
176+
credentials1 = get_for_service_account_json('key1.json')
177+
credentials2 = get_for_service_account_json('key2.json')
178+
179+
# Create two different connections.
180+
connection1 = pubsub.Connection(credentials=credentials1)
181+
connection2 = pubsub.Connection(credentials=credentials2)
182+
183+
# Create two different topics.
184+
pubsub.Topic('topic1', project='project1', connection=connection1).create()
185+
pubsub.Topic('topic2', project='project2', connection=connection2).create()
186+
187+
If you have one "main" set of credentials
188+
and others are "one-offs" for special cases,
189+
you can avoid all this typing
190+
by using the default connection for the main set,
191+
and separate connections for the others.
192+
193+
Using the same example as before,
194+
and assuming ``'key1.json'`` is the "main" set of credentials,
195+
here's what that same code might look like.
196+
197+
.. code-block:: python
198+
199+
from gcloud import pubsub
200+
from gcloud.credentials import get_for_service_account_json
201+
202+
credentials2 = get_for_service_account_json('key2.json')
203+
connection2 = pubsub.Connection(credentials=credentials2)
204+
205+
pubsub.Topic('topic1').create()
206+
pubsub.Topic('topic2', project='project2', connection=connection2).create()
207+
208+
===============
209+
Troubleshooting
210+
===============
211+
212+
--------------------------------------------------
213+
You keep mentioning key.json... How do I get that?
214+
--------------------------------------------------
215+
216+
When we say ``key.json``
217+
we're referring to what we call a "Service Account".
218+
These are sort of like passwords
219+
which let you access the different cloud services.
220+
221+
Service Accounts are pretty easy to create,
222+
just head over to the `Credentials`_ page
223+
in the `Google Developers Console`_,
224+
create a new Client ID,
225+
and generate a new JSON key.
226+
227+
If you're a bit confused,
228+
take a look at the step by step guide here:
229+
https://cloud.google.com/storage/docs/authentication#service_accounts
230+
231+
----------------------------------------------------------------
232+
I'm running in Compute Engine, but can't access Datastore. Help?
233+
----------------------------------------------------------------
234+
235+
When you create your Compute Engine instance,
236+
you need to specify which services this particular instance has access to
237+
(you might not want all of your machines to access Datastore for example).
238+
239+
To do this,
240+
click on "Show advanced options" on the "New Instance" page
241+
(at the top of the screen, towards the right),
242+
scroll down to the section called "Project Access",
243+
and set the appropriate access
244+
for the service you want your VM to have
245+
(ie, Datastore -> Enabled).
246+
247+
.. note::
248+
249+
Unfortunately,
250+
you can't change these settings after the VM is created. :(
251+
Hopefully Google will change this in the future.
252+
253+
-------------------------------
254+
I'm still having trouble. Help?
255+
-------------------------------
256+
257+
If you're having trouble authenticating,
258+
feel free to open a `Github Issue`_ on this project
259+
and hopefully we can help
260+
(and add the answer to your question here).
261+
262+
.. _Google Developers Console: https://console.developers.google.com/project
263+
.. _Credentials: https://pantheon.corp.google.com/project/_/apiui/credential
264+
.. _Github Issue: https://github.com/GoogleCloudPlatform/gcloud-python/issues/new?title=I+need+help+with+auth!

‎docs/index.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@
33
:hidden:
44

55
gcloud-api
6+
gcloud-auth
67
datastore-api
78
datastore-entities
89
datastore-keys

0 commit comments

Comments
 (0)
0