Browse Source

Consolidate identity-domain-specific-config.rst

Consolidate from configuration.rst into identity-domain-specific-config.rst.

Change-Id: Id989342e31be31a3c5cb946ff2177ffa5a8f47a8
tags/15.0.0.0rc1
Suramya Shah 1 year ago
parent
commit
ed6366813d
2 changed files with 140 additions and 185 deletions
  1. 136
    3
      doc/source/admin/identity-domain-specific-config.rst
  2. 4
    182
      doc/source/configuration.rst

+ 136
- 3
doc/source/admin/identity-domain-specific-config.rst View File

@@ -49,6 +49,141 @@ Any domain-specific configuration options specified through the
49 49
 Identity v3 API will override domain-specific configuration files in the
50 50
 ``/etc/keystone/domains`` directory.
51 51
 
52
+Unlike the file-based method of specifying domain-specific configurations,
53
+options specified via the Identity API will become active without needing to
54
+restart the keystone server. For performance reasons, the current state of
55
+configuration options for a domain are cached in the keystone server, and in
56
+multi-process and multi-threaded keystone configurations, the new
57
+configuration options may not become active until the cache has timed out. The
58
+cache settings for domain config options can be adjusted in the general
59
+keystone configuration file (option ``cache_time`` in the ``domain_config``
60
+group).
61
+
62
+.. NOTE::
63
+
64
+    It is important to notice that when using either of these methods of
65
+    specifying domain-specific configuration options, the main keystone
66
+    configuration file is still maintained. Only those options that relate
67
+    to the Identity driver for users and groups (i.e. specifying whether the
68
+    driver for this domain is SQL or LDAP, and, if LDAP, the options that
69
+    define that connection) are supported in a domain-specific manner. Further,
70
+    when using the configuration options via the Identity API, the driver
71
+    option must be set to an LDAP driver (attempting to set it to an SQL driver
72
+    will generate an error when it is subsequently used).
73
+
74
+For existing installations that already use file-based domain-specific
75
+configurations who wish to migrate to the SQL-based approach, the
76
+``keystone-manage`` command can be used to upload all configuration files to
77
+the SQL database:
78
+
79
+.. code-block:: bash
80
+
81
+    $ keystone-manage domain_config_upload --all
82
+
83
+Once uploaded, these domain-configuration options will be visible via the
84
+Identity API as well as applied to the domain-specific drivers. It is also
85
+possible to upload individual domain-specific configuration files by
86
+specifying the domain name:
87
+
88
+.. code-block:: bash
89
+
90
+    $ keystone-manage domain_config_upload --domain-name DOMAINA
91
+
92
+.. NOTE::
93
+
94
+    It is important to notice that by enabling either of the domain-specific
95
+    configuration methods, the operations of listing all users and listing all
96
+    groups are not supported, those calls will need either a domain filter to
97
+    be specified or usage of a domain scoped token.
98
+
99
+.. NOTE::
100
+
101
+    Keystone does not support moving the contents of a domain (i.e. "its" users
102
+    and groups) from one backend to another, nor group membership across
103
+    backend boundaries.
104
+
105
+.. NOTE::
106
+
107
+    When using the file-based domain-specific configuration method, to delete a
108
+    domain that uses a domain specific backend, it's necessary to first disable
109
+    it, remove its specific configuration file (i.e. its corresponding
110
+    keystone.<domain_name>.conf) and then restart the Identity server. When
111
+    managing configuration options via the Identity API, the domain can simply
112
+    be disabled and deleted via the Identity API; since any domain-specific
113
+    configuration options will automatically be removed.
114
+
115
+.. NOTE::
116
+
117
+    Although keystone supports multiple LDAP backends via the above
118
+    domain-specific configuration methods, it currently only supports one SQL
119
+    backend. This could be either the default driver or a single
120
+    domain-specific backend, perhaps for storing service users in a
121
+    predominantly LDAP installation.
122
+
123
+.. NOTE::
124
+
125
+    Keystone has deprecated the ``keystone-manage domain_config_upload``
126
+    option. The keystone team recommends setting domain config options via the
127
+    API instead.
128
+
129
+Due to the need for user and group IDs to be unique across an OpenStack
130
+installation and for keystone to be able to deduce which domain and backend to
131
+use from just a user or group ID, it dynamically builds a persistent identity
132
+mapping table from a public ID to the actual domain, local ID (within that
133
+backend) and entity type. The public ID is automatically generated by keystone
134
+when it first encounters the entity. If the local ID of the entity is from a
135
+backend that does not guarantee to generate UUIDs, a hash algorithm will
136
+generate a public ID for that entity, which is what will be exposed by
137
+keystone.
138
+
139
+The use of a hash will ensure that if the public ID needs to be regenerated
140
+then the same public ID will be created. This is useful if you are running
141
+multiple keystones and want to ensure the same ID would be generated whichever
142
+server you hit.
143
+
144
+While keystone will dynamically maintain the identity mapping, including
145
+removing entries when entities are deleted via the keystone, for those entities
146
+in backends that are managed outside of keystone (e.g. a read-only LDAP),
147
+keystone will not know if entities have been deleted and hence will continue to
148
+carry stale identity mappings in its table. While benign, keystone provides an
149
+ability for operators to purge the mapping table of such stale entries using
150
+the keystone-manage command, for example:
151
+
152
+.. code-block:: bash
153
+
154
+    $ keystone-manage mapping_purge --domain-name DOMAINA --local-id abc@de.com
155
+
156
+A typical usage would be for an operator to obtain a list of those entries in
157
+an external backend that had been deleted out-of-band to keystone, and then
158
+call keystone-manage to purge those entries by specifying the domain and
159
+local-id. The type of the entity (i.e. user or group) may also be specified if
160
+this is needed to uniquely identify the mapping.
161
+
162
+Since public IDs can be regenerated **with the correct generator
163
+implementation**, if the details of those entries that have been deleted are
164
+not available, then it is safe to simply bulk purge identity mappings
165
+periodically, for example:
166
+
167
+.. code-block:: bash
168
+
169
+    $ keystone-manage mapping_purge --domain-name DOMAINA
170
+
171
+will purge all the mappings for DOMAINA. The entire mapping table can be purged
172
+with the following command:
173
+
174
+.. code-block:: bash
175
+
176
+    $ keystone-manage mapping_purge --all
177
+
178
+Generating public IDs in the first run may take a while, and most probably
179
+first API requests to fetch user list will fail by timeout. To prevent this,
180
+``mapping_populate`` command should be executed. It should be executed right after
181
+LDAP has been configured or after ``mapping_purge``.
182
+
183
+.. code-block:: bash
184
+
185
+    $ keystone-manage mapping_populate --domain DOMAINA
186
+
52 187
 Migrate domain-specific configuration files to the SQL database
53 188
 ---------------------------------------------------------------
54 189
 
@@ -64,6 +199,4 @@ domain name:
64 199
 
65 200
 .. code-block:: console
66 201
 
67
-   # keystone-manage domain_config_upload --domain-name DOMAIN_NAME
68
-
69
-
202
+   # keystone-manage domain_config_upload --domain-name DOMAIN_NAME

+ 4
- 182
doc/source/configuration.rst View File

@@ -103,191 +103,13 @@ Keystone supports several different choices that will substantially impact how
103 103
 you'll configure, deploy, and interact with keystone.
104 104
 
105 105
 You can also mix-and-match various sources of identity (see `Domain-specific
106
-Drivers`_ below for an example). For example, you can store OpenStack service
107
-users and their passwords in SQL, manage customers in LDAP, and authenticate
108
-employees via SAML federation.
106
+Configuration`_ for an example). For example, you can store OpenStack service users
107
+and their passwords in SQL, manage customers in LDAP, and authenticate employees
108
+via SAML federation.
109 109
 
110
+.. _Domain-specific Configuration: admin/identity-domain-specific-config.html
110 111
 .. support_matrix:: identity-support-matrix.ini
111 112
 
112
-.. Domain-specific Drivers:
113
-
114
-Domain-specific Drivers
115
------------------------
116
-
117
-Keystone supports the option (disabled by default) to specify identity driver
118
-configurations on a domain by domain basis, allowing, for example, a specific
119
-domain to have its own LDAP or SQL server. This is configured by specifying the
120
-following options:
121
-
122
-.. code-block:: ini
123
-
124
- [identity]
125
- domain_specific_drivers_enabled = True
126
- domain_config_dir = /etc/keystone/domains
127
-
128
-Setting ``domain_specific_drivers_enabled`` to ``True`` will enable this
129
-feature, causing keystone to look in the ``domain_config_dir`` for config files
130
-of the form::
131
-
132
- keystone.<domain_name>.conf
133
-
134
-Options given in the domain specific configuration file will override those in
135
-the primary configuration file for the specified domain only. Domains without a
136
-specific configuration file will continue to use the options from the primary
137
-configuration file.
138
-
139
-Keystone also supports the ability to store the domain-specific configuration
140
-options in the keystone SQL database, managed via the Identity API, as opposed
141
-to using domain-specific configuration files.
142
-
143
-This capability (which is disabled by default) is enabled by specifying the
144
-following options in the main keystone configuration file:
145
-
146
-.. code-block:: ini
147
-
148
-  [identity]
149
-  domain_specific_drivers_enabled = true
150
-  domain_configurations_from_database = true
151
-
152
-Once enabled, any existing domain-specific configuration files in the
153
-configuration directory will be ignored and only those domain-specific
154
-configuration options specified via the Identity API will be used.
155
-
156
-Unlike the file-based method of specifying domain-specific configurations,
157
-options specified via the Identity API will become active without needing to
158
-restart the keystone server. For performance reasons, the current state of
159
-configuration options for a domain are cached in the keystone server, and in
160
-multi-process and multi-threaded keystone configurations, the new
161
-configuration options may not become active until the cache has timed out. The
162
-cache settings for domain config options can be adjusted in the general
163
-keystone configuration file (option ``cache_time`` in the ``domain_config``
164
-group).
165
-
166
-.. NOTE::
167
-
168
-    It is important to notice that when using either of these methods of
169
-    specifying domain-specific configuration options, the main keystone
170
-    configuration file is still maintained. Only those options that relate
171
-    to the Identity driver for users and groups (i.e. specifying whether the
172
-    driver for this domain is SQL or LDAP, and, if LDAP, the options that
173
-    define that connection) are supported in a domain-specific manner. Further,
174
-    when using the configuration options via the Identity API, the driver
175
-    option must be set to an LDAP driver (attempting to set it to an SQL driver
176
-    will generate an error when it is subsequently used).
177
-
178
-For existing installations that already use file-based domain-specific
179
-configurations who wish to migrate to the SQL-based approach, the
180
-``keystone-manage`` command can be used to upload all configuration files to
181
-the SQL database:
182
-
183
-.. code-block:: bash
184
-
185
-    $ keystone-manage domain_config_upload --all
186
-
187
-Once uploaded, these domain-configuration options will be visible via the
188
-Identity API as well as applied to the domain-specific drivers. It is also
189
-possible to upload individual domain-specific configuration files by
190
-specifying the domain name:
191
-
192
-.. code-block:: bash
193
-
194
-    $ keystone-manage domain_config_upload --domain-name DOMAINA
195
-
196
-.. NOTE::
197
-
198
-    It is important to notice that by enabling either of the domain-specific
199
-    configuration methods, the operations of listing all users and listing all
200
-    groups are not supported, those calls will need either a domain filter to
201
-    be specified or usage of a domain scoped token.
202
-
203
-.. NOTE::
204
-
205
-    Keystone does not support moving the contents of a domain (i.e. "its" users
206
-    and groups) from one backend to another, nor group membership across
207
-    backend boundaries.
208
-
209
-.. NOTE::
210
-
211
-    When using the file-based domain-specific configuration method, to delete a
212
-    domain that uses a domain specific backend, it's necessary to first disable
213
-    it, remove its specific configuration file (i.e. its corresponding
214
-    keystone.<domain_name>.conf) and then restart the Identity server. When
215
-    managing configuration options via the Identity API, the domain can simply
216
-    be disabled and deleted via the Identity API; since any domain-specific
217
-    configuration options will automatically be removed.
218
-
219
-.. NOTE::
220
-
221
-    Although keystone supports multiple LDAP backends via the above
222
-    domain-specific configuration methods, it currently only supports one SQL
223
-    backend. This could be either the default driver or a single
224
-    domain-specific backend, perhaps for storing service users in a
225
-    predominantly LDAP installation.
226
-
227
-.. NOTE::
228
-
229
-    Keystone has deprecated the ``keystone-manage domain_config_upload``
230
-    option. The keystone team recommends setting domain config options via the
231
-    API instead.
232
-
233
-Due to the need for user and group IDs to be unique across an OpenStack
234
-installation and for keystone to be able to deduce which domain and backend to
235
-use from just a user or group ID, it dynamically builds a persistent identity
236
-mapping table from a public ID to the actual domain, local ID (within that
237
-backend) and entity type. The public ID is automatically generated by keystone
238
-when it first encounters the entity. If the local ID of the entity is from a
239
-backend that does not guarantee to generate UUIDs, a hash algorithm will
240
-generate a public ID for that entity, which is what will be exposed by
241
-keystone.
242
-
243
-The use of a hash will ensure that if the public ID needs to be regenerated
244
-then the same public ID will be created. This is useful if you are running
245
-multiple keystones and want to ensure the same ID would be generated whichever
246
-server you hit.
247
-
248
-While keystone will dynamically maintain the identity mapping, including
249
-removing entries when entities are deleted via the keystone, for those entities
250
-in backends that are managed outside of keystone (e.g. a read-only LDAP),
251
-keystone will not know if entities have been deleted and hence will continue to
252
-carry stale identity mappings in its table. While benign, keystone provides an
253
-ability for operators to purge the mapping table of such stale entries using
254
-the keystone-manage command, for example:
255
-
256
-.. code-block:: bash
257
-
258
-    $ keystone-manage mapping_purge --domain-name DOMAINA --local-id abc@de.com
259
-
260
-A typical usage would be for an operator to obtain a list of those entries in
261
-an external backend that had been deleted out-of-band to keystone, and then
262
-call keystone-manage to purge those entries by specifying the domain and
263
-local-id. The type of the entity (i.e. user or group) may also be specified if
264
-this is needed to uniquely identify the mapping.
265
-
266
-Since public IDs can be regenerated **with the correct generator
267
-implementation**, if the details of those entries that have been deleted are
268
-not available, then it is safe to simply bulk purge identity mappings
269
-periodically, for example:
270
-
271
-.. code-block:: bash
272
-
273
-    $ keystone-manage mapping_purge --domain-name DOMAINA
274
-
275
-will purge all the mappings for DOMAINA. The entire mapping table can be purged
276
-with the following command:
277
-
278
-.. code-block:: bash
279
-
280
-    $ keystone-manage mapping_purge --all
281
-
282
-Generating public IDs in the first run may take a while, and most probably
283
-first API requests to fetch user list will fail by timeout. To prevent this,
284
-``mapping_populate`` command should be executed. It should be executed right after
285
-LDAP has been configured or after ``mapping_purge``.
286
-
287
-.. code-block:: bash
288
-
289
-    $ keystone-manage mapping_populate --domain DOMAINA
290
-
291 113
 Public ID Generators
292 114
 --------------------
293 115
 

Loading…
Cancel
Save