From 9e91db17aa17f342ecfacd62bda18b8c0e086b1e Mon Sep 17 00:00:00 2001 From: tikitavi Date: Thu, 14 Sep 2017 19:15:48 +0300 Subject: [PATCH] Add configuration reference to doc/source/configuration Change-Id: I077f4e7c3b12689f809cd68177e00a097d6cd0a2 --- doc/source/conf.py | 20 ++- .../_flagmappings/ec2api.flagmappings | 143 ++++++++++++++++++ .../_flagmappings/ec2api.headers | 7 + doc/source/configuration/api.rst | 18 +++ doc/source/configuration/index.rst | 17 +++ doc/source/configuration/metadata.rst | 16 ++ .../configuration/tables/ec2api-clients.rst | 37 +++++ .../configuration/tables/ec2api-common.rst | 41 +++++ .../configuration/tables/ec2api-database.rst | 25 +++ .../configuration/tables/ec2api-ec2.rst | 69 +++++++++ .../configuration/tables/ec2api-metadata.rst | 76 ++++++++++ doc/source/configuration/tables/ec2api-s3.rst | 37 +++++ .../configuration/tables/ec2api-service.rst | 49 ++++++ 13 files changed, 553 insertions(+), 2 deletions(-) create mode 100644 doc/source/configuration/_flagmappings/ec2api.flagmappings create mode 100644 doc/source/configuration/_flagmappings/ec2api.headers create mode 100644 doc/source/configuration/api.rst create mode 100644 doc/source/configuration/index.rst create mode 100644 doc/source/configuration/metadata.rst create mode 100644 doc/source/configuration/tables/ec2api-clients.rst create mode 100644 doc/source/configuration/tables/ec2api-common.rst create mode 100644 doc/source/configuration/tables/ec2api-database.rst create mode 100644 doc/source/configuration/tables/ec2api-ec2.rst create mode 100644 doc/source/configuration/tables/ec2api-metadata.rst create mode 100644 doc/source/configuration/tables/ec2api-s3.rst create mode 100644 doc/source/configuration/tables/ec2api-service.rst diff --git a/doc/source/conf.py b/doc/source/conf.py index 8a4c8fb7..f933c260 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -21,8 +21,16 @@ os.environ['DJANGO_SETTINGS_MODULE'] = 'openstack_dashboard.settings' # Add any Sphinx extension module names here, as strings. They can be extensions # coming with Sphinx (named 'sphinx.ext.*') or your custom ones. -extensions = ['sphinx.ext.autodoc', 'sphinx.ext.doctest', 'sphinx.ext.todo', - 'sphinx.ext.viewcode'] +extensions = ['sphinx.ext.autodoc', + 'sphinx.ext.doctest', + 'sphinx.ext.todo', + 'sphinx.ext.viewcode', + 'openstackdocstheme'] + +# openstackdocstheme options +repository_name = 'openstack/ec2-api' +bug_project = 'ec2-api' +bug_tag = '' # autodoc generation is a bit aggressive and a nuisance when doing heavy # text edit cycles. @@ -58,10 +66,18 @@ pygments_style = 'sphinx' #html_theme_path = ["."] #html_theme = '_theme' #html_static_path = ['static'] +html_theme = 'openstackdocs' + +html_last_updated_fmt = '%Y-%m-%d %H:%M' +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +html_theme_options = {"sidebar_mode": "toc"} # Output file base name for HTML help builder. htmlhelp_basename = '%sdoc' % project + git_cmd = ["git", "log", "--pretty=format:'%ad, commit %h'", "--date=local", "-n1"] try: diff --git a/doc/source/configuration/_flagmappings/ec2api.flagmappings b/doc/source/configuration/_flagmappings/ec2api.flagmappings new file mode 100644 index 00000000..08a48146 --- /dev/null +++ b/doc/source/configuration/_flagmappings/ec2api.flagmappings @@ -0,0 +1,143 @@ +admin_password disable +admin_tenant_name disable +admin_user disable +api_paste_config common +api_rate_limit disable +bindir disable +buckets_path disable +cert_topic disable +cinder_service_type clients +debug disable +default_flavor ec2 +default_log_levels disable +disable_ec2_classic ec2 +ec2_host ec2 +ec2_path ec2 +ec2_port ec2 +ec2_private_dns_show_ip ec2 +ec2_scheme ec2 +ec2_timestamp_expiry clients +ec2api_listen service +ec2api_listen_port service +ec2api_use_ssl service +ec2api_workers service +external_network ec2 +fatal_deprecations disable +fatal_exception_format_errors disable +image_decryption_dir s3 +instance_format disable +instance_uuid_format disable +internal_service_availability_zone ec2 +keystone_ec2_tokens_url clients +keystone_url disable +log_config_append disable +log_date_format disable +log_dir disable +log_file disable +logging_context_format_string disable +logging_debug_format_suffix disable +logging_default_format_string disable +logging_exception_prefix disable +logging_user_identity_format disable +max_header_line common +metadata_listen metadata +metadata_listen_port metadata +metadata_use_ssl metadata +metadata_workers metadata +my_ip ec2 +network_device_mtu ec2 +nova_service_type clients +publish_errors disable +pybasedir disable +rate_limit_burst disable +rate_limit_except_level disable +rate_limit_interval disable +region_list ec2 +s3_listen disable +s3_listen_port disable +s3_region s3 +s3_url s3 +service_down_time disable +ssl_ca_file disable +ssl_cert_file service +ssl_insecure disable +ssl_key_file service +state_path disable +syslog_log_facility disable +tcp_keepidle common +tempdir disable +use_forwarded_for service +use_journal disable +use_stderr disable +use_syslog disable +watch_log_file disable +wsgi_default_pool_size common +wsgi_log_format common +x509_root_private_key s3 +cache/backend disable +cache/backend_argument disable +cache/config_prefix disable +cache/debug_cache_backend disable +cache/enabled disable +cache/expiration_time disable +cache/memcache_dead_retry disable +cache/memcache_pool_connection_get_timeout disable +cache/memcache_pool_maxsize disable +cache/memcache_pool_unused_timeout disable +cache/memcache_servers disable +cache/memcache_socket_timeout disable +cache/proxies disable +database/backend disable +database/connection disable +database/connection_debug disable +database/connection_recycle_time disable +database/connection_trace disable +database/db_inc_retry_interval disable +database/db_max_retries disable +database/db_max_retry_interval disable +database/db_retry_interval disable +database/max_overflow disable +database/max_pool_size disable +database/max_retries disable +database/min_pool_size disable +database/mysql_enable_ndb disable +database/mysql_sql_mode disable +database/pool_timeout disable +database/retry_interval disable +database/slave_connection disable +database/sqlite_synchronous disable +database/use_db_reconnect disable +database/use_tpool database +keystone_authtoken/admin_password disable +keystone_authtoken/admin_tenant_name disable +keystone_authtoken/admin_token disable +keystone_authtoken/admin_user disable +keystone_authtoken/auth_admin_prefix disable +keystone_authtoken/auth_host disable +keystone_authtoken/auth_port disable +keystone_authtoken/auth_protocol disable +keystone_authtoken/auth_section disable +keystone_authtoken/auth_type disable +keystone_authtoken/auth_uri disable +keystone_authtoken/auth_version disable +keystone_authtoken/cache disable +keystone_authtoken/cafile disable +keystone_authtoken/certfile disable +keystone_authtoken/delay_auth_decision disable +keystone_authtoken/http_connect_timeout disable +keystone_authtoken/http_request_max_retries disable +keystone_authtoken/identity_uri disable +keystone_authtoken/insecure disable +keystone_authtoken/keyfile disable +keystone_authtoken/timeout disable +metadata/auth_ca_cert metadata +metadata/cache_expiration metadata +metadata/metadata_proxy_shared_secret metadata +metadata/nova_client_cert metadata +metadata/nova_client_priv_key metadata +metadata/nova_metadata_insecure metadata +metadata/nova_metadata_ip metadata +metadata/nova_metadata_port metadata +metadata/nova_metadata_protocol metadata +oslo_concurrency/disable_process_locking disable +oslo_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 00000000..a492e50b --- /dev/null +++ b/doc/source/configuration/_flagmappings/ec2api.headers @@ -0,0 +1,7 @@ +clients OpenStack Clients +common Common Service +database additional Database Client +ec2 EC2API +metadata Metadata +service EC2API Service +s3 S3 Client diff --git a/doc/source/configuration/api.rst b/doc/source/configuration/api.rst new file mode 100644 index 00000000..8c30254d --- /dev/null +++ b/doc/source/configuration/api.rst @@ -0,0 +1,18 @@ +=============================== +EC2API configuration +=============================== + +Configuration options +~~~~~~~~~~~~~~~~~~~~~ + +The following options allow configuration that EC2API supports. + + +.. include:: ./tables/ec2api-clients.rst +.. include:: ./tables/ec2api-database.rst +.. include:: ./tables/ec2api-service.rst +.. include:: ./tables/ec2api-ec2.rst +.. include:: ./tables/ec2api-s3.rst +.. include:: ./tables/ec2api-common.rst + + diff --git a/doc/source/configuration/index.rst b/doc/source/configuration/index.rst new file mode 100644 index 00000000..10548834 --- /dev/null +++ b/doc/source/configuration/index.rst @@ -0,0 +1,17 @@ +=================== +Configuring EC2-API +=================== + +To configure your EC2API installation, you must define configuration options in these files: + +* ``ec2api.conf`` contains EC2API configuration options and resides in the ``/etc/ec2api`` directory. + +* ``api-paste.ini`` defines EC2API limits and resides in the ``/etc/ec2api`` directory. + +A list of config options based on different topics can be found below: + +.. toctree:: + :maxdepth: 2 + + api.rst + metadata.rst diff --git a/doc/source/configuration/metadata.rst b/doc/source/configuration/metadata.rst new file mode 100644 index 00000000..9b8e9d50 --- /dev/null +++ b/doc/source/configuration/metadata.rst @@ -0,0 +1,16 @@ +============================== +EC2API Metadata configuration +============================== + +Configuration options +~~~~~~~~~~~~~~~~~~~~~ + +To configure Metadata Service for ec2api, EC2 API configuration_ common sections + (such as OpenStack Clients, Database Client, EC2API and Common sections) + must be configured as well. + +.. _configuration: ./api.html + +The additional configuration options for EC2 Metadata: + +.. 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 00000000..d073f291 --- /dev/null +++ b/doc/source/configuration/tables/ec2api-clients.rst @@ -0,0 +1,37 @@ +.. + Warning: Do not edit this file. It is automatically generated from the + software project's code and your changes will be overwritten. + + The tool to generate this file lives in openstack-doc-tools repository. + + Please make any changes needed in the code, then run the + autogenerate-config-doc tool from the openstack-doc-tools repository, or + ask for help on the documentation mailing list, IRC channel or meeting. + +.. _ec2api-clients: + +.. list-table:: Description of OpenStack Clients configuration options + :header-rows: 1 + :class: config-ref-table + + * - Configuration option = Default value + - Description + + * - **[DEFAULT]** + - + + * - ``cinder_service_type`` = ``volumev2`` + + - (String) Service type of Volume API, registered in Keystone catalog. + + * - ``ec2_timestamp_expiry`` = ``300`` + + - (Integer) Time in seconds before ec2 timestamp expires + + * - ``keystone_ec2_tokens_url`` = ``http://localhost:5000/v3/ec2tokens`` + + - (String) URL to authenticate token from ec2 request. + + * - ``nova_service_type`` = ``compute`` + + - (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 00000000..5f7cebb8 --- /dev/null +++ b/doc/source/configuration/tables/ec2api-common.rst @@ -0,0 +1,41 @@ +.. + Warning: Do not edit this file. It is automatically generated from the + software project's code and your changes will be overwritten. + + The tool to generate this file lives in openstack-doc-tools repository. + + Please make any changes needed in the code, then run the + autogenerate-config-doc tool from the openstack-doc-tools repository, or + ask for help on the documentation mailing list, IRC channel or meeting. + +.. _ec2api-common: + +.. list-table:: Description of Common Service configuration options + :header-rows: 1 + :class: config-ref-table + + * - Configuration option = Default value + - Description + + * - **[DEFAULT]** + - + + * - ``api_paste_config`` = ``api-paste.ini`` + + - (String) File name for the paste.deploy config for ec2api + + * - ``max_header_line`` = ``16384`` + + - (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). + + * - ``tcp_keepidle`` = ``600`` + + - (Integer) Sets the value of TCP_KEEPIDLE in seconds for each server socket. Not supported on OS X. + + * - ``wsgi_default_pool_size`` = ``1000`` + + - (Integer) Size of the pool of greenthreads used by wsgi + + * - ``wsgi_log_format`` = ``%(client_ip)s "%(request_line)s" status: %(status_code)s len: %(body_length)s time: %(wall_seconds).7f`` + + - (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 00000000..7ec42b98 --- /dev/null +++ b/doc/source/configuration/tables/ec2api-database.rst @@ -0,0 +1,25 @@ +.. + Warning: Do not edit this file. It is automatically generated from the + software project's code and your changes will be overwritten. + + The tool to generate this file lives in openstack-doc-tools repository. + + Please make any changes needed in the code, then run the + autogenerate-config-doc tool from the openstack-doc-tools repository, or + ask for help on the documentation mailing list, IRC channel or meeting. + +.. _ec2api-database: + +.. list-table:: Description of additional Database Client configuration options + :header-rows: 1 + :class: config-ref-table + + * - Configuration option = Default value + - Description + + * - **[database]** + - + + * - ``use_tpool`` = ``False`` + + - (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 00000000..942bc7e1 --- /dev/null +++ b/doc/source/configuration/tables/ec2api-ec2.rst @@ -0,0 +1,69 @@ +.. + Warning: Do not edit this file. It is automatically generated from the + software project's code and your changes will be overwritten. + + The tool to generate this file lives in openstack-doc-tools repository. + + Please make any changes needed in the code, then run the + autogenerate-config-doc tool from the openstack-doc-tools repository, or + ask for help on the documentation mailing list, IRC channel or meeting. + +.. _ec2api-ec2: + +.. list-table:: Description of EC2API configuration options + :header-rows: 1 + :class: config-ref-table + + * - Configuration option = Default value + - Description + + * - **[DEFAULT]** + - + + * - ``default_flavor`` = ``m1.small`` + + - (String) A flavor to use as a default instance type + + * - ``disable_ec2_classic`` = ``None`` + + - (Boolean) True if server does not support EC2 Classic mode in favor of default VPC + + * - ``ec2_host`` = ``$my_ip`` + + - (String) The IP address of the EC2 API server + + * - ``ec2_path`` = ``/`` + + - (String) The path prefix used to call the ec2 API server + + * - ``ec2_port`` = ``8788`` + + - (Integer) The port of the EC2 API server + + * - ``ec2_private_dns_show_ip`` = ``False`` + + - (Boolean) Return the IP address as private dns hostname in describe instances + + * - ``ec2_scheme`` = ``http`` + + - (String) The protocol to use when connecting to the EC2 API server (http, https) + + * - ``external_network`` = ``None`` + + - (String) Name of the external network, which is used to connectVPCs to Internet and to allocate Elastic IPs. + + * - ``internal_service_availability_zone`` = ``internal`` + + - (String) The availability_zone to show internal services under + + * - ``my_ip`` = ``10.0.0.1`` + + - (String) IP address of this host + + * - ``network_device_mtu`` = ``1500`` + + - (Integer) MTU size to set by DHCP for instances. Corresponds with the network_device_mtu in ec2api.conf. + + * - ``region_list`` = + + - (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 00000000..58b04af0 --- /dev/null +++ b/doc/source/configuration/tables/ec2api-metadata.rst @@ -0,0 +1,76 @@ +.. + Warning: Do not edit this file. It is automatically generated from the + software project's code and your changes will be overwritten. + + The tool to generate this file lives in openstack-doc-tools repository. + + Please make any changes needed in the code, then run the + autogenerate-config-doc tool from the openstack-doc-tools repository, or + ask for help on the documentation mailing list, IRC channel or meeting. + +.. _ec2api-metadata: + +.. list-table:: Description of Metadata configuration options + :header-rows: 1 + :class: config-ref-table + + * - Configuration option = Default value + - Description + + * - **[DEFAULT]** + - + + * - ``metadata_listen`` = ``0.0.0.0`` + + - (String) The IP address on which the metadata API will listen. + + * - ``metadata_listen_port`` = ``8789`` + + - (Integer) The port on which the metadata API will listen. + + * - ``metadata_use_ssl`` = ``False`` + + - (Boolean) Enable ssl connections or not for EC2 API Metadata + + * - ``metadata_workers`` = ``None`` + + - (Integer) Number of workers for metadata service. The default will be the number of CPUs available. + + * - **[metadata]** + - + + * - ``auth_ca_cert`` = ``None`` + + - (String) Certificate Authority public key (CA cert) file for ssl + + * - ``cache_expiration`` = ``15`` + + - (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. + + * - ``metadata_proxy_shared_secret`` = + + - (String) Shared secret to sign instance-id request + + * - ``nova_client_cert`` = + + - (String) Client certificate for nova metadata api server. + + * - ``nova_client_priv_key`` = + + - (String) Private key of client certificate. + + * - ``nova_metadata_insecure`` = ``False`` + + - (Boolean) Allow to perform insecure SSL (https) requests to nova metadata + + * - ``nova_metadata_ip`` = ``127.0.0.1`` + + - (String) IP address used by Nova metadata server. + + * - ``nova_metadata_port`` = ``8775`` + + - (Integer) TCP Port used by Nova metadata server. + + * - ``nova_metadata_protocol`` = ``http`` + + - (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 00000000..4bc4a35e --- /dev/null +++ b/doc/source/configuration/tables/ec2api-s3.rst @@ -0,0 +1,37 @@ +.. + Warning: Do not edit this file. It is automatically generated from the + software project's code and your changes will be overwritten. + + The tool to generate this file lives in openstack-doc-tools repository. + + Please make any changes needed in the code, then run the + autogenerate-config-doc tool from the openstack-doc-tools repository, or + ask for help on the documentation mailing list, IRC channel or meeting. + +.. _ec2api-s3: + +.. list-table:: Description of S3 Client configuration options + :header-rows: 1 + :class: config-ref-table + + * - Configuration option = Default value + - Description + + * - **[DEFAULT]** + - + + * - ``image_decryption_dir`` = ``/tmp`` + + - (String) Parent directory for tempdir used for image decryption + + * - ``s3_region`` = ``RegionOne`` + + - (String) Region of S3 server + + * - ``s3_url`` = ``http://$my_ip:3334`` + + - (String) URL to S3 server + + * - ``x509_root_private_key`` = ``None`` + + - (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 00000000..d9a6dfd9 --- /dev/null +++ b/doc/source/configuration/tables/ec2api-service.rst @@ -0,0 +1,49 @@ +.. + Warning: Do not edit this file. It is automatically generated from the + software project's code and your changes will be overwritten. + + The tool to generate this file lives in openstack-doc-tools repository. + + Please make any changes needed in the code, then run the + autogenerate-config-doc tool from the openstack-doc-tools repository, or + ask for help on the documentation mailing list, IRC channel or meeting. + +.. _ec2api-service: + +.. list-table:: Description of EC2API Service configuration options + :header-rows: 1 + :class: config-ref-table + + * - Configuration option = Default value + - Description + + * - **[DEFAULT]** + - + + * - ``ec2api_listen`` = ``0.0.0.0`` + + - (String) The IP address on which the EC2 API will listen. + + * - ``ec2api_listen_port`` = ``8788`` + + - (Integer) The port on which the EC2 API will listen. + + * - ``ec2api_use_ssl`` = ``False`` + + - (Boolean) Enable ssl connections or not for EC2 API + + * - ``ec2api_workers`` = ``None`` + + - (Integer) Number of workers for EC2 API service. The default will be equal to the number of CPUs available. + + * - ``ssl_cert_file`` = ``None`` + + - (String) SSL certificate of API server + + * - ``ssl_key_file`` = ``None`` + + - (String) SSL private key of API server + + * - ``use_forwarded_for`` = ``False`` + + - (Boolean) Treat X-Forwarded-For as the canonical remote address. Only enable this if you have a sanitizing proxy.