1==========================================
2 Using os-client-config in an Application
3==========================================
4
5Usage
6-----
7
8The simplest and least useful thing you can do is:
9
10.. code-block:: python
11
12  python -m os_client_config.config
13
14Which will print out whatever if finds for your config. If you want to use
15it from python, which is much more likely what you want to do, things like:
16
17Get a named cloud.
18
19.. code-block:: python
20
21  import os_client_config
22
23  cloud_config = os_client_config.OpenStackConfig().get_one_cloud(
24      'internap', region_name='ams01')
25  print(cloud_config.name, cloud_config.region, cloud_config.config)
26
27Or, get all of the clouds.
28
29.. code-block:: python
30
31  import os_client_config
32
33  cloud_config = os_client_config.OpenStackConfig().get_all_clouds()
34  for cloud in cloud_config:
35      print(cloud.name, cloud.region, cloud.config)
36
37argparse
38--------
39
40If you're using os-client-config from a program that wants to process
41command line options, there is a registration function to register the
42arguments that both os-client-config and keystoneauth know how to deal
43with - as well as a consumption argument.
44
45.. code-block:: python
46
47  import argparse
48  import sys
49
50  import os_client_config
51
52  cloud_config = os_client_config.OpenStackConfig()
53  parser = argparse.ArgumentParser()
54  cloud_config.register_argparse_arguments(parser, sys.argv)
55
56  options = parser.parse_args()
57
58  cloud = cloud_config.get_one_cloud(argparse=options)
59
60Constructing OpenStack SDK object
61---------------------------------
62
63If what you want to do is get an OpenStack SDK Connection and you want it to
64do all the normal things related to clouds.yaml, `OS_` environment variables,
65a helper function is provided. The following will get you a fully configured
66`openstack.connection.Connection` instance.
67
68.. code-block:: python
69
70  import os_client_config
71
72  sdk = os_client_config.make_sdk()
73
74If you want to do the same thing but on a named cloud.
75
76.. code-block:: python
77
78  import os_client_config
79
80  sdk = os_client_config.make_sdk(cloud='mtvexx')
81
82If you want to do the same thing but also support command line parsing.
83
84.. code-block:: python
85
86  import argparse
87
88  import os_client_config
89
90  sdk = os_client_config.make_sdk(options=argparse.ArgumentParser())
91
92It should be noted that OpenStack SDK has ways to construct itself that allow
93for additional flexibility. If the helper function here does not meet your
94needs, you should see the `from_config` method of
95`openstack.connection.Connection <https://docs.openstack.org/openstacksdk/latest//user/guides/connect_from_config.html>`_
96
97Constructing shade objects
98--------------------------
99
100If what you want to do is get a
101`shade <https://docs.openstack.org/infra/shade/>`_ OpenStackCloud object, a
102helper function that honors clouds.yaml and `OS_` environment variables is
103provided. The following will get you a fully configured `OpenStackCloud`
104instance.
105
106.. code-block:: python
107
108  import os_client_config
109
110  cloud = os_client_config.make_shade()
111
112If you want to do the same thing but on a named cloud.
113
114.. code-block:: python
115
116  import os_client_config
117
118  cloud = os_client_config.make_shade(cloud='mtvexx')
119
120If you want to do the same thing but also support command line parsing.
121
122.. code-block:: python
123
124  import argparse
125
126  import os_client_config
127
128  cloud = os_client_config.make_shade(options=argparse.ArgumentParser())
129
130Constructing REST API Clients
131-----------------------------
132
133What if you want to make direct REST calls via a Session interface? You're
134in luck. A similar interface is available as with `openstacksdk` and `shade`.
135The main difference is that you need to specify which service you want to
136talk to and `make_rest_client` will return you a keystoneauth Session object
137that is mounted on the endpoint for the service you're looking for.
138
139.. code-block:: python
140
141  import os_client_config
142
143  session = os_client_config.make_rest_client('compute', cloud='vexxhost')
144
145  response = session.get('/servers')
146  server_list = response.json()['servers']
147
148Constructing Legacy Client objects
149----------------------------------
150
151If you want get an old-style Client object from a python-\*client library,
152and you want it to do all the normal things related to clouds.yaml, `OS_`
153environment variables, a helper function is also provided. The following
154will get you a fully configured `novaclient` instance.
155
156.. code-block:: python
157
158  import os_client_config
159
160  nova = os_client_config.make_client('compute')
161
162If you want to do the same thing but on a named cloud.
163
164.. code-block:: python
165
166  import os_client_config
167
168  nova = os_client_config.make_client('compute', cloud='mtvexx')
169
170If you want to do the same thing but also support command line parsing.
171
172.. code-block:: python
173
174  import argparse
175
176  import os_client_config
177
178  nova = os_client_config.make_client(
179      'compute', options=argparse.ArgumentParser())
180
181If you want to get fancier than that in your python, then the rest of the
182API is available to you. But often times, you just want to do the one thing.
183