summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authortikitavi <rtikitavi@gmail.com>2017-09-14 19:15:48 +0300
committertikitavi <rtikitavi@gmail.com>2017-09-28 16:55:10 +0300
commit9e91db17aa17f342ecfacd62bda18b8c0e086b1e (patch)
tree00ee1ed9caa335d1fb95e338e786469925c1a66d
parent5ee64e4c16e1e1d8fff5cc047080797a8a65262d (diff)
Add configuration reference to doc/source/configuration
Notes
Notes (review): Code-Review+2: Feodor Tersin <ftersin@hotmail.com> Workflow+1: Feodor Tersin <ftersin@hotmail.com> Code-Review+2: Alexandre Levine <alexandrelevine@gmail.com> Workflow+1: Alexandre Levine <alexandrelevine@gmail.com> Verified+2: Zuul Submitted-by: Zuul Submitted-at: Sun, 01 Oct 2017 11:20:09 +0000 Reviewed-on: https://review.openstack.org/504110 Project: openstack/ec2-api Branch: refs/heads/master
-rw-r--r--doc/source/conf.py20
-rw-r--r--doc/source/configuration/_flagmappings/ec2api.flagmappings143
-rw-r--r--doc/source/configuration/_flagmappings/ec2api.headers7
-rw-r--r--doc/source/configuration/api.rst18
-rw-r--r--doc/source/configuration/index.rst17
-rw-r--r--doc/source/configuration/metadata.rst16
-rw-r--r--doc/source/configuration/tables/ec2api-clients.rst37
-rw-r--r--doc/source/configuration/tables/ec2api-common.rst41
-rw-r--r--doc/source/configuration/tables/ec2api-database.rst25
-rw-r--r--doc/source/configuration/tables/ec2api-ec2.rst69
-rw-r--r--doc/source/configuration/tables/ec2api-metadata.rst76
-rw-r--r--doc/source/configuration/tables/ec2api-s3.rst37
-rw-r--r--doc/source/configuration/tables/ec2api-service.rst49
13 files changed, 553 insertions, 2 deletions
diff --git a/doc/source/conf.py b/doc/source/conf.py
index 8a4c8fb..f933c26 100644
--- a/doc/source/conf.py
+++ b/doc/source/conf.py
@@ -21,8 +21,16 @@ os.environ['DJANGO_SETTINGS_MODULE'] = 'openstack_dashboard.settings'
21 21
22# Add any Sphinx extension module names here, as strings. They can be extensions 22# Add any Sphinx extension module names here, as strings. They can be extensions
23# coming with Sphinx (named 'sphinx.ext.*') or your custom ones. 23# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
24extensions = ['sphinx.ext.autodoc', 'sphinx.ext.doctest', 'sphinx.ext.todo', 24extensions = ['sphinx.ext.autodoc',
25 'sphinx.ext.viewcode'] 25 'sphinx.ext.doctest',
26 'sphinx.ext.todo',
27 'sphinx.ext.viewcode',
28 'openstackdocstheme']
29
30# openstackdocstheme options
31repository_name = 'openstack/ec2-api'
32bug_project = 'ec2-api'
33bug_tag = ''
26 34
27# autodoc generation is a bit aggressive and a nuisance when doing heavy 35# autodoc generation is a bit aggressive and a nuisance when doing heavy
28# text edit cycles. 36# text edit cycles.
@@ -58,10 +66,18 @@ pygments_style = 'sphinx'
58#html_theme_path = ["."] 66#html_theme_path = ["."]
59#html_theme = '_theme' 67#html_theme = '_theme'
60#html_static_path = ['static'] 68#html_static_path = ['static']
69html_theme = 'openstackdocs'
70
71html_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.
75html_theme_options = {"sidebar_mode": "toc"}
61 76
62# Output file base name for HTML help builder. 77# Output file base name for HTML help builder.
63htmlhelp_basename = '%sdoc' % project 78htmlhelp_basename = '%sdoc' % project
64 79
80
65git_cmd = ["git", "log", "--pretty=format:'%ad, commit %h'", "--date=local", 81git_cmd = ["git", "log", "--pretty=format:'%ad, commit %h'", "--date=local",
66 "-n1"] 82 "-n1"]
67try: 83try:
diff --git a/doc/source/configuration/_flagmappings/ec2api.flagmappings b/doc/source/configuration/_flagmappings/ec2api.flagmappings
new file mode 100644
index 0000000..08a4814
--- /dev/null
+++ b/doc/source/configuration/_flagmappings/ec2api.flagmappings
@@ -0,0 +1,143 @@
1admin_password disable
2admin_tenant_name disable
3admin_user disable
4api_paste_config common
5api_rate_limit disable
6bindir disable
7buckets_path disable
8cert_topic disable
9cinder_service_type clients
10debug disable
11default_flavor ec2
12default_log_levels disable
13disable_ec2_classic ec2
14ec2_host ec2
15ec2_path ec2
16ec2_port ec2
17ec2_private_dns_show_ip ec2
18ec2_scheme ec2
19ec2_timestamp_expiry clients
20ec2api_listen service
21ec2api_listen_port service
22ec2api_use_ssl service
23ec2api_workers service
24external_network ec2
25fatal_deprecations disable
26fatal_exception_format_errors disable
27image_decryption_dir s3
28instance_format disable
29instance_uuid_format disable
30internal_service_availability_zone ec2
31keystone_ec2_tokens_url clients
32keystone_url disable
33log_config_append disable
34log_date_format disable
35log_dir disable
36log_file disable
37logging_context_format_string disable
38logging_debug_format_suffix disable
39logging_default_format_string disable
40logging_exception_prefix disable
41logging_user_identity_format disable
42max_header_line common
43metadata_listen metadata
44metadata_listen_port metadata
45metadata_use_ssl metadata
46metadata_workers metadata
47my_ip ec2
48network_device_mtu ec2
49nova_service_type clients
50publish_errors disable
51pybasedir disable
52rate_limit_burst disable
53rate_limit_except_level disable
54rate_limit_interval disable
55region_list ec2
56s3_listen disable
57s3_listen_port disable
58s3_region s3
59s3_url s3
60service_down_time disable
61ssl_ca_file disable
62ssl_cert_file service
63ssl_insecure disable
64ssl_key_file service
65state_path disable
66syslog_log_facility disable
67tcp_keepidle common
68tempdir disable
69use_forwarded_for service
70use_journal disable
71use_stderr disable
72use_syslog disable
73watch_log_file disable
74wsgi_default_pool_size common
75wsgi_log_format common
76x509_root_private_key s3
77cache/backend disable
78cache/backend_argument disable
79cache/config_prefix disable
80cache/debug_cache_backend disable
81cache/enabled disable
82cache/expiration_time disable
83cache/memcache_dead_retry disable
84cache/memcache_pool_connection_get_timeout disable
85cache/memcache_pool_maxsize disable
86cache/memcache_pool_unused_timeout disable
87cache/memcache_servers disable
88cache/memcache_socket_timeout disable
89cache/proxies disable
90database/backend disable
91database/connection disable
92database/connection_debug disable
93database/connection_recycle_time disable
94database/connection_trace disable
95database/db_inc_retry_interval disable
96database/db_max_retries disable
97database/db_max_retry_interval disable
98database/db_retry_interval disable
99database/max_overflow disable
100database/max_pool_size disable
101database/max_retries disable
102database/min_pool_size disable
103database/mysql_enable_ndb disable
104database/mysql_sql_mode disable
105database/pool_timeout disable
106database/retry_interval disable
107database/slave_connection disable
108database/sqlite_synchronous disable
109database/use_db_reconnect disable
110database/use_tpool database
111keystone_authtoken/admin_password disable
112keystone_authtoken/admin_tenant_name disable
113keystone_authtoken/admin_token disable
114keystone_authtoken/admin_user disable
115keystone_authtoken/auth_admin_prefix disable
116keystone_authtoken/auth_host disable
117keystone_authtoken/auth_port disable
118keystone_authtoken/auth_protocol disable
119keystone_authtoken/auth_section disable
120keystone_authtoken/auth_type disable
121keystone_authtoken/auth_uri disable
122keystone_authtoken/auth_version disable
123keystone_authtoken/cache disable
124keystone_authtoken/cafile disable
125keystone_authtoken/certfile disable
126keystone_authtoken/delay_auth_decision disable
127keystone_authtoken/http_connect_timeout disable
128keystone_authtoken/http_request_max_retries disable
129keystone_authtoken/identity_uri disable
130keystone_authtoken/insecure disable
131keystone_authtoken/keyfile disable
132keystone_authtoken/timeout disable
133metadata/auth_ca_cert metadata
134metadata/cache_expiration metadata
135metadata/metadata_proxy_shared_secret metadata
136metadata/nova_client_cert metadata
137metadata/nova_client_priv_key metadata
138metadata/nova_metadata_insecure metadata
139metadata/nova_metadata_ip metadata
140metadata/nova_metadata_port metadata
141metadata/nova_metadata_protocol metadata
142oslo_concurrency/disable_process_locking disable
143oslo_concurrency/lock_path disable
diff --git a/doc/source/configuration/_flagmappings/ec2api.headers b/doc/source/configuration/_flagmappings/ec2api.headers
new file mode 100644
index 0000000..a492e50
--- /dev/null
+++ b/doc/source/configuration/_flagmappings/ec2api.headers
@@ -0,0 +1,7 @@
1clients OpenStack Clients
2common Common Service
3database additional Database Client
4ec2 EC2API
5metadata Metadata
6service EC2API Service
7s3 S3 Client
diff --git a/doc/source/configuration/api.rst b/doc/source/configuration/api.rst
new file mode 100644
index 0000000..8c30254
--- /dev/null
+++ b/doc/source/configuration/api.rst
@@ -0,0 +1,18 @@
1===============================
2EC2API configuration
3===============================
4
5Configuration options
6~~~~~~~~~~~~~~~~~~~~~
7
8The 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
diff --git a/doc/source/configuration/index.rst b/doc/source/configuration/index.rst
new file mode 100644
index 0000000..1054883
--- /dev/null
+++ b/doc/source/configuration/index.rst
@@ -0,0 +1,17 @@
1===================
2Configuring EC2-API
3===================
4
5To 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
11A 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
diff --git a/doc/source/configuration/metadata.rst b/doc/source/configuration/metadata.rst
new file mode 100644
index 0000000..9b8e9d5
--- /dev/null
+++ b/doc/source/configuration/metadata.rst
@@ -0,0 +1,16 @@
1==============================
2EC2API Metadata configuration
3==============================
4
5Configuration options
6~~~~~~~~~~~~~~~~~~~~~
7
8To 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
14The additional configuration options for EC2 Metadata:
15
16.. include:: ./tables/ec2api-metadata.rst
diff --git a/doc/source/configuration/tables/ec2api-clients.rst b/doc/source/configuration/tables/ec2api-clients.rst
new file mode 100644
index 0000000..d073f29
--- /dev/null
+++ b/doc/source/configuration/tables/ec2api-clients.rst
@@ -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.
diff --git a/doc/source/configuration/tables/ec2api-common.rst b/doc/source/configuration/tables/ec2api-common.rst
new file mode 100644
index 0000000..5f7cebb
--- /dev/null
+++ b/doc/source/configuration/tables/ec2api-common.rst
@@ -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.
diff --git a/doc/source/configuration/tables/ec2api-database.rst b/doc/source/configuration/tables/ec2api-database.rst
new file mode 100644
index 0000000..7ec42b9
--- /dev/null
+++ b/doc/source/configuration/tables/ec2api-database.rst
@@ -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
diff --git a/doc/source/configuration/tables/ec2api-ec2.rst b/doc/source/configuration/tables/ec2api-ec2.rst
new file mode 100644
index 0000000..942bc7e
--- /dev/null
+++ b/doc/source/configuration/tables/ec2api-ec2.rst
@@ -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
diff --git a/doc/source/configuration/tables/ec2api-metadata.rst b/doc/source/configuration/tables/ec2api-metadata.rst
new file mode 100644
index 0000000..58b04af
--- /dev/null
+++ b/doc/source/configuration/tables/ec2api-metadata.rst
@@ -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
diff --git a/doc/source/configuration/tables/ec2api-s3.rst b/doc/source/configuration/tables/ec2api-s3.rst
new file mode 100644
index 0000000..4bc4a35
--- /dev/null
+++ b/doc/source/configuration/tables/ec2api-s3.rst
@@ -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
diff --git a/doc/source/configuration/tables/ec2api-service.rst b/doc/source/configuration/tables/ec2api-service.rst
new file mode 100644
index 0000000..d9a6dfd
--- /dev/null
+++ b/doc/source/configuration/tables/ec2api-service.rst
@@ -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.