Browse Source

Add configuration reference to doc/source/configuration

Change-Id: I077f4e7c3b12689f809cd68177e00a097d6cd0a2
tags/6.0.0
tikitavi 1 year ago
parent
commit
9e91db17aa

+ 18
- 2
doc/source/conf.py View File

@@ -21,8 +21,16 @@ os.environ['DJANGO_SETTINGS_MODULE'] = 'openstack_dashboard.settings'
21 21
 
22 22
 # Add any Sphinx extension module names here, as strings. They can be extensions
23 23
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
24
-extensions = ['sphinx.ext.autodoc', 'sphinx.ext.doctest', 'sphinx.ext.todo',
25
-              'sphinx.ext.viewcode']
24
+extensions = ['sphinx.ext.autodoc',
25
+              'sphinx.ext.doctest',
26
+              'sphinx.ext.todo',
27
+              'sphinx.ext.viewcode',
28
+              'openstackdocstheme']
29
+
30
+# openstackdocstheme options
31
+repository_name = 'openstack/ec2-api'
32
+bug_project = 'ec2-api'
33
+bug_tag = ''
26 34
 
27 35
 # autodoc generation is a bit aggressive and a nuisance when doing heavy
28 36
 # text edit cycles.
@@ -58,10 +66,18 @@ pygments_style = 'sphinx'
58 66
 #html_theme_path = ["."]
59 67
 #html_theme = '_theme'
60 68
 #html_static_path = ['static']
69
+html_theme = 'openstackdocs'
70
+
71
+html_last_updated_fmt = '%Y-%m-%d %H:%M'
72
+# Theme options are theme-specific and customize the look and feel of a theme
73
+# further.  For a list of options available for each theme, see the
74
+# documentation.
75
+html_theme_options = {"sidebar_mode": "toc"}
61 76
 
62 77
 # Output file base name for HTML help builder.
63 78
 htmlhelp_basename = '%sdoc' % project
64 79
 
80
+
65 81
 git_cmd = ["git", "log", "--pretty=format:'%ad, commit %h'", "--date=local",
66 82
     "-n1"]
67 83
 try:

+ 143
- 0
doc/source/configuration/_flagmappings/ec2api.flagmappings View File

@@ -0,0 +1,143 @@
1
+admin_password disable
2
+admin_tenant_name disable
3
+admin_user disable
4
+api_paste_config common
5
+api_rate_limit disable
6
+bindir disable
7
+buckets_path disable
8
+cert_topic disable
9
+cinder_service_type clients
10
+debug disable
11
+default_flavor ec2
12
+default_log_levels disable
13
+disable_ec2_classic ec2
14
+ec2_host ec2
15
+ec2_path ec2
16
+ec2_port ec2
17
+ec2_private_dns_show_ip ec2
18
+ec2_scheme ec2
19
+ec2_timestamp_expiry clients
20
+ec2api_listen service
21
+ec2api_listen_port service
22
+ec2api_use_ssl service
23
+ec2api_workers service
24
+external_network ec2
25
+fatal_deprecations disable
26
+fatal_exception_format_errors disable
27
+image_decryption_dir s3
28
+instance_format disable
29
+instance_uuid_format disable
30
+internal_service_availability_zone ec2
31
+keystone_ec2_tokens_url clients
32
+keystone_url disable
33
+log_config_append disable
34
+log_date_format disable
35
+log_dir disable
36
+log_file disable
37
+logging_context_format_string disable
38
+logging_debug_format_suffix disable
39
+logging_default_format_string disable
40
+logging_exception_prefix disable
41
+logging_user_identity_format disable
42
+max_header_line common
43
+metadata_listen metadata
44
+metadata_listen_port metadata
45
+metadata_use_ssl metadata
46
+metadata_workers metadata
47
+my_ip ec2
48
+network_device_mtu ec2
49
+nova_service_type clients
50
+publish_errors disable
51
+pybasedir disable
52
+rate_limit_burst disable
53
+rate_limit_except_level disable
54
+rate_limit_interval disable
55
+region_list ec2
56
+s3_listen disable
57
+s3_listen_port disable
58
+s3_region s3
59
+s3_url s3
60
+service_down_time disable
61
+ssl_ca_file disable
62
+ssl_cert_file service
63
+ssl_insecure disable
64
+ssl_key_file service
65
+state_path disable
66
+syslog_log_facility disable
67
+tcp_keepidle common
68
+tempdir disable
69
+use_forwarded_for service
70
+use_journal disable
71
+use_stderr disable
72
+use_syslog disable
73
+watch_log_file disable
74
+wsgi_default_pool_size common
75
+wsgi_log_format common
76
+x509_root_private_key s3
77
+cache/backend disable
78
+cache/backend_argument disable
79
+cache/config_prefix disable
80
+cache/debug_cache_backend disable
81
+cache/enabled disable
82
+cache/expiration_time disable
83
+cache/memcache_dead_retry disable
84
+cache/memcache_pool_connection_get_timeout disable
85
+cache/memcache_pool_maxsize disable
86
+cache/memcache_pool_unused_timeout disable
87
+cache/memcache_servers disable
88
+cache/memcache_socket_timeout disable
89
+cache/proxies disable
90
+database/backend disable
91
+database/connection disable
92
+database/connection_debug disable
93
+database/connection_recycle_time disable
94
+database/connection_trace disable
95
+database/db_inc_retry_interval disable
96
+database/db_max_retries disable
97
+database/db_max_retry_interval disable
98
+database/db_retry_interval disable
99
+database/max_overflow disable
100
+database/max_pool_size disable
101
+database/max_retries disable
102
+database/min_pool_size disable
103
+database/mysql_enable_ndb disable
104
+database/mysql_sql_mode disable
105
+database/pool_timeout disable
106
+database/retry_interval disable
107
+database/slave_connection disable
108
+database/sqlite_synchronous disable
109
+database/use_db_reconnect disable
110
+database/use_tpool database
111
+keystone_authtoken/admin_password disable
112
+keystone_authtoken/admin_tenant_name disable
113
+keystone_authtoken/admin_token disable
114
+keystone_authtoken/admin_user disable
115
+keystone_authtoken/auth_admin_prefix disable
116
+keystone_authtoken/auth_host disable
117
+keystone_authtoken/auth_port disable
118
+keystone_authtoken/auth_protocol disable
119
+keystone_authtoken/auth_section disable
120
+keystone_authtoken/auth_type disable
121
+keystone_authtoken/auth_uri disable
122
+keystone_authtoken/auth_version disable
123
+keystone_authtoken/cache disable
124
+keystone_authtoken/cafile disable
125
+keystone_authtoken/certfile disable
126
+keystone_authtoken/delay_auth_decision disable
127
+keystone_authtoken/http_connect_timeout disable
128
+keystone_authtoken/http_request_max_retries disable
129
+keystone_authtoken/identity_uri disable
130
+keystone_authtoken/insecure disable
131
+keystone_authtoken/keyfile disable
132
+keystone_authtoken/timeout disable
133
+metadata/auth_ca_cert metadata
134
+metadata/cache_expiration metadata
135
+metadata/metadata_proxy_shared_secret metadata
136
+metadata/nova_client_cert metadata
137
+metadata/nova_client_priv_key metadata
138
+metadata/nova_metadata_insecure metadata
139
+metadata/nova_metadata_ip metadata
140
+metadata/nova_metadata_port metadata
141
+metadata/nova_metadata_protocol metadata
142
+oslo_concurrency/disable_process_locking disable
143
+oslo_concurrency/lock_path disable

+ 7
- 0
doc/source/configuration/_flagmappings/ec2api.headers View File

@@ -0,0 +1,7 @@
1
+clients OpenStack Clients
2
+common Common Service
3
+database additional Database Client
4
+ec2 EC2API
5
+metadata Metadata
6
+service EC2API Service
7
+s3 S3 Client

+ 18
- 0
doc/source/configuration/api.rst View File

@@ -0,0 +1,18 @@
1
+===============================
2
+EC2API configuration
3
+===============================
4
+
5
+Configuration options
6
+~~~~~~~~~~~~~~~~~~~~~
7
+
8
+The following options allow configuration that EC2API supports.
9
+
10
+
11
+.. include:: ./tables/ec2api-clients.rst
12
+.. include:: ./tables/ec2api-database.rst
13
+.. include:: ./tables/ec2api-service.rst
14
+.. include:: ./tables/ec2api-ec2.rst
15
+.. include:: ./tables/ec2api-s3.rst
16
+.. include:: ./tables/ec2api-common.rst
17
+
18
+

+ 17
- 0
doc/source/configuration/index.rst View File

@@ -0,0 +1,17 @@
1
+===================
2
+Configuring EC2-API
3
+===================
4
+
5
+To configure your EC2API installation, you must define configuration options in these files:
6
+
7
+* ``ec2api.conf`` contains EC2API configuration options and resides in the ``/etc/ec2api`` directory.
8
+
9
+* ``api-paste.ini`` defines EC2API limits and resides in the ``/etc/ec2api`` directory.
10
+
11
+A list of config options based on different topics can be found below:
12
+
13
+.. toctree::
14
+   :maxdepth: 2
15
+
16
+   api.rst
17
+   metadata.rst

+ 16
- 0
doc/source/configuration/metadata.rst View File

@@ -0,0 +1,16 @@
1
+==============================
2
+EC2API Metadata configuration
3
+==============================
4
+
5
+Configuration options
6
+~~~~~~~~~~~~~~~~~~~~~
7
+
8
+To configure Metadata Service for ec2api, EC2 API configuration_ common sections
9
+ (such as OpenStack Clients, Database Client, EC2API and Common sections)
10
+ must be configured as well.
11
+
12
+.. _configuration: ./api.html
13
+
14
+The additional configuration options for EC2 Metadata:
15
+
16
+.. include:: ./tables/ec2api-metadata.rst

+ 37
- 0
doc/source/configuration/tables/ec2api-clients.rst View File

@@ -0,0 +1,37 @@
1
+..
2
+    Warning: Do not edit this file. It is automatically generated from the
3
+    software project's code and your changes will be overwritten.
4
+
5
+    The tool to generate this file lives in openstack-doc-tools repository.
6
+
7
+    Please make any changes needed in the code, then run the
8
+    autogenerate-config-doc tool from the openstack-doc-tools repository, or
9
+    ask for help on the documentation mailing list, IRC channel or meeting.
10
+
11
+.. _ec2api-clients:
12
+
13
+.. list-table:: Description of OpenStack Clients configuration options
14
+   :header-rows: 1
15
+   :class: config-ref-table
16
+
17
+   * - Configuration option = Default value
18
+     - Description
19
+
20
+   * - **[DEFAULT]**
21
+     -
22
+
23
+   * - ``cinder_service_type`` = ``volumev2``
24
+
25
+     - (String) Service type of Volume API, registered in Keystone catalog.
26
+
27
+   * - ``ec2_timestamp_expiry`` = ``300``
28
+
29
+     - (Integer) Time in seconds before ec2 timestamp expires
30
+
31
+   * - ``keystone_ec2_tokens_url`` = ``http://localhost:5000/v3/ec2tokens``
32
+
33
+     - (String) URL to authenticate token from ec2 request.
34
+
35
+   * - ``nova_service_type`` = ``compute``
36
+
37
+     - (String) Service type of Compute API, registered in Keystone catalog. Should be v2.1 with microversion support. If it is obsolete v2, a lot of useful EC2 compliant instance properties will be unavailable.

+ 41
- 0
doc/source/configuration/tables/ec2api-common.rst View File

@@ -0,0 +1,41 @@
1
+..
2
+    Warning: Do not edit this file. It is automatically generated from the
3
+    software project's code and your changes will be overwritten.
4
+
5
+    The tool to generate this file lives in openstack-doc-tools repository.
6
+
7
+    Please make any changes needed in the code, then run the
8
+    autogenerate-config-doc tool from the openstack-doc-tools repository, or
9
+    ask for help on the documentation mailing list, IRC channel or meeting.
10
+
11
+.. _ec2api-common:
12
+
13
+.. list-table:: Description of Common Service configuration options
14
+   :header-rows: 1
15
+   :class: config-ref-table
16
+
17
+   * - Configuration option = Default value
18
+     - Description
19
+
20
+   * - **[DEFAULT]**
21
+     -
22
+
23
+   * - ``api_paste_config`` = ``api-paste.ini``
24
+
25
+     - (String) File name for the paste.deploy config for ec2api
26
+
27
+   * - ``max_header_line`` = ``16384``
28
+
29
+     - (Integer) Maximum line size of message headers to be accepted. max_header_line may need to be increased when using large tokens (typically those generated by the Keystone v3 API with big service catalogs).
30
+
31
+   * - ``tcp_keepidle`` = ``600``
32
+
33
+     - (Integer) Sets the value of TCP_KEEPIDLE in seconds for each server socket. Not supported on OS X.
34
+
35
+   * - ``wsgi_default_pool_size`` = ``1000``
36
+
37
+     - (Integer) Size of the pool of greenthreads used by wsgi
38
+
39
+   * - ``wsgi_log_format`` = ``%(client_ip)s "%(request_line)s" status: %(status_code)s len: %(body_length)s time: %(wall_seconds).7f``
40
+
41
+     - (String) A python format string that is used as the template to generate log lines. The following values can be formatted into it: client_ip, date_time, request_line, status_code, body_length, wall_seconds.

+ 25
- 0
doc/source/configuration/tables/ec2api-database.rst View File

@@ -0,0 +1,25 @@
1
+..
2
+    Warning: Do not edit this file. It is automatically generated from the
3
+    software project's code and your changes will be overwritten.
4
+
5
+    The tool to generate this file lives in openstack-doc-tools repository.
6
+
7
+    Please make any changes needed in the code, then run the
8
+    autogenerate-config-doc tool from the openstack-doc-tools repository, or
9
+    ask for help on the documentation mailing list, IRC channel or meeting.
10
+
11
+.. _ec2api-database:
12
+
13
+.. list-table:: Description of additional Database Client configuration options
14
+   :header-rows: 1
15
+   :class: config-ref-table
16
+
17
+   * - Configuration option = Default value
18
+     - Description
19
+
20
+   * - **[database]**
21
+     -
22
+
23
+   * - ``use_tpool`` = ``False``
24
+
25
+     - (Boolean) Enable the experimental use of thread pooling for all DB API calls

+ 69
- 0
doc/source/configuration/tables/ec2api-ec2.rst View File

@@ -0,0 +1,69 @@
1
+..
2
+    Warning: Do not edit this file. It is automatically generated from the
3
+    software project's code and your changes will be overwritten.
4
+
5
+    The tool to generate this file lives in openstack-doc-tools repository.
6
+
7
+    Please make any changes needed in the code, then run the
8
+    autogenerate-config-doc tool from the openstack-doc-tools repository, or
9
+    ask for help on the documentation mailing list, IRC channel or meeting.
10
+
11
+.. _ec2api-ec2:
12
+
13
+.. list-table:: Description of EC2API configuration options
14
+   :header-rows: 1
15
+   :class: config-ref-table
16
+
17
+   * - Configuration option = Default value
18
+     - Description
19
+
20
+   * - **[DEFAULT]**
21
+     -
22
+
23
+   * - ``default_flavor`` = ``m1.small``
24
+
25
+     - (String) A flavor to use as a default instance type
26
+
27
+   * - ``disable_ec2_classic`` = ``None``
28
+
29
+     - (Boolean) True if server does not support EC2 Classic mode in favor of default VPC
30
+
31
+   * - ``ec2_host`` = ``$my_ip``
32
+
33
+     - (String) The IP address of the EC2 API server
34
+
35
+   * - ``ec2_path`` = ``/``
36
+
37
+     - (String) The path prefix used to call the ec2 API server
38
+
39
+   * - ``ec2_port`` = ``8788``
40
+
41
+     - (Integer) The port of the EC2 API server
42
+
43
+   * - ``ec2_private_dns_show_ip`` = ``False``
44
+
45
+     - (Boolean) Return the IP address as private dns hostname in describe instances
46
+
47
+   * - ``ec2_scheme`` = ``http``
48
+
49
+     - (String) The protocol to use when connecting to the EC2 API server (http, https)
50
+
51
+   * - ``external_network`` = ``None``
52
+
53
+     - (String) Name of the external network, which is used to connectVPCs to Internet and to allocate Elastic IPs.
54
+
55
+   * - ``internal_service_availability_zone`` = ``internal``
56
+
57
+     - (String) The availability_zone to show internal services under
58
+
59
+   * - ``my_ip`` = ``10.0.0.1``
60
+
61
+     - (String) IP address of this host
62
+
63
+   * - ``network_device_mtu`` = ``1500``
64
+
65
+     - (Integer) MTU size to set by DHCP for instances. Corresponds with the network_device_mtu in ec2api.conf.
66
+
67
+   * - ``region_list`` =
68
+
69
+     - (List) List of region=fqdn pairs separated by commas

+ 76
- 0
doc/source/configuration/tables/ec2api-metadata.rst View File

@@ -0,0 +1,76 @@
1
+..
2
+    Warning: Do not edit this file. It is automatically generated from the
3
+    software project's code and your changes will be overwritten.
4
+
5
+    The tool to generate this file lives in openstack-doc-tools repository.
6
+
7
+    Please make any changes needed in the code, then run the
8
+    autogenerate-config-doc tool from the openstack-doc-tools repository, or
9
+    ask for help on the documentation mailing list, IRC channel or meeting.
10
+
11
+.. _ec2api-metadata:
12
+
13
+.. list-table:: Description of Metadata configuration options
14
+   :header-rows: 1
15
+   :class: config-ref-table
16
+
17
+   * - Configuration option = Default value
18
+     - Description
19
+
20
+   * - **[DEFAULT]**
21
+     -
22
+
23
+   * - ``metadata_listen`` = ``0.0.0.0``
24
+
25
+     - (String) The IP address on which the metadata API will listen.
26
+
27
+   * - ``metadata_listen_port`` = ``8789``
28
+
29
+     - (Integer) The port on which the metadata API will listen.
30
+
31
+   * - ``metadata_use_ssl`` = ``False``
32
+
33
+     - (Boolean) Enable ssl connections or not for EC2 API Metadata
34
+
35
+   * - ``metadata_workers`` = ``None``
36
+
37
+     - (Integer) Number of workers for metadata service. The default will be the number of CPUs available.
38
+
39
+   * - **[metadata]**
40
+     -
41
+
42
+   * - ``auth_ca_cert`` = ``None``
43
+
44
+     - (String) Certificate Authority public key (CA cert) file for ssl
45
+
46
+   * - ``cache_expiration`` = ``15``
47
+
48
+     - (Integer) This option is the time (in seconds) to cache metadata. Increasing this setting should improve response times of the metadata API when under heavy load. Higher values may increase memory usage, and result in longer times for host metadata changes to take effect.
49
+
50
+   * - ``metadata_proxy_shared_secret`` =
51
+
52
+     - (String) Shared secret to sign instance-id request
53
+
54
+   * - ``nova_client_cert`` =
55
+
56
+     - (String) Client certificate for nova metadata api server.
57
+
58
+   * - ``nova_client_priv_key`` =
59
+
60
+     - (String) Private key of client certificate.
61
+
62
+   * - ``nova_metadata_insecure`` = ``False``
63
+
64
+     - (Boolean) Allow to perform insecure SSL (https) requests to nova metadata
65
+
66
+   * - ``nova_metadata_ip`` = ``127.0.0.1``
67
+
68
+     - (String) IP address used by Nova metadata server.
69
+
70
+   * - ``nova_metadata_port`` = ``8775``
71
+
72
+     - (Integer) TCP Port used by Nova metadata server.
73
+
74
+   * - ``nova_metadata_protocol`` = ``http``
75
+
76
+     - (String) Protocol to access nova metadata, http or https

+ 37
- 0
doc/source/configuration/tables/ec2api-s3.rst View File

@@ -0,0 +1,37 @@
1
+..
2
+    Warning: Do not edit this file. It is automatically generated from the
3
+    software project's code and your changes will be overwritten.
4
+
5
+    The tool to generate this file lives in openstack-doc-tools repository.
6
+
7
+    Please make any changes needed in the code, then run the
8
+    autogenerate-config-doc tool from the openstack-doc-tools repository, or
9
+    ask for help on the documentation mailing list, IRC channel or meeting.
10
+
11
+.. _ec2api-s3:
12
+
13
+.. list-table:: Description of S3 Client configuration options
14
+   :header-rows: 1
15
+   :class: config-ref-table
16
+
17
+   * - Configuration option = Default value
18
+     - Description
19
+
20
+   * - **[DEFAULT]**
21
+     -
22
+
23
+   * - ``image_decryption_dir`` = ``/tmp``
24
+
25
+     - (String) Parent directory for tempdir used for image decryption
26
+
27
+   * - ``s3_region`` = ``RegionOne``
28
+
29
+     - (String) Region of S3 server
30
+
31
+   * - ``s3_url`` = ``http://$my_ip:3334``
32
+
33
+     - (String) URL to S3 server
34
+
35
+   * - ``x509_root_private_key`` = ``None``
36
+
37
+     - (String) Path to ca private key file

+ 49
- 0
doc/source/configuration/tables/ec2api-service.rst View File

@@ -0,0 +1,49 @@
1
+..
2
+    Warning: Do not edit this file. It is automatically generated from the
3
+    software project's code and your changes will be overwritten.
4
+
5
+    The tool to generate this file lives in openstack-doc-tools repository.
6
+
7
+    Please make any changes needed in the code, then run the
8
+    autogenerate-config-doc tool from the openstack-doc-tools repository, or
9
+    ask for help on the documentation mailing list, IRC channel or meeting.
10
+
11
+.. _ec2api-service:
12
+
13
+.. list-table:: Description of EC2API Service configuration options
14
+   :header-rows: 1
15
+   :class: config-ref-table
16
+
17
+   * - Configuration option = Default value
18
+     - Description
19
+
20
+   * - **[DEFAULT]**
21
+     -
22
+
23
+   * - ``ec2api_listen`` = ``0.0.0.0``
24
+
25
+     - (String) The IP address on which the EC2 API will listen.
26
+
27
+   * - ``ec2api_listen_port`` = ``8788``
28
+
29
+     - (Integer) The port on which the EC2 API will listen.
30
+
31
+   * - ``ec2api_use_ssl`` = ``False``
32
+
33
+     - (Boolean) Enable ssl connections or not for EC2 API
34
+
35
+   * - ``ec2api_workers`` = ``None``
36
+
37
+     - (Integer) Number of workers for EC2 API service. The default will be equal to the number of CPUs available.
38
+
39
+   * - ``ssl_cert_file`` = ``None``
40
+
41
+     - (String) SSL certificate of API server
42
+
43
+   * - ``ssl_key_file`` = ``None``
44
+
45
+     - (String) SSL private key of API server
46
+
47
+   * - ``use_forwarded_for`` = ``False``
48
+
49
+     - (Boolean) Treat X-Forwarded-For as the canonical remote address. Only enable this if you have a sanitizing proxy.

Loading…
Cancel
Save